+ xmltex: A non validating (and not 100% + conforming) namespace aware XML parser implemented in TeX +

From 3db8854079e5f66bff8e115d3e53b74a9e6b1b94 Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Sun, 24 May 2009 00:31:38 +0000 Subject: move doc for lesser-used formats to subdirs git-svn-id: svn://tug.org/texlive/trunk@13440 c570f23f-e606-0410-a88d-b1316a301751 --- .../doc/otherformats/xmltex/base/englishutf16.xml | Bin 0 -> 194 bytes .../doc/otherformats/xmltex/base/englishutf8.xml | 6 + .../doc/otherformats/xmltex/base/langtest.xml | 21 + .../doc/otherformats/xmltex/base/manual.html | 882 +++++++++++++++++++++ .../doc/otherformats/xmltex/base/manual.tex | 4 + .../doc/otherformats/xmltex/base/manual.xml | 799 +++++++++++++++++++ .../doc/otherformats/xmltex/base/manual.xsl | 29 + .../otherformats/xmltex/base/portugeselatin1.xml | 7 + .../doc/otherformats/xmltex/base/readme.txt | 123 +++ .../doc/otherformats/xmltex/base/russiankoi8.xml | 9 + .../doc/otherformats/xmltex/base/russianutf8.xml | 7 + .../doc/otherformats/xmltex/base/testascii.cfg | 159 ++++ .../doc/otherformats/xmltex/base/testascii.tex | 4 + .../doc/otherformats/xmltex/base/testascii.xml | 22 + .../doc/otherformats/xmltex/base/testsec.tex | 5 + .../doc/otherformats/xmltex/base/testsec.xml | 77 ++ 16 files changed, 2154 insertions(+) create mode 100644 Master/texmf-dist/doc/otherformats/xmltex/base/englishutf16.xml create mode 100644 Master/texmf-dist/doc/otherformats/xmltex/base/englishutf8.xml create mode 100644 Master/texmf-dist/doc/otherformats/xmltex/base/langtest.xml create mode 100644 Master/texmf-dist/doc/otherformats/xmltex/base/manual.html create mode 100644 Master/texmf-dist/doc/otherformats/xmltex/base/manual.tex create mode 100644 Master/texmf-dist/doc/otherformats/xmltex/base/manual.xml create mode 100644 Master/texmf-dist/doc/otherformats/xmltex/base/manual.xsl create mode 100644 Master/texmf-dist/doc/otherformats/xmltex/base/portugeselatin1.xml create mode 100644 Master/texmf-dist/doc/otherformats/xmltex/base/readme.txt create mode 100644 Master/texmf-dist/doc/otherformats/xmltex/base/russiankoi8.xml create mode 100644 Master/texmf-dist/doc/otherformats/xmltex/base/russianutf8.xml create mode 100644 Master/texmf-dist/doc/otherformats/xmltex/base/testascii.cfg create mode 100644 Master/texmf-dist/doc/otherformats/xmltex/base/testascii.tex create mode 100644 Master/texmf-dist/doc/otherformats/xmltex/base/testascii.xml create mode 100644 Master/texmf-dist/doc/otherformats/xmltex/base/testsec.tex create mode 100644 Master/texmf-dist/doc/otherformats/xmltex/base/testsec.xml (limited to 'Master/texmf-dist/doc/otherformats/xmltex/base') diff --git a/Master/texmf-dist/doc/otherformats/xmltex/base/englishutf16.xml b/Master/texmf-dist/doc/otherformats/xmltex/base/englishutf16.xml new file mode 100644 index 00000000000..c51d565faf7 Binary files /dev/null and b/Master/texmf-dist/doc/otherformats/xmltex/base/englishutf16.xml differ diff --git a/Master/texmf-dist/doc/otherformats/xmltex/base/englishutf8.xml b/Master/texmf-dist/doc/otherformats/xmltex/base/englishutf8.xml new file mode 100644 index 00000000000..6710da9b143 --- /dev/null +++ b/Master/texmf-dist/doc/otherformats/xmltex/base/englishutf8.xml @@ -0,0 +1,6 @@ + +

+ Test + Hello World! +

+ diff --git a/Master/texmf-dist/doc/otherformats/xmltex/base/langtest.xml b/Master/texmf-dist/doc/otherformats/xmltex/base/langtest.xml new file mode 100644 index 00000000000..081cfe06833 --- /dev/null +++ b/Master/texmf-dist/doc/otherformats/xmltex/base/langtest.xml @@ -0,0 +1,21 @@ + + + + + + + +]> + + + +&englishutf8; +&englishutf16; +&portugeselatin1; +&russiankoi8; +&russianutf8; + + + diff --git a/Master/texmf-dist/doc/otherformats/xmltex/base/manual.html b/Master/texmf-dist/doc/otherformats/xmltex/base/manual.html new file mode 100644 index 00000000000..2c88af23dfa --- /dev/null +++ b/Master/texmf-dist/doc/otherformats/xmltex/base/manual.html @@ -0,0 +1,882 @@ + + + + + xmltex: A non validating (and not 100% + conforming) namespace aware XML parser implemented in TeX + + + + + + + + + + + +

	+ Numerical Algorithms Group: NAG +
	+ + xmltex: A non validating (and not 100% + conforming) namespace aware XML parser implemented in TeX + +

+ xmltex: A non validating (and not 100% + conforming) namespace aware XML parser implemented in TeX +

+ Date: 2000-02-02 +

+davidc@nag.co.uk +

+David Carlisle +

+Introduction +
+Installation +
+Using xmltex +
+Stopping xmltex +
+xmltex package files +
+XML processing +
+Accessing TeX +
+Bugs +
+Don't Read Past This Point +

