relaton-bib 1.20.8 → 2.0.0

data/grammars/biblio-standoc.rng

@@ -1,27 +1,32 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<grammar xmlns="http://relaxng.org/ns/structure/1.0">
-  <!--
-    Add-ons to biblio.rnc for standoc model: defines the extension point BibDataExtensionType
-    of relaton
-    
-    Specialisations as for biblio.rnc. Extension point can be redefined completely for a flavour of standoc
-    (SDO); but other elements in Bibdata can only be extended (more specialised vocabularies for Bibdata)
-  -->
+<grammar xmlns:a="http://relaxng.org/ns/compatibility/annotations/1.0" xmlns="http://relaxng.org/ns/structure/1.0">
   <include href="biblio.rng">
+    <!-- ALERT: we cannot have comments on root element, as they intervene with https://github.com/metanorma/metanorma/issues/437 fix -->
+    <!--
+      Add-ons to biblio.rnc for standoc model: defines the extension point BibDataExtensionType
+      of relaton
+      
+      Specialisations as for biblio.rnc. Extension point can be redefined completely for a flavour of standoc
+      (SDO); but other elements in Bibdata can only be extended (more specialised vocabularies for Bibdata)
+    -->
     <define name="BibData">
+      <a:documentation>The bibliographic description of a standardisation document</a:documentation>
       <ref name="StandardBibliographicItem"/>
       <optional>
-        <ref name="ext"/>
+        <ref name="ext">
+          <a:documentation>The extension point of the bibliographic description of a standardisation document</a:documentation>
+        </ref>
       </optional>
     </define>
     <define name="docrelation">
+      <a:documentation>Update to StandardReducedBibliographicItem</a:documentation>
       <element name="relation">
         <attribute name="type">
           <ref name="DocRelationType"/>
         </attribute>
         <optional>
           <element name="description">
-            <ref name="FormattedString"/>
+            <ref name="LocalizedMarkedUpString"/>
           </element>
         </optional>
         <element name="bibitem">
@@ -47,34 +52,55 @@
     </define>
   </include>
   <define name="ext">
+    <a:documentation>The extension point of the bibliographic description of a standardisation document</a:documentation>
     <element name="ext">
       <ref name="BibDataExtensionType"/>
     </element>
   </define>
   <define name="BibDataExtensionType">
     <optional>
-      <attribute name="schema-version"/>
+      <attribute name="schema-version">
+        <a:documentation>The version of the flavour-specific schema that this extension point conforms to</a:documentation>
+      </attribute>
     </optional>
-    <ref name="doctype"/>
+    <ref name="doctype">
+      <a:documentation>Classification of the standardisation document that is treated as a distinct series by the
+standards defining organization, and that is rendered in a distinct manner</a:documentation>
+    </ref>
     <optional>
-      <ref name="docsubtype"/>
-    </optional>
-    <optional>
-      <ref name="editorialgroup"/>
+      <ref name="docsubtype">
+        <a:documentation>Subclass of the standardisation document, that is treated or processed differently
+from other documents in the same doctype</a:documentation>
+      </ref>
     </optional>
+    <ref name="flavor">
+      <a:documentation>Flavour of Metanorma used to process this document</a:documentation>
+    </ref>
     <zeroOrMore>
-      <ref name="ics"/>
+      <ref name="ics">
+        <a:documentation>Classification of the document contents taken from the International Classification of Standards</a:documentation>
+      </ref>
     </zeroOrMore>
     <zeroOrMore>
-      <ref name="structuredidentifier"/>
+      <ref name="structuredidentifier">
+        <a:documentation>Representation of the identifier for the standardisation document, giving its individual semantic components</a:documentation>
+      </ref>
     </zeroOrMore>
+    <ref name="DocumentImages">
+      <a:documentation>Coverpage and other images to be rendered with document</a:documentation>
+    </ref>
   </define>
   <define name="doctype">
+    <a:documentation>Classification of the standardisation document</a:documentation>
     <element name="doctype">
       <optional>
-        <attribute name="abbreviation"/>
+        <attribute name="abbreviation">
+          <a:documentation>Standard abbreviation for the doctype value used by the standards defining organization</a:documentation>
+        </attribute>
       </optional>
-      <ref name="DocumentType"/>
+      <ref name="DocumentType">
+        <a:documentation>Name of the doctype</a:documentation>
+      </ref>
     </element>
   </define>
   <define name="DocumentType">
@@ -88,120 +114,155 @@
   <define name="DocumentSubtype">
     <text/>
   </define>
-  <define name="editorialgroup">
-    <element name="editorialgroup">
-      <oneOrMore>
-        <ref name="technical-committee"/>
-      </oneOrMore>
-    </element>
-  </define>
-  <define name="technical-committee">
-    <element name="technical-committee">
-      <ref name="IsoWorkgroup"/>
+  <define name="flavor">
+    <element name="flavor">
+      <ref name="MetanormaFlavor"/>
     </element>
   </define>
