manual update (dak 23 Apr 2008 18:11:26)

git-svn-id: svn://tug.org/texlive/trunk@7653 c570f23f-e606-0410-a88d-b1316a301751

2 files changed, 124 insertions, 69 deletions

diff --git a/Master/texmf-dist/doc/xmltex/base/manual.html b/Master/texmf-dist/doc/xmltex/base/manual.html
index 387b474ca8c..2c88af23dfa 100644
--- a/Master/texmf-dist/doc/xmltex/base/manual.html
+++ b/Master/texmf-dist/doc/xmltex/base/manual.html
@@ -28,7 +28,7 @@
    xmltex: A non validating (and not 100%
     conforming) namespace aware XML parser implemented in TeX
   </h2>
-  Date: 2000-01-18
+  Date: 2000-02-02
   <h2>
 <it>davidc@nag.co.uk</it>
 </h2>
@@ -43,28 +43,28 @@
 <a class="subtoc" href="#intro">Introduction</a>
 </li>
 <li>
-<a class="subtoc" href="#manualN178">Installation</a>
+<a class="subtoc" href="#manualN211">Installation</a>
 </li>
 <li>
-<a class="subtoc" href="#manualN310">Using xmltex</a>
+<a class="subtoc" href="#manualN343">Using xmltex</a>
 </li>
 <li>
 <a class="subtoc" href="#stopping">Stopping xmltex</a>
 </li>
 <li>
-<a class="subtoc" href="#manualN609">xmltex package files</a>
+<a class="subtoc" href="#manualN651">xmltex package files</a>
 </li>
 <li>
-<a class="subtoc" href="#manualN863">XML processing</a>
+<a class="subtoc" href="#manualN1004">XML processing</a>
 </li>
 <li>
-<a class="subtoc" href="#manualN915">Accessing TeX</a>
+<a class="subtoc" href="#manualN1059">Accessing TeX</a>
 </li>
 <li>
-<a class="subtoc" href="#manualN1030">Bugs</a>
+<a class="subtoc" href="#manualN1146">Bugs</a>
 </li>
 <li>
-<a class="subtoc" href="#manualN1045">Don't Read Past This Point</a>
+<a class="subtoc" href="#manualN1161">Don't Read Past This Point</a>
 </li>
 </ul>
 </div>
@@ -89,7 +89,7 @@ attributes, processing instructions, and with unicode character data.
 
 
 <h2>
-<a name="manualN178"></a>Installation</h2>
+<a name="manualN211"></a>Installation</h2>
 
 <p>The xmltex parser itself does not require LaTeX. It may be loaded
 into initex to produce a format capable of parsing XML files. However
@@ -99,7 +99,7 @@ LaTeX. In this section we assume that the document to be
 processed is called <tt>document.xml</tt>.
 </p>
 <h3>
-<a name="manualN195"></a>Using xmltex as an input to the LaTeX command</h3>
+<a name="manualN228"></a>Using xmltex as an input to the LaTeX command</h3>
 
 <p>LaTeX requires a document in TeX syntax, not XML. To process
 <tt>document.xml</tt>, first produce a two line file called
@@ -107,7 +107,6 @@ processed is called <tt>document.xml</tt>.
 <pre>
 \def\xmlfile{document.xml}
 \input xmltex.tex
-\end{document}
 </pre>
 
 Do <em>not</em> put any other commands in this file!</p>
@@ -117,7 +116,7 @@ or the equivalent procedure in your TeX environment.
 </p>
 
 <h3>
-<a name="manualN234"></a>Using xmltex as a TeX format built on LaTeX</h3>
+<a name="manualN267"></a>Using xmltex as a TeX format built on LaTeX</h3>
 
 <p>
 You may prefer to set up xmltex as a format in its own right.
@@ -130,8 +129,8 @@ depending on your TeX system.
 <pre>
 initex &amp;latex xmltex
 initex \&amp;latex xmltex
-tex -ini &amp;latex
-tex -ini \&amp;latex
+tex -ini &amp;latex xmltex
+tex -ini \&amp;latex xmltex
 </pre>
 </p>
 <p>This will produce a format file <tt>xmltex.fmt</tt>. You should then
