User:Sperling/References

This is a proposal for enhancing the wikimedia markup language to facilitate easy creation and maintenance of a list of external sources quoted in a document.

Enhanced References

In my opinion, the current link markup makes it cumbersome to create and especially maintain a proper list of references for a document. While the [link] syntax creates numbers in square brackets that mimics the look of references seen in scientific papers, it has a number of drawbacks:

• Multiple links to the same URL don't get the same number. (This could be fixed quite easily.)
• The References list at the end of the document has to be created manually, and the numbers have to be manually kept in sync with the numbers assigned by [link]. This is very cumbersome, as any edit that changes the order of two [link]s mandates a change in the References section.
• Links created with [link] point directly to the target document. This is of course the proper behaviour for normal hypertext links, as those are usually sufficiently described by their link label. But when providing a reference, the link label needs to be short to avoid cluttering the document, and additional information about the referenced document needs to be provided in the References section. Making the reference an intra-document link to the corresponding entry in the References section solves this problem.
• With [link] it is impossible to reference documents that don't have a URL.

Please comment on this proposal on the talk page. Any comments on the problems listed below would be especially useful. If a consensus is reached that implementing this (or a modified) proposal is a good idea, I will probably go ahead and write the required code. Unless, of course, one of the existing wikimedia hackers is keen to do it or beats me to it ;-) --K. Sperling

References in Action

This sample markup shows how references could be used. A "rendered" version of this example can be found at http://spiff.de/misc/wikirefs.html. I can't put the HTML here directly, because the wikitext parser would escape it.

 It is generally recognized that frogs are greener than
 grass.[[XRef:Green Frogs]]  
 
 A little known[[XRef:Frog Poll]] fact, however, is that frogs can move
 backwards in time.[[XRef:Encyclopedia Galactica|p4982]]
 
 === References ===
 
 [[Reference:Green Frogs|http://all-about-frogs.com/green.html]] The most
 comprehensive source on green frogs on the web
 
 [[Reference:Encyclopedia Galactica]] ''The Encyclopedia Galactica'',
 available on a planet near you
 
 [[Reference:Frog Poll|http://all-about-frogs.com/poll.html|Poll on all-about-frogs.com]] 

Proposed Syntax

[[XRef:Reference Name]]
[[XRef:Reference Name|Additional Label]]

[[XRef]] creates a cross reference. References are identified by a reference name. For each reference name referenced by an [[XRef]], there must be a corresponding [[Reference]] somewhere in the document (usually at the end).

The reference is rendered as a number in square brackets (e.g. [7]), linking to the corresponding [[Reference]]. If the [[Reference]] has an URL associated with it, a direct link to that URL is also included. The additional label, if present, is placed inside the square brackets, and separated from them by a comma (e.g. [7, 1st chapter]).

[[Reference:Reference Name]]
[[Reference:Reference Name|URL]]
[[Reference:Reference Name|URL|Link Label]]

[[Reference]] defines a named reference. There mustn't be more than one [[Reference]] with the same reference name.

The reference definition is rendered as a numbered list item. The same number will be displayed in all [[XRef]]s referring to this reference definition. The optional URL and Link Label parameters can be used associate a link with the reference definition. If no Link Label is given, it defaults to the URL.

Any text following the [[Reference]] on the same line will be included in the list item.

Problems

A few problems still need to be addressed:

• References and plain [link]s (without a link label) would look very similar in the rendered document. This would be especially confusing if they used separate counters to generate the labels. This problem could be solved in (at least) three ways:
  1. Change the way references are rendered. This is undesirable, as the number-in-square-bracket notation is a de-facto standard.
  2. Change the way unlabeled links are rendered, e.g. by using letters instead of digits or some other form of bracket. However, changing the current numbering scheme would affect existing documents that emulate a References section using unlabeled links. Simply using another style of bracket doesn't have this problem, but may still be visually too close to the way references are rendered.
  3. Have unlabeled links and references share a counter. This makes creating the references section a little more difficult, because reference numbers could be non-continuous, leading to gaps in the References section. This could in turn be solved by first numbering references from 1 continuously, and only then assigning higher numbers to links. Note that this scheme (in either variant) does not change the link numbering in existing documents. Changes would only be required once references are actually used in a document.
• If a reference name is referenced but not defined in the References section, the wikitext translator will still have to do something. Options include silently ignoring the reference, or rendering an error indicator instead.
• For references that have a URL, it is desirable to link to both the entry in the References section and the target URL. The rendering employed in the sample may not be the best way to implement this.