Commits

Anonymous committed 8ee023e Merge

Comments (0)

Files changed (1)

doc/convention.html

         <dd>Peter Murray-Rust, University of Cambridge</dd>
 
     </dl>
+    <h1>THIS DOCUMENT IS PRE-RELEASE AND SHOULD BE IGNORED</h1>
 
     <h2><a name="abstract" id="abstract"></a>Abstract</h2>
 
 
 <p class="toc">1. <a href="#introduction">Introduction</a><br/>
 &nbsp;&nbsp;&nbsp;&nbsp;1.1 <a href="#notational_conventions">Notational Conventions</a><br/>
-&nbsp;&nbsp;&nbsp;&nbsp;1.2 <a href="#namespaces">Namespaces</a><br/>
 2. <a href="#applying">Applying the citation convention</a><br/>
-3. <a href="#citation_element">Dictionary Element</a><br/>
 
-&nbsp;&nbsp;&nbsp;&nbsp;3.1 <a href="#citation_namespace">Namespace</a><br/>
-&nbsp;&nbsp;&nbsp;&nbsp;3.2 <a href="#citation-prefix">Prefix</a><br/>
-&nbsp;&nbsp;&nbsp;&nbsp;3.3 <a href="#citation-title">Title</a><br/>
 &nbsp;&nbsp;&nbsp;&nbsp;3.4 <a href="#citation-description">Description</a><br/>
 &nbsp;&nbsp;&nbsp;&nbsp;3.5<a href="#citation-entries">Entries</a><br/>
-4. <a href="#entry-elements">Entry Elements</a><br/>
 
-&nbsp;&nbsp;&nbsp;&nbsp;4.1 <a href="#entry-id">Id</a><br/>
-&nbsp;&nbsp;&nbsp;&nbsp;4.2 <a href="#entry-term">Term</a><br/>
-&nbsp;&nbsp;&nbsp;&nbsp;4.3 <a href="#entry-definition">Definition</a><br/>
-&nbsp;&nbsp;&nbsp;&nbsp;4.4 <a href="#entry-description">Description</a><br/>
-&nbsp;&nbsp;&nbsp;&nbsp;4.5 <a href="#entry-data-type">Data type</a><br/>
-&nbsp;&nbsp;&nbsp;&nbsp;4.6 <a href="#entry-unit-type">Unit type</a><br/>
+4. <a href="#entry-elements">Occurrence in ScHTML files</a><br/>
 
-&nbsp;&nbsp;&nbsp;&nbsp;4.7 <a href="#entry-default-unit">Default units</a><br/>
-5. <a href="#example">Example Dictionary</a></p>
+&nbsp;&nbsp;&nbsp;&nbsp;4.1 <a href="#entry-id">Preprocessed document</a><br/>
+&nbsp;&nbsp;&nbsp;&nbsp;4.2 <a href="#entry-term">Postprocessed document</a><br/>
+
+5. <a href="#example">Example Citation</a></p>
 <h2>Appendices</h2>
 <p>A. <a href="#refs">References</a><br/>
 B. <a href="#acks">Acknowledgements</a></p>
 
 <h1><a name="introduction">1.</a> Introduction</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>There are two main use cases for citing things:
-<ol>
-<li>. where we are working in research communities where the default is online, we should be able to clearly cite those online citation items (e.g. DOI).</li>
-<li>. where resources are not online and are not citable via an existing URI, therefore they will need to embed the bibliography of the citation themselves.</li>
-</ol>
-
-
-
-<h1><a name="example">5.</a> Example Citation in ?? format</h1>
-
-<div class="good">
-<pre>
-@article{Domenicano:a22144,
-author = "Domenicano, A. and  Murray-Rust, P. and Vaciago, A.",
-title =  "{Molecular geometry of substituted benzene derivatives.
-IV. Analysis of  variance in monosubstituted benzene rings}",
-journal = "Acta Crystallographica  Section B",
-year = "1983",
-volume = "39",
-number = "4",
-pages = "457--468",
-month = "Aug",
-doi = {10.1107/S0108768183002736},
-url = {http://dx.doi.org/10.1107/S0108768183002736},
-}
-</pre>
-</div>
-
-
-
-
-
 <h2><a name="notational_conventions">1.1</a> Notational Conventions</h2>
 
 <p>
 
 <p>The use of fonts is as follows:</p>
 <ul>
-    <li>Schema terms, including elements and attributes, are written in <code>this font</code>.</li>
+    <li>Convention terms, including URIs, elements and attributes, are written in <code>this font</code>.</li>
 </ul>
 
-<h2><a name="namespaces">1.2</a> Namespaces</h2>
 
-<p>This specification uses the following namespaces and prefixes to indicate those namespaces:</p>
+<h1><a name="introduction">1.2</a> Overview</h1>
 