@@ -144,11 +143,11 @@ option in a setup menu.
 </p>
 
 <h3>
-<a name="manualN278"></a>Using making an xmltex format `from scratch'</h3>
+<a name="manualN311"></a> Making an xmltex format `from scratch'</h3>
 
 <p>
 Whilst it may be convenient to build an xmltex format as above, starting
-from the LaTeX format you may prefer to instead work with an initex
+from the LaTeX format. You may prefer to instead work with an initex
 with no existing format file. Even if you wish to use a standard LaTeX
 it may be preferable to make a TeX input file that first inputs 
 <tt>latex.ltx</tt> then <tt>xmltex.tex</tt>. In particular this
@@ -170,7 +169,7 @@ undocumented.</p>
 
 
 <h2>
-<a name="manualN310"></a>Using xmltex</h2>
+<a name="manualN343"></a>Using xmltex</h2>
 
 <p>
 xmltex by default `knows' nothing about any particular type of XML
@@ -217,7 +216,7 @@ file determines which files will be loaded.
 </ol>
 </p>
 <h3>
-<a name="manualN365"></a>The xmltex Catalogue</h3>
+<a name="manualN398"></a>The xmltex Catalogue</h3>
 <p>As discussed above, xmltex requires a mapping between PUBLIC and
 SYSTEM identifiers, namespace URI, and element names, to files of
 TeX code. This mapping is implemented by the following commands:
@@ -226,13 +225,19 @@ TeX code. This mapping is implemented by the following commands:
 <tt>\PUBLIC</tt>{<em>FPI</em>}{<em>file</em>}
 <tt>\SYSTEM</tt>{<em>URI</em>}{<em>file</em>}
 <tt>\NAME</tt>{<em>element-name</em>}{<em>xmt-file</em>}
+<tt>\XMLNS</tt>{<em>element-name</em>}{<em>URI</em>}
 </pre>
 As described above, if the first argument of one of these commands
 matches the string specified in the XML source file, the corresponding
 TeX commands in the file specified in the second argument are
 loaded. The PUBLIC and SYSTEM catalogue entries may also be used
 to control which XML files should be input in response to external
-entity references.</p>
+entity references. The <tt>\XMLNS</tt> is rather different,
+if an element in the null namespace does not have any definition
+attatched to it, this declaration forces the default namespace to the
+given URI. The catalogue lookup is then repeated. This allows for
+example documents beginning <tt>&lt;html&gt;</tt> to be coerced into
+the xhtml namespace.</p>
 <p>These commands may be placed in a configuration file, either
 <tt>xmltex.cfg</tt>, in which case they apply to all documents,
 or in a configuration file `<tt>\jobname.cfg</tt>' (eg
@@ -242,7 +247,7 @@ case the commands just apply to the specified document.
 
 
 <h3>