-  <define name="IsoWorkgroup">
-    <optional>
-      <attribute name="number"/>
-    </optional>
-    <optional>
-      <attribute name="type"/>
-    </optional>
-    <optional>
-      <attribute name="identifier"/>
-    </optional>
-    <optional>
-      <attribute name="prefix"/>
-    </optional>
+  <define name="MetanormaFlavor">
+    <a:documentation>This is in fact an enum, as of this writing: standoc iso generic ietf ieee itu nist ogc csa cc iho ribose jis iec bsi bipm plateau.
+However we prefer not to hardcode it, given ongoing extension.</a:documentation>
     <text/>
   </define>
   <define name="ics">
+    <a:documentation>Classification taken from the International Classification of Standards. 
+ICS is defined by ISO here -- https://www.iso.org/publication/PUB100033.html</a:documentation>
     <element name="ics">
       <element name="code">
+        <a:documentation>Classification code taken from the ICS</a:documentation>
         <text/>
       </element>
       <optional>
         <element name="text">
+          <a:documentation>Text string associated with the classification code</a:documentation>
           <text/>
         </element>
       </optional>
     </element>
   </define>
   <define name="structuredidentifier">
+    <a:documentation>Representation of the identifier for a standardisation document, giving its individual semantic components</a:documentation>
     <element name="structuredidentifier">
       <optional>
-        <attribute name="type"/>
+        <attribute name="type">
+          <a:documentation>Representation in the identifier of the type of standard document, corresponds to bibitem/ext/doctype</a:documentation>
+        </attribute>
       </optional>
       <oneOrMore>
         <element name="agency">
+          <a:documentation>Representation in the identifier of the agency responsible for the standard document</a:documentation>
           <text/>
         </element>
       </oneOrMore>
       <optional>
         <element name="class">
+          <a:documentation>Representation in the identifier of the class of standard document (as a subclass of the document type),
+corresponds to bibitem/item/docsubtype</a:documentation>
           <text/>
         </element>
       </optional>
       <element name="docnumber">
+        <a:documentation>Representation in the identifier of the (typically numeric) component uniquely identifying the document
+or standard. If a document includes parts or supplements, the docnumber identifies the document as whole,
+and not those document components</a:documentation>
         <text/>
       </element>
       <optional>
         <element name="partnumber">
+          <a:documentation>Representation in the identifier of the document part, if this is a document part. May be compound</a:documentation>
           <text/>
         </element>
       </optional>
       <optional>
         <element name="edition">
+          <a:documentation>Representation in the identifier of the document edition, if this is a published document</a:documentation>
           <text/>
         </element>
       </optional>
       <optional>
         <element name="version">
+          <a:documentation>Representation in the identifier of the document version, which can include document drafts</a:documentation>
           <text/>
         </element>
       </optional>
       <optional>
         <element name="supplementtype">
+          <a:documentation>Representation in the identifier of the type of document supplement, if this is a document supplement</a:documentation>
           <text/>
         </element>
       </optional>
       <optional>
         <element name="supplementnumber">
+          <a:documentation>Representation in the identifier of the document supplement, if this is a document supplement</a:documentation>
           <text/>
         </element>
       </optional>
       <optional>
         <element name="amendment">
+          <a:documentation>Representation in the identifier of the document amendment, if this is a document amendment</a:documentation>
           <text/>
         </element>
       </optional>
       <optional>
         <element name="corrigendum">
+          <a:documentation>Representation in the identifier of the document corrigendum, if this is a document corrigendum</a:documentation>
           <text/>
         </element>
       </optional>
       <optional>
         <element name="language">
+          <a:documentation>Representation in the identifier of the language of the document</a:documentation>
           <text/>
         </element>
       </optional>
       <optional>
         <element name="year">
+          <a:documentation>Representation in the identifier of the year of publication or issuance of the document</a:documentation>
           <text/>
         </element>
       </optional>
     </element>
   </define>
+  <define name="DocumentImages">
+    <zeroOrMore>
+      <element name="coverpage-image">
+        <a:documentation>Images to be displayed on the coverpage of the document</a:documentation>
+        <ref name="image-no-id"/>
+      </element>
+    </zeroOrMore>
+    <zeroOrMore>
+      <element name="innercoverpage-image">
+        <a:documentation>Images to be displayed on the inner coverpage of the document</a:documentation>
+        <ref name="image-no-id"/>
+      </element>
+    </zeroOrMore>
+    <zeroOrMore>
+      <element name="tocside-image">
+        <a:documentation>Images to be displayed on the Table of Contents page of the document</a:documentation>
+        <ref name="image-no-id"/>
+      </element>
+    </zeroOrMore>
+    <zeroOrMore>
+      <element name="backpage-image">
+        <a:documentation>Images to be displayed on the backpage of the document</a:documentation>
+        <ref name="image-no-id"/>
+      </element>
+    </zeroOrMore>
+  </define>
   <define name="StandardBibliographicItem">
     <ref name="BibliographicItem"/>
     <zeroOrMore>
-      <ref name="amend"/>
+      <ref name="amend">
+        <a:documentation>Description of changes specific to this document</a:documentation>
+      </ref>
     </zeroOrMore>
   </define>
   <define name="StandardReducedBibliographicItem">
     <ref name="ReducedBibliographicItem"/>
     <zeroOrMore>
-      <ref name="amend"/>
+      <ref name="amend">
+        <a:documentation>Description of changes specific to this document</a:documentation>
+      </ref>
     </zeroOrMore>
   </define>
 </grammar>