Bikeshed Documentation

8. Bibliography

Bibliographical references form a special class of autolinks. They’re typically added only via the shorthands [[FOO]] for informative references and [[!FOO]] for normative references.

(A "normative reference" is a reference that your document depends on; something in the other document is required in order to implement your document correctly. An "informative" reference is anything else. Informative references might be to normative documents, if your feature doesn’t actually depend on the referenced document.)

Unlike regular autolinks, which link to dfn elements, biblio autolinks cause the spec to generate entries in its "References" section, and then link to that instead.

The bibliography database is completely separate from the autolinking database, and comes from multiple sources. The default data comes from the SpecRef project and the CSSWG’s own biblio file (preferring SpecRef’s information when the same name appears in both).

8.1. Biblio Link Modifiers

Several aspects of how bibliography autolinks work can be controlled by adding keywords to the autolink, after the biblio name.

• Some biblio entries come with multiple sets of urls; at present, Bikeshed tracks a single "current" url and a single "snapshot" url. In the W3C, for example, this maps to Editors Drafts and things in /TR space, respectively.

  You can specify which url to use by specifying current or snapshot within the biblio shorthand, like [[FOO current]], or specify the default url to choose for all your biblio refs with the Default Ref Status.

• By default, biblio autolinks are formatted in the "index" style, where they are links to the bibliography, and appear like you typed, just with a single set of square brackets: [[FOO]] will produce a link with the text "[FOO]".

  Alternately, they can be configured to use the "direct" style, which links directly to the document in question, rather than the bibliography entry containing the link. (The bibliography entry still gets added.)

  There is also an "inline" style, which links directly to the document in question, and formats itself as the title of the document, rather than as the short biblio tag you typed.

  These can be controlled on a link-by-link basis by setting inline, direct, or index in the shorthand, like [[FOO inline]], or change the default for all biblio links in the document by setting the Default Biblio Display metadata.

• The bibliography database tracks whether certain documents have been obsoleted by newer documents, and if you attempt to link to the the now-obsolete document, Bikeshed defaults to linking to the newer document instead and asking you to update the reference.

  If you do intentionally need to link to a now-obsolete document (for example, if you’re talking about a feature in the old document that’s since been replaced), you can tell Bikeshed you do intend to link to that by setting obsolete in the shorthand, like [[FOO obsolete]].

All of these keywords can be combined, in any order, such as [[FOO inline obsolete]] or [[FOO index current]].

8.2. Autolinking and Automatic Bibliography Entries

Whenever you autolink to a term from another spec using a standard dfn autolink, Bikeshed automatically adds a bibliography entry for that document if one doesn’t already exist.

By default, it assumes these are normative references. However, if the link is in a "non-normative" element, Bikeshed doesn’t put it in the bibliography. This includes any notes (class=note), examples (class=example), or sections manually marked with class=non-normative. (You can override this and get a normative reference by adding a class=normative to the link or an ancestor.)

8.3. Manual Biblio Links

If, for whatever reason, you need to craft a bibliography link manually, just create an a element with data-link-type=biblio and the biblio tag either in the text content of the link or in a data-lt attribute, similar to a manually-crafted autolink.

If you need one of the biblio link modifiers, add data-biblio-type=[normative | informative], data-biblio-status=[current | snapshot], data-biblio-display=[index | inline], and/or data-biblio-obsolete="" to the link as well.

8.4. Custom Biblio Entries

You can also add your own bibliography data, following the SpecRef JSON format:

{
  "foo-bar": {
    "authors": [
      "Tab Atkins",
      "Bat Snikta"
    ],
    "href": "http://www.example.com/foo-bar/",
    "title": "Foo Bar Level 1",
    "status": "CR",
    "publisher": "W3C",
    "deliveredBy": [
      "http://www.w3.org/html/wg/"
    ]
  }
}

This would allow you to write [[FOO-BAR]] into your document, and have it be recognized as a valid autolink, with a bibliography entry generated in the index just like any of the predefined biblio references.

Note: Only the "title" field is strictly necessary; the rest can be omitted if desired.

This JSON should be inline, in a <pre class=biblio> block. It can also be in a biblio.json file in the same folder as the Bikeshed file, but this is incompatible with the web service.

If you find yourself adding this to more than one document, it might be worth adding to SpecRef itself so others can benefit from it as well; file an issue on that project if you’re interested.