Languedoc schema massaging, Makefile fixing

git-svn-id: https://slps.svn.sourceforge.net/svnroot/slps@654 ab42f6e0-554d-0410-b580-99e487e6eeb2
grammarware · Jun 6, 2009 · 126a469 · 126a469
1 parent fd61402
commit 126a469
Show file tree

Hide file tree

Showing 11 changed files with 226 additions and 53 deletions.
diff --git a/shared/python/xldfCommands.py b/shared/python/xldfCommands.py
@@ -270,7 +270,7 @@ def xldf_add_subsection(localpath,cmd,tree):
   tree.findall('//frontMatter')[0].append(s)
   print '[XLDF] add-subsection (',s.tag,', front matter, ...)'
   success = True
- elif s.tag in ('purpose','description','location','considerations','defaults','normative','note','example','informative'):
+ elif s.tag in ('synopsis','description','syntax','constraints','references','relationship','semantics','rationale','example','update','default','list','value','section'):
   found = findnode(tree,cmd.findtext('to'))
   if found:
    found.append(s)

diff --git a/shared/python/xsd2ldf.py b/shared/python/xsd2ldf.py
@@ -92,6 +92,8 @@ def main(xsdfile,bgffile,ldffile):
  for p in stree.findall('/'+slpsns.xsd_('annotation')+'/'+slpsns.xsd_('documentation'))[1:]:
   pel = ET.SubElement(el,'text')
   pel.text = p.text
+ if not el.findall('*'):
+  ET.SubElement(el,'empty')
 
  if stree.findall('/'+slpsns.xsd_('import')):
   el = ET.SubElement(section,'normativeReferences')

diff --git a/shared/xsd/ldf.xsd b/shared/xsd/ldf.xsd
@@ -532,7 +532,7 @@
           </xsd:documentation>
         </xsd:annotation>
       </xsd:element>
-      <xsd:element name="relationship" type="ldf:listOfInternalLinks">
+      <xsd:element name="references" type="ldf:listOfInternalLinks">
         <xsd:annotation>
           <xsd:documentation>
             Hardbound standards have been trying to be more hypertext
@@ -543,40 +543,59 @@
           </xsd:documentation>
         </xsd:annotation>
       </xsd:element>
-      <!-- <xsd:group ref="ldf:top-section"/> -->
-      <xsd:element name="subtopic" type="ldf:structuredSection">
+      <xsd:element name="section" type="ldf:simpleSection">
         <xsd:annotation>
           <xsd:documentation>
-            In big documents it is not uncommon to find one topic divided into
-            several subtopics, each one dedicated to a separate issue and each one
-            structured in the same way its parent section is.
+            Any other type of normative or informative section.
           </xsd:documentation>
         </xsd:annotation>
       </xsd:element>
-      <xsd:element name="clause" type="ldf:simpleSection">
+      <!-- <xsd:group ref="ldf:top-section"/> -->
+      <xsd:element name="subtopic" type="ldf:structuredSection">
         <xsd:annotation>
           <xsd:documentation>
+            In big documents it is not uncommon to find one topic divided into
+            several subtopics, each one dedicated to a separate issue and each one
+            structured in the same way its parent section is.
             DSLs and 4GLs specification authors often find it easier to lay out
             different clauses of one language construct in different sections.
+            When the language has a lof of parametrised constructs, it makes sense
+            to dedicate a special subsection for each field.
+            Parameters, types, methods, operations, participants---whatever categories
+            inspire these subtopics, each of them is a fully structured section in itself.
           </xsd:documentation>
         </xsd:annotation>
       </xsd:element>
-      <xsd:element name="field" type="ldf:simpleSection">
+      <xsd:element name="value">
         <xsd:annotation>
           <xsd:documentation>
-            When the language has a lof of parametrised constructs, it makes sense
-            to dedicate a special subsection for each field.
+            A singled named value can be bound to a language document section: it can be
+            a type of a parameter that is being described here, or an alternative name,
+            or a superclass, or anything else that is atomic and non-structured.
           </xsd:documentation>
         </xsd:annotation>
+        <xsd:complexType>
+          <xsd:sequence>
+            <xsd:element name="key" type="xsd:string"/>
+            <xsd:element name="data" type="xsd:string"/>
+          </xsd:sequence>
+        </xsd:complexType>
       </xsd:element>
     </xsd:choice>
   </xsd:group>
 
   <!-- tokens -->
 
   <xsd:group name="normative">
+    <xsd:annotation>
+      <xsd:documentation>
+        Normative sections form the core of the language standard: for each core section they belong to,
+        they define the purpose of the language construct, provide a description, some syntax definition,
+        list use constraints and other semantic details, etc.
+      </xsd:documentation>
+    </xsd:annotation>
     <xsd:choice>
