citation-strawman-01

Citation Stawman: "h3988"

This is a sketch for a citation microformat. Please raise any problems with this draft on the issues page; and suggest any expansions on the brainstorming page.

The final name of the microformat is not decided — "h3988" should be considered a working title to differentiate it from other proposed citation microformats. The root class name may eventually change to something more author-friendly.

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.

Key

Based on Perl's standard quantifiers:

bold {1}	MUST be present exactly once
italic*	OPTIONAL, and MAY occur more than once
+	MUST be present, and MAY occur more than once
?	OPTIONAL, but MUST NOT occur more than once
[square brackets]	list of common values
(parentheses)	data format
#	comment
!	awaiting documentation

Book Citations

• h3988 {1}
  • btitle {1} — book title
  • edition ?
  • isbn ?
  • 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
  • Common properties

Journal Citations

At least one of jtitle or stitle must be present.

• h3988 {1}
  • artnum ? — article number
  • eissn ? — EISSN
  • issue ? — issue of the journal, often numeric
  • jtitle ? — journal title
  • part ? — part of the issue being cited, if the issue is divided into physical parts (e.g. "pull-out", "supplement", "B")
  • quarter ? (1|2|3|4) — quarter of publication
  • ssn ? — season of publication (e.g. 'spring')
  • stitle ? — abbreviated (short) title. (e.g. "JMLA")
  • volume ? — volume of journal, often numeric
  • Common properties

Common Properties

• • atitle ? — article/chapter/section title, if citing a particular article within the publication
  • au * (hCard|text) — author of article, if article is being cited; or (rarely) editor if whole issue is being cited.
  • date ? (ISO-8601) — date published
  • description ? — a description of the item being cited, or the reason it is being cited
  • genre ?
    • For book schema: (book|bookitem|proceeding|conference|report|document|unknown) — "book" is the default, but "bookitem" is implied if 'atitle' or 'pages' is present.
    • For journal schema: (issue|article|proceeding|conference|preprint|unknown) — "issue" is the default, but "article" is implied if 'atitle' or 'pages' is present.
  • issn ? — ISSN
  • language ? — the language of the item being cited. (Not to be confused with the language of the citation itself, which should be indicated using standard markup — lang or xml:lang)
  • pages ? — pages being cited, if only part of the publication is being cited. Has optional subproperties.
    • spage ? — start page
    • epage ? — end page
  • url * — URL of the item.

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).

The root element SHOULD 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.

When more detail is required, hCard's role property may be used to indicate the person's role in the publication (e.g. 'editor', 'primary author', 'contributor', etc).

Corporate authors may be indicated using an organisational hCard. i.e. class="fn org".

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.

url

url is unique in that it is the only property not directly derived from Z39.88. It has however been shown to be useful in hCard and various other microformats, and it is very common to include a URL when citing an online resource.

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 rel="footnote" id="#ref-fpc">FPC</a>].
</p>

References

• OCOinS.info: Brief guide to Implementing OpenURL 1.0 Context Object for Journal Articles
• OCOinS.info: Brief guide to Implementing OpenURL 1.0 Context Object for Books

Related Pages

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