-<a name="manualN442"></a>Configuring xmltex</h3>
+<a name="manualN490"></a>Configuring xmltex</h3>
 
 <p>In addition to the `catalogue' commands described earlier there are
 other commands that may be placed in the configuration files.
@@ -323,20 +328,16 @@ XML document may also be used (which is loaded immediately after
 <h2>
 <a name="stopping"></a>Stopping xmltex</h2>
 
-<p>In tracing mode, xmltex will stop after the end of the document
-element has been processed. In the normal processing mode xmltex
-does not currently automatically stop TeX processing. After
-the document has completed TeX will move to the interactive
-<tt>*</tt> prompt (from which you might want to exit with
-<tt>&lt;?xmltex stop?&gt;</tt>). Normally the
-end code specified for the document element should execute
-<tt>\end{document}</tt> and so stop processing and avoid the 
-<tt>*</tt> prompt.
+<p>xmltex  should stop after the end of the document
+element has been processed. If things go wrong and
+you end up at the interactive
+<tt>*</tt> prompt  you might want to exit with
+<tt>&lt;?xmltex \stop?&gt;</tt>).
 </p>
 
 
 <h2>
-<a name="manualN609"></a>xmltex package files</h2>
+<a name="manualN651"></a>xmltex package files</h2>
 
 <p>
 xmltex package files are the link between the XML markup and TeX
@@ -444,6 +445,18 @@ does not specify any value.</p>
 the element code may distinguish the case that the attribute is not used
 in the document.</p>
 </li>
+<li> <p>
+  <tt>\XMLnamespaceattribute</tt>
+{<em>prefix</em>}{<em>attribute-qname</em>}
+{<em>command-name</em>}{<em>default</em>}</p>
+<p>This command is similar to <tt>\XMLattribute</tt>
+ but is used at the top level of the package file, not in the argument
+to <tt>\XMLelement</tt>. It is equivalent to specifying the
+attribute in <em>every</em> element in the namespace specified by
+the first argument. As usual the prefix (which may be {} to denote the
+default namespace) refers to the namespace declarations in the xmltex
+package: the prefixes used in the document may be different.</p>
+</li>
 
 <li>
 <p>
@@ -452,12 +465,40 @@ in the document.</p>
 <tt>&lt;!ENTITY</tt> declaration, except that the
 replacement text is specified in TeX syntax.</p>
 </li>
+
+<li>
+<p>
+<tt>\XMLname</tt>{<em>name</em>}{<em>command-name</em>}</p>
+<p>Declare the TeX command to hold the (normalised, internal form) of
+the XML name given in the first argument. This allows the code specified in
+<tt>\XMLelement</tt> to refer to XML element names without knowing
+the encodings or namespace prefixes used in the document. Of particular
+use might be to compare such a name with <tt>\ifx\XML@parent</tt>
+which will allow element code to take different actions depending on
+the parent of the current element.</p>
+</li>
+
+
+<li>
+<p>
+<tt>\XMLstring</tt>{<em>command-name</em>}&lt;&gt;<em>XML Data</em>&lt;/&gt;</p>
+<p>This saves the XML fragment as the TeX command given in the first
+argument. It may be particularly useful for redefining `fixed strings'
+that are generated by LaTeX document classes to use any special
+typesetting rules specified for individual characters.</p>
+<p>It should also be used for defining any strings used to
+in comparison tests with strings occurring in the XML document.
+Using <tt>\XMLstring</tt> rather than <tt>\def</tt> ensures
+that the characters and encodings in the string are correctly normalised.</p>
+</li>
+
+
 </ul>
 
 </p>
 
 <h2>
-<a name="manualN863"></a>XML processing</h2>
+<a name="manualN1004"></a>XML processing</h2>
 
 <p>
 xmltex tries as far as possible to be a fully conforming non
@@ -480,9 +521,10 @@ validating parser. It fails in the following respects.
   parsed entities and parameter entities are essentially treated as
   TeX macros, and nonparsed entities are saved along with their
   NDATA type, for use presumably by <tt>\includegraphics</tt>.</p>
