% LaTeX %nul %nul %nul %nul %nul %nul %nul %nul %nul %nul %nul %nul %nul %nul %nul %nul %nul %nul %nul %nul %nul %nul %nul %nul %nul \documentclass[leqno]{article} \usepackage{url} \usepackage{graphicx} \usepackage{amsmath} \usepackage{amssymb} \usepackage{amsfonts} \usepackage{bm} \usepackage{gellmu} \usepackage[margin=100bp,nohead]{geometry} \setlength{\parskip}{6bp} \setlength{\parindent}{0bp} \thispagestyle{empty} \title{Frequently Asked Questions about GELL\-MU} \date{Last Revision: \today{} } %nul \newlength{\centerskip} \setlength{\centerskip}{\topsep} \newcommand{\hsf}{\hspace*{\fill}} \newcommand{\tdbc}[1]{\hsf\textbf{#1}\hsf} \newenvironment{menulist}{ \begin{list}{}{ \setlength{\topsep}{0bp} \setlength{\labelwidth}{0.03\linewidth} \setlength{\leftmargin}{0.06\linewidth} \setlength{\itemindent}{0bp} \setlength{\itemsep}{-6bp} \setlength{\parsep}{6bp}} }{\end{list}} \newenvironment{Menulist}{ \begin{list}{}{ \setlength{\topsep}{0bp} \setlength{\labelwidth}{0.03\linewidth} \setlength{\leftmargin}{0.06\linewidth} \setlength{\itemindent}{0bp} \setlength{\itemsep}{3bp} \setlength{\parsep}{6bp}} }{\end{list}} \newenvironment{toclist}{\normalsize \begin{list}{}{ }}{\end{list}} \newenvironment{Toclist}{\large \begin{list}{}{ }}{\end{list}} \newenvironment{citations}{ \begin{list}{}{ \setlength{\topsep}{0bp} \setlength{\labelwidth}{0bp} \setlength{\leftmargin}{0.04\linewidth} \setlength{\labelsep}{0bp} \setlength{\itemindent}{-0.2\leftmargin} \setlength{\itemsep}{3bp} \setlength{\parsep}{0bp}} }{\end{list}} \author{William F. Hammond} \begin{document} \begin{center}\LARGE\bfseries{} Frequently Asked Questions about GELL\-MU \end{center} \begin{center}\Large\bfseries{} \textsl{William F. Hammond} \end{center} \begin{center} \large\bfseries{} Last Revision: \today{} \end{center} \medskip \section*{Table of Contents} \begin{Toclist} \item[]{Part I\ \ \ \ Basic Questions\dotfill{}~\pageref{SU-1}} \begin{toclist}\normalsize \item[]{1\ \ \ What is \textsc{GELL\-MU}?\dotfill{}~\pageref{SU-1.1}} \item[]{2\ \ \ What is \textsc{XML}?\dotfill{}~\pageref{SU-1.2}} \item[]{3\ \ \ Why was \textsc{GELL\-MU} Created?\dotfill{}~\pageref{SU-1.3}} \item[]{4\ \ \ Can \textsc{GELL\-MU} Help Me to Write My Web Pages?\dotfill{}~\pageref{SU-1.4}} \item[]{5\ \ \ What is the Diffence between Basic and Regular \textsc{GELL\-MU}?\dotfill{}~\pageref{SU-1.5}} \item[]{6\ \ Are There Other Similar Markups?\dotfill{}~\pageref{SU-1.6}} \end{toclist} \item[]{Part II\ \ \ \ Running \textsc{GELL\-MU}\dotfill{}~\pageref{SU-2}} \begin{toclist}\normalsize \item[]{7\ \ \ On What Platforms Can \textsc{GELL\-MU} Be Used?\dotfill{}~\pageref{SU-2.1}} \item[]{8\ \ \ What is Needed to Run \textsc{GELL\-MU}?\dotfill{}~\pageref{SU-2.2}} \end{toclist} \item[]{Part III\ \ \ \ Things in \LaTeX{} not in \textsc{GELL\-MU}\dotfill{}~\pageref{SU-3}} \begin{toclist}\normalsize \item[]{9\ \ \ Why are So Many Things Not ``In'' \textsc{GELL\-MU}?\dotfill{}~\pageref{SU-3.1}} \item[]{10\ \ \ Why Doesn't \texttt{}\verb+\+\texttt{ref} Automatically Make Anchors?\dotfill{}~\pageref{SU-3.2}} \item[]{11\ \ \ What About Split-File Source?\dotfill{}~\pageref{SU-3.3}} \item[]{12\ \ \ What About Split-File Formattings?\dotfill{}~\pageref{SU-3.4}} \end{toclist} \item[]{Part IV\ \ \ \ Relation of \textsc{GELL\-MU} to Other Things\dotfill{}~\pageref{SU-4}} \begin{toclist}\normalsize \item[]{13\ \ \ How is \textsc{GELL\-MU} Related to \textsl{latex2html}?\dotfill{}~\pageref{SU-4.1}} \item[]{14\ \ \ How is \textsc{GELL\-MU} Related to \textsl{hyperlatex}?\dotfill{}~\pageref{SU-4.2}} \item[]{15\ \ \ How is \textsc{GELL\-MU} Related to \textsl{tex4ht}?\dotfill{}~\pageref{SU-4.3}} \end{toclist} \end{Toclist} %nul \section*{Part I\ \ \label{SU-1}\label{basic}\ \ Basic Questions} \subsection*{1\ \ \label{SU-1.1}\label{whatIsGellmu}\ What is GELL\-MU?} \par{\textsc{GELL\-MU} stands for ``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 \textsc{XML} (see question 2). \ } \subsection*{2\ \ \label{SU-1.2}\label{whatIsXml}\ What is XML?} \par{\textsc{XML} stands for ``Extensible Markup Language'', which is second generation basic markup language for the World Wide Web. \ The use of the word \emph{extensible} means that the set of markup tags is not fixed. \ That, in turn, means that \textsc{XML} is not a markup language but rather a family of markup languages with a shared syntax. \ } \subsection*{3\ \ \label{SU-1.3}\label{whyGellmu}\ Why was GELL\-MU Created?} \par{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. \ } \par{He found that if he wrote \textsc{HTML} directly, he could not derive adequate printed versions, and he found converters for translating \LaTeX{} into \textsc{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 \textsc{HTML} to \LaTeX{}.)}. \ } \par{\textsc{GELL\-MU} 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 question 6. \ } \subsection*{4\ \ \label{SU-1.4}\label{authorWeb}\ Can GELL\-MU Help Me to Write My Web Pages?} \par{Yes, in two ways. \ There is a choice between \emph{basic} \textsc{GELL\-MU} and \emph{regular} \textsc{GELL\-MU}. \ } \par{If you are familiar with the tag set for \textsc{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} \textsc{GELL\-MU} provides \LaTeX{}-like notation, which is somewhat more succinct than regular \textsc{HTML} tagging, and \emph{newcommand}-like macros for writing \textsc{HTML}. \ For this see also part IV. \ } \par{If you want to write for more than one ultimate output with a single source markup (see question 6), then \emph{regular} \textsc{GELL\-MU} may be considered. \ } \subsection*{5\ \ \label{SU-1.5}\label{twoGellmus}\ What is the Diffence between Basic and Regular GELL\-MU?} \par{Basic \textsc{GELL\-MU} provides minimal (1) \LaTeX{}-like syntax and (2) \emph{newcommand}-like macros for conscious writing toward an \textsc{SGML} or \textsc{XML} document type such as \textsc{HTML}, DocBook, TEI, SGMLTexi, \ldots{}. \ } \par{Regular \textsc{GELL\-MU} provides also a fuller array of \LaTeX{}-like syntax features and some \LaTeX{}-like shorthand. \ Moreover, the \textsc{GELL\-MU} didactic production system provides a document type with many \LaTeX{}-like commands. \ } \subsection*{6\ \ \label{SU-1.6}\label{singleSource}\ Are There Other Choices for Single Source, Multiple Output Markup Languages for Authors?} \par{Yes. \ \textsl{Tex\-info}, the language of the \textsc{GNU}\footnote{The free software project of Richard Stallman and the Free Software Foundation. \\{} See \url{http://www.gnu.org/}. \ } Documentation System, is an example. \ In the 80's \textsl{Tex\-info} could be used to provide two forms of a \textsc{GNU} document: (1) \textsl{Info} online hypertext, suitable for the text-based terminals with cursor control of that time and (2) finely typeset text in \textsc{DVI} format. \ } \par{By the late 80's Charles Goldfarb had created \textsc{SGML}, the very general family of markup languages in which \textsc{HTML} is a member and relative to which \textsc{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. \ %nul } \section*{Part II\ \ \label{SU-2}\label{running}\ \ Running GELL\-MU} \subsection*{7\ \ \label{SU-2.1}\label{platforms}\ On What Platforms Can GELL\-MU Be Used?} \par{A complete suite of materials for the \textsc{GELL\-MU} didactic production system is available for the \textsc{GNU} Operating System, Linux, the various flavors of Unix, and modern ``Windows''. \ } \subsection*{8\ \ \label{SU-2.2}\label{needed}\ What is Needed to Run GELL\-MU?} \par{Minimally the \textsc{GELL\-MU} Syntactic Translator, an \textsc{GNU} Emacs Lisp program. \ To use it, you need the Emacs Lisp engine, which is \textsc{GNU} Emacs. \ } \par{For \emph{basic} \textsc{GELL\-MU} (see question 5) the \textsc{GELL\-MU} Syntactic Translator is all that you need. \ Its output is the \textsc{SGML} or \textsc{XML} language such as, for example, \textsc{HTML}, for which you are explicitly tagging. \ Of course, you need whatever is required in order for you to deal with that output. \ } \par{For \emph{regular} \textsc{GELL\-MU} with the didactic \textsc{GELL\-MU} production system you need to have \begin{enumerate} \item James Clark's \textsl{nsgmls/SP}. \ \item Perl. \ \item \TeX{}. \ \end{enumerate} } \section*{Part III\ \ \label{SU-3}\label{missing}\ \ Things in \LaTeX{} not in GELL\-MU} \subsection*{9\ \ \label{SU-3.1}\label{whyMissing}\ Why are So Many Things Not ``In'' GELL\-MU?} \par{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. \ } \par{More information about this will be found in the \textsc{GELL\-MU} Manual\footnote{URI: ../doc/glman.html}, especially in the appendix entitled \emph{Release Notes}\footnote{URI: ../doc/glman.html\#release}. \ } \subsection*{10\ \ \label{SU-3.2}\label{refanch}\ Why Doesn't \texttt{\textbackslash{}ref} Automatically Make Anchors?} \par{First note that every \texttt{}\verb+\+\texttt{label} command does result in the creation of a base to which one may anchor. \ In the two didactic formattings for \LaTeX{} and \textsc{HTML} the anchor base is not visible when rendered\footnote{Some \textsc{HTML} renderers might disclose \emph{id} anchors with empty content.}. \ There are three reasons why \texttt{}\verb+\+\texttt{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 ``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{center} \texttt{}\verb+\+\texttt{newcommand}\verb+{+\texttt{}\verb+\+\texttt{Ref}\verb+}+\texttt{[1]}\verb+{+\texttt{}\verb+\+\texttt{anch[iref=\texttt{"}}\verb+\+\texttt{ref}\verb+{+\texttt{\#1}\verb+}+\texttt{\texttt{"}]}\verb+{+\texttt{}\verb+\+\texttt{ref}\verb+{+\texttt{\#1}\verb+}+\texttt{}\verb+}+\texttt{}\verb+}+\texttt{}\ , \end{center} 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 \texttt{"ref"} instead of \texttt{"Ref"} is also allowed in \textsc{GELL\-MU}, though in \LaTeX{} one would need to use \emph{renewcommand}\footnote{Since \LaTeX{}'s \emph{newcommand} actually creates a new command whereas \textsc{GELL\-MU}'s \emph{newcommand} is one-time forward macro substitution. \ }. \ \end{enumerate} } \subsection*{11\ \ \label{SU-3.3}\label{splitSource}\ What About Split-File Source?} \par{The best way to merge document input is at the level of \textsc{SGML} source, i.e., at the stage represented by the output of the syntactic translator. \ } \par{For example, this will make the parsing error reports from \textsl{nsgmls} easy to locate in \textsc{GELL\-MU} 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. \ } \subsection*{12\ \ \label{SU-3.4}\label{splitOutput}\ What About Split-File Formattings?} \par{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. \ } \par{This would make sense, for example, for a \emph{collection} document class that was constructed to consist of independently authored \textsc{GELL\-MU} \emph{article}s. \ While one might want a unified typesetting, one might also want separate \textsc{HTML} versions and separate screen-sized \textsc{PDF} versions. \ } \par{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. \ } \section*{Part IV\ \ \label{SU-4}\label{related}\ \ Relation of GELL\-MU to Other Things} \subsection*{13\ \ \label{SU-4.1}\label{latex2html}\ How is GELL\-MU Related to latex2html?} \par{\textsc{GELL\-MU} provides \LaTeX{}-like markup for the conscious writing of instances under an \textsc{XML} document type. \ That document type could be \textsc{HTML}. \ } \par{\textsl{latex2html}, on the other hand, is designed to translate source consciously written as classical \TeX{} or \LaTeX{} markup. \ } \subsection*{14\ \ \label{SU-4.2}\label{hyperlatex}\ How is GELL\-MU Related to hyperlatex?} \par{\textsc{GELL\-MU} provides a way to write \textsc{HTML} consciously using \LaTeX{}-like syntax, while \textsl{hyperlatex} involves translation of a special dialect of \LaTeX{}. \ There are a number of similar features in \textsl{hyperlatex} including: \begin{enumerate} \item The use of \LaTeX{} (not \LaTeX{}-like) markup to write \textsc{HTML}. \ \item The use of a \textsc{GNU} Emacs Lisp program to translate source markup (in this case to \textsc{HTML}). \ \item Careful, reliable production of both \textsc{HTML} and typeset forms of a document. \ \end{enumerate} As it stands in relation to \textsc{SGML} or \textsc{XML}, \textsl{hyperlatex} is specific for \textsc{HTML}. \ The source of a \textsl{hyperlatex} document may be given to \textsl{hyperlatex}'s Emacs Lisp program for translation to \textsc{HTML} or to \textsl{LaTeX}, the program, for typesetting with \textsl{hyperlatex} macros. \ } \par{\textsc{GELL\-MU}'s basic layer, which operates at the level of syntax without knowledge of markup vocabulary, may be used for writing under many \textsc{SGML} or \textsc{XML} document types, not just \textsc{HTML}. \ Subsequent to syntactic translation from \LaTeX{}-like markup to standard \textsc{SGML} or \textsc{XML} markup, one may employ any suitable \textsc{SGML} or \textsc{XML} processor for further translation, typesetting, or other processing. \ \textsc{GELL\-MU}'s basic layer for writing in \textsc{HTML} (or in any other \textsc{SGML} or \textsc{XML} document type) directly does not provide typesetting. \ } \par{The \textsc{GELL\-MU} didactic production system provides what is intended as a first \textsc{SGML}/\textsc{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 \textsl{LaTeX}, the Program, with \textsc{GELL\-MU} source is a choice, not a requirement. \ } \subsection*{15\ \ \label{SU-4.3}\label{tex4ht}\ How is GELL\-MU Related to tex4ht?} \par{The \textsl{tex4ht} family of applications is conversion software. \ It uses \textsl{TeX}, the Program, configured with special macros aimed at a target format, such as \textsc{HTML}, to create \textsc{DVI} ``specials'' in \textsl{TeX}'s normal \textsc{DVI} output. \ While one can print the \textsc{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 \textbf{if} the original source is carefully crafted. \ For legacy source this method is likely to produce optimal results. \ } \par{\textsc{GELL\-MU} provides \LaTeX{}-like markup for the conscious writing of instances under an \textsc{XML} document type. \ There is very little intersection of this with the functionality of \textsl{tex4ht} except in the relatively rare instances of \TeX{} or \LaTeX{} source that is carefully crafted under a custom markup. \ } \par{\textsc{GELL\-MU} 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 ``port'' legacy \LaTeX{} source into useful \textsc{GELL\-MU} source. \ The item \url{lfaq.glm} in the examples archive\footnote{URI: ./} is an example of a port. \ } \end{document}