citation-strawman-00

From Microformats Wiki
Jump to navigation Jump to search

Brian's citation straw format

Editor
Brian Suda

Reasoning

implied schema (examples)

+ publisher
+ language
+ description
+ title
+ creator
+ journal
+ volume
+ issue
+ page 
+ edition
+ identifier
+ tags
+ format
+ date published
+ copyright
- audience

implied schema (formats)

+ publisher
+ language
+ description
+ title
+ creator
+ volume
+ pages
+ edition
+ issue
+ identifier
+ tags
+ format
+ date published
+ date copyrighted
- subtitle
- image 
- excerpt
- index terms
- series title
- publication
- journal
- part (1 of X)

UNION of the two schemas

+ (PLUS) means common properties
- (MINUS) means unique to the schema


Working straw schema

This list records discussion about the common schema from above. The format is descriptive-name (optional-recommended-element 'class-name') (link to explanation).

If there is no explanation link, that field should be considered either obvious or up for debate. If you're not sure which, it's up for debate.

  • root element ('hcite') (explanation)
    • title ('title')
    • Author / Editor etc. ('creator')
    • Pages ('pages')
      • note: this can be any value
    • container ('container hcite')
    • Volume Number ('volume')
    • Edition ('edition')
    • Issue number ('issue')
    • Tags (href rel='tag')
    • Format ('format')
      • Note - this is unclear at present - does format mean 'type', as in 'book' vs. 'article'? --Mike 22:53, 16 Jan 2007 (PST)
    • date published ('date-published') (explanation)
    • date accessed ('date-accessed') (explanation)
    • publisher
    • language
      • Note - There are two uses for the language attribute (And therefore two language attributes should two be considered for inclusion in the schema). One value is the language the resource is written in (which the resource might polyglot work and therefore require multiple values in the attribute). The other attribute is the language which the resource is about. i.e. a Book written about German, written in English. This might be considered as language-subject and language-written. OLAC has recommended using the ISO 639-3 to Identify the languages used. Additionally, there is room here to describe the script used in a resource (script not encoding). Some languages print in more than one script, I know this is common in several South Asian Languages where there might be a romanized script and a Indic script. --HughP 12:44 1 Feb 2011 (CST)
    • Abstract / description ('description')
    • URI (href class='uri') (explanation)
    • identifier
      • an (not necessarily globally unique) identifier, such as a cite-key, pubmed ID number, or simply the reference number or string within a publication ([1] or [CLRS2001])

Notes about missing / changed fields in the schema

This section lists fields that are intentionally not included in the straw schema, or are not represented directly, and links to discussion about each.

Examples

Markup examples using the above format:

Book

This is Brian's original example


<ul class="bibliography">
	<li class="hcite" xml:lang="en-gb">
	
		<!-- publisher data as hCard--;
		<div class="publisher vcard">
			<span class="fn org">ABC Publishing Co.</span>
			<span class="country-name">United Kingdom</span>
			...
		</div>
		
		<!-- author(s) data as hCard -->
		<div class="creator vcard">
			<span class="fn n"><span class="given-name">John <span class="family-name">Doe</span></span>
			...
		</div>

		<!-- location data -->
		<span class="fn">Foobar!</span>
		<span class="description">World Class Book about foobar</span>
		<span class="volume">1</span>
		<span class="issue">1</span>
		<span class="edition">1</span>
		<span class="pages">1-10</span>
		<span class="format">article</span>
		
		<!-- differed to the UID debate -->
		<span class="identifier">12345678</span>
		
		<!-- keywords -->
		<a class="keyword" rel="tag" href="/tags/foo">foo</a>
		<span class="keyword">bar</span>
		
		<!-- date properties -->
		Published <abbr class="date-published" title="20060101">January 1st 1006</abbr>
		Copyright <abbr class="copyright" title="20060101">2006</abbr>
	</li>
	...
</ul>

<p class="hcite">Have you read <span class="title"><abbr title="book" class="format">Foo Bar</abbr></span>? 
It was written by <span class="author vcard"><span class="fn">John Doe</span></span>. 
It only came out a <abbr class="dtpublished" title="20060101">few months ago</abbr></p>

Note: the "format" property above is incorrect. Format would refer more the physical characteristics of an item, rather than its type or genre (e.g. "article", "book", etc.). I'd rather have the main class for the li be "article" in this context, than the fairly meaningless "citation." Of course, one could have both, which would be fine too. -- bruce

Note: Could we use ROLE from hCard to identify editors, translators, authors, etc? This was discussed on the mailing list and the idea was dropped [1]

Comments : singpolyma 08:03, 16 Jun 2006 (PDT) : keywords should be rel="tag", and probably also XOXO 1.0: Extensible Open XHTML Outlines (the same way the citation list is)

