diff options
author | Norbert Preining <norbert@preining.info> | 2019-09-02 13:46:59 +0900 |
---|---|---|
committer | Norbert Preining <norbert@preining.info> | 2019-09-02 13:46:59 +0900 |
commit | e0c6872cf40896c7be36b11dcc744620f10adf1d (patch) | |
tree | 60335e10d2f4354b0674ec22d7b53f0f8abee672 /support/ltoh/readme.html |
Initial commit
Diffstat (limited to 'support/ltoh/readme.html')
-rw-r--r-- | support/ltoh/readme.html | 777 |
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> <font color=green><tt>ltoh</tt></font> xyz.tex +or + prompt> 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> 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> ===> </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><strong> ... </strong></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}:<UL>:</>: +:comm :\hrule:<hr>:: ++comm +\homepage+http://www.best.com/~quong++ +:{} :\textbf:<STRONG>:</>: +:{2} :\rqhttp#1#2:<a href="#2"> #1 </a>:: +</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></></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 <H2> header in HTML, so I specify + +<pre> +:{} :\section:<hr><H2><FONT color=green>:</>: +</pre> +<p> +which is equivalent to + +<pre> +:{} :\section:<hr><H2><FONT color=green>:</FONT></H2></HR>: +</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:<a href="#2"> #1 </a>::</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 <A HREF="http://www.best.com/~quong/ltoh"> ltoh web page </A> +</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><TITLE></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> 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> 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> 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:<font color=green><tt>ltoh</tt></font>:: +... +\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><br></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><p></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 {, }, <, > 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> |