path: root/support/gellmu/README

                          GELLMU version 0.8

                          William F. Hammond
                Department of Mathematics & Statistics
                         University at Albany
                        Albany, NY 12222 (USA)


CHANGES IN VERSION 0.8.4 (5 July 2007)

---

"Regular" GELLMU:

About 30 new commands have been added, mostly mathematical, including
more arrows, more dots, as well as "\prime" and "\backprime"
(emulating the corresponding AMS LaTeX names).  Also "itimes"
(invisible times) and "icomma" (invisible comma) join "aF" (invisible
applyFunction) for optional use as weak semantic hints.

The handling of mathematical prime accents has been completely revised
in order that the XHTML+MathML formatting will work better with the
(largely undocumented) handling of the corresponding unicode data
points in the web browsers that support MathML.  In only a few cases,
however, will legacy source files require change.  In this connection,
there is now an explicit rule for distinguishing in _regular_ GELLMU
source between uses of the character "'" as (a) apostrophe (\apos)
and (b) right-single-quote (\rsq): it's an apostrophe if and only if
it is followed by a "word-character" (as determined according to the
sense of that term for regular expression handling in GNU Emacs).
Sequences of two, three or four "'" characters become \rdq, \rtq,
or \rqq, respectively, unless, with the first of these the string
"''" is found to balance a previous string "``" in which case the
markup \quophrase{} is still generated.  (Moreover, matching pairs of
"`" and "'" still generate \squophrase{} when that is enabled by
certain manners of calling the syntactic translator.)

The handling of limits for sums, integrals, and products has been
revised beginning with a document type definition revision which
should be compatible with old source files that passed correctly
through the production stream.  Although processing toward the LaTeX
and XHTML+MathML formats had been "working", there were errors in the
classic HTML handling of these limits resulting from the fact that the
SGML/XML content models for \sum, \int, and \prod had been inadequate.

By default links, internal and external, found in \text{} in math mode
are now set using xlink rather than using an XML namespace switch to
enable HTML anchors.  This is tied to the environmental variable
GELLMU_XLink.  Also the previous limited handling of bold and italic
style in \text{} in math mode has also been revised to treatment that,
though less elegant, avoids namespace switching.

When XHTML+MathML output is produced, but regardless of the
availabilty of "dtd" validation, the production stream provides a
"child-count" checker for certain MathML elements.  It is intended
that this particular step, like the XML conformance check, will work
without reference to any formal document type definition.
Consequently, the use of classical HTML named entity references has
been eliminated.

Width specification for tabular p-cells is now supported in HTML and
XHTML using CSS style attributes.

There have been some miscellaneous revisions of the limited
representation of mathematics in the classic HTML formatting, and
there have been numerous bug fixes and minor improvements in all of
the various components of the "regular" production stream.

---

Syntactic translator:

Improved diagnostics for handling mismatched arguments in \newcommand
invocations.

For the context of "regular" GELLMU: (1) elaborated handling of prime
accents and (2) stronger efforts to diagnose unbalanced '$' characters
for toggling in and out of inline math zones.

Correction of a bug related to the signaling of an error when an
opening balancing character cannot be matched and elimination of the
unwanted double announcement of line numbers with many error messages.

--

Documentation:

There have been updates to both The Gellmu Manual and the Introductory
User Guide to Regular GELLMU.

----------------------------------------------------------------------

CHANGES IN VERSION 0.8.3 (23 Oct 2006)

IMPORTANT change necessitated by change in Firefox and other Mozilla
browsers:

This update is mandatory for those who wish their XHTML+MathML outputs
to function properly in Mozilla.  Because of a mid-September 2006
change in Mozilla with the handling of equations and arrays of
equations, previously generated XHTML+MathML outputs will need to be
rebuilt.

This release also has reduced use of XML namespace switching in the
XHTML+MathML outputs for the sake of greater compatibilty with
browsers that do not recognize it.

The XML side door:

The largest change in this update release concerns "Regular GELLMU"
(the didactic production system described in the GELLMU Manual).  The
standard translation pipeline leading from LaTeX-like source through
SGML and XML document types to (1) LaTeX source (hence DVI and PDF
outputs), (2) classical HTML output with pseudo-TeX math, and (3)
XHTML with MathML output has been modified to capture along the way a
variant of the XML document type that is reusable as XML source.
Subsequent pipeline processing proceeds from that point with end
results equivalent to those in earlier releases.

