Citations

This page provides instructions for defining and citing references by this task force. These instructions apply to documents that use Respec for processing.

Short cut

However, you can send the reference to Ayelet, who will add it to the JSON reference page. Then you just need to:

1. Check if it has been used (see "Finding already defined references" bellow)
2. Decide the handler and check it has not been used
3. Send Ayelet the information about the citation and your handler (see "Citing a reference" bellow)

Key resources:

• W3C reference format
• Instructions for the JSON reference format
• Citing references in Respec documents
• COGA bibliography
• Coming soon, hopefully, human-readable rendered view of the COGA bibliography

Finding already defined references

Specifications published by W3C are usually already in the common database of references. Other publications may also be defined in this database. It is strongly preferred to use references from the central database whenever possible, so if a reference is likely to be in that database, please double check it.

The specref page provides various ways to search the database. These techniques do require creating special URIs, and return results in JSON format, which is not super human friendly. Hopefully the task force can make available search forms to facilitate searching, and a rendering tool to produce human-readable results. Those resources will be referenced from here when available.

If a reference is not in the central database, it may be already defined in the COGA bibliography. Please check that resource as well. Again, search forms and render tools may become available, but at the moment this requires reviewing the raw bibliography file.

Defining a reference

If a reference is not defined in one of the above places, it must be added to the COGA bibliography before it can be cited in a document. To add a reference you must edit the COGA bibliography file, either on the web site by activating the pencil icon "Edit this file", or by editing the git repository on your local machine and then pushing your update.

All reference consist of a "handle" in quotes, followed by a colon, followed by a curly braces that enclose a set of values, followed by a trailing comma. At its most simple, this looks like:

"handle": {
  ...
},

The handle is the key to using the reference, so it must be unique. It should also be reasonable short, and must consist only of alphanumeric characters and simple punctuation such as period, underscore, and hyphen. For the moment the task force has decided that the handle will be the lead author's surname, followed by a hyphen, followed by a number so multiple publications from the same lead author can be differentiated. To make it easier for people working on the document, please position new references so that the file is sorted alphabetically by handle name.

Inside the curly braces are key / value pairs that provide data for the reference. Refer to the specref documentation for information about available keys. Not all references require all keys. For instance, "deliveredBy" is only used for materials developed by a subgroup within the publishing organization, such as a W3C Working Group. "href" is only used for references that are available online.

Some of the keys allow multiple values to be provided. If you are providing multiple values, enclose them in square braces, as shown in the example documentation. If the values are simply strings, they can be provided as is, separated by commas (as is done with "authors" in the example documentation. If the values are themselves sets of key / value pairs, enclose each of those in curly braces as well (as is done with "deliveredBy" in the example documentation).

References defined in this format refer to an entire publication - an entire book, specification, journal article, etc. It is not possible nor appropriate to include page numbers, section numbers, chapter numbers, etc. in the central database. Clarifying these details is done when the reference is cited. This allows a single book to be defined once and different page ranges used in different citations.

Citing a reference

In a specification, references are cited by enclosing the handle in double square brackets. A reference identified by "handle" as in the example above would be cited by including "[[handle]]" in the document. The processing script sees that handle, looks up the reference in the database (both the global one and the task force specific one), adds a formatted reference to the references section, and changes the "[[handle]]" that triggered all this into a link to that entry in the references section. Note this is done when the document is loaded in the browser, not during editing.

A reference should be cited in this manner at least once in the document to ensure it shows up in the reference appendix. It is possible to cite it many times, and it is best to cite it whenever the reference is directly discussed. Use discretion though, if a reference is discussed multiple times in a single paragraph, it is probably only necessary to cite it once in that paragraph.

If it is important for the citation to specify a particular page number in a book or section in an online document, this is done after the citation. Enclose the citation in parentheses and specify the page number or section after the citation inside the parentheses. This would look like "([[handle]], page X)". Citing the same publication multiple times can reference different page numbers.

Adding COGA bibliography to new publications

Include the script in the HTML page with a script tag, just below the one that includes the Respec processing script:

<script src="../common/biblio.js" class="remove"></script>

This script defines a variable "biblio" and sets its value to the JSON data structure of the references that have been identified above.

In the respecConfig section of the specification, change the line beginning "localBiblio" to be:

localBiblio: biblio,

Any bibliographic content enclosed in curly braces should be removed and put into the biblio.js file.

Style guidelines for references

• Content: We should always have the name of the article / book, author(s), date of publication, journal title (if appropriate),
• To cite a specific part of a source (always necessary for quotations), include the page.
• For urls should have the name of the article, date viewed and URL
• References links occur at minimum at the first mention of the source. Spell out what the reference link refers to at least in the first occurrence, e.g.:
  • This is discussed in Namespaces in XML [XMLName].
    or
  • "This is discussed in the XML namespaces specification [XMLName]. "
    and not
  • "This is discussed in [XMLName]".