RCanine 11:55, 18 Dec 2006 (EST) :

  • Is there a reason not to re-use "published" from hAtom instead of inventing a new, basically equivalent term in "dtpublished"?
    • note - date-published was decided on for the field, example changed to reflect it --Mike 10:12, 30 Mar 2007 (PDT)
  • Missing a URL/URI/IRI/UID etc. field example (ISBN for Book).
  • Does the "copyright" class conflict with WHATWG's definition?
  • WRT Bruce's comment, I'm currently using class="article citation" for my writing, as it has the most flexibility with CSS styles for titles (e.g. Book titles .citation>.fn must be italicized, while article titles must not, their container should).
  • Speaking of containers, we need an "in" or "collection" field for journal articles or articles-in-books, or is that covered by "publisher"?

Citing Private Communication

Needs an example.

Citing Legal Cases

Needs an example. see Wikipedia example for inspiration.

Citing a Book

needs an example

Citing a journal article

From an old entry in PubMed - J Aersp Med. link

<span class="hcite">
  <span class="creator vcard"><span class="fn">R R Burton</span></span>,
  <span class="creator vcard"><span class="fn">S D Leverett</span></span>, and
  <span class="creator vcard"><span class="fn">E D Michaelson</span></span>

  <span class="title">Man at high sustained +Gz acceleration: a review.</span>
  In  <span class="container hcite">
    <abbr class="type" title="Journal">J.</abbr><abbr class="title" title="Aerospace medicine">Aersp. Med.</abbr>
    <span class="uri uid">urn:issn:0001-9402</span>
    <span class="volume">45</span>
    <span class="issue">10</span>
    <abbr class="date-published" title="101974">Oct, 1974</abbr>
  </span>, pages <span class="page">1115-36</span>.

</span>

Note, I'm not entirely sure about the issn urn here.

Citing a magazine article

needs an example

Citing a Patent

Drawn from this example from Wikipedia:

<li class="hcite"><a href="http://patft.uspto.gov/netacgi/nph-Parser?patentnumber=4,405,829" class="url" 
    title="http://patft.uspto.gov/netacgi/nph-Parser?patentnumber=4,405,829">
<span class="format">U.S. Patent</span> <span class="identifier">4,405,829</span></a>:
    <span class="description">The <a href="/wiki/RSA" title="RSA">RSA</a> patent, a famous software patent on the ground-breaking 
    and highly unobvious algorithm for public key encryption, widely used for secure communications 
    in many industries nowdays</span>
</li>

Citing a conference publication

Based on the conference publication reference example.

Changed Oct 06 to conform with Brian's format. --Mike 18:09, 12 Oct 2006 (PDT) (everything but the url class should be in line with that proposal)

L. Hochstein, J. Carver, F. Shull, S. Asgari, V. Basili, J. K. Hollingsworth, and M. Zelkowitz, “Hpc programmer productivity: A case study of novice hpc programmers,” in Proceedings of ACM/IEEE Supercomputing Conference, 2005.

<span class="hcite">
  <span class="creator vcard"><span class="fn">Lorin Hochstein</span>
  <span class="org"> University of Maryland, College Park </span></span>,
  <span class="creator vcard"><span class="fn"> Jeff Carver </span> 
  <span class="org"> Mississippi State University </span> </span>,
  <span class="creator vcard"><span class="fn"> Forrest Shull </span> 
  <span class="org"> Fraunhofer Center Maryland </span> </span>,
  <span class="creator vcard"><span class="fn"> Sima Asgari</span> 
  <span class="org"> University of Maryland, College Park </span> </span>,
  <span class="creator vcard"><span class="fn"> Victor Basili</span> 
  <span class="org"> Fraunhofer Center Maryland </span> </span>,
  <span class="creator vcard"><span class="fn"> Jeffrey K. Hollingsworth</span> 
  <span class="org"> University of Maryland, College Park </span> </span>, and 
  <span class="creator vcard"><span class="fn"> Marv Zelkowitz</span> 
  <span class="org"> University of Maryland, College Park </span> </span>,
  
  <a class="title url" href="http://dx.doi.org/10.1109/SC.2005.53">HPC Programmer Productivity: A Case Study of Novice HPC Programmers</a>. 
  (<span class="format">conference publication</span>)
  <span class="container hcite">
    <a class="title url" href="...">Proceedings of ACM/IEEE Supercomputing Conference</a>
    <abbr class="date-published" title="20051126T0000-0800">2005</abbr>
  </span>
  page <span class="pages">35</span>
  <span class="publisher vcard">
    <span class="fn">IEEE Computer Society
    </span>
    <span class="adr">
      <span class="locality">Washington</span>,
      <span class="region">DC</span>
    </span>
  </span>
  <a class="url eprint" href="http://portal.acm.org/...">PDF of full text from ACM</a>
  
  DOI: <a class="url uid" href="http://dx.doi.org/10.1109/SC.2005.53">10.1109/SC.2005.53</a>
  Tags: 
  <a class="keyword" rel="tag" href="results.cfm?query=genterm%3A%22Design%22 ...">Design</a>,
  <a class="keyword" rel="tag" href="results.cfm?query=genterm%3A%22Experimentation%22 ....">Experimentation</a>,
  <a class="keyword" rel="tag" href="results.cfm?query=genterm%3A%22Measurement%22...">Measurement</a>,
  <a class="keyword" rel="tag" href="results.cfm?query=genterm%3A%22Performance%22 ...">Performance</a>

  <span class="description">In developing High-Performance Computing (HPC) software, ....</span>