+Introduction

+ +

+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. +

+ + +

+Installation

+ +

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 document.xml. +

+Using xmltex as an input to the LaTeX command

+ +

LaTeX requires a document in TeX syntax, not XML. To process +document.xml, first produce a two line file called +document.tex of the following form: +

+\def\xmlfile{document.xml}
+\input xmltex.tex
+

+ +Do not put any other commands in this file!

You may then process the document with either of the commands: +latex document or latex document.tex +or the equivalent procedure in your TeX environment. +

+ +

+Using xmltex as a TeX format built on LaTeX

+ +

+You may prefer to set up xmltex as a format in its own right. +This may speed things up slightly (as xmltex.tex 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 +.tex wrapper.

To make a format you will need a command such as the following, +depending on your TeX system. +

+initex &latex xmltex
+initex \&latex xmltex
+tex -ini &latex xmltex
+tex -ini \&latex xmltex
+

This will produce a format file xmltex.fmt. You should then +be able to make a xmltex command by copying the way the +latex command is defined in terms of +latex.fmt. 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. + +

+ +

+ Making an xmltex format `from scratch'

+ +

+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 +latex.ltx then xmltex.tex. 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 latex.ltx you could in principle +use a modified docstrip install file and produce a +`cut down' latex that did not have features that are not going to be +used in xmltex. +

+Unfortunately the support for this method of building xmltex (and access +to non English hyphenation generally) is not fully designed and totally +undocumented.

+ + +

+Using xmltex

+ +

If the file begins with a Byte Order Mark, the default encoding + is set to utf-16. Otherwise the default encoding is utf-8. +
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 encoding.xmt 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.) +
If the document has a DOCTYPE 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 + .xmt extension) will be loaded. +
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. +
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. +
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.) +

+The xmltex Catalogue

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: +

+\NAMESPACE{URI}{xmt-file}
+\PUBLIC{FPI}{file}
+\SYSTEM{URI}{file}
+\NAME{element-name}{xmt-file}
+\XMLNS{element-name}{URI}
+

+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 \XMLNS 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 <html> to be coerced into +the xhtml namespace.

These commands may be placed in a configuration file, either +xmltex.cfg, in which case they apply to all documents, +or in a configuration file `\jobname.cfg' (eg +document.cfg in the example in the Introduction) in which +case the commands just apply to the specified document. +

+ + +

+Configuring xmltex

+ +

In addition to the `catalogue' commands described earlier there are +other commands that may be placed in the configuration files. + +

+\xmltraceonly +
+
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.
+
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 +\xmltraceonly and \jobname.cfg is empty.
+
+\xmltraceoff +
+
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.
+
+
\inputonce{xmt-file}
+
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.
+
+
+\UnicodeCharacter{hex-or-dec}{tex-code}
+
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 +`x'.
+
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.
+
+\ActivateASCII{hex-or-dec}
+
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.
+
Some ASCII characters are activated by default. The list is +essentially those characters with special meanings to either TeX or +XML.
+

+If a format is being made, there are essentially two copies of +xmltex.cfg 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 +xmltex.cfg may be used in the input path of `normal' TeX, +this will then be used for additional information loaded each run.

In either case, a separate configuration file specific to the given +XML document may also be used (which is loaded immediately after +xmltex.cfg). +

+ + + +

+Stopping xmltex

+ +

xmltex should stop after the end of the document +element has been processed. If things go wrong and +you end up at the interactive +* prompt you might want to exit with +<?xmltex \stop?>). +

+ + +

+xmltex package files

+ +

+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 \LoadClass{article}, or +alternatively it may cause some XML element in the document to +execute \documentclass{article}. In either case the document will +suffer the dubious benefit of being formatted based on the style +implemented in article.cls. 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.

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 not ignored.

The available commands are: + +

+
+\FileEncoding{encoding}
+
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.
+
+
+\DeclareNamespace{prefix}{URI}
+
This declares a prefix to be used in this file 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).
+
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 \DeclareNamespace 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.)
+
Three namespaces are predeclared. The null namespace (0), the XML +namespace (http://www.w3.org/1998/xml) (1) which is predeclaed +with prefix xml as specified in the Namespace Recommendation, +and the xmltex namespace +(http://www.dcarlisle.demon.co.uk/xmltex) (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). +
+
+
+ \XMLelement{element-qname}{attribute-spec} +{begin-code}{end-code}
+
This is similar to a LaTeX \newenvironment command.
+
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 \XMLattribute command +described below. +
+
+
+ \XMLelement{element-qname} +{attribute-spec} +{\xmlgrab}{end-code}
+
A special case of the above command (which may be better made into a + separate declaration) is to make the start-code just be the command + \xmlgrab. In this case the end-code has access to the + element content (in XML syntax) as #1. This content isn't + literally the same as the original document, namespaces, white space + and attribute quote symbols will all have been normalised. +
+
+ \XMLattribute{attribute-qname} +{command-name}{default}
+
This command may only be used in the argument to +\XMLelement. + 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. +
+
The special token \inherit 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.
+
If a TeX token such as \relax is used as the default +the element code may distinguish the case that the attribute is not used +in the document.
+
+ \XMLnamespaceattribute +{prefix}{attribute-qname} +{command-name}{default}
+
This command is similar to \XMLattribute + but is used at the top level of the package file, not in the argument +to \XMLelement. It is equivalent to specifying the +attribute in every 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.
+
+
+\XMLentity{name}{code}
+
Declare an (internal parsed) entity, this is equivalent to a +<!ENTITY declaration, except that the +replacement text is specified in TeX syntax.
+
+
+\XMLname{name}{command-name}
+
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 +\XMLelement 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 \ifx\XML@parent +which will allow element code to take different actions depending on +the parent of the current element.
+
+
+\XMLstring{command-name}<>XML Data</>
+
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.
+
It should also be used for defining any strings used to +in comparison tests with strings occurring in the XML document. +Using \XMLstring rather than \def ensures +that the characters and encodings in the string are correctly normalised.
+

+ +

+XML processing

+ +

+xmltex tries as far as possible to be a fully conforming non +validating parser. It fails in the following respects. +

Error reporting is virtually non existent. Names are not checked + against the list of allowed characters, and various other + constraints are not enforced. +
+
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 \input 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 \includegraphics.
+
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 \XMLattribute.
+
+
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).
+
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.
+