-<p>  What is not currently done, but mandated by the XML 1.0
-  Recommendation is that default attributes are read from the internal
-  subset. (This might be added later.)</p>
+<p>Attribute defaults are processed in the local subset of the dtd, however
+   note that this is `namespace unaware' defaulting and only applies to
+   elements using the same prefix and local name, unlike the defaulting
+   done by <tt>\XMLattribute</tt>. </p>  
 </li>
 <li>
 <p> Support for encodings depends on having an encoding mapping
@@ -506,7 +548,7 @@ validating parser. It fails in the following respects.
 </p>
 
 <h2>
-<a name="manualN915"></a>Accessing TeX</h2>
+<a name="manualN1059"></a>Accessing TeX</h2>
 
 <p>In theory you should be able to control the document just be suitable
 code specified by <tt>\XMLelement</tt> and friends, but sometimes it may be
@@ -542,12 +584,8 @@ source.</p>
 <li>
 <p> A second different mechanism is available, to use XML processing
   instructions. A Processing Instruction of the form:
-<tt>&lt;?xmltex&gt;</tt>  <em>name</em> {<em>arg1</em>} {<em>arg1</em>} &hellip; <tt>?&gt;</tt>
-will be executed as the TeX command:
-\<em>name</em> {<em>arg1</em>} {<em>arg1</em>} &hellip;</p>
-<p>Note that <em>only</em> the first name will be converted into a TeX
-command, any arguments should only contain character strings.
-</p>
+<tt>&lt;?xmltex&gt;</tt>  <em>TeX commands</em> <tt>?&gt;</tt>
+will execute the TeX commands.</p>
 </li>
 </ul>
 
@@ -555,13 +593,13 @@ command, any arguments should only contain character strings.
 
 
 <h2>
-<a name="manualN1030"></a>Bugs</h2>
+<a name="manualN1146"></a>Bugs</h2>
 
 <p>None, of course.</p>
 
 
 <h2>
-<a name="manualN1045"></a>Don't Read Past This Point</h2>
+<a name="manualN1161"></a>Don't Read Past This Point</h2>
 
 <p>Thus section discusses some of the more experimental features of xmltex
 that may get a cleaner syntax (or be removed, as a bad idea) in later releases,
@@ -569,12 +607,12 @@ and also describes some of the internal interfaces (which are also
 subject to change)</p>
 
 <h3>
-<a name="manualN1059"></a>Input Encodings and States</h3>
+<a name="manualN1175"></a>Input Encodings and States</h3>
 
 <p>At any point while processing a document, xmltex is in one of two 
 <em>states</em>: <em>tex</em> or <em>xml</em>.</p>
 <h4>
-<a name="manualN1085"></a>States</h4>
+<a name="manualN1201"></a>States</h4>
 <p>In the xml <em>state</em>,
  &lt; and &amp; are the only two characters that
 trigger special markup codes. Other characters, such as !, &gt;, =,
@@ -600,7 +638,7 @@ referring to XML element names in the first argument to
 <tt>\XMLelement</tt> and releated commands.</p>
 
 <h4>
-<a name="manualN1117"></a>Encodings</h4>
+<a name="manualN1233"></a>Encodings</h4>
 <p>Whenever a new (XML or TeX) file is input by the xmltex system the
 <em>encoding</em> is first switched to UTF-8. At the end of the
 input the encoding is returned to whatever was the current encoding.
@@ -647,7 +685,7 @@ is not strictly a ine byte extension of the ASCII code page.
 
 
 <h3>
-<a name="manualN1182"></a>xmltex Package Commands</h3>
+<a name="manualN1298"></a>xmltex Package Commands</h3>
 
 <p>You can use arbitrary TeX commands in an xmltex package,
 althought you should be aware that the file may be input into a local
@@ -725,6 +763,17 @@ For example the code for MathMl frac might be
 
 <li>
 <p>
+<tt>\xmltexforall\csa{#1}</tt>
+</p>
+<p>The TeX command <tt>\csa</tt> is called repeatedly,
+taking each child element of the current element as argument
+on each iteration. As a convenience the command <tt>\xml@name</tt>
+is defined before each iteration to have the (internal, normalised)
+name of the element being processed.</p>
+</li>
+
+<li>
+<p>
 <tt>\NDATAEntity\csa\csb\attvalue</tt>
 </p>
 <p>If the XML parser encounters an internalor external entity reference
@@ -761,7 +810,7 @@ discards the notation name (URL) and applies the command
 
 
 <h3>
-<a name="manualN1356"></a>Character Data Internals</h3>
+<a name="manualN1489"></a>Character Data Internals</h3>
 
 <p>
 <div align="center">
@@ -824,7 +873,7 @@ discards the notation name (URL) and applies the command
  </div>
 <hr>
 <address>
- Last updated: Date: 2000-01-18.
+ Last updated: Date: 2000-02-02.
  <br> Copyright 2000 David Carlisle, NAG
 
 <!--Created by a version 1
diff --git a/Master/texmf-dist/doc/xmltex/base/manual.xml b/Master/texmf-dist/doc/xmltex/base/manual.xml
index aec2851b949..610938913ff 100644
--- a/Master/texmf-dist/doc/xmltex/base/manual.xml
+++ b/Master/texmf-dist/doc/xmltex/base/manual.xml
@@ -35,6 +35,8 @@
     <revisionDesc>
       <list>
         <head></head>
+         <item><date>February 2nd 2000</date>
+               <name>David Carlisle</name>Updated)</item>
          <item><date>January 24th 2000</date>
                <name>David Carlisle</name>Updated)</item>
          <item><date>January 19th 2000</date>
@@ -60,7 +62,7 @@
    <titlePart type="main">xmltex: A non validating (and not 100%
     conforming) namespace aware XML parser implemented in &TeX;</titlePart>
   </docTitle>
-  <docDate>Date: 2000-01-24</docDate>
+  <docDate>Date: 2000-02-02</docDate>
   <docAuthor rend="email">davidc@nag.co.uk</docAuthor>
   <docAuthor>David Carlisle</docAuthor>
 </front>
@@ -306,15 +308,11 @@ XML document may also be used (which is loaded immediately after
 
 <div  id="stopping">
 <head>Stopping xmltex</head>
-<p>In tracing mode, xmltex will stop after the end of the document
-element has been processed. In the normal processing mode xmltex
-does not currently automatically stop &TeX; processing. After
-the document has completed &TeX; will move to the interactive
-<code>*</code> prompt (from which you might want to exit with
-<code><![CDATA[<?xmltex stop?>]]></code>). Normally the
-end code specified for the document element should execute
-<code>\end{document}</code> and so stop processing and avoid the 
-<code>*</code> prompt.
+<p>xmltex  should stop after the end of the document
+element has been processed. If things go wrong and
+you end up at the interactive
+<code>*</code> prompt  you might want to exit with
+<code><![CDATA[<?xmltex \stop?>]]></code>).
 </p>
 </div>
 
@@ -455,6 +453,10 @@ the parent of the current element.</p>
 argument. It may be particularly useful for redefining `fixed strings'
 that are generated by &LaTeX; document classes to use any special
 typesetting rules specified for individual characters.</p>
