summaryrefslogtreecommitdiff
path: root/support/ltoh/readme.html
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
committerNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
commite0c6872cf40896c7be36b11dcc744620f10adf1d (patch)
tree60335e10d2f4354b0674ec22d7b53f0f8abee672 /support/ltoh/readme.html
Initial commit
Diffstat (limited to 'support/ltoh/readme.html')
-rw-r--r--support/ltoh/readme.html777
1 files changed, 777 insertions, 0 deletions
diff --git a/support/ltoh/readme.html b/support/ltoh/readme.html
new file mode 100644
index 0000000000..4ab8f49444
--- /dev/null
+++ b/support/ltoh/readme.html
@@ -0,0 +1,777 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
+<HTML>
+<HEAD>
+<TITLE>
+Ltoh, a customizable LaTeX to HTML converter
+</TITLE>
+</HEAD>
+<BODY>
+
+
+<p>
+
+<p>
+
+
+<p>
+
+<p>
+
+<p>
+
+<p>
+
+<p><center><H1><FONT color=green><font color=green><tt>Ltoh</tt></font>: a customizable LaTeX to HTML converter</FONT></H1></center>
+<center><H3><FONT color=teal>Version 97e, 31 Mar 1997</FONT></H3></center>
+<center><H3><FONT color=teal>Russell W. Quong</FONT></H3></center>
+
+<p>
+<DIV ALIGN=center>
+<EM>(http://www.best.com/~quong/ltoh)</EM>
+</DIV>
+
+<p><hr><H2><FONT color=blue>Introduction</FONT></H2></hr>
+
+<p><font color=green><tt>Ltoh</tt></font> is a customizable LaTeX to HTML converter. It handles text,
+tables, and hypertext links. <font color=green><tt>ltoh</tt></font> is a large Perl script, and hence is
+(almost completely) platform independent. <font color=green><tt>ltoh</tt></font> is customizable in that
+you can specify how to translate a given LaTeX2<it>e</it> macro into HTML,
+including your own personal macros. In fact, you must manually specify
+how to handle your own macros, otherwise <font color=green><tt>ltoh</tt></font> will give a friendly
+warning.
+
+<p>See <a href="http://www.best.com/~quong/ltoh"> the <font color=green><tt>ltoh</tt></font> web page </a> for documentation, the
+latest release, and how to contact the author (see the bottom of the web
+page). Naturally, the HTML version of document was generated using
+<font color=green><tt>ltoh</tt></font>, and in my opinion looks better than the LaTeX2<it>e</it> dvi/PS output,
+mostly due to the extra colors. The first public release was version
+97e on 3/31/97.
+
+<p><font color=green><tt>Ltoh</tt></font> has two main restrictions. First, <font color=green><tt>ltoh</tt></font> does <EM>not</EM> handle
+math equations, which in general are difficult to display in HTML.
+<font size=-1>[Some have resorted to converting the latex equations into
+Postscript (PS), converting the PS to a bitmapped figure, and the
+displaying the figure in HTML. This is all too difficult for me.]</font>
+Second, <font color=green><tt>ltoh</tt></font> requires La/Tex macro parameters to be delimited by
+braces; in practice, <font color=green><tt>ltoh</tt></font> might be unsuitable for most existing TeX
+code.
+
+<p>Surprisingly, I often preview my LaTeX2<it>e</it> documents via <font color=green><tt>ltoh</tt></font> instead of
+running <SAMP>latex</SAMP>, <SAMP>dvips</SAMP>, and <SAMP>ghostview</SAMP>.
+
+<p><hr><H2><FONT color=blue>The distribution</FONT></H2></hr>
+
+<p><font color=green><tt>Ltoh</tt></font> is distributed as either <a href="ltoh.zip"> a zip file </a> or a
+<a href="ltoh.tgz"> gzipped tar file </a> (about 75K).
+
+<p>Both distributions contain the following files.
+
+<p><DIV ALIGN=center>
+<table border>
+<TR> <TD align=left> ltoh.pl </TD> <TD align=left> The perl script that does everything </TD></TR>
+<TR> <TD align=left> ltoh.specs </TD> <TD align=left> The default specifications. </TD></TR>
+<TR> <TD align=left> readme.html </TD> <TD align=left> Generated by <font color=green><tt>ltoh</tt></font> </TD></TR>
+<TR> <TD align=left> readme.dvi </TD> <TD align=left> LaTeX2<it>e</it> output </TD></TR>
+<TR> <TD align=left> readme.ps </TD> <TD align=left> Uses Times Roman </TD></TR>
+<TR> <TD align=left> readme.txt </TD> <TD align=left> Text version (generated from netscape) </TD></TR>
+<TR> <TD align=left> README </TD> <TD align=left> </TD></TR>
+<TR> <TD align=left> rq-ltoh.specs </TD> <TD align=left> An example of my specifications </TD></TR>
+<TR> <TD align=left> rq209.sty </TD> <TD align=left> Allow use of new LaTeX2<it>e</it> font commands in old LaTeX2<it>e</it>. </TD></TR>
+<TR> <TD align=left>
+</table>
+</DIV>
+
+<p><hr><H2><FONT color=blue>System Software Requirements</FONT></H2></hr>
+
+<p><font color=green><tt>Ltoh</tt></font> version 97e requires the following system software.
+
+<p><OL>
+ <li><strong></strong> A unix operating system. I have tested <font color=green><tt>ltoh</tt></font> only under Linux,
+although there is nothing Linux specific in the code. A handful of
+lines are Unix dependent mostly in due to filename conventions. Because
+<font color=green><tt>ltoh</tt></font> is written in Perl, almost all the code is platform-independent.
+
+<p> <li><strong></strong> Perl version 5.00x, preferably 5.002 or higher. Run
+
+<p><P align=center><SAMP>perl -v</SAMP></P>
+
+<p>to see the version of Perl you have.
+
+<p> <li><strong></strong> LaTeX2<it>e</it> macro parameters (or arguments) must be brace delimited
+(surrounded by braces), because <font color=green><tt>ltoh</tt></font> relies on the braces.
+
+<p> <li><strong></strong> The <EM>new latex</EM> (LaTeX2<it>e</it>) is strongly recommended over the
+<EM>old latex</EM> (LaTeX 2.09),
+
+<p>Additionally, the default <font color=green><tt>ltoh</tt></font> specifications is
+based on standard new latex macros. Finally, to make full use of HTML
+tables, future versions of <font color=green><tt>ltoh</tt></font> are likely to support multiple rows in
+the table packages only found in the new latex.
+</OL>
+
+<p><H3><FONT color=teal>If you must use LaTeX 2.09 instead of LaTeX2<it>e</it></FONT></H3>
+
+<p><font color=green><tt>ltoh</tt></font> relies on unique matching braces to delimit arguments to the latex
+macros. In particular, the font family and size commands in old latex
+do not use braces to delimit arguments. Thus, <font color=green><tt>ltoh</tt></font>\ does not (and
+probably never will) handle old latex 2.09 font specifications.
+Instead, you must use the LaTeX2<it>e</it> convention, which delimits the text to
+be affected by a font change via braces as shown in the following
+comparison.
+
+<pre>
+(Old latex) Normal but switch \bf to {bold \it then italics, back to}
+bold \normalfont then normal.
+
+(New latex) Normal but switch \textbf{to bold \textit{then italics, back
+to} bold} then normal.
+</pre>
+<p>
+Produces:
+
+<p><BLOCKQUOTE>
+Normal but switch <STRONG>to bold <EM>then italics, back to</EM>
+bold</STRONG> then normal.
+</BLOCKQUOTE>
+
+<p>Using the old latex syntax, <font color=green><tt>ltoh</tt></font> cannot determine when the bold and
+italic fonts stop being active.
+
+<p>If you have the new latex on your system, use it. If you must use an
+old latex file, convert it to look like new latex as much as possible.
+<OL>
+ <li><strong></strong> Convert all font change macros to use the new latex syntax.
+Namely, convert <CODE><FONT color=navy> {\<EM>XYZ</EM> ... } </FONT></CODE> and <CODE><FONT color=navy>
+\<EM>XYZ</EM> ... \normalfont </FONT></CODE> to <CODE><FONT color=navy>\
+text<EM>XYZ</EM>...</FONT></CODE>.
+
+<p> <li><strong></strong> Use the style file <TT><FONT color=maroon>rq209.sty</FONT></TT> (which should be) included
+with the <font color=green><tt>ltoh</tt></font> distribution, which defines the \text<EM>XYZ</EM>
+macros for use in the old latex.
+
+<p>To use this file, put
+<DIV ALIGN=center>
+ <SAMP>\input{rq209.sty}</SAMP>
+</DIV>
+
+<p>in your latex files. The file <TT><FONT color=maroon>rq209.sty</FONT></TT> additionally defines
+the font size macros
+ <CODE><FONT color=navy>\fsize<EM>Tiny</EM></FONT></CODE>/.../<CODE><FONT color=navy>\fsize
+<EM>Huge</EM></FONT></CODE> which take a single brace-delimited argument. For
+exapmle, use <CODE><FONT color=navy>\fsizesmall{some text}</FONT></CODE> instead of <CODE><FONT color=navy>
+{ \small some text }</FONT></CODE>. (This author wrote <TT><FONT color=maroon>rq209.sty</FONT></TT> back in
+1994 because the office computer ran the old latex but the home Linux
+machine ran the new latex.)
+
+<p>Alternatively, write and use your own definitions of the \
+text<EM>XYZ</EM> font change macros.
+</OL>
+
+<p>(One final note.) The old latex convention is simply a poor technical
+chioce. The current philosophy for document specifications (and even
+programming languages) is that parameters/arguments/blocks are clearly
+delimited syntactically. The use of matching braces by latex2e conforms
+to the the SGML syntax, as does HTML which ubiquitously uses matching
+begin and end tags.
+
+<p><hr><H2><FONT color=blue>Running <font color=green><tt>ltoh</tt></font></FONT></H2></hr>
+
+<p>To generate the HTML file <TT><FONT color=maroon>xyz.html</FONT></TT> from the latex file
+<TT><FONT color=maroon>xyz.tex</FONT></TT>, assuming ltoh is in your path, run:
+
+<p><PRE>
+ prompt&gt; <font color=green><tt>ltoh</tt></font> xyz.tex
+or
+ prompt&gt; perl fullpath-of-ltoh.pl xyz.tex
+</PRE>
+
+<p>(I have not tested <font color=green><tt>ltoh</tt></font> on a Win32 machine, yet...) On a Win32 machine,
+which cannot automatically start Perl to execute the <font color=green><tt>ltoh</tt></font>, you would
+probably run
+
+<p><PRE>
+ prompt&gt; perl <font color=green><tt>ltoh</tt></font>.pl xyz.tex
+</PRE>
+
+<p><hr><H2><FONT color=blue>Specifications</FONT></H2></hr>
+
+<p>There are five types of <font color=green><tt>ltoh</tt></font> specifications. Please note the names.
+
+<p><OL>
+ <li><strong>[Begin/end pair (<CODE><FONT color=navy>b/e</FONT></CODE>)]</strong> Specifies how to translate a latex
+<CODE><FONT color=navy>\begin{XYZ}</FONT></CODE> and matching <CODE><FONT color=navy>\end{XYZ}</FONT></CODE>
+command.
+
+<p> <li><strong>[Command (<CODE><FONT color=navy>comm</FONT></CODE>)]</strong> Specifies how to translate a latex
+command that does not take any parameters, such as <CODE><FONT color=navy>\par</FONT></CODE>,
+<CODE><FONT color=navy>\item</FONT></CODE> or <CODE><FONT color=navy>\hrule</FONT></CODE>.
+
+<p> <li><strong>[Simple-macro (<CODE><FONT color=navy>{}</FONT></CODE>)]</strong> Specifies a translation for a
+latex macro that takes a single brace-delimited argument <EM>arg-1</EM>,
+where the corresponding HTML consists simply of surrounding the argument
+with a preamble and postamble. The translation is simple as the
+argument stays put; <font color=green><tt>ltoh</tt></font> merely puts stuff before and after it. That
+is, we expect
+
+<p><P align=center>
+ <CODE><FONT color=navy>
+ \simplemacro{<EM>...</EM>} <IT> ===&gt; </IT>
+ HTML-preable <EM>...</EM> HTML-postable
+ </FONT></CODE>
+</P>
+
+<p>For example, use a simple-macro specification to translate the latex
+macro <CODE><FONT color=navy>\textbf{ ... }</FONT></CODE> (switch to bold face) into the HTML
+<CODE><FONT color=navy>&lt;strong&gt; ... &lt;/strong&gt;</FONT></CODE>.
+
+<p> <li><strong>[Arg-macro (<CODE><FONT color=navy>{<EM>N</EM>}</FONT></CODE>)]</strong> Specifies a translation
+for a latex macro that takes $N$ brace-delimited arguments; the
+corresponding HTML can make arbitrary use of the arguments. For
+example, my latex macro <CODE><FONT color=navy>\swallow{arg-1}</FONT></CODE> discards its
+single (possibly long) argument. In the corresponding HTML, we also
+``use'' the argument, by discarding it.
+
+<p> <li><strong>[Assignment (<CODE><FONT color=navy>:=</FONT></CODE>)]</strong> An assignment sets a <font color=green><tt>ltoh</tt></font> variable
+which is then used later. As of version 97e, only a small number
+of built-in variables are supported. I hope to support setting and
+getting user-defined variables in the future.
+
+<p>
+
+<p></OL>
+
+<p>The first four specications are known as translations specifications.
+
+<p><H3><FONT color=teal>Translation specifications</FONT></H3>
+
+<p>The four types of translation specifications have the same form. Do not
+use leading whitespace. Here is the general form and an example of each
+type.
+
+<pre>
+:type :latex-macro-name:HTML-start-code:HTML-end-code:reserved/not-used
+
+:b/e :\begin{itemize}:&lt;UL&gt;:&lt;/&gt;:
+:comm :\hrule:&lt;hr&gt;::
++comm +\homepage+http://www.best.com/~quong++
+:{} :\textbf:&lt;STRONG&gt;:&lt;/&gt;:
+:{2} :\rqhttp#1#2:&lt;a href="#2"&gt; #1 &lt;/a&gt;::
+</pre>
+<p>
+Each specification contains six parts.
+
+<p><OL>
+ <li><strong></strong> The first character on the line is the <EM>separator</EM> char,
+which delimits the remaining parts of the specification. The separator
+char can be any character. I have used a colon (:) and a plus sign (+)
+in the above examples. Note that the <CODE><FONT color=navy>\homepage</FONT></CODE> macro
+expands to HTML containing a colon, so a colon cannot be the delimiter
+and I have used a plus. I do not recommend using a space/tab as the
+delimiter, as multiple spaces/tabs are easy to overlook.
+
+<p> <li><strong></strong> The <EM>type</EM>. If the type is arg-macro, the number of
+parameters is specified in the braces. Arbitrary space may follow the
+type.
+
+<p> <li><strong></strong> The <EM>latex macro name</EM> specifies the latex macro to be
+translated. A latex macro must start with a backslash (if you have
+redefined the LaTeX2<it>e</it> catcodes, sorry). An optional Perl regular
+expression can following the macro name, to account for parameters for
+the macro. Usually the latex parameters are just discarded in the
+resulting HTML.
+
+<p>As an example of an optional regular expression, the LaTeX2<it>e</it> horizontal
+space command <CODE><FONT color=navy>\hspace</FONT></CODE> takes an optional <CODE><FONT color=navy>*</FONT></CODE>
+argument, and then a required horizontal length argument. In the
+generated HTML, we want to ignore the entire <CODE><FONT color=navy>\hspace</FONT></CODE>
+macro, and so I use the following <font color=green><tt>ltoh</tt></font> spec.
+
+<pre>
+:comm :\hspace[*]?\{[^\}]+\}:::
+</pre>
+<p>
+ <li><strong></strong> The <EM>HTML start code</EM> is the HTML code to insert
+when the macro is first seen.
+
+<p><OL>
+ <li><strong>[begin/end pair]</strong> The <CODE><FONT color=navy>\beginXXX</FONT></CODE> expands to
+<EM>HTML start code</EM>.
+ <li><strong>[command]</strong> The LaTeX2<it>e</it> macro expands to <EM>HTML start code</EM>.
+ <li><strong>[Simple-macro]</strong> The opening brace expands to <EM>HTML start
+code</EM>; the closing brace expands to <EM>HTML end code</EM>.
+ <li><strong>[arg-macro]</strong> The command and all its arguments expands to
+<EM>HTML start code</EM>.
+</OL>
+
+<p>In an arg-macro specification, using the LaTeX2<it>e</it> convention, the first
+argument is represented by #1, the second argument by #2, and so on in
+the HTML start code. (To actually generate a <CODE><FONT color=navy>\#1</FONT></CODE>, use
+braces as in #{1}.) Thus, a macro that swaps the order of its
+parameters would be written as
+
+<pre>
+:{2} :\swap_two:#2#1::
+</pre>
+<p>
+As another example, the LaTeX2<it>e</it> <CODE><FONT color=navy>\makebox</FONT></CODE> command takes an
+optional alignment parameter (one of <CODE><FONT color=navy>[l]</FONT></CODE>, <CODE><FONT color=navy>[c]</FONT></CODE> or
+<CODE><FONT color=navy>[r]</FONT></CODE>) followed by text to be put into the box. I use the
+following <font color=green><tt>ltoh</tt></font> spec to ignore the alignment parameter and to print the
+text out unadorned.
+
+<pre>
+:{1} :\makebox[^{]*#1:#1::
+</pre>
+<p>
+ <li><strong></strong> The <EM>HTML end code</EM> specifier is the HTML code to insert
+at $(i)$ the end of a begin-end pair or $(ii)$ the closing brace of a
+simple-macro. Note that the <EM>HTML end code</EM> specifier does not
+make sense for a <EM>command</EM> or <EM>arg-macro</EM> specification
+and is ignored.
+
+<p>As a convenience, using <CODE><FONT color=navy>&lt;/&gt;</FONT></CODE> in the <EM>HTML end code</EM>
+expands to the end tag(s) in reverse order of the corresponding HTML
+begin code. For example, I want a LaTeX2<it>e</it> <CODE><FONT color=navy>\section</FONT></CODE> to show
+up as a green &lt;H2&gt; header in HTML, so I specify
+
+<pre>
+:{} :\section:&lt;hr&gt;&lt;H2&gt;&lt;FONT color=green&gt;:&lt;/&gt;:
+</pre>
+<p>
+which is equivalent to
+
+<pre>
+:{} :\section:&lt;hr&gt;&lt;H2&gt;&lt;FONT color=green&gt;:&lt;/FONT&gt;&lt;/H2&gt;&lt;/HR&gt;:
+</pre>
+<p>
+</OL>
+
+<p>The following table summarizes the effects of the various
+specifications, and the parts of the spefications used.
+
+<p><CODE><FONT color=navy>
+<table border>
+<TR> <TD align=left> Type </TD> <TD align=left> macro name </TD> <TD align=left> HTML start </TD> <TD align=left> HTML end </TD> <TD align=left> </TD> <TD align=left> input </TD> <TD align=left> output </TD></TR>
+<TR> <TD align=left> comm </TD> <TD align=left> \abc </TD> <TD align=left> XYZ </TD> <TD align=left> not-used </TD> <TD align=left> </TD> <TD align=left> \abc </TD> <TD align=left> XZY </TD></TR>
+<TR> <TD align=left> b/e </TD> <TD align=left> \begin{abc} </TD> <TD align=left> XYZ </TD> <TD align=left> ijk </TD> <TD align=left> </TD> <TD align=left> \begin{abc}...\end{abc} </TD> <TD align=left> XZY ... ijk </TD></TR>
+<TR> <TD align=left> {} </TD> <TD align=left> \abc </TD> <TD align=left> XYZ </TD> <TD align=left> ijk </TD> <TD align=left> </TD> <TD align=left> \abc{...} </TD> <TD align=left> XYZ... ijk </TD></TR>
+<TR> <TD align=left> {2} </TD> <TD align=left> \abc </TD> <TD align=left> X#2Y#1Z </TD> <TD align=left> not-used </TD> <TD align=left> </TD> <TD align=left>\abc{===}{+++} </TD> <TD align=left>
+X+++Y===Z </TD></TR>
+</table>
+</FONT></CODE>
+
+<p>As a final example, here's how generate links in HTML. I define a latex
+macro <CODE><FONT color=navy>\rqhttp</FONT></CODE> and a corresponding <font color=green><tt>ltoh</tt></font> specficiation.
+Because the tilde is accessible only in math mode, I have had to define
+a latex macro (<CODE><FONT color=navy>\rqtilde</FONT></CODE>) for it, too.
+
+<p><PRE>
+(latex macro)
+<CODE><FONT color=navy>\def\rqtilde{\ensuremath{\tilde{\;}}\xspace}</FONT></CODE>
+<CODE><FONT color=navy>\def\rqhttp#1#2{#1 (\texttt{#2})}</FONT></CODE>
+(<font color=green><tt>ltoh</tt></font> spec)
+<CODE><FONT color=navy>:comm :\rqtilde:~::</FONT></CODE>
+<CODE><FONT color=navy>:2 :\rqhttp#1#2:&lt;a href="#2"&gt; #1 &lt;/a&gt;::</FONT></CODE>
+</PRE>
+
+<p>In LaTeX2<it>e</it>, I use the <CODE><FONT color=navy>\rqhttp</FONT></CODE> macro as follows.
+
+<p><BLOCKQUOTE>
+ See the \rqhttp{\ltoh
+ webpage}{http://www.best.com/\rqtilde{}quong/ltoh}.
+</BLOCKQUOTE>
+
+<p>The resulting dvi output from latex and the HTML from <font color=green><tt>ltoh</tt></font> look like
+
+<p><PRE>
+ (Latex) See the ltoh web page (http://www.best.com/~quong/ltoh).
+
+<p> (HTML) See the &lt;A HREF="http://www.best.com/~quong/ltoh"&gt; ltoh web page &lt;/A&gt;
+</PRE>
+
+<p><hr>
+
+<p>Finally, good example of using <font color=green><tt>ltoh</tt></font> specifiers is the default <font color=green><tt>ltoh</tt></font> spec file
+<TT><FONT color=maroon>ltoh.specs</FONT></TT> that comes with this release.
+
+<p>[Aside: Technically, the <CODE><FONT color=navy>simple-macro</FONT></CODE> specifier is not needed,
+as its functionality can be duplicated with an <CODE><FONT color=navy>arg-macro</FONT></CODE>.
+Namely,
+<pre>
+:{} :\macro:HTML-begin:HTML-end::
+</pre>
+
+<p>can be duplicated via
+
+<pre>
+:{1} :\macro:HTML-begin#1HTML-end:::.
+</pre>
+<p>
+Nonetheless, use of a simple-macro { } specifiction is preferred,
+because its processing is much simpler. With a simple-macro, <font color=green><tt>ltoh</tt></font> does
+not have to extract and pass the parameter, and hence it is less likely
+to break than an arg-macro.]
+
+<p><H3><FONT color=teal>Assignment</FONT></H3>
+
+<p>An assignment specification has two nearly identical forms. The double
+quotes are optional and can be used to imbed leading spaces into the
+string-value. The whitespace surrounding string-value is removed.
+
+<p><PRE>
+ variable-name := string-value
+ variable-name := "string-value"
+
+<p> title := The readme for ltoh
+</PRE>
+
+<p>Here are the currently used built-in variables.
+
+<p><table border>
+<TR> <TD align=left> variable </TD> <TD align=left> Default </TD> <TD align=left> Description </TD></TR>
+<TR> <TD align=left> <CODE><FONT color=navy>title</FONT></CODE> </TD> <TD align=left> <CODE><FONT color=navy>none</FONT></CODE> </TD> <TD align=left> Title of the resulting HTML file, via
+the <CODE><FONT color=navy>&lt;TITLE&gt;</FONT></CODE> tag. <STRONG><FONT color=maroon>You must define this variable.</FONT></STRONG>
+Set <CODE><FONT color=navy>title</FONT></CODE> in the latex file itself. (It drives me nuts when
+web pages don't have titles) </TD></TR>
+<TR> <TD align=left> <CODE><FONT color=navy>url</FONT></CODE> </TD> <TD align=left> <CODE><FONT color=navy>none</FONT></CODE> </TD> <TD align=left> URL of the home page of the author. </TD></TR>
+<TR> <TD align=left> <CODE><FONT color=navy>author</FONT></CODE> </TD> <TD align=left> <CODE><FONT color=navy>none</FONT></CODE> </TD> <TD align=left> Author of the document. </TD></TR>
+<TR> <TD align=left> <CODE><FONT color=navy>email</FONT></CODE> </TD> <TD align=left> <CODE><FONT color=navy>none</FONT></CODE> </TD> <TD align=left> Email address to which comments
+should be sent </TD></TR>
+<TR> <TD align=left> <CODE><FONT color=navy>htmlfile_spec</FONT></CODE> </TD> <TD align=left> <CODE><FONT color=navy>$BASE.html</FONT></CODE> </TD> <TD align=left> Name of HTML file
+generated. The <font color=green><tt>ltoh</tt></font> variable <CODE><FONT color=navy>$BASE</FONT></CODE> is the
+latex file name stripped of the directory and suffix components. </TD></TR>
+</table>
+
+<p>The <CODE><FONT color=navy>url</FONT></CODE>, <CODE><FONT color=navy>author</FONT></CODE>, and <CODE><FONT color=navy>email</FONT></CODE> variables are used
+to generate an address block at the bottom of the HTML page. (See the
+bottom of this document if you are reading it on the web).
+
+<p><hr><H2><FONT color=blue>Tables</FONT></H2></hr>
+
+<p><font color=green><tt>ltoh</tt></font> handles the LaTeX2<it>e</it> <CODE><FONT color=navy>tabular</FONT></CODE> and <CODE><FONT color=navy>tabularx</FONT></CODE>
+environments. Column alignments are read and passed onto the
+corresponding HTML. The known column alignments must be one of `` l c r
+p X''. If you define your own column alignment, it will not be
+understood.
+
+<p><font color=green><tt>ltoh</tt></font> handles the LaTeX2<it>e</it> <CODE><FONT color=navy>multicolumn</FONT></CODE> macro reasonably well.
+The column alignment is read and passed onto the corresponding HTML.
+
+<p>I plan to support the <CODE><FONT color=navy>\multirow</FONT></CODE> macro soon.
+
+<p><font color=green><tt>ltoh</tt></font> ignores extraneous LaTeX2<it>e</it> specs in the column alignment
+specifications, such as <CODE><FONT color=navy>\@</FONT></CODE>, but there is a small
+chance a complicated multiple column alignment spec will break this
+code.
+
+<p>The generated HTML table has a border if one or more dividing lines in
+the LaTeX2<it>e</it> table column alignment (namely if a $|$ specifier appears in
+the latex, the HTML table has a border). Nested tables are not
+supported, and I currently do not plan to support them, as this feature
+seems hard.
+
+<p><hr><H2><FONT color=blue>Where are specifications found?</FONT></H2></hr>
+
+<p>As of version 97e, <font color=green><tt>ltoh</tt></font> reads specifications from $(i)$
+various specification-files and $(ii)$ from the LaTeX2<it>e</it> file itself as it
+is being processed, as follows.
+
+<p><OL>
+ <li><strong></strong> Reads the specification file <TT><FONT color=maroon>ltoh.specs</FONT></TT> from the
+<TT><FONT color=maroon>install-dir</FONT></TT>, which is the directory where you have placed both
+<TT><FONT color=maroon>ltoh.pl</FONT></TT> and <TT><FONT color=maroon>ltoh.specs</FONT></TT>. The <TT><FONT color=maroon>install-dir</FONT></TT> can
+be anywhere.
+
+<p>(In version 97e, you should do one of the following when running
+<font color=green><tt>ltoh</tt></font>.
+<OL>
+ <li><strong></strong> Run <font color=green><tt>ltoh</tt></font> via:
+
+<p><SAMP>prompt&gt; perl install-dir/ltoh.pl file.tex</SAMP>.
+
+<p> <li><strong></strong> Set up an alias as follows:
+
+<p>(csh) <SAMP>alias ltoh perl install-dir/ltoh</SAMP> <br>
+or<br>
+(bash) <SAMP>alias ltoh=perl install-dir/ltoh</SAMP>
+
+<p> <li><strong></strong> Put <TT><FONT color=maroon>install-dir</FONT></TT> in your path, and run:
+
+<p><SAMP>prompt&gt; ltoh.pl file.tex</SAMP>
+
+<p> <li><strong></strong> Set up a single symbolic link, say called <TT><FONT color=maroon>ltoh</FONT></TT>, in your
+path which points directly to <TT><FONT color=maroon>install-dir/ltoh.pl</FONT></TT>. You can
+then run
+
+<p><SAMP>prompt&gt; ltoh file.tex</SAMP>
+
+<p></OL>
+
+<p>This mess is relative symbolic links. Yes. Given an arbitrary
+invocation of <font color=green><tt>ltoh</tt></font> involving symbolic links, I cannot currently
+determine where the <TT><FONT color=maroon>ltoh.pl</FONT></TT> script actually resides (the
+<TT><FONT color=maroon>install-dir</FONT></TT>). Once I implement this code, the setup won't be
+complicated.
+
+<p> <li><strong></strong> Reads the specification file <TT><FONT color=maroon>.ltoh.specs</FONT></TT> in your home directory.
+ <li><strong></strong> Reads the specification file <TT><FONT color=maroon>.ltoh.specs</FONT></TT> in the current
+directory, where the command is being run.
+
+<p> <li><strong></strong> If any of these specification files exist, <font color=green><tt>ltoh</tt></font> proceeds to the
+next step reading the LaTeX2<it>e</it> input file
+
+<p>However, if none of the preceding spec files were, <font color=green><tt>ltoh</tt></font> tries to read
+
+<p><TT><FONT color=maroon>/usr/local/bin/ltoh.specs</FONT></TT> and that fails, tries
+<TT><FONT color=maroon>/usr/bin/ltoh.specs</FONT></TT>. If both of these still fail, <font color=green><tt>ltoh</tt></font>
+<STRONG><FONT color=maroon>quits</FONT></STRONG>.
+
+<p> <li><strong></strong> Reads specifications from the latex file being processed, which
+appear as latex comments of the form
+
+<p><P align=center><CODE><FONT color=navy>%-ltoh- <EM>ltoh-specification</EM></FONT></CODE></P>.
+
+<p><font color=green><tt>ltoh</tt></font> strips the leading <CODE><FONT color=navy>%-ltoh- </FONT></CODE> and processes the
+remainder of the line.
+
+<p>If nothing else, set the <CODE><FONT color=navy>title</FONT></CODE> variable this way. For example,
+here's how this LaTeX2<it>e</it> file starts.
+
+<pre>
+\documentclass[]{article}
+... various latex commands like \usepackage
+%-ltoh- title := Ltoh, a customizable LaTeX to HTML converter
+%-ltoh- :comm:\ltoh:&lt;font color=green&gt;&lt;tt&gt;ltoh&lt;/tt&gt;&lt;/font&gt;::
+...
+\begin{document}
+... the body of the document
+</pre>
+<p>
+</OL>
+
+<p><hr><H2><FONT color=blue>Limitations, bugs, missing features</FONT></H2></hr>
+
+<p><H3><FONT color=teal>Limitations</FONT></H3>
+
+<p><OL>
+ <li><strong></strong> Specifications are applied only once to a latex macro. Namely
+if a macro <EM>macroAA</EM> generates a macro <EM>macroBB</EM> in latex,
+and <EM>macroBB</EM> is translated to <EM>htmlBB</EM>, then you must
+specify to <font color=green><tt>ltoh</tt></font> that <EM>macroAA</EM> is translated directly to
+<EM>htmlBB</EM> in your specification for <EM>macroAA</EM>.
+</OL>
+
+<p><H3><FONT color=teal>Bugs</FONT></H3>
+
+<p>It is not difficult to break <font color=green><tt>ltoh</tt></font>, though there are often easy fixes by
+restructuring your LaTeX2<it>e</it>.
+
+<p><H3><FONT color=teal>Missing features</FONT></H3>
+
+<p><OL>
+ <li><strong></strong> There are no command line flags. The following would be
+particularly useful.
+
+<p><table border>
+<TR> <TD align=left> -o <EM>ofile</EM> </TD> <TD align=left> generate HTML into file <EM>ofile</EM> </TD></TR>
+<TR> <TD align=left> -I <EM>specfile</EM> </TD> <TD align=left> read specifications from <EM>specfile</EM> </TD></TR>
+<TR> <TD align=left> -w N </TD> <TD align=left> set the warning level to N (for debugging) </TD></TR>
+</table>
+
+<p> <li><strong></strong> There no means to manipulate counters, which would be useful for
+sectioning commands.
+
+<p> <li><strong></strong> There should be away to set and get a value as part of a
+specification.
+
+<p> <li><strong></strong> If the input uses LaTeX2<it>e</it> sectioning macros, optionally generate
+a table of contents with links to anchors.
+
+<p> <li><strong></strong> Allow for an abitrary prologue and epilogue in the HTML file.
+
+<p> <li><strong></strong> In a table, we assume that the column alignment specs are on the
+same line as the owning <CODE><FONT color=navy>\begin{tabular}</FONT></CODE> or the owning
+<CODE><FONT color=navy>\multicolumn</FONT></CODE>. This assumption is very reasonable and
+circumventing this restriction is difficult.
+</OL>
+
+<p><hr><H2><FONT color=blue>Internal details</FONT></H2></hr>
+
+<p><font color=green><tt>Ltoh</tt></font> first reads the entire LaTeX2<it>e</it> file into memory, makes several
+passes over the data, and finally spits out the HTML file<font size=-1>[Thus,
+it is conceivable that <font color=green><tt>ltoh</tt></font> might run out of memory if processing a
+huge LaTeX2<it>e</it> file on a machine with limited memory.]</font> The passes are
+roughly as follows.
+
+<p><OL>
+ <li><strong></strong> Read spec files.
+ <li><strong></strong> Handle comments and the verbatim environment.
+ <li><strong></strong> Escape/protect characters.
+ <li><strong></strong> Handle tables.
+ <li><strong></strong> Handle begin/end pairs.
+ <li><strong></strong> Handle LaTeX2<it>e</it> commands without parameters.
+ <li><strong></strong> Mark braces, linking braces to macros.
+ <li><strong></strong> Handle simple macros.
+ <li><strong></strong> Handle arg macros.
+ <li><strong></strong> Generate HTML.
+</OL>
+
+<p><hr><H2><FONT color=blue>History</FONT></H2></hr>
+
+<p>
+
+<p><table border>
+<TR> <TD align=left> June 1996 </TD> <TD align=left> Version 96a. Preliminary fully hard-coded (not
+customizable) version.
+ Purely regular expression based. Unable to handle nested braces.
+Ugly, but it worked. Sort of.
+ </TD></TR>
+<TR> <TD align=left>
+ July 1-15 1996 </TD> <TD align=left> Version 96b. First working version. Able to handle
+commands with multiple arguments and nested arguments. Took me a lot
+longer than I had expected to get this working.
+</TD></TR>
+<TR> <TD align=left>
+ Jan 27-29 1997 </TD> <TD align=left> Version 97a. Stops processing at
+<CODE><FONT color=navy>\end{document}</FONT></CODE>. Convert double back slashes
+\\to <CODE><FONT color=navy>&lt;br&gt;</FONT></CODE>, which should have done a long time ago.
+Fixed bug involving macros with only one parameter.
+</TD></TR>
+<TR> <TD align=left>
+ Feb 1997 </TD> <TD align=left> Version 97b. Added HTML <CODE><FONT color=navy>&lt;p&gt;</FONT></CODE> tags whenever
+two or more consecutive blank lines are seen.
+</TD></TR>
+<TR> <TD align=left>
+ Mar 11-15 1997 </TD> <TD align=left> Version 97c. Much improved handling of special
+characters such as {, }, &lt;, &gt; and @. In particular, bare braces
+which mean nothing in latex are stripped from the HTML. Improved
+paragraph detection handling. (OK, OK, "Improved ..." really means
+"fixed bugs in ..."). No longer generates HTML comments for latex
+comments, by default. Version 97c was meant to be first public release,
+but the tables this <TT><FONT color=maroon>readme.tex</FONT></TT> document broke <font color=green><tt>ltoh</tt></font> badly.
+</TD></TR>
+<TR> <TD align=left>
+ Mar 19-20 1997 </TD> <TD align=left> Version 97d. Complete rewrite of the table handling
+code. Latex column alignment specifications are understood and passed
+onto to the HTML. Multiple columns specified via either
+<CODE><FONT color=navy>\multicolumn</FONT></CODE> or <CODE><FONT color=navy>\mc</FONT></CODE> (which is my personal
+abbreviation macro) are handled properly. We try to ignore extraneous
+LaTeX2<it>e</it> specs in the column alignment specifications, such as
+<CODE><FONT color=navy>@</FONT></CODE>.
+, but there is there is a small chance multiple
+columns
+
+<p>In particular, <font color=green><tt>ltoh</tt></font> now handles this file (<TT><FONT color=maroon>readme.tex</FONT></TT>)
+properly.
+</TD></TR>
+<TR> <TD align=left>
+ Mar 25-31 1997 </TD> <TD align=left> Version 97e. Official release. Clean up source a
+bit for release. Minor improvements on tables (allow end of a row to be
+on a separate line), paragraphs, specification files and handling
+special characters (allow for multiple chars on one line). </TD></TR>
+</table>
+
+<p><hr><H2><FONT color=blue>License for use</FONT></H2></hr>
+
+<p>You may use <font color=green><tt>ltoh</tt></font> freely, under the following conditions, which are
+covered under a BSD-style license.
+
+<p><OL>
+ <li><strong></strong> You must keep the <font color=green><tt>ltoh</tt></font> notice at the end of all generated HTML.
+This notice indicates how the document was generated (namely, with
+<font color=green><tt>ltoh</tt></font>) and has a link to the <font color=green><tt>ltoh</tt></font> web page. You may reduce the size of
+the notice if you wish, but it must remain in your document and visible.
+
+<p> <li><strong></strong> <font color=green><tt>Ltoh</tt></font> comes with neither a warranty nor a gaurantee about its
+correctness, performance, or suitability for any task.
+
+<p> <li><strong></strong> If you modify or redistribute <font color=green><tt>ltoh</tt></font>, you must keep the current
+disclaimer and license with the <font color=green><tt>ltoh</tt></font> source which must be visible upon
+startup, unless you
+
+<p> <li><strong></strong> I, Russell Quong, retain the copyright for <font color=green><tt>ltoh</tt></font>.
+</OL>
+
+<p><H3><FONT color=teal>Official software license</FONT></H3>
+
+<p>Here's the official license as of 31 Mar 97.
+
+<pre>
+# Copyright (c) 1996, 1997 Russell W Quong.
+#
+# In the following, the "author" refers to "Russell Quong."
+#
+# Permission to use, copy, modify, distribute, and sell this software and
+# its documentation for any purpose is hereby granted without fee, provided
+# that the following conditions are met:
+# 1. Redistributions of source code must retain the above copyright
+# notice, this list of conditions and the following disclaimer.
+# 2. All advertising materials mentioning features or use of this software
+# must display the following acknowledgement:
+# This product includes software developed by Russell Quong.
+# 3. All HTML generated by ltoh must retain a visible notice that it
+# was generated by ltoh and contain a link to the ltoh web page
+#
+# Any or all of these provisions can be waived if you have specific,
+# prior permission from the author.
+#
+# THE SOFTWARE IS PROVIDED "AS-IS" AND WITHOUT WARRANTY OF ANY KIND,
+# EXPRESS, IMPLIED OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY
+# WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
+#
+# IN NO EVENT SHALL RUSSELL QUONG BE LIABLE FOR ANY SPECIAL,
+# INCIDENTAL, INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY KIND, OR ANY
+# DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
+# WHETHER OR NOT ADVISED OF THE POSSIBILITY OF DAMAGE, AND ON ANY
+# THEORY OF LIABILITY, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+# PERFORMANCE OF THIS SOFTWARE.
+</pre>
+<p>
+<hr><H2><FONT color=blue>Motivation</FONT></H2></hr>
+
+<p>(The motivation section belongs right after the introduction, but most
+people probably just want to get on with using <font color=green><tt>ltoh</tt></font>. So this section
+has been relegated here. Ah well...)
+
+<p>Although other LaTeX2<it>e</it> to HTML converters exist, I wrote my own because I
+wanted to generate HTML customized to my own liking. In particular, I
+use my own custom LaTeX2<it>e</it> definitions (who doesn't?) and wanted to
+generate HTML appropriately. Additionally, when using other converters,
+I was unable get them to run properly, or I did not like the way the
+generated HTML looked.
+
+<p>Fundamentally, <font color=green><tt>ltoh</tt></font> is a specialized macro processor that reads macro
+<EM>specifications</EM> and generates HTML accordingly. A specification
+indicates how to convert a specific LaTeX2<it>e</it> definition into HTML.
+
+<p>My orginal goals in writing <font color=green><tt>ltoh</tt></font> were
+
+<p><OL>
+ <li><strong></strong> To become more proficient in Perl.
+
+<p> <li><strong></strong> To write a converter that allowed customized HTML to be
+generated.
+
+<p> <li><strong></strong> To handle arbitrary LaTeX2<it>e</it> macros, including macros that take
+multiple arguments, and arguments that contained nested macros.
+
+<p> <li><strong></strong> To generate HTML that resembled the original LaTeX2<it>e</it>, as if
+someone had done the translation by hand. In particular, I wanted to
+avoid generating very long lines of HTML source, which are difficult to
+read when ``viewing the source'' in a browser.
+</OL>
+
+<p><hr><H2><FONT color=blue>Acknowledgements</FONT></H2></hr>
+
+<p>Thanks to <a href="http://www.varesearch.com"> VA Research </a> for letting the author work on
+<font color=green><tt>ltoh</tt></font>.
+
+<p><HR>
+<font size=+0><EM>[Converted LaTeX --> HTML by <a href="http://www.best.com/~quong/ltoh.html">ltoh</a>]</EM></font><br>
+<ADDRESS>
+<A href="http://www.best.com/~quong">Russell W. Quong</A>
+(<A href="mailto:quong@best.com"><SAMP>quong@best.com</SAMP></A>)
+Last modified: <font color=maroon><samp>Apr 1 1997</samp></font>
+</ADDRESS>
+</BODY>
+</HTML>