The new variant of the XML document type may be regarded as a
full-featured author level XML document type.  It is usable and
modifiable by authors who choose to write XML syntax rather than the
LaTeX-like equivalent.

The new author level variant of the XML document type is a suitable
target for translation from other XML document types, and therefore,
could provide an alternative way to format other document types for
PDF, HTML, and XHTML+MathML.

Beyond that document instances under the new author level variant of
the XML document type should usually be "stand-alone" instances that
are suitable for semi-formatted viewing through the web with CSS
styling.  They cannot be fully formatted because, for example,
numbering has not been inserted, and cross-references have not been
resolved.

A consequence of having the XML side door is that the automatically
formatted LaTeX files will tend to have very long lines.

Driver Scripts:

For the regular GELLMU main track use the driver script "mmkg" to
build from regular GELLMU source.  One should use the new driver
script "mmkgfromx" to build from XML source under the document type
defined in the DTD file "xml/axgellmu.dtd".  (This DTD file lives
under the UTF-8 text encoding though presently only one little-used
element name is non-ASCII, and that name admits Latin-1
representation.)

Windows XP Support:

In the case of a recently acquired (August 2006) ``notebook'' class
computer with ``Windows XP, Home Edition'', it was found after (1)
installing Cygwin, (2) then installing Cygwin packages for GNU Emacs,
Perl, Tcsh, TeX and LaTeX, OpenSP/OpenJade, and Expat (for the
important and basic "xmlwf" utility), and (3) making sure that all of
the appropriate executables are in one's command path (within Cygwin),
that the GELLMU tarball drops easily into "/usr/local/gellmu" (Cygwin
filesystem hierarchy), and the Linux driver scripts may be used.

The bin/win32 directory in the distribution remains untouched since
2001 for lack of a volunteer interested in updating the batch files.
For that approach to be sensible one wants to acquire the free
software items mentioned above for regular installation in Windows
(apart from Cygwin -- but all of these things co-exist peacefully when
found in both worlds as far as this author knows).

----------------------------------------------------------------------

Early 2006

IMPORTANT ISSUE for MathML output

The newer versions of Perl are somewhat incompatible with less new
versions regarding the UTF-8 content-encoding.  This can create
problems with parsing math zones while generating XHTML+MathML output.
One of the aspects of this issue is that the meaning of "use UTF-8"
has changed (as advertised by advance warnings).  The specific concern
is with splitting a UTF-8 string into the array of its characters.

It seems to be the case with Perl 5.6 that "use UTF-8" is adequate for
Gellmu's parsing, while with Perl 5.8.1 and later one wants both "use
UTF-8" and "use encoding".  There seems to be no "encoding" available
by default in 5.6.  Consequently, this release of gellmu provides a
dummy library "encoding.pm" that is intended for use when there is no
separate "encoding" package installed with Perl 5.6.  With the newer
Perl versions simply move the small dummy "encoding.pm" out of (or to
another name in) the "perllib" directory in the Gellmu tree.

----------------------------------------------------------------------

CHANGES IN VERSION 0.8.2.3 (25 May 2006)

1.  Bug fix.  Intermediate XML file that is not standalone is so
    labeled.

2.  Modified XHTML+MathML to use − as minus sign.

3.  Bug fix.  Display style was not in force for "equation" and
    "eqnarray" in XHTML+MathML

4.  Modified handling of "text" (for incidental text inside math
    zones) so that the presence or absence, but not its extent, of
    initial or trailing whitespace is significant in HTML and
    XHTML+MathML formattings.  Also fixed whitespace handling for
    "bmod" and "pmod".  Modified the LaTeX formatting so that "text"
    is set as LaTeX's "text" instead of as "mbox".

----------------------------------------------------------------------

CHANGES IN VERSION 0.8.2 (28 Feb 2006)

1.  Tables and Tabular now have functioning p cells.  Only "par",
    not "parb", should be used to introduce a new paragraph in
    a tabular p-cell.  For a forced linebreak inside a p-cell use
    the named form \brk rather than "\\", which may only be used
    to begin a new row.