+ +

+Accessing TeX

+ +

In theory you should be able to control the document just be suitable +code specified by \XMLelement and friends, but sometimes it may be +necessary to `tweak' the output by placing commands directly in the +source.

Two mechanisms are availalable to do this. +

+
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 \contentsline which might be an element + accessed by <xmltex:contentsline>… where the xmltex + prefix is declared on this or a parent element to be + xmlns:xmltex="http://www.dcarlisle.demon.co.uk/xmltex".
+
As the xmltex namespace is declared but currently empty, a more + useful variant of this might be:
+
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 \NAMESPACE). + For instance if you put <clearpage xmlns="/my/tex/tweak"/> + in your document, this will force a page break if you have at + suitable points, \NAMESPACE{/my/tex/tweak}{tweak.xmt} + and +
```
+\DeclareNamespace{tweak}{"/my/tex/tweak"}
+\XMLelement{tweak:clearpage}{\clearpage}
+
```
+
+
A second different mechanism is available, to use XML processing + instructions. A Processing Instruction of the form: +<?xmltex> TeX commands ?> +will execute the TeX commands.
+

+ +

+ + +

+Bugs

+ +

None, of course.

+ + +

+Don't Read Past This Point

+ +

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)

+ +

+Input Encodings and States

+ +

At any point while processing a document, xmltex is in one of two +states: tex or xml.

+States

In the xml state, + < 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 \ActivateASCII command, which allows special +typesetting rules to be activated for the characters, at some cost in +processing speed.

In the tex state, +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 +\XMLelement and releated commands.

+ +

+Encodings

Whenever a new (XML or TeX) file is input by the xmltex system the +encoding 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 \FileEncoding command for TeX +files. Note that the encoding mechanism only is triggered +by xmltex file includes. Once an xmltex package file is loaded it may +include other TeX files by \input or +\includepackage 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.

Note that if the \includepackage 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 \includepackage is included in code specified +by \XMLelement, 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.

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.

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 encoding.xmt (in lowercase, +on case sensitive systems) this should consist of a series of +\InputCharacter 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 expansion +and so ligatures and inter letter kerns will be preserved. (Conversely +if characers are accessed by character references, Ӓ 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. +

+ + + +

+xmltex Package Commands

+ +

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 \XMLElement. +

+
+\ignorespaces +
+
This is actually a TeX primitive +(for the moment!)
+
+
+\obeyspaces +
+
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.)
+
+
+\obeylines +
+
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.)
+
+
+\xmltexfirstchild#1\@ +
+
If the start-code for an element is specified as +\xmlgrab then the end-code may use +#1 in order to execute the element content. Sometimes you +do not want all of the content. The a construction (with currently +unpleasant syntax) \xmltexfirstchild#1\@ will just evaluate +the first child element of the content, discarding the remaining +elements.
+
+
+\xmltextwochildren\csa\csb#1 +
+
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 +\csa{child-1}\csb{child-2 +So either two TeX command smay be supplied, one will be applied to +each child, or the second argument may be {} in which case +the first argument may be a TeX command that takes two arguments. +For example the code for MathMl frac might be +
```
+\XMLelement{m:mfrac}
+  {}
+  {\xmlgrab}
+  {\xmltextwochildren\frac{}#1}
+
```
+
+
+
+\xmltexthreechildren\csa\csb\csc#1 +
+
As above, but more so.
+
+
+\xmltexforall\csa{#1} +
+
The TeX command \csa is called repeatedly, +taking each child element of the current element as argument +on each iteration. As a convenience the command \xml@name +is defined before each iteration to have the (internal, normalised) +name of the element being processed.
+
+
+\NDATAEntity\csa\csb\attvalue +
+
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 \attvalue. is a TeX command holding the value of an +attribute, as declared in \XMLattribute then +\NDATAEntity\csa\csb\attvalue applies the two TeX +commands \csa and \csb to the notation type +and the value, in a way exactly corresponding to +\xmltextwochildren so for example the XML document for this +manual specifies +
```
+ <!NOTATION URL SYSTEM "" >
+ <!ENTITY lppl SYSTEM "http://www.latex-project.org/lppl.txt" NDATA URL>
+
```
+and this is handled by the following xmltex code +
```
+\XMLelement{xptr}
+ {\XMLattribute{doc}{\xptrdoc}{}}
+ {\NDATAEntity\xptrdoc\@gobble\url}
+ {}
+
```
+which saves the attribute value in \xptrdoc and then +discards the notation name (URL) and applies the command +\url to typeset the supplied URL. +
+

+ + + +

+Character Data Internals

+ +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

	int.	ext. xml	ext. mixed	csn typeout
d	xabc	xabc	xabc (12)	xabc (12)	xabc (12)
c	xab	xab	xab (12)	xab (12)	xab (12)
b	xa	xa	xa (12)	xa (12)	xa (12)
ax	x	x	x	x	x (12)	(!)
ay	x	x	x	{	x (12)	(e)
az	x	\az x	{	{	x (12)	(<)
<	<	<	<	<	< (12)	(<)

+ +

+ + + + + + +

+[NAG +| NAG +] +

+ Last updated: Date: 2000-02-02. +
Copyright 2000 David Carlisle, NAG + +

+ + diff --git a/Master/texmf-dist/doc/otherformats/xmltex/base/manual.tex b/Master/texmf-dist/doc/otherformats/xmltex/base/manual.tex new file mode 100644 index 00000000000..d788efe2fe9 --- /dev/null +++ b/Master/texmf-dist/doc/otherformats/xmltex/base/manual.tex @@ -0,0 +1,4 @@ +\def\xmlfile{manual.xml} +\input xmltex + + diff --git a/Master/texmf-dist/doc/otherformats/xmltex/base/manual.xml b/Master/texmf-dist/doc/otherformats/xmltex/base/manual.xml new file mode 100644 index 00000000000..610938913ff --- /dev/null +++ b/Master/texmf-dist/doc/otherformats/xmltex/base/manual.xml @@ -0,0 +1,799 @@ + + + + + + + + + + +]> + + + + + xmltex + + + +

+ This file is distributed under the LaTeX Project Public License + (LPPL) as found at . + Either version 1.0, or at your option, any later version. +

+ + + +

+ + + + + + + + February 2nd 2000 + David CarlisleUpdated) + January 24th 2000 + David CarlisleUpdated) + January 19th 2000 + David CarlisleUpdated) + January 18th 2000 + David CarlisleUpdated) + January 15th 2000 + David CarlisleUpdated) + January 10th 2000 + Sebastian Rahtzcorrections + January 10th 2000 + David CarlisleUpdated (in XML) + January 6th 2000 + Sebastian RahtzConverted to TEI XML + January 6th 2000 + David Carlislewritten in LaTeX + + + + + + + xmltex: A non validating (and not 100% + conforming) namespace aware XML parser implemented in &TeX; + + Date: 2000-02-02 + davidc@nag.co.uk + David Carlisle + + +

+Introduction +

+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. +

+ +

+Installation +

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 document.xml. +

+Using xmltex as an input to the &LaTeX; command +

&LaTeX; requires a document in &TeX; syntax, not XML. To process +document.xml, first produce a two line file called +document.tex of the following form: + +\def\xmlfile{document.xml} +\input xmltex.tex + + +Do not put any other commands in this file!

You may then process the document with either of the commands: +latex document or latex document.tex +or the equivalent procedure in your &TeX; environment. +

+Using xmltex as a &TeX; format built on &LaTeX; +

To make a format you will need a command such as the following, +depending on your &TeX; system. + +initex &latex xmltex +initex \&latex xmltex +tex -ini &latex xmltex +tex -ini \&latex xmltex +

This will produce a format file xmltex.fmt. You should then +be able to make a xmltex command by copying the way the +latex command is defined in terms of +latex.fmt. 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. + +

+ Making an xmltex format `from scratch' +

+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 +latex.ltx then xmltex.tex. 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 latex.ltx you could in principle +use a modified docstrip install file and produce a +`cut down' latex that did not have features that are not going to be +used in xmltex. +

+Unfortunately the support for this method of building xmltex (and access +to non English hyphenation generally) is not fully designed and totally +undocumented.

+Using xmltex +

+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. + + + If the file begins with a Byte Order Mark, the default encoding + is set to utf-16. Otherwise the default encoding is utf-8. + + 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 encoding.xmt 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.) + + If the document has a DOCTYPE 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 + .xmt extension) will be loaded. + + 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. + + 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. + + 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.) + + +

The xmltex Catalogue +

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: + +\NAMESPACE{URI}{xmt-file} +\PUBLIC{FPI}{file} +\SYSTEM{URI}{file} +\NAME{element-name}{xmt-file} +\XMLNS{element-name}{URI} + +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 \XMLNS 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 <html> to be coerced into +the xhtml namespace.

+ +

+Configuring xmltex +

In addition to the `catalogue' commands described earlier there are +other commands that may be placed in the configuration files. + + +

\xmltraceonly

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.

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 +\xmltraceonly and \jobname.cfg is empty.

+ +

\xmltraceoff

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.

+ + +

\inputonce{xmt-file}

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.

+ +

\UnicodeCharacter{hex-or-dec}{tex-code}

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 +`x'.

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.

+ +

\ActivateASCII{hex-or-dec}

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.

Some ASCII characters are activated by default. The list is +essentially those characters with special meanings to either &TeX; or +XML.

+ + + +

+If a format is being made, there are essentially two copies of +xmltex.cfg 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 +xmltex.cfg may be used in the input path of `normal' &TeX;, +this will then be used for additional information loaded each run.

In either case, a separate configuration file specific to the given +XML document may also be used (which is loaded immediately after +xmltex.cfg). +

+ +

+Stopping xmltex +

xmltex should stop after the end of the document +element has been processed. If things go wrong and +you end up at the interactive +* prompt you might want to exit with +]]>). +