-<table class="namespace-table" summary="Namespaces table">
-    <tr>
-        <th>Prefix</th>
-        <th>Namespace URI</th>
-        <th>Description</th>
-    </tr>
+<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>
 
-    <tr>
-        <td><code>cml</code></td>
-        <td><code>http://www.xml-cml.org/schema</code></td>
-        <td>Chemical Markup Language elements</td>
-    </tr>
-    <tr>
-        <td><code>convention</code></td>
+<p>There are two main use cases for citing things:
+<ol>
+<li>. where we are working in research communities where the default is online, we should be able to clearly cite those online citation items (e.g. DOI).</li>
+<li>. where resources are not online and are not citable via an existing URI, therefore they will need to embed the bibliography of the citation themselves.</li>
+</ol>
+</p>
 
-        <td><code>http://www.xml-cml.org/convention/</code></td>
-        <td>Standard Chemical Markup Language convention namespace</td>
-    </tr>
-    <tr>
-        <td><code>xhtml</code></td>
-        <td><code>http://www.w3.org/1999/xhtml</code></td>
-        <td>XHTML</td>
 
-    </tr>
-</table>
+<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>
+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>
+
+<div class="good">
+<pre>
+
+    &lt;div class="bibliography">
+
+      &lt;div about="http://dx.doi.org/10.1107/S0108768183002736">
+      &lt;span property="doi" content="http://dx.doi.org/10.1107/S0108768183002736">&lt;/span>
+      &lt;span property="http://purl.org/net/biblio#itemType" content="journalArticle" >&lt;/span>
+      &lt;span property="dc:title">Molecular geometry of substituted benzene derivatives.
+      IV. Analysis  of variance in monosubstituted benzene rings&lt;/span>
+      &lt;/div>
+
+    &lt;/div>
+</pre>
+</div>
+
+<br/>
+<div class="good">
+<pre>
+@article{Domenicano:a22144,
+author = "Domenicano, A. and  Murray-Rust, P. and Vaciago, A.",
+title =  "{Molecular geometry of substituted benzene derivatives.
+IV. Analysis of  variance in monosubstituted benzene rings}",
+journal = "Acta Crystallographica  Section B",
+year = "1983",
+volume = "39",
+number = "4",
+pages = "457--468",
+month = "Aug",
+doi = {10.1107/S0108768183002736},
+url = {http://dx.doi.org/10.1107/S0108768183002736},
+}
+</pre>
+</div>
+
+<p>which is the  same (in BibTeX format) as:</p>
+
+<div class="good">
+<pre>
+Acta Cryst. (1983). B39,  457-468    [  doi:10.1107/S0108768183002736  ]
+Molecular  geometry of substituted benzene derivatives. IV.
+Analysis  of variance  in monosubstituted benzene rings  A. Domenicano, P. Murray-Rust and
+A.  Vaciago
+</pre>
+</div>
+
+
 
 
 <h1><a name="applying">2.</a> Applying the citation convention</a></h1>
 
 <p>
-    The citation convention MUST be specified using the <code>convention</code>
-    attribute on either a <code>cml</code> or a <code>citation</code> element.
-    If the convention is specified on a <code>cml</code> element then that element
-    MUST contain a single child element in the <code>http://www.xml-cml.org/schema</code>
+    The citation convention MUST be specified using the <code>rel="http://www.scholarlyhtml.org/"</code>
+    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.
 
-    namespace, which MUST be a <code>citation</code> element.
-</p>
-
-<h1><a name="citation_element">3.</a> Dictionary Element</h1>
-
-<h2><a name="citation_namespace">3.1</a> Namespace</h2>
-
-<p>
-    The <code>citation</code> element MUST have a <code>namespace</code> attribute,
-    the value of which MUST be a valid URI defining the the scope within which the
-    entry terms are unique.
-    The citation's namespace URI SHOULD resolve to a representation of the citation.
-    The citation's namespace URI SHOULD end with either a '/' character or a '#' character
-    so that terms may be referenced by appending them to the URI.
-</p>
-
-
-<h2><a name="citation-prefix">3.2</a> Prefix</h2>
-
-<p>
-    The <code>citation</code> element SHOULD have a <code>citationPrefix</code>
-    attribute specifying the default prefix to use when referencing citation entries.
-    The <code>citationPrefix</code> MUST be a valid XML QName prefix, and SHOULD be
-    unique within the CML domain.
-</p>
-
-
-<h2><a name="citation-title">3.3</a> Title</h2>
-
-<p>
-    The <code>citation</code> element SHOULD have a <code>title</code>
-    attribute intended for human-readability.
-</p>
-
-
-<h2><a name="citation-description">3.4</a> Description</h2>
-
-<p>
-    The <code>citation</code> element SHOULD have a single <code>description</code>
-    child element, the contents of which provide a human-readable description of the
-    domain of the citation.
-    The <code>description</code> element MUST contain one or more child elements in the
-    <code>http://www.w3.org/1999/xhtml</code> namespace.
-    The <code>description</code> element MUST NOT contain any child elements not in
-    the <code>http://www.w3.org/1999/xhtml</code> namespace.
 
 </p>
 
 
