Jump to content

Extension:Cite/Cite.php: Difference between revisions

From mediawiki.org
Browse history interactively
← Older editNewer edit →
Content deleted Content added
VisualWikitext
m partial revert of myself
→‎<ref>: cut and pasted over technobabble from http://meta.wikimedia.org/wiki/User:Travb#footnotes
Line 11: Line 11:


== Description ==
== Description ==
The basic concept of the <nowiki><ref></nowiki> tag is that it inserts the text enclosed by the ref tags as a footnote in a designated section, which you indicate with the placeholder tag <nowiki><references/></nowiki>. The new format cannot be used interchangeably with the old format - you must pick one or the other.
⚫
=== &lt;ref&gt; ===
<code>&lt;ref&gt;</code> defines inline citations that are collected for later insertion in the page using <code>&lt;references&gt;</code>. For instance, try typing the following in an edit box and clicking "Save page":


If you forget to include <nowiki><references/></nowiki> at the end of the article, none of the footnotes will appear.
<blockquote style="border:1px solid black;padding:1em;">AIDS is a collection of symptoms and infections resulting from the specific damage to the immune system caused by infection with the human immunodeficiency virus (HIV).'''<code><nowiki><ref name=Marx>Marx, J. L. New disease baffles medical community. Science. 1982;217(4560):618–621.</ref></nowiki></code>'''
<p>Most researchers believe that HIV originated in sub-Saharan Africa '''<code><nowiki><ref name=NYT>''New York Times''. [[January 14]], [[2010]] issue, page 16</ref></nowiki></code>'''; it is now a global epidemic. Some authorities '''<code><nowiki><ref>UNAIDS</ref></nowiki></code>''' estimate that AIDS has killed more than 25 million people since it was first recognized on December 1, 1981, making it one of the most destructive epidemics in recorded history. The folks at the NYT are worried sick about this.'''<code><nowiki><ref name=NYT/></nowiki></code>'''
⚫
</blockquote>
will result in the following text on the article page:


This page itself uses footnotes, such as the one at the end of this sentence.<ref>This footnote is used as an example in the "How to use" section.</ref> If you view the Wikicode of this page by clicking "Edit this page", you can see a working example of footnotes.
<blockquote style="padding:1em;">AIDS is a collection of symptoms and infections resulting from the specific damage to the immune system caused by infection with the human immunodeficiency virus (HIV).<ref name=Marx>Marx, J. L. New disease baffles medical community. Science. 1982;217(4560):618–621.</ref>

<p>Most researchers believe that HIV originated in sub-Saharan Africa;<ref name=NYT>''New York Times''. [[January 14]], [[2010]] issue, page 16</ref> it is now a global epidemic. Some authorities<ref>UNAIDS</ref> estimate that AIDS has killed more than 25 million people since it was first recognized on December 1, 1981, making it one of the most destructive epidemics in recorded history. The folks at the NYT are worried sick about this.<ref name=NYT/>
⚫
=== Example ===
<blockquote>
<tt>
According to scientists, the Sun is pretty big.{{highlight|'''&lt;ref>'''Miller, E: "The Sun.", page 23. Academic Press, 2005'''&lt;/ref>'''}}
<br/>
The Moon, however, is not so big.{{highlight|'''&lt;ref>'''Smith, R: "Size of the Moon", ''Scientific American'', 46(78):46'''&lt;/ref>'''}}
<br/>
<br/>
&#61;=Notes==
<br/>
{{highlight|'''&lt;references/>'''}}
</tt>
</blockquote>
</blockquote>


===Multiple uses of the same footnote===


