Template:R/doc

From the AARoads Wiki: Read about the road before you go
Jump to navigation Jump to search

Intent

The {{r}} (referencing) template allows to define and invoke any kind of full or shortened references (citations as well as footnotes) in articles in a very intuitive way utilizing an easy-to-remember and very short notation reducing a lot of clutter from article source code, thereby making them easier to read and maintain.

{{r}} provides means for links to references to carry additional information (like pages, quotations and other commentary) in a condensed format, thereby eliminating the need for an additional article section for shortened references (and hence avoiding the problems related to that approach like the extra layer of indirection of links, the real-estate occupied for, as well as the amount of whitespace created by that section, and the often unreliable proprietary linking system with ambiguous or dangling links as well as lacking backlinks from the full citations to the shortened references). Its annotation system can be used to enrich the full citation with information given where a reference gets invoked, to bundle multiple citations into one entry, or to group sub-references under the corresponding full reference (i.e. to implement r-style shortened citations).

By utilizing the MediaWiki Extension:Cite internally (instead of establishing an independent linking system on top of it), {{r}} also remains fully compatible with other referencing systems and will take advantage of any future improvements of the underlying system.

It can be used with raw text definitions for the references as well as be combined with other citation templates (like CS1).

Overview

In its basic format the template provides a compact shorthand for <ref name="RefName" /> citation tags, simplifying syntax so cutting code clutter.

It can also be used to define inline]]nd/or list-defined references (LDR), including nested footnotes inside other footnotes (up to five levels deep). Citations can be provided as raw text citations or through other citation templates (such as the suite of CS1 citation templates).

Optionally, it allows to provide and display individual page numbers (or other in-source location information) and quotations (including language information and translations) from the source alongside the invocations of a reference (that is, the link to the reference). If the page numbers given are too unspecific for the quotation, an extra page number can optionally be given for the quotation only. The page number will be shown as superscript immediately following the reference link, the other related information is available as tooltip when hovering over that superscript. Plural page parameters have special support for lists and ranges, automatically converting hyphens to endashes—the accept-this-as-written markup to override the automatic conversion is supported as well.

The template allows the definition of reference annotation, which will be collected and appended to the end of the full citation defined earlier. This can be used to accumulate extra notes (including page numbers and quotes from the invocations), allows for citations defined at different locations to be bundled and residing under a single entry, or to group sub-references under the corresponding full reference.

The template parameters can take raw text information, but are also compatible with simple MediaWiki and HTML markup allowing for the usage of links and templates in template parameters. Such markup would be automatically stripped off for tooltip display, but passed on for other purposes (annotation system).

Custom link anchors can be enabled for the reference links as well as for reference definitions and various annotation, thereby allowing to smoothly blend in with other citation systems used on the same page, or to create sophisticated linking schemes with links to individual pieces of contents and backlinks to reference links (i.e. acting as shortened references).

The template allows to define and show a context section in the article prose to indicate which specific statements in the article are supported by the reference, if this isn't already obvious from where the reference link is positioned. The section can be divided into multiple pieces and can overlap with other sections defined for other references.

Missing page numbers can be indicated similar to {{Page needed}}.

For as long as the tooltip feature isn't occupied by the template to display quotations, the template will provide a tooltip by itself explaining the truncated page / location information attached to the link.

The template is compatible with the parameter names of most other citation templates, and it works for normal citations just as well as for any kinds of groups (i.e. for footnotes, including the predefined ones).

Bidirectional support (left-to-right, right-to-left) for citations is available if the corresponding CSS definitions are activated.

The template optimizes the visual kerning in the superscript and has configurable support for line wrapping after or within superscripts (with corresponding CSS).

The template is compatible with editing features such as the pipe trick and template substituting.

(The present implementation supports multiple citations, but this functionality may be moved to a wrapper like {{rr}} in the future in order to introduce a further simplified and more powerful calling convention to the core template {{r}}. For maximum future-compatibility, use {{rr}} when using enumerated parameters (to support multiple citations in one call) or use unnamed parameters.)

For example:

Using <ref> For example, fact<ref name=Bal/><ref name=Bam/><ref name=Bar/> and fact.<ref name=Bas/><ref name=Bay/><ref name=Baz/>

Displays as: For example, fact[1][2][3] and fact.[4][5][6]