+<p>It should also be used for defining any strings used to
+in comparison tests with strings occurring in the XML document.
+Using <code>\XMLstring</code> rather than <code>\def</code> ensures
+that the characters and encodings in the string are correctly normalised.</p>
 </item>
 
 
@@ -484,9 +486,10 @@ validating parser. It fails in the following respects.
   parsed entities and parameter entities are essentially treated as
   &TeX; macros, and nonparsed entities are saved along with their
   NDATA type, for use presumably by <code>\includegraphics</code>.</p>
-<p>  What is not currently done, but mandated by the XML 1.0
-  Recommendation is that default attributes are read from the internal
-  subset. (This might be added later.)</p>
+<p>Attribute defaults are processed in the local subset of the dtd, however
+   note that this is `namespace unaware' defaulting and only applies to
+   elements using the same prefix and local name, unlike the defaulting
+   done by <code>\XMLattribute</code>. </p>  
 </item>
 <item><p> Support for encodings depends on having an encoding mapping
   file. Any 8bit encoding that matches Unicode for the first 127 positions
@@ -542,12 +545,8 @@ source.</p>
 </item>
 <item><p> A second different mechanism is available, to use XML processing
   instructions. A Processing Instruction of the form:
-<gi>?xmltex</gi>  <emph>name</emph> {<emph>arg1</emph>} {<emph>arg1</emph>} &ldots; <code>?></code>
-will be executed as the &TeX; command:
-\<emph>name</emph> {<emph>arg1</emph>} {<emph>arg1</emph>} &ldots;</p>
-<p>Note that <emph>only</emph> the first name will be converted into a &TeX;
-command, any arguments should only contain character strings.
-</p>
+<gi>?xmltex</gi>  <emph>&TeX; commands</emph> <code>?></code>
+will execute the &TeX; commands.</p>
 </item>
 </list>
 
@@ -696,7 +695,14 @@ For example the code for MathMl frac might be
 </item>
 
 <item><p><code>\xmltexthreechildren\csa\csb\csc#1</code></p>
-<p>As above, but more so.</p>
+<p>As above, but more so.</p></item>
+
+<item><p><code>\xmltexforall\csa{#1}</code></p>
+<p>The &TeX; command <code>\csa</code> is called repeatedly,
+taking each child element of the current element as argument
+on each iteration. As a convenience the command <code>\xml@name</code>
+is defined before each iteration to have the (internal, normalised)
+name of the element being processed.</p>
 </item>
 
 <item><p><code>\NDATAEntity\csa\csb\attvalue</code></p>