diff options
author | Norbert Preining <norbert@preining.info> | 2019-09-02 13:46:59 +0900 |
---|---|---|
committer | Norbert Preining <norbert@preining.info> | 2019-09-02 13:46:59 +0900 |
commit | e0c6872cf40896c7be36b11dcc744620f10adf1d (patch) | |
tree | 60335e10d2f4354b0674ec22d7b53f0f8abee672 /support/gellmu/doc/glman.xhtml |
Initial commit
Diffstat (limited to 'support/gellmu/doc/glman.xhtml')
-rw-r--r-- | support/gellmu/doc/glman.xhtml | 3648 |
1 files changed, 3648 insertions, 0 deletions
diff --git a/support/gellmu/doc/glman.xhtml b/support/gellmu/doc/glman.xhtml new file mode 100644 index 0000000000..ba73f7fefa --- /dev/null +++ b/support/gellmu/doc/glman.xhtml @@ -0,0 +1,3648 @@ +<?xml version="1.0" encoding="UTF-8"?> +<?xml-stylesheet type="text/css" href="../webstyle/mxh.css"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1 plus MathML 2.0//EN" "http://www.w3.org/Math/DTD/mathml2/xhtml-math11-f.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"> +<head> +<link rel="stylesheet" type="text/css" href="../webstyle/mxh.css" /> +<meta name="surtitle" content="The GELLMU Manual" /> +<meta name="title" content="The GELLMU Manual" /> +<meta name="subtitle" content="Version 0.8.4 Release, July 2007" /> +<meta name="author" content="William F. Hammond" /> +<title>The GELLMU Manual</title> +</head> +<body> +<h1 class="display">The GELLMU Manual</h1> +<h4 class="display">Version 0.8.4 Release, July 2007</h4> +<h2 class="display">William F. Hammond</h2> +<h4 class="display"> +Dept. of Mathematics & Statistics<br + /> University at Albany<br + /> Albany, New York 12222 (USA)</h4> +<p class="display">Email: <kbd>hammond@math.albany.edu</kbd></p> +<h4 class="display">Revision of July 5, 2007</h4> +<h5 class="display">Copyright © 2001–2007 William F. Hammond</h5> +<h3 class="display">ABSTRACT</h3> +<blockquote> + +<p>This is the manual for Generalized Extensible <em>LaTeX</em>-Like +Markup (GELLMU). The central focus in the GELLMU project is to tie +<em>LaTeX</em> to the worlds of SGML and XML by providing <em>LaTeX</em>-like markup +for writing documents under SGML and XML vocabularies (formally +known as document types). </p> + +<p>The Manual explains the distinction between <em>basic</em> and +<em>advanced</em> use, provides a description of <em>regular</em> +GELLMU as an instance of advanced GELLMU, and discusses +the use of the didactic production system, which is the project's suite of +processors for working with regular GELLMU. </p> + +<p>The Manual also deals with the metacommands available when +writing GELLMU markup. One of these metacommands is the project's +emulation of <em>LaTeX</em>'s <em>newcommand</em>, which makes it possible to +have macros taking multiple arguments while writing for an SGML or +XML vocabulary. +</p> +</blockquote> +<div class="tableofcontents"> +<h3>Table of Contents</h3> +<dl class="tableofcontents"> +<dd>1  Introduction... <a href="#SU-1">*</a> +</dd><dd> +2  Basic GELLMU... <a href="#SU-2">*</a> +</dd><dd> +3  Metacommands... <a href="#SU-3">*</a> +<dl><dd> +3.1  \documenttype... <a href="#SU-3.1">*</a> +</dd><dd> +3.2  \newcommand... <a href="#SU-3.2">*</a> +</dd><dd> +3.3  \begin{} … \end{}... <a href="#SU-3.3">*</a> +</dd><dd> +3.4  \macro and \Macro... <a href="#SU-3.4">*</a> +</dd><dd> +3.5  Macro-Level Fronting of SGML Element Names... <a href="#SU-3.5">*</a> +</dd></dl></dd><dd> +4  Advanced GELLMU... <a href="#SU-4">*</a> +<dl><dd> +4.1  Illustrations.... <a href="#SU-4.1">*</a> +</dd><dd> +4.2  Multiple Argument/Option Syntax... <a href="#SU-4.2">*</a> +</dd><dd> +4.3  Limitation in Regard to XML... <a href="#SU-4.3">*</a> +</dd></dl></dd><dd> +5  The Didactic Document Type... <a href="#SU-5">*</a> +<dl><dd> +5.1  Suggestions and Caveats... <a href="#SU-5.1">*</a> +</dd><dd> +5.2  Markup Fundamentals... <a href="#SU-5.2">*</a> +<dl><dd> +5.2.1  Explicitly named commands.... <a href="#SU-5.2.1">*</a> +</dd><dd> +5.2.2  Certain single characters.... <a href="#SU-5.2.2">*</a> +</dd><dd> +5.2.3  Certain strings... <a href="#SU-5.2.3">*</a> +</dd></dl></dd><dd> +5.3  Large Structure... <a href="#SU-5.3">*</a> +</dd><dd> +5.4  Sectioning... <a href="#SU-5.4">*</a> +</dd><dd> +5.5  Labels, References, and Anchors... <a href="#SU-5.5">*</a> +<dl><dd> +5.5.1  Labels and Sequencing... <a href="#SU-5.5.1">*</a> +</dd><dd> +5.5.2  Anchors... <a href="#SU-5.5.2">*</a> +</dd><dd> +5.5.3  Example Emulating a <em>LaTeX</em> Counter... <a href="#SU-5.5.3">*</a> +</dd></dl></dd><dd> +5.6  General Usage for Sectional Units... <a href="#SU-5.6">*</a> +<dl><dd> +5.6.1  The Content Model... <a href="#SU-5.6.1">*</a> +</dd><dd> +5.6.2  The <em>LaTeX</em>-Like Form of General Usage... <a href="#SU-5.6.2">*</a> +</dd></dl></dd><dd> +5.7  <em>verbatim</em>, <em>verblist</em>, and +<em>manmac</em>... <a href="#SU-5.7">*</a> +</dd><dd> +5.8  Accents... <a href="#SU-5.8">*</a> +</dd><dd> +5.9  Tabular Environment Emulation... <a href="#SU-5.9">*</a> +</dd><dd> +5.10  Graphic Inclusions... <a href="#SU-5.10">*</a> +</dd></dl></dd><dd> +6  Mathematics in <em>article</em>... <a href="#SU-6">*</a> +<dl><dd> +6.1  General... <a href="#SU-6.1">*</a> +</dd><dd> +6.2  Assertions... <a href="#SU-6.2">*</a> +<dl><dd> +6.2.1  Examples... <a href="#SU-6.2.1">*</a> +</dd><dd> +6.2.2  Usage for <em>assertion</em>... <a href="#SU-6.2.2">*</a> +</dd></dl></dd><dd> +6.3  Equations and Equation Arrays... <a href="#SU-6.3">*</a> +</dd><dd> +6.4  The \mathsym Metacommand... <a href="#SU-6.4">*</a> +</dd></dl></dd><dd> +7  The Didactic Production System... <a href="#SU-7">*</a> +<dl><dd> +7.1  Permission... <a href="#SU-7.1">*</a> +</dd><dd> +7.2  Materials... <a href="#SU-7.2">*</a> +</dd><dd> +7.3  Other Required Software... <a href="#SU-7.3">*</a> +</dd><dd> +7.4  Using the syntactic translator... <a href="#SU-7.4">*</a> +<dl><dd> +7.4.1  Operation in Batch Mode... <a href="#SU-7.4.1">*</a> +</dd><dd> +7.4.2  Interactive Operation... <a href="#SU-7.4.2">*</a> +</dd><dd> +7.4.3  Interrupting the Syntactic +Translator... <a href="#SU-7.4.3">*</a> +</dd></dl></dd><dd> +7.5  Using the didactic production system... <a href="#SU-7.5">*</a> +<dl><dd> +7.5.1  Staged Design... <a href="#SU-7.5.1">*</a> +</dd><dd> +7.5.2  Default Staging... <a href="#SU-7.5.2">*</a> +</dd><dd> +7.5.3  Parsing with <em>nsgmls</em>... <a href="#SU-7.5.3">*</a> +</dd><dd> +7.5.4  Processing with <em>sgmlspl</em>... <a href="#SU-7.5.4">*</a> +</dd><dd> +7.5.5  Environmental Variables... <a href="#SU-7.5.5">*</a> +</dd></dl></dd></dl></dd><dd> +Appendix A  The GELLMU Archive... <a href="#SU-8">*</a> +</dd><dd> +Appendix B  Release Notes... <a href="#SU-9">*</a> +<dl><dd> +B.1  Comments on the Syntactic Translator... <a href="#SU-9.1">*</a> +</dd><dd> +B.2  Comments on the Didactic Production System... <a href="#SU-9.2">*</a> +<dl><dd> +B.2.1  Internationalization... <a href="#SU-9.2.1">*</a> +</dd><dd> +B.2.2  Document Type Definitions... <a href="#SU-9.2.2">*</a> +</dd><dd> +B.2.3  Translation to XML... <a href="#SU-9.2.3">*</a> +</dd><dd> +B.2.4  Translation to HTML... <a href="#SU-9.2.4">*</a> +</dd><dd> +B.2.5  Translation to <em>LaTeX</em>... <a href="#SU-9.2.5">*</a> +</dd><dd> +B.2.6  Future Plans... <a href="#SU-9.2.6">*</a> +</dd></dl></dd></dl></dd></dl> +</div> + +<div class="section"> +<h3>1.  <a id="SU-1"></a><a id="intro"></a>Introduction</h3> + +<p>GELLMU is an acronym for “Generalized Extensible +<em>LaTeX</em>-Like MarkUp”, which is the author's concept for using <em>LaTeX</em>-like +markup to write consciously for SGML document types such as HTML, +DocBook, TEI, or GELLMU's own didactic <em>LaTeX</em>-like document +type called <em>article</em>. </p> + +<p>It evolved from earlier thought about delineation of a coherent subset +of <em>LaTeX</em> commands with the property that if a <em>LaTeX</em> document used +only those commands then it could be translated with full reliability +to other formats including HTML so that documents could be prepared +both for print and for the web from a single source. </p> + +<p>Problems with this early thought during the years 1996–1997 included +the fact that there did not seem to be a community of <em>LaTeX</em> users +willing to focus on a narrow vocabulary and the fact then of a legacy +practice that mixed <em>LaTeX</em> commands freely with non-<em>LaTeX</em> <em>TeX</em> +commands. </p> + +<p>The present idea was crystalized in the summer of 1998 while the author +was looking at Ulrich Vieth's <em>LaTeX</em> markup for the <em>TeX</em> Directory +System (TDS) specification from the <em>TeX</em> User Group +(TUG), which now is physically realized in TUG's +<em>TeX</em>Live series of <em>TeX</em>-related software distributions on +CDrom. The HTML version of that specification was derived +through an intermediate ad hoc translation from <em>LaTeX</em> to +<em>Texinfo</em>, the language of the GNU Documentation System, +which is a robust hypertex system pre-dating HTML driven by <em>TeX</em> +the Program. </p> + +<p>In thinking about generalizing Vieth's ad hoc translation, which used +GNU <em>Emacs</em> Lisp (<em>Elisp</em>), one of the most widely available +<a href="http://www.gnu.org/">free</a> cross-platform programming languages +for which there is a free robust engine, the same engine that +underlies the interactive editing interface of <em>Emacs</em>, the author +realized that the structure of <em>Texinfo</em> is very much like that of an +authoring level SGML document type. From that idea it was a small +step to decide that one might profitably write <em>Elisp</em> code to use <em>LaTeX</em>-like +markup for the conscious writing of a new <em>LaTeX</em>-like <em>article</em> document +type. </p> + +<p>The idea, which by itself saves keystrokes, gains significant power +with the emulation of <em>LaTeX</em>'s <em>newcommand</em>. Although SGML +markup offers both subdocument inclusions and macro substitutions +using the notion of <em>entity</em>, there is no SGML-standard macro +facility that takes arguments. Moreover, GELLMU's <em>newcommand</em>, +which is, unlike <em>LaTeX</em>'s, a simple macro substitution facility, +also provides a base for experimenting with document type extensions +in a way that the SGML notion of <em>entity</em> does not since SGML +entities are invoked with a notation that is apart from that used to +markup with SGML <em>elements</em>, which are the objects corresponding +in the GELLMU scheme with <em>LaTeX</em>-like <em>commands</em>. </p> + +<p>Software associated with the GELLMU project falls into two parts: +</p> +<ol class="decimal"> +<li><p> <b>The syntactic translator.</b> This is a purely syntactic layer for converting + <em>LaTeX</em>-like markup in configurable ways to SGML markup. Its output may + be handled in standard SGML or XML systems. </p> +</li> +<li><p> <b>The didactic production system.</b> This component is a sketch, which might usefully + serve as a base for further development, of an SGML production + system for an authoring environment that consists of + </p> +<ol class="lower-alpha"> +<li><p> An SGML document type called <em>article</em> that is + accompanied by a corresponding XML document type. + </p> +</li> +<li><p> A package of extensible translating utilities written + in the language <em>Perl</em>. + </p> +</li> +</ol> + + As its name suggests, these materials are didactic and + should be regarded as unfinished for production work. </li> +</ol> +<p></p> + +<p>There are two overall concepts: <em>basic</em> mode and <em>advanced</em> +mode. The basic mode may be used to write consciously for any +standard document type such as HTML, DocBook, or TEI, +and the syntactic translator is for that mode the only software under this project that +might be relevant. The advanced mode incorporates a configurable +broader array of <em>LaTeX</em>-like markup features, mostly for brevity, in the syntactic translator. +This mode is fully developed only for use with a <em>LaTeX</em>-like document type +such as the didactic <em>article</em> document type that is part of the +didactic production system. </p> + +<p>One may use any SGML or XML processing framework in working +with the <em>article</em> document type. The didactic production system includes what is +needed to produce both HTML and regular <em>LaTeX</em> forms of an +<em>article</em> instance. Consequently, one is able to produce both +DVI using the <em>LaTeX</em> format for <em>TeX</em>, the program, and PDF +using the <em>LaTeX</em> format for PDF<em>TeX</em>, the program. Moreover, one +may tune the PDF in various ways using small alterations of the +<em>Perl</em> code for translating the XML version of <em>article</em> +to regular <em>LaTeX</em>. +</p> +</div> + +<div class="section"> +<h3>2.  <a id="SU-2"></a><a id="basic"></a>Basic GELLMU</h3> + +<p>Neither the basic nor the advanced mode involves in any way adoption +of the language of <em>LaTeX</em>. (But many command names under the didactic +<em>article</em> document type, mimic <em>LaTeX</em> command names.) There are +two fundamental ideas: +</p> +<ol class="decimal"> +<li><p> A <em>LaTeX</em>-like command “<kbd>\foo</kbd>” corresponds + to an SGML element “<kbd><foo></kbd>”. </p> +</li> +<li><p> The syntactic translator is almost entirely ignorant of vocabulary + and a name like <em>foo</em> need not have meaning in it although + it must have meaning in the document type for which one is + consciously writing.<sup><a id="revfnote1" href="#fnote1">1</a></sup></p> +</li> +</ol> +<p> +To use the basic mode one must be familiar with the SGML document +type for which one is writing. Ordinary HTML is an example. Very +few of the features in the advanced markup not also part of the basic +markup<sup><a id="revfnote2" href="#fnote2">2</a></sup> +make any sense for use in the direct preparation of HTML with <em>LaTeX</em>-like +input. </p> + +<p>GELLMU uses <em>LaTeX</em> special characters such as ‘<kbd>\</kbd>’, +‘<kbd>{</kbd>’, and ‘<kbd>}</kbd>’ along with <em>LaTeX</em>-like argument/option syntax, +where braces immediately following a command name indicate command +arguments and square brackets, i.e., ‘<kbd>[</kbd>’ and +‘<kbd>]</kbd>’, indicate command options. A command corresponds to +an SGML element, and in basic mode a command may have at most one +argument, the content of which corresponds to SGML element content, +and at most one option, the content of which corresponds to a list of +SGML attribute specifications. Thus for example, in basic mode for +HTML one may use the markup +</p> +<div class="display"><table class="gdisplay"><tbody><tr><td> +<kbd>\a[href="http://www.w3.org/"]{The World Wide Web Consortium}</kbd></td></tr></tbody></table></div> +<p> +to form the HTML anchor: +</p> +<div class="display"><table class="gdisplay"><tbody><tr><td> +<kbd><a href="http://www.w3.org/">The World Wide Web Consortium</a></kbd> +. </td></tr></tbody></table></div> +<p> +(The formation of anchors with the didactic <em>article</em> document +type in advanced mode is slightly more complicated because the +characters ‘<kbd>=</kbd>’ and ‘<kbd>/</kbd>’, which may acquire special (and +“overloaded”) semantic significance in mathematical +contexts, are held for delayed evaluation as empty elements and +because the syntactic translator, which does not recognize command names, regards this +usage in advanced mode as <em>multiple</em> +<a href="#argopt">argument/option syntax</a> (section 4.2), which is not part of basic +mode.)</p> + +<p>An example of the distinction between basic and advanced GELLMU is that +in advanced mode it is possible and easy to arrange to have a blank line, +as in <em>LaTeX</em>, represent the beginning of a paragraph. In basic mode +for HTML one +must<sup><a id="revfnote3" href="#fnote3">3</a></sup> +use “<kbd>\p</kbd>” to begin a paragraph, and for the XML version of +HTML one must also provide markup for the end of every paragraph, which +may be done in several ways. </p> + +<p>For some of the details on using the basic markup with HTML see +<a href="ghtml.html"><em>Using the GELLMU Syntactic Translator to Write HTML</em></a>. +It will be instructive to have the parallel <a href="ghtml.glm">source +markup</a> available at the same time. +</p> +</div> + +<div class="section"> +<h3>3.  <a id="SU-3"></a><a id="meta"></a>Metacommands</h3> + +<p>A metacommand is a <em>LaTeX</em>-like command that does not correspond to an +SGML element. Each metacommand is handled internally by the +syntactic translator. +</p> + +<div class="subsection"> +<h4>3.1.  <a id="SU-3.1"></a><a id="doctype"></a>\documenttype</h4> + +<p>A document prepared in GELLMU source usually begins with a +<em>documenttype</em> command. For example, +</p> +<div class="display"><table class="gdisplay"><tbody><tr><td> +<kbd>\documenttype{html}</kbd></td></tr></tbody></table></div> +<p> +is used to begin a document prepared for the most common form +of classical HTML. </p> + +<p>The syntactic translator has two public variables +<em>gellmu-doctype-keylist</em> and <em>gellmu-doctype-info</em>, +which are <em>Elisp</em> associative lists, that enable one to match XML +or SGML “<kbd><!DOCTYPE ... ></kbd>” declarations with +<em>LaTeX</em>-like +</p> +<div class="display"><table class="gdisplay"><tbody><tr><td> +<kbd>\documenttype[</kbd><em>my-optional-key</em><kbd>]{</kbd><em>my-doctype</em><kbd>}</kbd></td></tr></tbody></table></div> +<p> +commands, where <em>my-optional-key</em> is available to override a +default key for <em>my-doctype</em>. Thus, for example, +“<kbd>\documenttype{html}</kbd>” points to the default key for +“<kbd>html</kbd>”, which is “<kbd>html-4.01</kbd>” and which points to +the <em>W3C HTML 4.01 Transitional</em> document type, while +</p> +<div class="display"><table class="gdisplay"><tbody><tr><td> +<kbd>\documenttype[xhtml-1.0s]{html}</kbd></td></tr></tbody></table></div> +<p> +indicates <em>W3C XHTML 1.0 Strict</em>. </p> + +<p>A user may configure these variables without modifying the source +code for the GELLMU syntactic translator, but minimal knowledge of <em>Elisp</em> will +be required. A future release might provide a configuration file +for this purpose. </p> + +<p>A second option for the <em>documenttype</em> metacommand, which must +follow the single required argument, is provided for writing an +internal declaration subset. The contents of an internal declaration +subset constructed this way may be any internal declaration subset +material. However, some care is required for entering characters +that are special. To ease the handling of special characters four +metacommands have been provided for use inside the internal declaration +subset: +</p> +<dl> +<dd> <kbd>\attlist{...}</kbd></dd> +<dd> <kbd>\element{...}</kbd></dd> +<dd> <kbd>\entity{...}</kbd></dd> +<dd> <kbd>\notation{...}</kbd></dd> +</dl> +<p> +For example, a user who wishes to be able in source to use +“<kbd>&quo;</kbd>” to reference the ASCII quotation mark +when writing consciously in basic mode for TEI.2 would begin +the source file with: +</p> +<dl class="verblist"> +<dd><kbd> +\documenttype{TEI.2}[</kbd></dd> +<dd><kbd> +\entity{quo "&#x22;"}</kbd></dd> +<dd><kbd> +]</kbd></dd> +</dl> +<p> +</p> +</div> + +<div class="subsection"> +<h4>3.2.  <a id="SU-3.2"></a><a id="newcommand"></a>\newcommand</h4> + +<p>From a user's viewpoint this provides emulation of <em>LaTeX</em>'s +<em>newcommand</em>. But it is a simple facility providing macro +substitution with arguments forward in a source file from the +point of its occurrence. It differs from the <em>newcommand</em> +facility in <em>LaTeX</em> in that it does not add the name +of a newcommand to any namespace. Instead, as the syntactic translator encounters +each newcommand definition, it performs the corresponding expansions +and then forgets the name.<sup><a id="revfnote4" href="#fnote4">4</a></sup></p> + +<p>The general construction of a newcommand definition is +</p> +<div class="display"><table class="gdisplay"><tbody><tr><td> +<kbd>\newcommand{</kbd><em>name</em><kbd>}[</kbd><em>nargs</em><kbd>][</kbd><em>first</em><kbd>]{</kbd><em>value</em><kbd>}</kbd></td></tr></tbody></table></div> +<p> +where <em>name</em> is the name of the newcommand, +<em>nargs</em> optionally specifies the number of its arguments, +<em>first</em> is an optionally-provided default value for the first +argument, and <em>value</em> denotes the value string. </p> + +<p>In the value string the character ‘<kbd>#</kbd>’ is used to reference an +argument by the numeric value of its position. Thus, “<kbd>#1</kbd>” +refers to the first argument that is provided at an invocation of +the newcommand, “<kbd>#2</kbd>” the second, etc., and there is no limit +on the number of arguments. It is not required that <em>nargs</em> be +supplied in order to define and use a newcommand taking +arguments. However, for the sake of automatic error checking the +use of <em>nargs</em> is strongly recommended when the definition of +a newcommand taking arguments is entered. </p> + +<p><b>Example.</b> In writing HTML one might use +</p> +<dl class="verblist"> +<dd><kbd> +\newcommand{\href}[2][http://www.w3.org/]{\a[href="#1"]{#2}}</kbd></dd> +</dl> +<p> +for brevity in writing many HTML anchors. With this definition the +invocation +</p> +<div class="display"><table class="gdisplay"><tbody><tr><td> +<kbd>\href{http://www.myweb.mydomain/me.html}{my web page}</kbd></td></tr></tbody></table></div> +<p> gives +rise to the HTML markup +</p> +<div class="display"><table class="gdisplay"><tbody><tr><td> +<kbd><a href="http://www.myweb.mydomain/me.html">my web page</a></kbd></td></tr></tbody></table></div> +<p> +while the invocation +“<kbd>\href{Web Central}</kbd>” gives rise to +</p> +<div class="display"><table class="gdisplay"><tbody><tr><td> +<kbd><a href="http://www.w3.org/">Web Central</a></kbd> . </td></tr></tbody></table></div> +<p></p> + +<p><b>Rules.</b> +</p> +<ol class="decimal"> +<li><p> The name of a newcommand may not be referenced in its +value string.<sup><a id="revfnote5" href="#fnote5">5</a></sup> +</p> +</li> +<li><p> A newcommand may not be invoked before it is defined unless +the invocation occurs in the value string of another newcommand +definition in which case the definition of the latter may be first and +<b>must</b> be first if the invocation of the former in the definition +of the latter involves argument substitutions. </p> +</li> +</ol> +<p></p> + +<p>Failure to observe these rules may cause the syntactic translator to enter an infinite +recursive loop. If a user suspects this may have happened, then the +invocation of the syntactic translator should be <a href="#interrupt">interrupted</a> (section 7.4.3). +</p> +</div> + +<div class="subsection"> +<h4>3.3.  <a id="SU-3.3"></a><a id="beginend"></a>\begin{} … \end{}</h4> + +<p>These provide emulation of <em>LaTeX</em> environment notation without +actually providing anything that is not otherwise available. Markup +which resembles that for a <em>LaTeX</em> environment simply resolves to an +SGML element. This usage may be convenient for SGML elements of +large scope such as, for example, the <em>body</em> of an HTML +document. </p> + +<p>With advanced mode the special form +</p> +<div class="display"><table class="gdisplay"><tbody><tr><td> +<kbd>\begin{document} . . . \end{document}</kbd></td></tr></tbody></table></div> +<p> +may be used to emulate the corresponding feature of <em>LaTeX</em> for a +document type, such as the didactic <em>article</em> document type, +that in the large consists of a preamble and a body. +</p> +</div> + +<div class="subsection"> +<h4>3.4.  <a id="SU-3.4"></a><a id="macmac"></a>\macro and \Macro</h4> + +<p>Use of these is discouraged in the absence of a need. One situation +that presents a need is name “fronting”: see the +discussion below in <a href="#fronting">section 3.5</a>. +Please note that in most situations one may use <em>newcommand</em> +without an argument for simple macro substitutions. </p> + +<p><em>macro</em> and <em>Macro</em> do very much the same thing except +for the order of expansions. Every <em>macro</em> is expanded forward +as encountered before any newcommand definition is expanded. Every +<em>Macro</em> is expanded forward after every newcommand +has been expanded. </p> + +<p>There are four primary differences between <em>macro</em> and <em>Macro</em>, +on the one hand, and <em>newcommand</em>, on the other hand. +</p> +<ol class="decimal"> +<li><p> Neither <em>macro</em> nor <em>Macro</em> can be used to define a +macro that takes arguments. </p> +</li> +<li><p> The name of a newcommand must consist of word characters, +but there is no restriction on the characters, apart from unbalanced +brace characters (‘<kbd>{</kbd>’ and ‘<kbd>}</kbd>’), that may appear in +the name field of a <em>macro</em> or <em>Macro</em> metacommand. </p> +</li> +<li><p> If the name of a <em>macro</em> or <em>Macro</em> does not begin +with the command sequence introducer, i.e., the character ‘<kbd>\</kbd>’, +then an invocation of that metacommand is given by every forward match +of its name. The use of such names is strongly discouraged because +document segments can then become opaque much too easily. </p> +</li> +<li><p> A newcommand invocation, absent the use of a semi-colon +for termination, is only effective at the whole word level — with +<em>word</em> here denoting a maximal string of successive word +characters — whereas <em>macro</em> and <em>Macro</em> invocations are +effective regardless of word boundaries. </p> +</li> +</ol> +<p></p> + +<p>Elaboration on the last point: If <kbd>x</kbd> is the name of a +newcommand, then invocations are +only considered by the syntactic translator on the string “<kbd>\x</kbd>” when it is followed +by a non-word character. For example, if the locale is us-ascii, +then the word characters are the 52 upper and lower case letters +and the ten numerals. Therefore with <em>newcommand</em>, as with its +namesake in regular <em>LaTeX</em>, the use of “x” as a name will +not intercept the occasions of “<kbd>\x</kbd>” as an initial +substring of “<kbd>\xy</kbd>”. With either <em>macro</em> or +<em>Macro</em> such interception does take place. One may block it at +the point of an invocation with the markup “<kbd>\x;</kbd>”, and when +this is done, the terminating semi-colon is removed. </p> + +<p>Human authors using either <em>macro</em> or <em>Macro</em> may find +unanticipated interactions between the three forms of macro +substitution. </p> + +<p>Unbalanced brace characters, i.e., the characters ‘<kbd>{</kbd>’ and +‘<kbd>}</kbd>’, may not be used in the name field or the value field of +any form of macro metacommand. +</p> +</div> + +<div class="subsection"> +<h4>3.5.  <a id="SU-3.5"></a><a id="fronting"></a>Macro-Level Fronting of SGML Element Names</h4> + +<p>The word <em>fronting</em> as used here describes the practice of +modifying the meaning of an SGML element name by using one or +more of the macro facilities to generate usage of the same name as +an element combined with other markup using the syntax that would +otherwise correspond to basic use of the element. </p> + +<p>Suppose, for example, one wants all paragraphs in HTML (marked +with <kbd>\p</kbd> in GELLMU source) to be placed in a (style) class called +<em>custom</em>. </p> + +<p><b>Recommended procedure:</b> Create a new unique name and then use +<em>macro</em> to front it. +</p> +<dl class="verblist"> +<dd><kbd> +\newcommand{\cp}[1][]{\p[class="custom"]{#1}}</kbd></dd> +<dd><kbd> +\macro{\p}{\cp}</kbd></dd> +</dl> +<p> +Each invocation of “<kbd>\p{...}</kbd>” will first be replaced by “<kbd>\cp{...}</kbd>” +because all <em>macro</em> definitions are expanded before any +newcommand definition is expanded. Subsequent expansion +of the newcommand will yield +</p> +<div class="display"><table class="gdisplay"><tbody><tr><td> +<kbd>\p[class="custom"]{...}</kbd> . </td></tr></tbody></table></div> +<p></p> + +<p>This will not intercept the alternate, otherwise nearly equivalent, +markup given with <kbd>\begin{p}</kbd> … <kbd>\end{p}</kbd> since <em>newcommand</em> +is based on simple macro substitution and does not operate at the +level of namespaces. +</p> +</div> +</div> + +<div class="section"> +<h3>4.  <a id="SU-4"></a><a id="advanced"></a>Advanced GELLMU</h3> + +<p>The idea with advanced GELLMU is that for SGML document +types sharing structural characteristics with <em>LaTeX</em> one might +wish to have the syntactic translator provide <em>LaTeX</em>-like markup syntax beyond the level +used with basic GELLMU and that these additional layers of syntax +should be configurable. The only substantial realization of this +program so far is the case of the GELLMU didactic document type called <em>article</em>. +The specifics of that realization are discussed in the following +section. +</p> + +<div class="subsection"> +<h4>4.1.  <a id="SU-4.1"></a><a id="illustrations"></a>Illustrations.</h4> + +<p>One might want to be able to use blank lines, as in +<em>LaTeX</em>, for introducing new paragraphs in a document type that +provides paragraphs. </p> + +<p>In some article-level document types each sectional unit has a unit +header providing markup for various, often optional, unit descriptors. +It is convenient to be able to use <em>LaTeX</em>-like multiple +<a href="#argopt">argument/option syntax</a> (section 4.2) for these. </p> + +<p>If the document type provides authoring-level mathematical markup +beyond inclusions of the World Wide Web Consortium's +<a href="http://www.w3.org/Math/">Mathematical Markup Language</a> (MathML) +under its <a href="http://www.w3.org/TR/REC-xml-names">XML namespace</a> +regime, then one might want to be able to use the ‘<kbd>$</kbd>’ character +to toggle in and out of inline math, and if the document provides +for math displays, then one might want to use, as in <em>LaTeX</em>, the +strings “<kbd>\[</kbd>” and “<kbd>\]</kbd>” as delimiters for +unstructured mathematical displays, and markup such as +</p> +<div class="display"><table class="gdisplay"><tbody><tr><td> +<kbd>\begin{equation} . . . \end{equation}</kbd></td></tr></tbody></table></div> +<p> +for a single equation, and markup such as +</p> +<div class="display"><table class="gdisplay"><tbody><tr><td> +<kbd>\begin{eqnarray} . . . \end{eqnarray}</kbd></td></tr></tbody></table></div> +<p> +for a list of equations. </p> + +<p>It is important to emphasize, however, that by overall system design +the syntactic translator operates without substantial knowledge of vocabulary. While +it is true that if ‘<kbd>$</kbd>’ is to provide a toggle for an inline +element containing math, say, <em>tmath</em>, then the syntactic translator needs to have +that association made, but the association is provided as the +value of a configuration variable in the syntactic translator that can be changed +between documents so that the syntactic translator may be used with many document +types. </p> + +<p>One way to make such configuration convenient is to use an array of +<em>Elisp</em> functions that are fronts with various variable configuration +packages for the basic function <em>gellmu-trans</em> in the syntactic translator. +</p> + +<p>The general outline for advanced GELLMU with arbitrary document types +is not fully developed in the present release. Instead the project +has concentrated on the realization of these ideas for the project's +didactic <em>article</em> document type, which is the subject of the +next section. </p> + +<p>As the syntactic translator stands now, basic mode is characterized in the syntactic translator by the +true setting for its Boolean variable <em>gellmu-straight-sgml</em>, +while the configuration used by default for the didactic document type (which +<em>could</em> be handled in basic mode with more verbose source markup) +has that variable set false and also the variable +<em>gellmu-regular-sgml</em> set false. </p> + +<p>The term <a id="regular"></a><em>regular</em> GELLMU refers to use of the +syntactic translator with the default configuration for the didactic document type. It involves nearly +maximal emulation of <em>LaTeX</em>-like markup; it implies both <em>advanced</em> mode +and the <a href="#ddt">didactic document type</a> (section 5) <em>article</em>. +</p> +</div> + +<div class="subsection"> +<h4>4.2.  <a id="SU-4.2"></a><a id="argopt"></a>Multiple Argument/Option Syntax</h4> + +<p>An essential point in the present design is that the whole system +is built from components, each of which has its own +function<sup><a id="revfnote6" href="#fnote6">6</a></sup>. +Consistent with this design the syntactic translator operates with knowledge of syntax +but little or no knowledge of language. </p> + +<p>Multiple argument/option syntax has been built into advanced mode as +part of the overall idea of providing, where sensible, <em>LaTeX</em>-like +features in a precise user markup interface for writing in document +types under SGML and XML. </p> + +<p>What are the rules for converting the multiple argument/option syntax +in source markup into SGML? Direct conversion by the syntactic translator of this +type of usage into XML is not available because such conversion +requires some language knowledge and the program does not operate with +knowledge of language at that level<sup><a id="revfnote7" href="#fnote7">7</a></sup>. +One obtains an XML version of a +document in the didactic production system by using a translator with +minimal knowledge of the command vocabulary to create the XML version +from an SGML version that is the immediate output of the syntactic translator. </p> + +<p>In multiple argument/option syntax, which is much like that of +<em>LaTeX</em>, arguments and options follow command names. Arguments are +delimited by braces, i.e., ‘<kbd>{</kbd>’ and ‘<kbd>}</kbd>’ and options +by square brackets, i.e., ‘<kbd>[</kbd>’ and ‘<kbd>]</kbd>’. There +must be no white space between the arguments and options nor between +the command name and the first member of an argument/option sequence. </p> + +<p>Each command with a multiple argument/option sequence is translated to +an open tag whose name is the name of the command. Each argument is +translated to an <em>ag0</em> element and each option to an <em>op0</em> +element. (Both <em>ag0</em> and <em>op0</em> lie in GELLMU's reserved +name space.) There are two exceptional cases. + +</p> +<ol class="decimal"> +<li><p> The first argument or option is an option inside which the very +first character is a colon, i.e., ‘<kbd>:</kbd>’. This is the method +provided in advanced mode for the direct entry of an SGML attribute +sequence.<sup><a id="revfnote8" href="#fnote8">8</a></sup> +The entire contents of the option string, apart from the +leading ‘<kbd>:</kbd>’, which is discarded, are understood to be a +sequence of SGML attributes for the SGML element whose name is the +name of the command. There is no syntax check of the attribute +contents by the syntactic translator. Such an <em>attribute option</em> is not treated +as an <em>op0</em> element. In particular, an attribute option is +correctly followed immediately by a semi-colon, i.e., the character +‘<kbd>;</kbd>’, if and only if the corresponding SGML element is a +defined-empty element under the SGML document type. Since SGML +attributes correspond to very little of classical <em>LaTeX</em><sup><a id="revfnote9" href="#fnote9">9</a></sup>, +attribute options are seldom used<sup><a id="revfnote10" href="#fnote10">10</a></sup> +in the didactic production system. One such use is for the GELLMU equivalent of latex's +<em>equation*</em> and <em>eqnarray*</em> environments, which is marked up +this way: +</p> +<dl class="verblist"> +<dd><kbd> +\begin{equation}[:nonum="true"]</kbd></dd> +<dd><kbd> +e = mc^2</kbd></dd> +<dd><kbd> +\end{equation}</kbd></dd> +</dl> + +to produce: + +<math xmlns="http://www.w3.org/1998/Math/MathML" display="block" mode="display" +><mtable><mtr class="labeled"><mtd></mtd><mtd><mrow><mi>e</mi><mo>=</mo><mi>m</mi><msup><mi>c</mi><mn>2</mn></msup +></mrow></mtd></mtr></mtable></math +> +</li> +<li><p> The first argument is the only argument and there are no options +apart from a possible attribute option. This case, which is extremely +common, is exceptional relative to argument/option handling +since the sole argument simply becomes element content without an +<em>ag0</em> wrapper. +</p> +</li> +</ol> +<p></p> + +<p>When a command has a multiple argument/option sequence, the question +arises whether the <em>ag0</em> and <em>op0</em> elements that arise from +the arguments and options are the only content of the element +corresponding to the command. The syntax does not provide a way to +determine this. On the other hand, the SGML document type definition +does provide information that indicates whether other content is +possible. It is beyond the scope of the design of the syntactic translator for the +syntactic translator to read a document type definition. The syntactic translator does, however, +have a configurable list variable <em>gellmu-autoclose-list</em> +that contains the names of elements +for which no content beyond the elements arising from arguments and +options is possible. While it is not necessary that every such +command be entered in this list, when such a command not in the list +is not explicitly followed by an element closing command, it is +possible in some instances for an SGML parser to infer incorrectly +the location of end of the element. Thus, the didactic production system provides a +command <em>anch</em> for making anchors. The document type definition +provides for one option, a reference, and one argument, the anchored +text.<sup><a id="revfnote11" href="#fnote11">11</a></sup> +Because the syntactic translator does not consider the document type definition, +if one enters the markup +</p> +<div class="display"><table class="gdisplay"><tbody><tr><td> +<kbd>\anch[href="http://www.w3.org/"]{W3C} HQ</kbd> ,</td></tr></tbody></table></div> +<p> +unless the name <em>anch</em> is in the list<sup><a id="revfnote12" href="#fnote12">12</a></sup> +<em>gellmu-autoclose-list</em>, +an SGML parser will not have reason to close the <em>anch</em> until +it sees the space following the anchored text “W3C”, and so +that space will be considered insignificant white space with the result +that there will be no space between the anchored text and the following +“HQ”. +</p> +</div> + +<div class="subsection"> +<h4>4.3.  <a id="SU-4.3"></a><a id="xmllimit"></a>Limitation in Regard to XML</h4> + +<p>A final general comment about advanced mode is that the features it +can provide beyond basic mode when one is writing consciously for an +XML document type are somewhat limited. For example, blank lines +cannot easily be made adequate for paragraph markup with the XML form +of the didactic <em>article</em> document type. Although it is not a +specific limitation for future editions of the syntactic translator, the vision is that +use of advanced mode will be specifically for a somewhat rich SGML +version of a document type. +</p> +</div> +</div> + +<div class="section"> +<h3>5.  <a id="SU-5"></a><a id="ddt"></a>The Didactic Document Type</h3> + +<p>The didactic document type is the document type underlying what is called regular +GELLMU. It is the heart of the idea of GELLMU as a bridge for authors +from <em>LaTeX</em> to the world of XML. More specifically, the bridge is +from the world of a <em>LaTeX</em> <em>article</em> to a document type in the +world of XML, also called <em>article</em>, that has a structure and a +vocabulary similar to those of the <em>LaTeX</em> document class.<sup><a id="revfnote13" href="#fnote13">13</a></sup> +The techniques used in the didactic production system are extensible and can be carried over +to other types of documents than articles. It is important to note +that there are many features in regular <em>LaTeX</em> which have no analogue +so far in the development of this project. One might hope to get an +idea of the extent of coverage by reviewing the examples in the +<a href="#archive">project archive</a> (appendix A). </p> + +<p>When an author prepares a document as a <em>LaTeX</em> <em>article</em>, the +document is being marked up as data for a specific typesetting +program: Donald Knuth's program <em>TeX</em> running with the main <em>LaTeX</em> +facilities loaded. </p> + +<p>When an author prepares a document as GELLMU source, the syntactic translator provides +a <em>LaTeX</em>-like markup interface, but its output is not data for a +specific typesetting program. Rather it is data for a broad class of +processors. This means that multiple output formats can be obtained +from a single source without the need for human intervention because +XML provides a framework that makes it relatively easy to create +reliable programs for translation from an XML document type to other +formats. It offers, moreover, the possibility of translation to +future formats free of any need for human intervention once +translators from the original document type to such formats are +written. The small price one pays for this advantage in moving from +<em>LaTeX</em> markup to GELLMU markup is that the author must learn a few +new things.<sup><a id="revfnote14" href="#fnote14">14</a></sup></p> + +<p>There are two formal constructions of the didactic document type. The name of the +document type is <em>article</em>. The first construction is an SGML +version of <em>article</em> that provides features convenient for +authors that are not available under XML. The second is an XML +version. For most non-technical purposes the two constructions should +be regarded as equivalent. </p> + +<p>The SGML construction of an <em>article</em> is derived from GELLMU +source markup for a document by using the syntactic translator. The didactic document +type is accompanied by a translator implemented under the Perl +language framework <em>sgmlspl</em> by David Megginson (see +the release notes in <a href="#release">appendix B</a> +for more information) for converting the SGML version of an +<em>article</em> to the XML version. </p> + +<p>The description in this section of the manual deals primarily with +source level markup for the didactic document type and with how it is handled <sup><a id="revfnote15" href="#fnote15">15</a></sup> +by the time the XML version of an article is generated. Secondarily +there is comment on how it is rendered in the chief output formats +of the didactic production system, which are PDF, classic HTML, and XHTML+MathML. </p> + +<p>A quick glance at the <a href="#flow">flowchart</a> (section 7.5.2) shows that the first +XML stage — author-level XML — may be viewed as a second entry +point to didactic production system processing. Some day this could become a reasonable +formatting route for translations from things like <em>Texinfo</em>, +<em>DocBook</em>, and, even perhaps, classical <em>LaTeX</em> itself via a +processor such as <em>tex4ht</em>. +</p> + +<div class="subsection"> +<h4>5.1.  <a id="SU-5.1"></a><a id="caveat"></a>Suggestions and Caveats</h4> + +<p>Although this is the manual for a software release, it is not a book. +A document of book size would be required for a full description of +the didactic production system. </p> + +<p>Much of the markup vocabulary is copied from <em>LaTeX</em>. There are some +instances where there is some deviation from <em>LaTeX</em> usage, and many +of those instances are mentioned here. </p> + +<p>Definitive information about the didactic document type may be derived by consulting the +document type definition. Because the didactic production system is conceived as a base for +future development there are sketches in the document type definition +that are not covered by the didactic processors. For example, +although there is sketched code for the analogues of <em>LaTeX</em>'s +<em>paragraph</em> and <em>subparagraph</em> commands, which are sectional +in nature, that is found in the translation from SGML to XML, there is +no sketched code for these elements in the two formatters. </p> + +<p>Another way to obtain information about the didactic production system is by studying +examples including this manual and the examples in the +<a href="#archive">project archive</a> (appendix A). +</p> +</div> + +<div class="subsection"> +<h4>5.2.  <a id="SU-5.2"></a><a id="mufund"></a>Markup Fundamentals</h4> + +<p>There are several kinds of commands: +</p> + +<div class="subsubsection"> +<h5>5.2.1.  <a id="SU-5.2.1"></a><a id="explicitnames"></a>Explicitly named commands.</h5> + +<p>Apart from macro level +metacommands an explicitly named command begins with <b>a maximal +string introduced by the character</b> ‘<kbd>\</kbd>’ <b>followed by +word characters, including the numerals</b> ‘<kbd>0</kbd>’, ‘<kbd>1</kbd>’, +…, ‘<kbd>9</kbd>’. The notion of <em>word character</em> depends on +one's locale, a concept that is formalized in GNU <em>Emacs</em>. In the +ASCII character set the word characters are the 52 upper and +lower case letters and the 10 numerals. <b>The first numeral, if +any, must not be ‘<kbd>0</kbd>’</b> since such names are reserved for use by +the syntactic translator. Command names are case sensitive. </p> + +<p>An explicitly named command is a <em>container</em>, corresponding to an +SGML <em>element</em>, if its name is immediately followed, without +intervening white space, by the character ‘<kbd>{</kbd>’. In that case +the delimited zone of containment normally ends with the subsequent +balancing character ‘<kbd>}</kbd>’. (<em>LaTeX</em>-like +<a href="#argopt">multiple argument/option</a> (section 4.2) chains deserve more +discussion; for now it will suffice to point out that the use of the +<kbd>\anch</kbd> command in this document for making “anchors” is an +example, and, of course, <em>LaTeX</em>'s <kbd>\frac</kbd> command is another example. +For the present discussion these commands are considered to be +containers.)</p> + +<p>An explicitly named command corresponds to an SGML +<em>defined-empty element</em> if its name is immediately followed, +without intervening white space, by the character ‘<kbd>;</kbd>’. </p> + +<p>An explicitly named command corresponds to an SGML element closing +tag if its name is immediately followed, without intervening +white space, by the character ‘<kbd>:</kbd>’. </p> + +<p>The name of an explicitly named command is terminated by a non-word +character. There is a small, possibly acceptable, level of syntactic +ambiguity unless the name terminator is one of ‘<kbd>{</kbd>’, +‘<kbd>;</kbd>’, ‘<kbd>:</kbd>’, or ‘<kbd>[</kbd>’. </p> + +<p>In basic mode if the name terminator is ‘<kbd>[</kbd>’, then that +character introduces a list of SGML attribute specifications, each of +the form <em>name</em>="<em>value</em>", and the list must be +terminated by the character ‘<kbd>]</kbd>’. Then if the following +character is ‘<kbd>{</kbd>’, the named command is a container that ends +with the balancing ‘<kbd>}</kbd>’. Otherwise the following character +may be ‘<kbd>;</kbd>’ if the named command is a defined-empty element and +must be so in that case for direct editing of an XML document type. </p> + +<p>In advanced mode if the name terminator is ‘<kbd>[</kbd>’, then that +character introduces a <em>LaTeX</em>-like command option — part of the +emulation of <em>LaTeX</em>'s multiple <a href="#argopt">argument/option syntax</a> (section 4.2) +— unless it is immediately followed, without intervening white space, +by the character ‘<kbd>:</kbd>’, in which case the bracketed content is +a list of SGML attribute specifications. (The initial ‘<kbd>:</kbd>’, +which may be used optionally in basic mode, is discarded.)</p> + +<p>In any other case there is some syntactical ambiguity. The syntactic translator will +produce a corresponding SGML open tag unless the logical variable +<em>gellmu-xml-strict</em> has been set.<sup><a id="revfnote16" href="#fnote16">16</a></sup> If +the usage is consistent with the structure of the document type, an +SGML parser will in many cases be able to handle the result +correctly. The result of this type of syntactic ambiguity in source +markup is not tolerated if one is editing directly for an XML document +type. The terminator can be a blank space, but, if so, the +blank space is likely to become invisible after SGML parsing much +in the way that in <em>LaTeX</em> the markup +</p> +<div class="display"><table class="gdisplay"><tbody><tr><td> +<kbd>\LaTeX document</kbd></td></tr></tbody></table></div> +<p> +will be collapsed into the single word form “<em>LaTeX</em>document” +when typeset.<sup><a id="revfnote17" href="#fnote17">17</a></sup> +</p> +</div> + +<div class="subsubsection"> +<h5>5.2.2.  <a id="SU-5.2.2"></a><a id="single"></a>Certain single characters.</h5> + +<p>The characters +‘<kbd>\</kbd>’, ‘<kbd>{</kbd>’, ‘<kbd>}</kbd>’, ‘<kbd>^</kbd>’, +‘<kbd>_</kbd>’, ‘<kbd>$</kbd>’, ‘<kbd>%</kbd>’, and ‘<kbd>~</kbd>’ +have command meanings that are similar to their meanings in <em>LaTeX</em>. +The characters ‘<kbd>;</kbd>’ and ‘<kbd>:</kbd>’ are ordinary characters that +have special meaning at the end of a command name. The character +‘<kbd>#</kbd>’ is also a special character used, as with <em>LaTeX</em>, in +<em>newcommand</em> templates. In source for the didactic +<em>article</em> document type any non-alphanumeric ASCII +character may be escaped (referenced for itself) with a named command, +e.g. ‘<kbd>~</kbd>’ may be referenced for itself as <kbd>\tld;</kbd>. This +is <b>necessary</b> in order to provide delayed evaluation for +ultimate translation to one of many possible ultimate formats. </p> + +<p>The following language meanings apply to both basic and advanced +markup: + </p> +<ol class="decimal"> +<li><p> “<kbd>\</kbd>”: <b>Command introducer.</b><br + /> Escape in basic mode: <kbd>\\</kbd> . This escape is + incorrect in advanced mode since this notation has a different + meaning — forced linebreak — in <em>LaTeX</em> itself. For the + didactic <em>article</em> + document type the escape is <kbd>\bsl;</kbd> . For other document + types one may resort to an entity reference + if adverse to providing a corresponding + defined-empty element or if one lacks control of the document type. + </p> +</li> +<li><p> “<kbd>{</kbd>”: <b>Command argument opener.</b><br + /> Escape: <kbd>\{</kbd> or <kbd>\lbr;</kbd> . + </p> +</li> +<li><p> “<kbd>}</kbd>”: <b>Command argument closer.</b><br + /> Escape: <kbd>\}</kbd> or <kbd>\rbr;</kbd> . + </p> +</li> +<li><p> “<kbd>[</kbd>”: <b>Command option opener.</b><br + /> Escape: <kbd>\lsb;</kbd> (usually not necessary<sup><a id="revfnote18" href="#fnote18">18</a></sup>). + </p> +</li> +<li><p> “<kbd>]</kbd>”: <b>Command option closer.</b><br + /> Escape: <kbd>\rsb;</kbd> . + </p> +</li> +<li><p> “<kbd>;</kbd>”: <b>Command terminator for defined-empty tags.</b><br + /> Escape: <kbd>\scl;</kbd> . + Usually an ordinary character. + Its use as a command terminator is invisible and may be + omitted optionally in some contexts. This syntax is analogous to + the use of ‘<kbd>;</kbd>’ as an entity reference terminator in SGML. + </p> +</li> +<li><p> “<kbd>:</kbd>”: <b>Command terminator for close tags.</b><br + /> Escape: <kbd>\cln;</kbd> . + Otherwise an ordinary character. + Its use as a command terminator is invisible. + </p> +</li> +<li><p> “<kbd>%</kbd>”: <b>Comment introducer, in force to end of line.</b><br + /> Escape: <kbd>\%</kbd> or <kbd>\pct;</kbd> . + </p> +</li> +<li><p> “<kbd>#</kbd>”: <b>Argument marker in <em>newcommand</em> definitions.</b><br + /> Escape: <kbd>\#</kbd> or <kbd>\hsh;</kbd> . + In the definition of a newcommand “<kbd>#1</kbd>” indicates the first + invocation argument, “<kbd>#2</kbd>” the second invocation argument, etc. + (There is no limit on the number of arguments.) + </p> +</li> +</ol> +<p></p> + +<p>The following language meanings apply to advanced markup with +allusion to the didactic <em>article</em> document type. + </p> +<ol class="decimal"> +<li><p> “<kbd>~</kbd>”: <b>Non-breaking interword space.</b><br + /> Escape: <kbd>\tld;</kbd>.<sup><a id="revfnote19" href="#fnote19">19</a></sup><br + /> Equivalent: <kbd>\nbs;</kbd>, cf. <kbd>&nbsp;</kbd> in HTML. + </p> +</li> +<li><p> “<kbd>^</kbd>”: <b>Superscript command.</b><br + /> Escape: <kbd>\crt;</kbd> .<br + /> Equivalent: <kbd>\sup</kbd> or, in math, <kbd>\msup</kbd> . + </p> +</li> +<li><p> “<kbd>_</kbd>”: <b>Subscript command.</b><br + /> Escape: <kbd>\_</kbd> or <kbd>\und;</kbd> .<br + /> Equivalent: <kbd>\sub</kbd> or, in math, <kbd>\msub</kbd> . + </p> +</li> +<li><p> “<kbd>&</kbd>”: <b>Dual use: tabular cells and entity introducer.</b><br + /> Escape: <kbd>\&</kbd> or <kbd>\amp;</kbd> .<br + /> ‘<kbd>&</kbd>’ introduces an entity reference if it is followed + by anything other than white space. It is used, as in <em>LaTeX</em>, as + a <em>tabular</em> cell delineator when it is followed by white space. + </p> +</li> +<li><p> “<kbd>$</kbd>”: <b>Toggle inline math mode.</b><br + /> Escape: <kbd>\$</kbd> or <kbd>\dol;</kbd> .<br + /> Equivalent: “<kbd>\tmath{ . . . }</kbd>”. <br + /> Nearly equivalent: “<kbd>\( . . . \)</kbd>” +or “<kbd>\math{ . . . }</kbd>”.<sup><a id="revfnote20" href="#fnote20">20</a></sup> + </p> +</li> +</ol> +<p> +</p> +</div> + +<div class="subsubsection"> +<h5>5.2.3.  <a id="SU-5.2.3"></a><a id="certainstrings"></a>Certain strings</h5> + +<p>These are strings of plain text with markup significance in the didactic document type that +are part of markup in <em>LaTeX</em>. + </p> +<ol class="decimal"> +<li><p> “<kbd>--</kbd>” <br + /> <b>Short dash</b> as used with a range + of numbers, e.g., 1–2.<br + /> Equivalent: <kbd>\rdash;</kbd> . + </p> +</li> +<li><p> “<kbd>---</kbd>” <br + /> <b>Long dash</b> as used for + punctuation, e.g., a dash — like this.<br + /> Equivalent: <kbd>\pdash;</kbd> . + </p> +</li> +<li><p> “<kbd>\ </kbd>” <br + /> <b>Blank interword space.</b><br + /> Equivalent: <kbd>\spc;</kbd> . + </p> +</li> +<li><p> “<kbd>\,</kbd>” <br + /> <b>Small horizontal space.</b><br + /> Equivalent: <kbd>\hsp;</kbd> . + </p> +</li> +<li><p> “<kbd>\\</kbd>” <br + /> <b>Forced line break.</b><br + /> “<kbd>\\</kbd>” may be used at the end of a line of + input for a forced line break. In a <em>tabular</em> environment + (with the didactic <em>article</em> document type, as in + <em>LaTeX</em>) it begins a new <em>tabular</em> row. Any other use is + deprecated, and will result in translation to the defined-empty + element <em>bsl</em> corresponding to the ASCII character + ‘<kbd>\</kbd>’ with a warning from the syntactic translator.<br + /> Equivalents: <kbd>\brk;</kbd> for a + line break outside of a <em>tabular</em> environment.<sup><a id="revfnote21" href="#fnote21">21</a></sup> + </p> +</li> +<li><p> Blank line.<br + /> <b>Begin new paragraph command.</b><br + /> Equivalent: <kbd>\parb</kbd> . Nearly equivalent: <kbd>\par</kbd> . + </p> +</li> +<li><p> “<kbd>``</kbd>” <br + /> <b>Left (double) quotation mark.</b><br + /> Equivalent: <kbd>\ldq;</kbd> . + </p> +</li> +<li><p> “<kbd>''</kbd>” <br + /> <b>Right (double) quotation mark.</b><br + /> Equivalent: <kbd>\rdq;</kbd> . + </p> +</li> +<li><p> “<kbd>\(</kbd>” <br + /> <b>Begin <em>math mode</em> command.</b><br + /> Equivalent: <kbd>\begin{math}</kbd> . + </p> +</li> +<li><p> “<kbd>\)</kbd>” <br + /> <b>End <em>math mode</em> command.</b><br + /> Equivalent: <kbd>\end{math}</kbd> . + </p> +</li> +<li><p> “<kbd>\[</kbd>” <br + /> <b>Begin <em>displaymath mode</em> command.</b><br + /> Equivalent: <kbd>\begin{displaymath}</kbd> . + </p> +</li> +<li><p> “<kbd>\]</kbd>” <br + /> <b>End <em>displaymath mode</em> command.</b><br + /> Equivalent: <kbd>\end{displaymath}</kbd> . + </p> +</li> +<li><p> “<kbd>.  </kbd>”, “<kbd>?  </kbd>”, “<kbd>!  </kbd>” <br + /> <b>End-of-sentence marks.</b><br + /> Equivalent: <kbd>\eos;</kbd>, <kbd>\eoq;</kbd>, <kbd>\eoe;</kbd> .<br + /> A period followed either by two blank spaces or by a newline + is recorded as an end of sentence. There is similar provision + for the question mark and the exclamation point. These tagged + forms may be used explicitly for the corresponding punctuation + inside math displays to distinguish punctuation from + mathematical use of the punctuation symbols. Explicit markup + for a comma is “<kbd>\cma;</kbd>”.<sup><a id="revfnote22" href="#fnote22">22</a></sup> + + </p> +</li> +</ol> +<p> +</p> +</div> +</div> + +<div class="subsection"> +<h4>5.3.  <a id="SU-5.3"></a><a id="large"></a>Large Structure</h4> + +<p>Overall an <em>article</em> consists of a <em>preamble</em> followed by +a <em>body</em>. As <a href="#beginend">noted previously</a> (section 3.3) advanced mode +provides a special form of usage +</p> +<div class="display"><table class="gdisplay"><tbody><tr><td> +<kbd>\begin{document} . . . \end{document}</kbd></td></tr></tbody></table></div> +<p> +with the paired metacommands <em>begin</em> and <em>end</em> that with an +<em>article</em> delimit its <em>body</em>. This is enabled with the +<em>gellmu-trans</em> call for the syntactic translator, and, consistent with regular +<em>LaTeX</em> usage the <em>preamble</em> is present without explicit tagging. </p> + +<p>The only required markup in a <em>preamble</em> is a <em>title</em>, and it +is formally correct for its content to be empty. The SGML content +model for a <em>body</em> is somewhat loose, but is usually understood +to consist of <em>section</em>s and may contain ordinary paragraphs +(<em>par</em>, which must be marked up explicitly, or <em>parb</em>, +which is begun with a blank line). Although a <em>body</em> may be entirely +empty (likely not useful) or may consist only of <em>par</em> and +<em>parb</em> elements, all inline text must be within one of these +basic paragraph containers. </p> + +<p>For example this formally correct textless document is handled without +noise by the didactic production system: +</p> +<dl class="verblist"> +<dd><kbd> +\documenttype{article}</kbd></dd> +<dd><kbd> +\title{}</kbd></dd> +<dd><kbd> +\begin{document}\end{document}</kbd></dd> +</dl> +<p> +while the following document with text outside of a paragraph fails +initial validation in the didactic production system: +</p> +<dl class="verblist"> +<dd><kbd> +\documenttype{article}</kbd></dd> +<dd><kbd> +\title{}</kbd></dd> +<dd><kbd> +\begin{document}</kbd></dd> +<dd><kbd> +x</kbd></dd> +<dd><kbd> +\end{document}</kbd></dd> +</dl> +<p> +The error may be corrected by placing a blank line before the +character ‘<kbd>x</kbd>’. </p> + +<p>The content model for <em>preamble</em> is tighter than that for +<em>body</em>. This makes it possible to have a greater level of +error-checking than would otherwise be possible. For example, a +preamble must have exactly one <em>title</em> although it is not +specified where in the preamble a title might be. There may be at +most one of each of the elements <em>surtitle</em>, <em>subtitle</em>, and +<em>date</em>. Although <em>newcommand</em>, which is a metacommand, does +not affect the document type definition and may be used at different +locations in the preamble, the small number of actual elements that +may be multiply used in the preamble, such as <em>mathsym</em> (which is +partly a metacommand) must be located together. +</p> +</div> + +<div class="subsection"> +<h4>5.4.  <a id="SU-5.4"></a><a id="sectioning"></a>Sectioning</h4> + +<p>In classical <em>LaTeX</em> one writes simply +</p> +<div class="display"><table class="gdisplay"><tbody><tr><td> +<kbd>\section{Some title for a section}</kbd></td></tr></tbody></table></div> +<p> +to begin a new section. While this markup specifically delineates +the section title, <em>LaTeX</em> understands that a section has begun. +The <em>section</em> command has an option whose content is an alternate +title for the table of contents, and the starred form of the command +suppresses an otherwise automatic section number. </p> + +<p>With SGML the classical approach is something along the following +lines: +</p> +<dl class="verblist"> +<dd><kbd> +<section><sectiontitle>Some title for a section</sectiontitle></kbd></dd> +<dd><kbd> +<para> A paragraph.</kbd></dd> +<dd><kbd> +<para> Another paragraph.</kbd></dd> +<dd><kbd> +     . . .</kbd></dd> +<dd><kbd> +</section></kbd></dd> +</dl> +<p> +<em>Basic</em> GELLMU markup corresponding to this would +be:<sup><a id="revfnote23" href="#fnote23">23</a></sup> +</p> +<dl class="verblist"> +<dd><kbd> +\begin{section}\sectiontitle{Some title for a section}</kbd></dd> +<dd><kbd> +\para A paragraph.</kbd></dd> +<dd><kbd> +\para Another paragraph.</kbd></dd> +<dd><kbd> +    . . .</kbd></dd> +<dd><kbd> +\end{section}</kbd></dd> +</dl> +<p> +If, moreover, the markup is to be well-formed XML markup, then each +<em>para</em> tag would need explicit closure with <kbd></para></kbd>. </p> + +<p>The main point here is that the open and close tags for a section +in a classical SGML document type encompass the whole contents of +a section, and separate markup is required for the section +title.<sup><a id="revfnote24" href="#fnote24">24</a></sup></p> + +<p>The didactic SGML document type under <em>advanced</em> GELLMU seeks to +model classical <em>LaTeX</em> as closely as possible in order to provide a +bridge for authors from <em>LaTeX</em> to SGML (and, indeed, XML). For +this reason a command <em>section</em> similar to the classical <em>LaTeX</em> +command that delineates a section title is provided in the didactic +SGML document type. At the same time this document type has a whole +section container <em>Section</em> (upper case <em>S</em>) that in the +simplest case consists of a <em>shead</em> container for its title (or +header) followed by any number of paragraphs. The XML form of the +didactic document type supports only this latter tag, which means that +the translation script that converts SGML to XML has an unambiguous +way of performing the conversion from <em>section</em> to <em>Section</em> +provided that the author's source leads to an SGML instance which is +valid<sup><a id="revfnote25" href="#fnote25">25</a></sup> +under the didactic document type. +</p> +</div> + +<div class="subsection"> +<h4>5.5.  <a id="SU-5.5"></a><a id="labelref"></a>Labels, References, and Anchors</h4> + +<p>A <em>label</em> command may be placed anywhere that text may be placed +in order to mark a location and associate a symbolic “key” +with that location. A <em>ref</em> command may be placed anywhere that +text may be placed to generate a visible allusion called its +<em>reference value</em>, for example a section number, to the location +associated with a label key. An <em>anch</em> command may be placed +anywhere that text may be placed to provide a hypertext reference +either by key to an internal location or by uniform resource +identifier (URI) to an external resource. </p> + +<p>At this point the discussion will become descriptive of of the entire +didactic production system rather than simply of its document type. +</p> + +<div class="subsubsection"> +<h5>5.5.1.  <a id="SU-5.5.1"></a><a id="seq"></a>Labels and Sequencing</h5> + +<p>The basic usage for <em>label</em> is +</p> +<div class="display"><table class="gdisplay"><tbody><tr><td> +<kbd>\label[:series="</kbd> +<em>series-name</em> +<kbd>" serseq="</kbd> +<em>number</em> +<kbd>" refkey="</kbd> +<em>ref-key</em> +"<kbd>]{</kbd> +<em>key</em> +<kbd>}</kbd></td></tr></tbody></table></div> +<p> +where use of the attributes is optional and, moreover, the required +<em>key</em> may be empty, i.e., the markup <kbd>\label{}</kbd> is permitted. +The <em>key</em> must be a case-sensitive string that is +<b>monocase</b> unique.<sup><a id="revfnote26" href="#fnote26">26</a></sup> +The didactic production system will provide a unique automatically generated string value +for <em>key</em> if none is provided by the author; this can be useful +if a <em>series</em> name is specified as an attribute for the label. </p> + +<p>An author should never reference a label key not provided by the +author, but the empty element <em>popkey</em> is intended for processing +evaluation as the last label <em>key</em>, automatic or not, preceding +its location. </p> + +<p>Sequencing<sup><a id="revfnote27" href="#fnote27">27</a></sup> +may be handled under the GELLMU didactic <em>article</em> +document type using labels and references. Toward this end one +makes use of three SGML attributes that are provided with the +<em>label</em> tag: +</p> +<dl> +<dt><b> +series</b></dt> +<dd>The value is the name of a sequenced family of labels. + A label may belong to at most one family, but there may be multiple + labels at the same location. There is no default value of series. </dd><dt><b> +serseq</b></dt> +<dd>The value is the sequence number of the label in its series + if a series is defined. It is meaningless if no series is specified + for the label. </dd><dt><b> +refkey</b></dt> +<dd>The name of a label key from which to spawn an automatically + generated value for the attribute <em>serseq</em> of the current label. </dd></dl> +<p></p> + +<p>Every label has a reference value that is normally accessed with +the <em>ref</em> command. This results in the creation, when +the XML version is generated, of an XML entity reference with name +based on the reference's <em>key</em> argument, that matches a CDATA +entity definition at the top of the XML document. The use of indirection +provided by this entity technique means that it is immaterial whether the +reference is forward or backward. </p> + +<p>The <em>evalref</em> command gives access to the literal value of a +reference without indirection, and places that value as a literal in +the XML version of an article. Thus, <em>evalref</em> is the name of a +tag only in the SGML document type and in the author-level XML document +type but not in the elaborated XML document type. +An <em>evalref</em> invocation will be successful only with a backward +reference. This is extremely useful for managing non-default +numbering of sectional units. For ordinary label references its use +is undesirable even though it is possible for backward references. </p> + +<p>The reference value of a label is determined as follows: +</p> +<ol class="decimal"> +<li><p> Basic reference values are positive integers. Upper and lower +case alphabetic values and upper and lower case roman numeral values +may be obtained by applying the <em>series</em> command (not to be +confused with the <em>series</em> attribute for the <em>label</em> command) +to a basic reference value with <em>type</em> attribute of <em>series</em> +set to one of ‘<kbd>A</kbd>’, ‘<kbd>a</kbd>’, ‘<kbd>I</kbd>’, or ‘<kbd>i</kbd>’. +</p> +</li> +<li><p> If the label is assigned to a label series and is given a +<em>refkey</em> attribute, then the reference value of the label is the +reference value of the label referenced by the key that is the value +of the <em>refkey</em>. (This mechanism is used to re-start the +sequencing of the sectional unit id's at the end of this document.) +</p> +</li> +<li><p> Else if the label is assigned to a label series and the author +supplies an explicit <b>literal</b> numeric value for the +<em>serseq</em> attribute, then the value of <em>serseq</em> is its +reference value. (Markup — in particular, <em>evalref</em> — +cannot be used in defining an attribute value.) +</p> +</li> +<li><p> Else if the label is assigned to a label series, the reference +value of the label is the next (positive integer) value for a label +in that series. (This mechanism is used to control the sectional +id of the last section of this document. It may also be used to +run parallel interleaved sequences of sectional units, such as, for +example, questions and answers, within a document.) +</p> +</li> +<li><p> Else the reference value of the label is the sectional unit +identifier, i.e., its <em>sunit</em> value rather than the logical +value in its attribute <em>sid</em>, of the smallest sectional +unit containing the label. These values may not be numeric. For +example the string “A.3.2” might be a sectional unit +identifier. The <em>series</em> command should not be used to express +type conversion of a reference value that might resolve as a sectional +unit identifier. +</p> +</li> +</ol> +<p> +</p> +</div> + +<div class="subsubsection"> +<h5>5.5.2.  <a id="SU-5.5.2"></a>Anchors</h5> + +<p>The basic usage for <em>anch</em> is +</p> +<div class="display"><table class="gdisplay"><tbody><tr><td> +<kbd>\anch[</kbd> +<em>reference specs</em> +<kbd>]{</kbd> +<em>anchored text</em> +<kbd>}</kbd></td></tr></tbody></table></div> +<p> +where the option, which is not an attribute option but rather +becomes the element <em>anchref</em> in XML (while the anchor's argument +— its “presented content” — becomes <em>anchv</em>), is +expected to contain white space separated strings of the form +<kbd>name="value"</kbd><sup><a id="revfnote28" href="#fnote28">28</a></sup> +with name restricted to one of the following: +</p> +<dl> +<dt><b>fref</b></dt> +<dd> A footnote reference. Value is a string + that becomes the content of an automatically created + footnote to the text in <em>anchv</em>. This usage is deprecated; + use \footnote instead. +</dd> +<dt><b>href</b></dt> +<dd> A web reference as with <em>href</em> in HTML. + That is, value is a URI. It <em>could be</em> of the form + “<kbd>#labelkey</kbd>” where “<kbd>labelkey</kbd>” is the name of a label + key that is preferably and more easily used with <em>iref</em>. + (The ‘<kbd>#</kbd>’ needs to be escaped, i.e., marked up as + “<kbd>\#</kbd>”.) In a non hypertext formatting the URI + may be presented as a note or footnote associated with the text in + <em>anchv</em>. +</dd> +<dt><b>Href</b></dt> +<dd> Same as <em>href</em> except that the author wishes + to suppress any note or footnote presentation of the URI. This + might be the case if, for example, the URI might be obviously + deducible from the <em>anchv</em> content. +</dd> +<dt><b>iref</b></dt> +<dd> An internal reference; value must be a label key arising + from <em>label</em> or <em>klabel</em><sup><a id="revfnote29" href="#fnote29">29</a></sup>. </dd> +</dl> +<p> + Note also that there is a command <em>urlanch</em> (probably should have + been <em>urianch</em>), taking a single argument, used for URIs, + which is intended to have the same effect as a newcommand with + one argument for creating a web anchor with the URI as presented + content. +</p> +</div> + +<div class="subsubsection"> +<h5>5.5.3.  <a id="SU-5.5.3"></a><a id="counters"></a>Example Emulating a <em>LaTeX</em> Counter</h5> + +<p>Suppose that one wants to fashion an inline enumerated list at some +point in a document. An <em>enumerate</em> environment is a list +structure that, while it may occur in a paragraph, is not inline. The +idea is to give each item a label and fashion the inline list item +number by referencing that label. One writes a newcommand to ease +this. </p> + +<p>The name of a <em>LaTeX</em> counter is emulated with the name of the +<em>series</em> attribute for one or more labels. Unless one wishes to +be able to reference the items apart from the immediate reference, one +need not provide a label key. The didactic production system will provide a default labelkey +and the command “<kbd>\popkey</kbd>”, which grabs the key of the last preceding +label, may be used to furnish the key for the immediate reference. +If one wants small Roman numerals, one wraps the “<kbd>\ref</kbd>” command +in a “<kbd>\series</kbd>” command. Since <em>series</em> requires an actual +number, one must use <em>evalref</em> instead of <em>ref</em>, which is +permitted so long as the reference follows the label. +Here's the markup: +</p> +<dl class="verblist"> +<dd><kbd> +\label[:series="foo" serseq="0"]{} % zero the counter named foo</kbd></dd> +<dd><kbd> +\newcommand{\ti}{%</kbd></dd> +<dd><kbd> +\label[:series="foo"]{}(\series[:type="i"]{\evalref{\popkey}})}</kbd></dd> +<dd><kbd> +Hilbert's three most important contributions to algebraic geometry</kbd></dd> +<dd><kbd> +are \ti~the basis theorem, \ti~the nullstellensatz, and \ti~the syzygy</kbd></dd> +<dd><kbd> +theorem.</kbd></dd> +</dl> +<p> +The rendering is this: +<a id="KEY-1"></a> + + +Hilbert's three most important contributions to algebraic geometry +are <a id="KEY-2"></a>(i) the basis theorem, <a id="KEY-3"></a>(ii) the nullstellensatz, and <a id="KEY-4"></a>(iii) the syzygy +theorem. </p> + +<p>With the current didactic production system if one had used “<kbd>\ref</kbd>” instead of +“<kbd>evalref</kbd>”, the translator from author-level XML to elaborated +XML, which resolves references, would have issued a warning in the +scroll, but the build would have run to otherwise successful completion +by ignoring the presence of the <em>series</em> command. +</p> +</div> +</div> + +<div class="subsection"> +<h4>5.6.  <a id="SU-5.6"></a><a id="secusage"></a><a id="last"></a>General Usage for Sectional Units</h4> + +<p>This describes the content model in the GELLMU didactic document type +for the “whole” sectional units <em>Section</em>, +<em>Subsection</em>, … as fully tagged. +</p> + +<div class="subsubsection"> +<h5>5.6.1.  <a id="SU-5.6.1"></a><a id="seccontent"></a>The Content Model</h5> + +<p>The content model for sectional units is: +</p> +<div class="display"><table class="gdisplay"><tbody><tr><td> +<kbd>((sopt)?,(sprefix)?,(sunit)?,(shead),(%UnitContent)*)</kbd></td></tr></tbody></table></div> +<p> +where: +</p> +<dl> +<dt><b>%UnitContent</b></dt> +<dd> refers to the subsections, loose paragraphs, and other general content + that is allowed inside a section. +</dd> +<dt><b>shead</b></dt> +<dd> is the required<sup><a id="revfnote30" href="#fnote30">30</a></sup> + section header or title. +</dd> +<dt><b>sopt</b></dt> +<dd> is an optional title for use in the table of + contents<sup><a id="revfnote31" href="#fnote31">31</a></sup>. +</dd> +<dt><b>sprefix</b></dt> +<dd> is optional markup for text that is to precede the sectional unit + sequence notation. For example, if the sectional unit sequence is + “B” and <em>sprefix</em> is the markup string + “<kbd>Appendix </kbd>” (ending with a blank space), then the visible + indicator for the sectional unit, when consistent with the setting of + <em>secnumdepth</em>, is “Appendix B” both at the beginning + of the section and in the table of contents. Or if the sequence is + “3” and the <em>sprefix</em> is “A”, then the + visible indicator is “A3”. +</dd> +<dt><b>sunit</b></dt> +<dd> is an optional setting for the sectional unit sequence. The GELLMU + didactic document type has an attribute “sid” for the + sectional units <em>Section</em>, <em>Subsection</em>, … that is + optional (and rare for author usage) in the SGML version but + required in the XML version. The translator from SGML to XML + computes it in the standard way. For example subsubsection 1 of + subsection 3 in section 2 acquires the <em>sid</em> “2.3.1”. + It is expected that formatters will use this value for the visible + sectional unit indicator, preceded, as previously described, by + any <em>sprefix</em>, unless the user provides <em>sunit</em>. While + <em>sunit</em> is intended to override the visible indicator, it is + not provided to override the <em>sid</em> attribute itself which a + formatter should see as describing logical structure. </dd> +</dl> +<p> +</p> +</div> + +<div class="subsubsection"> +<h5>5.6.2.  <a id="SU-5.6.2"></a><a id="ltxsecusage"></a>The <em>LaTeX</em>-Like Form of General Usage</h5> + +<p>Corresponding <em>LaTeX</em>-like <em>argument</em>/<em>option</em> syntax can be used, as previously +indicated, in GELLMU source with <em>section</em>, <em>subsection</em>, +… . If, however, <em>argument</em>/<em>option</em> syntax is used, one must be mindful of +the ordering of the options, and use empty option brackets, as +necessary, to indicate the position in the sequence of an option with +content. For example, a sole option is understood as <em>sopt</em>, the +version of the sectional unit title to be used in the table of +contents. To provide only <em>sprefix</em> with <em>argument</em>/<em>option</em> syntax one +precedes the bracket sequence for <em>sprefix</em> with an empty pair +“<kbd>[]</kbd>” of option brackets<sup><a id="revfnote32" href="#fnote32">32</a></sup> +for <em>sopt</em>. +</p> +</div> +</div> + +<div class="subsection"> +<h4>5.7.  <a id="SU-5.7"></a><a id="verb"></a><em>verbatim</em>, <em>verblist</em>, and +<em>manmac</em></h4> + +<p>The ordinary notion of “verbatim” is complicated in the +context of a document type that is intended for processing toward +multiple output formats. There is no special provision for verbatim +markup under <em>basic</em> GELLMU<sup><a id="revfnote33" href="#fnote33">33</a></sup>, +but there are two layers, one simplistic and one sophisticated, in the +didactic production system with each layer having provision for both inline and block-level +verbatim markup. </p> + +<p>The simplistic approach involves the provision of an inline element +<em>verb</em> and a block-level element <em>verbatim</em> in the didactic document type. +With these the author is responsible for entering special characters +in ways that are safe for input source notation, safe for syntactic translator +output, and safe for each output format that is envisioned.<sup><a id="revfnote34" href="#fnote34">34</a></sup> +In the simplistic layer the formatting program in the didactic production system for HTML +output renders <em>verb</em> as an HTML <em>kbd</em> element and +<em>verbatim</em> as an HTML <em>pre</em> element. In formatting for +regular <em>LaTeX</em> output each of these SGML elements is rendered +as its <em>LaTeX</em> namesake. Neither the <em>pre</em> element in HTML +nor the (basic) <em>verbatim</em> command in <em>LaTeX</em> is context-sensitive, +and typically are formatted with left margin justification. </p> + +<p>The sophisticated layer in the syntactic translator for <em>verbatim</em> is enabled by +setting the variable <em>gellmu-verbatim-clean</em> true. If this is +the case, then a user should input verbatim material literally between +<kbd>\begin{verbatim}</kbd> and <kbd>\end{verbatim}</kbd> markers occupying whole lines +and the syntactic translator will convert each of the 33 non-alphanumeric printable +ASCII characters therein to the corresponding empty element in +the didactic document type, and render each line of the converted material as a list +item bearing the item name <em>nln</em> in a list element +<em>verblist</em>.<sup><a id="revfnote35" href="#fnote35">35</a></sup></p> + +<p>Similar arrangements pertain to the sophisticated inline analogue +of <em>verb</em>, which is enabled in the syntactic translator by setting the variable +<em>gellmu-manmac-bar-name</em> to a non-empty string value that is +to become the name of the element, such as <em>quostr</em>, to contain +the content, which should be delimited in source by successive +‘<kbd>|</kbd>’ characters. By default the user must enter a +verbatim string in “safe” form, but may enter it, +apart from any occurrence of the character ‘<kbd>|</kbd>’, literally +if the variable <em>gellmu-manmac-literal</em> is true. The term +“manmac” is derived from an old plain <em>TeX</em> package for +writing documentation by that name in which the character ‘<kbd>|</kbd>’ +is used to delimit inline literal material for verbatim presentation. +Moreover, consistent with usage observed in <em>LaTeX</em> documentation +markup of the form +</p> +<div class="display"><table class="gdisplay"><tbody><tr><td> +<kbd>\</kbd><em>name</em><kbd>|</kbd><em>literal-text</em><kbd>|</kbd></td></tr></tbody></table></div> +<p> +is translated by the syntactic translator to an element named as with simple +“<kbd>|...|</kbd>” having a setting for its attribute +with name the value of the string variable +<em>gellmu-manmac-attribute</em>, which for <em>quostr</em> in the didactic document type +would appropriately be its attribute <em>inv</em>. </p> + +<p>Variable settings to provide for the use of literal input both for +<em>verbatim</em> as a metacommand front for the list element +<em>verblist</em> and <em>manmac</em> configuration for the element +<em>quostr</em>, as described, are default when the syntactic translator is begun with +the non-default function <em>gellmu-latex-faq</em>. This function also +sets the variable <em>gellmu-squophrase-name</em>, which otherwise +defaults to the empty string, to the value “<kbd>squophrase</kbd>”. +This causes the syntactic translator to attempt to interpret balancing +character pairs consisting of the character ‘<kbd>‘</kbd>’ and the +character ‘<kbd>’</kbd>’ as delimiters for the element +<em>squophrase</em>, an alternate form along with <em>quophrase</em>, +for “quoted phrase”, with odd instances of the character +‘<kbd>’</kbd>’ set as the empty element <em>apos</em>, which represents +an apostrophe. +</p> +</div> + +<div class="subsection"> +<h4>5.8.  <a id="SU-5.8"></a><a id="accents"></a>Accents</h4> + +<p>Traditional <em>LaTeX</em> markup employs accent commands for modifying +ASCII characters in order to produce non-ASCII +characters. On the other hand characters from 16 +“byte-planes” of Unicode are now available in HTML +and XML as ordinary characters, with treatment as the atoms of +ordinary strings of text not requiring any special attention or notice +from the viewpoint of markup. It may happen that this will affect +development in the <em>LaTeX</em> project, and it is, therefore, unclear what +the long term role might be of <em>LaTeX</em>'s accent commands. </p> + +<p>Nonetheless, the didactic document type provides element names corresponding to the +14 classical <em>LaTeX</em> accents although it does not provide classical +markup notations such as “<kbd>\'</kbd>”, +“<kbd>\"</kbd>”, “<kbd>\~</kbd>”, … inasmuch +as names are required in syntactic translator output.<sup><a id="revfnote36" href="#fnote36">36</a></sup> +The names for the accents may be seen by locating the word +“accent” in the didactic production system file <kbd>gellmu.dtd</kbd> and reading +the following 14 lines. </p> + +<p>An author, particularly an author residing in an English language +locale, may introduce, for example, the character é in +several ways: +</p> +<ol class="decimal"> +<li><p> by using an algorithmic accent command — in this case + <kbd>\acute{e}</kbd>: é. </p> +</li> +<li><p> by direct Unicode-based entity reference – in this case + <kbd>&#xE9;</kbd>: é. </p> +</li> +<li><p> by simple direct entry of the Unicode point in a file + having the UTF-8 text encoding. </p> +</li> +</ol> +<p> +Note that Unicode values are numbers represented in hexadecimal +notation (base 16); the digits are 0–9 and A–F. Thus, E9 is +233, and one could also use the entity reference <kbd>&#233;</kbd>. </p> + +<p>While for the long term, the largely equivalent<sup><a id="revfnote37" href="#fnote37">37</a></sup> +second or third methods are superior, +there are caveats for their use in 2007: +</p> +<ul> +<li><p> One's <em>LaTeX</em> back end must have a suitably robust way + of handling Unicode, presumably via the <em>inputenc</em> + package or possibly via <em>Omega/Lambda</em>. +</p> +</li> +<li><p> Even when fonts are available, some web browsers + seem only to handle Unicode via entity references. </p> +</li> +</ul> +<p> + +</p> +</div> + +<div class="subsection"> +<h4>5.9.  <a id="SU-5.9"></a><a id="tabular"></a>Tabular Environment Emulation</h4> + +<p>At this point (2006-7) the didactic document type is able to accomodate emulation +of <em>LaTeX</em>'s <em>tabular</em> environment with “<kbd>l</kbd>”, “<kbd>c</kbd>”, +“<kbd>r</kbd>”, and “<kbd>p</kbd>” column cell specifiers with, where +robust CSS support is available for HTML, “<kbd>|</kbd>” indicators +for vertical cell rules and “<kbd>\hline</kbd>” commands for horizontal +rules between rows. While <em>multicol</em>, and <em>multirow</em> are not +modeled, cells may contain other <em>tabular</em>s recursively. </p> + +<p>A “<kbd>p</kbd>” column specifier optionally takes a decimal argument +that represents the fraction of available width to be made available +for the cells in that column. When is no fractional width specifier, +the default fractional width is <math xmlns="http://www.w3.org/1998/Math/MathML" mode="inline" +><mfrac +><mn>1</mn><mrow><mi>n</mi><mo>+</mo><mn>1</mn></mrow +></mfrac +></math +> where <math xmlns="http://www.w3.org/1998/Math/MathML" mode="inline" +><mi>n</mi></math +> is the +total of number of columns. </p> + +<p>What may be viewed as a shortcoming of the <em>tabular</em> emulation +is that in each <em>tabular</em> row the first cell must contain +some markup in order for the document to be structurally correct. +This arises from a rule associated with SGML document types +that might be overcome if GELLMU source were processed by a +monolithic program. Instead, however, it is an +assemby of <a href="#flow">separate components</a> (appendix 7.5.2) in which the first stage +has knowledge of syntax but not of the markup vocabulary. </p> + +<p>One thing to keep in mind with <em>tabular</em> is that in the current, +though probably not future, design of HTML tables are not allowed +in paragraph content. The didactic production system works hard to deal with this. In most +web browsers there will be a line break before an HTML table and +again after an HTML table. (One way to finesse that is to place a +table in a cell in a sur-table, which is abuse of markup.) This +author generally places a <em>tabular</em> inside a <em>display</em>, +which is the GELLMU object corresponding to <em>LaTeX</em>'s <em>center</em>. </p> + +<p>The document type does not offer “floating” objects, and, therefore, +the name <em>table</em> is not used as as in <em>LaTeX</em>. </p> + +<p>The name <em>table</em> is used for emulation in regular GELLMU +source of HTML tables. A <em>table</em>, like a <em>tabular</em>, +takes a required argument consisting of column specifiers. +In the didactic production system at the point where an article is spun to the elaborated +XML version of <em>article</em>, there is no longer a distinction +between <em>tabular</em> and <em>table</em>. </p> + +<p>There is also <em>array</em>, which, as in <em>LaTeX</em>, is the in-math +version of <em>tabular</em>, except that in GELLMU its emulation of +<em>LaTeX</em>'s array survives translation to the XML version of +<em>article</em>. An <em>array</em> has only “<kbd>l</kbd>”, “<kbd>r</kbd>”, +and “<kbd>c</kbd>” cells. </p> + +<p><b>Example:</b> The markup for the <a href="#dtdfiles">table of DTD's</a> +in Appendix B.2.2 is this: +</p> +<dl class="verblist"> +<dd><kbd> +\begin{display}</kbd></dd> +<dd><kbd> +\begin{tabular}{l|cc}</kbd></dd> +<dd><kbd> +~                       & Latin-1              & \abbr{UTF-8}          \\</kbd></dd> +<dd><kbd> +\hline</kbd></dd> +<dd><kbd> +First stage \abbr{SGML} &  \quostr{gellmu.dtd} &  \quostr{ugellmu.dtd} \\</kbd></dd> +<dd><kbd> +Author Level \abbr{XML} &  ~                   & \quostr{axgellmu.dtd} \\</kbd></dd> +<dd><kbd> +Elaborated \abbr{XML}   & \quostr{xgellmu.dtd} & \quostr{uxgellmu.dtd}</kbd></dd> +<dd><kbd> +\end{tabular}</kbd></dd> +<dd><kbd> +\end{display}</kbd></dd> +</dl> +<p> +Because the one horizontal divider and the one vertical divider rely +on CSS support in HTML, these dividers might not be seen in a web +browser with weak CSS support. +</p> +</div> + +<div class="subsection"> +<h4>5.10.  <a id="SU-5.10"></a><a id="graphics"></a>Graphic Inclusions</h4> + +<p>There is basic support for graphics inclusions suitable for the HTML +backend and the <em>LaTeX</em> backend with both DVI and PDF outputs. +The arrangements are not unlike those required for the use of +the <em>includegraphics</em> command provided by <em>LaTeX</em>'s +<em>graphicx</em> package. This means that, apart from the didactic production system's chain +of processors, one needs to provide several different versions of a +given graphic object in order to accommodate the needs of the three +different output formats (HTML, PDF, and DVI). A reliable graphics +format converter such as that provided by <em>ImageMagick</em> +(<a href="http://www.imagemagick.org/"><kbd>http://www.imagemagick.org/</kbd></a>) +or the <em>netpbm</em> utilities +(<a href="http://netpbm.sourceforge.net/"><kbd>http://netpbm.sourceforge.net/</kbd></a>) +and a broad <em>TeX</em> support environment similar to that provided by +TUG's <a href="http://www.tug.org/texlive/"><em>TeXLive</em></a> +are essential for work with included graphics. </p> + +<p>For example, if one begins with an encapsulated PostScript image +<kbd>glmy.eps</kbd> made, say, with Metapost, then one might run +the commands +</p> +<dl class="verblist"> +<dd><kbd> +   epstopdf glmy.eps</kbd></dd> +<dd><kbd> +   convert glmy.pdf glmy.png</kbd></dd> +</dl> +<p> +before making PDF with <em>pdflatex</em> and PNG (for inclusion +in HTML). In this case the PDF version of the graphic should be +regarded as best for use with <em>pdflatex</em>, and so one wants to +have the PNG version out of view from <em>pdflatex</em> when +building the GELLMU source <kbd>glman.glm</kbd> for this document. +With the new <em>mmkg</em> drivers one may prepare a tiny file +<kbd>glman.prx</kbd> that is a list of names of image files, one file +per line, that should be out of view at the point in the pipeline when +<em>pdflatex</em> is active. Thus, a line in the file +<kbd>glman.prx</kbd> should contain the name <kbd>glmy.png</kbd>. </p> + +<p>In <a href="glman.glm"><kbd>glman.glm</kbd></a> one has the +code: +</p> +<dl class="verblist"> +<dd><kbd> +\begin{quotation}</kbd></dd> +<dd><kbd> +   Sometimes a picture is worth a thousand words.</kbd></dd> +<dd><kbd> +   \display[:frame="1.1"]{\includegraphics[:scale="0.2"]{glmy}}</kbd></dd> +<dd><kbd> +\end{quotation}</kbd></dd> +</dl> +<p> +which yields: +</p><blockquote> + +<p>Sometimes a picture is worth a thousand words. + </p> +<div class="display"><table class="gdisplay" style="padding: 1ex; border: 0.3ex solid;"><tbody><tr><td> +<img src="glmy.png" alt="Image file: glmy.png" /> +</td></tr></tbody></table></div> +<p></p> +</blockquote> +<p></p> + +<p>In this markup one sees, first of all, two uses of SGML +attributes — <em>frame</em> and <em>scale</em>. Attribute +options are opened with “<kbd>[:</kbd>” rather than simply with +“<kbd>[</kbd>”. Whereas options generally may contain markup, +attribute options may not. </p> + +<p>The meaning in this example of <em>scale</em> is that the <b>width</b> +of the graphic in DVI and PDF outputs will be the result +of multiplying the <em>scale</em> by <em>LaTeX</em>'s value of +<em>\textwidth</em>.<sup><a id="revfnote38" href="#fnote38">38</a></sup> +The HTML formatter will link to the PNG without a width +specification. Thus, the brower window width of the graphic will be +the actual width of the PNG image unless, perhaps, it's too large for +the browser's window. The meaning of <em>frame</em> is that for print +outputs the graphic image will be surrounded by a <em>LaTeX</em> +<em>framebox</em> with diameter that is <math xmlns="http://www.w3.org/1998/Math/MathML" mode="inline" +><mn>1.1</mn></math +> times the diameter of the +<em>display</em>'s content. In the current HTML formatter no use is +made of the numeric value of <em>frame</em> although a default frame is +constructed via an HTML attribute giving values for the CSS +properties <em>border</em> and <em>padding</em>. When image framing is +desired, another approach is to incorporate framing in the graphic +itself. +</p> +</div> +</div> + +<div class="section"> +<h3>6.  <a id="SU-6"></a><a id="math"></a>Mathematics in <em>article</em></h3> + +<div class="subsection"> +<h4>6.1.  <a id="SU-6.1"></a><a id="genmath"></a>General</h4> + +<p>There was previous mention of the basic mathematical container element +<em>tmath</em> in the discussion of <a href="#single">single string</a> (section 5.2.2) markup +and the <em>math</em> and <em>displaymath</em> elements in the discussion +of <a href="#certainstrings">certain strings</a> (section 5.2.3) of special markup +significance. </p> + +<p>The markup used inside these containers is very similar to that +which is used in <em>LaTeX</em> although far from all of <em>LaTeX</em>'s math +markup, as extended by the <em>amsmath</em> package, has any +analogue in the didactic production system. </p> + +<p>There are a few things that deserve short mention: +</p> +<dl> +<dt><b>\sum, \int, and \prod</b></dt> +<dd> are all similar to +their <em>LaTeX</em> namesakes except that each requires explicit closure. +For example, + +<div class="display"><table class="gdisplay"><tbody><tr><td> +<kbd>\[ \sum_{0}^{\infty} \frac{x^k}{k!} \sum: \]</kbd></td></tr></tbody></table></div> + +produces + +<math xmlns="http://www.w3.org/1998/Math/MathML" display="block" mode="display" +><mrow><munderover><mo>∑</mo><mn>0</mn><mi>∞</mi></munderover><mfrac +><mrow><msup><mi>x</mi><mi>k</mi></msup +></mrow +><mrow><mi>k</mi><mo>!</mo></mrow +></mfrac +></mrow +><mspace width="0.6em"/><mtext>.</mtext +></math> + +</dd> +<dt><b>\regch, \mbox, and \text</b></dt> +<dd> The didactic document type provides <em>regch</em>, +for “regular character” that is a one character version +of <em>mbox</em> provided for separating from general +<em>mbox</em> matter the content to which a non-math +<a href="#accents">algorithmic accent</a> (section 5.8), may +be applied. For example, +<dl class="verblist"> +<dd><kbd> +\newcommand{\Q}{\regch{\bold{Q}}}  % intended for use in math</kbd></dd> +<dd><kbd> +\newcommand{\galQ}{\mbox{Gal}(\ovbar{\Q}/\Q)}  % only in math</kbd></dd> +<dd><kbd> +$\galQ$\aos;</kbd></dd> +</dl> + +produces + + +<math xmlns="http://www.w3.org/1998/Math/MathML" mode="inline" +><mi>Gal</mi><mfenced open="(" close =")" +><mrow><mover accent="true"><mi mathvariant="bold" fontweight="bold" fontstyle="normal">Q</mi><mo>¯</mo></mover +><mo stretchy="true" lspace="0.3em" rspace="0.3em">⁄</mo><mi mathvariant="bold" fontweight="bold" fontstyle="normal">Q</mi></mrow></mfenced +></math +>. + +<p>Both <em>regch</em> and <em>mbox</em> should be used only for symbols. +Note that “Gal” in the foregoing is a symbol. The command +\text is provided for the use of text phrases – usually conjunctive +in nature – inside math zones. For example, the markup +</p> +<dl class="verblist"> +<dd><kbd> +\[ \absval{x} = \lbalbr{\begin{array}{rl}</kbd></dd> +<dd><kbd> +             x & \text{\ if\ } x \geq 0 \\</kbd></dd> +<dd><kbd> +            -x & \text{\ if\ } x < 0</kbd></dd> +<dd><kbd> +            \end{array}} \]</kbd></dd> +</dl> +<p> +produces + +<math xmlns="http://www.w3.org/1998/Math/MathML" display="block" mode="display" +><mfenced open="|" close="|"><mi>x</mi></mfenced><mo>=</mo><mfenced open="{" close ="" +><mtable +><mtr><mtd columnalign="right"><mi>x</mi></mtd +><mtd columnalign="left"><mtext +> if </mtext +><mi>x</mi><mo>≥</mo><mn>0</mn></mtd +></mtr><mtr><mtd columnalign="right"><mo>−</mo><mi>x</mi></mtd +><mtd columnalign="left"><mtext +> if </mtext +><mi>x</mi><mo><</mo><mn>0</mn></mtd +></mtr></mtable +></mfenced +></math> + +In this example note that the command name <em>lbalbr</em> stands for +“<b>l</b>eft <b>bal</b>anced <b>br</b>ace”. It corresponds to +the use of <kbd>\left\{  ...  \right.</kbd> in <em>LaTeX</em><sup><a id="revfnote39" href="#fnote39">39</a></sup>. +</p> +</dd> +<dt><b>\aos;, \aoc; \aoq;, and \aoe;</b></dt> +<dd> are the +named forms of the <em>LaTeX</em> space adjustment commands “<kbd>\@.</kbd>”, +“<kbd>\@,</kbd>”, “<kbd>\@?</kbd>”, and “<kbd>\@!</kbd>”, which +provide correct placement of inline punctuation immediately following +inline mathematical markup. There is now also default provision in the +didactic production system for the more <em>LaTeX</em>-like “<kbd>\@</kbd>” usage. Note that the +use of <kbd>\@</kbd> is seldom necessary. +</dd> +</dl> +<p> +</p> +</div> + +<div class="subsection"> +<h4>6.2.  <a id="SU-6.2"></a><a id="assert"></a>Assertions: Near Emulation of + <em>LaTeX</em>'s Theorem-Like Environments</h4> + +<div class="subsubsection"> +<h5>6.2.1.  <a id="SU-6.2.1"></a>Examples</h5> + +<p>The container element <em>\assertion</em> is used in the didactic document type for the +creation of its analogue under SGML of theorem-like environments. As +a first example of the near emulation of a <em>LaTeX</em> theorem-like +environment, here is markup to give <em>LaTeX</em>-like meaning to +“<kbd>\begin{theorem}</kbd>” and “<kbd>\end{theorem}</kbd>”. +</p> +<dl class="verblist"> +<dd><kbd> +\newcommand{\begin{thm}}[1][]{%</kbd></dd> +<dd><kbd> +\begin{assertion}[#1][theorem]{Theorem}[\evalref{\popkey}]}</kbd></dd> +<dd><kbd> +\newcommand{\end{thm}}{\end{assertion}}</kbd></dd> +</dl> +<p> + + + +For a first instance it is invoked without supplying the optional first +argument, which is for a label key. +<a id="AssertLabel-1"></a></p> +<dl class="assertion"> +<dd> +<b>Theorem 1.</b> +  The continued fraction expansion of a real number is finite +if and only if the real number is a rational number. </dd></dl> +<p> +This is just text to follow the statement of a theorem. </p> + +<p>If we do the same thing again, the theorem number should go up by +<math xmlns="http://www.w3.org/1998/Math/MathML" mode="inline" +><mn>1</mn></math +> since in the didactic production system this usage is equivalent to using the default +counter associated with a label series name <em>theorem</em>.<sup><a id="revfnote40" href="#fnote40">40</a></sup> +<a id="AssertLabel-2"></a></p> +<dl class="assertion"> +<dd> +<b>Theorem 2.</b> +  The continued fraction expansion of a rational number is +eventually periodic if and only if the real number is an irrational +number that is the root of some quadratic polynomial with rational +coefficients. </dd></dl> +<p> +</p> +</div> + +<div class="subsubsection"> +<h5>6.2.2.  <a id="SU-6.2.2"></a><a id="assertion"></a>Usage for <em>assertion</em></h5> + +<p>The general usage of <em>assertion</em> is the following: +</p> +<dl> +<dd> <kbd>\begin{assertion}[</kbd><em>key</em><kbd>][</kbd><em>series</em> +<kbd>]{</kbd><em>name</em><kbd>}[</kbd><em>id</em><kbd>]</kbd></dd> +<dd> <kbd>  .  .  .</kbd></dd> +<dd> <kbd>\end{assertion}</kbd></dd> +</dl> +<p> +The options <em>key</em> and <em>series</em> represent the same things as +the corresponding <a href="#seq"><em>label</em></a> (section 5.5.1) options. The <em>id</em> +option is for explicit customization of the visible identifier, e.g., +theorem number, as illustrated with one of the examples later in this +section. One may use the <em>id</em> option, which must follow +the name argument, without using either of the other options. But in +order to use the <em>series</em> option, a <em>key</em> option, which may +simply be empty, must be present. </p> + +<p>There is also a fully named way to proceed: +</p> +<dl> +<dd> <kbd>\begin{assertion}</kbd></dd> +<dd> <kbd>\asstkey{. . .}\asstser{. . .}\asstname{. . .}\asstid{. . .}</kbd></dd> +<dd> <kbd>  .  .  .</kbd></dd> +<dd> <kbd>\end{assertion}</kbd></dd> +</dl> +<p> +Here order is important, but any of the options may simply be omitted. +For example, we may write +</p> +<dl class="verblist"> +<dd><kbd> +\newcommand{\begin{Thm}}[1]{%</kbd></dd> +<dd><kbd> +\begin{assertion}\asstser{#1}\asstname{Theorem}%</kbd></dd> +<dd><kbd> +\asstid{\sref;.\evalref{\popkey}}%</kbd></dd> +<dd><kbd> +}</kbd></dd> +<dd><kbd> +\newcommand{\end{Thm}}{\end{assertion}}</kbd></dd> +<dd><kbd> +\begin{Thm}{XXseries}</kbd></dd> +<dd><kbd> +If $[ n_1, n_2, \ldots ]$ is an infinite continued fraction, then</kbd></dd> +<dd><kbd> +its sequence of convergents always has a limit.</kbd></dd> +<dd><kbd> +\end{Thm}</kbd></dd> +</dl> +<p> +to obtain: + + + + + +<a id="AssertLabel-3"></a></p> +<dl class="assertion"> +<dd> +<b>Theorem 6.2.2.1.</b> +  If <math xmlns="http://www.w3.org/1998/Math/MathML" mode="inline" +><mfenced open="[" close ="]" +><mrow><msub><mi>n</mi><mn>1</mn></msub +><mo>,</mo><msub><mi>n</mi><mn>2</mn></msub +><mo>,</mo><mi>…</mi></mrow></mfenced +></math +> is an infinite continued fraction, then +its sequence of convergents always has a limit. </dd></dl> +<p> +Notice that the <em>asstid</em> argument is merging the reference value +for (the new) series <em>XXseries</em> with the visible id of the +current sectional unit. +</p> +</div> +</div> + +<div class="subsection"> +<h4>6.3.  <a id="SU-6.3"></a><a id="eqn"></a>Equations and Equation Arrays</h4> + +<p>The general usage for <em>equation</em> is the following: +</p> +<dl> +<dd> <kbd>\begin{equation}[</kbd><em>key</em><kbd>][</kbd><em>series</em><kbd>]</kbd></dd> +<dd> <kbd>  .  .  . </kbd></dd> +<dd> <kbd>\end{equation}</kbd></dd> +</dl> +<p> +The options <em>key</em> and <em>series</em> represent the same things as +the corresponding <a href="#seq"><em>label</em></a> (section 5.5.1) options. In order to use +the <em>series</em> option, a <em>key</em> option, which may simply be +empty, must be present. The use of “<kbd>equation*</kbd>” as a name for an +equation display that is not numbered is +not permitted, but one may instead use the <em>nonum</em> attribute +as follows: +</p> +<div class="display"><table class="gdisplay"><tbody><tr><td> +<kbd>\begin{equation}[:nonum="true"] . . . \end{equation}</kbd> .</td></tr></tbody></table></div> +<p></p> + +<p>General usage for an equation array (name <em>eqnarray</em>) is: +</p> +<dl> +<dd> <kbd>\begin{eqnarray}[</kbd><em>key</em><kbd>][</kbd><em>series</em><kbd>]</kbd></dd> +<dd> <kbd>  .  .  . </kbd></dd> +<dd> <kbd>\end{eqnarray}</kbd></dd> +</dl> +<p> +where the content is an <em>eqnabody</em> consisting of <em>eqnrow</em>'s, +each row may be terminated in <em>LaTeX</em>-like markup, as in <em>LaTeX</em>, with the +string “<kbd>\\</kbd>” and consists of three parts, corresponding to elements +<em>eqnleft</em>, <em>eqncenter</em>, and <em>eqnright</em>, that may +be separated in <em>LaTeX</em>-like markup with the character ‘<kbd>&</kbd>’. </p> + +<p>Support for numbering in eqnarrays is only minimally developed +although there is suggestive sketching in the didactic document type that is not +supported in the formatters. By default the equations in equation +arrays are numbered consecutively throughout an article. This +behavior can be altered by using the <em>series</em> attribute of an +<em>eqnarray</em>. If that is done, then, as things have been sketched, +numbering applies to whole arrays rather than to the equations within +arrays. Numbering in an equation array may be suppressed by setting +its attribute <em>nonum</em> to the string “<kbd>true</kbd>”. +</p> +</div> + +<div class="subsection"> +<h4>6.4.  <a id="SU-6.4"></a><a id="mathsym"></a>The \mathsym Metacommand</h4> + +<p><em>mathsym</em> is a macro substitution metacommand that is +available in the didactic production system for enabling an author to declare that a macro +name represents a mathematical symbol. It is a formal way of +recording statements commonly made by authors in introducing notation. </p> + +<p>Unlike regular metacommands, which may appear at any point in +GELLMU source, <em>mathsym</em> may only appear in the <em>preamble</em> +of an <em>article</em>, or, equivalently with defaults in the +syntactic translator, <em>mathsym</em> may only appear before the <em>LaTeX</em>-like +“<kbd>\begin{document}</kbd>”. </p> + +<p>Its usage is: +</p> +<div class="display"><table class="gdisplay"><tbody><tr><td> +<kbd>\mathsym{</kbd> +<em>symbol-name</em> +<kbd>}{</kbd> +<em>symbol-rendering</em> +<kbd>}[</kbd><em>symbol-meta-info</em> +<kbd>]</kbd> . </td></tr></tbody></table></div> +<p></p> + +<p>Here <em>symbol-name</em> is an alphanumeric string (case-sensitive) +beginning with a letter. The second argument is the presentation +rendering of the symbol in GELLMU markup. It is like the definition +of a <em>newcommand</em> except that it may not involve +arguments.<sup><a id="revfnote41" href="#fnote41">41</a></sup> +The optional third argument <em>symbol-meta-info</em> is an +alpha-numeric string that might also include possibly a few other +string characters such as ‘<kbd>/</kbd>’, ‘<kbd>-</kbd>’, ‘<kbd>,</kbd>’, +‘<kbd>.</kbd>’, ‘<kbd>*</kbd>’, etc. Its exact structure depends on the +typing system. (No typing system is part of the didactic production system.) For example, +it might consist of (name, value) pairs for conveying meta-information +about the symbol. </p> + +<p>The syntactic translator replaces each invocation of a given +<em>mathsym</em> with the specified rendering and writes for each +<em>mathsym</em> definition a corresponding element in the SGML output +whose content consists solely of the declared symbol name if there is +no meta information but otherwise consists of the symbol name followed +by a blank space and then whatever string of meta information is +provided in the optional argument. Additionally, each invocation is +wrapped in a rendering-inert <em>Sym</em> element whose <em>key</em> +attribute reveals the name given to the symbol at the point of +declaration (and by which the symbol is invoked). This makes it +possible for a downstream authoring platform processor that has +remembered the list of declared symbol names to match each invocation +of a declared symbol with its associated meta information, if any, +provided by the author in the symbol declaration. </p> + +<p>A related feature in the didactic GELLMU document type is the +<em>mlg</em> tag for marking mathematical logical groups. This is +somewhat akin to the <em>lgg</em> tag for <em>TeX</em>-like logical groups, +traditionally created in <em>TeX</em> markup with braces that are not +attached to a command.<sup><a id="revfnote42" href="#fnote42">42</a></sup> +As with <em>lgg</em> there is no obvious evidence of an <em>mlg</em> tag +in a typeset rendering, but the presence of such a tag is intended as +a signal to downstream mathematical parsers that the contents of the +tag be given grouping priority as, say, with visible parentheses. +Furthermore, the <em>mtype</em> and <em>mml</em> attributes of the +<em>mlg</em> tag may be used to pass semantic information about the +tag's contents to a processor. +</p> +</div> +</div> + +<div class="section"> +<h3>7.  <a id="SU-7"></a><a id="dps"></a>The Didactic Production System</h3> + +<p>The didactic production system is the suite of processors and technical support files +underlying what is called regular GELLMU. +</p> + +<div class="subsection"> +<h4>7.1.  <a id="SU-7.1"></a>Permission</h4> + +<p>The items of the didactic production system are copyrighted free software released +under the <a href="http://www.gnu.org/copyleft/">GNU General Public License</a>. +</p> +</div> + +<div class="subsection"> +<h4>7.2.  <a id="SU-7.2"></a><a id="materials"></a>Materials</h4> + +<p>The release contains everything originating with the author that is +currently used in “building” GELLMU documents. </p> + +<p>It also contains a slightly <a href="../perllib/SGMLS.pm">modified version</a> +of David Megginson's <em>Perl</em> module “<kbd>SGMLS.pm</kbd>” based on +another slightly modified version that was furnished to me by Dave +Holden in a very quick early 1999 response to my posted request for a +modification that handles the labels provided (optionally) by +<em>nsgmls</em> for SGML elements that are defined empty. A similar +slight modification was also supplied a few days later by Vassilii +Kachaturov and had been available at his web site. </p> + +<p>Although the materials offered in this package aside from the syntactic translator +pertain only to the didactic document type and the didactic production system, it should be understood that +the larger design for GELLMU envisions other parties, on the one +hand, building in various ways to extend the functionality of the +didactic system, and, on the other hand, applying the methods of the +didactic system to other document types and other formatting programs +for those document types. </p> + +<p>The basic items originating with the author, aside from the document +type definition <a href="#dtdfiles">files</a> (section B.2.2) are: +</p> +<dl> +<dt><b><a href="../gellmu.el"><kbd>gellmu.el</kbd></a></b></dt> +<dd>the GELLMU syntactic translator, which makes SGML</dd> +<dt><b><a href="../xplaingart.pl"><kbd>xplaingart.pl</kbd></a></b></dt> +<dd>converts SGML to + author-level XML</dd> +<dt><b><a href="../xmlgart.pl"><kbd>xmlgart.pl</kbd></a></b></dt> +<dd>converts author-level XML + to elaborated XML</dd> +<dt><b><a href="../ltxgart.pl"><kbd>ltxgart.pl</kbd></a></b></dt> +<dd>translates elaborated XML + to <em>LaTeX</em></dd> +<dt><b><a href="../htmlgart.pl"><kbd>htmlgart.pl</kbd></a></b></dt> +<dd>translates elaborated XML + to classical HTML and translates specially prepared XML to XHTML+MathML</dd> +<dt><b><a href="../mathcdata.pl"><kbd>mathcdata.pl</kbd></a></b></dt> +<dd>first of two special + preparations for translation toward XHTML+MathML</dd> +<dt><b><a href="../mathprep.pl"><kbd>mathprep.pl</kbd></a></b></dt> +<dd>second of two special + preparations for translation toward XHTML+MathML</dd> +<dt><b><a href="../mval.pl"><kbd>mval.pl</kbd></a></b></dt> +<dd>check for certain types of MathML errors</dd> +</dl> +<p></p> + +<p>Since some users will only be interested in the syntactic translator, additional +description of these materials is found below in +<a href="#usingdps">“Using the didactic production system”</a> (section 7.5) and in the +<a href="#release">Release Notes</a> (appendix B). +</p> +</div> + +<div class="subsection"> +<h4>7.3.  <a id="SU-7.3"></a><a id="requiredsoftware"></a>Other Required Software</h4> + +<p>To make use of the GELLMU syntactic translator a user must have or separately acquire +<a href="http://www.gnu.org/software/emacs/"><em>Emacs</em></a>.<sup><a id="revfnote43" href="#fnote43">43</a></sup> +(“Windows” users should look at the special +<a href="http://www.gnu.org/software/emacs/windows">FAQ</a>.) <em>Emacs</em> is +commonly found on GNU/Linux systems and on *ix systems. It may be +found on other systems when provided by system managers.<sup><a id="revfnote44" href="#fnote44">44</a></sup></p> + +<p>To make use of the didactic production system beyond the syntactic translator a user must have or acquire +the following items of free cross-platform software + +</p> +<ul> +<li><p> an ESIS +generating SGML parser such as found in the cross-platform package +<a href="http://www.jclark.com/sp/"><em>SP</em></a> by James Clark, +which has stood the test of years, or the newer variant +<a href="http://openjade.sourceforge.net/"><em>OpenSP</em></a>, which +is internationalized, from the <em>OpenJade</em> Team. +</p> +</li> +<li><p> <a href="http://www.cpan.org/"><em>Perl</em> at CPAN</a>. +</p> +</li> +<li><p> a complete <em>TeX</em> system, for which one may look to + <a href="http://www.tug.org">The <em>TeX</em> Users Group (TUG)</a> or + The Comprehensive <em>TeX</em> Archive Network + (<a href="http://www.ctan.org">CTAN</a>). +</p> +</li> +<li><p> <em>xmlwf</em> — a basic utility that is part of the release of + James Clark's <a href="http://expat.sourceforge.net/"><em>expat</em></a>. +</p> +</li> +</ul> +<p> +</p> +</div> + +<div class="subsection"> +<h4>7.4.  <a id="SU-7.4"></a>Using the syntactic translator</h4> + +<p>This explains how to use the syntactic translator, which is the Emacs Lisp program +contained in the file <a href="../gellmu.el"><kbd>gellmu.el</kbd></a>. +</p> + +<div class="subsubsection"> +<h5>7.4.1.  <a id="SU-7.4.1"></a>Operation in Batch Mode</h5> + +<p>For linux and the other *ix a script like <a href="../bin/linux/g2s"><kbd>bin/linux/g2s</kbd></a> will be +adequate if your working directory is the distribution directory<sup><a id="revfnote45" href="#fnote45">45</a></sup>. +</p> +<div class="display"><table class="gdisplay"><tbody><tr><td> +Usage: <kbd>g2s  </kbd><em>stem-name</em> +<kbd>  [ </kbd><em>function-call</em><kbd> ]</kbd> </td></tr></tbody></table></div> +<p> +For example, if “<kbd>foo.glm</kbd>” is the name of the source file, then +the first argument should be “<kbd>foo</kbd>”. The optional second +argument <em>function-call</em> is the name of the function in the Emacs +Lisp package “<kbd>gellmu.el</kbd>” that is to be used. The function +call defaults to “<kbd>gellmu-trans</kbd>”, which is the correct name for +<em>LaTeX</em>-like usage under the <a href="#ddt">didactic document type</a> (section 5). </p> + +<p>There are also parallel scripts “<kbd>g2h</kbd>” and “<kbd>g2x</kbd>”. </p> + +<p>“<kbd>g2s</kbd>” will byte compile “<kbd>gellmu.el</kbd>” if +“<kbd>gellmu.elc</kbd>” is not present. </p> + +<p>“<kbd>g2h</kbd>” runs the function <em>gellmu-html</em> for the case +where the GELLMU file has been written directly for HTML. +The file <a href="ghtml.glm"><kbd>ghtml.glm</kbd></a> and the derived file <a href="ghtml.html"><kbd>ghtml.html</kbd></a> +are examples. </p> + +<p>“<kbd>g2x</kbd>” runs the function <em>gellmu-xml</em> for the case +where the GELLMU file has been written directly for XML. </p> + +<p>The directory “<kbd>bin/win32</kbd>” contains parallel, though more +complicated, batch files for use in a “DOS” command line +under “Windows”. +</p> +</div> + +<div class="subsubsection"> +<h5>7.4.2.  <a id="SU-7.4.2"></a>Interactive Operation</h5> + +<p>Open GNU <em>Emacs</em> interactively on the GELLMU source file. When +finished editing the source, save it but keep <em>Emacs</em> open. Then do +</p> +<div class="display"><table class="gdisplay"><tbody><tr><td> +<kbd>M-x load-file gellmu.el</kbd></td></tr></tbody></table></div> +<p> +and +</p> +<div class="display"><table class="gdisplay"><tbody><tr><td> +<kbd>M-x gellmu-trans</kbd> . </td></tr></tbody></table></div> +<p></p> + +<p>(It is better to have byte-compiled “<kbd>gellmu.el</kbd>” and if the +byte-compiled version “<kbd>gellmu.elc</kbd>” is in your <em>Emacs</em> +<em>load-path</em>, then +</p> +<div class="display"><table class="gdisplay"><tbody><tr><td> +<kbd>M-x load-library gellmu</kbd></td></tr></tbody></table></div> +<p> +is faster.)</p> + +<p>The SGML output should come up in a second buffer. Save that buffer +to save the output. </p> + +<p>Make any corrections or changes in the GELLMU source buffer and re-run +</p> +<div class="display"><table class="gdisplay"><tbody><tr><td> +<kbd>M-x gellmu-trans</kbd> . </td></tr></tbody></table></div> +<p></p> + +<p>As with batch operation the functions <em>gellmu-html</em> and +<em>gellmu-xml</em>, may be handled parallel to <em>gellmu-trans</em>. </p> + +<p>There are a number of other functions besides these three for +obtaining syntactic translation from GELLMU source to SGML. Each of +these is, in fact, a front for calling <em>gellmu-trans</em> with +various combinations of variable settings. There are a great many +user configurable variables in the syntactic translator. Notable +among these for <a href="#regular"><em>regular</em> GELLMU</a> (section 4.1) are (1) +<em>gellmu-parb-nogo</em> and (2) <em>gellmu-autoclose-list</em>. +See the variable documentation text, available interactively when the +GELLMU library is loaded in <em>Emacs</em> with the key combination +qquostrC-h C-h v, for more information. For a list of the names of +all user configurable variables see the variable documentation for +<em>gellmu-public-vars</em>. </p> + +<p>For example, setting <em>gellmu-verblist</em> true causes a sequence of lines +beginning with the line “<kbd>\begin{verbatim}</kbd>” and ending +with the line “<kbd>\end{verbatim}</kbd>” to be considered +<em>verbatim</em> as in <em>LaTeX</em>, i.e., without requiring escaped forms +of special characters, and then to be set as a simple <em>verblist</em>, +which is in most circumstances superior to GELLMU's version of +pre-historic <em>verbatim</em>.<sup><a id="revfnote46" href="#fnote46">46</a></sup> +</p> +</div> + +<div class="subsubsection"> +<h5>7.4.3.  <a id="SU-7.4.3"></a><a id="interrupt"></a>Interrupting the Syntactic +Translator</h5> + +<p>Interruption of the GELLMU syntactic translator will be necessary in the event that the +combined use of <em>newcommand</em>, <em>macro</em>, <em>Macro</em>, +and <em>mathsym</em> (advanced mode only) leads to infinite recursive +loops. Users should avoid the use of <em>macro</em> and <em>Macro</em> +unless such use is absolutely necessary since these metacommands +present greater looping risks. </p> + +<p>Inasmuch as there are two ways to invoke the syntactic translator, there are two +different procedures for interrupting it should that be necessary. +</p> +<dl> +<dt><b> +Batch mode invocation</b></dt> +<dd>This is the case when GNU <em>Emacs</em> is launched +in batch processing mode to run the syntactic translator. To interrupt the syntactic translator in this +case one must interrupt the <em>Emacs</em> process. The author does not +know of any case when <em>Emacs</em> does not respond to standard interrupts. +For example, on <em>linux</em> systems pressing “Control-C” +when the process was launched from a shell provides a standard interrupt. +If the processed was launched in some other way, a normal “<kbd>kill</kbd>” +addressed to the process should have the same effect. +</dd><dt><b> +Interactive invocation</b></dt> +<dd>This is the case when the syntactic translator is launched +from within the GNU <em>Emacs</em> editing interface. Use the standard <em>Emacs</em> +function “quit”, accessed with the key “<kbd>C-g</kbd>” (Control-G) +to interrupt the syntactic translator. +</dd></dl> +<p> +</p> +</div> +</div> + +<div class="subsection"> +<h4>7.5.  <a id="SU-7.5"></a><a id="usingdps"></a>Using the didactic production system</h4> + +<div class="subsubsection"> +<h5>7.5.1.  <a id="SU-7.5.1"></a>Staged Design</h5> + +<p>The items in the didactic production system are components for use with staged processing. +The document type may be used with any SGML system. Of course, one +may not use a parser that is limited to XML with the SGML version of +the document type. Moreover, if one makes use of features in the +SGML version such as the positional argument and option elements, +then one might want to provide translation to the XML version of the +document type. </p> + +<p>No particular processing system is required for the XML version of +the document type. For example, one might profitably write an +<a href="http://www.w3.org/TR/xslt">XSLT</a> sheet for translation to some +other format and then submit the document and the XSLT sheet +to an XSLT engine such as <em>xt</em>, <em>xsltproc</em>, or +<em>saxon</em>. +</p> +</div> + +<div class="subsubsection"> +<h5>7.5.2.  <a id="SU-7.5.2"></a>Default Staging</h5> + +<p>The release includes <a href="../bin/linux/lmkg"><kbd>bin/linux/lmkg</kbd></a> and +<a href="../bin/linux/mmkg"><kbd>bin/linux/mmkg</kbd></a> as example driver scripts for running the +following sequence. (The <a href="../bin/win32"><kbd>bin/win32</kbd></a> directory contains +old driver scripts for the MS Windows command line that might someday +be worth updating.) The behavior of these driver scripts depends +on the way they are called though the specific of this are somewhat +different for <kbd>lmkg</kbd> than for <kbd>mmkg</kbd>. The older +<kbd>lmkg</kbd> scripts do not generate XHTML+MathML at this point they are +provided primarily for backward compatibility. </p> + +<p>The <kbd>mmkg</kbd> scripts by default make XHTML+MathML but not if called by +a name, e.g., via a symbolic link, without the substring “<kbd>mm</kbd>”. +If an <kbd>mmkg</kbd> script is called with a name ending in the string +“<kbd>froms</kbd>” or “<kbd>fromx</kbd>”, then it will take as starting +point, respectively, an SGML, i.e., “<kbd>.sgml</kbd>”, or author-level +XML, i.e., “<kbd>.xml</kbd>”, version of the document. Thus, for +example, <kbd>mmkgfromx</kbd> might be used to operate on a document +that is an author-level XML translation from a non-GELLMU source. </p> + +<p><b>Caution.</b> These scripts, like all shell scripts, should be +examined for file system locations, system environmental variables, +and other platform-specific and location-specific issues. The user +who introduces a script on a platform should understand the script. +A user who does not understand a script should not attempt to +introduce it on a local platform. </p> + +<p><a id="flow"></a> Flow in the didactic production system is portrayed in the following diagram: +</p> +<div class="display"><table class="gdisplay"><tbody><tr><td> +<img src="gcompst.png" alt="Image file: gcompst.png" /> +</td></tr></tbody></table></div> +<p></p> + +<p>These are the stages in the didactic production system pipeline: + +</p> +<ol class="decimal"> +<li><p> Prepare GELLMU source using a text editor. +</p> +</li> +<li><p> Process the source with the syntactic translator to obtain an SGML document under + the didactic document type. +</p> +</li> +<li><p> Use <em>nsgmls</em> to validate the SGML document and obtain an + ESIS for it as output. +</p> +</li> +<li><p> Submit the SGML ESIS as input<sup><a id="revfnote47" href="#fnote47">47</a></sup> + to the <em>Perl</em> + program <em>sgmlspl</em> with the script <a href="../xplaingart.pl"><kbd>xplaingart.pl</kbd></a> + as file argument, obtaining an author-level XML document. +</p> +</li> +<li><p> Use <em>nsgmls</em> to validate the author-level XML document + and then submit its ESIS as input to to <em>sgmlspl</em> + with the script <a href="../xmlgart.pl"><kbd>xmlgart.pl</kbd></a>, obtaining an elaborated + XML document. This document, which is accompanied by several + auxiliary files<sup><a id="revfnote48" href="#fnote48">48</a></sup>, + has things such as sectional unit numbers and cross references + fully resolved so that there will be consistency in these across + the various output formats. +</p> +</li> +<li><p> Use <em>nsgmls</em> to validate the elaborated XML document and + submit its ESIS as input multiply to <em>sgmlspl</em>: + </p> +<ol class="lower-alpha"> +<li><p> with the script <a href="../htmlgart.pl"><kbd>htmlgart.pl</kbd></a> to obtain a + classical HTML document that then will be validated if an + HTML validation program is identified in the driver script. + + </p> +</li> +<li><p> with the script <a href="../ltxgart.pl"><kbd>ltxgart.pl</kbd></a> + as file argument, obtaining a <em>LaTeX</em> document. The <em>LaTeX</em> + document is then built with <em>latex</em> to make a DVI + file and with <em>pdflatex</em> to make a PDF file. + + </p> +</li> +<li><p> for a pipeline using successive runs of <em>sgmlspl</em> with + 3 scripts, <a href="../mathcdata.pl"><kbd>mathcdata.pl</kbd></a>, <a href="../mathprep.pl"><kbd>mathprep.pl</kbd></a>, + and <a href="../htmlgart.pl"><kbd>htmlgart.pl</kbd></a> (called in a special way) to make + a XHTML+MathML file that is then checked for XML well-formedness + using <em>xmlwf</em>, checked for certain kinds of MathML + errors using <em>sgmlspl</em> with <a href="../mval.pl"><kbd>mval.pl</kbd></a>, and + validated if a suitable validation program is + identified in the driver script. + </p> +</li> +</ol> + +</li> +</ol> +<p> +</p> +</div> + +<div class="subsubsection"> +<h5>7.5.3.  <a id="SU-7.5.3"></a>Parsing with <em>nsgmls</em></h5> + +<p>The program <em>nsgmls</em> is part of the +<a href="http://www.jclark.com/sp/">SP</a> package, which includes +extensive documentation. Those familiar with it will want to ignore +these hints. </p> + +<p>Since for both the SGML and the XML versions of the didactic document type SP +requires non-default SGML declarations, it is recommended that the user +employ SGML catalogs, one for SGML and another for XML. +The file system location of a catalog is conveyed to <em>nsgmls</em> +as the value of its command line argument immediately following the +argument “-c”. </p> + +<p>Each catalog should contain an SGMLDECL directive that is the +file system location of an SGML declaration. Aside from that a catalog +may contain a number of three string lines of either of the following +forms +</p> +<dl> +<dd> PUBLIC  <em>formal-public-identifier</em>  <em>quoted-pathname</em></dd> +<dd> SYSTEM  <em>quoted-system-identifier</em>  <em>quoted pathname</em></dd> +</dl> +<p> +where the quoted pathname, which may be relative to the location of the +catalog, should for this context in each case be that of a +DTD file. </p> + +<p>It is recommended in each case that <em>nsgmls</em> be run with +arguments “-l” (for propagating line number references) and +“-oempty” (for flagging defined-empty elements). For +processing the XML version of the didactic document type one should additionally use +the argument “-wxml”. </p> + +<p>Additionally, a user may wish to make locally-specific arrangements +for the handling of character sets. +</p> +</div> + +<div class="subsubsection"> +<h5>7.5.4.  <a id="SU-7.5.4"></a>Processing with <em>sgmlspl</em></h5> + +<p>The program <em>sgmlspl</em> is part of David Megginson's +SGMLSPM package. Megginson's extensive documentation for it +may be found in the (December 1995) release found at +<a href="http://www.cpan.org/">CPAN</a>.<sup><a id="revfnote49" href="#fnote49">49</a></sup></p> + +<p>One uses <em>sgmlspl</em> by calling the Perl program <em>sgmlspl</em> +with an ESIS as input and a script as argument. Additional +arguments become arguments for the script. </p> + +<p>Although some operating systems provide a way for dealing with a Perl +program, which is stored in a text file, as an executable object, in +other cases one must explicitly call the Perl engine as a program with +an ESIS as input, the system name of <em>sgmlspl</em> as first +argument, and (the system name of) a script as second argument. In +both cases one will want to arrange, perhaps with an environmental +variable or perhaps with the “-I” argument to the Perl engine, +for the directory containing “<kbd>SGMLS.pm</kbd>” and its supporting +module “<kbd>SGMLS/Output.pm</kbd>” to be in its path array +<kbd>@INC</kbd>. +</p> +</div> + +<div class="subsubsection"> +<h5>7.5.5.  <a id="SU-7.5.5"></a><a id="environmentals"></a>Environmental Variables</h5> + +<p>There are a number of environmental variables that affect processing +in the didactic production system. The names all begin with the string “<kbd>GELLMU_</kbd>”. +Of course, the names are case-sensitive. </p> + +<p>Many of these variables are set in the distributed driver scripts. +When that is the case, the distributed driver scripts commonly check +for a previous setting (which may, therefore, be easily placed in a +fronting script that makes a setting and then just calls the +distributed driver). </p> + +<p>Setting environmentals can be difficult in a non-Unix-like +operating system environment. This is one reason why the author +generally recommends that Windows users install GELLMU under +<a href="http://www.cygwin.com/"><em>Cygwin</em></a>. + +</p> +<dl> +<dt><b><kbd>GELLMU_Dir</kbd></b></dt> +<dd> The top of the directory tree where GELLMU is installed. +</dd> +<dt><b><kbd>GELLMU_StyleDir</kbd></b></dt> +<dd> URI or directory location of CSS and XSLT style + sheets that is used by the didactic production system in writing links in XML, + HTML and XHTML+MathML files. + The value usually has a different meaning under the eye of a + web server than in a local file system. A relative URI or + path is usually best. A value like “<kbd>../webstyle</kbd>” + can often be made to work both ways. +</dd> +<dt><b><kbd>GELLMU_CSSName</kbd></b></dt> +<dd> Name, relative if given relative syntax, to the value of + <kbd>GELLMU_StyleDir</kbd>, of the CSS stylesheet written by the + didactic production system in HTML and XHTML+MathML files. +</dd> +<dt><b><kbd>GELLMU_XhtmlSuffix</kbd></b></dt> +<dd> Suffix given to XHTML or XHTML+MathML files written + by <kbd>htmlgart.pl</kbd>. +</dd> +<dt><b><kbd>GELLMU_NoUMSS</kbd></b></dt> +<dd> Value <math xmlns="http://www.w3.org/1998/Math/MathML" mode="inline" +><mn>0</mn></math +> or <math xmlns="http://www.w3.org/1998/Math/MathML" mode="inline" +><mn>1</mn></math +>: if <math xmlns="http://www.w3.org/1998/Math/MathML" mode="inline" +><mn>1</mn></math +>, signals to <kbd>htmlgart.pl</kbd> + that it should not link to W3C's + <a href="http://www.w3.org/Math/XSL/">UMSS</a> XSLT + stylesheets. +</dd> +<dt><b><kbd>GELLMU_UTF8</kbd></b></dt> +<dd> Value <math xmlns="http://www.w3.org/1998/Math/MathML" mode="inline" +><mn>0</mn></math +> or <math xmlns="http://www.w3.org/1998/Math/MathML" mode="inline" +><mn>1</mn></math +>: signals to <em>sgmlspl</em> scripts that + Perl's handling of the UTF-8 text encoding should be invoked. + The meaning is subtly different between Perl versions 5.6 + and 5.8. +</dd> +<dt><b><kbd>GELLMU_Encoding</kbd></b></dt> +<dd> String value for text encoding that is set by the + <kbd>xplaingart.pl</kbd> in writing author-level XML and by + <kbd>xmlgart.pl</kbd> in writing elaborated XML. (HTML, + XHTML, and XHTML+MathML are always written with the UTF-8 + encoding.) +</dd> +<dt><b><kbd>GELLMU_LaTeXUTF8</kbd></b></dt> +<dd> Value <math xmlns="http://www.w3.org/1998/Math/MathML" mode="inline" +><mn>0</mn></math +> or <math xmlns="http://www.w3.org/1998/Math/MathML" mode="inline" +><mn>1</mn></math +>: signals to <em>latex</em> and + <em>pdflatex</em> to expect the UTF-8 encoded text in + their input. +</dd> +<dt><b><kbd>GELLMU_LaTeXStyle</kbd></b></dt> +<dd> Pathname for <em>LaTeX</em> stylesheets that <em>latex</em> + and <em>pdflatex</em> should use when such stylesheets are + not properly positioned for <em>TeX</em> system KPSE-based + location. (It's better to use a local or personal + TDS tree.) +</dd> +<dt><b><kbd>GELLMU_PAPER</kbd></b></dt> +<dd> String value for the paper used in printing; becomes an + option for the <em>documentclass</em> command in the output + <em>LaTeX</em> file. +</dd> +<dt><b><kbd>GELLMU_Memoir</kbd></b></dt> +<dd> Value <math xmlns="http://www.w3.org/1998/Math/MathML" mode="inline" +><mn>0</mn></math +> or <math xmlns="http://www.w3.org/1998/Math/MathML" mode="inline" +><mn>1</mn></math +>: if <math xmlns="http://www.w3.org/1998/Math/MathML" mode="inline" +><mn>1</mn></math +>, use the <em>memoir</em>, rather + than <em>article</em>, documentclass in the output <em>LaTeX</em> file. +</dd> +<dt><b><kbd>GELLMU_DefaultEmptyEqncenter</kbd></b></dt> +<dd> <em>Experimental.</em> String value + consisting of a small bit of <em>LaTeX</em> wrapped as a Perl + string to use in tweeking the <em>LaTeX</em>-rendered appearance of + a GELLMU <em>eqnarray</em> (which is rendered in <em>LaTeX</em> using + either <em>align</em> or <em>aligned</em>, depending on + numbering arrangments) in the case of an empty middle cell + (<em>eqncenter</em>). The current default value used in + <kbd>ltxgart.pl</kbd> is the string “<kbd> \qquad </kbd>”. Be + mindful of how such a string can be entered as a literal + string in Perl or as part of an on-the-fly environmental + setting from a command line shell. +</dd> +<dt><b><kbd>GELLMU_XLink</kbd></b></dt> +<dd> Value <math xmlns="http://www.w3.org/1998/Math/MathML" mode="inline" +><mn>0</mn></math +> or <math xmlns="http://www.w3.org/1998/Math/MathML" mode="inline" +><mn>1</mn></math +>. How to handle links in MathML output + when writing XHTML+MathML. Such links, which are currently + illegal inside XHTML+MathML math zones, are confined to + <kbd>\text{...}</kbd> areas in GELLMU. If the value is <math xmlns="http://www.w3.org/1998/Math/MathML" mode="inline" +><mn>1</mn></math +>, use + XLink; otherwise, switch into the HTML namespace and + write an HTML anchor. (<em>Firefox</em> handles both, + while more of the other browsers seem to choke on the + namespace switch than choke on the necessarily cumbersome + use of XLink.) +</dd> +<dt><b><kbd>GELLMU_OriginLabel</kbd></b></dt> +<dd> Name for an automatic label key, chiefly of occasional + value for HTML and XHTML+MathML outputs, that, when this + variable is present in the environment, places a link target, + with id the value of this variable, at the top of the document. +</dd> +</dl> +<p> +</p> +</div> +</div> +</div> + +<div class="section"> +<h3>Appendix A.  <a id="SU-8"></a><a id="KEY-5"></a><a id="archive"></a>The GELLMU Archive</h3> + +<p>The GELLMU Archive is the web site +<a href="http://www.albany.edu/~hammond/gellmu/"><kbd>http://www.albany.edu/~hammond/gellmu/</kbd></a>. </p> + +<p>It is the source for late breaking information about GELLMU. +Among other things, it houses a largely uncommented +<a href="http://www.albany.edu/~hammond/gellmu/examples">archive of examples</a>. This is provided +in the belief that the study of examples is one of the quickest +ways to learn a markup language. </p> + +<p>Of course, this document, which is furnished with the release, +is also an example. </p> + +<p>Another item, also an example, that is housed in the archive +is <a href="http://www.albany.edu/~hammond/gellmu/examples/gfaq.html">The GELLMU FAQ</a>. +</p> +</div> + +<div class="section"> +<h3>Appendix B.  <a id="SU-9"></a><a id="KEY-6"></a><a id="release"></a>Release Notes</h3> + +<p>This version of the manual was prepared for release 0.8.5 in +July 2007. The <a href="#materials">GELLMU materials</a> (section 7.2) consist of: + +</p> +<ol class="decimal"> +<li><p> The manual, which is this document. +</p> +</li> +<li><p> The GELLMU syntactic translator, a <em>Emacs</em> Lisp program, which is the only +item of software required for those who simply wish to use GELLMU +markup for the conscious preparation of HTML documents or documents +under some other classical SGML or XML document type for which the +user is otherwise equipped. +</p> +</li> +<li><p> The GELLMU didactic production system, which consists of +an SGML document type called <em>article</em>, an XML document type +also called <em>article</em>, and three separate collections of <em>Perl</em> +functions for the well-known <em>Perl</em> SGML processing framework +<em>sgmlspl</em> by <a href="http://www.megginson.com/">David Megginson</a>. +A very slightly modified version of Megginson's <em>Perl</em> library +<em>SGMLSpm</em> that provides a method for detecting defined-empty +SGML elements, as flagged in an SGML parse stream in ESIS +format, is included as part of the didactic production system. +Since it is by size 60% of the software content of the +Megginson package on <a href="http://www.cpan.org/">CPAN</a>, the rest of the +package, licensed under the GNU +<a href="http://www.gnu.org/copyleft/gpl.html">General Public License</a> +is distributed with the didactic production system as well, though without its +documentation. The distribution includes 7 scripts for use with +<em>sgmlspl</em> in the didactic production system pipeline. For more +on this see <a href="#usingdps">“Using the didactic production system”</a> (section 7.5). +</p> +</li> +</ol> +<p> +</p> + +<div class="subsection"> +<h4>B.1.  <a id="SU-9.1"></a>Comments on the Syntactic Translator</h4> + +<p>The GELLMU syntactic translator is more mature than the other components. The following +comments pertain to it. + +</p> +<dl> +<dt><b>internationalization</b></dt> +<dd> + +<p>Internationalization has a considerable and evolving +level of support in <em>Emacs</em>. The concept is that an author resides in +a locale. When the author enters a character from a locale, it gives +rise in <em>Emacs</em> to a somewhat complicated multibyte entity that can have +“properties”. Particularly relevant variables in <em>Emacs</em> +are: <kbd>coding-system-for-write</kbd> and +<kbd>buffer-file-coding-system</kbd>. GELLMU provides the user +variable <kbd>gellmu-sgml-default-coding</kbd>, which should be properly +coordinated via driver script settings with one's SGML parser. +</p> +</dd> +<dt><b>inclusions</b></dt> +<dd> + +<p>It is not actually a limitation that a GELLMU source file cannot +be included in another. The primary reason is that one should +make use of the inclusion mechanism of SGML. For that one needs +to define the included pieces as entities in the direct internal +subset <sup><a id="revfnote50" href="#fnote50">50</a></sup> +of the source file and then reference each as an entity, e.g., +“<kbd>&sect2;</kbd>” at the appropriate location in the source +file where it is to be included. Because the inclusion happens +at the SGML level there are two points to observe: +</p> +<ol class="decimal"> +<li><p> Macro information is local to each source file. </p> +</li> +<li><p> The situation is optimal for the location of validation + errors provided that one's parser reports such errors by + filename and line number since the syntactic translator + provides line number alignment between source and generated + SGML. </p> +</li> +</ol> +<p></p> + +<p>A second reason is that source inclusion would disturb +line number alignment between source and SGML output. This +is important for the interpretation of SGML validation error +messages. Such validation is considered routine, and plays an +important role in detecting an author's mistakes. Some author errors +are diagnosed in the syntactic translator. </p> + +<p>A third reason, which at the same time might be considered also +a disadvantage, is that all of GELLMU's macro facilities are +local to each source file. This adds both robustness and flexibility +at the price of the inconvenience of physical inclusion of common +macro definitions. +</p> +</dd> +<dt><b>variable management</b></dt> +<dd> + +<p>This refers to the management of user variables in the syntactic +translator. These are <em>Elisp</em> variables. One who is familiar with +<em>Elisp</em> should be able to provide values in batch mode without +making changes in the <em>Elisp</em> source.<sup><a id="revfnote51" href="#fnote51">51</a></sup> +Setting values interactively in the Emacs editing interface can be +done easily using “<kbd>M-x set-variable</kbd>”. </p> + +<p>With a future release it is likely that additionally a user resource +file for custom variable settings without the need for writing <em>Elisp</em> +code will be provided. +</p> +</dd> +<dt><b>Bugs</b></dt> +<dd> + +<p>No serious existing problem is known in the GELLMU syntactic translator at the time of this +release. Of course, as stated in source code comments, there is no +warranty of any kind. Please report bugs to the author: +<a href="mailto:hammond@math.albany.edu"><kbd>hammond@math.albany.edu</kbd></a>. + +</p> +<ul> +<li><p> <b>Reserved element names.</b> +The GELLMU syntactic translator reserves for its own internal use all SGML or XML element +names in which the first numeric character in the range +“0–9” is the character “0”. +</p> +</li> +<li><p> <b>Limitation on braces in macros.</b> +Unbalanced braces are not permitted in either the name or the value +field of any form of macro metacommand. +</p> +</li> +<li><p> <b>First cell limitation.</b> +In the <em>LaTeX</em>-like emulation of an <em>array</em> or <em>tabular</em> +environment the first cell in each row must have something other than +whitespace. Of course, sometimes no content is wanted, and then +<kbd>\empty</kbd> (for nil markup, not to be confused with the mathematical +<kbd>\emptyset</kbd>) is one way to handle it, but this author usually uses +something that is mostly inconsequential like “<kbd>~</kbd>” or +“<kbd>\,</kbd>”. Another way to handle it is to invoke the names +of the SGML elements, i.e., <kbd>\firstcell{}</kbd> for <em>tabular</em> or +<kbd>\firstacell{}</kbd> for <em>array</em>. +</p> +</li> +<li><p> <b>Concept of advanced GELLMU immature.</b> +Inasmuch as didactic article is the only document type for +which the idea of advanced GELLMU has been implemented, the general +concept of advanced GELLMU is not fully developed in the GELLMU syntactic translator. +Basic GELLMU is characterized in the GELLMU syntactic translator by the evaluation of +the Boolean variable <em>gellmu-straight-sgml</em> to “true”. +This automatically make the Boolean variable +<em>gellmu-regular-sgml</em> true. +Full LaTeX-like support for the didactic production system is realized only by both +of these Booleans being false. Thus, advanced GELLMU will +need to evolve in the space in between, probably after the +introduction of further such Boolean variables, some public and +some private. This technique will make it possible for the +code to continue performing as now when the variable +<em>gellmu-straight-sgml</em>, the flag for basic GELLMU, is true +and also when both of these flags are false. +</p> +</li> +<li><p> <b>Reserved strings.</b> +The strings “<kbd><<</kbd>” and “<kbd>>></kbd>” have been reserved +as future notation for mathematical objects. Although it might seem +at first glance that this type of short hand has no place apart from +the fully <em>LaTeX</em>-like environment of the GELLMU syntactic translator in the context of the didactic production system, in +which they have not yet been used, it is actually not so clear that +one could not make sensible use of such notation in the context of +“XHTML plus MathML” under advanced GELLMU along with +other features such as blank lines for new paragraphs and many other +mathematical shortcuts. It awaits the further development of advanced +GELLMU, and reserving this notation is necessary to ensure backward +compatibility. +</p> +<p>Consequently, for example, entering “<kbd><<a>></kbd>” is +problematical, because only the first “<kbd><</kbd>” or “<kbd>></kbd>” +will be converted to something appropriate. In basic mode +“<kbd>&lt;</kbd>” and “<kbd>&gt;</kbd>” are one-step ways of +circumventing this when these entities are available, which is +guaranteed for any form of HTML as well as for any form of XML. In +the didactic production system one should use “<kbd>\ltc;</kbd>” and +“<kbd>\gtc;</kbd>”. For other cases the one-step circumvention is +to use entity references to the numeric character codes, e.g., in +ASCII “<kbd>&#3C;</kbd>” and “<kbd>&#3E;</kbd>”, and for +convenience these may be brought up as macros, perhaps +“<kbd>\lt</kbd>” and “<kbd>\gt</kbd>”. +</p> +</li> +</ul> +<p> +</p> +</dd> +</dl> +<p> +</p> +</div> + +<div class="subsection"> +<h4>B.2.  <a id="SU-9.2"></a>Comments on the Didactic Production System</h4> + +<p>The didactic production system is to be understood as a potential base for development. +As such it is not intended ever to offer everything that might +be imagined. The following comments pertain to it. +</p> + +<div class="subsubsection"> +<h5>B.2.1.  <a id="SU-9.2.1"></a>Internationalization</h5> + +<p>Internationalization has been a concern of the project. It is +possible, for example, to use the ISO-Latin-1 +character ‘é’ in the name of an element. The +didactic <em>article</em> document type offers, for example, an element +<em>étale</em>, which is a style, parallel to <em>bold</em>. +Use of the character ‘é’ as a raw word character +data with the didactic production system is less robust than the more careful +“<kbd>\acute{e}</kbd>”<sup><a id="revfnote52" href="#fnote52">52</a></sup> +construction, which is desirable for translation of <em>article</em> +to formats that do not support latin1. For that matter, the +exact extent of <em>LaTeX</em>'s support of latin1 is a bit tricky, and +the whole matter of internationalization is currently under +review in the <em>LaTeX</em> project.<sup><a id="revfnote53" href="#fnote53">53</a></sup> +</p> +</div> + +<div class="subsubsection"> +<h5>B.2.2.  <a id="SU-9.2.2"></a><a id="doctypes"></a>Document Type Definitions</h5> + +<p>Currently the project has one SGML document type definition +and two XML document type definitions. Files under the +various document types are suffixed as follows: +</p> +<div class="display"><table class="gdisplay"><tbody><tr><td> +<table><tbody> +<tr><td align="left">First stage SGML</td><td align="left"><kbd>.sgml</kbd></td></tr +><tr><td align="left">Author Level XML</td><td align="left"><kbd>.xml</kbd></td></tr +><tr><td align="left">Elaborated XML</td><td align="left"><kbd>.exml</kbd></td></tr +></tbody></table> +</td></tr></tbody></table></div> +<p></p> + +<p>Additionally, in the three steps of processing to generate an +XHTML+MathML file from an elaborated XML file there are two intermediate +XML files generated, the first with suffix “<kbd>.yml</kbd>”, which +lives under the document type definition for an elaborated XML +document, and the second with suffix “<kbd>.zml</kbd>”, an XML file +for which there is no extant formal document type +definition.<sup><a id="revfnote54" href="#fnote54">54</a></sup></p> + +<p>The author-level XML document type is formalized by the +DTD "axgellmu.dtd", while the elaborated XML document +type is formalized by a modification that is found in the DTD +"uxgellmu.dtd". (The latter was the only XML document type +used with the regular GELLMU production stream prior to +October, 2006.)</p> + +<p>The document type represented by "uxgellmu.dtd" is now called the +elaborated XML document type. </p> + +<p>The author-level XML document type is suitable as a translation +target from other markups. The elaborated XML document type +should not be used as a translation target other than from the +GELLMU author-level XML document type. </p> + +<p>All document type definitions are available under the UTF-8 +text encoding. The two older document type definitions will continue +to exist for a while under the Latin-1 (ISO-8859-1) text +encoding. The text encoding of a so-called DTD file (not +quite the same thing as a document type definition) is significant +in regard to the names of SGML/XML entities and +elements rather than in regard to document instances which might +be processed. The names of the DTD files are: +<a id="dtdfiles"></a> +</p> +<div class="display"><table class="gdisplay"><tbody><tr><td> +<table><tbody> +<tr class="bruled"><td class="rruled" align="left"> </td><td class="lruled" align="center">Latin-1</td><td align="center">UTF-8</td></tr +><tr class="truled"><td class="rruled" align="left">First stage SGML</td><td class="lruled" align="center"><kbd>gellmu.dtd</kbd></td><td align="center"><kbd>ugellmu.dtd</kbd></td></tr +><tr><td class="rruled" align="left">Author Level XML</td><td class="lruled" align="center"> </td><td align="center"><kbd>axgellmu.dtd</kbd></td></tr +><tr><td class="rruled" align="left">Elaborated XML</td><td class="lruled" align="center"><kbd>xgellmu.dtd</kbd></td><td align="center"><kbd>uxgellmu.dtd</kbd></td></tr +></tbody></table> +</td></tr></tbody></table></div> +<p> +</p> +</div> + +<div class="subsubsection"> +<h5>B.2.3.  <a id="SU-9.2.3"></a>Translation to XML</h5> + +<p>Presently the author-level XML files link to a CSS stylesheet that +provides primitive rendering. One could go further in this direction, +but the rendering of mathematics will be limited without more development +in that direction of CSS. +</p> +</div> + +<div class="subsubsection"> +<h5>B.2.4.  <a id="SU-9.2.4"></a>Translation to HTML</h5> +<dl> +<dt><b> +Math in classic HTML</b></dt> +<dd>The classic HTML output does not use graphic images for mathematical +zones in the manner of programs like <em>latex2html</em>. Instead it +uses pseudo-<em>TeX</em> notation for math. +There are a +number of reasons: +<ol class="decimal"> +<li><p> Well typeset mathematics is available in the modern form of + HTML that is more precisely called XHTML+MathML. </p> +</li> +<li><p> Graphical images completely block accessibility in the + sense of the World Wide Web Consortium's + <a href="http://www.w3.org/WAI/">Web Accesibility Initiative</a>. </p> +</li> +<li><p> The present classical HTML output files may be deciphered + in terminal window browsers. </p> +</li> +<li><p> The present classical HTML output files may be “dumped” to + plain text using a program such as <em>lynx</em> or <em>w3m</em> + for various sometimes useful purposes. </p> +</li> +</ol> + +</dd><dt><b> +Style.</b></dt> +<dd>HTML and XHTML+MathML made with the didactic production system now rely on CSS, even, for +some things, level 2 CSS. +</dd></dl> +</div> + +<div class="subsubsection"> +<h5>B.2.5.  <a id="SU-9.2.5"></a>Translation to <em>LaTeX</em></h5> + +<p>This translator writes <em>LaTeX</em><sub>2E</sub>. A number of packages, including +<em>graphicx</em>, <em>amsmath</em>, <em>amssymb</em>, <em>amsfonts</em>, +<em>bm</em>, <em>url</em> (not <em>hyperref</em> for the standard track +where the focus is on printed output), and <em>inputenc</em> for UTF-8 +(which may be needed even if the GELLMU source or, otherwise, the +author-level XML source is not UTF-8 encoded). +Apart from current font availability issues, the author would have +preferred to invoke the T1 font encoding. </p> + +<p>Even though GELLMU source uses the names <em>equation</em> and +<em>eqnarray</em>, in the <em>LaTeX</em> formatting <em>amsmath</em> constructions +are used. </p> + +<p>A small modification of this translator can be used to write +Adobe's Portable Document Format (PDF) with pages sized for screens +rather than for paper. +</p> +</div> + +<div class="subsubsection"> +<h5>B.2.6.  <a id="SU-9.2.6"></a>Future Plans</h5> + +<p>This is a very limited list. +</p> +<dl> +<dt><b>A literate document type definition.</b></dt> +<dd> + +<p>Capable of spawning not only the 5 DTD's but type definitions +under other mechanisms such as, for example, <em>RelaxNG</em>. +</p> +</dd> +<dt><b>Mathematical Semantics</b></dt> +<dd> + +<p>Provision for optional semantic tightening sufficient for authors +wishing to be able to export mathematical markup into computer algebra +systems. +</p> +</dd> +</dl> +<p> +</p> +</div> +</div> +</div> +<hr /> +<h3>Footnotes</h3> +<ol> +<li><a id="fnote1" href="#revfnote1">*</a> The syntactic translator does, however, have some facilities for + classifying the names in a list in regard to common syntactic + behavior. See, in particular, the <em>Elisp</em> variables + <em>gellmu-autoclose-list</em> and <em>gellmu-parb-hold</em>, both + of which are not significant in basic GELLMU.</li> +<li><a id="fnote2" href="#revfnote2">*</a> With several minor exceptions, one related to the direct writing of +SGML attributes (which cannot contain markup and which do not have +many parallels in <em>LaTeX</em>) and another related to the way of escaping +the character ‘<kbd>\</kbd>’, everything about basic mode also +applies to advanced mode.</li> +<li><a id="fnote3" href="#revfnote3">*</a> There is a way, with the setting of several +variables for the syntactic translator in advanced mode, to have blank lines begin +new paragraphs in basic input for HTML</li> +<li><a id="fnote4" href="#revfnote4">*</a> This means that it is a relatively slow form of processing, but +the author believes that it is a good match for the intuitive +expectations of most <em>LaTeX</em> users. </li> +<li><a id="fnote5" href="#revfnote5">*</a> In a future release an alternative metacommand +called <em>frontcommand</em> may be provided which could be used, for +example, if one wishes to have a macro name of some kind match the +name of an actual SGML element. </li> +<li><a id="fnote6" href="#revfnote6">*</a> In the prototype production system based on +the didactic <em>article</em> document type the output from each +stage is available for examination and, where necessary, intervention. +However, such use of intervention is intended only for temporary +expedient use while a GELLMU system is being designed or enhanced. +As with <em>LaTeX</em>, enhancement is an ongoing process. </li> +<li><a id="fnote7" href="#revfnote7">*</a> In handling GELLMU source markup one could provide +a more elaborate processor that can be configured to know for each +such command the list of names for its positional arguments and +options. It was decided that this goes somewhat beyond syntactic +handling but that the question of whether a list of arguments and options +corresponds to sole content might be regarded as a syntactic matter. </li> +<li><a id="fnote8" href="#revfnote8">*</a> Its use is optionally permitted in basic mode as well. </li> +<li><a id="fnote9" href="#revfnote9">*</a> Indeed, <em>LaTeX</em> usage allows markup in options, but (element level) +markup is not permitted in SGML attributes. Note, however, that +in the didactic document type the SGML content model for an option is more restrictive +than that for an argument. Also in the didactic document type some options, such as +that for <em>anch</em>, which is described later in this section, are +practically required. </li> +<li><a id="fnote10" href="#revfnote10">*</a> To say <em>seldom</em> is not to say <em>not</em>. Two important +instances in the didactic production system are the <em>series</em> attribute for the +<em>label</em> command, which stands in, to the extent possible, for the +notion of <em>counter</em> in <em>LaTeX</em>, and the <em>type</em> attribute for +the <em>series</em> command, which provides emulation of counter +conversion from, say, number values to letter values. </li> +<li><a id="fnote11" href="#revfnote11">*</a> In the XML version of <em>article</em> the option becomes the element +<em>anchref</em> and the anchored text becomes the element <em>anchv</em>. +One may use these names directly in GELLMU source, but option/argument +notation is more familiar and more succinct. </li> +<li><a id="fnote12" href="#revfnote12">*</a> There was no list +of this type in early pre-release versions of the syntactic translator. </li> +<li><a id="fnote13" href="#revfnote13">*</a> The <em>LaTeX</em> concept of document class has only a loose correspondence +with the SGML concept of document type. </li> +<li><a id="fnote14" href="#revfnote14">*</a> It is not inconceivable that at some future point conscious writing +for some XML document types using <em>LaTeX</em>-like markup might be +subsumed in the <em>LaTeX</em> project, but in saying this, the author is +neither predicting it nor assessing the merits of the idea. He has no +affiliation with the <em>LaTeX</em> project other than as a user. </li> +<li><a id="fnote15" href="#revfnote15">*</a> Strict discussion of an SGML document type would not allow use of the +word <em>handled</em>. In this instance a coordinated pair of document +types is being described, one SGML and the other an XML translation. +For most purposes the SGML document type is the richer of the two. +However, because of its use of a handful of generic elements (in its +reserved namespace consisting of names that contain ‘<kbd>0</kbd>’ (zero) +as first numeric character) for modeling certain convenience features +of <em>LaTeX</em>, it is possible for a correct translation of a valid SGML +article to yield an XML version that fails validation because the +content models of the generic elements are necessarily loose. </li> +<li><a id="fnote16" href="#revfnote16">*</a> The variable +<em>gellmu-xml-strict</em> is by default unset in advanced mode. </li> +<li><a id="fnote17" href="#revfnote17">*</a> The correct <em>LaTeX</em> markup is “<kbd>\LaTeX{} document</kbd>”. In the didactic production system the +name of <em>LaTeX</em> is “latex”, which is a defined-empty +element, that for the SGML version of <em>article</em> may be marked up +safely either as “<kbd>\latex;</kbd>” or as “<kbd>\latex{}</kbd>”. </li> +<li><a id="fnote18" href="#revfnote18">*</a> In math ‘<kbd>[</kbd>’ sometimes needs to be escaped to prevent confusion +between its markup use and its ordinary use in an instance such as +the markup for <math xmlns="http://www.w3.org/1998/Math/MathML" mode="inline" +><mi mathvariant="double-struck" mathcolor="#b00">Z</mi +><mo stretchy="true">[</mo><mi>t</mi><mo stretchy="true">]</mo></math +>. The syntactic translator would need to know +vocabulary — at least the argument/option pattern for +<em>mathbb</em> — in order to elude the syntactic ambiguity. </li> +<li><a id="fnote19" href="#revfnote19">*</a> “<kbd>\~</kbd>” is an example of a markup string that is defined in <em>LaTeX</em> (for +an accent) that is not defined in the didactic document type. A <em>LaTeX</em> user may recover +a prior markup habit of this type using <em>newcommand</em> possibly in +combination with <em>macro</em>. For more information see the +<a href="#accents">discussion of accents</a> (section 5.8). </li> +<li><a id="fnote20" href="#revfnote20">*</a> It is possible to merge the inline <em>math</em> and <em>tmath</em> zones +at any level of processing beyond the syntactic translator. These are indeed the same +in <em>LaTeX</em>, but the syntactic translator resists the temptation here to +go beyond syntax and merge them. With the didactic <em>article</em> +document type the formatting to <em>LaTeX</em> inserts the <em>LaTeX</em> markup +“<kbd>\,</kbd>” for a small horizontal space before and after +<em>math</em>, but not before and after <em>tmath</em>. </li> +<li><a id="fnote21" href="#revfnote21">*</a> The syntactic translator simply outputs the SGML defined-empty element +<em>brk0</em>, which belongs to its reserved name space. The dual use of +<em>brk0</em> involves some SGML chicanery that is resolved during translation +to the XML version of the <em>article</em> document type, +where <em>tabular</em> is converted to <em>table</em> and non-tabular use of +<em>brk0</em> is converted to <em>brk</em>. See also the handling of +<em>array</em>, which is different even though the source markup, as in +<em>LaTeX</em> is similar. </li> +<li><a id="fnote22" href="#revfnote22">*</a> Alternate forms “<kbd>\aos;</kbd>”, “<kbd>\aoq;</kbd>”, “<kbd>\aoe;</kbd>” of sentence ending +punctuation are provided that may be used following inline mathematical +markup at the end of a sentence. Similarly, “<kbd>\aoc;</kbd>” is an alternate +form for a comma. </li> +<li><a id="fnote23" href="#revfnote23">*</a> Or one +could use: +<dl class="verblist"> +<dd><kbd> +\Section{\sectiontitle{Some...}</kbd></dd> +<dd><kbd> +\para A para...  . . .}</kbd></dd> +</dl> + +instead of using the environment-like +<em>begin</em>/<em>end</em> construction. </li> +<li><a id="fnote24" href="#revfnote24">*</a> In fact, classical SGML document types are often +even more elaborate than this.</li> +<li><a id="fnote25" href="#revfnote25">*</a> Caveats: +<dl> +<dd> No document type definition under SGML is actually a complete + language definition. A document type definition describes a document + markup structurally; in particular, it does not provide definition + for legal “field” values. </dd> +<dd> While the GELLMU syntactic translator is now considered as +“alpha” software, the document type and the accompanying +translators, which constitute the didactic production system are +developmental. These materials have some support for obsolete +practice and also contain sketch sections that are not fully robust. </dd> +</dl> +</li> +<li><a id="fnote26" href="#revfnote26">*</a> It is recommended that the characters in label key strings be +restricted to lower case ASCII letters, the digits 0–9, and +possibly the character ‘<kbd>-</kbd>’ or the character ‘<kbd>.</kbd>’ for +maximal inter-operability with current and future formattings. +For example, the ‘<kbd>_</kbd>’ is problematical in this context. </li> +<li><a id="fnote27" href="#revfnote27">*</a> Although one <em>could</em> provide SGML modeling for <em>LaTeX</em>'s +counters, it would not be very much along the lines of main track +SGML or XML document types. </li> +<li><a id="fnote28" href="#revfnote28">*</a> The value strings may contain simple markup such as, for example, +“<kbd>\tld;</kbd>” to provide robust multiple output processing of +‘<kbd>~</kbd>’ whereas an attribute option may not contain markup. </li> +<li><a id="fnote29" href="#revfnote29">*</a> A <em>klabel</em> is a +“visible key” label.</li> +<li><a id="fnote30" href="#revfnote30">*</a> It may be left empty, but it must be present. + </li> +<li><a id="fnote31" href="#revfnote31">*</a> The presence of <em>sopt</em> + does not cause a table of contents to be produced automatically. + For that one uses “<kbd>\tableofcontents</kbd>”. Moreover, + the presence of <em>sopt</em> should have no effect upon a manually + constructed “<kbd>\TableOfContents</kbd>”.</li> +<li><a id="fnote32" href="#revfnote32">*</a> The didactic production system offers a way to furnish a formally empty string, which is an +empty element called <em>empty</em> in the document type for use in +places such as the the table of contents option of a sectional unit, +where it is not otherwise possible to distinguish after parsing whether +deliberately empty content was specified by the author. +That is, the markup “<kbd>\sopt{}</kbd>” furnishes an empty +string which, in turn, signals “no <em>sopt</em>”, while +“<kbd>\sopt{\empty;}</kbd>” indicates that empty content +was specified for <em>sopt</em>. </li> +<li><a id="fnote33" href="#revfnote33">*</a> When editing for HTML one may, of course use HTML's <em>pre</em>, +which stands for “pre-formatted text”</li> +<li><a id="fnote34" href="#revfnote34">*</a> With a sufficiently long list of output format candidates each of the +33 non-alphanumeric printable ASCII characters is unsafe. +However, one might use an external character-to-string conversion +program to prepare a large amount of verbatim material for inclusion +inside the simplistic <em>verbatim</em> command in GELLMU source. </li> +<li><a id="fnote35" href="#revfnote35">*</a> To export this procedure for general <em>advanced</em> mode usage, all +of the names used need to be made user-configurable. </li> +<li><a id="fnote36" href="#revfnote36">*</a> Familiar short forms +may be introduced by a user using the <em>macro</em> facility.</li> +<li><a id="fnote37" href="#revfnote37">*</a> For the +third method one's GELLMU driver script must provide appropriately +for the text encoding of the source file.</li> +<li><a id="fnote38" href="#revfnote38">*</a> This meaning of <em>scale</em> differs +from the meaning of <em>scale</em> with <em>includegraphics</em> under +<em>LaTeX</em>'s <em>graphicx</em> package. New controls of this type +may be introduced in a future version.</li> +<li><a id="fnote39" href="#revfnote39">*</a> Note that the use of <em>lbalbr</em> in this instance is insufficiently +semantic for translation to content MathML while it is meaningful +for translation to presentation MathML. Adequate enhancement might +be had by providing <kbd>mml="cases"</kbd> (using a name from <em>amsmath</em>) +as an attribute for <em>lbalbr</em> with this example. </li> +<li><a id="fnote40" href="#revfnote40">*</a> There is also a default counter that is used when no label series name +is present. That counter simply is the position of the underlying +<em>assertion</em> in the list of all assertions. </li> +<li><a id="fnote41" href="#revfnote41">*</a> However, a declared math symbol may be invoked in +a <em>newcommand</em> that takes arguments. </li> +<li><a id="fnote42" href="#revfnote42">*</a> Such unattached braces in GELLMU markup lead to an <em>lg0</em> tag in +the output of the syntactic translator that is translated to an +<em>lgg</em> tag in the XML version of the didactic document type. </li> +<li><a id="fnote43" href="#revfnote43">*</a> Version 20 or later should be adequate. Although the author began +this project using version 19, he is no longer able to run tests +with that version.</li> +<li><a id="fnote44" href="#revfnote44">*</a> It is an embarrassment of the business world in the years since 1985 +that many business computing installations do not provide general +purpose cross-platform programming systems despite the widespread +availability of excellent free robust systems such as <em>Emacs</em> (for +Lisp), <em>gcc</em> (for C), and <em>Perl</em>. This new phenomenon +apparently arises not so much from lack of organizational interest but +from the fact that the responsibility for maintenance cannot be passed +beyond the local system manager to a vendor. </li> +<li><a id="fnote45" href="#revfnote45">*</a> None of the enclosed scripts either for linux or for win32 should be used +without prior examination and verification for suitability. </li> +<li><a id="fnote46" href="#revfnote46">*</a> The main reasons that this version is not the default with a call to +<em>gellmu-trans</em> are: +<ol class="decimal"> +<li><p> It breaks the paradigm under which a GELLMU command name is the +name of an SGML element. </p> +</li> +<li><p> It breaks backward compatibility with earlier versions of the +syntactic translator, i.e., breaks older documents. </p> +</li> +<li><p> It is felt that the user invoking <em>verblist</em> this way +should be aware of what is being done. </p> +</li> +</ol> + +Note that direct invocation of <em>verblist</em> requires escaping +special characters. Thus, using the function call +<em>gellmu-verblist</em> converts the name <em>verbatim</em> from a +command name to a meta-command name.</li> +<li><a id="fnote47" href="#revfnote47">*</a> Specifically, this mention of “input” refers to + what is called “standard input” in a command line + situation. There may be a challenge here on platforms that do + not provide a command line. </li> +<li><a id="fnote48" href="#revfnote48">*</a> Formally, two of these auxiliary files are considered part of the + elaborated XML document. </li> +<li><a id="fnote49" href="#revfnote49">*</a> At the time of this release +there was discussion in the UseNet newsgroup +<a href="news:comp.text.sgml"><kbd>news:comp.text.sgml</kbd></a> about a proposed revision of +SGMLSPM by another party. The code for “<kbd>SGMLS.pm</kbd>” +included in this GELLMU release contains a very small modification +of Megginson's 1995 release. </li> +<li><a id="fnote50" href="#revfnote50">*</a> The direct internal subset is the content of the optional argument of +the <em>documenttype</em> metacommand that follows its required argument. +It should be noted in the didactic production system that the direct internal +subset cannot be propagated to the XML form of <em>article</em> +because it is digested by any standard SGML parser and, hence, +by any translation based on a standard parsing. Thus, +any pieces are merged in the XML form of an article although +the translator <kbd>xmlgart</kbd> might be modified to +construct an internal declaration subset there and provide +partitioning of the XML version among filesystem pieces based +on document structure. </li> +<li><a id="fnote51" href="#revfnote51">*</a> Please observe the rules of the <em>LaTeX</em> project regarding filenames +as well as the license rules of the GNU General Public License +if you wish to distribute a modified version of the <em>Elisp</em> +source. Alternatively, the author is always interested in learning +of suggestions for change.</li> +<li><a id="fnote52" href="#revfnote52">*</a> The corresponding usage in <em>LaTeX</em> would be “<kbd>\'e</kbd>”; +this could be brought into GELLMU source using <em>\macro</em>, +but it must be resolved to a name in the output of the GELLMU syntactic translator where +everything that is markup needs a name. Rather than using a +general container <em>acute</em>, the document type could have provided +a name for the specific character. </li> +<li><a id="fnote53" href="#revfnote53">*</a> Alternatively <em>LaTeX</em> source can be submitted to the program +<em>lambda</em> which is the <em>LaTeX</em> format for the program +<em>omega</em> that is now under development as a substitute for +Knuth's <em>TeX</em>, the program, with internationalization as a stated +goal.</li> +<li><a id="fnote54" href="#revfnote54">*</a> There is no formal document type definition +for a “<kbd>.zml</kbd>” file because such a file is endowed via XML +attributes with information about tree structure for +mathematical zones.</li> +</ol> +</body> +</html> + |