Instead using {{r}} For example, fact{{r|Bal|Bam|Bar}} and fact.{{r|Bas|Bay|Baz}}

Displays as: For example, fact[1][2][3] and fact.[4][5][6]

{{r}} and <ref> can coexist on the same page, and like <ref>, {{r}} can be used with or without list-defined references. In addition, a |page= or |p= parameter adds the functionality of {{rp}}:

Using {{r}} with
|p= parameter 		For example, fact.{{r|RefName|p=22}}

Displays as: For example, fact.[7]: 22 

Usage

In-source-location parameters

The in-source-location of a source can be specified with either |page=/|p= (for a single page), with |pages=/|pp= (for plural pages), or with |location=/|loc=/|at= for other in-source-locations.

The specified page number(s) can be a single page number (287), a list of several pages (xii, 287, 292, 418) or a range of pages (287–288) or any combination thereof. Do not add "Page", "pp.", etc.—just the numbers.

Other in-source-location information can also be used for non-numeric pages, for example: "f. 29", "A7", and "back cover", etc., and can also be used for non-paginated sources, e.g., "0:35:12" for a video source.

Choose one of the template parameters above according to the type of page or in-source-location specified.

While typically only one of these three types of parameters is given, it is also possible to combine them to suit more special use cases. If both, singular and plural page parameters are given at the same time, the plural page info is assumed to be the span of the article, whereas the singular page info is considered to be the page within that span supporting the statement. The template will indicate this by framing the singular page in square brackets following the plural page info. If an in-source-location is given in addition to the page info, the template assumes it to further detail the preceding page info rather than representing some kind of stand-alone in-source location info.

Do not attempt to use multiple aliases of a parameter at the same time. Only one will be chosen and the others may be ignored without error message.

Inline invocation

Usage Display Notes
{{r|RefName}} Text.[7] Equivalent to <ref name="RefName" />.
{{r|RefName|p=100}}

{{r|RefName|page=100}}

{{r|RefName|page=[[w:Hundred|100]]}}

