the last bit of Languedoc for a while

git-svn-id: https://slps.svn.sourceforge.net/svnroot/slps@645 ab42f6e0-554d-0410-b580-99e487e6eeb2

shared/tools/ldinc

@@ -16,9 +16,13 @@ elif [ ! -d ${SLPS}/topics/languedoc/$1 ]; then
 	echo "Oops: directory $1 not found."
 	exit 1
 else
-	${SLPS}/shared/tools/xsd2ldf ${SLPS}/shared/xsd/$1.xsd $1.ldf
+	if [ -r ${SLPS}/topics/languedoc/$1/prepare.xbgf ]; then
+		${SLPS}/shared/tools/xsd2ldf ${SLPS}/shared/xsd/$1.xsd $1.ldf ${SLPS}/topics/languedoc/$1/prepare.xbgf
+	else
+		${SLPS}/shared/tools/xsd2ldf ${SLPS}/shared/xsd/$1.xsd $1.ldf
+	fi
 	${SLPS}/shared/tools/xldf ${SLPS}/topics/languedoc/$1/$1.xldf $1.ldf $1.ready.ldf
-	xsltproc ${SLPS}/shared/xsl/ldf2tex.xslt $1.ready.ldf | python ${SLPS}/shared/python/pp_pp.py 70 > $1.not.tex
+	xsltproc ${SLPS}/shared/xsl/ldf2tex.xslt $1.ready.ldf | python ${SLPS}/shared/python/pp_pp.py 69 > $1.not.tex
 	cat $1.not.tex | grep -v 'END_CONTENT' | grep -A 10000 $2 > $1.tex
 	rm -f $1.not.tex $1.ready.ldf $1.ldf xldf-tmp* printed_for_xldf.tmp
 fi

shared/xsd/xldf.xsd

@@ -30,8 +30,8 @@
       <xsd:documentation>
         XLDF transformation suite does not include any sophisticated grammar
         manipulations, in that sense it complements XBGF rather than extends it.
-        All grammar transformations are supposed to be performed prior to
-        language document transformations.
+        All grammar transformations are supposed to be be handled by XBGF either
+        prior to language document transformations or as a part of them.
       </xsd:documentation>
     </xsd:annotation>
     <xsd:choice>
@@ -56,7 +56,7 @@
   <xsd:element name="add-figure">
     <xsd:annotation>
       <xsd:documentation>
-        TBD
+        Adds a figure to the designated section or subsection.
       </xsd:documentation>
     </xsd:annotation>
     <xsd:complexType>
@@ -70,7 +70,10 @@
   <xsd:element name="add-section">
     <xsd:annotation>
       <xsd:documentation>
-        TBD
+        Completes the language document with a top-level section.
+        The target is unspecified because it is possible for the transformation engine
+        to decide it automatically (i.e., lexical sections go to the lexical part,
+        core sections to the core, etc).
       </xsd:documentation>
     </xsd:annotation>
     <xsd:complexType>
@@ -87,7 +90,9 @@
   <xsd:element name="add-subsection">
     <xsd:annotation>
       <xsd:documentation>
-        TBD
+        Adds an inner section to the document. All front matter sections go
+        automatically to the front matter, otherwise a target needs to be
+        specified.
       </xsd:documentation>
     </xsd:annotation>
     <xsd:complexType>
@@ -108,7 +113,7 @@
   <xsd:element name="append">
     <xsd:annotation>
       <xsd:documentation>
-        TBD
+        Adds more content to the existing section or subsection.
       </xsd:documentation>
     </xsd:annotation>
     <xsd:complexType>
@@ -122,7 +127,8 @@
   <xsd:element name="combine">
     <xsd:annotation>
       <xsd:documentation>
-        TBD
+        Reorganises all the content from one section or subsection to be merged with
+        another section or subsection.
       </xsd:documentation>
     </xsd:annotation>
     <xsd:complexType>
@@ -138,7 +144,7 @@
   <xsd:element name="drop">
     <xsd:annotation>
       <xsd:documentation>
-        TBD
+        Excludes one top level section from the language document.
       </xsd:documentation>
     </xsd:annotation>
     <xsd:complexType>
@@ -152,7 +158,9 @@
   <xsd:element name="extract-subsection">
     <xsd:annotation>
       <xsd:documentation>
-        TBD
+        Cuts out a part of an existing inner section and promotes it to a separate inner section.
+        If the target context is not specified, the new section becomes a subsection of the place
+        it has been extracted from.
       </xsd:documentation>
     </xsd:annotation>
     <xsd:complexType>
@@ -170,7 +178,7 @@
   <xsd:element name="import-grammar">
     <xsd:annotation>
       <xsd:documentation>
-        TBD
+        Includes a piece of grammar taken from an external BGF file.
       </xsd:documentation>
     </xsd:annotation>
     <xsd:complexType>