-<h2><a name="citation-entries">3.5</a> Entries</h2>
-
-<p>
-    The <code>citation</code> element MUST contain one ore more child <code>entry</code>
-    elements, and MUST not contain any other child elements from the
-    <code>http://www.xml-cml.org/schema</code> namespace.
-
-</p>
-
-
-<h1><a name="entry-elements">4.</a> Entry Elements</h1>
-
-<h2><a name="entry-id">4.1</a> ID</h2>
-
-<p>
-    An <code>entry</code> element MUST have an <code>id</code> attribute, the
-    value of which MUST be unique within the scope of the citation.
-
-</p>
-<p>
-    The value of the <code>id</code> attribute MUST start with a letter, and
-    MUST only contain letters, numbers, dot, hyphen or underscore.
-</p>
-
-<table>
-    <tr>
-        <td><code>IdStartChar</code></td>
-        <td>::=</td>
-
-        <td><code>[A-Z] | [a-z]</code></td>
-    </tr>
-    <tr>
-        <td><code>IdChar</code></td>
-        <td>::=</td>
-        <td><code>IdStartChar | [0-9] | "." | "-" | "_"</code></td>
-    </tr>
-
-    <tr>
-        <td><code>Id</code></td>
-        <td>::=</td>
-        <td><code>IdStartChar (IdChar)*</code></td>
-    </tr>
-</table>
-
-<h2><a name="entry-term">4.2</a> Term</h2>
-
-<p>
-    An <code>entry</code> element MUST have a <code>term</code> attribute, the
-    value of which provides a unique nounal phrase linguistically identifying
-    the subject of the entry.
-</p>
-<p>
-    The value of the <code>term</code> attribute MAY contain any valid unicode
-    character, however it is RECOMMENDED that any character from outside of
-    the ASCII subset (codepoints 32-127) is represented using an entity reference.
-
-</p>
-
-
-<h2><a name="entry-definition">4.3</a> Definition</h2>
-
-<p>
-    An <code>entry</code> element MUST contain a single <code>definition</code>
-    child element, the content of which provides a nounal phrase defining of the
-    subject of the entry more verbosely than the term.
-
-</p>
-<p>
-    The <code>definition</code> element MUST contain one or more child elements in the
-    <code>http://www.w3.org/1999/xhtml</code> namespace.
-    The <code>definition</code> element MUST NOT contain any child elements not in
-    the <code>http://www.w3.org/1999/xhtml</code> namespace.
-</p>
-
-
-<h2><a name="entry-description">4.4</a> Description</h2>
-
-<p>
-    An <code>entry</code> element MAY have a single <code>description</code>
-    child element, the content of which provides further information regarding
-    the term, including, but not limited to: examples, human-readable semantics
-    and hyperlinks to other useful resources.
-
-</p>
-<p>
-    The <code>description</code> element MUST contain one or more child elements in the
-    <code>http://www.w3.org/1999/xhtml</code> namespace.
-    The <code>description</code> element MUST NOT contain any child elements not in
-    the <code>http://www.w3.org/1999/xhtml</code> namespace.
-</p>
-
-
-<h2><a name="entry-data-type">4.5</a> Data type</h2>
-
-<p>
-    When applicable to the concept defined, an <code>entry</code> SHOULD have
-    <code>dataType</code> attribute, the value of which is a QName
-    referencing the data type of value defined using the <code>entry</code>.
-
-</p>
-
-<h3>Common data types:</h3>
-<ul>
-    <li><code>xsd:string</code></li>
-    <li><code>xsd:double</code></li>
-    <li><code>xsd:integer</code></li>
-    <li><code>xsd:boolean</code></li>
-
-</ul>
-
-
-<h2><a name="entry-unit-type">4.6</a> Unit type</h2>
-
-<p>
-    When applicable to the concept defined, an <code>entry</code> SHOULD have
-    a <code>unitType</code> attribute, the value of which is a QName
-    referencing the unit type (e.g. temperature) of any value defined using
-    the <code>entry</code>.
-
-</p>
-
-
-<h2><a name="entry-default-unit">4.7</a> Default units</h2>
-
-<p>
-    When applicable to the concept defined, an <code>entry</code> SHOULD have
-    a <code>units</code> attribute, the value of which is a QName
-    referencing the default units (e.g. Kelvin) of any value defined using the
-    <code>entry</code>.
-
-</p>
 
 
 <h1><a name="refs">A.</a> References</h1>
         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>