diff options
Diffstat (limited to 'support/gellmu/doc')
| -rw-r--r-- | support/gellmu/doc/gcompst.png | bin | 0 -> 21698 bytes | |||
| -rw-r--r-- | support/gellmu/doc/glman.html | 3583 | ||||
| -rw-r--r-- | support/gellmu/doc/glman.pdf | bin | 0 -> 386650 bytes | |||
| -rw-r--r-- | support/gellmu/doc/glman.xhtml | 3648 | ||||
| -rw-r--r-- | support/gellmu/doc/glmy.png | bin | 0 -> 4573 bytes | |||
| -rw-r--r-- | support/gellmu/doc/userdoc.html | 1216 | ||||
| -rw-r--r-- | support/gellmu/doc/userdoc.pdf | bin | 0 -> 210475 bytes | |||
| -rw-r--r-- | support/gellmu/doc/userdoc.xhtml | 1402 |
8 files changed, 9849 insertions, 0 deletions
diff --git a/support/gellmu/doc/gcompst.png b/support/gellmu/doc/gcompst.png Binary files differnew file mode 100644 index 0000000000..c9036d4962 --- /dev/null +++ b/support/gellmu/doc/gcompst.png diff --git a/support/gellmu/doc/glman.html b/support/gellmu/doc/glman.html new file mode 100644 index 0000000000..d8efbce24c --- /dev/null +++ b/support/gellmu/doc/glman.html @@ -0,0 +1,3583 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> +<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 bgcolor="#ffffff" text="#000000" +link="#0000ee" vlink="#0000bb" alink="#ff0000"> +<h1 align="center">The GELLMU Manual</h1> +<h4 align="center">Version 0.8.4 Release, July 2007</h4> +<h2 align="center">William F. Hammond</h2> +<h4 align="center"> +Dept. of Mathematics & Statistics<br +> University at Albany<br +> Albany, New York 12222 (USA)</h4> +<p align="center">Email: <kbd>hammond@math.albany.edu</kbd></p> +<h4 align="center">Revision of July 5, 2007</h4> +<h5 align="center">Copyright © 2001–2007 William F. Hammond</h5> +<h3 align="center">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 name="SU-1" id="SU-1"></a><a name="intro" 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 type="1"> +<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 type="a"> +<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 name="SU-2" id="SU-2"></a><a name="basic" 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 type="1"> +<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 name="revfnote1" 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 name="revfnote2" 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> +<center><table class="gdisplay"><tbody><tr><td> +<kbd>\a[href="http://www.w3.org/"]{The World Wide Web Consortium}</kbd></td></tr></tbody></table></center> +<p> +to form the HTML anchor: +</p> +<center><table class="gdisplay"><tbody><tr><td> +<kbd><a href="http://www.w3.org/">The World Wide Web Consortium</a></kbd> +. </td></tr></tbody></table></center> +<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 name="revfnote3" 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 name="SU-3" id="SU-3"></a><a name="meta" 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 name="SU-3.1" id="SU-3.1"></a><a name="doctype" id="doctype"></a>\documenttype</h4> + +<p>A document prepared in GELLMU source usually begins with a +<em>documenttype</em> command. For example, +</p> +<center><table class="gdisplay"><tbody><tr><td> +<kbd>\documenttype{html}</kbd></td></tr></tbody></table></center> +<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> +<center><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></center> +<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> +<center><table class="gdisplay"><tbody><tr><td> +<kbd>\documenttype[xhtml-1.0s]{html}</kbd></td></tr></tbody></table></center> +<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 compact="compact"> +<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" compact="compact"> +<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 name="SU-3.2" id="SU-3.2"></a><a name="newcommand" 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 name="revfnote4" id="revfnote4" href="#fnote4">4</a></sup></p> + +<p>The general construction of a newcommand definition is +</p> +<center><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></center> +<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" compact="compact"> +<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> +<center><table class="gdisplay"><tbody><tr><td> +<kbd>\href{http://www.myweb.mydomain/me.html}{my web page}</kbd></td></tr></tbody></table></center> +<p> gives +rise to the HTML markup +</p> +<center><table class="gdisplay"><tbody><tr><td> +<kbd><a href="http://www.myweb.mydomain/me.html">my web page</a></kbd></td></tr></tbody></table></center> +<p> +while the invocation +“<kbd>\href{Web Central}</kbd>” gives rise to +</p> +<center><table class="gdisplay"><tbody><tr><td> +<kbd><a href="http://www.w3.org/">Web Central</a></kbd> . </td></tr></tbody></table></center> +<p></p> + +<p><b>Rules.</b> +</p> +<ol type="1"> +<li><p> The name of a newcommand may not be referenced in its +value string.<sup><a name="revfnote5" 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 name="SU-3.3" id="SU-3.3"></a><a name="beginend" 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> +<center><table class="gdisplay"><tbody><tr><td> +<kbd>\begin{document} . . . \end{document}</kbd></td></tr></tbody></table></center> +<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 name="SU-3.4" id="SU-3.4"></a><a name="macmac" 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 type="1"> +<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 name="SU-3.5" id="SU-3.5"></a><a name="fronting" 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" compact="compact"> +<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> +<center><table class="gdisplay"><tbody><tr><td> +<kbd>\p[class="custom"]{...}</kbd> . </td></tr></tbody></table></center> +<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 name="SU-4" id="SU-4"></a><a name="advanced" 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 name="SU-4.1" id="SU-4.1"></a><a name="illustrations" 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> +<center><table class="gdisplay"><tbody><tr><td> +<kbd>\begin{equation} . . . \end{equation}</kbd></td></tr></tbody></table></center> +<p> +for a single equation, and markup such as +</p> +<center><table class="gdisplay"><tbody><tr><td> +<kbd>\begin{eqnarray} . . . \end{eqnarray}</kbd></td></tr></tbody></table></center> +<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 name="regular" 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 name="SU-4.2" id="SU-4.2"></a><a name="argopt" 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 name="revfnote6" 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 name="revfnote7" 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 type="1"> +<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 name="revfnote8" 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 name="revfnote9" id="revfnote9" href="#fnote9">9</a></sup>, +attribute options are seldom used<sup><a name="revfnote10" 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" compact="compact"> +<dd><kbd> +\begin{equation}[:nonum="true"]</kbd></dd> +<dd><kbd> +e = mc^2</kbd></dd> +<dd><kbd> +\end{equation}</kbd></dd> +</dl> + +to produce: +<center><table cellspacing="0" cellpadding="0"><tr><td> +e  =  mc^{2} +</td></tr></table></center> + +</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 name="revfnote11" id="revfnote11" href="#fnote11">11</a></sup> +Because the syntactic translator does not consider the document type definition, +if one enters the markup +</p> +<center><table class="gdisplay"><tbody><tr><td> +<kbd>\anch[href="http://www.w3.org/"]{W3C} HQ</kbd> ,</td></tr></tbody></table></center> +<p> +unless the name <em>anch</em> is in the list<sup><a name="revfnote12" 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 name="SU-4.3" id="SU-4.3"></a><a name="xmllimit" 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 name="SU-5" id="SU-5"></a><a name="ddt" 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 name="revfnote13" 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 name="revfnote14" 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 name="revfnote15" 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 name="SU-5.1" id="SU-5.1"></a><a name="caveat" 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 name="SU-5.2" id="SU-5.2"></a><a name="mufund" id="mufund"></a>Markup Fundamentals</h4> + +<p>There are several kinds of commands: +</p> + +<div class="subsubsection"> +<h5>5.2.1.  <a name="SU-5.2.1" id="SU-5.2.1"></a><a name="explicitnames" 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 name="revfnote16" 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> +<center><table class="gdisplay"><tbody><tr><td> +<kbd>\LaTeX document</kbd></td></tr></tbody></table></center> +<p> +will be collapsed into the single word form “<em>LaTeX</em>document” +when typeset.<sup><a name="revfnote17" id="revfnote17" href="#fnote17">17</a></sup> +</p> +</div> + +<div class="subsubsection"> +<h5>5.2.2.  <a name="SU-5.2.2" id="SU-5.2.2"></a><a name="single" 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 type="1"> +<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 name="revfnote18" 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 type="1"> +<li><p> “<kbd>~</kbd>”: <b>Non-breaking interword space.</b><br +> Escape: <kbd>\tld;</kbd>.<sup><a name="revfnote19" 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 name="revfnote20" id="revfnote20" href="#fnote20">20</a></sup> + </p> +</li> +</ol> +<p> +</p> +</div> + +<div class="subsubsection"> +<h5>5.2.3.  <a name="SU-5.2.3" id="SU-5.2.3"></a><a name="certainstrings" 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 type="1"> +<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 name="revfnote21" 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 name="revfnote22" id="revfnote22" href="#fnote22">22</a></sup> + + </p> +</li> +</ol> +<p> +</p> +</div> +</div> + +<div class="subsection"> +<h4>5.3.  <a name="SU-5.3" id="SU-5.3"></a><a name="large" 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> +<center><table class="gdisplay"><tbody><tr><td> +<kbd>\begin{document} . . . \end{document}</kbd></td></tr></tbody></table></center> +<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" compact="compact"> +<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" compact="compact"> +<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 name="SU-5.4" id="SU-5.4"></a><a name="sectioning" id="sectioning"></a>Sectioning</h4> + +<p>In classical <em>LaTeX</em> one writes simply +</p> +<center><table class="gdisplay"><tbody><tr><td> +<kbd>\section{Some title for a section}</kbd></td></tr></tbody></table></center> +<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" compact="compact"> +<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 name="revfnote23" id="revfnote23" href="#fnote23">23</a></sup> +</p> +<dl class="verblist" compact="compact"> +<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 name="revfnote24" 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 name="revfnote25" id="revfnote25" href="#fnote25">25</a></sup> +under the didactic document type. +</p> +</div> + +<div class="subsection"> +<h4>5.5.  <a name="SU-5.5" id="SU-5.5"></a><a name="labelref" 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 name="SU-5.5.1" id="SU-5.5.1"></a><a name="seq" id="seq"></a>Labels and Sequencing</h5> + +<p>The basic usage for <em>label</em> is +</p> +<center><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></center> +<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 name="revfnote26" 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 name="revfnote27" 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 type="1"> +<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 name="SU-5.5.2" id="SU-5.5.2"></a>Anchors</h5> + +<p>The basic usage for <em>anch</em> is +</p> +<center><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></center> +<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 name="revfnote28" 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 name="revfnote29" 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 name="SU-5.5.3" id="SU-5.5.3"></a><a name="counters" 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" compact="compact"> +<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 name="KEY-1" id="KEY-1"></a> + + +Hilbert's three most important contributions to algebraic geometry +are <a name="KEY-2" id="KEY-2"></a>(i) the basis theorem, <a name="KEY-3" id="KEY-3"></a>(ii) the nullstellensatz, and <a name="KEY-4" 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 name="SU-5.6" id="SU-5.6"></a><a name="secusage" id="secusage"></a><a name="last" 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 name="SU-5.6.1" id="SU-5.6.1"></a><a name="seccontent" id="seccontent"></a>The Content Model</h5> + +<p>The content model for sectional units is: +</p> +<center><table class="gdisplay"><tbody><tr><td> +<kbd>((sopt)?,(sprefix)?,(sunit)?,(shead),(%UnitContent)*)</kbd></td></tr></tbody></table></center> +<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 name="revfnote30" 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 name="revfnote31" 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 name="SU-5.6.2" id="SU-5.6.2"></a><a name="ltxsecusage" 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 name="revfnote32" id="revfnote32" href="#fnote32">32</a></sup> +for <em>sopt</em>. +</p> +</div> +</div> + +<div class="subsection"> +<h4>5.7.  <a name="SU-5.7" id="SU-5.7"></a><a name="verb" 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 name="revfnote33" 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 name="revfnote34" 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 name="revfnote35" 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> +<center><table class="gdisplay"><tbody><tr><td> +<kbd>\</kbd><em>name</em><kbd>|</kbd><em>literal-text</em><kbd>|</kbd></td></tr></tbody></table></center> +<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 name="SU-5.8" id="SU-5.8"></a><a name="accents" 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 name="revfnote36" 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 type="1"> +<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 name="revfnote37" 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 name="SU-5.9" id="SU-5.9"></a><a name="tabular" 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 {1}/{n+1} where n 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" compact="compact"> +<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 name="SU-5.10" id="SU-5.10"></a><a name="graphics" 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" compact="compact"> +<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" compact="compact"> +<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> +<center><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></center> +<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 name="revfnote38" 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 1.1 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 name="SU-6" id="SU-6"></a><a name="math" id="math"></a>Mathematics in <em>article</em></h3> + +<div class="subsection"> +<h4>6.1.  <a name="SU-6.1" id="SU-6.1"></a><a name="genmath" 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, + +<center><table class="gdisplay"><tbody><tr><td> +<kbd>\[ \sum_{0}^{\infty} \frac{x^k}{k!} \sum: \]</kbd></td></tr></tbody></table></center> + +produces +<center><table cellspacing="0" cellpadding="0"><tr><td> + SUM_{0}^{INFTY}[{x^{k}}/{k!} ]    . +</td></tr></table></center> +</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" compact="compact"> +<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 + + +Gal(\={<b>Q</b>}/<b>Q</b>). + +<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" compact="compact"> +<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 +</p> +<center><table cellspacing="0" cellpadding="0"><tr><td> +  |x|   =  </td><td><table cellspacing="0" cellpadding="0"><tr><td valign="middle" align="right">{</td><td valign="middle" align="left"></td><td><table> +<tr><td align="right">x </td> +<td align="left"> if  x  >=  0</td> +</tr><tr><td align="right">-x</td> +<td align="left"> if  x < 0</td> +</tr></table></td><td></td></tr></table> +</td><td>  +</td></tr></table></center> +<p> +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 name="revfnote39" 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 name="SU-6.2" id="SU-6.2"></a><a name="assert" id="assert"></a>Assertions: Near Emulation of + <em>LaTeX</em>'s Theorem-Like Environments</h4> + +<div class="subsubsection"> +<h5>6.2.1.  <a name="SU-6.2.1" 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" compact="compact"> +<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 name="AssertLabel-1" 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 +1 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 name="revfnote40" id="revfnote40" href="#fnote40">40</a></sup> +<a name="AssertLabel-2" 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 name="SU-6.2.2" id="SU-6.2.2"></a><a name="assertion" id="assertion"></a>Usage for <em>assertion</em></h5> + +<p>The general usage of <em>assertion</em> is the following: +</p> +<dl compact="compact"> +<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 compact="compact"> +<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" compact="compact"> +<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 name="AssertLabel-3" id="AssertLabel-3"></a></p> +<dl class="assertion"> +<dd> +<b>Theorem 6.2.2.1.</b> +  If [ n_{1}, n_{2}, … ] 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 name="SU-6.3" id="SU-6.3"></a><a name="eqn" id="eqn"></a>Equations and Equation Arrays</h4> + +<p>The general usage for <em>equation</em> is the following: +</p> +<dl compact="compact"> +<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> +<center><table class="gdisplay"><tbody><tr><td> +<kbd>\begin{equation}[:nonum="true"] . . . \end{equation}</kbd> .</td></tr></tbody></table></center> +<p></p> + +<p>General usage for an equation array (name <em>eqnarray</em>) is: +</p> +<dl compact="compact"> +<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 name="SU-6.4" id="SU-6.4"></a><a name="mathsym" 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> +<center><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></center> +<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 name="revfnote41" 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 name="revfnote42" 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 name="SU-7" id="SU-7"></a><a name="dps" 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 name="SU-7.1" 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 name="SU-7.2" id="SU-7.2"></a><a name="materials" 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 name="SU-7.3" id="SU-7.3"></a><a name="requiredsoftware" 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 name="revfnote43" 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 name="revfnote44" 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 name="SU-7.4" 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 name="SU-7.4.1" 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 name="revfnote45" id="revfnote45" href="#fnote45">45</a></sup>. +</p> +<center><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></center> +<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 name="SU-7.4.2" 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> +<center><table class="gdisplay"><tbody><tr><td> +<kbd>M-x load-file gellmu.el</kbd></td></tr></tbody></table></center> +<p> +and +</p> +<center><table class="gdisplay"><tbody><tr><td> +<kbd>M-x gellmu-trans</kbd> . </td></tr></tbody></table></center> +<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> +<center><table class="gdisplay"><tbody><tr><td> +<kbd>M-x load-library gellmu</kbd></td></tr></tbody></table></center> +<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> +<center><table class="gdisplay"><tbody><tr><td> +<kbd>M-x gellmu-trans</kbd> . </td></tr></tbody></table></center> +<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 name="revfnote46" id="revfnote46" href="#fnote46">46</a></sup> +</p> +</div> + +<div class="subsubsection"> +<h5>7.4.3.  <a name="SU-7.4.3" id="SU-7.4.3"></a><a name="interrupt" 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 name="SU-7.5" id="SU-7.5"></a><a name="usingdps" id="usingdps"></a>Using the didactic production system</h4> + +<div class="subsubsection"> +<h5>7.5.1.  <a name="SU-7.5.1" 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 name="SU-7.5.2" 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 name="flow" id="flow"></a> Flow in the didactic production system is portrayed in the following diagram: +</p> +<center><table class="gdisplay"><tbody><tr><td> +<img src="gcompst.png" alt="Image file: gcompst.png"> +</td></tr></tbody></table></center> +<p></p> + +<p>These are the stages in the didactic production system pipeline: + +</p> +<ol type="1"> +<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 name="revfnote47" 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 name="revfnote48" 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 type="a"> +<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 name="SU-7.5.3" 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 compact="compact"> +<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 name="SU-7.5.4" 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 name="revfnote49" 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 name="SU-7.5.5" id="SU-7.5.5"></a><a name="environmentals" 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 0 or 1: if 1, 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 0 or 1: 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 0 or 1: 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 0 or 1: if 1, 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 0 or 1. 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 1, 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 name="SU-8" id="SU-8"></a><a name="KEY-5" id="KEY-5"></a><a name="archive" 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 name="SU-9" id="SU-9"></a><a name="KEY-6" id="KEY-6"></a><a name="release" 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 type="1"> +<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 name="SU-9.1" 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 name="revfnote50" 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 type="1"> +<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 name="revfnote51" 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 name="SU-9.2" 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 name="SU-9.2.1" 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 name="revfnote52" 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 name="revfnote53" id="revfnote53" href="#fnote53">53</a></sup> +</p> +</div> + +<div class="subsubsection"> +<h5>B.2.2.  <a name="SU-9.2.2" id="SU-9.2.2"></a><a name="doctypes" 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> +<center><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></center> +<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 name="revfnote54" 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 name="dtdfiles" id="dtdfiles"></a> +</p> +<center><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></center> +<p> +</p> +</div> + +<div class="subsubsection"> +<h5>B.2.3.  <a name="SU-9.2.3" 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 name="SU-9.2.4" 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 type="1"> +<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 name="SU-9.2.5" 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 name="SU-9.2.6" 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 name="fnote1" 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 name="fnote2" 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 name="fnote3" 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 name="fnote4" 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 name="fnote5" 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 name="fnote6" 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 name="fnote7" 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 name="fnote8" id="fnote8" href="#revfnote8">*</a> Its use is optionally permitted in basic mode as well. </li> +<li><a name="fnote9" 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 name="fnote10" 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 name="fnote11" 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 name="fnote12" id="fnote12" href="#revfnote12">*</a> There was no list +of this type in early pre-release versions of the syntactic translator. </li> +<li><a name="fnote13" 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 name="fnote14" 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 name="fnote15" 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 name="fnote16" id="fnote16" href="#revfnote16">*</a> The variable +<em>gellmu-xml-strict</em> is by default unset in advanced mode. </li> +<li><a name="fnote17" 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 name="fnote18" 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 <b>Z</b>[t]. 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 name="fnote19" 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 name="fnote20" 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 name="fnote21" 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 name="fnote22" 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 name="fnote23" id="fnote23" href="#revfnote23">*</a> Or one +could use: +<dl class="verblist" compact="compact"> +<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 name="fnote24" id="fnote24" href="#revfnote24">*</a> In fact, classical SGML document types are often +even more elaborate than this.</li> +<li><a name="fnote25" id="fnote25" href="#revfnote25">*</a> Caveats: +<dl compact="compact"> +<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 name="fnote26" 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 name="fnote27" 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 name="fnote28" 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 name="fnote29" id="fnote29" href="#revfnote29">*</a> A <em>klabel</em> is a +“visible key” label.</li> +<li><a name="fnote30" id="fnote30" href="#revfnote30">*</a> It may be left empty, but it must be present. + </li> +<li><a name="fnote31" 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 name="fnote32" 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 name="fnote33" 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 name="fnote34" 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 name="fnote35" 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 name="fnote36" id="fnote36" href="#revfnote36">*</a> Familiar short forms +may be introduced by a user using the <em>macro</em> facility.</li> +<li><a name="fnote37" 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 name="fnote38" 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 name="fnote39" 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 name="fnote40" 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 name="fnote41" id="fnote41" href="#revfnote41">*</a> However, a declared math symbol may be invoked in +a <em>newcommand</em> that takes arguments. </li> +<li><a name="fnote42" 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 name="fnote43" 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 name="fnote44" 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 name="fnote45" 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 name="fnote46" 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 type="1"> +<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 name="fnote47" 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 name="fnote48" id="fnote48" href="#revfnote48">*</a> Formally, two of these auxiliary files are considered part of the + elaborated XML document. </li> +<li><a name="fnote49" 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 name="fnote50" 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 name="fnote51" 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 name="fnote52" 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 name="fnote53" 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 name="fnote54" 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> + diff --git a/support/gellmu/doc/glman.pdf b/support/gellmu/doc/glman.pdf Binary files differnew file mode 100644 index 0000000000..e0ad522518 --- /dev/null +++ b/support/gellmu/doc/glman.pdf 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> + diff --git a/support/gellmu/doc/glmy.png b/support/gellmu/doc/glmy.png Binary files differnew file mode 100644 index 0000000000..6570e50fc6 --- /dev/null +++ b/support/gellmu/doc/glmy.png diff --git a/support/gellmu/doc/userdoc.html b/support/gellmu/doc/userdoc.html new file mode 100644 index 0000000000..19a58da4ad --- /dev/null +++ b/support/gellmu/doc/userdoc.html @@ -0,0 +1,1216 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> +<link rel="stylesheet" type="text/css" href="../webstyle/mxh.css"> +<meta name="surtitle" content="GELLMU: Introductory User's Guide"> +<meta name="title" content="Introductory User's Guide to Regular GELLMU"> +<meta name="subtitle" content="Version 0.8.4 release, July 2007"> +<meta name="author" content="William F. Hammond"> +<title>GELLMU: Introductory User's Guide</title> +</head> +<body bgcolor="#ffffff" text="#000000" +link="#0000ee" vlink="#0000bb" alink="#ff0000"> +<h1 align="center">Introductory User's Guide to <em>Regular</em> GELLMU</h1> +<h4 align="center">Version 0.8.4 release, July 2007</h4> +<h2 align="center">William F. Hammond</h2> +<h4 align="center"> +Dept. of Mathematics & Statistics <br +> University at Albany <br +> Albany, New York 12222 (USA)</h4> +<h4 align="center">revision of July 6, 2007</h4> +<div class="tableofcontents"> +<h3>Table of Contents</h3> +<dl class="tableofcontents"> +<dd>1  Introduction... <a href="#SU-1">*</a> +</dd><dd> +2  First Steps... <a href="#SU-2">*</a> +<dl><dd> +2.1  Acquiring and Installing... <a href="#SU-2.1">*</a> +</dd><dd> +2.2  Writing an Article... <a href="#SU-2.2">*</a> +</dd></dl></dd><dd> +3  Basic Markup Within Sentences... <a href="#SU-3">*</a> +</dd><dd> +4  Sectioning... <a href="#SU-4">*</a> +</dd><dd> +5  Lists... <a href="#SU-5">*</a> +</dd><dd> +6  <em>Tabular</em> Environment Emulation... <a href="#SU-6">*</a> +</dd><dd> +7  Labels, Cross References, and Anchors... <a href="#SU-7">*</a> +</dd><dd> +8  Mathematics... <a href="#SU-8">*</a> +</dd><dd> +9  Beyond this Introductory Guide... <a href="#SU-9">*</a> +</dd></dl> +</div> + +<div class="section"> +<h3>1.  <a name="SU-1" id="SU-1"></a><a name="intro" id="intro"></a>Introduction</h3> + +<p>Regular GELLMU is the part of the GELLMU Project under which +source language markup most closely resembles actual <em>LaTeX</em> source +markup. Much of the markup vocabulary is the same as that of +actual <em>LaTeX</em>. The differences — and, indeed, the whole reason +for the GELLMU Project — arises from the author's conclusion in +1998 that it would not be possible in a robust way to write rules +for actual <em>LaTeX</em> source markup so that the collection of documents +in the <em>article</em> document class prepared under such rules would +admit fully reliable automatic translation to other formats<sup><a name="revfnote1" id="revfnote1" href="#fnote1">1</a></sup>. </p> + +<p>The version 0.8 release of the GELLMU Project was the first +release providing an output stream for the XML form of HTML extended +by the World Wide Web Consortium's +<a href="http://www.w3.org/Math/">Mathematical Markup Language (MathML)</a>. +The driver script <kbd>mmkg</kbd> provides translations of regular GELLMU +articles to (1) actual <em>LaTeX</em> (and from there to DVI and +PDF), (2) classic HTML, and (3) XHTML+MathML, while the driver +script <kbd>mkg</kbd> omits XHTML+MathML. Though the +PDF output may be read on a screen, it is intended primarily +for printing by end consumers. </p> + +<p>While one could provide a landscape version of the PDF output with +live anchors for screen consumption, the XHTML+MathML version +would still be superior for screen reading since, as with ordinary +HTML, the text is re-formatted to conform naturally both to +magnification and window-resizing actions by the end user. The +quality of the rendering of mathematics in the XHTML+MathML +version is very nearly as good as that in the PDF version. </p> + +<p>Indeed the author, as an author, finds that the best venue for proof +reading what he writes is XHTML+MathML when displayed in a suitable web +browser<sup><a name="revfnote2" id="revfnote2" href="#fnote2">2</a></sup> +with larger than normal font size and narrower than normal +line length. </p> + +<p>Moreover, the XHTML+MathML version is fully compliant with the +<a href="http://www.w3.org/WAI/">Accessibility Guidelines</a> of the +<a href="http://www.w3.org/">World Wide Web Consortium</a>. </p> + +<p>This document is an introductory user guide. The relation of regular +GELLMU to the GELLMU Project overall is explained in the <a href="glman.html">Manual</a>, and +advanced user information on regular GELLMU is found there as well. +This document covers fundamentals not mentioned in the manual. It is +available in <a href="userdoc.pdf">PDF</a>, <a href="userdoc.xhtml">XHTML+MathML</a>, +and <a href="userdoc.html">classical HTML</a> versions. Online copies of +this Introductory Guide and of the Manual may be found at +<a href="http://www.tex.ac.uk/tex-archive/help/Catalogue/entries/gellmu.html +">CTAN</a> and the <a href="http://www.albany.edu/~hammond/gellmu/">GELLMU web site</a>. </p> + +<p>To use this document as an example for learning refer to its +<a href="userdoc.glm">source markup</a> and to use the project manual +as an example refer to the +<a href="glman.glm">manual's source markup</a>. +</p> +</div> + +<div class="section"> +<h3>2.  <a name="SU-2" id="SU-2"></a><a name="firststeps" id="firststeps"></a>First Steps</h3> + +<div class="subsection"> +<h4>2.1.  <a name="SU-2.1" id="SU-2.1"></a>Acquiring and Installing</h4> + +<p>GELLMU is implemented as cross-platform free software licensed under +the GNU <a href="http://www.gnu.org/copyleft/">General Public +License</a>. Its package is available from the +<a href="http://www.ctan.org">Comprehensive TeX Archive Network</a> (CTAN) +and from the <a href="http://www.albany.edu/~hammond/gellmu/">GELLMU web site</a>. </p> + +<p>The package requires a number of other cross-platform free software +packages including GNU Emacs, <em>Perl</em>, and some standard items of +SGML/XML software, chiefly <em>Open SP</em>. Locations may be +found in the <a href="glman.html#requiredsoftware">Manual (key “<kbd>requiredsoftware</kbd>”)</a>. </p> + +<p><b>Linux:</b> The required packages are generally part of a full +GNU/<em>Linux</em> distribution. The package should be installed in +<kbd>/usr/local/gellmu</kbd> and symlinks to driver scripts should be +made from a suitable place in one's command path. </p> + +<p><b>MacOS-X and other Unix variants:</b> The only difference from +GNU/<em>Linux</em> is that some of the supporting packages may need +to be acquired and installed. </p> + +<p><b>MS Windows:</b> The best strategy is to acquire and install a +<b>full</b> <a href="http://www.cygwin.com/"><em>Cygwin</em></a> distribution. +Then proceed as with <em>Linux</em>. </p> + +<p>Additional information may be found in the <a href="glman.html">Manual</a>. +</p> +</div> + +<div class="subsection"> +<h4>2.2.  <a name="SU-2.2" id="SU-2.2"></a>Writing an Article</h4> + +<p>The minimal form of a regular GELLMU article is this:</p> + +<p></p> +<dl class="verblist" compact="compact"> +<dd><kbd> +\documenttype{article}</kbd></dd> +<dd><kbd> +\title{Some title}</kbd></dd> +<dd><kbd> + </kbd></dd> +<dd><kbd> +\begin{document}</kbd></dd> +<dd><kbd> + </kbd></dd> +<dd><kbd> +First Paragraph.</kbd></dd> +<dd><kbd> + </kbd></dd> +<dd><kbd> +Second Paragraph.</kbd></dd> +<dd><kbd> + </kbd></dd> +<dd><kbd> +. . .</kbd></dd> +<dd><kbd> + </kbd></dd> +<dd><kbd> +\end{document}</kbd></dd> +</dl> +<p></p> + +<p>An article must begin with <kbd>\documenttype{article}</kbd>. The initial +part of an article up to the required <kbd>\begin{document}</kbd> is the +article's <em>preamble</em>, and the rest of the article is the +article's <em>body</em>. </p> + +<p>Almost everything in the <em>body</em> of an article must be part of +a paragraph. Most typically a paragraph is begun with a blank line. +Paragraphs themselves may be parts of sectional units. </p> + +<p>Beware special characters. For example ‘<kbd>%</kbd>’ converts the rest +of its line to comment status. To use ‘<kbd>%</kbd>’ in text write +“<kbd>\%</kbd>”. The special characters are with small exceptions +the same as those in <em>LaTeX</em>. Note, however, that in dealing with +multiple downstream formats any character that is not alpha-numeric +becomes potentially special. Therefore, there is a named form for +every non-alphanumeric ASCII character. For example, +“<kbd>\tld;</kbd>” is the name of ASCII ‘<kbd>~</kbd>’, +which is sometimes handy when forming a URL.<sup><a name="revfnote3" id="revfnote3" href="#fnote3">3</a></sup></p> + +<p>The names of special characters may be found by browsing the SGML +document type definition in the file <kbd>gellmu.dtd</kbd> at the top of +the distribution tree.<sup><a name="revfnote4" id="revfnote4" href="#fnote4">4</a></sup> +</p> +</div> +</div> + +<div class="section"> +<h3>3.  <a name="SU-3" id="SU-3"></a><a name="sentences" id="sentences"></a>Basic Markup Within Sentences</h3> + +<p>Although there is no markup for a sentence as a unit, there is markup +for the end of a sentence or a “full stop”. The normal way to +indicate the end of a sentence is to use an ASCII period +‘<kbd>.</kbd>’ followed by either a newline or two or more blank spaces. +An end of sentence is marked up as the SGML empty element <em>eos</em>. +This is automatically generated under the condition indicated above. +For most purposes it will not matter if an ASCII period is followed +by only a single blank space, but in that case no <em>eos</em> will be +generated. </p> + +<p>The foregoing paragraph provides several instances of markup within +sentences other than <em>eos</em>. There are (1) a quoted phrase, +(2) two abbreviations, (3) a quoted character, and (4) two instances +of emphasized text. The source for that paragraph is:</p> + +<p></p> +<dl class="verblist" compact="compact"> +<dd><kbd> +Although there is no markup for a sentence as a unit, there is markup</kbd></dd> +<dd><kbd> +for the end of a sentence or a ``full stop''.  The normal way to</kbd></dd> +<dd><kbd> +indicate the end of a sentence is to use an \abbr{ASCII} period</kbd></dd> +<dd><kbd> +\quochar{.}  followed by either a newline or two or more blank spaces.</kbd></dd> +<dd><kbd> +An end of sentence is marked up as the \sgml empty element \emph{eos}.</kbd></dd> +<dd><kbd> +This is automatically generated under the condition indicated above.</kbd></dd> +<dd><kbd> +For most purposes it will not matter if an \ascii period is followed</kbd></dd> +<dd><kbd> +by only a single blank space, but in that case no \emph{eos} will be</kbd></dd> +<dd><kbd> +generated.</kbd></dd> +</dl> +<p></p> + +<p>The <kbd>``full stop''</kbd> is a marked up quoted phrase. The named form of a +quoted phrase is <em>quophrase</em>. The markup <kbd>\quophrase{full stop}</kbd> +is the equivalent expanded form. An abbreviation is indicated with the +command <em>abbr</em>. There is, of course, no requirement that an +abbreviation be marked up; it is merely good practice. </p> + +<p>The name of markup for emphasized text is <em>emph</em>. A common +alternate form of emphasis is called <em>bold</em>. One way the two +differ is that <em>emph</em> has order two effect, i.e., <em>emph</em> +within <em>emph</em> removes emphasis while <em>bold</em> is not permitted +within itself. Note that <em><b>bold</b></em> may be emphasized. </p> + +<p>In the cited marked up text above the instances <kbd>\sgml</kbd> and <kbd>\ascii</kbd> +are user-defined <em>newcommands</em> occurring in the preamble (or at least +before the invocations): +</p> +<dl class="verblist" compact="compact"> +<dd><kbd> +\newcommand{\ascii}{\abbr{ASCII}}</kbd></dd> +<dd><kbd> +\newcommand{\sgml}{\abbr{SGML}}</kbd></dd> +</dl> +<p> +The command <em>newcommand</em> is a meta-command in GELLMU source. +All <em>newcommand</em> instances are fully expanded by the syntactic +translator before it writes any output. </p> + +<p>The markup <kbd>\quochar{x}</kbd> produces a quoted character: in this case +‘<kbd>x</kbd>’. There is no compelling reason why <em>quophrase</em> could +not have been used instead of <em>quochar</em>, but it is customary in +technical documentation to use a different presentation style for +quoted characters than for quoted phrases. Beyond that for +non-traditional forms of processing it can be very useful to provide +for semantic distinctions such as the distinction between a quoted +phrase in normal discourse and a quoted string in technical discourse. +More particularly, it is significant that in some languages for +computer programming there is an important distinction between a +character and a string of unit length. Some of the markup commands +useful with technical documentation are +</p> +<center><table class="gdisplay"><tbody><tr><td> +<table><tbody> +<tr><td align="left"><b>command</b></td><td align="left"><b>example in source</b></td><td align="left"><b>example rendered</b></td></tr +><tr><td align="left"><em>quochar</em></td><td align="left"><kbd>use \quochar{\%} to comment</kbd></td><td align="left">use ‘<kbd>%</kbd>’ to comment</td></tr +><tr><td align="left"><em>quostr</em></td><td align="left"><kbd>\quostr{unsigned long num;}</kbd></td><td align="left"><kbd>unsigned long num;</kbd></td></tr +><tr><td align="left"><em>qquostr</em></td><td align="left"><kbd>type \qquostr{done} to exit</kbd></td><td align="left">type “<kbd>done</kbd>” to exit</td></tr +><tr><td align="left"><em>path</em></td><td align="left"><kbd>\path{C:\bsl;TEX\bsl;TEXMF}</kbd></td><td align="left"><kbd>C:\TEX\TEXMF</kbd></td></tr +><tr><td align="left"><em>urlanch</em></td><td align="left"><kbd>see \urlanch{userdoc.glm}  </kbd></td><td align="left">see <a href="userdoc.glm"><kbd>userdoc.glm</kbd></a></td></tr +></tbody></table> +</td></tr></tbody></table></center> +<p> +With regular <em>LaTeX</em> standard practice is to use <em>texttt</em> for the +examples just cited involving <em>quochar</em>, <em>quostr</em>, +<em>path</em>, and, apart from web-related considerations, +<em>urlanch</em>. The name <em>url</em> has been used variously in +regular <em>LaTeX</em>; therefore, <em>url</em> has not been introduced as a +name in regular GELLMU so that an author may safely use it, if +desired, as a macro name. +</p> +</div> + +<div class="section"> +<h3>4.  <a name="SU-4" id="SU-4"></a><a name="sectioning" id="sectioning"></a>Sectioning</h3> + +<p>Unless one wants fancy non-default behavior, one may provide +sections, subsections, and subsubsections as in <em>LaTeX</em>. Thus, +for example,</p> + +<p></p> +<dl class="verblist" compact="compact"> +<dd><kbd> +\documenttype{article}</kbd></dd> +<dd><kbd> +\title{Some title}</kbd></dd> +<dd><kbd> + </kbd></dd> +<dd><kbd> +\begin{document}</kbd></dd> +<dd><kbd> + </kbd></dd> +<dd><kbd> +\section{Title of first section}</kbd></dd> +<dd><kbd> +First Paragraph.</kbd></dd> +<dd><kbd> + </kbd></dd> +<dd><kbd> +Second Paragraph.</kbd></dd> +<dd><kbd> + </kbd></dd> +<dd><kbd> +. . .</kbd></dd> +<dd><kbd> + </kbd></dd> +<dd><kbd> +\section{Title of second section}</kbd></dd> +<dd><kbd> +First Paragraph.</kbd></dd> +<dd><kbd> + </kbd></dd> +<dd><kbd> +Second Paragraph.</kbd></dd> +<dd><kbd> + </kbd></dd> +<dd><kbd> +. . .</kbd></dd> +<dd><kbd> + </kbd></dd> +<dd><kbd> +\end{document}</kbd></dd> +</dl> +<p></p> + +<p>With this style of markup one does not indicate the end of a section +although there is a way described in the <a href="glman.html#secusage">Manual (key “<kbd>secusage</kbd>”)</a> to gain finer +control over sectional units. +</p> +</div> + +<div class="section"> +<h3>5.  <a name="SU-5" id="SU-5"></a><a name="lists" id="lists"></a>Lists</h3> + +<p>As with <em>LaTeX</em> GELLMU <em>article</em> provides lists with the +names <em>description</em>, <em>enumerate</em>, and <em>itemize</em>. +For example, the markup +</p> +<dl class="verblist" compact="compact"> +<dd><kbd> +\begin{enumerate}</kbd></dd> +<dd><kbd> +\item bird</kbd></dd> +<dd><kbd> +\item cat</kbd></dd> +<dd><kbd> +\item dog</kbd></dd> +<dd><kbd> +\end{enumerate}</kbd></dd> +</dl> +<p> +yields: +</p> +<dl compact="compact"> +<dd> <ol type="1"> +<li><p> bird</p> +</li> +<li><p> cat</p> +</li> +<li><p> dog</p> +</li> +</ol> +</dd> +</dl> +<p> +while the markup +</p> +<dl class="verblist" compact="compact"> +<dd><kbd> +\begin{description}</kbd></dd> +<dd><kbd> +\item[Parrot] a type of bird</kbd></dd> +<dd><kbd> +\item[Persian] a type of house cat</kbd></dd> +<dd><kbd> +\item[Pointer] a type of dog</kbd></dd> +<dd><kbd> +\end{description}</kbd></dd> +</dl> +<p> +yields: +</p> +<dl compact="compact"> +<dd> <dl> +<dt><b> +Parrot</b></dt> +<dd>a type of bird</dd><dt><b> +Persian</b></dt> +<dd>a type of house cat</dd><dt><b> +Pointer</b></dt> +<dd>a type of dog</dd></dl> +</dd> +</dl> +<p></p> + +<p>A list is normally part of a paragraph, but a list may occur outside +of a paragraph in a sectional unit or even at the top level of +an article's body. </p> + +<p>An <em>item</em> in a list may contain paragraphs but, as the foregoing +examples show, may contain loose text. </p> + +<p>While <em>LaTeX</em> provides an excellent construction facility for customized +lists through its <em>list</em> environment, which may be used in +conjunction with its <em>newenvironment</em> command, there is no facility +for the provision of on-the-fly markup in SGML. Therefore, the +<em>article</em> document type provides several other kinds of list. </p> + +<p>The lists called <em>menu</em> and <em>Menu</em> consist of +<em>items</em>. These lists have no item labels. They differ only +in intention for spacing in presentation formats. </p> + +<p>It often makes sense for <em>menu</em> to be used inside an <em>item</em> +of another list. Moreover, a single item <em>menu</em> will render in +either the <em>LaTeX</em> or HTML formattings as “hanging indentation”. </p> + +<p>A <em>defnlist</em> is intended to be more like the list called <em>dl</em> +in HTML than like <em>description</em>. It must consist of one or +more <em>term</em>, <em>desc</em> pairs with <em>term</em> mandatory and +<em>desc</em> optional. </p> + +<p>There are also other lists that will not be mentioned here except to +point out that when the name <em>verbatim</em> is enabled as a +metacommand, rather than as a command, by calling the syntactic +translator with a non-default function<sup><a name="revfnote5" id="revfnote5" href="#fnote5">5</a></sup> +such as <kbd>verblist</kbd> or <kbd>latex-faq</kbd>, the verbatim material +is organized as a <em>verblist</em>. </p> + +<p>For more information about lists browse the document type definitions +<kbd>gellmu.dtd</kbd> and <kbd>xml/xgellmu.dtd</kbd> being mindful that +default processing in the didactic production system sometimes does +a small amount of list manipulation between the SGML and XML versions +of an <em>article</em>. +</p> +</div> + +<div class="section"> +<h3>6.  <a name="SU-6" id="SU-6"></a><a name="tabular" id="tabular"></a><em>Tabular</em> Environment Emulation</h3> + +<p>Most users having a <em>LaTeX</em> background will find that <em>tabular</em> +with column arguments limited to ‘<kbd>l</kbd>’, ‘<kbd>r</kbd>’, +‘<kbd>c</kbd>’, and ‘<kbd>p</kbd>’ is reasonably functional. +Improvement made during 2006 were made possible by the increased +availability to users of web browsers supporting version 2 of the +cascading style sheets (CSS) specification. </p> + +<p>For example, the following markup underlies a small +<a href="#mathzones"><em>lcc</em> table</a> in the section on mathematics. +</p> +<dl class="verblist" compact="compact"> +<dd><kbd> +\display{\begin{tabular}{lcc}</kbd></dd> +<dd><kbd> +\bold{Name} & \bold{Opener}       & \bold{Closer}   \\</kbd></dd> +<dd><kbd> +math        & \quostr{\bsl;(}     & \quostr{\bsl;)} \\</kbd></dd> +<dd><kbd> +tmath       & \quostr{\$}         & \quostr{\$}     \\</kbd></dd> +<dd><kbd> +displaymath & \quostr{\bsl\lsb;}  & \quostr{\bsl\rsb;}</kbd></dd> +<dd><kbd> +\end{tabular}}</kbd></dd> +</dl> +<p> +(In this markup <em>bsl</em> is a name for the backslash character +and <em>lsb</em>, <em>rsb</em> the names of the square brackets.)</p> + +<p>There is presently no concept of “float”. </p> + +<p>More information is available in the <a href="glman.html#tabular">Manual (key “<kbd>tabular</kbd>”)</a>. +</p> +</div> + +<div class="section"> +<h3>7.  <a name="SU-7" id="SU-7"></a><a name="links" id="links"></a>Labels, Cross References, and Anchors</h3> + +<p>The basic idea is very simple. Use +</p> +<center><table class="gdisplay"><tbody><tr><td> +<kbd>\label{</kbd><em>mylabelkey</em><kbd>}</kbd></td></tr></tbody></table></center> +<p> +to <b>mark</b> a location that is associated with the named +label key, and use +</p> +<center><table class="gdisplay"><tbody><tr><td> +<kbd>\ref{</kbd><em>mylabelkey</em><kbd>}</kbd></td></tr></tbody></table></center> +<p> +or one of several other methods to reference that location. +The command <em>ref</em> may be regarded as the default method. +In an online version, however, it has <b>not</b> been designed to +create a selectable anchor but rather simply to indicate section +number. </p> + +<p>For example, in this document there is a label with the key +“<kbd>math</kbd>” at the beginning of the section (8) on +mathematics. The previous sentence contains a reference with +the markup <kbd>\ref{math}</kbd> to that section. This markup results +in the number of that section appearing in the first sentence. +For clarity the markup for the entire first sentence of this +paragraph is: +</p> +<dl class="verblist" compact="compact"> +<dd><kbd> +For example, in this document there is a label with the key</kbd></dd> +<dd><kbd> +\qquostr{math} at the beginning of the section (\ref{math}) on</kbd></dd> +<dd><kbd> +mathematics.</kbd></dd> +</dl> +<p></p> + +<p>If, on the other hand, one wants an online version to contain +a <a href="#math">selectable anchor to section 8</a> to the +section on math, then +in the preamble of the document one might place the newcommand +definition +</p> +<center><table class="gdisplay"><tbody><tr><td> +<kbd>\newcommand{\iref}[2]{\anch[iref="#1"]{#2}}</kbd></td></tr></tbody></table></center> +<p> +and then, as in the foregoing portion of this sentence use +the markup +</p> +<center><table class="gdisplay"><tbody><tr><td> +<kbd>\iref{math}{selectable anchor to section \ref{math}}</kbd> .</td></tr></tbody></table></center> +<p> +Note that this markup uses the label key “<kbd>math</kbd>” twice: +once as the first argument to the newcommand called <em>iref</em> +and once as the sole argument of the command <em>ref</em> that +itself appears in the second argument of <em>iref</em>. </p> + +<p>On the question of whether to use <em>ref</em> or one of several +other commands to make a reference, there are several considerations: +</p> +<ol type="1"> +<li><p> How should the reference be indicated in an online format + that will be viewed in an ebook or a web browser? </p> +</li> +<li><p> How should the reference be indicated in a typeset format + where there is neither a cursor nor the possibility of automatic + scrolling? </p> +</li> +</ol> +<p> +More details on this subject may be found in the +<a href="glman.html#labelref">Manual (key “<kbd>labelref</kbd>”)</a>. +</p> +</div> + +<div class="section"> +<h3>8.  <a name="SU-8" id="SU-8"></a><a name="math" id="math"></a>Mathematics</h3> + +<p>GELLMU <em>article</em> provides 5 containers for mathematical +content: <em>math</em>, <em>tmath</em>, <em>displaymath</em>, <em>equation</em>, +<em>eqnarray</em>. All may be referenced by name. However, +<em>LaTeX</em>-like markup is supported: +<a name="mathzones" id="mathzones"></a> +</p> +<center><table class="gdisplay"><tbody><tr><td> +<table><tbody> +<tr><td align="left"><b>Name</b></td><td align="center"><b>Opener</b></td><td align="center"><b>Closer</b></td></tr +><tr><td align="left">math</td><td align="center"><kbd>\(</kbd></td><td align="center"><kbd>\)</kbd></td></tr +><tr><td align="left">tmath</td><td align="center"><kbd>$</kbd></td><td align="center"><kbd>$</kbd></td></tr +><tr><td align="left">displaymath</td><td align="center"><kbd>\[</kbd></td><td align="center"><kbd>\]</kbd></td></tr +></tbody></table> +</td></tr></tbody></table></center> +<p></p> + +<p>The containers <em>math</em> and <em>tmath</em> are essentially +equivalent non-displayed containers. The current <em>LaTeX</em> formatter +provides a tiny amount of extra horizontal space around <em>math</em> +but not around <em>tmath</em>. </p> + +<p>Just as with ordinary <em>LaTeX</em> there can be difficulty locating +a missing ‘<kbd>$</kbd>’ if one uses these for <em>tmath</em>. Unbalanced +‘<kbd>$</kbd>’ characters usually lead the syntactic translator to +complain (correctly, though not with as much user-friendliness as one +might wish) about not being able to balance a brace. In this case +if <em>tmath</em> is seen in the displayed surrounding text, a missing +‘<kbd>$</kbd>’ is likely. </p> + +<p>MathML rendering support (with MathML's presentation markup) in HTML +versions, i.e., the modern XML form of HTML extended with MathML, is +new in the summer of 2004. </p> + +<p>A program to generate an output stream providing content-level MathML +markup, i.e., semantic markup transparent for computer algebra +systems, has not yet been written. </p> + +<p>Those who use mathematics may find the following illustrations +instructive. </p> + +<p>The markup +</p> +<dl class="verblist" compact="compact"> +<dd><kbd> +Just as with \tex; or \latex; it is easy to provide a mathematical</kbd></dd> +<dd><kbd> +formula, such as $y = x^3/(x^2 + 1)$\aoc either inline or displayed.</kbd></dd> +</dl> +<p> +produces: +</p> +<dl compact="compact"> +<dd> Just as with <em>TeX</em> or <em>LaTeX</em> it is easy to provide a mathematical +formula, such as y = x^{3}/(x^{2} + 1), either inline or displayed. </dd> +</dl> +<p></p> + +<p>This markup +</p> +<dl class="verblist" compact="compact"> +<dd><kbd> +Here the same formula is displayed.</kbd></dd> +<dd><kbd> +\[ y = \frac{x^3}{x^2 + 1} \eos\]</kbd></dd> +</dl> +<p> +yields: +</p> +<dl compact="compact"> +<dd> Here the same formula is displayed. +<center><table cellspacing="0" cellpadding="0"><tr><td> + y  =  {x^{3}}/{x^{2} + 1}   . +</td></tr></table></center></dd> +</dl> +<p> +The <em>eos</em> corresponds to an empty SGML element for “end of +sentence” (or “full stop”). Normally one simply uses ‘<kbd>.</kbd>’, +but inside a displayed math zone there is semantic-level risk of +confusion with various possible uses of ‘<kbd>.</kbd>’ as a mathematical +symbol. </p> + +<p>Markup: +</p> +<dl class="verblist" compact="compact"> +<dd><kbd> +The square root of a compound fraction:</kbd></dd> +<dd><kbd> +\[ \sqrt{\frac{\frac{a}{b}}{\frac{c}{d}}} \eos \]</kbd></dd> +</dl> +<p> +Rendered: +</p> +<dl compact="compact"> +<dd> The square root of a compound fraction: +<center><table cellspacing="0" cellpadding="0"><tr><td> + SQRT{{{a}/{b}}/{{c}/{d}}}   .  +</td></tr></table></center></dd> +</dl> +<p></p> + +<p>In the current XHTML+MathML formatting by default radical signs in +source markup are converted by default to fractional exponents because +of an intellectual property issue with fonts available for use by the +open source <em>Mozilla</em> browser and its spinoffs including +<em>Firefox</em>, <em>Galeon</em>, and <em>Nautilus</em>.<sup><a name="revfnote6" id="revfnote6" href="#fnote6">6</a></sup></p> + +<p>Using the markup for numbered equations +</p> +<dl class="verblist" compact="compact"> +<dd><kbd> +The quadratic equation</kbd></dd> +<dd><kbd> +\begin{equation} a x^2 + b x + c = 0 \end{equation}</kbd></dd> +<dd><kbd> +has roots</kbd></dd> +<dd><kbd> +\begin{equation}</kbd></dd> +<dd><kbd> + x = \frac{-b \pm \sqrt{b^2 - 4 a c}}{2 a} \ \eos</kbd></dd> +<dd><kbd> +\end{equation}</kbd></dd> +</dl> +<p> +one obtains the rendering: +</p> +<dl compact="compact"> +<dd> The quadratic equation +<a name="EqnKey-1" id="EqnKey-1"></a><center><table cellspacing="0" cellpadding="0"><tr><td> +(1)   a x^{2} + b x + c  =  0  +</td></tr></table></center> + +has roots +<a name="EqnKey-2" id="EqnKey-2"></a><center><table cellspacing="0" cellpadding="0"><tr><td> +(2)   x  =  {-b ± SQRT{b^{2} - 4 a c}}/{2 a}    . +</td></tr></table></center> +</dd> +</dl> +<p></p> + +<p><b>Rule for subscripts and superscripts:</b> A subscript or +superscript must be braced if keyboarding it involves more than +one character. Thus, one <em>may</em> use <kbd>$C^2$</kbd> or <kbd>$C^{2}$</kbd> +to produce C^{2}, but one <em>must</em> use <kbd>$C^{\infty}$</kbd> to +generate C^{INFTY}. </p> + +<p>The Taylor series of the <em>exponential</em> function is +</p> +<center><table cellspacing="0" cellpadding="0"><tr><td> + e^{t}  =  SUM_{k  =  0}^{INFTY}[  {t^{k}}/{k!} ]    .  +</td></tr></table></center> +<p> +Note here that the <em>sum</em> markup <kbd>\sum</kbd> requires a formal +terminator <kbd>\sum:</kbd> (likewise with <kbd>\int</kbd> for integral and <kbd>\prod</kbd> +for product). +</p> +<dl class="verblist" compact="compact"> +<dd><kbd> +\[ e^t = \sum_{k = 0}^{\infty} \, \frac{t^k}{k!} \sum: \ \eos \]</kbd></dd> +</dl> +<p></p> + +<p>The markup +</p> +<dl class="verblist" compact="compact"> +<dd><kbd> +The continued fraction expansion of the \emph{golden mean}:</kbd></dd> +<dd><kbd> +\[\frac{1 + \sqrt{5}}{2} =</kbd></dd> +<dd><kbd> +     1 + \frac{1}{1+\frac{1}{1+\frac{1}{1+\frac{1}{1+\ldots;}}}} \eos \]</kbd></dd> +</dl> +<p> +produces: +</p> +<dl compact="compact"> +<dd> The continued fraction expansion of the <em>golden mean</em>: +<center><table cellspacing="0" cellpadding="0"><tr><td> +{1 + SQRT{5}}/{2}  =   1 + {1}/{1+{1}/{1+{1}/{1+{1}/{1+…}}}}   .  +</td></tr></table></center></dd> +</dl> +<p> +while the markup +</p> +<dl class="verblist" compact="compact"> +<dd><kbd> +Mixed function application and multiplication:</kbd></dd> +<dd><kbd> +\[ {\func{sin}\aF;{ax}}\itimes;{\func{cos}\aF;{bx}} \eos \]</kbd></dd> +</dl> +<p> +yields +</p> +<dl compact="compact"> +<dd> Mixed function application and multiplication: +<center><table cellspacing="0" cellpadding="0"><tr><td> + {<b>sin</b>{ax}}{<b>cos</b>{bx}}   .  +</td></tr></table></center></dd> +</dl> +<p></p> + +<p>Markup: +</p> +<dl class="verblist" compact="compact"> +<dd><kbd> +Newton's binomial series:</kbd></dd> +<dd><kbd> +\[ (1 + t)^r = \sum_{k=0}^{\infty} \,</kbd></dd> +<dd><kbd> +  \frac{r(r - 1)(r - 2)\ldots(r - k + 1)}{k!}\, t^k \sum: \eos \]</kbd></dd> +</dl> +<p> +rendering: +</p> +<dl compact="compact"> +<dd> Newton's binomial series: +<center><table cellspacing="0" cellpadding="0"><tr><td> + (1 + t)^{r}  =  SUM_{k = 0}^{INFTY}[   {r(r - 1)(r - 2)…(r - k + 1)}/{k!}  t^{k} ]   .  +</td></tr></table></center></dd> +</dl> +<p></p> + +<p>Markup: +</p> +<dl class="verblist" compact="compact"> +<dd><kbd> +A differential equation:</kbd></dd> +<dd><kbd> +\[ D^2 y - 3 x (D y)^2 = x \func{cos} x \ \eos \]</kbd></dd> +</dl> +<p> +rendering: +</p> +<dl compact="compact"> +<dd> A differential equation: +<center><table cellspacing="0" cellpadding="0"><tr><td> + D^{2} y - 3 x (D y)^{2}  =  x <b>cos</b> x    .  +</td></tr></table></center></dd> +</dl> +<p></p> + +<p>The statement of Stokes's Theorem in space +</p> +<center><table cellspacing="0" cellpadding="0"><tr><td> + INT[INT_{S}[  (<b>curl</b>    <b>F</b>  ·  <b>N</b>)  d<b>sigma</b>]]   =  INT_{<b>partial</b> S}[  (<b>F</b>  ·  <b>T</b>)  ds ]    .  +</td></tr></table></center> +<p> +may be generated by the markup +</p> +<dl class="verblist" compact="compact"> +<dd><kbd> +\[ \int\int_S \, (\mbox{\bold{curl}}</kbd></dd> +<dd><kbd> + \, \regch{\bold{F}} \,\cdot\, \regch{\bold{N}})\, d\sigma;</kbd></dd> +<dd><kbd> +\int:\int:</kbd></dd> +<dd><kbd> + = </kbd></dd> +<dd><kbd> +\int_{\partial S} \, (\regch{\bold{F}}</kbd></dd> +<dd><kbd> +\,\cdot\, \regch{\bold{T}})\, ds \int:\, \eos \]</kbd></dd> +</dl> +<p> +Note that each <kbd>\int</kbd> integral opener must be followed eventually +by a <kbd>\int:</kbd> closer (or braces could be used, i.e., <kbd>\int{ ... }</kbd>, +or <kbd>\begin{int}</kbd> … <kbd>\end{int}</kbd> also could be used. </p> + +<p>The branched definition of the absolute value of a real number may +be marked up with +</p> +<dl class="verblist" compact="compact"> +<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}} \ \eos \]</kbd></dd> +</dl> +<p> +to yield +</p> +<center><table cellspacing="0" cellpadding="0"><tr><td> +  |x|   =  </td><td><table cellspacing="0" cellpadding="0"><tr><td valign="middle" align="right">{</td><td valign="middle" align="left"></td><td><table> +<tr><td align="right">x </td> +<td align="left"> if  x  >=  0</td> +</tr><tr><td align="right">-x</td> +<td align="left"> if  x < 0</td> +</tr></table></td><td></td></tr></table> +</td><td>    .  +</td></tr></table></center> +<p></p> + +<p>The <em>LaTeX</em>-like command <em>mathbf</em> is new in GELLMU +<em>article</em>. It may only be used in math. The command +<em>bold</em>, which indicates bold-style emphasis, parallel to +<em>strong</em> in HTML and <em>textbf</em> in <em>LaTeX</em>, may be +used inside mathematical content as well as outside. However, +<em>bold</em> may not contain math-special symbols such as that given by +<kbd>\alpha</kbd>, while <em>mathbf</em> may. </p> + +<p>A certain amount of attention to semantics is required in order to +have robust generation of the XHTML+MathML output. An absolutely +basic part of this is having unambiguous determination of what is a +single symbol. By long convention in <em>TeX</em> the string “abcd” in +math is understood as the product (in whatever sense of “product”) +of four symbols. If a string with more than one character — for +example, “Hom” — is to be a single symbol, it may be marked up +with <em>mbox</em> or, in GELLMU source, be assigned a symbol name +having custom print representation using <em>mathsym</em> in the preamble. +In GELLMU source <em>mathbf</em> should only contain a single symbol. + + +</p> + +<p>The markup +</p> +<dl class="verblist" compact="compact"> +<dd><kbd> +\display{$\nabla\times\vec{\mbox{\bold{B}}}$</kbd></dd> +<dd><kbd> +         \ with ``mbox'' and ``bold'' versus</kbd></dd> +<dd><kbd> +         \ $\nabla\times\vec{\mathbf{B}}$ \ with ``mathbf''\,.}</kbd></dd> +</dl> +<p> +produces +</p> +<center><table class="gdisplay"><tbody><tr><td> + \nabla \times\vec{<b>B</b>} + with “mbox” and “bold” versus + \nabla \times\vec{<b>B</b>} with “mathbf”.</td></tr></tbody></table></center> +<p></p> + +<p>Diagrams are done using <em>array</em>. They must, therefore, be +rectangular. The markup +</p> +<dl class="verblist" compact="compact"> +<dd><kbd> +\newcommand{\ra}{\rightarrow}</kbd></dd> +<dd><kbd> +\newcommand{\da}{\downarrow}</kbd></dd> +<dd><kbd> +\[ \begin{array}{ccccccccc}</kbd></dd> +<dd><kbd> +0 & \ra  & A'  & \ra  & A   & \ra &  A''  & \ra & 0 \\</kbd></dd> +<dd><kbd> +~ &      & \da &      & \da &     & \da   &     &   \\</kbd></dd> +<dd><kbd> +0 & \ra  & B'  & \ra  & B   & \ra &  B''  & \ra & 0</kbd></dd> +<dd><kbd> +\end{array} \]</kbd></dd> +</dl> +<p> +yields +</p> +<center><table cellspacing="0" cellpadding="0"><tr><td> + </td><td><table> +<tr><td align="center">0 </td> +<td align="center"> --> </td> +<td align="center">A^{′}</td> +<td align="center"> --> </td> +<td align="center">A</td> +<td align="center"> --> </td> +<td align="center">A^{″}</td> +<td align="center"> --> </td> +<td align="center">0</td> +</tr><tr><td align="center"> </td> +<td align="center"></td> +<td align="center">↓</td> +<td align="center"></td> +<td align="center">↓</td> +<td align="center"></td> +<td align="center">↓</td> +<td align="center"></td> +<td align="center"></td> +</tr><tr><td align="center">0</td> +<td align="center"> --> </td> +<td align="center">B^{′}</td> +<td align="center"> --> </td> +<td align="center">B</td> +<td align="center"> --> </td> +<td align="center">B^{″}</td> +<td align="center"> --> </td> +<td align="center">0</td> +</tr></table></td><td>  +</td></tr></table></center> +<p> + +</p> +<dl> +<dd> <b>Comments about <em>array</em>, <em>eqnarray</em>, <em>tabular</em></b> +<ol type="1"> +<li><p> In this markup note the appearance of the character ‘<kbd>~</kbd>’ at +the beginning of the second row of the array. The modular design of +the didactic production system requires that the syntactic translator +may only deal with markup syntax. The ‘<kbd>~</kbd>’, which is markup +in GELLMU source as in <em>LaTeX</em> for “non-breaking space”, in the +first cell of the second row serves to keep the first cell from being +empty. There is a technical error in the SGML output of the +syntactic translator when the first cell in an <em>array</em> or +<em>tabular</em> row is empty unless there is an explicit opentag for +the first cell. The technical error will trigger a validation error +though it should not interfere with the generation of a correct parsed +output.<sup><a name="revfnote7" id="revfnote7" href="#fnote7">7</a></sup> +</p> +</li> +<li><p> Also in the foregoing markup note that the <em>LaTeX</em>-like use of the +character ‘<kbd>&</kbd>’ as the introducer of a new cell must in GELLMU +source be followed by whitespace. Otherwise there is risk of +confusion with the alternative markup use of ‘<kbd>&</kbd>’ in GELLMU +source (though not in <em>LaTeX</em> source) to initiate an SGML entity +reference. </p> +</li> +</ol> +<br><br +></dd> +</dl> +<p></p> + +<p>There is multiscript support. The command <em>mscript</em> takes 5 +arguments. The first is its base. The script order is counter-clockwise +beginning with upper-left. For example, +</p> +<center><table cellspacing="0" cellpadding="0"><tr><td> +\pre[_{2}^{14}]<b>{</b><b>C</b><b>}</b>_{5+}^{2}    \pre[_{b}^{a}]<b>{</b>Hom<b>}</b>_{c}^{d}(X,Y) +</td></tr></table></center> +<p> +is produced by +</p> +<dl class="verblist" compact="compact"> +<dd><kbd> +\[</kbd></dd> +<dd><kbd> +\mscript{\mathbf{C}}{14}{2}{5+}{2}\quad</kbd></dd> +<dd><kbd> +\mscript{\mbox{Hom}}{a}{b}{c}{d}(X,Y)</kbd></dd> +<dd><kbd> +\]</kbd></dd> +</dl> +<p></p> + +<p><em>AMSMath</em>-like overset and underset: <kbd>\overset{A}{B}</kbd> + then <kbd>\underset{A}{B}</kbd> +</p> +<center><table cellspacing="0" cellpadding="0"><tr><td> + \overset{A}{B} +     \underset{A}{B} +  +</td></tr></table></center> +<p></p> + +<p>The command <em>overset</em> is the <em>AMSMath</em> replacement in <em>LaTeX</em> +for <em>LaTeX</em>'s native <em>stackrel</em>. </p> + +<p></p> +<dl class="verblist" compact="compact"> +<dd><kbd> +A map may be labeled using \emph{overset}:</kbd></dd> +<dd><kbd> +\[ X \overset{f}{\longrightarrow} Y \]</kbd></dd> +<dd><kbd> +or using \emph{underset}:</kbd></dd> +<dd><kbd> +\[ X \underset{f}{\longrightarrow} Y \]</kbd></dd> +</dl> +<p> +</p> +<dl compact="compact"> +<dd> A map may be labeled using <em>overset</em>: +<center><table cellspacing="0" cellpadding="0"><tr><td> + X \overset{f}{ ----> } + Y  +</td></tr></table></center> +or using <em>underset</em>: +<center><table cellspacing="0" cellpadding="0"><tr><td> + X \underset{f}{ ----> } + Y  +</td></tr></table></center></dd> +</dl> +<p></p> + +<p>Binary or pseudo-binary operators: +</p> +<center><table cellspacing="0" cellpadding="0"><tr><td> +vee: ∨   setminus: ∖   ll: ≪   gg: ≫     approx: ≊  ਊsymp: ≈    +</td></tr></table></center> +<p> +</p> +<center><table cellspacing="0" cellpadding="0"><tr><td> +rightarrow:  -->    leftarrow:  <--     implies: ⇒   revimplies: ⇐   iff: ⇔    +</td></tr></table></center> +<p></p> + +<p>Other operators: +</p> +<center><table cellspacing="0" cellpadding="0"><tr><td> +uparrow: ↑  ਍ownarrow: ↓   triangle: ▵  ꂫuts: ⇒    +</td></tr></table></center> +<p></p> + +<p>The command <em>vect</em> is for vector generation. Its usage is: +</p> +<center><table class="gdisplay"><tbody><tr><td> +<kbd>\vect[</kbd><em>open-close-separator spec</em><kbd>]{</kbd><em>coordinate</em><kbd>}</kbd> …</td></tr></tbody></table></center> +<p> +Thus, the markup <kbd>\vect{x}{y}{z}</kbd> produces (x, y, z). +On the other hand the markup <kbd>\vect[]{x}{y}{z}</kbd> produces +xyz. This might be useful, for example, in +providing reasonably semantic (but visibly traditional) markup for a +tensor field. For example +</p> +<center><table cellspacing="0" cellpadding="0"><tr><td> +T_{j_{1}j_{2}…j_{q}}^{i_{1}i_{2}…i_{p}} +</td></tr></table></center> +<p> +When <em>vect</em>'s option is empty, vector opener, closer, and coordinate +separators are all nil. <em>vect</em> might be used to provide the stylized, +though semantically dubious, +inner product markup <kbd>\vect[<>;]{v}{w}</kbd> yielding +</p> +<center><table cellspacing="0" cellpadding="0"><tr><td> + <v; w>  ,  +</td></tr></table></center> +<p> +or with the markup <kbd>\vect[\lsb;\rsb;:]{a}{b}{c}</kbd> +to customize notation for the homogeneous coordinate triple +representing a point of <b>P</b>^{2}: +</p> +<center><table cellspacing="0" cellpadding="0"><tr><td> + [a: b: c]    .  +</td></tr></table></center> +<p></p> + +<p>Leray's spectral sequence: +</p> +<dl compact="compact"> +<dd> If +<center><table cellspacing="0" cellpadding="0"><tr><td> + X   ---->    B  +</td></tr></table></center> +with fibre F, then +<center><table cellspacing="0" cellpadding="0"><tr><td> + {<b>{</b>E<b>}</b>_{2}^{pq}  =  H^{p}(B, H^{q}(F))}  ⇒ H^{*}(X)    .  +</td></tr></table></center></dd> +</dl> +<p> +is produced by +</p> +<dl class="verblist" compact="compact"> +<dd><kbd> +If</kbd></dd> +<dd><kbd> +\[ X \ \longrightarrow \  B \]</kbd></dd> +<dd><kbd> +with fibre $F$\@, then </kbd></dd> +<dd><kbd> +\[ {\mscript{E}{}{}{2}{\vect[]{p}{q}} = H^p\aF(B, H^q\aF(F))}</kbd></dd> +<dd><kbd> +   \abuts H^{*}\aF(X) \ \eos \]</kbd></dd> +</dl> +<p> +In this markup the command <kbd>\aF</kbd>, is not strictly necessary. +It provides a deliberate way to indicate that, in the second +instance above, the symbol X is argument-like in relation to +the symbol H^{*}. In MathML rendering <em>aF</em> gives rise to +presentation-level MathML's invisible operator <em>ApplyFunction</em>. +</p> +</div> + +<div class="section"> +<h3>9.  <a name="SU-9" id="SU-9"></a>Beyond this Introductory Guide</h3> + +<p>More information about GELLMU is available in the <a href="glman.html">Manual</a>. +Some examples of topics to be found there include: +</p> +<ul> +<li><p> Inclusion of graphic objects: <a href="glman.html#graphics">Manual (key “<kbd>graphics</kbd>”)</a>. </p> +</li> +<li><p> Equations and equation arrays: <a href="glman.html#eqn">Manual (key “<kbd>eqn</kbd>”)</a>. </p> +</li> +<li><p> Emulation of <em>LaTeX</em>'s <em>newtheorem</em> environments: <a href="glman.html#assert">Manual (key “<kbd>assert</kbd>”)</a>. </p> +</li> +<li><p> Emulation of <em>LaTeX</em>'s counters: <a href="glman.html#counters">Manual (key “<kbd>counters</kbd>”)</a>. </p> +</li> +<li><p> The flowchart for regular GELLMU processing: <a href="glman.html#flow">Manual (key “<kbd>flow</kbd>”)</a>. </p> +</li> +</ul> +<p></p> + +<p>The author tries to keep fresh information on the <a href="http://www.albany.edu/~hammond/gellmu/">GELLMU web site</a>. +</p> +</div> +<hr> +<h3>Footnotes</h3> +<ol> +<li><a name="fnote1" id="fnote1" href="#revfnote1">*</a> This should not be construed to mean, however, that standard <em>LaTeX</em> +processing could not incorporate this type of source markup at some +time in the future. </li> +<li><a name="fnote2" id="fnote2" href="#revfnote2">*</a> The author prefers the freely available cross-platform +browser <em>Firefox</em> (<a href="http://www.mozilla.com/"><kbd>http://www.mozilla.com/</kbd></a>) from the +<em>Mozilla</em> Project. </li> +<li><a name="fnote3" id="fnote3" href="#revfnote3">*</a> In +GELLMU source, as in <em>LaTeX</em> source ‘<kbd>~</kbd>’ is markup for +“non-breaking space”. Note further that ASCII tilde +“<kbd>\tld;</kbd>” should not be confused with either the accent +command “<kbd>\tilde</kbd>” or the math command “<kbd>\sim</kbd>” +(rendered as ~ ) that is typically used for mathematical +operators.</li> +<li><a name="fnote4" id="fnote4" href="#revfnote4">*</a> The SGML document type definition is +more elaborately commented than its XML mirror found in the file +<kbd>xml/xgellmu.dtd</kbd>.</li> +<li><a name="fnote5" id="fnote5" href="#revfnote5">*</a> The most convenient +way to call the syntactic translator with a non-default function is to +make the first line of the source file point to the name of the +special function. For example, the function “gellmu-verblist” will +be called if the first line of the source file is “<kbd>%!verblist</kbd>”.</li> +<li><a name="fnote6" id="fnote6" href="#revfnote6">*</a> Similar intellectual property issues pertain more widely to fonts. +In particular, for this reason by default in the XHTML+MathML +output character coloring is used to cover possible font failures +for the blackboard bold, calligraphic, and fraktur math fonts; the +colors corresponding colors are, respectively, red, blue, and green.</li> +<li><a name="fnote7" id="fnote7" href="#revfnote7">*</a> Beyond that in certain situations some web browsers +appear not to deal well with empty table cells, and placing an HTML +non-breaking space in such a cell is often a good thing for that +reason. Of course, the special character ‘<kbd>~</kbd>’ for +non-breaking space in GELLMU source gives rise in HTML output to the +SGML non-breaking space character denoted with the entity reference +“&#xA0;”.</li> +</ol> +</body> +</html> + diff --git a/support/gellmu/doc/userdoc.pdf b/support/gellmu/doc/userdoc.pdf Binary files differnew file mode 100644 index 0000000000..7176a9785f --- /dev/null +++ b/support/gellmu/doc/userdoc.pdf diff --git a/support/gellmu/doc/userdoc.xhtml b/support/gellmu/doc/userdoc.xhtml new file mode 100644 index 0000000000..563864f957 --- /dev/null +++ b/support/gellmu/doc/userdoc.xhtml @@ -0,0 +1,1402 @@ +<?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="GELLMU: Introductory User's Guide" /> +<meta name="title" content="Introductory User's Guide to Regular GELLMU" /> +<meta name="subtitle" content="Version 0.8.4 release, July 2007" /> +<meta name="author" content="William F. Hammond" /> +<title>GELLMU: Introductory User's Guide</title> +</head> +<body> +<h1 class="display">Introductory User's Guide to <em>Regular</em> GELLMU</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> +<h4 class="display">revision of July 6, 2007</h4> +<div class="tableofcontents"> +<h3>Table of Contents</h3> +<dl class="tableofcontents"> +<dd>1  Introduction... <a href="#SU-1">*</a> +</dd><dd> +2  First Steps... <a href="#SU-2">*</a> +<dl><dd> +2.1  Acquiring and Installing... <a href="#SU-2.1">*</a> +</dd><dd> +2.2  Writing an Article... <a href="#SU-2.2">*</a> +</dd></dl></dd><dd> +3  Basic Markup Within Sentences... <a href="#SU-3">*</a> +</dd><dd> +4  Sectioning... <a href="#SU-4">*</a> +</dd><dd> +5  Lists... <a href="#SU-5">*</a> +</dd><dd> +6  <em>Tabular</em> Environment Emulation... <a href="#SU-6">*</a> +</dd><dd> +7  Labels, Cross References, and Anchors... <a href="#SU-7">*</a> +</dd><dd> +8  Mathematics... <a href="#SU-8">*</a> +</dd><dd> +9  Beyond this Introductory Guide... <a href="#SU-9">*</a> +</dd></dl> +</div> + +<div class="section"> +<h3>1.  <a id="SU-1"></a><a id="intro"></a>Introduction</h3> + +<p>Regular GELLMU is the part of the GELLMU Project under which +source language markup most closely resembles actual <em>LaTeX</em> source +markup. Much of the markup vocabulary is the same as that of +actual <em>LaTeX</em>. The differences — and, indeed, the whole reason +for the GELLMU Project — arises from the author's conclusion in +1998 that it would not be possible in a robust way to write rules +for actual <em>LaTeX</em> source markup so that the collection of documents +in the <em>article</em> document class prepared under such rules would +admit fully reliable automatic translation to other formats<sup><a id="revfnote1" href="#fnote1">1</a></sup>. </p> + +<p>The version 0.8 release of the GELLMU Project was the first +release providing an output stream for the XML form of HTML extended +by the World Wide Web Consortium's +<a href="http://www.w3.org/Math/">Mathematical Markup Language (MathML)</a>. +The driver script <kbd>mmkg</kbd> provides translations of regular GELLMU +articles to (1) actual <em>LaTeX</em> (and from there to DVI and +PDF), (2) classic HTML, and (3) XHTML+MathML, while the driver +script <kbd>mkg</kbd> omits XHTML+MathML. Though the +PDF output may be read on a screen, it is intended primarily +for printing by end consumers. </p> + +<p>While one could provide a landscape version of the PDF output with +live anchors for screen consumption, the XHTML+MathML version +would still be superior for screen reading since, as with ordinary +HTML, the text is re-formatted to conform naturally both to +magnification and window-resizing actions by the end user. The +quality of the rendering of mathematics in the XHTML+MathML +version is very nearly as good as that in the PDF version. </p> + +<p>Indeed the author, as an author, finds that the best venue for proof +reading what he writes is XHTML+MathML when displayed in a suitable web +browser<sup><a id="revfnote2" href="#fnote2">2</a></sup> +with larger than normal font size and narrower than normal +line length. </p> + +<p>Moreover, the XHTML+MathML version is fully compliant with the +<a href="http://www.w3.org/WAI/">Accessibility Guidelines</a> of the +<a href="http://www.w3.org/">World Wide Web Consortium</a>. </p> + +<p>This document is an introductory user guide. The relation of regular +GELLMU to the GELLMU Project overall is explained in the <a href="glman.html">Manual</a>, and +advanced user information on regular GELLMU is found there as well. +This document covers fundamentals not mentioned in the manual. It is +available in <a href="userdoc.pdf">PDF</a>, <a href="userdoc.xhtml">XHTML+MathML</a>, +and <a href="userdoc.html">classical HTML</a> versions. Online copies of +this Introductory Guide and of the Manual may be found at +<a href="http://www.tex.ac.uk/tex-archive/help/Catalogue/entries/gellmu.html +">CTAN</a> and the <a href="http://www.albany.edu/~hammond/gellmu/">GELLMU web site</a>. </p> + +<p>To use this document as an example for learning refer to its +<a href="userdoc.glm">source markup</a> and to use the project manual +as an example refer to the +<a href="glman.glm">manual's source markup</a>. +</p> +</div> + +<div class="section"> +<h3>2.  <a id="SU-2"></a><a id="firststeps"></a>First Steps</h3> + +<div class="subsection"> +<h4>2.1.  <a id="SU-2.1"></a>Acquiring and Installing</h4> + +<p>GELLMU is implemented as cross-platform free software licensed under +the GNU <a href="http://www.gnu.org/copyleft/">General Public +License</a>. Its package is available from the +<a href="http://www.ctan.org">Comprehensive TeX Archive Network</a> (CTAN) +and from the <a href="http://www.albany.edu/~hammond/gellmu/">GELLMU web site</a>. </p> + +<p>The package requires a number of other cross-platform free software +packages including GNU Emacs, <em>Perl</em>, and some standard items of +SGML/XML software, chiefly <em>Open SP</em>. Locations may be +found in the <a href="glman.html#requiredsoftware">Manual (key “<kbd>requiredsoftware</kbd>”)</a>. </p> + +<p><b>Linux:</b> The required packages are generally part of a full +GNU/<em>Linux</em> distribution. The package should be installed in +<kbd>/usr/local/gellmu</kbd> and symlinks to driver scripts should be +made from a suitable place in one's command path. </p> + +<p><b>MacOS-X and other Unix variants:</b> The only difference from +GNU/<em>Linux</em> is that some of the supporting packages may need +to be acquired and installed. </p> + +<p><b>MS Windows:</b> The best strategy is to acquire and install a +<b>full</b> <a href="http://www.cygwin.com/"><em>Cygwin</em></a> distribution. +Then proceed as with <em>Linux</em>. </p> + +<p>Additional information may be found in the <a href="glman.html">Manual</a>. +</p> +</div> + +<div class="subsection"> +<h4>2.2.  <a id="SU-2.2"></a>Writing an Article</h4> + +<p>The minimal form of a regular GELLMU article is this:</p> + +<p></p> +<dl class="verblist"> +<dd><kbd> +\documenttype{article}</kbd></dd> +<dd><kbd> +\title{Some title}</kbd></dd> +<dd><kbd> + </kbd></dd> +<dd><kbd> +\begin{document}</kbd></dd> +<dd><kbd> + </kbd></dd> +<dd><kbd> +First Paragraph.</kbd></dd> +<dd><kbd> + </kbd></dd> +<dd><kbd> +Second Paragraph.</kbd></dd> +<dd><kbd> + </kbd></dd> +<dd><kbd> +. . .</kbd></dd> +<dd><kbd> + </kbd></dd> +<dd><kbd> +\end{document}</kbd></dd> +</dl> +<p></p> + +<p>An article must begin with <kbd>\documenttype{article}</kbd>. The initial +part of an article up to the required <kbd>\begin{document}</kbd> is the +article's <em>preamble</em>, and the rest of the article is the +article's <em>body</em>. </p> + +<p>Almost everything in the <em>body</em> of an article must be part of +a paragraph. Most typically a paragraph is begun with a blank line. +Paragraphs themselves may be parts of sectional units. </p> + +<p>Beware special characters. For example ‘<kbd>%</kbd>’ converts the rest +of its line to comment status. To use ‘<kbd>%</kbd>’ in text write +“<kbd>\%</kbd>”. The special characters are with small exceptions +the same as those in <em>LaTeX</em>. Note, however, that in dealing with +multiple downstream formats any character that is not alpha-numeric +becomes potentially special. Therefore, there is a named form for +every non-alphanumeric ASCII character. For example, +“<kbd>\tld;</kbd>” is the name of ASCII ‘<kbd>~</kbd>’, +which is sometimes handy when forming a URL.<sup><a id="revfnote3" href="#fnote3">3</a></sup></p> + +<p>The names of special characters may be found by browsing the SGML +document type definition in the file <kbd>gellmu.dtd</kbd> at the top of +the distribution tree.<sup><a id="revfnote4" href="#fnote4">4</a></sup> +</p> +</div> +</div> + +<div class="section"> +<h3>3.  <a id="SU-3"></a><a id="sentences"></a>Basic Markup Within Sentences</h3> + +<p>Although there is no markup for a sentence as a unit, there is markup +for the end of a sentence or a “full stop”. The normal way to +indicate the end of a sentence is to use an ASCII period +‘<kbd>.</kbd>’ followed by either a newline or two or more blank spaces. +An end of sentence is marked up as the SGML empty element <em>eos</em>. +This is automatically generated under the condition indicated above. +For most purposes it will not matter if an ASCII period is followed +by only a single blank space, but in that case no <em>eos</em> will be +generated. </p> + +<p>The foregoing paragraph provides several instances of markup within +sentences other than <em>eos</em>. There are (1) a quoted phrase, +(2) two abbreviations, (3) a quoted character, and (4) two instances +of emphasized text. The source for that paragraph is:</p> + +<p></p> +<dl class="verblist"> +<dd><kbd> +Although there is no markup for a sentence as a unit, there is markup</kbd></dd> +<dd><kbd> +for the end of a sentence or a ``full stop''.  The normal way to</kbd></dd> +<dd><kbd> +indicate the end of a sentence is to use an \abbr{ASCII} period</kbd></dd> +<dd><kbd> +\quochar{.}  followed by either a newline or two or more blank spaces.</kbd></dd> +<dd><kbd> +An end of sentence is marked up as the \sgml empty element \emph{eos}.</kbd></dd> +<dd><kbd> +This is automatically generated under the condition indicated above.</kbd></dd> +<dd><kbd> +For most purposes it will not matter if an \ascii period is followed</kbd></dd> +<dd><kbd> +by only a single blank space, but in that case no \emph{eos} will be</kbd></dd> +<dd><kbd> +generated.</kbd></dd> +</dl> +<p></p> + +<p>The <kbd>``full stop''</kbd> is a marked up quoted phrase. The named form of a +quoted phrase is <em>quophrase</em>. The markup <kbd>\quophrase{full stop}</kbd> +is the equivalent expanded form. An abbreviation is indicated with the +command <em>abbr</em>. There is, of course, no requirement that an +abbreviation be marked up; it is merely good practice. </p> + +<p>The name of markup for emphasized text is <em>emph</em>. A common +alternate form of emphasis is called <em>bold</em>. One way the two +differ is that <em>emph</em> has order two effect, i.e., <em>emph</em> +within <em>emph</em> removes emphasis while <em>bold</em> is not permitted +within itself. Note that <em><b>bold</b></em> may be emphasized. </p> + +<p>In the cited marked up text above the instances <kbd>\sgml</kbd> and <kbd>\ascii</kbd> +are user-defined <em>newcommands</em> occurring in the preamble (or at least +before the invocations): +</p> +<dl class="verblist"> +<dd><kbd> +\newcommand{\ascii}{\abbr{ASCII}}</kbd></dd> +<dd><kbd> +\newcommand{\sgml}{\abbr{SGML}}</kbd></dd> +</dl> +<p> +The command <em>newcommand</em> is a meta-command in GELLMU source. +All <em>newcommand</em> instances are fully expanded by the syntactic +translator before it writes any output. </p> + +<p>The markup <kbd>\quochar{x}</kbd> produces a quoted character: in this case +‘<kbd>x</kbd>’. There is no compelling reason why <em>quophrase</em> could +not have been used instead of <em>quochar</em>, but it is customary in +technical documentation to use a different presentation style for +quoted characters than for quoted phrases. Beyond that for +non-traditional forms of processing it can be very useful to provide +for semantic distinctions such as the distinction between a quoted +phrase in normal discourse and a quoted string in technical discourse. +More particularly, it is significant that in some languages for +computer programming there is an important distinction between a +character and a string of unit length. Some of the markup commands +useful with technical documentation are +</p> +<div class="display"><table class="gdisplay"><tbody><tr><td> +<table><tbody> +<tr><td align="left"><b>command</b></td><td align="left"><b>example in source</b></td><td align="left"><b>example rendered</b></td></tr +><tr><td align="left"><em>quochar</em></td><td align="left"><kbd>use \quochar{\%} to comment</kbd></td><td align="left">use ‘<kbd>%</kbd>’ to comment</td></tr +><tr><td align="left"><em>quostr</em></td><td align="left"><kbd>\quostr{unsigned long num;}</kbd></td><td align="left"><kbd>unsigned long num;</kbd></td></tr +><tr><td align="left"><em>qquostr</em></td><td align="left"><kbd>type \qquostr{done} to exit</kbd></td><td align="left">type “<kbd>done</kbd>” to exit</td></tr +><tr><td align="left"><em>path</em></td><td align="left"><kbd>\path{C:\bsl;TEX\bsl;TEXMF}</kbd></td><td align="left"><kbd>C:\TEX\TEXMF</kbd></td></tr +><tr><td align="left"><em>urlanch</em></td><td align="left"><kbd>see \urlanch{userdoc.glm}  </kbd></td><td align="left">see <a href="userdoc.glm"><kbd>userdoc.glm</kbd></a></td></tr +></tbody></table> +</td></tr></tbody></table></div> +<p> +With regular <em>LaTeX</em> standard practice is to use <em>texttt</em> for the +examples just cited involving <em>quochar</em>, <em>quostr</em>, +<em>path</em>, and, apart from web-related considerations, +<em>urlanch</em>. The name <em>url</em> has been used variously in +regular <em>LaTeX</em>; therefore, <em>url</em> has not been introduced as a +name in regular GELLMU so that an author may safely use it, if +desired, as a macro name. +</p> +</div> + +<div class="section"> +<h3>4.  <a id="SU-4"></a><a id="sectioning"></a>Sectioning</h3> + +<p>Unless one wants fancy non-default behavior, one may provide +sections, subsections, and subsubsections as in <em>LaTeX</em>. Thus, +for example,</p> + +<p></p> +<dl class="verblist"> +<dd><kbd> +\documenttype{article}</kbd></dd> +<dd><kbd> +\title{Some title}</kbd></dd> +<dd><kbd> + </kbd></dd> +<dd><kbd> +\begin{document}</kbd></dd> +<dd><kbd> + </kbd></dd> +<dd><kbd> +\section{Title of first section}</kbd></dd> +<dd><kbd> +First Paragraph.</kbd></dd> +<dd><kbd> + </kbd></dd> +<dd><kbd> +Second Paragraph.</kbd></dd> +<dd><kbd> + </kbd></dd> +<dd><kbd> +. . .</kbd></dd> +<dd><kbd> + </kbd></dd> +<dd><kbd> +\section{Title of second section}</kbd></dd> +<dd><kbd> +First Paragraph.</kbd></dd> +<dd><kbd> + </kbd></dd> +<dd><kbd> +Second Paragraph.</kbd></dd> +<dd><kbd> + </kbd></dd> +<dd><kbd> +. . .</kbd></dd> +<dd><kbd> + </kbd></dd> +<dd><kbd> +\end{document}</kbd></dd> +</dl> +<p></p> + +<p>With this style of markup one does not indicate the end of a section +although there is a way described in the <a href="glman.html#secusage">Manual (key “<kbd>secusage</kbd>”)</a> to gain finer +control over sectional units. +</p> +</div> + +<div class="section"> +<h3>5.  <a id="SU-5"></a><a id="lists"></a>Lists</h3> + +<p>As with <em>LaTeX</em> GELLMU <em>article</em> provides lists with the +names <em>description</em>, <em>enumerate</em>, and <em>itemize</em>. +For example, the markup +</p> +<dl class="verblist"> +<dd><kbd> +\begin{enumerate}</kbd></dd> +<dd><kbd> +\item bird</kbd></dd> +<dd><kbd> +\item cat</kbd></dd> +<dd><kbd> +\item dog</kbd></dd> +<dd><kbd> +\end{enumerate}</kbd></dd> +</dl> +<p> +yields: +</p> +<dl> +<dd> <ol class="decimal"> +<li><p> bird</p> +</li> +<li><p> cat</p> +</li> +<li><p> dog</p> +</li> +</ol> +</dd> +</dl> +<p> +while the markup +</p> +<dl class="verblist"> +<dd><kbd> +\begin{description}</kbd></dd> +<dd><kbd> +\item[Parrot] a type of bird</kbd></dd> +<dd><kbd> +\item[Persian] a type of house cat</kbd></dd> +<dd><kbd> +\item[Pointer] a type of dog</kbd></dd> +<dd><kbd> +\end{description}</kbd></dd> +</dl> +<p> +yields: +</p> +<dl> +<dd> <dl> +<dt><b> +Parrot</b></dt> +<dd>a type of bird</dd><dt><b> +Persian</b></dt> +<dd>a type of house cat</dd><dt><b> +Pointer</b></dt> +<dd>a type of dog</dd></dl> +</dd> +</dl> +<p></p> + +<p>A list is normally part of a paragraph, but a list may occur outside +of a paragraph in a sectional unit or even at the top level of +an article's body. </p> + +<p>An <em>item</em> in a list may contain paragraphs but, as the foregoing +examples show, may contain loose text. </p> + +<p>While <em>LaTeX</em> provides an excellent construction facility for customized +lists through its <em>list</em> environment, which may be used in +conjunction with its <em>newenvironment</em> command, there is no facility +for the provision of on-the-fly markup in SGML. Therefore, the +<em>article</em> document type provides several other kinds of list. </p> + +<p>The lists called <em>menu</em> and <em>Menu</em> consist of +<em>items</em>. These lists have no item labels. They differ only +in intention for spacing in presentation formats. </p> + +<p>It often makes sense for <em>menu</em> to be used inside an <em>item</em> +of another list. Moreover, a single item <em>menu</em> will render in +either the <em>LaTeX</em> or HTML formattings as “hanging indentation”. </p> + +<p>A <em>defnlist</em> is intended to be more like the list called <em>dl</em> +in HTML than like <em>description</em>. It must consist of one or +more <em>term</em>, <em>desc</em> pairs with <em>term</em> mandatory and +<em>desc</em> optional. </p> + +<p>There are also other lists that will not be mentioned here except to +point out that when the name <em>verbatim</em> is enabled as a +metacommand, rather than as a command, by calling the syntactic +translator with a non-default function<sup><a id="revfnote5" href="#fnote5">5</a></sup> +such as <kbd>verblist</kbd> or <kbd>latex-faq</kbd>, the verbatim material +is organized as a <em>verblist</em>. </p> + +<p>For more information about lists browse the document type definitions +<kbd>gellmu.dtd</kbd> and <kbd>xml/xgellmu.dtd</kbd> being mindful that +default processing in the didactic production system sometimes does +a small amount of list manipulation between the SGML and XML versions +of an <em>article</em>. +</p> +</div> + +<div class="section"> +<h3>6.  <a id="SU-6"></a><a id="tabular"></a><em>Tabular</em> Environment Emulation</h3> + +<p>Most users having a <em>LaTeX</em> background will find that <em>tabular</em> +with column arguments limited to ‘<kbd>l</kbd>’, ‘<kbd>r</kbd>’, +‘<kbd>c</kbd>’, and ‘<kbd>p</kbd>’ is reasonably functional. +Improvement made during 2006 were made possible by the increased +availability to users of web browsers supporting version 2 of the +cascading style sheets (CSS) specification. </p> + +<p>For example, the following markup underlies a small +<a href="#mathzones"><em>lcc</em> table</a> in the section on mathematics. +</p> +<dl class="verblist"> +<dd><kbd> +\display{\begin{tabular}{lcc}</kbd></dd> +<dd><kbd> +\bold{Name} & \bold{Opener}       & \bold{Closer}   \\</kbd></dd> +<dd><kbd> +math        & \quostr{\bsl;(}     & \quostr{\bsl;)} \\</kbd></dd> +<dd><kbd> +tmath       & \quostr{\$}         & \quostr{\$}     \\</kbd></dd> +<dd><kbd> +displaymath & \quostr{\bsl\lsb;}  & \quostr{\bsl\rsb;}</kbd></dd> +<dd><kbd> +\end{tabular}}</kbd></dd> +</dl> +<p> +(In this markup <em>bsl</em> is a name for the backslash character +and <em>lsb</em>, <em>rsb</em> the names of the square brackets.)</p> + +<p>There is presently no concept of “float”. </p> + +<p>More information is available in the <a href="glman.html#tabular">Manual (key “<kbd>tabular</kbd>”)</a>. +</p> +</div> + +<div class="section"> +<h3>7.  <a id="SU-7"></a><a id="links"></a>Labels, Cross References, and Anchors</h3> + +<p>The basic idea is very simple. Use +</p> +<div class="display"><table class="gdisplay"><tbody><tr><td> +<kbd>\label{</kbd><em>mylabelkey</em><kbd>}</kbd></td></tr></tbody></table></div> +<p> +to <b>mark</b> a location that is associated with the named +label key, and use +</p> +<div class="display"><table class="gdisplay"><tbody><tr><td> +<kbd>\ref{</kbd><em>mylabelkey</em><kbd>}</kbd></td></tr></tbody></table></div> +<p> +or one of several other methods to reference that location. +The command <em>ref</em> may be regarded as the default method. +In an online version, however, it has <b>not</b> been designed to +create a selectable anchor but rather simply to indicate section +number. </p> + +<p>For example, in this document there is a label with the key +“<kbd>math</kbd>” at the beginning of the section (8) on +mathematics. The previous sentence contains a reference with +the markup <kbd>\ref{math}</kbd> to that section. This markup results +in the number of that section appearing in the first sentence. +For clarity the markup for the entire first sentence of this +paragraph is: +</p> +<dl class="verblist"> +<dd><kbd> +For example, in this document there is a label with the key</kbd></dd> +<dd><kbd> +\qquostr{math} at the beginning of the section (\ref{math}) on</kbd></dd> +<dd><kbd> +mathematics.</kbd></dd> +</dl> +<p></p> + +<p>If, on the other hand, one wants an online version to contain +a <a href="#math">selectable anchor to section 8</a> to the +section on math, then +in the preamble of the document one might place the newcommand +definition +</p> +<div class="display"><table class="gdisplay"><tbody><tr><td> +<kbd>\newcommand{\iref}[2]{\anch[iref="#1"]{#2}}</kbd></td></tr></tbody></table></div> +<p> +and then, as in the foregoing portion of this sentence use +the markup +</p> +<div class="display"><table class="gdisplay"><tbody><tr><td> +<kbd>\iref{math}{selectable anchor to section \ref{math}}</kbd> .</td></tr></tbody></table></div> +<p> +Note that this markup uses the label key “<kbd>math</kbd>” twice: +once as the first argument to the newcommand called <em>iref</em> +and once as the sole argument of the command <em>ref</em> that +itself appears in the second argument of <em>iref</em>. </p> + +<p>On the question of whether to use <em>ref</em> or one of several +other commands to make a reference, there are several considerations: +</p> +<ol class="decimal"> +<li><p> How should the reference be indicated in an online format + that will be viewed in an ebook or a web browser? </p> +</li> +<li><p> How should the reference be indicated in a typeset format + where there is neither a cursor nor the possibility of automatic + scrolling? </p> +</li> +</ol> +<p> +More details on this subject may be found in the +<a href="glman.html#labelref">Manual (key “<kbd>labelref</kbd>”)</a>. +</p> +</div> + +<div class="section"> +<h3>8.  <a id="SU-8"></a><a id="math"></a>Mathematics</h3> + +<p>GELLMU <em>article</em> provides 5 containers for mathematical +content: <em>math</em>, <em>tmath</em>, <em>displaymath</em>, <em>equation</em>, +<em>eqnarray</em>. All may be referenced by name. However, +<em>LaTeX</em>-like markup is supported: +<a id="mathzones"></a> +</p> +<div class="display"><table class="gdisplay"><tbody><tr><td> +<table><tbody> +<tr><td align="left"><b>Name</b></td><td align="center"><b>Opener</b></td><td align="center"><b>Closer</b></td></tr +><tr><td align="left">math</td><td align="center"><kbd>\(</kbd></td><td align="center"><kbd>\)</kbd></td></tr +><tr><td align="left">tmath</td><td align="center"><kbd>$</kbd></td><td align="center"><kbd>$</kbd></td></tr +><tr><td align="left">displaymath</td><td align="center"><kbd>\[</kbd></td><td align="center"><kbd>\]</kbd></td></tr +></tbody></table> +</td></tr></tbody></table></div> +<p></p> + +<p>The containers <em>math</em> and <em>tmath</em> are essentially +equivalent non-displayed containers. The current <em>LaTeX</em> formatter +provides a tiny amount of extra horizontal space around <em>math</em> +but not around <em>tmath</em>. </p> + +<p>Just as with ordinary <em>LaTeX</em> there can be difficulty locating +a missing ‘<kbd>$</kbd>’ if one uses these for <em>tmath</em>. Unbalanced +‘<kbd>$</kbd>’ characters usually lead the syntactic translator to +complain (correctly, though not with as much user-friendliness as one +might wish) about not being able to balance a brace. In this case +if <em>tmath</em> is seen in the displayed surrounding text, a missing +‘<kbd>$</kbd>’ is likely. </p> + +<p>MathML rendering support (with MathML's presentation markup) in HTML +versions, i.e., the modern XML form of HTML extended with MathML, is +new in the summer of 2004. </p> + +<p>A program to generate an output stream providing content-level MathML +markup, i.e., semantic markup transparent for computer algebra +systems, has not yet been written. </p> + +<p>Those who use mathematics may find the following illustrations +instructive. </p> + +<p>The markup +</p> +<dl class="verblist"> +<dd><kbd> +Just as with \tex; or \latex; it is easy to provide a mathematical</kbd></dd> +<dd><kbd> +formula, such as $y = x^3/(x^2 + 1)$\aoc either inline or displayed.</kbd></dd> +</dl> +<p> +produces: +</p> +<dl> +<dd> Just as with <em>TeX</em> or <em>LaTeX</em> it is easy to provide a mathematical +formula, such as <math xmlns="http://www.w3.org/1998/Math/MathML" mode="inline" +><mi>y</mi><mo>=</mo><msup><mi>x</mi><mn>3</mn></msup +><mo stretchy="true" lspace="0.3em" rspace="0.3em">⁄</mo><mfenced open="(" close =")" +><mrow><msup><mi>x</mi><mn>2</mn></msup +><mo>+</mo><mn>1</mn></mrow></mfenced +></math +>, either inline or displayed. </dd> +</dl> +<p></p> + +<p>This markup +</p> +<dl class="verblist"> +<dd><kbd> +Here the same formula is displayed.</kbd></dd> +<dd><kbd> +\[ y = \frac{x^3}{x^2 + 1} \eos\]</kbd></dd> +</dl> +<p> +yields: +</p> +<dl> +<dd> Here the same formula is displayed. + +<math xmlns="http://www.w3.org/1998/Math/MathML" display="block" mode="display" +><mi>y</mi><mo>=</mo><mrow><mfrac +><mrow><msup><mi>x</mi><mn>3</mn></msup +></mrow +><mrow><msup><mi>x</mi><mn>2</mn></msup +><mo>+</mo><mn>1</mn></mrow +></mfrac></mrow +><mtext>.</mtext +></math> +</dd> +</dl> +<p> +The <em>eos</em> corresponds to an empty SGML element for “end of +sentence” (or “full stop”). Normally one simply uses ‘<kbd>.</kbd>’, +but inside a displayed math zone there is semantic-level risk of +confusion with various possible uses of ‘<kbd>.</kbd>’ as a mathematical +symbol. </p> + +<p>Markup: +</p> +<dl class="verblist"> +<dd><kbd> +The square root of a compound fraction:</kbd></dd> +<dd><kbd> +\[ \sqrt{\frac{\frac{a}{b}}{\frac{c}{d}}} \eos \]</kbd></dd> +</dl> +<p> +Rendered: +</p> +<dl> +<dd> The square root of a compound fraction: + +<math xmlns="http://www.w3.org/1998/Math/MathML" display="block" mode="display" +><msqrt><mfrac +><mfrac +><mi>a</mi><mi>b</mi></mfrac +><mfrac +><mi>c</mi><mi>d</mi></mfrac +></mfrac +></msqrt +><mtext>.</mtext +></math> +</dd> +</dl> +<p></p> + +<p>In the current XHTML+MathML formatting by default radical signs in +source markup are converted by default to fractional exponents because +of an intellectual property issue with fonts available for use by the +open source <em>Mozilla</em> browser and its spinoffs including +<em>Firefox</em>, <em>Galeon</em>, and <em>Nautilus</em>.<sup><a id="revfnote6" href="#fnote6">6</a></sup></p> + +<p>Using the markup for numbered equations +</p> +<dl class="verblist"> +<dd><kbd> +The quadratic equation</kbd></dd> +<dd><kbd> +\begin{equation} a x^2 + b x + c = 0 \end{equation}</kbd></dd> +<dd><kbd> +has roots</kbd></dd> +<dd><kbd> +\begin{equation}</kbd></dd> +<dd><kbd> + x = \frac{-b \pm \sqrt{b^2 - 4 a c}}{2 a} \ \eos</kbd></dd> +<dd><kbd> +\end{equation}</kbd></dd> +</dl> +<p> +one obtains the rendering: +</p> +<dl> +<dd> The quadratic equation +<a id="EqnKey-1"></a> +<math xmlns="http://www.w3.org/1998/Math/MathML" display="block" mode="display" +><mtable><mtr class="labeled" id="EqnAutoEqnKey-1"><mtd><mtext>(1)</mtext></mtd +><mtd><mrow><mi>a</mi><msup><mi>x</mi><mn>2</mn></msup +><mo>+</mo><mi>b</mi><mi>x</mi><mo>+</mo><mi>c</mi><mo>=</mo><mn>0</mn></mrow></mtd></mtr></mtable></math +> +has roots +<a id="EqnKey-2"></a> +<math xmlns="http://www.w3.org/1998/Math/MathML" display="block" mode="display" +><mtable><mtr class="labeled" id="EqnAutoEqnKey-2"><mtd><mtext>(2)</mtext></mtd +><mtd><mrow><mi>x</mi><mo>=</mo><mrow><mfrac +><mrow><mo>−</mo><mi>b</mi><mo>±</mo><msqrt><mrow><msup><mi>b</mi><mn>2</mn></msup +><mo>−</mo><mn>4</mn><mi>a</mi><mi>c</mi></mrow></msqrt +></mrow +><mrow><mn>2</mn><mi>a</mi></mrow +></mfrac></mrow +><mspace width="0.6em"/><mtext>.</mtext +></mrow></mtd></mtr></mtable></math +></dd> +</dl> +<p></p> + +<p><b>Rule for subscripts and superscripts:</b> A subscript or +superscript must be braced if keyboarding it involves more than +one character. Thus, one <em>may</em> use <kbd>$C^2$</kbd> or <kbd>$C^{2}$</kbd> +to produce <math xmlns="http://www.w3.org/1998/Math/MathML" mode="inline" +><msup><mi>C</mi><mn>2</mn></msup +></math +>, but one <em>must</em> use <kbd>$C^{\infty}$</kbd> to +generate <math xmlns="http://www.w3.org/1998/Math/MathML" mode="inline" +><msup><mi>C</mi><mi>∞</mi></msup +></math +>. </p> + +<p>The Taylor series of the <em>exponential</em> function is + +<math xmlns="http://www.w3.org/1998/Math/MathML" display="block" mode="display" +><msup><mi>e</mi><mi>t</mi></msup +><mo>=</mo><mrow><munderover><mo>∑</mo><mrow><mi>k</mi><mo>=</mo><mn>0</mn></mrow><mi>∞</mi></munderover><mrow><mspace width="0.3em"/><mfrac +><mrow><msup><mi>t</mi><mi>k</mi></msup +></mrow +><mrow><mi>k</mi><mo>!</mo></mrow +></mfrac +></mrow></mrow +><mspace width="0.6em"/><mtext>.</mtext +></math> + +Note here that the <em>sum</em> markup <kbd>\sum</kbd> requires a formal +terminator <kbd>\sum:</kbd> (likewise with <kbd>\int</kbd> for integral and <kbd>\prod</kbd> +for product). +</p> +<dl class="verblist"> +<dd><kbd> +\[ e^t = \sum_{k = 0}^{\infty} \, \frac{t^k}{k!} \sum: \ \eos \]</kbd></dd> +</dl> +<p></p> + +<p>The markup +</p> +<dl class="verblist"> +<dd><kbd> +The continued fraction expansion of the \emph{golden mean}:</kbd></dd> +<dd><kbd> +\[\frac{1 + \sqrt{5}}{2} =</kbd></dd> +<dd><kbd> +     1 + \frac{1}{1+\frac{1}{1+\frac{1}{1+\frac{1}{1+\ldots;}}}} \eos \]</kbd></dd> +</dl> +<p> +produces: +</p> +<dl> +<dd> The continued fraction expansion of the <em>golden mean</em>: + +<math xmlns="http://www.w3.org/1998/Math/MathML" display="block" mode="display" +><mrow><mfrac +><mrow><mn>1</mn><mo>+</mo><msqrt><mn>5</mn></msqrt +></mrow +><mn>2</mn></mfrac></mrow +><mo>=</mo><mn>1</mn><mo>+</mo><mrow><mfrac +><mn>1</mn><mrow><mn>1</mn><mo>+</mo><mrow><mfrac +><mn>1</mn><mrow><mn>1</mn><mo>+</mo><mrow><mfrac +><mn>1</mn><mrow><mn>1</mn><mo>+</mo><mrow><mfrac +><mn>1</mn><mrow><mn>1</mn><mo>+</mo><mi>…</mi></mrow +></mfrac></mrow +></mrow +></mfrac></mrow +></mrow +></mfrac></mrow +></mrow +></mfrac></mrow +><mtext>.</mtext +></math> +</dd> +</dl> +<p> +while the markup +</p> +<dl class="verblist"> +<dd><kbd> +Mixed function application and multiplication:</kbd></dd> +<dd><kbd> +\[ {\func{sin}\aF;{ax}}\itimes;{\func{cos}\aF;{bx}} \eos \]</kbd></dd> +</dl> +<p> +yields +</p> +<dl> +<dd> Mixed function application and multiplication: + +<math xmlns="http://www.w3.org/1998/Math/MathML" display="block" mode="display" +><mrow><mrow><mspace width="0.2em"/><mi>sin</mi></mrow><mo class="invisible">⁡</mo><mrow><mi>a</mi><mi>x</mi></mrow></mrow><mo class="invisible">⁢</mo><mrow><mrow><mspace width="0.2em"/><mi>cos</mi></mrow><mo class="invisible">⁡</mo><mrow><mi>b</mi><mi>x</mi></mrow></mrow><mtext>.</mtext +></math> +</dd> +</dl> +<p></p> + +<p>Markup: +</p> +<dl class="verblist"> +<dd><kbd> +Newton's binomial series:</kbd></dd> +<dd><kbd> +\[ (1 + t)^r = \sum_{k=0}^{\infty} \,</kbd></dd> +<dd><kbd> +  \frac{r(r - 1)(r - 2)\ldots(r - k + 1)}{k!}\, t^k \sum: \eos \]</kbd></dd> +</dl> +<p> +rendering: +</p> +<dl> +<dd> Newton's binomial series: + +<math xmlns="http://www.w3.org/1998/Math/MathML" display="block" mode="display" +><msup><mfenced open="(" close =")" +><mrow><mn>1</mn><mo>+</mo><mi>t</mi></mrow></mfenced +><mi>r</mi></msup +><mo>=</mo><mrow><munderover><mo>∑</mo><mrow><mi>k</mi><mo>=</mo><mn>0</mn></mrow><mi>∞</mi></munderover><mrow><mspace width="0.3em"/><mfrac +><mrow><mi>r</mi><mfenced open="(" close =")" +><mrow><mi>r</mi><mo>−</mo><mn>1</mn></mrow></mfenced +><mfenced open="(" close =")" +><mrow><mi>r</mi><mo>−</mo><mn>2</mn></mrow></mfenced +><mi>…</mi><mfenced open="(" close =")" +><mrow><mi>r</mi><mo>−</mo><mi>k</mi><mo>+</mo><mn>1</mn></mrow></mfenced +></mrow +><mrow><mi>k</mi><mo>!</mo></mrow +></mfrac +><mspace width="0.3em"/><msup><mi>t</mi><mi>k</mi></msup +></mrow></mrow +><mtext>.</mtext +></math> +</dd> +</dl> +<p></p> + +<p>Markup: +</p> +<dl class="verblist"> +<dd><kbd> +A differential equation:</kbd></dd> +<dd><kbd> +\[ D^2 y - 3 x (D y)^2 = x \func{cos} x \ \eos \]</kbd></dd> +</dl> +<p> +rendering: +</p> +<dl> +<dd> A differential equation: + +<math xmlns="http://www.w3.org/1998/Math/MathML" display="block" mode="display" +><msup><mi>D</mi><mn>2</mn></msup +><mi>y</mi><mo>−</mo><mn>3</mn><mi>x</mi><msup><mfenced open="(" close =")" +><mrow><mi>D</mi><mi>y</mi></mrow></mfenced +><mn>2</mn></msup +><mo>=</mo><mi>x</mi><mrow><mspace width="0.2em"/><mi>cos</mi></mrow><mi>x</mi><mspace width="0.6em"/><mtext>.</mtext +></math> +</dd> +</dl> +<p></p> + +<p>The statement of Stokes's Theorem in space + +<math xmlns="http://www.w3.org/1998/Math/MathML" display="block" mode="display" +><mrow><mo>∫</mo><mrow><msub><mo>∫</mo><mi>S</mi></msub><mrow><mspace width="0.3em"/><mfenced open="(" close =")" +><mrow><mi mathvariant="bold" fontweight="bold" fontstyle="normal">curl</mi><mspace width="0.3em"/><mi mathvariant="bold" fontweight="bold" fontstyle="normal">F</mi><mspace width="0.3em"/><mo>·</mo><mspace width="0.3em"/><mi mathvariant="bold" fontweight="bold" fontstyle="normal">N</mi></mrow></mfenced +><mspace width="0.3em"/><mi>d</mi><mi>σ</mi></mrow></mrow +></mrow +><mo>=</mo><mrow><msub><mo>∫</mo><mrow><mi>∂</mi><mi>S</mi></mrow></msub><mrow><mspace width="0.3em"/><mfenced open="(" close =")" +><mrow><mi mathvariant="bold" fontweight="bold" fontstyle="normal">F</mi><mspace width="0.3em"/><mo>·</mo><mspace width="0.3em"/><mi mathvariant="bold" fontweight="bold" fontstyle="normal">T</mi></mrow></mfenced +><mspace width="0.3em"/><mi>d</mi><mi>s</mi></mrow></mrow +><mspace width="0.3em"/><mtext>.</mtext +></math> + +may be generated by the markup +</p> +<dl class="verblist"> +<dd><kbd> +\[ \int\int_S \, (\mbox{\bold{curl}}</kbd></dd> +<dd><kbd> + \, \regch{\bold{F}} \,\cdot\, \regch{\bold{N}})\, d\sigma;</kbd></dd> +<dd><kbd> +\int:\int:</kbd></dd> +<dd><kbd> + = </kbd></dd> +<dd><kbd> +\int_{\partial S} \, (\regch{\bold{F}}</kbd></dd> +<dd><kbd> +\,\cdot\, \regch{\bold{T}})\, ds \int:\, \eos \]</kbd></dd> +</dl> +<p> +Note that each <kbd>\int</kbd> integral opener must be followed eventually +by a <kbd>\int:</kbd> closer (or braces could be used, i.e., <kbd>\int{ ... }</kbd>, +or <kbd>\begin{int}</kbd> … <kbd>\end{int}</kbd> also could be used. </p> + +<p>The branched definition of the absolute value of a real number may +be marked up with +</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}} \ \eos \]</kbd></dd> +</dl> +<p> +to yield + +<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 +><mspace width="0.6em"/><mtext>.</mtext +></math> +</p> + +<p>The <em>LaTeX</em>-like command <em>mathbf</em> is new in GELLMU +<em>article</em>. It may only be used in math. The command +<em>bold</em>, which indicates bold-style emphasis, parallel to +<em>strong</em> in HTML and <em>textbf</em> in <em>LaTeX</em>, may be +used inside mathematical content as well as outside. However, +<em>bold</em> may not contain math-special symbols such as that given by +<kbd>\alpha</kbd>, while <em>mathbf</em> may. </p> + +<p>A certain amount of attention to semantics is required in order to +have robust generation of the XHTML+MathML output. An absolutely +basic part of this is having unambiguous determination of what is a +single symbol. By long convention in <em>TeX</em> the string “abcd” in +math is understood as the product (in whatever sense of “product”) +of four symbols. If a string with more than one character — for +example, “Hom” — is to be a single symbol, it may be marked up +with <em>mbox</em> or, in GELLMU source, be assigned a symbol name +having custom print representation using <em>mathsym</em> in the preamble. +In GELLMU source <em>mathbf</em> should only contain a single symbol. + + +</p> + +<p>The markup +</p> +<dl class="verblist"> +<dd><kbd> +\display{$\nabla\times\vec{\mbox{\bold{B}}}$</kbd></dd> +<dd><kbd> +         \ with ``mbox'' and ``bold'' versus</kbd></dd> +<dd><kbd> +         \ $\nabla\times\vec{\mathbf{B}}$ \ with ``mathbf''\,.}</kbd></dd> +</dl> +<p> +produces +</p> +<div class="display"><table class="gdisplay"><tbody><tr><td> +<math xmlns="http://www.w3.org/1998/Math/MathML" mode="inline" +><mi>∇</mi><mo lspace="0.25em" rspace="0.25em">×</mo><mover accent="true"><mi mathvariant="bold" fontweight="bold" fontstyle="normal">B</mi><mo>⇀</mo></mover +></math +> + with “mbox” and “bold” versus + <math xmlns="http://www.w3.org/1998/Math/MathML" mode="inline" +><mi>∇</mi><mo lspace="0.25em" rspace="0.25em">×</mo><mover accent="true"><mi mathvariant="bold-italic" fontweight="bold">B</mi +><mo>⇀</mo></mover +></math +> with “mathbf”.</td></tr></tbody></table></div> +<p></p> + +<p>Diagrams are done using <em>array</em>. They must, therefore, be +rectangular. The markup +</p> +<dl class="verblist"> +<dd><kbd> +\newcommand{\ra}{\rightarrow}</kbd></dd> +<dd><kbd> +\newcommand{\da}{\downarrow}</kbd></dd> +<dd><kbd> +\[ \begin{array}{ccccccccc}</kbd></dd> +<dd><kbd> +0 & \ra  & A'  & \ra  & A   & \ra &  A''  & \ra & 0 \\</kbd></dd> +<dd><kbd> +~ &      & \da &      & \da &     & \da   &     &   \\</kbd></dd> +<dd><kbd> +0 & \ra  & B'  & \ra  & B   & \ra &  B''  & \ra & 0</kbd></dd> +<dd><kbd> +\end{array} \]</kbd></dd> +</dl> +<p> +yields + +<math xmlns="http://www.w3.org/1998/Math/MathML" display="block" mode="display" +><mtable +><mtr><mtd columnalign="center"><mn>0</mn></mtd +><mtd columnalign="center"><mo>→</mo></mtd +><mtd columnalign="center"><msup><mi>A</mi><mo>′</mo></msup +></mtd +><mtd columnalign="center"><mo>→</mo></mtd +><mtd columnalign="center"><mi>A</mi></mtd +><mtd columnalign="center"><mo>→</mo></mtd +><mtd columnalign="center"><msup><mi>A</mi><mo>′′</mo></msup +></mtd +><mtd columnalign="center"><mo>→</mo></mtd +><mtd columnalign="center"><mn>0</mn></mtd +></mtr><mtr><mtd columnalign="center"><mspace width="0.6em"/></mtd +><mtd columnalign="center"></mtd +><mtd columnalign="center"><mo>↓</mo></mtd +><mtd columnalign="center"></mtd +><mtd columnalign="center"><mo>↓</mo></mtd +><mtd columnalign="center"></mtd +><mtd columnalign="center"><mo>↓</mo></mtd +><mtd columnalign="center"></mtd +><mtd columnalign="center"></mtd +></mtr><mtr><mtd columnalign="center"><mn>0</mn></mtd +><mtd columnalign="center"><mo>→</mo></mtd +><mtd columnalign="center"><msup><mi>B</mi><mo>′</mo></msup +></mtd +><mtd columnalign="center"><mo>→</mo></mtd +><mtd columnalign="center"><mi>B</mi></mtd +><mtd columnalign="center"><mo>→</mo></mtd +><mtd columnalign="center"><msup><mi>B</mi><mo>′′</mo></msup +></mtd +><mtd columnalign="center"><mo>→</mo></mtd +><mtd columnalign="center"><mn>0</mn></mtd +></mtr></mtable +></math> + + +</p> +<dl> +<dd> <b>Comments about <em>array</em>, <em>eqnarray</em>, <em>tabular</em></b> +<ol class="decimal"> +<li><p> In this markup note the appearance of the character ‘<kbd>~</kbd>’ at +the beginning of the second row of the array. The modular design of +the didactic production system requires that the syntactic translator +may only deal with markup syntax. The ‘<kbd>~</kbd>’, which is markup +in GELLMU source as in <em>LaTeX</em> for “non-breaking space”, in the +first cell of the second row serves to keep the first cell from being +empty. There is a technical error in the SGML output of the +syntactic translator when the first cell in an <em>array</em> or +<em>tabular</em> row is empty unless there is an explicit opentag for +the first cell. The technical error will trigger a validation error +though it should not interfere with the generation of a correct parsed +output.<sup><a id="revfnote7" href="#fnote7">7</a></sup> +</p> +</li> +<li><p> Also in the foregoing markup note that the <em>LaTeX</em>-like use of the +character ‘<kbd>&</kbd>’ as the introducer of a new cell must in GELLMU +source be followed by whitespace. Otherwise there is risk of +confusion with the alternative markup use of ‘<kbd>&</kbd>’ in GELLMU +source (though not in <em>LaTeX</em> source) to initiate an SGML entity +reference. </p> +</li> +</ol> +</dd> +</dl> +<p></p> + +<p>There is multiscript support. The command <em>mscript</em> takes 5 +arguments. The first is its base. The script order is counter-clockwise +beginning with upper-left. For example, + +<math xmlns="http://www.w3.org/1998/Math/MathML" display="block" mode="display" +><mmultiscripts><mi mathvariant="bold-italic" fontweight="bold">C</mi +><mrow><mn>5</mn><mo>+</mo></mrow><mn>2</mn><mprescripts/><mn>2</mn><mn>14</mn></mmultiscripts +><mspace width="1.8em"/><mmultiscripts><mi>Hom</mi><mi>c</mi><mi>d</mi><mprescripts/><mi>b</mi><mi>a</mi></mmultiscripts +><mfenced open="(" close =")" +><mrow><mi>X</mi><mo>,</mo><mi>Y</mi></mrow></mfenced +></math> + +is produced by +</p> +<dl class="verblist"> +<dd><kbd> +\[</kbd></dd> +<dd><kbd> +\mscript{\mathbf{C}}{14}{2}{5+}{2}\quad</kbd></dd> +<dd><kbd> +\mscript{\mbox{Hom}}{a}{b}{c}{d}(X,Y)</kbd></dd> +<dd><kbd> +\]</kbd></dd> +</dl> +<p></p> + +<p><em>AMSMath</em>-like overset and underset: <kbd>\overset{A}{B}</kbd> + then <kbd>\underset{A}{B}</kbd> + +<math xmlns="http://www.w3.org/1998/Math/MathML" display="block" mode="display" +><mover><mi>B</mi><mi>A</mi></mover +><mspace width="1.8em"/><munder><mi>B</mi><mi>A</mi></munder +></math> +</p> + +<p>The command <em>overset</em> is the <em>AMSMath</em> replacement in <em>LaTeX</em> +for <em>LaTeX</em>'s native <em>stackrel</em>. </p> + +<p></p> +<dl class="verblist"> +<dd><kbd> +A map may be labeled using \emph{overset}:</kbd></dd> +<dd><kbd> +\[ X \overset{f}{\longrightarrow} Y \]</kbd></dd> +<dd><kbd> +or using \emph{underset}:</kbd></dd> +<dd><kbd> +\[ X \underset{f}{\longrightarrow} Y \]</kbd></dd> +</dl> +<p> +</p> +<dl> +<dd> A map may be labeled using <em>overset</em>: + +<math xmlns="http://www.w3.org/1998/Math/MathML" display="block" mode="display" +><mi>X</mi><mover><mo>→</mo><mi>f</mi></mover +><mi>Y</mi></math> + +or using <em>underset</em>: + +<math xmlns="http://www.w3.org/1998/Math/MathML" display="block" mode="display" +><mi>X</mi><munder><mo>→</mo><mi>f</mi></munder +><mi>Y</mi></math> +</dd> +</dl> +<p></p> + +<p>Binary or pseudo-binary operators: + +<math xmlns="http://www.w3.org/1998/Math/MathML" display="block" mode="display" +><mtext +>vee:</mtext +><mspace width="0.6em"/><mo>∨</mo><mspace width="1.8em"/><mtext +>setminus:</mtext +><mspace width="0.6em"/><mo>∖</mo><mspace width="1.8em"/><mtext +>ll:</mtext +><mspace width="0.6em"/><mo>≪</mo><mspace width="1.8em"/><mtext +>gg:</mtext +><mspace width="0.6em"/><mo>≫</mo><mspace width="1.8em"/><mtext +>approx:</mtext +><mspace width="0.6em"/><mo>≊</mo><mspace width="1.8em"/><mtext +>asymp:</mtext +><mspace width="0.6em"/><mo>≈</mo><mspace width="1.8em"/></math> + + +<math xmlns="http://www.w3.org/1998/Math/MathML" display="block" mode="display" +><mtext +>rightarrow:</mtext +><mspace width="0.6em"/><mo>→</mo><mspace width="1.8em"/><mtext +>leftarrow:</mtext +><mspace width="0.6em"/><mo>←</mo><mspace width="1.8em"/><mtext +>implies:</mtext +><mspace width="0.6em"/><mo>⇒</mo><mspace width="1.8em"/><mtext +>revimplies:</mtext +><mspace width="0.6em"/><mo>⇐</mo><mspace width="1.8em"/><mtext +>iff:</mtext +><mspace width="0.6em"/><mo>⇔</mo><mspace width="1.8em"/></math> +</p> + +<p>Other operators: + +<math xmlns="http://www.w3.org/1998/Math/MathML" display="block" mode="display" +><mtext +>uparrow:</mtext +><mspace width="0.6em"/><mo>↑</mo><mspace width="1.8em"/><mtext +>downarrow:</mtext +><mspace width="0.6em"/><mo>↓</mo><mspace width="1.8em"/><mtext +>triangle:</mtext +><mspace width="0.6em"/><mo>▵</mo><mspace width="1.8em"/><mtext +>abuts:</mtext +><mspace width="0.6em"/><mo>⇒</mo><mspace width="1.8em"/></math> +</p> + +<p>The command <em>vect</em> is for vector generation. Its usage is: +</p> +<div class="display"><table class="gdisplay"><tbody><tr><td> +<kbd>\vect[</kbd><em>open-close-separator spec</em><kbd>]{</kbd><em>coordinate</em><kbd>}</kbd> …</td></tr></tbody></table></div> +<p> +Thus, the markup <kbd>\vect{x}{y}{z}</kbd> produces <math xmlns="http://www.w3.org/1998/Math/MathML" mode="inline" +><mfenced><mi>x</mi><mi>y</mi><mi>z</mi></mfenced +></math +>. +On the other hand the markup <kbd>\vect[]{x}{y}{z}</kbd> produces +<math xmlns="http://www.w3.org/1998/Math/MathML" mode="inline" +><mfenced open="" close="" separators=""><mi>x</mi><mi>y</mi><mi>z</mi></mfenced +></math +>. This might be useful, for example, in +providing reasonably semantic (but visibly traditional) markup for a +tensor field. For example + +<math xmlns="http://www.w3.org/1998/Math/MathML" display="block" mode="display" +><msubsup><mi>T</mi><mfenced open="" close="" separators=""><mrow><msub><mi>j</mi><mn>1</mn></msub +></mrow><mrow><msub><mi>j</mi><mn>2</mn></msub +></mrow><mi>…</mi><mrow><msub><mi>j</mi><mi>q</mi></msub +></mrow></mfenced +><mfenced open="" close="" separators=""><mrow><msub><mi>i</mi><mn>1</mn></msub +></mrow><mrow><msub><mi>i</mi><mn>2</mn></msub +></mrow><mi>…</mi><mrow><msub><mi>i</mi><mi>p</mi></msub +></mrow></mfenced +></msubsup +></math> + +When <em>vect</em>'s option is empty, vector opener, closer, and coordinate +separators are all nil. <em>vect</em> might be used to provide the stylized, +though semantically dubious, +inner product markup <kbd>\vect[<>;]{v}{w}</kbd> yielding + +<math xmlns="http://www.w3.org/1998/Math/MathML" display="block" mode="display" +><mfenced open="<" close=">" separators=";"><mi>v</mi><mi>w</mi></mfenced +><mspace width="0.6em"/><mtext>,</mtext></math> + +or with the markup <kbd>\vect[\lsb;\rsb;:]{a}{b}{c}</kbd> +to customize notation for the homogeneous coordinate triple +representing a point of <math xmlns="http://www.w3.org/1998/Math/MathML" mode="inline" +><msup><mi mathvariant="bold-italic" fontweight="bold">P</mi +><mn>2</mn></msup +></math +>: + +<math xmlns="http://www.w3.org/1998/Math/MathML" display="block" mode="display" +><mfenced open="[" close="]" separators=":"><mi>a</mi><mi>b</mi><mi>c</mi></mfenced +><mspace width="0.6em"/><mtext>.</mtext +></math> +</p> + +<p>Leray's spectral sequence: +</p> +<dl> +<dd> If + +<math xmlns="http://www.w3.org/1998/Math/MathML" display="block" mode="display" +><mi>X</mi><mspace width="0.6em"/><mo>→</mo><mspace width="0.6em"/><mi>B</mi></math> + +with fibre <math xmlns="http://www.w3.org/1998/Math/MathML" mode="inline" +><mi>F</mi></math +>, then + +<math xmlns="http://www.w3.org/1998/Math/MathML" display="block" mode="display" +><mrow><mmultiscripts><mi>E</mi><mn>2</mn><mfenced open="" close="" separators=""><mi>p</mi><mi>q</mi></mfenced +></mmultiscripts +><mo>=</mo><msup><mi>H</mi><mi>p</mi></msup +><mo class="invisible">⁡</mo><mfenced open="(" close =")" +><mrow><mi>B</mi><mo>,</mo><msup><mi>H</mi><mi>q</mi></msup +><mo class="invisible">⁡</mo><mfenced open="(" close =")" +><mi>F</mi></mfenced +></mrow></mfenced +></mrow><mo>⇒</mo><msup><mi>H</mi><mi>*</mi></msup +><mo class="invisible">⁡</mo><mfenced open="(" close =")" +><mi>X</mi></mfenced +><mspace width="0.6em"/><mtext>.</mtext +></math> +</dd> +</dl> +<p> +is produced by +</p> +<dl class="verblist"> +<dd><kbd> +If</kbd></dd> +<dd><kbd> +\[ X \ \longrightarrow \  B \]</kbd></dd> +<dd><kbd> +with fibre $F$\@, then </kbd></dd> +<dd><kbd> +\[ {\mscript{E}{}{}{2}{\vect[]{p}{q}} = H^p\aF(B, H^q\aF(F))}</kbd></dd> +<dd><kbd> +   \abuts H^{*}\aF(X) \ \eos \]</kbd></dd> +</dl> +<p> +In this markup the command <kbd>\aF</kbd>, is not strictly necessary. +It provides a deliberate way to indicate that, in the second +instance above, the symbol <math xmlns="http://www.w3.org/1998/Math/MathML" mode="inline" +><mi>X</mi></math +> is argument-like in relation to +the symbol <math xmlns="http://www.w3.org/1998/Math/MathML" mode="inline" +><msup><mi>H</mi><mi>*</mi></msup +></math +>. In MathML rendering <em>aF</em> gives rise to +presentation-level MathML's invisible operator <em>ApplyFunction</em>. +</p> +</div> + +<div class="section"> +<h3>9.  <a id="SU-9"></a>Beyond this Introductory Guide</h3> + +<p>More information about GELLMU is available in the <a href="glman.html">Manual</a>. +Some examples of topics to be found there include: +</p> +<ul> +<li><p> Inclusion of graphic objects: <a href="glman.html#graphics">Manual (key “<kbd>graphics</kbd>”)</a>. </p> +</li> +<li><p> Equations and equation arrays: <a href="glman.html#eqn">Manual (key “<kbd>eqn</kbd>”)</a>. </p> +</li> +<li><p> Emulation of <em>LaTeX</em>'s <em>newtheorem</em> environments: <a href="glman.html#assert">Manual (key “<kbd>assert</kbd>”)</a>. </p> +</li> +<li><p> Emulation of <em>LaTeX</em>'s counters: <a href="glman.html#counters">Manual (key “<kbd>counters</kbd>”)</a>. </p> +</li> +<li><p> The flowchart for regular GELLMU processing: <a href="glman.html#flow">Manual (key “<kbd>flow</kbd>”)</a>. </p> +</li> +</ul> +<p></p> + +<p>The author tries to keep fresh information on the <a href="http://www.albany.edu/~hammond/gellmu/">GELLMU web site</a>. +</p> +</div> +<hr /> +<h3>Footnotes</h3> +<ol> +<li><a id="fnote1" href="#revfnote1">*</a> This should not be construed to mean, however, that standard <em>LaTeX</em> +processing could not incorporate this type of source markup at some +time in the future. </li> +<li><a id="fnote2" href="#revfnote2">*</a> The author prefers the freely available cross-platform +browser <em>Firefox</em> (<a href="http://www.mozilla.com/"><kbd>http://www.mozilla.com/</kbd></a>) from the +<em>Mozilla</em> Project. </li> +<li><a id="fnote3" href="#revfnote3">*</a> In +GELLMU source, as in <em>LaTeX</em> source ‘<kbd>~</kbd>’ is markup for +“non-breaking space”. Note further that ASCII tilde +“<kbd>\tld;</kbd>” should not be confused with either the accent +command “<kbd>\tilde</kbd>” or the math command “<kbd>\sim</kbd>” +(rendered as <math xmlns="http://www.w3.org/1998/Math/MathML" mode="inline" +><mo>∼</mo></math +>) that is typically used for mathematical +operators.</li> +<li><a id="fnote4" href="#revfnote4">*</a> The SGML document type definition is +more elaborately commented than its XML mirror found in the file +<kbd>xml/xgellmu.dtd</kbd>.</li> +<li><a id="fnote5" href="#revfnote5">*</a> The most convenient +way to call the syntactic translator with a non-default function is to +make the first line of the source file point to the name of the +special function. For example, the function “gellmu-verblist” will +be called if the first line of the source file is “<kbd>%!verblist</kbd>”.</li> +<li><a id="fnote6" href="#revfnote6">*</a> Similar intellectual property issues pertain more widely to fonts. +In particular, for this reason by default in the XHTML+MathML +output character coloring is used to cover possible font failures +for the blackboard bold, calligraphic, and fraktur math fonts; the +colors corresponding colors are, respectively, red, blue, and green.</li> +<li><a id="fnote7" href="#revfnote7">*</a> Beyond that in certain situations some web browsers +appear not to deal well with empty table cells, and placing an HTML +non-breaking space in such a cell is often a good thing for that +reason. Of course, the special character ‘<kbd>~</kbd>’ for +non-breaking space in GELLMU source gives rise in HTML output to the +SGML non-breaking space character denoted with the entity reference +“&#xA0;”.</li> +</ol> +</body> +</html> + |
