Commits

petermr  committed 8979865

first pass at documentation

  • Participants
  • Parent commits 4ed5f8f

Comments (0)

Files changed (1)

File doc/convention.html

 
 <hr />
 
+<h1><a name="introduction">1.</a> Introduction</h1>
+
 <h2><a name="notational_conventions">1.1</a> Notational Conventions</h2>
 
 <p>
 </ul>
 
 
-<h1><a name="introduction">1.</a> Introduction</h1>
+<h1><a name="introduction">1.2</a> Overview</h1>
 
-<p>Citations are universal throughout scholarly endeavour and this convention describes the components
-of a citation, their role and the aggregation into a list of citations (reference list).</p>
+<p>"Citations" or "References" are universal throughout scholarly endeavour and this convention describes the components of a citation, their role and the aggregation into a list of citations (reference list).</p>
 
 <p>There are two main use cases for citing things:
 <ol>
 </p>
 
 
-<h1><a name="example">5.</a> Citation Infrastructure</h1>
+<h1><a name="example">2.</a> Citation Terminology and Infrastructure</h1>
+<p>Terms describing bibliography, bibliographic records, bibliographic metadata, citations, citaions lists etc. are used loosely. We define the components of ScholarlyHTML citation convention below</p>
+
+<p> We are informed by the the BiRO ontology [3] from SPAR has a series of terms which are appropriate to describe elements of the bibiliography:
+
+
+<h2>2.1 Bibliographic Record</h2>
+
+<p>IRI: <a href="http://purl.org/spar/biro/BibliographicRecord">http://purl.org/spar/biro/BibliographicRecord</a></p>
+
+<p>A record that uniquely references a particular publication (or a work in preparation for publication). Each bibliographic record is a set of entities describing aspects of the referenced work, for example authors, title, journal, publication year, DOI, ISSN, publisher and copyright information. The FRBR expression of a bibliographic record is a bibliographic reference, which usually contains only a sub-set of these entities, ordered in a particular way that corresponds to the house style of the publication in which it occurs.</p>
+
+<p>PMR: Where this object is used to manage an object in a bibliographic collection (e.g. in a library catalogue) it may be referred to as a Bibliographic Entry</p>
+
+<h2>2.2 Reference List:</h2>
+
+<p>IRI: <a href="http://purl.org/spar/biro/ReferenceList">http://purl.org/spar/biro/ReferenceList</a></p>
+
+<p>A list used to describe the bibliography of a research paper, a journal article, a book, a book chapter or similar publication.</p>
+
+<p>PMR: a typical referenceList is the list of references at the end of the discourse in the article. It may be headed by strings such as "References", "Bibliography" or "Citations".We avoid the term bibliography. In many cases the elements of the list are pointed to by referencePointers in the text or other document components. In others there are no pointers and the reference list cannot be mapped to the text.</p>
+
+
+<h2>2.3 Bibliographic List</h2>
+
+<p>IRI: <a href="http://purl.org/spar/biro/ReferenceList">http://purl.org/spar/biro/ReferenceList</a>
+or <a href="http://purl.org/spar/biro/BibliographicList">http://purl.org/spar/biro/BibliographicList</a></p>
+
+A list used to describe the bibliography of a research paper, a journal article, a book, a book chapter or similar publication.
+Bibliographic entry:
+http://purl.org/spar/biro/BibliographicRecord
+
+<h2>2.4 Bibliographic Reference</h2>
+
+<p>IRI: http://purl.org/spar/biro/BibliographicReference</p>
+
+<p>An expression of a bibliographic record in a specific format, that references a particular publication (or a work in preparation for publication). Each bibliographic reference is a list of items containing entities that describe aspects of the referenced work - for example authors, title, journal, publication year - selected from the bibliographic record.</p>
+http://purl.org/spar/biro/BibliographicRecord
+
+
+<h2>2.5 ReferencePointer [PMR]</h2>
+<p>
+Text and other document conmponents often contain pointers to Bibliographic References. These are frequently given abbreviated or symbolic forms
+<ol>
+<li>Abbreviated author+year <i>abbreviatedAuthorReference</i>
+
+<p>The crystal was red [Murr09]</p></li>
+<li>Number (bold or superscript) <i>numberReference</i>
+<p>The crystal was red <sup>23</sup></p></li>
+</li>
+<li>Thumbnail or other small image "thumbnailReference"
+<p>The crystal was red <img src="arrow.jpg" width="20" height="15"/></p>
+</li>
+</ol>
+The pointer could be dereferenced by replacing it with the complete bibliographic reference without changing the semantics of the document.
+</p>
+
+
+<h2>Bibliography</h2>
+<p>The term <i>"bibliography"</i> is used generally in a wide variety of ways and should be avoided. It is often used as a synonym for ReferenceList.
+</p>
+
 <h2>Citation</h2>
 <p>
-A citation is a reference to a defined scholarly object. A simple citation is the address of the object (e.g. URI) or the names of objects defining the object (authors, addresses, dates, book/journal etc.)
-</p>
-<h2>CitationReference</h2>
-<p>
-Citations are frequently given abbreviated or symbolic forms
-<ol>
-<li>Abbreviated author+year [Murr09] "abbreviatedAuthorReference"</li>
-<li>Number (bold or superscript) "numberReference"</li>
-<li>Thumbnail e.g. arrow "thumbnailReference</li>
-</ol>
+PMR: A citation is a reference to a defined scholarly object and here is synonymous with BibliographicReference.
 </p>
 
 <h1><a name="example">5.</a> Example Citation format</h1>
 </pre>
 </div>
 
-
+<br/>
 <div class="good">
 <pre>
 @article{Domenicano:a22144,
 </pre>
 </div>
 
-which is the  same (in BibTeX format) as:
+<p>which is the  same (in BibTeX format) as:</p>
 
 <div class="good">
 <pre>
 
 <p>
     The citation convention MUST be specified using the <code>rel="http://www.scholarlyhtml.org/"</code>
-    attribute on a <code>span</code> element.
+    attribute on a <code>span</code> element. This <code>span</code> object identifies a span of text within the document which is the anchor of the citationReference. The text MAY be destroyed by conversion to postProcessed citation ScHTML and should have no semantic value.
+
 
 </p>
 
         26 October 2008. This version is http://www.w3.org/TR/2008/REC-xml-20081126. <a href="http://www.w3.org/TR/REC-xml">latest version of XML</a> is available at http://www.w3.org/TR/REC-xml.
     </dd>
 
+http://speroni.web.cs.unibo.it/cgi-bin/lode/req.py?req=http:/purl.org/spar/biro
+
 </dl>