{{r|RefName|page=[https://books.google.com/books?id=S3JHAAAAYAAJ&pg=PA15 15]}}

{{r|RefName|pp=100, 102}}

{{r|RefName|pages=100, 102}}

Text.[7]: 100 

Text.[7]: 100 

Text.[7]: 100 

Text.[7]: 15 

Text.[7]: 100, 102 

Text.[7]: 100, 102 

Adds a page number (or other location identifier) within the source.

Use |p= or |page= for singular pages, |pp= or |pages= for plural pages, and |at= or |loc= for other in-source-locations.

If the article cites only one location in a given source, reduce clutter by coding simply {{r|RefName}} and integrating the location into the main RefName citation.

{{r|RefName|pages=10–14}} (endash)

{{r|RefName|pages=10-14}} (hyphen)

{{r|RefName|pages=2-14–2-16}} (hyphens and endash)

{{r|RefName|pages=2-14-2-16}} (hyphens)

{{r|RefName|pages=((2-14)), ((2-16))}} (hyphens)

{{r|RefName|pp=3, 6}}

{{r|RefName|at=§C}}

{{r|RefName|at=Dust jacket}}

{{r|RefName|at=para. 7}}

Text.[7]: 10–14 

Text.[7]: 10–14 

Text.[7]: 2-14–2-16 

Text.[7]: 2-14–2-16 

Text.[7]: 2-14, 2-16 

Text.[7]: 3, 6 

Text.[7]: §C 

Text.[7]: Dust jacket 

Text.[7]: para. 7 

{{r|RefName|Bam|Bar}} Text.[7][2][3] Equivalent to {{r|RefName}}{{r|Bam}}{{r|Bar}} or <ref name=RefName/><ref name=Bam/><ref name=Bar/>.

Up to nine references may be "bundled" this way.

{{r|1=RefName|2=Bam|3=Bar|4=Bas|p1=100|pp2=10–14|at4=§C}}

{{r|1=RefName|p1=100|2=Bam|pp2=10–14|3=Bar|4=Bas|at4=§C}}

{{r|n1=RefName|p1=100|n2=Bam|pp2=10–14|n3=Bar|n4=Bas|at4=§C}}

{{r |name1=RefName |page1=100 |name2=Bam |pages2=10–14 |name3=Bar |name4=Bas |at4=§C}}

Text.[7]: 100 [2]: 10–14 [3][4]: §C  Equivalent to {{r|RefName|p=100}}{{r|Bam|pp=10–14}}{{r|Bar}}{{r|Bas|at=§C}}.

In the example, not all references have pages; make sure that e.g. |1= matches |p1=

{{r|group=Notes|NtName}}

{{r|grp=Notes|NtName|NtCam}}

{{r|g=Notes|NtName|p=13}}

Text.[Notes 1]

Text.[Notes 1][Notes 2]

Text.[Notes 1]: 13 

The |group=, |grp=, and |g= parameters are equivalent and echo <ref group=Notes name=NtName/>.

If present, the parameter applies to all references in the template.

{{r|RefName|p=100|q=quote from the text}}

{{r|RefName|p=100|quote=quote from the text}}

{{r|RefName|p=100|quote-page=100|quote=quote from the text}}

{{r|RefName|p=100|quote-page=p|quote=quote from the text}}

Text.[7]: 100  Makes sense only if |p= (or one of its synonyms) is present. |quote= (or |q=) underlines the superscript page number/​location identifier, signaling availability of a quote from the source, which pops up when the mouse is hovered over the dashed underlined bit. |quote-page= or |quote-pages= can be used to optionally specify a specific page or number of pages for the quote only. If this number is the same as what's defined through |p= or |pp=, the special symbolic tokens "p" and "pp" can be used instead of an actual page number. Curved quotes are disfavored by MOS:STRAIGHT.
{{r|1=RefName|2=Bam|3=Bar|4=Bas|p1=100|pp2=10–14|at4=§C|q1=Quote from 100|q4=Quote from §C}}

{{r|n1=RefName|n2=Bam|n3=Bar|n4=Bas|p1=100|pp2=10–14|at4=§C|q1=Quote from 100|q4=Quote from §C}}

Text.[7]: 100 [2]: 10–14 [3][4]: §C  In the example, not all references have quotes; make sure that e.g. |1= and |p1= and |q1= all match.
{{r |n=RefName2 |p=201 |r=Harold Smith (1989). ''Proper Referencing''. Atlanta Press. p. 105, 201.}}

{{r |n=RefName3 |r={{cite book |author-first=Harold |author-last=Smith |date=2020 |edition=2nd |title=Proper Referencing |publisher=Atlanta Press |pages=321, 356}} }}

More[8]: 201 [9]: 321  good[9]: 356  prose.[Notes 3] Examples of inline definitions and nested footnotes.
{{r |n=RefName4 |r=Citation A.}}

{{r |n=RefName4 |a=Citation B.}}

{{r |n=RefName5 |r=Citation C.}}

{{r |n=RefName5 |p=102 |a=Note for page 102.}}

{{r |n=RefName5 |p=342 |a=Note for page 342.}}

{{r |n=RefName5 |p=346 |qp=p |q=Quote from page 346 |a=q}}

Two[10] citations[10] bundled into one entry, or one citation[11] with accumulated[11]: 102  commentary[11]: 342 [11]: 346  from shortened references. Examples of annotation. If the annotation should be the page number defined through |p= or what would be shown as quote in the tooltip, the special symbolic tokens "p" and "q" can be used with |annotation= in order to avoid having to repeat this contents.
{{r |n=RefName6 |r=Citation D.}}

{{r |n=RefName6 |p=102 |a=:p. 102: Note for page 102.}}

{{r |n=RefName6 |p=342 |a=:p. 342: Note for page 342.}}

{{r |n=RefName6 |p=346 |qp=p |q=Quote from page 346 |a=q |leadin=:p.&nbsp;}}

A citation[12] with accumulated[12]: 102  commentary[12]: 342 [12]: 346  using indentation in reference section and tooltip view. Indentation in annotations. It can be achieved by adding : colons. If it is using for the quote parameter |q=, it can be achieved by using |leadin=.
{{r |n=RefName7 |r=Citation E. |s=Context7}}

{{r |n=RefName7 |p=10 |q=Quote E |a=q |s=Context7}}

<section begin="Context7"/>Context sections of the article<section end="Context7"/> supported by the reference <section begin="Context7"/> can be defined through<section end="Context7"/> {{section}} (or <section begin="Context7"/> other means<section end="Context7"/>, see: LST). The three parts of section "Context7" in this example[13] are shown underlined for illustration purposes.[13]: 10  {{R}} will display its "context" as "dotted underline" tooltip (to be distinguished from the "dashed underline" tooltip further up) when hovering the mouse over the reference link. Multiple sections of the same name will be shown merged (without separator, hence include some delimiter like space into the sections). Note the special syntax used to define sections (with empty |begin= and |end= attributes). Keep the size of the selected sections reasonably short and do not forget to define the end of a section. When no name was specified, names are build following this scheme for context sections: "cite_sect-group-name-pagelocation" (where group, name, page (either page or pages) and location refer to the corresponding template parameters and can be empty if omitted).

References section

The ref names may be defined within a {{reflist}} (as illustrated below) or (in the more usual way) scattered throughout the article text using e.g. <ref name="RefName">Reference text</ref> or {{refn|name=RefName|Reference text}}. 

===References===
{{reflist|refs=
<ref name="RefName">Reference text.</ref>
<ref name="Bam">Bam reference text.</ref>
<ref name="Bar">Bar reference text.</ref>
<ref name="Bas">Bas reference text.</ref>
<ref name="Bay">Bay reference text.</ref>
<ref name="Baz">Baz reference text.</ref>
}}

===Notes===
{{reflist|group="Notes"|refs=
<ref name="NtName">Note text.</ref>
<ref name="NtCam">Cam note text.</ref>
}}

Resulting in:

References
  1. ^ a b Bal reference text.
  2. ^ a b c d e Bam reference text.
  3. ^ a b c d e Bar reference text.
  4. ^ a b c d Bas reference text.
  5. ^ a b Bay reference text.
  6. ^ a b Baz reference text.
  7. ^ a b c d e f g h i j k l m n o p q r s t u Reference text.
  8. ^ a b Harold Smith (1989). Proper Referencing. Atlanta Press. pp. 105, 201.
  9. ^ a b Smith, Harold (2020). Proper Referencing (2nd ed.). Atlanta Press. pp. 321, 356.
  10. ^ a b Citation A. Citation B.
  11. ^ a b c d Citation C. Note for page 102. Note for page 342. ‌346: Quote from page 346
  12. ^ a b c d Citation D.
    p. 102: Note for page 102.
    p. 342: Note for page 342. ‌
    p. 346: Quote from page 346
  13. ^ a b Citation E. ‌Quote E
Notes
  1. ^ a b c Note text.
  2. ^ Cam note text.
  3. ^ This example shows how to nest footnotes.[8]: 105 

Alternatively, the references can be defined through {{r}} itself:[1][2][3][4][5][6][NB 1][NB 2] 

===References===
{{reflist|refs=
{{r|RefName|r=Reference text.}}
{{r|Bam|r=Bam reference text.}}
{{r|Bar|r=Bar reference text.}}
{{r|Bas|r=Bas reference text.}}
{{r|Bay|r=Bay reference text.}}
{{r|Baz|r=Baz reference text.}}
}}

===Notes===
{{reflist|group="NB"|refs=
{{r|g=NB|NtName|r=Note text.}}
{{r|g=NB|NtCam|r=Cam note text.}}
}}

Resulting in:

References
  1. ^ Reference text.
  2. ^ Bam reference text.
  3. ^ Bar reference text.
  4. ^ Bas reference text.
  5. ^ Bay reference text.
  6. ^ Baz reference text.
Notes
  1. ^ Note text.
  2. ^ Cam note text.

R-style shortened references

The {{r}}-style annotation system can be used to create sub-references (as shortened citations) with back- or crosslinks grouped under their corresponding full citation. There are many possible variants, some illustrated below:

Example 1 (with backlinks and automatic numbering of sub-references, here also with nested citations): 

Lorem ipsum{{r|n=C1|r=Citation 1}} dolor sit amet,{{r|n=C1|p=23|a=#[[#L1|^]] p. 23: Quotation from page 23. |link-id=L1}} consectetur adipisici elit,{{r|n=C2|r=Citation 2|p=92}} sed eiusmod tempor incidunt ut labore et dolore magna aliqua.{{r|n=C1|pp=56, 59|a=#[[#L2|^]] pp. 56, 59: Commentary on page 56 from review.{{r|n=C2|p=70}}|link-id=L2}}{{r|n=C3|r=Citation 3}}

===References===
{{reflist}}

Resulting in:

Lorem ipsum[1] dolor sit amet,[1]: 23  consectetur adipisici elit,[2]: 92  sed eiusmod tempor incidunt ut labore et dolore magna aliqua.[1]: 56, 59 [3]

References
  1. ^ a b c Citation 1
    1. ^ p. 23: Quotation from page 23.
    2. ^ pp. 56, 59: Commentary on page 56 from review.[2]: 70 
  2. ^ a b Citation 2
  3. ^ Citation 3

Example 2 (with crosslinks, here also with nested citations): 

Lorem ipsum{{r|n=C1|r=Citation 1}} dolor sit amet,{{r|n=C1|p=[[#P1|23]]|a=<br/>[[#L1B|^]] p. 23: Quotation from page 23.|id=P1|link-id=L1B}} consectetur adipisici elit,{{r|n=C2|r=Citation 2|p=92}} sed eiusmod tempor incidunt ut labore et dolore magna aliqua.{{r|n=C1|pp=[[#P2|56]], 59|a=<br/>[[#L2B|^]] pp. 56, 59: Commentary on page 56 from review.{{r|n=C2|p=70}}|id=P2|link-id=L2B}}{{r|n=C3|r=Citation 3}}

===References===
{{reflist}}

Lorem ipsum[1] dolor sit amet,[1]: 23  consectetur adipisici elit,[2]: 92  sed eiusmod tempor incidunt ut labore et dolore magna aliqua.[1]: 56, 59 [3]

References
  1. ^ a b c Citation 1
    ^ p. 23: Quotation from page 23.
    ^ pp. 56, 59: Commentary on page 56 from review.[2]: 70 
  2. ^ a b Citation 2
  3. ^ Citation 3

Example 3 (with crosslinks and locally embedded inline quotations for tooltips, here also with nested citations): 

Lorem ipsum{{r|n=C1|r=Citation 1}} dolor sit amet,{{r|n=C1|p=[[#P1C|23]]|qp=p|q=Quotation from page 23.|a=q|leadin=<br/>[[#L1C|^]] p. |id=P1C|link-id=L1C}} consectetur adipisici elit,{{r|n=C2|r=Citation 2|p=92}} sed eiusmod tempor incidunt ut labore et dolore magna aliqua.{{r|n=C1|pp=[[#P2C|56]], 59|qpp=pp|q=Commentary on page 56 from review.{{r|n=C2|p=70}}|a=q|leadin=<br/>[[#L2C|^]] pp. |id=P2C|link-id=L2C}}{{r|n=C3|r=Citation 3}}

===References===
{{reflist}}

Lorem ipsum[1] dolor sit amet,[1]: 23  consectetur adipisici elit,[2]: 92  sed eiusmod tempor incidunt ut labore et dolore magna aliqua.[1]: 56, 59 [3]

References
  1. ^ a b c Citation 1 ‌
    ^ p. 23: Quotation from page 23. ‌
    ^ pp. 56, 59: Commentary on page 56 from review.[2]: 70 
  2. ^ a b Citation 2
  3. ^ Citation 3

Spacing

Where multiple citations occur in series, {{r}} prevents line breaks between the citations. In this case, |wrap=yes can be used to allow a line break. Alternatively, if line breaks should be allowed also inside a long page / location information, |wrap=forced can be used instead (however, if this actually results in line breaks also depends on the browser, CSS and the skin selected).

Hyphens

Per MOS:DASH, page ranges should normally be declared with an ndash ({{r|name=RefName|pages=27&ndash;29}}→[1]:) rather than a hyphen. Tools like AA:AWB will automatically convert hyphens to dashes in such instances. For the plural page parameters |pages=, |pp= and |quote-pages= and aliases, {{r}} will automatically translate hyphens into ndashes for display purposes. (This does not apply to the singular and other in-source-location parameters |page=, |p=, |at=, |loc=, |quote-page= and aliases.) If the hyphen is actually desired for whatever reason, the "accept-this-as-written-markup" (which is also supported by {{rp}} and {{ran}}, the family of {{sfn}}- and {{harv}}-style templates, and all CS1/CS2 citation templates) can be used to indicate this ({{r|name=RefName|pages=((27-29)), 41}}→[1]:).

Known issues

Editing features

Because of a technical limitation, some of the standard markup elements that are often used in the article prose do not work within a set of <ref>...</ref> tags, including but not limited to the pipe trick, template substitution and another "nested" set of <ref>...</ref> tags. For example, the following does not work as expected:

  1. <ref>[[Help:Footnotes| ]]</ref> (Generates: [[Help:Footnotes| ]]> instead of a wikilink)
  2. <ref>{{SUBST:TODAY}}</ref> (Generates: {{SUBST:TODAY}} instead of the date that the edit was made)
  3. <ref>Explanatory footnote<ref>Citation</ref></ref> (Generates: Cite error: A <ref> tag is missing the closing </ref> (see the help page). </ref>)

Replacing the outermost <ref>...</ref> set with {{r|r=...}} (or {{r|a=...}} allows for the use of the markup elements listed above.

Incompatibilities

Issues in this template make it incompatible with the {{excerpt}} template. {{r}} should not be used in sections that will be transcluded by {{excerpt}}.

TemplateData

This is the TemplateData for this template used by TemplateWizard, VisualEditor and other tools. See a monthly parameter usage report for Template:R in articles based on its TemplateData.

TemplateData for R

<templatedata> { "params": { "name": { "aliases": [ "n", "name1", "n1", "1" ], "label": "Reference name 1", "description": "If this is \"RefName\", the template displays [1].", "type": "string", "required": true }, "name2": { "aliases": [ "n2", "2" ], "label": "Reference name 2", "description": "If this is \"RefName\", the template displays [1].", "type": "string", "suggested": false }, "name3": { "aliases": [ "n3", "3" ], "label": "Reference name 3", "description": "If this is \"RefName\", the template displays [1].", "type": "string", "suggested": false }, "name4": { "aliases": [ "n4", "4" ], "label": "Reference name 4", "description": "If this is \"RefName\", the template displays [1].", "type": "string" }, "name5": { "aliases": [ "n5", "5" ], "label": "Reference name 5", "description": "If this is \"RefName\", the template displays [1].", "type": "string" }, "name6": { "aliases": [ "n6", "6" ], "label": "Reference name 6", "description": "If this is \"RefName\", the template displays [1].", "type": "string" }, "name7": { "aliases": [ "n7", "7" ], "label": "Reference name 7", "description": "If this is \"RefName\", the template displays [1].", "type": "string" }, "name8": { "aliases": [ "n8", "8" ], "label": "Reference name 8", "description": "If this is \"RefName\", the template displays [1].", "type": "string" }, "name9": { "aliases": [ "n9", "9" ], "label": "Reference name 9", "description": "If this is \"RefName\", the template displays [1].", "type": "string" }, "group": { "aliases": [ "grp", "g" ], "label": "Reference group", "description": "The reference group of all the references displayed; see WP:REFGROUP for help.", "type": "string", "default": "Defaults to not being in a group.", "suggested": true }, "page": { "aliases": [ "p", "page1", "p1", "1p" ], "label": "Page number: reference 1", "description": "Adds a page number within the source. Note that you can also put this information in the original reference instead, so it need only be stated once. Choose parameter only if singular page is given.", "example": "\"2\"", "type": "content", "suggested": true }, "pages": { "aliases": [ "pp", "pages1", "pp1", "1pp" ], "label": "Pages numbers: reference 1", "description": "Adds page numbers within the source. Note that you can also put this information in the original reference instead, so it need only be stated once. Choose parameter only if plural pages are given.", "example": "\"34–38\"", "type": "content", "suggested": true }, "location": { "aliases": [ "location1", "loc", "loc1", "1loc", "at", "at1" ], "label": "In-source location: reference 1", "description": "Adds other location identifier within the source. Note that you can also put this information in the original reference instead, so it need only be stated once. Choose parameter only if location information different from singular or plural page info is given.", "example": "\"inside cover

  1. ^ a b c d e f g h i Cite error: Invalid <ref> tag; no text was provided for refs named \"RefName\"
Retrieved from "https://wiki.aaroads.com/w/index.php?title=Template:R/doc&oldid=231171"