View source for Template:Listref/doc

{{Documentation subpage}}
<!-- Categories and interwikis go at the bottom of this page. -->

==Purpose==
{{for|the use of standard footnotes with labels such as lower-alpha|WP:CITELABEL}}

This template creates in-text citations and a reference list for use in list articles as a supplement to the standard [[Help:Footnotes|footnote system]]. It is intended for use only for references used a large number of times. The template is styled to render in-text citations and the reference list like the {{tag|ref|o}} tags and {{tl|reflist}} template used by the footnote system.

Differences:
* There is no backlink from the citation in the reference list, by design.
* The in-text citation uses a standard HTML link without an id, by design. Other templates create an HTML id, which is only allowed to be defined once, thus multiple uses of the same in-text citation results in invalid HTML
* The in-text citation link and the anchor in the reference list are created manually.

Likenesses:
* In-text citations use the same style.
* The reference list uses the same marking and font size.
* The citation in the reference list is highlighted when the in-text citation is followed.
* The reference list can be formatted with columns like {{tl|reflist}}.

This template is compatible with [[User:Blue-Haired Lawyer/Footnote popups]].

==The problem==
List articles often use a single named reference a large number of times. Each use creates a backlink in the reference list entry and eventually the backlinks become ugly and useless. For example:

# {{dummy backlink|a b c d e f g h i j k l m n o p q r s t u v w x y z aa ab ac ad ae af ag ah ai aj ak al am an ao ap aq ar as at au av aw ax ay az ba bb bc bd be bf bg bh bi bj bk bl bm bn bo bp bq br bs bt bu bv bw bx by bz ca cb cc cd ce cf cg ch ci cj ck cl cm cn co cp cq cr cs ct cu cv cw cx cy cz da db dc dd de df dg dh di dj dk dl dm dn do}}

Backlinks are defined in [[MediaWiki:Cite references link many format backlink labels]]. Backlinks were originally only ''a''—''z'' but over time have been increased to ''a''—''azz'' allowing for 1377 backlinks.