-      <xsd:element name="purpose" type="ldf:simpleSection">
+      <xsd:element name="synopsis" type="ldf:simpleSection">
         <xsd:annotation>
           <xsd:documentation>
             A separate subsection named `purpose' is only encountered in some 4GL
@@ -590,28 +609,51 @@
         <xsd:annotation>
           <xsd:documentation>
             Description is the core of the parent section, containing the main details about the
-            defined topic.
+            defined topic, information about its usage, motivation behind its design.
           </xsd:documentation>
         </xsd:annotation>
       </xsd:element>
-      <xsd:element name="location" type="ldf:simpleSection">
+      <xsd:element name="syntax">
         <xsd:annotation>
           <xsd:documentation>
-            Location section describes the context in which the introduced language construct
-            can be encountered and in which it should or should not be used.
+            Syntax sections consist of one or more BGF productions.
           </xsd:documentation>
         </xsd:annotation>
+        <xsd:complexType>
+          <xsd:sequence>
+            <xsd:element ref="bgf:production" maxOccurs="unbounded"/>
+          </xsd:sequence>
+        </xsd:complexType>
       </xsd:element>
-      <xsd:element name="considerations" type="ldf:simpleSection">
+      <xsd:element name="constraints" type="ldf:simpleSection">
         <xsd:annotation>
           <xsd:documentation>
-            A section on considerations usually lists some narrow places of
-            non-obvious usage, implementation details, incompatibility issues,
-            coding standards, common programming practices, etc.
+            This section can list requirements needed for using a specific language construct,
+            applicability constraints and other restrictions.
+          </xsd:documentation>
+        </xsd:annotation>
+      </xsd:element>
+      <xsd:element name="relationship" type="ldf:simpleSection">
+        <xsd:annotation>
+          <xsd:documentation>
+            Related language constructs can be named and referenced here.
+            It is not a simple list of references, but rather a comprehensive
+            overview on the kind of consequences other parts of the language
+            can bear if this one is used.
+          </xsd:documentation>
+        </xsd:annotation>
+      </xsd:element>
+      <xsd:element name="semantics" type="ldf:simpleSection">
+        <xsd:annotation>
+          <xsd:documentation>
+            A section on semantics explains in plain English, if no other specific formalism
+            is used, how exactly the language construct works, what happens inside the system when
+            it is utilised. It also describes the context in which the introduced language construct
+            can be encountered and in which it should or should not be used.
           </xsd:documentation>
         </xsd:annotation>
       </xsd:element>
-      <xsd:element name="defaults" type="ldf:simpleSection">
+      <xsd:element name="default" type="ldf:simpleSection">
         <xsd:annotation>
           <xsd:documentation>
             It is quite common in the sections that describe an optional parameter
@@ -620,23 +662,33 @@
           </xsd:documentation>
         </xsd:annotation>
       </xsd:element>
-      <!-- none of the above -->
+      <!-- none of the above 
       <xsd:element name="normative" type="ldf:simpleSection">
         <xsd:annotation>
           <xsd:documentation>
             Any other type of normative section.
           </xsd:documentation>
         </xsd:annotation>
-      </xsd:element>
+      </xsd:element>-->
     </xsd:choice>
   </xsd:group>
 
   <xsd:group name="informative">
+    <xsd:annotation>
+      <xsd:documentation>
+        Unlike normative sections that impose some conformance constraints that need
+        to be satisfied by a language processor to claim compatibility with the standard,
+        the informative sections are only presented to provide some additional information
+        to the reader.
+      </xsd:documentation>
+    </xsd:annotation>
     <xsd:choice>
-      <xsd:element name="note" type="ldf:simpleSection">
+      <xsd:element name="rationale" type="ldf:simpleSection">
         <xsd:annotation>
           <xsd:documentation>
-            A note (called `rationale' in ANSI Smalltalk standard) is a
+            A rationale or a note usually lists some narrow places of
+            non-obvious usage, implementation details, incompatibility issues,
+            coding standards, common programming practices, etc. It is a
             subsection of secondary importance, contributing some information
             on a minor point that can still be interesting and useful for some
             readers. Notes usually tell the readers how to use certain language
@@ -652,14 +704,21 @@
           </xsd:documentation>
         </xsd:annotation>
       </xsd:element>
-      <!-- none of the above -->
-      <xsd:element name="informative" type="ldf:simpleSection">
+      <xsd:element name="update" type="ldf:simpleSection">
         <xsd:annotation>
           <xsd:documentation>
-            Any other type of informative section.
+            It is quite uncommon practice, but some standardisation bodies really
+            put the information about language evolution directly into each section
+            that changed since the last public version of the language document.
+          </xsd:documentation>
+          <xsd:documentation>
+            If this is done consistently and carefully, it is possible to generate
+            the global `What's new' section automatically.
           </xsd:documentation>
         </xsd:annotation>
       </xsd:element>
+      <!-- none of the above -->
+
     </xsd:choice>
   </xsd:group>
 

diff --git a/topics/languedoc/bgf/Makefile b/topics/languedoc/bgf/Makefile
@@ -1,4 +1,4 @@
-validator = ../../shared/tools/checkxml
+validator = ../../../shared/tools/checkxml
 
 build: tex
 	pdflatex -interaction=batchmode bgf

diff --git a/topics/languedoc/lcf/Makefile b/topics/languedoc/lcf/Makefile
@@ -1,4 +1,4 @@
-validator = ../../shared/tools/checkxml
+validator = ../../../shared/tools/checkxml
 
 build: tex
 	pdflatex -interaction=batchmode lcf