To give a footnote a unique identifier, use '''<nowiki><ref name="name"></nowiki>'''. You can then refer to the same footnote again by using a ref tag with the same name. The text inside the second tag doesn't matter, because the text already exists in the first reference. You can either copy the whole footnote, or you can use a terminated empty ref tag that looks like this: '''<nowiki><ref name="name"/></nowiki>'''.
Note that references may be cited more than once using <code><nowiki><ref name=/></nowiki></code>. In the example above, the ''New York Times'' article is cited twice. In the second instance, instead of typing out the full reference (<code><nowiki><ref name=NYT>''New York Times''. [[January 14]], [[2010]] issue, page 16</ref></nowiki></code>), one may simply use <code><nowiki><ref name=NYT/></nowiki></code>. Be careful not to forget the <code>/</code>. (Note that apparently, as of [[14 March]] [[2006]], all-number names [[Talk:Cite/Cite.php#What's wrong with numeric labels?|do not work]].)

In the following example, the same source is cited three times.

<blockquote>
<tt>
This is an example of multiple references to the same footnote.{{highlight|'''&lt;ref name&#61;"multiple">'''Remember that when you refer to the same footnote multiple times, the text from the first reference is used.'''&lt;/ref>'''}}
<br/>
<br/>
Such references are particularly useful when citing sources, if different statements come from
the same source.{{highlight|'''&lt;ref name&#61;"multiple">'''This text is superfluous, and won't show up anywhere. We may as well just use an empty tag.'''&lt;/ref>'''}}
<br/>
<br/>
A concise way to make multiple references is to use empty ref tags, which have a slash at the
end.{{highlight|'''&lt;ref name&#61;"multiple" />'''}}
<br/>
<br/>
&#61;=Notes==
<br/>
{{highlight|'''&lt;references/>'''}}
</tt>
⚫
</blockquote>

The text above gives the following result in the article (see also [[#Notes|Notes section]] below):
<blockquote>
This is an example of multiple references to the same footnote.<ref name="multiple">Remember that when you refer to the same footnote multiple times, the text from the first reference is used.</ref>
<br/>
<br/>
Such references are particularly useful when citing sources, when different statements come from the same source.<ref name="multiple">This text is superfluous, and won't show up anywhere. We may as well just use an empty tag.</ref>
<br/>
<br/>
A concise way to make multiple references is to use empty ref tags, which have a slash at the end.<ref name="multiple" />
</blockquote>


=== &lt;references&gt; ===
=== &lt;references&gt; ===

Revision as of 02:50, 16 April 2006

Template:Cite/Cite.php

This page gives general documentation valid for all MediaWiki installations which use the cite extension. For use of this feature in the English Wikipedia see w:Wikipedia:Footnotes. That page also includes more examples.

Cite.php is a Cite extension that adds two parser hooks to MediaWiki, <ref> and <references>; these operate together to add citations to pages.

Synopsis

  • <ref[ name=["id"|id]]>Reference text</ref> — the quotes are only needed if id contains whitespace, where whitespace is one of [\x09\x0a\x0d\x20]
  • <ref name=["id"|id]/> — repeated use of same reference may be done as before or in this format with no need to repeat the reference text. In this case the ID is mandatory.
  • <references/>

Description

The basic concept of the <ref> tag is that it inserts the text enclosed by the ref tags as a footnote in a designated section, which you indicate with the placeholder tag <references/>. The new format cannot be used interchangeably with the old format - you must pick one or the other.

If you forget to include <references/> at the end of the article, none of the footnotes will appear.

This page itself uses footnotes, such as the one at the end of this sentence.[1] If you view the Wikicode of this page by clicking "Edit this page", you can see a working example of footnotes.

Example

According to scientists, the Sun is pretty big.<ref>Miller, E: "The Sun.", page 23. Academic Press, 2005</ref>
The Moon, however, is not so big.<ref>Smith, R: "Size of the Moon", Scientific American, 46(78):46</ref>

==Notes==
<references/>

Multiple uses of the same footnote

To give a footnote a unique identifier, use <ref name="name">. You can then refer to the same footnote again by using a ref tag with the same name. The text inside the second tag doesn't matter, because the text already exists in the first reference. You can either copy the whole footnote, or you can use a terminated empty ref tag that looks like this: <ref name="name"/>.

In the following example, the same source is cited three times.

This is an example of multiple references to the same footnote.<ref name="multiple">Remember that when you refer to the same footnote multiple times, the text from the first reference is used.</ref>

Such references are particularly useful when citing sources, if different statements come from the same source.<ref name="multiple">This text is superfluous, and won't show up anywhere. We may as well just use an empty tag.</ref>

A concise way to make multiple references is to use empty ref tags, which have a slash at the end.<ref name="multiple" />

==Notes==
<references/>

The text above gives the following result in the article (see also Notes section below):

This is an example of multiple references to the same footnote.[2]

Such references are particularly useful when citing sources, when different statements come from the same source.[2]

A concise way to make multiple references is to use empty ref tags, which have a slash at the end.[2]

<references>

Placing <references> inserts the full text of all pending inline citations defined by <ref>, anywhere on the page. For example, based on the citations above, the code:

<references/>

will yield:

  1. ↑ This footnote is used as an example in the "How to use" section.
  2. ↑ 2.0 2.1 2.2 Remember that when you refer to the same footnote multiple times, the text from the first reference is used. Cite error: Invalid <ref> tag; name "multiple" defined multiple times with different content

Customization

The format of the output of <ref> and <references> is almost completely customizable through MediaWiki messages, that can be modified e.g. though the MediaWiki namespace depending on the configuration of the wiki.

List of messages that control the output of <ref> and <references> and the values, if any, that are passed to them ($1, $2, $3 ...), see the code in CVS for an up-to-date listing of their default contents.

  • cite_reference_link_key_with_num
    1. key
    2. num
  • cite_reference_link_prefix
  • cite_reference_link_suffix
  • cite_references_link_prefix
  • cite_references_link_suffix
  • cite_reference_link
    1. ref ID
    2. backlink ID
    3. count to display
  • cite_references_link_one
    1. backlink ID
    2. ref ID
    3. text of note
  • cite_references_link_many
    1. backlink ID
    2. list of links
    3. text of note
  • cite_references_link_many_format
    1. ref ID
    2. numeric value to use as a backlink
    3. custom value (as defined in cite_references_link_many_format_backlink_labels to use as a backlink)
  • cite_references_link_many_format_backlink_labels
  • cite_references_link_many_sep
  • cite_references_link_many_and
  • cite_references_prefix
  • cite_references_suffix

Issues

Current issues

Using <ref> in templates breaks numbering
Issue with MediaWiki regarding in what order things are parsed
It's impossible to pass template arguments to <ref>, e.g. <ref name={{{1}}}>
Issue with MediaWiki, see bug 4529
Using <ref> in image captions breaks the XHTML output
Issue with MediaWiki, not this extension, see bug 1887.
The citation links generated by <ref> and the backlinks generated by <references> have an empty title attribute (<a href="..." title="">...)
Issue with MediaWiki, not this extension. MediaWiki will generate output like <a href="#foo" title="">bar</a> when given input like [[#foo|bar]]
Missing name= anchors for backwards compatibility
The generated <a href="#_note-n"> links should have a name="_ref-n".
The generated <a href="#_ref-n"> links should have a name="_note-n".
Commenting out <ref> with HTML comments <--…--> hides the citation but the reference still appears on the list
This would appear to be a parser error…
Template substitution misrenders inside <ref> tag.

Past issues

The extension didn't generate id attributes that could be uniformly styled with CSS2 attribute selectors
Issue in Cite.php, see bug 4579
Using multibyte characters, colons, spaces and other values that need to be encoded according to the HTML spec breaks internal links
Issue with MediaWiki, not this extension, see bug 4461.

Comparing ref/note style and Cite.php style

They are actually very similar.

  • To make a single use footnote:
    • Ref/note
      1. {{ref|foo}} at the in-text place.
      2. # {{note|foo}} text of note at the proper place in the References list.
    • Cite.php
      1. <ref>text of note</ref> at the in-text place.
      2. (Only needed once per article)<references/> under the References heading.
  • To make a multiple use footnote:
    • Ref/note
      • With strict ref/note style this was impossible, but a number of alternative forms had been created, for the details of which, see the appropriate pages.
    • Cite.php
      1. <ref name=foo>text of note</ref> at each in-text place.
        1. Alternatively <ref name=foo /> A self-closing tag on every use after name=foo has been defined.
      1. (Only needed once per article)<references/> under the References heading; exactly the same as to make a single-use note.
Retrieved from "https://www.mediawiki.org/w/index.php?title=Extension:Cite/Cite.php&oldid=102299"