Examples:
* [http://en.wikipedia.org/w/index.php?title=List_of_Eagle_Scouts_%28Boy_Scouts_of_America%29&oldid=86505036#References List of Eagle Scouts]
* [http://en.wikipedia.org/w/index.php?title=List_of_islands_of_Maine&oldid=445514409 List of islands of Maine]
* [http://en.wikipedia.org/w/index.php?title=List_of_philosophers_%28A%E2%80%93C%29&oldid=450397767 List of philosophers (A–C)]

Templates such as {{tl|ref}} create an HTML id. When reused, the same id is defined multiple times resulting in invalid HTML.

==In-text citation==
The in-text citation is a link created with an unnamed parameter that defines the link id. If undefined, it defaults to <var>a</var>.

Examples:
* {{tlx|listref}} shows as {{listref}}
* {{tlx|listref|b}} shows as {{listref|b}}
* {{tlx|listref|IV}} shows as {{listref|IV}}

Although any characters can be used, only these styles will link to citations in the reference list:
* lower-alpha
* upper-alpha
* lower-roman
* upper-roman
* lower-greek
* decimal

To include a page number use {{para|p}}

* {{tlx|listref|a|2=p=10}} shows as {{listref|p=10}}

==Reference list==
The citations are defined in and the reference list is displayed with {{tlx|listref/reflist}}. There are two named parameters for up to nine citations:
* {{para|id1}} through {{para|id9}} matches the link id set with {{tl|listref}}.
* {{para|ref1}} through {{para|ref9}} defines the full citation.

{{tlx|Listref/reflist}} supports style parameters similar to {{tl|reflist}}:
* Columns: Using {{tlx|listref/reflist|2}} will create a two-column reference list, {{tlx|listref/reflist|3}} will create a three-column list, and {{tlx|listref/reflist|30em}} will automatically choose the number of columns based on the width of the web browser. You should set this to match the columns parameter in {{tl|reflist}}.
* List style: The reference list is styled as lower-alpha by default. It can be changed with {{para|liststyle}} to:
** upper-alpha
** lower-roman
** upper-roman
** lower-greek
** decimal

:The style must match the in-text link id style.

{{pre2|<nowiki>{{listref/reflist
|id1=a |ref1=Reference a
|id2=b |ref2=Reference b
}}</nowiki>}}

Citations in the reference list must be in the proper order for the ordered list to work properly.

==Freestyle==
You can use any text for the label by setting {{para|liststyle|square}}. The reference list will show as an unordered list and the label will show in the reference list at the beginning of each entry enclosed by brackets.

==Examples==
{{pre2|<nowiki>* The brontosaurus is thin at one end.{{listref}}
* Then it becomes much thicker in the middle.{{listref}}
* The Norwegian Blue Parrot will not move if its feet are nailed to the perch.{{listref|b}}
* Its metabolic processes are a matter of interest only to historians.{{listref|b}}

{{listref/reflist|
|id1=a |ref1={{cite book |last=Elk |first=Anne |title=[[Anne Elk's Theory on Brontosauruses]] |date=November 16, 1972}}
|id2=b |ref2={{cite book |last=Praline |first=Eric |title=[[Dead Parrot sketch]] |date=December 7, 1969}}
}}</nowiki>}}
* The brontosaurus is thin at one end.{{listref}}
* Then it becomes much thicker in the middle.{{listref}}
* The Norwegian Blue Parrot will not move if its feet are nailed to the perch.{{listref|b}}
* Its metabolic processes are a matter of interest only to historians.{{listref|b}}

{{listref/reflist|
|id1=a |ref1={{cite book |last=Elk |first=Anne |title=[[Anne Elk's Theory on Brontosauruses]] |date=November 16, 1972}}
|id2=b |ref2={{cite book |last=Praline |first=Eric |title=[[Dead Parrot sketch]] |date=December 7, 1969}}
}}

{{pre2|<nowiki>* The brontosaurus is thin at one end.{{listref|i}}
* Then it becomes much thicker in the middle.{{listref|i}}
* The Norwegian Blue Parrot will not move if its feet are nailed to the perch.{{listref|ii}}
* Its metabolic processes are a matter of interest only to historians.{{listref|ii}}

{{listref/reflist|liststyle=lower-roman
|id1=i |ref1={{cite book |last=Elk |first=Anne |title=[[Anne Elk's Theory on Brontosauruses]] |date=November 16, 1972}}
|id2=ii |ref2={{cite book |last=Praline |first=Eric |title=[[Dead Parrot sketch]] |date=December 7, 1969}}
}}</nowiki>}}
* The brontosaurus is thin at one end.{{listref|i}}
* Then it becomes much thicker in the middle.{{listref|i}}
* The Norwegian Blue Parrot will not move if its feet are nailed to the perch.{{listref|ii}}
* Its metabolic processes are a matter of interest only to historians.{{listref|ii}}

{{listref/reflist|liststyle=lower-roman
|id1=i |ref1={{cite book |last=Elk |first=Anne |title=[[Anne Elk's Theory on Brontosauruses]] |date=November 16, 1972}}
|id2=ii |ref2={{cite book |last=Praline |first=Eric |title=[[Dead Parrot sketch]] |date=December 7, 1969}}
}}

{{listref/reflist|
|id1=a |ref1={{cite book |last=Elk |first=Anne |title=[[Anne Elk's Theory on Brontosauruses]] |date=November 16, 1972}}
|id2=b |ref2={{cite book |last=Praline |first=Eric |title=[[Dead Parrot sketch]] |date=December 7, 1969}}
}}

'''Used with standard footnotes:'''
{{pre2|<nowiki>Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.<ref>consectetur adipisicing elit</ref> Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.<ref>sunt in culpa qui officia</ref> Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
* The brontosaurus is thin at one end.{{listref}}
* Then it becomes much thicker in the middle.{{listref}}
* The Norwegian Blue Parrot will not move if its feet are nailed to the perch.{{listref|b}}
* Its metabolic processes are a matter of interest only to historians.{{listref|b}}

{{listref/reflist|
|id1=a |ref1={{cite book |last=Elk |first=Anne |title=[[Anne Elk's Theory on Brontosauruses]] |date=November 16, 1972}}
|id2=b |ref2={{cite book |last=Praline |first=Eric |title=[[Dead Parrot sketch]] |date=December 7, 1969}}
}}
{{reflist}}</nowiki>}}

Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.<ref>consectetur adipisicing elit</ref> Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.<ref>sunt in culpa qui officia</ref> Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
* The brontosaurus is thin at one end.{{listref}}
* Then it becomes much thicker in the middle.{{listref}}
* The Norwegian Blue Parrot will not move if its feet are nailed to the perch.{{listref|b}}
* Its metabolic processes are a matter of interest only to historians.{{listref|b}}

{{listref/reflist|
|id1=a |ref1={{cite book |last=Elk |first=Anne |title=[[Anne Elk's Theory on Brontosauruses]] |date=November 16, 1972}}
|id2=b |ref2={{cite book |last=Praline |first=Eric |title=[[Dead Parrot sketch]] |date=December 7, 1969}}
}}
{{reflist|close=1}}

'''Freestyle labels'''
{{pre2|<nowiki>Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.<ref>consectetur adipisicing elit</ref> Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.<ref>sunt in culpa qui officia</ref> Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
* The brontosaurus is thin at one end.{{listref|bronto}}
* Then it becomes much thicker in the middle.{{listref|bronto}}
* The Norwegian Blue Parrot will not move if its feet are nailed to the perch.{{listref|parrot}}
* Its metabolic processes are a matter of interest only to historians.{{listref|parrot}}

{{listref/reflist|liststyle=square
|id1=bronto |ref1={{cite book |last=Elk |first=Anne |title=[[Anne Elk's Theory on Brontosauruses]] |date=November 16, 1972}}
|id2=parrot |ref2={{cite book |last=Praline |first=Eric |title=[[Dead Parrot sketch]] |date=December 7, 1969}}
}}
{{reflist}}</nowiki>}}

Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.<ref>consectetur adipisicing elit</ref> Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.<ref>sunt in culpa qui officia</ref> Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
* The brontosaurus is thin at one end.{{listref|bronto}}
* Then it becomes much thicker in the middle.{{listref|bronto}}
* The Norwegian Blue Parrot will not move if its feet are nailed to the perch.{{listref|parrot}}
* Its metabolic processes are a matter of interest only to historians.{{listref|parrot}}

{{listref/reflist|liststyle=square
|id1=bronto |ref1={{cite book |last=Elk |first=Anne |title=[[Anne Elk's Theory on Brontosauruses]] |date=November 16, 1972}}
|id2=parrot |ref2={{cite book |last=Praline |first=Eric |title=[[Dead Parrot sketch]] |date=December 7, 1969}}
}}
{{reflist|close=1}}

==Troubleshooting==
To show errors, add this to [[Special:MyPage/skin.js]] (current skin only) or  [[Special:MyPage/common.js]] (all skins):

<source lang=javascript>
importScript('Template:Listref/ListrefErrors.js'); // Linkback: [[Template:Listref/ListrefErrors.js]]
</source>

This will detect and show two types of errors:
* Listref error: link to <var>name</var> doesn't point to any matching citation.
:The in-text cite invoked by {{tl|listref}} does not have a matching citation defined in {{tl|listref/reflist}}.
* Listref error: There is no link pointing to this citation.
:The citation defined in {{tl|listref/reflist}} has no in-text cites invoked by {{tl|listref}} that link to it.

After installing the script, errors should show in this test:

* In-text use of {{tl|listref}} that does not link.{{listref|x}}

{{listref/reflist|
|id1=z |ref1=Citation defined in {{tl|listref/reflist}} with no in-text links.}}

==Bug==
The issue with over-backlinking has been reported as {{bug|23455}} Cite extension: suppress backlink. If the extension is updated, then this template should be deprecated.

==See also==
<includeonly>
<!-- Categories and interwikis go here: -->
[[Category:Footnote templates]]
</includeonly>