@@ -184,7 +192,15 @@
   <xsd:element name="import-sample">
     <xsd:annotation>
       <xsd:documentation>
-        TBD
+        Includes a sample taken from an external file. It is possible to
+        specify a pretty-printer that will be fed that file and the output will be
+        included.
+      </xsd:documentation>
+      <xsd:documentation>
+        For instance, in the XBGF document the samples were originally in XBGF,
+        but were pretty-printed with an external universal pretty-printer to get
+        the nice EBNF-ish look (otherwise the reader would be overwhelmed with XML
+        listings).
       </xsd:documentation>
     </xsd:annotation>
     <xsd:complexType>
@@ -199,7 +215,11 @@
   <xsd:element name="insert">
     <xsd:annotation>
       <xsd:documentation>
-        TBD
+        This is one of the transformations that has no corresponding command in XBGF,
+        since grammars do not have order of elements (in fact, any concrete grammar
+        notation does, but it does not matter) and language documents do (and do care about
+        it a lot). This transformation inserts new content right before or after another
+        piece of content that is looked up by the XLDF engine at the run-time.
       </xsd:documentation>
     </xsd:annotation>
     <xsd:complexType>
@@ -213,7 +233,8 @@
   <xsd:element name="place">
     <xsd:annotation>
       <xsd:documentation>
-        TBD
+        Makes one section to become a subsection of another section. The target section must be 
+        of a type that supports subsections.
       </xsd:documentation>
     </xsd:annotation>
     <xsd:complexType>
@@ -229,7 +250,11 @@
   <xsd:element name="retitle">
     <xsd:annotation>
       <xsd:documentation>
-        TBD
+        Changes the title of a section or a subsection. It is still possible to designate the target
+        for this transformation with an ID, but a more friendly and user-expected way of designating it
+        with its current title is also possible: that way by looking at a transformation one can
+        immediately tell what was the title before and what will it be (and possibly deduct the reason for
+        this change).
       </xsd:documentation>
     </xsd:annotation>
     <xsd:complexType>
@@ -250,7 +275,7 @@
   <xsd:element name="remove-section">
     <xsd:annotation>
       <xsd:documentation>
-        TBD
+        Excludes one subsection from a specified section.
       </xsd:documentation>
     </xsd:annotation>
     <xsd:complexType>
@@ -264,7 +289,8 @@
   <xsd:element name="transform-document">
     <xsd:annotation>
       <xsd:documentation>
-        TBD
+        Modularisation support: we allow to put an evolution sequence in a separate file
+        to be called from a place in another file.
       </xsd:documentation>
     </xsd:annotation>
     <xsd:complexType>
@@ -277,7 +303,12 @@
   <xsd:element name="transform-grammar">
     <xsd:annotation>
       <xsd:documentation>
-        TBD
+        This is an interface between XLDF and XBGF: all the grammar productions are gathered
+        from the target section and its subsections, to be fed into a transformation (or a
+        chain of transformations). If the XBGF engine evaluates successfully, the result of
+        that transformation is returned to the target section. It is also possible to specify
+        a number of context section --- all productions from them will be gathered, too, but
+        since they are not subject to change, they will not be confused with the result.
       </xsd:documentation>
     </xsd:annotation>
     <xsd:complexType>
@@ -288,8 +319,6 @@
       </xsd:sequence>
     </xsd:complexType>
   </xsd:element>
-
-
 
   <xsd:group name="relative">
     <xsd:choice>

topics/languedoc/languedoc.csproj

@@ -97,6 +97,7 @@
     <None Include="xldf\xldf.xldf" />
     <None Include="xldf\xldf\dropLdf.xldf" />
     <None Include="xldf\xldf\dropXbgf.xldf" />
+    <None Include="xldf\xldf\renameStr.xldf" />
   </ItemGroup>
   <ItemGroup>
     <Content Include="..\..\shared\xsl\ldf2tex.xslt">

topics/languedoc/xldf/xldf.xldf

@@ -8,5 +8,12 @@
   <xldf:transform-document>
     <file>xldf/dropLdf.xldf</file>
   </xldf:transform-document>
+  <xldf:transform-document>
+    <file>xldf/renameStr.xldf</file>
+  </xldf:transform-document>
+  <xldf:combine>
+    <section>group-relative</section>
+    <with>element-insert</with>
+  </xldf:combine>
 
 </xldf:evolution-sequence>

topics/languedoc/xldf/xldf/dropLdf.xldf

@@ -2,12 +2,6 @@
 <xldf:evolution-sequence
   xmlns:xldf="http://planet-sl.org/xldf">
 
-  <xldf:drop>
-    <section>element-evolution-sequence</section>
-  </xldf:drop>
-  <xldf:drop>
-    <section>group-document-transformation</section>
-  </xldf:drop>
   <xldf:drop>
     <section>complexType-listOfTerms</section>
   </xldf:drop>