summaryrefslogtreecommitdiff
path: root/support/ltoh/readme.html
blob: 4ab8f4944440f5a420402240943312eb573a0e90 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
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>