+ +

+xmltex package files +

+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 \LoadClass{article}, or +alternatively it may cause some XML element in the document to +execute \documentclass{article}. In either case the document will +suffer the dubious benefit of being formatted based on the style +implemented in article.cls. 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.

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 not ignored.

The available commands are: + + +

\FileEncoding{encoding}

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.

+ + +

\DeclareNamespace{prefix}{URI}

This declares a prefix to be used in this file 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).

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 \DeclareNamespace 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.)

Three namespaces are predeclared. The null namespace (0), the XML +namespace (http://www.w3.org/1998/xml) (1) which is predeclaed +with prefix xml as specified in the Namespace Recommendation, +and the xmltex namespace +(http://www.dcarlisle.demon.co.uk/xmltex) (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). +

+ +

+ \XMLelement{element-qname}{attribute-spec} +{begin-code}{end-code}

This is similar to a &LaTeX; \newenvironment command.

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 \XMLattribute command +described below. +

+ +

+ \XMLelement{element-qname} +{attribute-spec} +{\xmlgrab}{end-code}

A special case of the above command (which may be better made into a + separate declaration) is to make the start-code just be the command + \xmlgrab. In this case the end-code has access to the + element content (in XML syntax) as #1. This content isn't + literally the same as the original document, namespaces, white space + and attribute quote symbols will all have been normalised. +

+ +

+ \XMLattribute{attribute-qname} +{command-name}{default}

This command may only be used in the argument to +\XMLelement. + 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. +

The special token \inherit 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.

If a &TeX; token such as \relax is used as the default +the element code may distinguish the case that the attribute is not used +in the document.

+ +

+ \XMLnamespaceattribute +{prefix}{attribute-qname} +{command-name}{default}

This command is similar to \XMLattribute + but is used at the top level of the package file, not in the argument +to \XMLelement. It is equivalent to specifying the +attribute in every 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.

+ + +

\XMLentity{name}{code}

Declare an (internal parsed) entity, this is equivalent to a + declaration, except that the +replacement text is specified in &TeX; syntax.

+ + +

\XMLname{name}{command-name}

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 +\XMLelement 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 \ifx\XML@parent +which will allow element code to take different actions depending on +the parent of the current element.

+ + + +

\XMLstring{command-name}<>XML Data</>

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.

It should also be used for defining any strings used to +in comparison tests with strings occurring in the XML document. +Using \XMLstring rather than \def ensures +that the characters and encodings in the string are correctly normalised.

+ + + + + +

+XML processing +

+xmltex tries as far as possible to be a fully conforming non +validating parser. It fails in the following respects. + + Error reporting is virtually non existent. Names are not checked + against the list of allowed characters, and various other + constraints are not enforced. + +

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 \input 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 \includegraphics.

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 \XMLattribute.

+ +

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).

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.