</span>


Note (From Discoleo, Sept. 06)

  • sometimes, the citation must include Town/Country and Precise Date/Date Range, e.g.
    • Gillespie SH, Dickens A. Variation in mutation rate of quinolone resistance in Streptococcus pneumoniae [abstract P06-17A]. In: Abstracts of the 3rd International Symposium on Pneumococci and Pneumococcal Disease (Anchorage, 5-9 May 2002).Washington, DC: American Society of Microbiology, 2002.
    • Bassetti, M.; Righi, E.; Rebesco, B.; Molinari, MP.; Costa, A.; Fasce, R.; Cruciani, M.; Bassetti, D.; Bobbio Pallavicini, F. 44th Annual Interscience Conference on Antimicrobial Agents and Chemotherapy (ICAAC). Washington, DC; 2004. Epidemiological trends in nosocomial candidemia in ICU: A five-year Italian perspective.
    • Peacock JE, Wade JC, Lazarus HM, et al. Ciprofloxacin/piperacillin vs. tobramycin/piperacillin as empiric therapy for fever in neutropenic cancer patients, a randomized, double-blind trial [abstract 373]. In: Program and abstracts of the 37th Interscience Conference on Antimicrob Agents and Chemotherapy (Toronto). Washington, DC: American Society for Microbiology, 1997.

Citing an external website

This is based on a formal citation of a website in the references section of a research paper, but could also be used for in-line links that had added information. Here's the original:

[25] David Stern, "eprint Moderator Model", http://www.library.yale.edu/scilib/modmodexplain.html (version dated Jan 25, 1999)

<cite class="hcite">
<a class="fn url" href="http://www.library.yale.edu/scilib/modmodexplain.html">eprint Moderator Model</a>
<span class="author vcard">
<a href="http://pantheon.yale.edu/~dstern/dsbio.html" class="url fn">David Stern</a>
</span>  
<abbr class="dtpublished" title="19990125T0000-0500">
    Jan 25, 1999
  </abbr>
</cite>

Discussion of Straw Format elements

This section is to provide explanations for posterity about the elements of the straw format, linking to discussions on the list and elsewhere if possible.

'hcite' as Root Element name

This discussion took place in January of 2007, with voting occurring on the mailing list.

It was decided to use 'hcite' as the root element's class-name for uniqueness and to reflect a trend in using 'h' to start microformat names.

The URI Element

It was decided to use URI for both http links to available copies or URNs. This encompasses URLs that link directly to online copies as well as through resolvers using URIs such as urn:isbn: 0521890012

See the discussion from November and December.

Date Fields

Brian's original straw format had three date fields, "accessed", "copyrighted", and "published". After examining the examples of usage on the web, it was clear that 'copyrighted' was not used in the examples we have. It was used once, but without a corresponding 'published' field (OCLC WorldCat), and it seems in that case to be used as an equivalent to 'published'.

I updated the straw citation to include only 'accessed' and 'published' on January 31. --Mike 00:26, 31 Jan 2007 (PST)

I've mentioned more than once that "date-published" is misleadingly specific; too much for real world citations. Consider that many books are published in the year preceding their copyright date, which is in fact the date used for citation. I'd prefer just "date" and "date-accessed" as a first cut. --Bruce 3 Feb 2007

See the discussion from the 'dates' thread on the list.

Container

Discussion about how to represent containing relationships is on the thread 'nesting container elements'

title

The problem of the use of the term "title" for the name of a citation item (or media item) is twofold:

  1. It's already used to mean "job title" in the context of microformats (hCard 1.0).
  2. The concept that it is being proposed to represent is the *name* of a citation item. "fn" already means the name of an item. we should not introduce a new term to mean the same thing as an existing term.

Tantek

fn

We should use "fn" for the name of a citation item rather than "title". Tantek

  • "fn" means the "name of a person, organisation or venue". Andy Mabbett 01:04, 4 Feb 2008
    • This is false. "fn" by itself simply means "formatted name". "fn" when used in an hCard 1.0 means "name of a person, organization or venue". "fn" when used in an hReview 0.4 (in progress) item means name of the item. Thus "fn" when used in a citation, or perhaps a citation item, would mean name of the cited item. Tantek
      • Its use in hReview does not accord with the defining instance in vCard's RFC2426 (which makes no mention of reviews). Andy Mabbett 11:28, 4 Feb 2008 (PST)
        • microformats attempt to re-use the vocabulary from existing standards. such re-use does not necessarily imply wholesale re-use of original context. To Do this should be clarified in the principles/process. Tantek 12:10, 4 Feb 2008 (PST)
  • Some problems with using fn for the names of other things are being discussed as at Jan-Feb 2008 (see [2] et seq). Any specific such problems should be extracted, summarized and moved here.

Related Pages