diff options
Diffstat (limited to 'macros/xmltex/base/manual.html')
| -rw-r--r-- | macros/xmltex/base/manual.html | 882 |
1 files changed, 882 insertions, 0 deletions
diff --git a/macros/xmltex/base/manual.html b/macros/xmltex/base/manual.html new file mode 100644 index 0000000000..2c88af23df --- /dev/null +++ b/macros/xmltex/base/manual.html @@ -0,0 +1,882 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> +<html xmlns:lxslt="http://xml.apache.org/xslt" xmlns:saxon="http://icl.com/saxon" xmlns:xalan="org.apache.xalan.xslt.extensions.Xalan"> +<head> +<title> + xmltex: A non validating (and not 100% + conforming) namespace aware XML parser implemented in TeX + </title> +<link rel="stylesheet" type="text/css" href="http://www.oucs.ox.ac.uk/stylesheets/tei-oucs.css"> +</head> +<body> +<table width="100%"> +<tr> +<td rowspan="2"></td><td align="left"> +<h2>Numerical Algorithms Group: NAG</h2> +</td> +</tr> +<tr> +<td align="left"> +<h1> + xmltex: A non validating (and not 100% + conforming) namespace aware XML parser implemented in TeX + </h1> +</td> +</tr> +</table> +<hr> + <h2> + xmltex: A non validating (and not 100% + conforming) namespace aware XML parser implemented in TeX + </h2> + Date: 2000-02-02 + <h2> +<it>davidc@nag.co.uk</it> +</h2> + <h2> +<it>David Carlisle</it> +</h2> +<h2>Contents</h2> +<p> +<div class="subtoc"> +<ul> +<li> +<a class="subtoc" href="#intro">Introduction</a> +</li> +<li> +<a class="subtoc" href="#manualN211">Installation</a> +</li> +<li> +<a class="subtoc" href="#manualN343">Using xmltex</a> +</li> +<li> +<a class="subtoc" href="#stopping">Stopping xmltex</a> +</li> +<li> +<a class="subtoc" href="#manualN651">xmltex package files</a> +</li> +<li> +<a class="subtoc" href="#manualN1004">XML processing</a> +</li> +<li> +<a class="subtoc" href="#manualN1059">Accessing TeX</a> +</li> +<li> +<a class="subtoc" href="#manualN1146">Bugs</a> +</li> +<li> +<a class="subtoc" href="#manualN1161">Don't Read Past This Point</a> +</li> +</ul> +</div> +</p> +<h2> +<a name="intro"></a>Introduction</h2> + +<p> +xmltex implements +a non validating parser for documents matching the +W3C XML Namespaces Recommendation. + + +The system may just be used to parse the file (expanding entity +references and normalising namespace declarations) in which case it +records a trace of the parse on the terminal. Normally however the +information from the parse is used to trigger TeX typesetting code. +Declarations (in TeX syntax) are provided as part of xmltex to +associate TeX code with the start and end of each XML element, +attributes, processing instructions, and with unicode character data. +</p> + + +<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 +such a format would have no convenient commands for typesetting, and +so normally xmltex will be used on top of an existing format, normally +LaTeX. In this section we assume that the document to be +processed is called <tt>document.xml</tt>. +</p> +<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 +<tt>document.tex</tt> of the following form: +<pre> +\def\xmlfile{document.xml} +\input xmltex.tex +</pre> + +Do <em>not</em> put any other commands in this file!</p> +<p>You may then process the document with either of the commands: +<tt>latex document</tt> or <tt>latex document.tex</tt> +or the equivalent procedure in your TeX environment. +</p> + +<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. +This may speed things up slightly (as <tt>xmltex.tex</tt> does not +have to be read each time) but more importantly perhaps it allows the +XML file to be processed directly without needing to make the +<tt>.tex</tt> wrapper.</p> +<p>To make a format you will need a command such as the following, +depending on your TeX system. +<pre> +initex &latex xmltex +initex \&latex xmltex +tex -ini &latex xmltex +tex -ini \&latex xmltex +</pre> +</p> +<p>This will produce a format file <tt>xmltex.fmt</tt>. You should then +be able to make a <tt>xmltex</tt> command by copying the way the +<tt>latex</tt> command is defined in terms of +<tt>latex.fmt</tt>. Depending on the TeX system, this might be a +symbolic link, or a shell script, or batch file, or a configuration +option in a setup menu. + +</p> + +<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 +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 +will allow you to have a different hyphenation and language +customisation for xmltex than for LaTeX. Many of the features of +the language support in LaTeX are related to modifying the input +syntax to be more convenient. Such changes are not needed in xmltex as +the input syntax is always XML. Some language files may change the +meaning of such characters as < which would break the xmltex parser. +Also, rather than using <tt>latex.ltx</tt> you could in principle +use a modified <tt>docstrip</tt> install file and produce a +`cut down' latex that did not have features that are not going to be +used in xmltex. +</p> +<p> +Unfortunately the support for this method of building xmltex (and access +to non English hyphenation generally) is not fully designed and totally +undocumented.</p> + + +<h2> +<a name="manualN343"></a>Using xmltex</h2> + +<p> +xmltex by default `knows' nothing about any particular type of XML +file, and so needs to load external files containing specific +information. This section describes how the information in the XML +file determines which files will be loaded. + +<ol> +<li> If the file begins with a Byte Order Mark, the default encoding + is set to utf-16. Otherwise the default encoding is utf-8. +</li> +<li> If (after an optional BOM) the document begins with an XML + declaration that specifies an encoding, this encoding will be used, + otherwise the default encoding will be used. A file with name of the + form <em>encoding</em><tt>.xmt</tt> will be loaded that maps the + requested encoding to Unicode positions. (It is an error if this + file does not exist for the requested encoding.) +</li> +<li> If the document has a <tt>DOCTYPE</tt> declaration that includes + a local subset then this will be parsed. If any external DTD entity + is referenced (by declaring and then referencing a parameter entity) + then the SYSTEM and PUBLIC identifiers of this entity will be looked + up in a catalogue (to be described below). If either identifier is + known in the catalogue the corresponding xmltex package (often with + <tt>.xmt</tt> extension) will be loaded. +</li> +<li> After any local subset has been processed, if the DOCTYPE + specifies an external entity, the PUBLIC and/or SYSTEM identifiers + of the external dtd file will be similarly looked up, and a + corresponding xmltex file loaded if known. +</li> +<li> As each element is processed, it may be `known' to xmltex by + virtue of one of the packages loaded, or it may be unknown. If it is + unknown then if it is in a declared namespace, the namespace URI + (not the prefix) is looked up in the xmltex catalogue. If the + catalogue specifies an xmltex package for this namespace it will be + loaded. If the element is not in a namespace, then the element name + will be looked up in the catalogue. +</li> +<li> If after all these steps the element is still unknown then + depending on the configuration setting either a warning or an error + will be displayed. (Currently only warning implemented.) +</li> +</ol> +</p> +<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: +<pre> +<tt>\NAMESPACE</tt>{<em>URI</em>}{<em>xmt-file</em>} +<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. 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><html></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 +<tt>document.cfg</tt> in the example in the Introduction) in which +case the commands just apply to the specified document. +</p> + + +<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. + +<ul> +<li> <p> +<tt>\xmltraceonly</tt> +</p> +<p> This stops xml from trying to typeset the + document. The external files specified in the catalogue are still + loaded, so that the trace may report any elements for which no code + is defined, but no actual typesetting takes place. In the event of + unknown errors it is always worth using xmltex in this mode to + isolate any problems.</p> +<p>It may be noted that if an xmltex format is built just using initex +without any typesetting commands, the resulting format should still +be able to parse any XML file if xmltex.cfg just specifies +<tt>\xmltraceonly</tt> and \jobname.cfg is empty.</p> +</li> +<li> <p> +<tt>\xmltraceoff</tt> +</p> +<p>By default xmltex provides a trace of its XML parse, displaying + each element begin and end. This command used in xmltex.cfg or + `\jobname.cfg' will stop this trace being produced.</p> +</li> + +<li> +<p> <tt>\inputonce</tt>{<em>xmt-file</em>}</p> +<p>The catalogue entries specify that + certain files should be loaded if XML constructs are met. + Alternatively the files may just always be loaded. The system will + ignore any later requests to load. This is especially useful if an + xmltex format is being made.</p> +</li> +<li> +<p> +<tt>\UnicodeCharacter</tt>{<em>hex-or-dec</em>}{<em>tex-code</em>}</p> +<p>The first argument specifies a unicode character number, in the same +format as used for XML character entities, namely either a decimal +number, or an upper case Hex number preceded by a lower case +`<tt>x</tt>'.</p> +<p>The second argument specifies arbitrary TeX code to be used when +typesetting this character. Any code in the XML +range may be specified (ie up to x10FFFF). Although codes in the +`ASCII' range, below 128, may be specified, the definitions supplied +for such characters will not be default be used. The definition will +howeverbe stored and used if the character is activated using the +command described below.</p> +</li> +<li> <p> +<tt>\ActivateASCII</tt>{<em>hex-or-dec</em>}</p> +<p>The argument to this command should be a number less than 128. +If a character us activated by this command in a configuration file +then any special typesetting instructions specified for the character +will be executed whenever the character appears as character data.</p> +<p>Some ASCII characters are activated by default. The list is +essentially those characters with special meanings to either TeX or +XML.</p> +</li> + +</ul> +</p> +<p> +If a format is being made, there are essentially two copies of +<tt>xmltex.cfg</tt> that may play a role. The configuration file +input when the format is made will control catalogue entries and +packages built into the format. A possibly different +<tt>xmltex.cfg</tt> may be used in the input path of `normal' TeX, +this will then be used for additional information loaded each run.</p> +<p>In either case, a separate configuration file specific to the given +XML document may also be used (which is loaded immediately after +<tt>xmltex.cfg</tt>). +</p> + + + +<h2> +<a name="stopping"></a>Stopping xmltex</h2> + +<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><?xmltex \stop?></tt>). +</p> + + +<h2> +<a name="manualN651"></a>xmltex package files</h2> + +<p> +xmltex package files are the link between the XML markup and TeX +typesetting code. They are written in TeX (rather than XML) syntax +and may load directly or indirectly other files, including LaTeX +class and package files. For example a file loaded for a particular +document type may directly execute <tt>\LoadClass{article}</tt>, or +alternatively it may cause some XML element in the document to +execute <tt>\documentclass{article}</tt>. In either case the document will +suffer the dubious benefit of being formatted based on the style +implemented in <tt>article.cls</tt>. Beware though that the package +files may be loaded at strange times, the first time a given namespace +is declared in a document, and so the code should be written to work +if loaded inside a local group.</p> +<p>Characters in xmltex package files have their normal LaTeX meanings +except that line endings are ignored so that you do not need to add +a % to the end of lines in macro code. Unlike fd file conventions, other +white space is <em>not</em> ignored.</p> +<p>The available commands are: + +<ul> +<li> +<p> +<tt>\FileEncoding</tt>{<em>encoding</em>}</p> +<p>This is the analogue for TeX syntax files of the encoding specification +in the XML or text declaration of XML files. If it is not specified the +file will be assumed to be in UTF-8.</p> +</li> + +<li> +<p> +<tt>\DeclareNamespace</tt>{<em>prefix</em>}{<em>URI</em>}</p> +<p>This declares a prefix to be used <em>in this file</em> for referring to +elements in the specified namespace. If the prefix is empty then this +declares the default namespace (otherwise, unprefixed element names +refer to elements that are not in a namespace).</p> +<p>Note that the elements in the XML document instance may use a +different prefix, or no prefix at all to access this namespace. +In order to resolve these different prefixes for the same namespace, +each time a namespace is encountered for the first time (either +by <tt>\DeclareNamespace</tt> in a preloaded package, or in a namespace +declaration in the XML instance) then it is allocated a new number +and any further namespace declaration for the same URI just locally +associates a prefix with this number. It is these numbers that are +displayed when the XML trace of the parse of the document is shown, +and also if any element is written out to an external file it will +have a normalised prefix of a number whichever prefix it had +originally. (Numeric prefixes are not legal XML, but this is an +advantage, it ensures these internal forms can not clash with any +prefix actually used in the document.)</p> +<p>Three namespaces are predeclared. The null namespace (0), the XML +namespace (<tt>http://www.w3.org/1998/xml</tt>) (1) which is predeclaed +with prefix <tt>xml</tt> as specified in the Namespace Recommendation, +and the xmltex namespace +(<tt>http://www.dcarlisle.demon.co.uk/xmltex</tt>) (2) which is not +given a default prefix, but may be used to have XML syntax for some +internal commands (eg to have .aux files fully in XML, currently they +are a hybrid mixture of some TeX and some XML syntax). +</p> +</li> +<li> +<p> + <tt>\XMLelement</tt>{<em>element-qname</em>}{<em>attribute-spec</em>} +{<em>begin-code</em>}{<em>end-code</em>}</p> +<p> This is similar to a LaTeX <tt>\newenvironment</tt> command.</p> +<p> Declare the code to execute at the start and end of each instance of +this element type. This code will be executed in a local group (like a +LaTeX environment). The second argument declares a list of attributes +and their default values using the <tt>\XMLattribute</tt> command +described below. +</p> +</li> +<li> +<p> + <tt>\XMLelement</tt>{<em>element-qname</em>} +{<em>attribute-spec</em>} +<tt>{\xmlgrab}</tt>{<em>end-code</em>}</p> +<p> A special case of the above command (which may be better made into a + separate declaration) is to make the <em>start-code</em> just be the command + <tt>\xmlgrab</tt>. In this case the <em>end-code</em> has access to the + element content (in XML syntax) as <tt>#1</tt>. This content isn't + literally the same as the original document, namespaces, white space + and attribute quote symbols will all have been normalised. +</p> +</li> +<li> <p> + <tt>\XMLattribute</tt>{<em>attribute-qname</em>} +{<em>command-name</em>}{<em>default</em>}</p> +<p>This command may only be used in the argument to +<tt>\XMLelement</tt>. + The first argument specifies the name of an attribute (using any + namespace prefixes current for this package file, which need not + be the same as the prefixes used in the document). + The second argument gives a TeX command name that will be used to + access the value of this attribute in the begin and end code for the + element. (Note using TeX syntax here provides a name independednt of + the namespace declarations that are in scope when this code is executed). + The third argument provides a default value that wil be used if the +attribute is not used on an instance of this element. + </p> +<p>The special token <tt>\inherit</tt> may be used which will cause +the command to have a value set in an ancestor element if this element +does not specify any value.</p> +<p>If a TeX token such as <tt>\relax</tt> is used as the default +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> +<tt>\XMLentity</tt>{<em>name</em>}{<em>code</em>}</p> +<p>Declare an (internal parsed) entity, this is equivalent to a +<tt><!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>}<><em>XML Data</em></></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="manualN1004"></a>XML processing</h2> + +<p> +xmltex tries as far as possible to be a fully conforming non +validating parser. It fails in the following respects. +<ul> +<li> Error reporting is virtually non existent. Names are not checked + against the list of allowed characters, and various other + constraints are not enforced. +</li> +<li> +<p> A non validating parser is not forced to read external dtd + entities (and this one does not) It is obliged to read the local + subset and process entity definitions and attribute declarations. + Entity declarations are reasonably well handled: External parameter + entities are handled as above, loading a corresponding xmltex file + if known. External entities are similarly processed, inputting + the XML file, a difference in this case is that if the entity is not + found in the catalogue, the SYSTEM identifier will be used directly + to <tt>\input</tt> as often this is a local file reference. Internal + 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>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 + file. Any 8bit encoding that matches Unicode for the first 127 positions + may be used by making a trivial mapping file. (The one for latin1 + looks over complicated as it programs a loop rather than having 127 + declarations saying that latin1 and Unicode are identical in this + range).</p> +<p> UTF-8 is supported, but support for UTF-16 is minimal. Currently + only latin-1 values work: (In this range UTF-16 is just latin-1 with + a null byte inserted after (or before, depending on endedness) + each latin-1 byte. The UTF-16 implementation just ignores this null + byte then processes as for latin-1. Probably the first few 8bit + pages could be similarly supported by making the low ascii control + characters activate UTF-16 processing but this will never be + satisfactory using a standard TeX. Hopefully a setup for a 16bit + TeX such as Omega will correct this.</p> +</li> +</ul> + +</p> + +<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 +necessary to `tweak' the output by placing commands directly in the +source.</p> +<p>Two mechanisms are availalable to do this. +<ul> +<li> +<p> Using the xmltex namespace. The xmltex namespace conatins a + small (currently empty) set of useful TeX constructs that are + accessed by XML syntax. For example if xmltex provides a mechanism + for having XML (rather than LaTeX) syntax toc files, it will need + an analogue of <tt>\contentsline</tt> which might be an element + accessed by <tt><xmltex:contentsline></tt>… where the xmltex + prefix is declared on this or a parent element to be + <tt>xmlns:xmltex="http://www.dcarlisle.demon.co.uk/xmltex"</tt>.</p> +<p> As the xmltex namespace is declared but currently empty, a more + useful variant of this might be:</p> +</li> +<li> Declare your own namespace for TeX tweaks, and load a suitable + package file that attatches TeX code to the elements in this + namespace (or at least specify the correspondence between the + namespace and the package using <tt>\NAMESPACE</tt>). + For instance if you put <tt><clearpage xmlns="/my/tex/tweak"/></tt> + in your document, this will force a page break if you have at + suitable points, <tt>\NAMESPACE{/my/tex/tweak}{tweak.xmt}</tt> + and +<pre> +\DeclareNamespace{tweak}{"/my/tex/tweak"} +\XMLelement{tweak:clearpage}{\clearpage} +</pre> +</li> +<li> +<p> A second different mechanism is available, to use XML processing + instructions. A Processing Instruction of the form: +<tt><?xmltex></tt> <em>TeX commands</em> <tt>?></tt> +will execute the TeX commands.</p> +</li> +</ul> + +</p> + + +<h2> +<a name="manualN1146"></a>Bugs</h2> + +<p>None, of course.</p> + + +<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, +and also describes some of the internal interfaces (which are also +subject to change)</p> + +<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="manualN1201"></a>States</h4> +<p>In the xml <em>state</em>, + < and & are the only two characters that +trigger special markup codes. Other characters, such as !, >, =, +… may be used in certain XML constructs as markup but unless +some code has been triggered by < they are treated simply as +character data. All characters above 127 are `active' to TeX +and are used to translate the input encoding to UTF-8. All internal +character handling is based on UTF-8, as described below. Some +characters in the ASCII range, below 127 are also active by default +(mainly punctuation characters used in XML constructs, such as +the ones listed above). Some or all of the others may be activated +using the <tt>\ActivateASCII</tt> command, which allows special +typesetting rules to be activated for the characters, at some cost in +processing speed.</p> +<p>In the tex <em>state</em>, +characters in the ASCII range have their usual +TeX meanings, so letters are `catcode 11' and may be used in TeX +control sequences, \ is the escape character, & the table cell +separator, etc. Characters above 127 have the meanings current for the +current encoding just as for the xml state, probably this means that +they are unusable in TeX code, except for the special case of +referring to XML element names in the first argument to +<tt>\XMLelement</tt> and releated commands.</p> + +<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. +The encoding current while the file is read is determined by the +encoding pseudo-attribute on the XML or text declaration in the case +of XML files, or by the <tt>\FileEncoding</tt> command for TeX +files. Note that the encoding mechanism <em>only</em> is triggered +by xmltex file includes. Once an xmltex package file is loaded it may +include other TeX files by <tt>\input</tt> or +<tt>\includepackage</tt> these input command swill be transparent +to the xmltex encoding system. The vast majority of TeX macro +packages only use ASCII characters so this should not be a +problem.</p> +<p>Note that if the <tt>\includepackage</tt> occurs directly in +the xmltex package file, the TeX code will be included with a known +encoding, the one specified in the xmltex package, or UTF-8. If +however the <tt>\includepackage</tt> is included in code specified +by <tt>\XMLelement</tt>, then it will be executed with whatever +encoding is current in the document at the point that element is +reached. Before xmltex executes the code for that element it will +switch to the tex state, thus normalising the ascii characters +but characters above 127 will not have predefined definitions in this +case.</p> +<p>Internally eveything is stored as UTF-8. So `aux' and `toc' files +will be in UTF-8 even if the document (or parts of the document) used +different encodings.</p> +<p>To specify a new encoding, if it is an 8 bit encoding that matches +ASCII in the printable ASCII range, then one just needs to produce a +file with name <em>encoding</em><tt>.xmt</tt> (in lowercase, +on case sensitive systems) this should consist of a series of +<tt>\InputCharacter</tt> commands, giving the input character slot +and the equivalent Unicode. If an encoding is specified in this manner +character data will be converted to UTF-8 by <em>expansion</em> +and so ligatures and inter letter kerns will be preserved. (Conversely +if characers are accessed by character references, &#1234; then +TeX arithmetic is used to decode the information and ligature +information will be lost. For some large character sets, especially +for Asian languages, these mechanisms will probably not prove to be +sufficient, some mechanisms are being investigated, but in the short +term it may be necessary to always use UTF-8 if the input encoding +is not strictly a ine byte extension of the ASCII code page. +</p> + + + +<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 +group, at the point in a document that a particular namespace is first +used, for example. There are however some specific commands designed +to be used in the begin or end code of <tt>\XMLElement</tt>. +<ul> + +<li> +<p> +<tt>\ignorespaces</tt> +</p> +<p>This is actually a TeX primitive +(for the moment!)</p> +</li> + +<li> +<p> +<tt>\obeyspaces</tt> +</p> +<p>Obey consecutive space characters, +rather than treating consecutive runs as a single space. +(A command of this name, but not this definition is in plain TeX.)</p> +</li> + +<li> +<p> +<tt>\obeylines</tt> +</p> +<p>Obey end of line characters, +rather than treating then as a space, force a line break. +(A command of this name, but not this definition is in plain TeX.)</p> +</li> + +<li> +<p> +<tt>\xmltexfirstchild#1\@</tt> +</p> +<p>If the <em>start-code</em> for an element is specified as +<tt>\xmlgrab</tt> then the <em>end-code</em> may use +<tt>#1</tt> in order to execute the element content. Sometimes you +do not want all of the content. The a construction (with currently +unpleasant syntax) <tt>\xmltexfirstchild#1\@</tt> will just evaluate +the first child element of the content, discarding the remaining +elements.</p> +</li> + +<li> +<p> +<tt>\xmltextwochildren\csa\csb#1</tt> +</p> +<p>If you know that the content will be exactly two child elements (for +examle a MathML frac or sub element) then this command may be used. +It will execute the TeX code +<tt>\csa{</tt><em>child-1</em><tt>}\csb{</tt><em>child-2</em> +So either two TeX command smay be supplied, one will be applied to +each child, or the second argument may be <tt>{}</tt> in which case +the first argument may be a TeX command that takes two arguments. +For example the code for MathMl frac might be +<pre> +\XMLelement{m:mfrac} + {} + {\xmlgrab} + {\xmltextwochildren\frac{}#1} +</pre> +</p> +</li> + +<li> +<p> +<tt>\xmltexthreechildren\csa\csb\csc#1</tt> +</p> +<p>As above, but more so.</p> +</li> + +<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 +it expands it without executing any special hook that may be defined in +an xmltex package. However NDATA entites are never directly encountered +in an entity reference. They may only be used as an attribute value. +If <tt>\attvalue</tt>. is a TeX command holding the value of an +attribute, as declared in <tt>\XMLattribute</tt> then +<tt>\NDATAEntity\csa\csb\attvalue</tt> applies the two TeX +commands <tt>\csa</tt> and <tt>\csb</tt> to the notation type +and the value, in a way exactly corresponding to +<tt>\xmltextwochildren</tt> so for example the XML document for this +manual specifies +<pre> + <!NOTATION URL SYSTEM "" > + <!ENTITY lppl SYSTEM "http://www.latex-project.org/lppl.txt" NDATA URL> +</pre> +and this is handled by the following xmltex code +<pre> +\XMLelement{xptr} + {\XMLattribute{doc}{\xptrdoc}{}} + {\NDATAEntity\xptrdoc\@gobble\url} + {} +</pre> +which saves the attribute value in <tt>\xptrdoc</tt> and then +discards the notation name (URL) and applies the command +<tt>\url</tt> to typeset the supplied URL. +</p> +</li> + +</ul> +</p> + + + +<h3> +<a name="manualN1489"></a>Character Data Internals</h3> + +<p> +<div align="center"> +<table> +<tr> +<td></td> <td>int.</td><td>ext. xml</td> +<td>ext. mixed</td><td>csn typeout</td> +<td></td> +</tr> +<tr> +<td>d</td><td>xabc</td><td>xabc</td> +<td>xabc (12)</td><td>xabc (12)</td><td>xabc (12)</td> +<td></td> +</tr> +<tr> +<td>c</td><td>xab</td><td>xab</td> +<td>xab (12)</td><td>xab (12)</td><td>xab (12)</td> +<td></td> +</tr> +<tr> +<td>b</td><td>xa</td><td>xa</td> +<td>xa (12)</td><td>xa (12)</td><td>xa (12)</td> +<td></td> +</tr> +<tr> +<td>ax</td><td>x</td><td>x</td> +<td>x</td><td>x</td><td>x (12)</td> +<td>(!)</td> +</tr> +<tr> +<td>ay</td><td>x</td><td>x</td> +<td>x</td><td>&#123;</td><td>x (12)</td> +<td>(e)</td> +</tr> +<tr> +<td>az</td><td>x</td><td>\az x</td> +<td>&#123;</td><td>&#123;</td><td>x (12)</td> +<td>(&lt;)</td> +</tr> +<tr> +<td><</td><td><</td><td><</td> +<td><</td><td><</td><td>< (12)</td> +<td>(<)</td> +</tr> +</table> +</div> + +</p> + + + + + + +<hr> +<div align="center"> +[<a href="http://www.tei-c.org/">NAG</a> +| <a href="http://www.nag.co.uk/">NAG</a> +] + </div> +<hr> +<address> + Last updated: Date: 2000-02-02. + <br> Copyright 2000 David Carlisle, NAG + +<!--Created by a version 1 + XSLT stylesheet by James Clark--></address> +</body> +</html> |