+ + + +

+Accessing &TeX; +

Two mechanisms are availalable to do this. + +

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 \contentsline which might be an element + accessed by xmltex:contentsline&ldots; where the xmltex + prefix is declared on this or a parent element to be + xmlns:xmltex="http://www.dcarlisle.demon.co.uk/xmltex".

As the xmltex namespace is declared but currently empty, a more + useful variant of this might be:

+ + 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 \NAMESPACE). + For instance if you put clearpage xmlns="/my/tex/tweak"/ + in your document, this will force a page break if you have at + suitable points, \NAMESPACE{/my/tex/tweak}{tweak.xmt} + and + +\DeclareNamespace{tweak}{"/my/tex/tweak"} +\XMLelement{tweak:clearpage}{\clearpage} + + +

A second different mechanism is available, to use XML processing + instructions. A Processing Instruction of the form: +?xmltex &TeX; commands ?> +will execute the &TeX; commands.

+ + + +

+ +

+Bugs +

None, of course.

+ +

+Don't Read Past This Point +

+ +

+Input Encodings and States +

At any point while processing a document, xmltex is in one of two +states: tex or xml.

States +

In the xml state, + < and & are the only two characters that +trigger special markup codes. Other characters, such as !, >, =, +&ldots; 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 \ActivateASCII command, which allows special +typesetting rules to be activated for the characters, at some cost in +processing speed.

In the tex state, +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 +\XMLelement and releated commands.

Encodings +

Whenever a new (XML or &TeX;) file is input by the xmltex system the +encoding 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 \FileEncoding command for &TeX; +files. Note that the encoding mechanism only is triggered +by xmltex file includes. Once an xmltex package file is loaded it may +include other &TeX; files by \input or +\includepackage 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.

Note that if the \includepackage 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 \includepackage is included in code specified +by \XMLelement, 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.

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.

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 encoding.xmt (in lowercase, +on case sensitive systems) this should consist of a series of +\InputCharacter 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 expansion +and so ligatures and inter letter kerns will be preserved. (Conversely +if characers are accessed by character references, Ӓ 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. +

+ +

+xmltex Package Commands +

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 \XMLElement. + + +

\ignorespaces

This is actually a &TeX; primitive +(for the moment!)

+ + +

\obeyspaces

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;.)

+ + +

\obeylines

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;.)

+ + +

\xmltexfirstchild#1\@

If the start-code for an element is specified as +\xmlgrab then the end-code may use +#1 in order to execute the element content. Sometimes you +do not want all of the content. The a construction (with currently +unpleasant syntax) \xmltexfirstchild#1\@ will just evaluate +the first child element of the content, discarding the remaining +elements.

+ + +

