citation-strawman-01

Citation Stawman: "h3988"

This is a sketch for a citation microformat.

Contributors

Editor: TobyInk

The editor acknowledges the input of contributors to the citation-formats, citation-examples and citation-brainstorming wiki pages.

Design Methodology

I have been through the citation-examples page, looking at which pieces of information are commonly used in citations on the Internet. Using that knowledge, and guided by the naming-principles (do not make up names from thin air, do not ignore earlier work) I have taken a subset of the terms from OpenURL (Z39.88) which correspond to the pieces of metadata used by citations in the wild.

I have then mapped these Z39.88 terms to semantic HTML, re-using existing microformats such as hCard for author and publisher information, and reusing existing design patterns such as the class-design-pattern the datetime-pattern for dates.

Schema

Separate, but largely overlapping schemas are provided for citations of books and journals. Websites may usually be cited as if they were journals.

As both schema use the same root class name, a method is needed to differentiate between journal citations and book citations. This method is: if a btitle property exists within the citation, then it is a book citation; otherwise, it is a journal citation.

Book Citations

• h3988 {1}
  • btitle {1} — book title
  • au * (hCard|text) — author
  • atitle ? — chapter/article title, if citing a particular part of the book
  • date ? (ISO-8601) — date published (generally only a year is needed)
  • edition ?
  • isbn ?
  • issn ? : ISSN, if part of a series
  • pages ? — pages being cited, if only part of the book is being cited. Has optional subproperties.
    • spage ? — start page
    • epage ? — end page
  • place ? (adr|text) — place published (can be implied from 'pub' hCard sometimes)
  • pub ? (hCard|text) — publisher
  • series ? — title of the series in which the book was published
  • genre ? (book|bookitem|proceeding|conference|report|document|unknown) — "book" is the default, but "bookitem" is implied if 'atitle' or 'pages' is present.

Journal Citations

At least one of jtitle or stitle must be present.

• h3988 {1}
  • au * (hCard|text) — author of article, if article is being cited; or (rarely) editor if whole issue is being cited.
  • artnum ? — article number
  • atitle ? — article title, if citing a particular article within the journal
  • date ? (ISO-8601) — date published
  • eissn ? — EISSN
  • issn ? — ISSN
  • issue ? — issue of the journal, often numeric
  • jtitle ? — journal title
  • pages ? — pages being cited, if only part of the issue is being cited. Has optional subproperties.
    • spage ? — start page
    • epage ? — end page
  • part ? — part of the issue being cited, if the issue is divided into physical parts (e.g. "pull-out", "supplement", "B")
  • stitle ? — abbreviated (short) title. (e.g. "JMLA")
  • genre ? (issue|article|proceeding|conference|preprint|unknown) — "issue" is the default, but "article" is implied if 'atitle' or 'pages' is present.
  • volume ? — volume of journal, often numeric

Footnotes

Additionally, this strawman microformat defines a rel value of "footnote" for linking from article text to an h3988 citation elsewhere on the page. (e.g. in footnotes or a bibliography section).

Parsers MAY follow rel=footnote links to other pages, but are not required to. Authors should be aware that parsers might not follow off-page footnote links. On-page references are generally preferred.

When linking to a citation by ID attribute, the ID attribute should be on the h3988 citation itself, and not on a parent or ancestor node. e.g.:

PREFERRED: <cite class="h3988" id="ref01">...</cite>
ALLOWED:   <li class="h3988" id="ref01"><cite>...</cite></li>
NO:        <li id="ref01"><cite class="h3988">...</cite></li>

Properties

Hopefully most of the properties are self explanatory, but some deserve a fuller explanation.

h3988

This microformat is derived from the Z39.88 standard, so similar to hCard uses its ancestor's name as the root class name. The punctuation is dropped and the "Z" replaced with an "h", partly to follow a common pattern in microformat naming, but also to avoid clashes with COinS (another Z39.88+HTML-based standard).

Normally, the root element will be a <cite> element. It is often useful to give the citation an ID attribute. For example:

<cite class="h3988" id="ref01">...</cite>

au

The author of the item being cited. This can be expressed as either plain text:

<span class="au">Elizabeth David</span>

Or as an embedded hCard:

<span class="au vcard">
  <span class="fn n">
    <span class="given-name">Elizabeth</span>
    <span class="family-name">David</span>
  </span>
</span>

When possible, an embedded hCard is preferable, but in some cases (e.g. automatic conversion from another citation format which only treats an author as a string) this may not be possible.

It should be noted that au is the only plural property.

pages

If only part of a work is being cited, it if often useful to include the page number(s). You may do this as a simple string:

<span class="pages">206, 208&ndash;209</span>

In the case where a contiguous section is referenced, then additional spage and epage subproperties are available to mark up the start and end pages:

<span class="pages">
  <span class="spage">46</span> to <span class="epage">46</span>
</span>

Parsers must not assume that pages will be numerically labelled. For instance, many books contain sections with pages numbered in roman numerals.

stitle

This property is for marking up the short title of a journal. Most academic journals have well-established short titles which are often used to reference them. Of interest is that this property should be considered "immune" to the abbr-design-pattern. That is:

<abbr class="stitle" title="Foo">Bar</abbr>

should be parsed as "Bar", not "Foo". This allows a convenient pattern to be used:

<abbr class="jtitle stitle" title="British Journal of Medicine">BMJ</abbr>

place

It is customary to include the city where a book has been published. However, if the publisher's hCard contains an adr with a locality subproperty, then place may be inferred from that.

Examples

Citation in Running Text

<p>
  According to
  <cite class="h3988">
    <i class="btitle">French Provincial Cooking</i> by
    <span class="au vcard">
      <span class="fn n">
        <abbr title="Elizabeth" class="given-name">E</abbr>
        <span class="family-name">David</span>
      </span>
    </span>
  </cite>
  to cook Filets de Macquereaux a la Tomate, you need to first coat the mackeral with flour.
</p>

A Book in a Bibliography

<h2>Bibliography</h2>
<ul>
  <li>
    <dfn>[FPC]</dfn>:
    <cite class="h3988" id="ref-fpc">
      <i class="btitle">French Provincial Cooking</i>,
      <span class="au vcard">
        <span class="fn n">
          <abbr title="Elizabeth" class="given-name">E</abbr>
          <span class="family-name">David</span>
        </span>
      </span>,
      <span class="pub vcard">
        <span class="fn org">Penguin Books</span>,
        <span class="adr"><span class="locality">London</span></span>
      </span>,
      <span class="date">1960</span>.
    </cite>
  </li>
  <!-- ... -->
</ul>

Which might be cited in running text like:

<p>
  To cook Filets de Macquereaux a la Tomate, you need to first coat the mackeral
  with flour [<a ref="footnote" id="#ref-fpc">FPC</a>].
</p>

Related Pages

• citation
• citation-examples
• citation-examples-markup
• citation-formats
• citation-brainstorming
• citation-faq
• citation-issues
• Strawman microformats:
  • hCite
  • h3988 (brainstorming, issues)