2.  Horizontal alignment in tables and tabular now function in
    HTML, as do horizontal rules (via hline in tabular or trule
    in table) and vertical rules (via '|' in table or tabular
    argument).  Much of the new functionality with tables in HTML
    is based on assuming web browsers have CSS2 support.

3.  Added support for the attribute "style" of "assertion", which
    plays the role of \theoremstyle in LaTeX.  If "style" is unset,
    the assertion is set in italics, while if "style" has the value
    "definition", the assertion is set upright.

4.  Bug.  Finally decided to rely on CSS for HTML/XHTML handling
    of assertion style.

5.  Bug.  Used the "bm" package in LaTeX formatting (and CSS in
    XHTML+MathML) to correct the appearance of "mathbf". 

6.  The elements "par" and "parb" are no longer allowed inside "emph".
    The element "par" now requires explicit closing in source.

7.  Use of the elements "mbox", "regch", and "text", is now restricted
    to math zones.

8.  Minor changes will be needed in order for some old documents to be
    used with new DTDs.

9.  Numerous bug fixes.

----------------------------------------------------------------------

CHANGES IN VERSION 0.8.0.7 (01 Feb 2005)

1.  Bug/Change.  Coding for the element "text" inside math elements
    in "mathprep.pl" had assumed that "text" had no sub-elements
    (consistent with the content model of MathML's "mtext").
    The author is debating with himself as to whether this is too
    restrictive.  Meanwhile that code has been changed.

2.  Change.  Added AMSMath names "ltimes", "rtimes", and "mp" to
    the "article" document type.

3.  Bug/Change.  Pushed handling of the element "sref" out to end
    formatters (parallel to handling of "ref") so as to use the
    ".xlb" database.

4.  Change.  Added handling in HTML and LaTeX formatters of "eqntag".

5.  Change.  Positive labelwidth in LaTeX formatting of "menu"
    and "Menu".


CHANGES IN VERSION 0.8.0.6 (01 Dec 2004)

1.  Bug fix.  The script "mathprep.pl" was failing to write 'mchld=""'
when a container had no actual content, thereby causing "htmlgart.pl"
to exit with an error message.

2.  Bug fix.  The parameter entity "%opline" was nonsensically
allowing "%fmath" content.  Its model was tightend and a new version
"%mopline" using "math|tmath" instead of "%fmath" was created for use
with "itemlabel" and "op0".

3.  Bug fix.  The shell script "bin/linux/lmkg" was revised to prevent
failure with some versions of "/bin/sh".

4.  Change.  The HTML "dl" written by "htmlgart.pl" for formatting
"assertion" was revised to have "class" attribute "assertion" so
that CSS-controlled margins can be customized.

5.  Change.  The CSS stylesheet "webstyle/mxh.css" was changed to zero
left and right margins for "dl.assertion" and to inhibit linebreaking
inside all "math" containers, inline as well as block.

6.  Bug fix.  Comments were inhibited (for validation) at the top
level of "thebibliography".

7.  Change.  Provided a GMT timezone option for the banner datestamp
in HTML output.

----------------------------------------------------------------------

CHANGES IN VERSION 0.8.0.5 (10 Oct 2004)

1.  Bug fix.  A small regressive bug in the LaTeX output stream from
version 0.8 caused line separation to be doubled for verblists
(corresponding to an enhanced form of LaTeX's verbatim) and addrs (for
surface mail addresses other than those in the preamble).

2.  Bug fix.  Binomial coefficients were not being fenced in the
XHTML+MathML output.

3.  Bug fix.  In LaTeX output there was unwanted space between
"\otimes" and any subscript attached to it.  Changed unconditional
output for "<otimes/>" from "\otimes{}" to "\otimes " (not sure if
this is adequate).  Similar changes for "times", "oplus", "cup",
"cap", "circ", and "wedge".  (There is no parallel issue on this if a
unicode point for "otimes" appears in UTF-8 source, but then there
might be other issues in the UTF-8 category for latex.)

4.  Change.  Comments in XHTML output that were present for
development purposes have been removed.

5.  Change.  In the XHTML+MathML output only streamlined UMSS
materials are now being used when content MathML is not being written
(as is the case now).  There is a user switch with the environmental
variable "GELLMU_NoUMSS" to turn off the use of UMSS materials (not
recommended apart from kiosk situations).  For information about the
UMSS materials see http://www.w3.org/Math/XSL/.

6.  Change.  The distribution directory called "css" has been replaced
by "webstyle", which now contains copies of the W3C UMSS materials as
well as "mxh.css".  For the XHTML+MathML and classical HTML outputs
the default value for the web style directory name (containing both
xsl and css sheets) is now "../webstyle".  The only override for this
is now via the environmental variable "GELLMU_StyleDir" (which may be
coded in a driver script such as "mmkg").  Take account of HTML "base"
directives, if used, when configuring "GELLMU_StyleDir"

----------------------------------------------------------------------

CHANGES IN VERSION 0.8.0.4 (29 Sep 2004)

These changes affect "regular" GELLMU, mainly in relation to
the new XHTML+MathML output.

1. Bug fix. The handling of "\not" for XHTML+MathML in version 0.8
suffered from a serious oversight.  It has been completely revised
beginning with a change in the content model from empty to non-empty,
with content the operator under negation, possibly following "\," or
"\ ".  An old source with, for example, the markup "a \not\,| b" will
still be good.

2. Bug fix. There was a serious adverse interaction between the use of
'_' and '^' for range content with sums, products, and integrals and
other use in connection with XHTML+MathML output.

3. Several old GELLMU sources have been found that failed processing
because of validation errors.  While some of these were simply author
errors, others have led to small loosenings in the SGML and XML
document type definitions.

4. SGML and XML files made from old sources that validate under old
DTDs may not validate under current DTDs.  The DTDs from the 0.7.4
release (July 2001) have been added to the current release in the
directory "dtd-old" for those who might need them.  One change that
will trip a significant number of old documents is that loose inline
text is no longer allowed with "abstract" (nor in "legalnotice").  For
this in most cases the regular GELLMU source document may be updated
simply by beginning the abstract with a blank line.

5. There has been further progress in writing the User Guide
(doc/userdoc).  It is a work in progress.  There have been requests
for a glossary of commands.  That is in the works, but the plan
involves a literate formal document type definition.  Meanwhile one
may search the DTDs "gellmu.dtd" (the Latin1 version or "ugellmu.dtd",
the UTF-8 version) for markup vocabulary.

----------------------------------------------------------------------

NEW IN VERSION 0.8 (2 Sep 2004)

The part of the project called "Regular GELLMU", which is a bridge
from LaTeX authoring to XML authoring in generalized LaTeX-like
markup, now has an output stream in the modern XML form of HTML
extended for mathematical content by the World Wide Web Consortium's
MathML.

If an article has mathematical content, build it with "mmkg".

If an article has no math, build it with "lmkg".  (If it does have
mathematical content, it will still build, but there will be no output
stream in XHTML + MathML.  The classical HTML output will contain
ASCII pseudo-TeX.)

HTML with MathML is obtained from a regular GELLMU article by calling
the Perl program htmlgart.pl with argument "-mathml".  Without that
argument the program writes classical HTML using ASCII pseudo-TeX for
mathematical content.  Classical HTML is still useful in terminal
windows and with the shrinking number of graphic screen web browsers
for which there is no support for MathML without cost.  If
htmlgart.pl is called with the argument "-xhtml", then it writes the
XML form of HTML using ASCII pseudo-TeX for mathematical content.

"doc/userdoc" is a beginning at providing an introduction for users.
Please let me know what else should be explained there.

At this time there has been no updating of the native command line
scripts for the win32 platform because the author no longer has
reasonable access to that platform.  If a win32 platform user acquires
"Cygwin" with Emacs, Perl, TeX, and OpenSP, then it should be easy to
adapt the current Linux scripts for use.

----------------------------------------------------------------------

ABOUT GELLMU

GELLMU is an acronym for "Generalized Extensible LaTeX-Like MarkUp",
which is the author's concept for using LaTeX-like markup to write
consciously for SGML document types such as HTML, DocBook, TEI, or
GELLMU's own didactic LaTeX-like article.

It evolved from earlier thought about delineation of a coherent subset
of LaTeX commands with the property that if a LaTeX 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.

Essential information is in the manual, which may be found in the
distribution tree as "doc/glman"

Both of these forms of the manual were prepared from a source file

                            doc/glman.glm

that is LaTeX-like markup for the didatic "article" SGML document
type.

Additional information is available at the GELLMU web site:

                http://www.albany.edu/~hammond/gellmu/