\xmltextwochildren\csa\csb#1

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 +\csa{child-1}\csb{child-2 +So either two &TeX; command smay be supplied, one will be applied to +each child, or the second argument may be {} in which case +the first argument may be a &TeX; command that takes two arguments. +For example the code for MathMl frac might be + +\XMLelement{m:mfrac} + {} + {\xmlgrab} + {\xmltextwochildren\frac{}#1} + +

+ + +

\xmltexthreechildren\csa\csb\csc#1

As above, but more so.

+ +

\xmltexforall\csa{#1}

The &TeX; command \csa is called repeatedly, +taking each child element of the current element as argument +on each iteration. As a convenience the command \xml@name +is defined before each iteration to have the (internal, normalised) +name of the element being processed.

+ + +

\NDATAEntity\csa\csb\attvalue

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 \attvalue. is a &TeX; command holding the value of an +attribute, as declared in \XMLattribute then +\NDATAEntity\csa\csb\attvalue applies the two &TeX; +commands \csa and \csb to the notation type +and the value, in a way exactly corresponding to +\xmltextwochildren so for example the XML document for this +manual specifies + + ]]> + +and this is handled by the following xmltex code + + +which saves the attribute value in \xptrdoc and then +discards the notation name (URL) and applies the command +\url to typeset the supplied URL. +

+ + + +

+ +

+Character Data Internals +

+ + + int.ext. xml +ext. mixedcsn typeout + + + +dxabcxabc +xabc (12)xabc (12)xabc (12) + + + +cxabxab +xab (12)xab (12)xab (12) + + + +bxaxa +xa (12)xa (12)xa (12) + + + +axxx +xxx (12) +(!) + + +ayxx +x{x (12) +(e) + + +azx\az x +{{x (12) +(<) + + +<<< +<<< (12) +(<) + +
+ +

+ + +

+ + + + + + + diff --git a/Master/texmf-dist/doc/otherformats/xmltex/base/manual.xsl b/Master/texmf-dist/doc/otherformats/xmltex/base/manual.xsl new file mode 100644 index 00000000000..0bf8a7234ed --- /dev/null +++ b/Master/texmf-dist/doc/otherformats/xmltex/base/manual.xsl @@ -0,0 +1,29 @@ + + +-2 +manual +-1 +center + +true +Numerical Algorithms Group: NAG +http://www.nag.co.uk/ +NAG +http://www.tei-c.org/ +NAG +http://www.nag.co.uk/ +NAG + + +true + + Copyright 2000 David Carlisle, NAG + + + + + + + + diff --git a/Master/texmf-dist/doc/otherformats/xmltex/base/portugeselatin1.xml b/Master/texmf-dist/doc/otherformats/xmltex/base/portugeselatin1.xml new file mode 100644 index 00000000000..a13fb0b4f3e --- /dev/null +++ b/Master/texmf-dist/doc/otherformats/xmltex/base/portugeselatin1.xml @@ -0,0 +1,7 @@ + + + + Teste + Ol� Mundo! + + diff --git a/Master/texmf-dist/doc/otherformats/xmltex/base/readme.txt b/Master/texmf-dist/doc/otherformats/xmltex/base/readme.txt new file mode 100644 index 00000000000..fb2ddfcc088 --- /dev/null +++ b/Master/texmf-dist/doc/otherformats/xmltex/base/readme.txt @@ -0,0 +1,123 @@ + + xmltex.tex + ========== + +Copyright 2000 David Carlisle + +This collection of files is distributed under the LaTeX Project Public +License a (LPPL) as found at http://www.latex-project.org/lppl.txt +Either version 1.0, or at your option, any later version. + + +xmltex is a system for typesetting XML files with TeX. It may be used +on its own or in conjunction with another TeX format. (LaTeX is +assumed for most examples). + +xmltex supports the XML Namespace Recommendation. Arbitrary prefixes +may be used in document instances, and in definition files. It +supports any encoding that matches ASCII in the first 127 positions. +UTF-8, latin-1 and KOI8-R are included in the distribution, other +encodings may be trivially added. + +Further documentation may be obtained by running manual.tex through +LaTeX. + +The distribution of 2000-01-18 consists of: + +* readme.txt + This file. + + + +* xmltex.tex + The source code for xmltex. + +* xmltex.cfg + Configuration file for xmltex, with sufficient information about + Unicode to typeset the latin-1 and Cyrillic examples in the + distribution, and information about the namespaces and dtd used in the + examples. + +* iso-8859-1.xmt + internal file defining latin-1 input encoding + +* utf-16.xmt + place holder for a file supporting UTF-16 (not really possible with + standard TeX). + +* koi8-r.xmt + internal file defining the Cyrillic encoding KOI8-R. + Support for any 8 bit encoding that matches ASCII for the first 127 + positions may be added by copying the format of file. + + + +* manual.xml + The manual for xmltex (marked up in TEI XML). + +* manual.tex + Support files for processing the manual. + LaTeX manual.tex with your standard LaTeX format, to obtain + the typeset documentation. + +* manual.html manual.xsl + HTML version of manual, generated via XSL (thanks to Sebastian Rahtz). + + +* tei.xmt + xmltex package file for TEI XML markup as used in the xmltex manual. + (The much of this file was implemented by Sebastian Rahtz) + +* mathml2.xmt + A small start towards an xmltex package for MathML2. + Used in one of the test files. + +* sec.xmt + A package for a small XML document language used in sone of the test + files. + + + +* langtest.xml langtest.tex + This test example file demonstrates a small `hello world' document in + different languages and different encodings all input into the same + document. Note that the table of contents is constructed correctly + despite the fact taht different encodings are used. Also note that + typesetting commands only need to be defined once, irrespective of + encoding. So the Cyrillic command for `document' looks quite different + in the utf-8 and koi8-r files, but the same definitions work in both + cases. + +* englishutf8.xml + English markup in utf-8, used by langtest.xml + +* English markup in utf-16, used by langtest.xml. + Note that utf-16 support is limited to the latin-1 range (it just + consists of ignoring the null byte). + +* portugeselatin1.xml + Portugese example, note that the markup is in latin 1, but the + definitions (in langtest.cfg are in utf-8). + +* russiankoi8.xml + Russian Example, KOI8-R. This test file typesets Cyrillic letters + This assumes the AMS `OT2' encoded cyrillic fonts are present on your + system. (Better support for cyrillic is available with the T2 encoded + fonts but these are not used in this example to enable the example + to be run on as many sites as possible.) + +* russiankutf8.xml + Russian Example, utf-8. + + +* testsec.xml testsec.tex + A small example testing varius features. + The final section includes some tests of MathML. + Note that the elements defined in this file use a namespace prefix + even though the elements in the XML document (testsec) do not. + +* testascii.xml testascii.tex testascii.cfg + A test file in which all characters are activated, allowing for some + special effects. (Here vowels are red and numbers are old style.) + + \ No newline at end of file diff --git a/Master/texmf-dist/doc/otherformats/xmltex/base/russiankoi8.xml b/Master/texmf-dist/doc/otherformats/xmltex/base/russiankoi8.xml new file mode 100644 index 00000000000..2404d9535be --- /dev/null +++ b/Master/texmf-dist/doc/otherformats/xmltex/base/russiankoi8.xml @@ -0,0 +1,9 @@ + + +<�� ="��"> + <��> + <��>�� + �� ! + + + diff --git a/Master/texmf-dist/doc/otherformats/xmltex/base/russianutf8.xml b/Master/texmf-dist/doc/otherformats/xmltex/base/russianutf8.xml new file mode 100644 index 00000000000..735c9151641 --- /dev/null +++ b/Master/texmf-dist/doc/otherformats/xmltex/base/russianutf8.xml @@ -0,0 +1,7 @@ +<документ атт="русский" > + <раздел> + <голова>Тест + Здравствуй Мир! + + + diff --git a/Master/texmf-dist/doc/otherformats/xmltex/base/testascii.cfg b/Master/texmf-dist/doc/otherformats/xmltex/base/testascii.cfg new file mode 100644 index 00000000000..2fc2494465e --- /dev/null +++ b/Master/texmf-dist/doc/otherformats/xmltex/base/testascii.cfg @@ -0,0 +1,159 @@ + +\ActivateASCII{0} +\ActivateASCII{1} +\ActivateASCII{2} +\ActivateASCII{3} +\ActivateASCII{4} +\ActivateASCII{5} +\ActivateASCII{6} +\ActivateASCII{7} +\ActivateASCII{8} +\ActivateASCII{9} +\ActivateASCII{0} +\ActivateASCII{11} +\ActivateASCII{12} +\ActivateASCII{13} +\ActivateASCII{14} +\ActivateASCII{15} +\ActivateASCII{16} +\ActivateASCII{17} +\ActivateASCII{18} +\ActivateASCII{19} +\ActivateASCII{20} +\ActivateASCII{21} +\ActivateASCII{22} +\ActivateASCII{23} +\ActivateASCII{24} +\ActivateASCII{25} +\ActivateASCII{26} +\ActivateASCII{27} +\ActivateASCII{28} +\ActivateASCII{29} +\ActivateASCII{30} +\ActivateASCII{31} +\ActivateASCII{32} +\ActivateASCII{33} +\ActivateASCII{34} +\ActivateASCII{35} +\ActivateASCII{36} +\ActivateASCII{37} +\ActivateASCII{38} +\ActivateASCII{39} +\ActivateASCII{30} +\ActivateASCII{31} +\ActivateASCII{32} +\ActivateASCII{33} +\ActivateASCII{34} +\ActivateASCII{35} +\ActivateASCII{36} +\ActivateASCII{37} +\ActivateASCII{38} +\ActivateASCII{39} +\ActivateASCII{40} +\ActivateASCII{41} +\ActivateASCII{42} +\ActivateASCII{43} +\ActivateASCII{44} +\ActivateASCII{45} +\ActivateASCII{46} +\ActivateASCII{47} +\ActivateASCII{48} +\ActivateASCII{49} +\ActivateASCII{50} +\ActivateASCII{51} +\ActivateASCII{52} +\ActivateASCII{53} +\ActivateASCII{54} +\ActivateASCII{55} +\ActivateASCII{56} +\ActivateASCII{57} +\ActivateASCII{58} +\ActivateASCII{59} +\ActivateASCII{60} +\ActivateASCII{61} +\ActivateASCII{62} +\ActivateASCII{63} +\ActivateASCII{64} +\ActivateASCII{65} +\ActivateASCII{66} +\ActivateASCII{67} +\ActivateASCII{68} +\ActivateASCII{69} +\ActivateASCII{70} +\ActivateASCII{71} +\ActivateASCII{72} +\ActivateASCII{73} +\ActivateASCII{74} +\ActivateASCII{75} +\ActivateASCII{76} +\ActivateASCII{77} +\ActivateASCII{78} +\ActivateASCII{79} +\ActivateASCII{80} +\ActivateASCII{81} +\ActivateASCII{82} +\ActivateASCII{83} +\ActivateASCII{84} +\ActivateASCII{85} +\ActivateASCII{86} +\ActivateASCII{87} +\ActivateASCII{88} +\ActivateASCII{89} +\ActivateASCII{90} +\ActivateASCII{91} +\ActivateASCII{92} +\ActivateASCII{93} +\ActivateASCII{94} +\ActivateASCII{95} +\ActivateASCII{96} +\ActivateASCII{97} +\ActivateASCII{98} +\ActivateASCII{99} +\ActivateASCII{100} +\ActivateASCII{101} +\ActivateASCII{102} +\ActivateASCII{103} +\ActivateASCII{104} +\ActivateASCII{105} +\ActivateASCII{106} +\ActivateASCII{107} +\ActivateASCII{108} +\ActivateASCII{109} +\ActivateASCII{110} +\ActivateASCII{111} +\ActivateASCII{112} +\ActivateASCII{113} +\ActivateASCII{114} +\ActivateASCII{115} +\ActivateASCII{116} +\ActivateASCII{117} +\ActivateASCII{118} +\ActivateASCII{119} +\ActivateASCII{120} +\ActivateASCII{121} +\ActivateASCII{122} +\ActivateASCII{123} +\ActivateASCII{124} +\ActivateASCII{125} +\ActivateASCII{126} +\ActivateASCII{127} + + +\UnicodeCharacter{105}{\textcolor{red}{i}} +\UnicodeCharacter{97}{\textcolor{red}{a}} +\UnicodeCharacter{101}{\textcolor{red}{e}} +\UnicodeCharacter{105}{\textcolor{red}{i}} +\UnicodeCharacter{111}{\textcolor{red}{o}} +\UnicodeCharacter{117}{\textcolor{red}{u}} + +\UnicodeCharacter{48}{\textzerooldstyle} +\UnicodeCharacter{49}{\textoneoldstyle} +\UnicodeCharacter{50}{\texttwooldstyle} +\UnicodeCharacter{51}{\textthreeoldstyle} +\UnicodeCharacter{52}{\textfouroldstyle} +\UnicodeCharacter{53}{\textfiveoldstyle} +\UnicodeCharacter{54}{\textsixoldstyle} +\UnicodeCharacter{55}{\textsevenoldstyle} +\UnicodeCharacter{56}{\texteightoldstyle} +\UnicodeCharacter{57}{\textnineoldstyle} + diff --git a/Master/texmf-dist/doc/otherformats/xmltex/base/testascii.tex b/Master/texmf-dist/doc/otherformats/xmltex/base/testascii.tex new file mode 100644 index 00000000000..fccb7db53cc --- /dev/null +++ b/Master/texmf-dist/doc/otherformats/xmltex/base/testascii.tex @@ -0,0 +1,4 @@ +\def\xmlfile{testascii.xml} +\input xmltex + + diff --git a/Master/texmf-dist/doc/otherformats/xmltex/base/testascii.xml b/Master/texmf-dist/doc/otherformats/xmltex/base/testascii.xml new file mode 100644 index 00000000000..32a23354a6c --- /dev/null +++ b/Master/texmf-dist/doc/otherformats/xmltex/base/testascii.xml @@ -0,0 +1,22 @@ + + + +Heading iii example (123) +

+This is an example of an experimental mode in which some +of the characters in the standard `ascii' range are given special +definitions. Vowels are made red, and digits (0123456789) are typeset in +oldstyle form. Note that you may still use the sepcial letters as part +of XML names, for example the follwoin word is set using the element `it': +italic. +

+While the special definitions apply to any text originating in the XML +document they do not apply to texts coming from the TeX code and in +particular from LaTeX packages. Note in this example that the +section numbers are not old style and the vowels in the word `contents' +are not coloured. +

+ + + diff --git a/Master/texmf-dist/doc/otherformats/xmltex/base/testsec.tex b/Master/texmf-dist/doc/otherformats/xmltex/base/testsec.tex new file mode 100644 index 00000000000..36136d92a3c --- /dev/null +++ b/Master/texmf-dist/doc/otherformats/xmltex/base/testsec.tex @@ -0,0 +1,5 @@ + +\def\xmlfile{testsec.xml} +\input xmltex.tex + + diff --git a/Master/texmf-dist/doc/otherformats/xmltex/base/testsec.xml b/Master/texmf-dist/doc/otherformats/xmltex/base/testsec.xml new file mode 100644 index 00000000000..533e2663b45 --- /dev/null +++ b/Master/texmf-dist/doc/otherformats/xmltex/base/testsec.xml @@ -0,0 +1,77 @@ + +some text some text some text.

" > + +]> + + + +lll + + This+&<> code 111 {\tt 222} 333 +

The first section.

+ + + + This+]]> code 999 {\tt 222} 333 +

The second section.

+ + + + +

abc+xyz q (1:& 2:&)

+ +&xxx;&xxx;&xxx;&xxx;&xxx; +&xxx;&xxx;&xxx;&xxx;&xxx; + + + Some utf8 [áéíóú] and some ascii [^^c3^^a1^^c3^^a9^^c3^^ad^^c3^^b3^^c3^^ba] +

and some more áéíóú

+ + + +&xxx;&xxx;&xxx;&xxx;&xxx; +&xxx;&xxx;&xxx;&xxx;&xxx; + + + The End +

The last section.

+ + +

+ {a + b}_{2} +

+ + +

+ \sqrt[3]{xxx - b} +

+ + +

+ +_{xxx}^{+} +

+ + +

+ (+, +^{xxx + 4 +}, +) +
+ \{+, +^{xxx + 4 +}, +] +
+

+ + \ No newline at end of file -- cgit v1.2.3

Numerical Algorithms Group: NAG

+ xmltex: A non validating (and not 100% + conforming) namespace aware XML parser implemented in TeX +

+ xmltex: A non validating (and not 100% + conforming) namespace aware XML parser implemented in TeX +

+davidc@nag.co.uk +

+David Carlisle +

Contents

+Introduction

+Installation

+Using xmltex as an input to the LaTeX command

+Using xmltex as a TeX format built on LaTeX

+ Making an xmltex format `from scratch'

+Using xmltex

+The xmltex Catalogue

+Configuring xmltex

+Stopping xmltex

+xmltex package files

+XML processing

+Accessing TeX

+Bugs

+Don't Read Past This Point

+Input Encodings and States

+States

+Encodings

+xmltex Package Commands

+Character Data Internals