%!latex-faq
\documenttype{article}
\newcommand{\part}[3][\series[:type="I"]{\evalref{#2}}]{%
\section[:inv="part"][][\label[:series="part"]{#2}Part ][#1]{\ \ #3}\section:%
}
\newcommand{\question}[3][]{%
\subsection[:inv="question"][#1][\label[:series="question"%
]{#2}][\evalref{#2}]{\ #3}%
\subsection:}
\newcommand{\pref}[2][part]{\anch[:inv="pref"%
][iref="#2"]{#1 \sref{#2}}}
\newcommand{\qref}[2][question]{\anch[:inv="qref"%
][iref="#2"]{#1 \ref{#2}}}
\newcommand{\gref}[2]{\href{\gweb/#1}{#2}}
\newcommand{\href}[2]{\anch[href="#1"]{#2}}
\newcommand{\gweb}{http://www.albany.edu/\tld;hammond/gellmu}
\newcommand{\dvi}{\abbr{DVI}}
\newcommand{\gellmu}{\abbr{GELL\-MU}}
\newcommand{\gnu}{\abbr{GNU}}
\newcommand{\gst}{\gellmu Syntactic Translator}
\newcommand{\html}{\abbr{HTML}}
\newcommand{\latexp}{\softw{LaTeX}}
\newcommand{\sgml}{\abbr{SGML}}
\newcommand{\texp}{\softw{TeX}}
\newcommand{\txi}{\softw{Tex\-info}}
\newcommand{\xml}{\abbr{XML}}
\newcommand{\www}{World Wide Web}
\surtitle{The \html Archive}
\title{Frequently Asked Questions about \gellmu}
\author{William F. Hammond}
\date{Last Revision: \today}
% \baseloc{\gweb/examples}
\nobanner

\begin{document}
\tableofcontents
% \part{A}{basic}{Basic Questions}
\part{basic}{Basic Questions}
\question{whatIsGellmu}{What is \gellmu?}

\gellmu stands for \quophrase{Generalized Extensible \latex;-Like
MarkUp}.  It is a markup language with syntax resembling in large part
that of \latex; that is designed to provide a bridge for authors who
wish to migrate from \latex to \xml (see \qref{whatIsXml}).

\question{whatIsXml}{What is \xml?}

\xml stands for \quophrase{Extensible Markup Language}, which is
second generation basic markup language for the \www.
The use of the word \emph{extensible} means that the set of markup
tags is not fixed.  That, in turn, means that \xml is not a markup
language but rather a family of markup languages with a shared
syntax.

\question{whyGellmu}{Why was \gellmu Created?}

The author is a math professor who became frustrated in recent years
with the extra work required to make his course materials available
on the web for his students.

He found that if he wrote \html directly, he could not derive adequate
printed versions, and he found converters for translating \latex; into
\html cumbersome, inaccurate, and unsatisfactory\footnote{There are now
better converters; however, the overall idea of translating from LaTeX
to HTML is not logically sound.  (On the other hand, it \emph{is}
logically sound to write a translator from \html to \latex;.)}.

\gellmu is designed as a single source language in which to write from
which different formats can be automatically derived with complete
reliability.  For more on single source, multiple output languages
for authors see \qref{singleSource}.

\question{authorWeb}{Can \gellmu Help Me to Write My Web Pages?}

Yes, in two ways.  There is a choice between \emph{basic} \gellmu
and \emph{regular} \gellmu.

If you are familiar with the tag set for \html (the basic language
used in web pages) and do not want any form for what you write other
than a web page, then \emph{basic} \gellmu provides \latex;-like
notation, which is somewhat more succinct than regular \html tagging,
and \emph{newcommand}-like macros for writing \html.  For this see
also \pref{related}.

If you want to write for more than one ultimate output with a
single source markup (see \qref{singleSource}), then \emph{regular}
\gellmu may be considered.

\question{twoGellmus}{What is the Diffence between Basic and Regular
\gellmu?}

Basic \gellmu provides minimal (1) \latex;-like syntax and (2)
\emph{newcommand}-like macros for conscious writing toward an \sgml
or \xml document type such as \html, DocBook, TEI, SGMLTexi, \ldots.

Regular \gellmu provides also a fuller array of \latex;-like syntax
features and some \latex;-like shorthand.  Moreover, the \gellmu
didactic production system provides a document type with many
\latex-like commands.

\question{Are There Other Similar Markups?}{singleSource}{Are There Other
Choices for Single Source, Multiple Output Markup Languages for Authors?}

Yes.  \txi, the language of the \gnu\footnote{The free software
project of Richard Stallman and the Free Software Foundation.\brk;
See \urlanch{http://www.gnu.org/}.
}
Documentation System, is an example.  In the 80's \txi could be used
to provide two forms of a \gnu document: (1) \softw{Info} online
hypertext, suitable for the text-based terminals with cursor control
of that time and (2) finely typeset text in \dvi format.

By the late 80's Charles Goldfarb had created \sgml, the very general
family of markup languages in which \html is a member and relative to
which \xml is a subfamily.  Although it is formally possible for
a language under this umbrella to admit essentially no translation,
the intention was to provide powerful languages suitable for multiple
outputs and to provide, thanks to the shared syntax, general processing
frameworks under which translations can be efficiently and reliably
written.

% \part{B}{running}{Running \gellmu}
\part{running}{Running \gellmu}

\question{platforms}{On What Platforms Can \gellmu Be Used?}

A complete suite of materials for the \gellmu didactic production system
is available for the \gnu Operating System, Linux, the various flavors
of Unix, and modern \quophrase{Windows}.

\question{needed}{What is Needed to Run \gellmu?}

Minimally the \gst, an \abbr{GNU} Emacs Lisp program.  To use it, you
need the Emacs Lisp engine, which is \gnu Emacs.

For \emph{basic} \gellmu (see \qref{twoGellmus}) the \gst is all that
you need.  Its output is the \sgml or \xml language such as, for example,
\html, for which you are explicitly tagging.  Of course, you need
whatever is required in order for you to deal with that output.

For \emph{regular} \gellmu with the didactic \gellmu production system
you need to have
\begin{enumerate}
\item James Clark's \softw{nsgmls/SP}.
\item Perl.
\item \tex.
\end{enumerate}

\part{missing}{Things in \latex; not in \gellmu}

\question{whyMissing}{Why are So Many Things Not ``In'' \gellmu?}

The didactic document type is intended to be a base for further
development.  For that reason its design is minimalist.  Its author
believes that the techniques used are adequate for a substantially
more elaborate system.  One who so wishes can move it closer to
regular \latex; than it already is.  On the other hand, if it is moved
too close to \latex;, which is a structured typesetting language,
then the range of possible translation targets might be diminished.

More information about this will be found in the
\href{../doc/glman.html}{\gellmu Manual}, especially in the appendix
entitled \href{../doc/glman.html\#release}{\emph{Release Notes}}.

\question{refanch}{Why Doesn't |\ref| Automatically Make Anchors?}

First note that every |\label| command does result in the creation of
a base to which one may anchor.  In the two didactic formattings for \latex;
and \html the anchor base is not visible when rendered\footnote{Some
\html renderers might disclose \emph{id} anchors with empty content.}.
There are three reasons why |\ref| does not automatically provide a link:
\begin{enumerate}
\item Since \emph{ref} is the same as a name in \latex;, there is an
effort to emulate \latex;'s behavior in this regard.

\item There is more than one reasonable way to \quophrase{style} an
anchor.

\item It is extremely easy for an author to use \emph{newcommand} to
reference a label.  For example, if an author writes
\begin{display}
|\newcommand{\Ref}[1]{\anch[iref="\ref{#1}"]{\ref{#1}}}|\ ,
\end{display}
then \emph{Ref} is created as a name for providing a label reference
(by key, as with \emph{ref}) with an anchor.  Or the same newcommand
with name string \qquostr{ref} instead of \qquostr{Ref} is also allowed
in \gellmu, though in \latex; one would need to use
\emph{renewcommand}\footnote{
Since \latex;'s \emph{newcommand} actually creates a new command whereas
\gellmu's \emph{newcommand} is one-time forward macro substitution.
}.
\end{enumerate}

\question{splitSource}{What About Split-File Source?}

The best way to merge document input is at the level of \sgml source,
i.e., at the stage represented by the output of the syntactic
translator.

For example, this will make the parsing error reports from
\softw{nsgmls} easy to locate in \gellmu source since errors are
reported by file and line number.  (The syntactic translator preserves
line number alignment between its source and its output, file by
file.)  Also when the syntactic translator is called separately for
different parts of a document, the \emph{newcommand} definitions are
localized to each part, thereby making the resolution of name
conflicts easy to track.

\question{splitOutput}{What About Split-File Formattings?}

As it is, the didactic production system is based on one file per
document.  If that is not what you want, just customize your
formatters to produce what you want.

This would make sense, for example, for a \emph{collection} document
class that was constructed to consist of independently authored
\gellmu \emph{article}s.  While one might want a unified typesetting,
one might also want separate \html versions and separate screen-sized
\abbr{PDF} versions.

In a design like that of the didactic production system the document
is seen as a whole at the stage where cross-referencing is handled.
This makes it possible for cross-referencing in split-file formattings
to comprehend the parts as they relate to the whole.

\part{related}{Relation of \gellmu to Other Things}

\question{latex2html}{How is \gellmu Related to \softw{latex2html}?}

\gellmu provides \latex;-like markup for the conscious writing of
instances under an \xml document type.  That document type could be
\html.

\softw{latex2html}, on the other hand, is designed to translate
source consciously written as classical \tex; or \latex; markup.

\question{hyperlatex}{How is \gellmu Related to \softw{hyperlatex}?}

\gellmu provides a way to write \html consciously using \latex;-like
syntax, while \softw{hyperlatex} involves translation of a special
dialect of \latex;.
There are a number of similar features in \softw{hyperlatex} including:
\begin{enumerate}
\item  The use of \latex; (not \latex;-like) markup to write \html.
\item  The use of a \abbr{GNU} Emacs Lisp program to translate
       source markup (in this case to \html).
\item  Careful, reliable production of both \html and typeset forms of
       a document.
\end{enumerate}
As it stands in relation to \sgml or \xml, \softw{hyperlatex} is
specific for \html.  The source of a \softw{hyperlatex} document may
be given to \softw{hyperlatex}'s Emacs Lisp program for translation to
\html or to \latexp, the program, for typesetting with
\softw{hyperlatex} macros.

\gellmu's basic layer, which operates at the level of syntax without
knowledge of markup vocabulary, may be used for writing under many
\sgml or \xml document types, not just \html.  Subsequent to syntactic
translation from \latex;-like markup to standard \sgml or \xml markup,
one may employ any suitable \sgml or \xml processor for further
translation, typesetting, or other processing.  \gellmu's basic layer
for writing in \html (or in any other \sgml or \xml document type)
directly does not provide typesetting.

The \gellmu didactic production system provides what is intended as a
first \sgml/\xml document type for those with experience as \latex;
authors.  The system is designed for free-standing separate
components, and new components can be introduced for translating to
new formats.  The use of \latexp, the Program, with \gellmu source
is a choice, not a requirement.

\question{tex4ht}{How is \gellmu Related to \softw{tex4ht}?}

The \softw{tex4ht} family of applications is conversion software.
It uses \texp, the Program, configured with special macros
aimed at a target format, such as \html, to create \abbr{DVI}
\quophrase{specials} in \texp's normal \abbr{DVI} output.  While one
can print the \abbr{DVI} file in the usual way, one may also then
submit it to a special post-processor for writing a translation of
the original document in the target format.  One can achieve very
good results this way \bold{if} the original source is carefully
crafted.  For legacy source this method is likely to produce optimal
results.

\gellmu provides \latex;-like markup for the conscious writing of
instances under an \xml document type.  There is very little intersection
of this with the functionality of \softw{tex4ht} except in the relatively
rare instances of \tex; or \latex; source that is carefully crafted under
a custom markup.

\gellmu does not provide a technique for automatic translation
of legacy documents although one may sometimes, especially with
clever use of its macro facilities, succeed with human effort to
\quophrase{port} legacy \latex; source into useful \gellmu source.
The item \urlanch{lfaq.glm} in the \href{./}{examples archive} is
an example of a port.

\end{document}