View source for citation-strawman-01

<h1>Citation Stawman: "h3988"</h1>

This is a sketch for a [[citation]] microformat. Please raise any problems with this draft on the [[citation-strawman-01-issues|issues]] page; and suggest any expansions on the [[citation-strawman-01-brainstorming| 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.

{{TOC-right}}

= Contributors =

'''Editor:''' [[User:TobyInk|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 [http://en.wikipedia.org/wiki/OpenURL 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, journals, patents and dissertations. Websites may usually be cited as if they were journals, with the site name as the '''jtitle''' and the page title as the '''atitle'''.

As the schema use the same root class name, a method is needed to differentiate between different types of citation. This method is:
# If a '''btitle''' property exists within the citation, then it is a book citation; 
# Else if '''stitle''' or '''jtitle''' exists, then it is a journal/website citation;
# Else if '''number''' exists, then it is a patent citation;
# Else if '''atitle''' exists, it is a dissertation citation.

<div style="clear:right;float:right;width:350px">
==Key==
Based on Perl's [http://www.perl.com/doc/manual/html/pod/perlre.html standard quantifiers]:
{| border="1" cellpadding="2"
| '''bold''' {1} || {{must}} be present exactly once
|- 
| ''italic''<nowiki>*</nowiki> || {{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 
|}
</div>

<div style="width:400px">

== Book Citations ==

* '''h3988 mfo''' {1}
** '''btitle''' {1} — book title
** ''edition'' ?
** ''pub'' ? (hCard|adr|text) — publisher
** ''series'' ? — title of the series in which the book was published
** [[#Common_Properties|Common properties]]

== Journal Citations ==

At least one of ''jtitle'' or ''stitle'' {{must}} be present.

* '''h3988 mfo''' {1}
** ''issue'' ? — issue of the journal, often numeric
** ''jtitle'' ? — journal title
** ''stitle'' ? — abbreviated (short) title. (e.g. "JMLA")
** ''volume'' ? — volume of journal, often numeric
** [[#Common_Properties|Common properties]]

== Patent Citations ==

* '''h3988 mfo''' {1}
** '''cc''' {1} (ISO 639)
** '''number''' {1}
** [[#Common_Properties|Common properties]]
*** common property '''atitle''' is {{required}}.

== Dissertation Citations ==

* '''h3988 mfo''' {1}
** ''advisor'' ? (hCard|text)
** ''degree'' ? (text)
** [[#Common_Properties|Common properties]]
*** common property '''atitle''' is {{required}}.

</div>

== Common Properties ==

** ''atitle'' ?  — article/chapter/section title, if citing a particular article within the publication
** ''au'' * (hCard|text) — author of the book, article, etc; or (rarely) editor if a whole issue of a journal is being cited.
** ''date'' ? (ISO 8601) — date published
** ''description'' ? — a description of the item being cited, or the reason it is being cited
** ''format'' ? — the type of resource being cited. (e.g. 'book', 'article', 'discussion')
** ''identifier'' * — an identifier for the item being cited
** ''language'' ? (ISO 639-1 or ISO 639-2) — 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 — <code>lang</code> or <code>xml:lang</code>)
** ''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 uses the existing (see [http://www.w3.org/TR/rdfa-syntax/#relValues RDFa], [http://www.w3.org/TR/xhtml2/mod-metaAttributes.html#adef_metaAttributes_rel XHTML 2.0], [[distributed-conversation-brainstorming#rel.3D.22cite.22_.2F_rev.3D.22cite.22|distributed conversation brainstorming]], etc) [[rel]] value of "cite" 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=cite 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.:

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

= Properties =

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

== <code>h3988 mfo</code> ==

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 [http://ocoins.info COinS] (another Z39.88+HTML-based standard).

Authors {{must}} include the class name "mfo" on the root element for [[MFO|opacity]] reasons.

The root element {{should}} be a <code>&lt;cite></code> element. It is often useful to give the citation an ID attribute. For example:

<pre><nowiki><cite class="h3988 mfo" id="ref01">...</cite></nowiki></pre>

== <code>au</code> ==

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

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

Or as an embedded hCard:

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

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 {{should}} be used to indicate the person's role in the publication (e.g. 'editor', 'primary author', 'contributor', etc). Corporate authors {{should}} be indicated using an organisational hCard. i.e. <code>class="fn org"</code>. For dissertations, the '''org''' property {{should}} be used to indicate the author's institution. For example:

<pre><nowiki><span class="au vcard">
  <span class="fn n">
    <span class="given-name">Joe</span>
    <span class="family-name">Bloggs</span>
  </span>,
  <span class="org">Poppleton University</span>,
  <span class="adr">
    <span class="region">Yorkshire</span>
    <abbr class="country-name" title="United Kingdom">UK</abbr>
  </span>
</span></nowiki></pre>

== <code>identifier</code> and <code>url</code> ==

There are a number of identifying codes, such as ISBN, ISSN, DOI, Pubmed ID and so forth, which are sometimes used when citing resources, especially in certain specialist fields. Rather than have separate properties for each of these, an <code>identifier</code> property is provided which follows rules similar to <code>tel</code> and <code>email</code> in [[hCard]], in that it has a type+value structure. For example:

<pre><nowiki><span class="identifier">
  <span class="type">ISBN</span>
  <span class="value">978-1-56619-909-4</span>
</span></nowiki></pre>

The following (case-insensitive) types are defined:

* BICI
* [http://en.wikipedia.org/wiki/CODEN CODEN]
* [http://en.wikipedia.org/wiki/Digital_object_identifier DOI]
* EISSN
* [http://en.wikipedia.org/wiki/International_Standard_Book_Number ISBN]
* [http://en.wikipedia.org/wiki/International_Standard_Serial_Number ISSN]
* [http://en.wikipedia.org/wiki/Library_of_Congress_Control_Number LCCN]
* [http://en.wikipedia.org/wiki/PMID PMID]
* [http://en.wikipedia.org/wiki/Serial_Item_and_Contribution_Identifier SICI]

The <code>identifier</code> property may be used with a null type to indicate an author-defined identifier or an identifier from a scheme not included in this specification. Lastly, if a journal citation has an <code>stitle</code> property ''and'' identifier type matches the citation's short title, then the identifier is assumed to be from a scheme specific to that journal. (If the value is also numeric, then this is an equivalent semantic to OpenURL's "artnum".) For example:

<pre><nowiki><cite class="h3988 mfo">
  <span class="jtitle">Journal of Rat Studies</span>:
  <span class="atitle">Rats and their Bretheren</span>.
  [<span class="identifier">
    <span class="stitle type">JRat</span>
    <span class="value">12345</span>
  </span>]
</cite></nowiki></pre>

As an optimisation, the type and value can both be implied when the identifier is a link matching one of the following patterns:

* <code><nowiki>http://dx.doi.org/X</nowiki></code> &rarr; type='DOI', value='X'
* <code><nowiki>doi:X</nowiki></code> &rarr; type='DOI', value='X' (Unapproved URI scheme, but parsers should support this for future proofing.)
* <code><nowiki>urn:doi:X</nowiki></code> &rarr; type='DOI', value='X' (Unapproved URN scheme, but parsers should support this for future proofing.)
* <code><nowiki>urn:isbn:X</nowiki></code> &rarr; type='ISBN', value='X'
* <code><nowiki>urn:issn:X</nowiki></code> &rarr; type='ISSN', value='X'
* <code><nowiki>http://lccn.loc.gov/X</nowiki></code> &rarr; type='LCCN', value='X'
* <code><nowiki>http://www.ncbi.nlm.nih.gov/pubmed/X</nowiki></code> &rarr; type='PMID', value='X'

For example:

<pre><nowiki><a class="atitle identifier" href="http://www.ncbi.nlm.nih.gov/pubmed/1"
>Formate assay in body fluids: application in methanol poisoning.</a></nowiki></pre>

Any identifier link which is not on the list of recognised optimisations above, parsers {{must not}} attempt to extract a type and value. (As this is a draft specification, the list above will expand though.) Instead, the type should be taken as null, and the value consists of the entire link URI.

The <code>url</code> property is different from an identifier. Rather than helping readers '''identify''' the cited resource, it helps them '''find''' the resource. The <code>url</code> {{may}} be a link to, say, an Amazon page to buy the book.

When citing a web page (rather than, say, a book or journal), you {{should}} mark up the page's URL as <code>class="url identifier"</code> as the URL both identifies the resource and allows people to find it.

<code>url</code> 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.

== <code>pages</code> ==

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:

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

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:

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

<pre><nowiki><span class="pages">
  <span class="spage">146</span>&amp;ndash;<abbr class="epage" title="148">8</abbr>
</span></nowiki></pre>

Parsers {{must not}} assume that pages will be numerically labelled. For instance, many books contain sections with pages numbered in roman numerals. If the subproperties have not been explicitly used, parsers {{should not}} attempt to extract a start and end page from the <code>pages</code> property — it {{should}} be treated as unstructured text.

== <code>pub</code> ==

An hCard or plain text string for the book's publisher. As with the <code>au</code> property, an hCard is preferred. The place of publication {{should}} be encoded within this hCard using [[adr]] and appropriate subproperties, or the '''label''' property.

<pre><nowiki><span class="pub">Penguin Books, London</span></nowiki></pre>

<pre><nowiki><span class="pub vcard">
  <span class="fn org">Penguin Books</span>
  <span class="label">London</span>
</span></nowiki></pre>

<pre><nowiki><span class="pub vcard">
  <span class="fn org">Penguin Books</span>
  <span class="adr"><span class="locality">London</span></span>
</span></nowiki></pre>

In the case where the publisher is unknown, but the place of publication is known, <code>pub</code> {{should}} use an embedded [[adr]]:

<pre><nowiki><span class="pub adr">
  <span class="locality">London</span>
</span></nowiki></pre>

If citing a self-published resource, the <code>pub</code> and <code>au</code> properties may be on the same element:

<pre><nowiki><span class="au pub">Joe Bloggs</span></nowiki></pre>

<pre><nowiki><span class="au pub vcard">
  <span class="fn">Joe Bloggs</span>,
  <span class="adr"><span class="locality">Edinburgh</span></span>
</span></nowiki></pre>

== <code>stitle</code> ==

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:

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

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

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

= Examples =

== Citation in Running Text ==

<pre><nowiki><p>
  According to
  <cite class="h3988 mfo">
    <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></nowiki></pre>

== A Book in a Bibliography ==

<pre><nowiki>
<h2>Bibliography</h2>
<ul>
  <li>
    <cite class="h3988 mfo" id="ref-fpc">
      [<span class="identifier">FPC</span>]:
      <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></nowiki></pre>

Which might be cited in running text like:

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

Note the use of [[VoteLinks]] to indicate agreement with the cited book.

= References =

* <cite class="h3988 mfo" id="ref_kev-book"><span class="jtitle">OpenURL Framework Repository</span>: <span class="atitle">[http://alcme.oclc.org/openurl/servlet/OAIHandler/extension?verb=GetMetadata&metadataPrefix=mtx&identifier=info:ofi/fmt:kev:mtx:book KEV Format: Book]</span></cite>
* <cite class="h3988 mfo" id="ref_kev-journal"><span class="jtitle">OpenURL Framework Repository</span>: <span class="atitle">[http://alcme.oclc.org/openurl/servlet/OAIHandler/extension?verb=GetMetadata&metadataPrefix=mtx&identifier=info:ofi/fmt:kev:mtx:journal KEV Format: Journal]</span></cite>
* <cite class="h3988 mfo" id="ref_kev-dissertation"><span class="jtitle">OpenURL Framework Repository</span>: <span class="atitle">[http://alcme.oclc.org/openurl/servlet/OAIHandler/extension?verb=GetMetadata&metadataPrefix=mtx&identifier=info:ofi/fmt:kev:mtx:dissertation KEV Format: Dissertation]</span></cite>
* <cite class="h3988 mfo" id="ref_kev-patent"><span class="jtitle">OpenURL Framework Repository</span>: <span class="atitle">[http://alcme.oclc.org/openurl/servlet/OAIHandler/extension?verb=GetMetadata&metadataPrefix=mtx&identifier=info:ofi/fmt:kev:mtx:patent KEV Format: Patent]</span></cite>
* <cite class="h3988 mfo" id="ref_kev-dc"><span class="jtitle">OpenURL Framework Repository</span>: <span class="atitle">[http://alcme.oclc.org/openurl/servlet/OAIHandler/extension?verb=GetMetadata&metadataPrefix=mtx&identifier=info:ofi/fmt:kev:mtx:dc KEV Format: Dublin Core]</span></cite>
* <cite class="h3988 mfo" id="ref_ocoins-journal"><span class="jtitle">OCOinS.info</span>: <span class="atitle">[http://ocoins.info/cobg.html Brief guide to Implementing OpenURL 1.0 Context Object for Journal Articles]</span></cite>
* <cite class="h3988 mfo" id="ref_ocoins-book"><span class="jtitle">OCOinS.info</span>: <span class="atitle">[http://ocoins.info/cobgbook.html Brief guide to Implementing OpenURL 1.0 Context Object for Books]</span></cite>

= Related Pages =

{{citation-related-pages}}