OGIP Memo OGIP/95-001

A Demonstration of LaTeX and the use of latex2html

http://legacy.gsfc.nasa.gov/docs/bios/imgeorge.html, http://legacy.gsfc.nasa.gov/docs/bios/turner.html & Bob Crosier

Code 668,
NASA/GSFC,
Greenbelt,
MD 20771

Version: 1995 Feb 08 (DRAFT)

SUMMARY

This document demonstrates a number of facilities provided by the word-processing language LaTeX, and their use in conjunction with the latex2html conversion software.

It is anticipated that this document will grow dramatically in details and examples as the authors become more experienced. Comments, suggestion & contributions are most welcome.

NOTE:
THIS IS NOT AN OFFICIAL MANUAL FOR THE LATEX OR LATEX2HTML (and related) SOFTWARE PACKAGES, MERELY A DEMONSTRATION DOCUMENT INTENDED PRIMARILY FOR INTERNAL OGIP USE

LOG OF SIGNIFICANT CHANGES

Release	Sections Changed	Brief Notes
Date

1994 Nov 17		First draft
1995 Feb 07	All	Updates & Corrections

1 INTRODUCTION

The role of this document is two-fold:
1) to demonstrate a number of facilities provided by the word-processing language LaTeX, and in particluar its use in conjunction with the latex2html package,
2) to list common problems people encounter with running latex2html and (hopefully) solutions or suggestions.

It is anticipated that this document will grow dramatically in details and examples as the authors become more experienced. Comments, suggestion & contributions are of course most welcome.

Again we emphasis that this document is NOT an official manual for the latex or latex2html (and related) software packages. It is merely a demonstration document, and as such is intended primarily for internal http://legacy.gsfc.nasa.gov/0 use.

Experienced LaTeXperts will probably be most interested in Sections , and . However, for the un-initiated, in Section , we briefly outline the LaTeX and latex2html software packages, along with some propaganda regarding their use. A brief description on where to obtain and how to install the software is given in Section .

2 WHAT ARE LaTeX AND latex2html ?

For those uninitiated, this section provides a brief introduction to the two software packages.

2.1 What is LaTeX ?

LaTeX (most commonly pronounced Lay-teck) is a document preparation package which sits on top of TeX (Teck). The latter was designed to produce high-quality typesetting, with a particular emphasis on mathematical text commonly used within science. TeX is extremely powerful (ie flexible), but as a result can be rather difficult to use by the non-expert. LaTeX is an attempt to keep the flexiblity & functionality, but wrap some of the more commonly used functions into more user-friendly commands.

Further information on LaTeX is available in the LaTeX User's Guide & Reference Manual (paperback; ISBN 0-202-15790-X) by Leslie Lamport (Addison-Wesley Publishing Company).

2.2 What is latex2html ?

latex2html is essentially a translator between the LaTeX language and html written by http://cbl.leeds.ac.uk/nikos/personal.html (nikos@cbl.leeds.ac.uk), Computer Based Learning Unit, University of Leeds, UK.

Below are some of its highlights, adapted from the README file. The translator:

breaks up a document into one or more components as specified by the user,
provides optional iconic navigation panels on every page which contain links to other parts of the document,
handles inlined equations, right-justified numbered equations, tables, or figures and any arbitrary environment,
can produce output suitable for browsers that support inlined images or character based browsers (as specified by the user),
handles definitions of new commands, environments, and theorems even when these are defined in external style files,
handles footnotes, tables of contents, lists of figures and tables, bibliographies, and can generate an index,
translates cross-references into hyperlinks and extends the LaTeX cross-referencing mechanism to work not just within a document but between documents which may reside in remote locations,
translates accent and special character commands to the equivalent ISO-LATIN-1 character set where possible,
recognizes hypertext links (to multimedia resources or arbitrary internet services such as sound/video/ftp/http/news) and links which invoke arbitrary program scripts, all expressed as LaTeX commands,
recognizes conditional text which is intended only for the hypertext version, or only for the paper (DVI) version,
can include raw HTML in a LaTeX document (e.g. in order to specify interactive forms),
can deal sensibly at least with the Common LaTeX commands summarized at the back of the LaTeX blue book,
will try and translate any document with embedded LaTeX commands irrespective of whether it is complete or syntactically legal.

The latex2html program includes its own manual, which is also available via the WWW http://cbl.leeds.ac.uk/nikos/tex2html/doc/manual/manual.html.

Further information is available on the WWW at the http://cbl.leeds.ac.uk/nikos/tex2html/doc/latex2html/latex2html.html, including an overview, the manual, bug reporting forms, etc etc.

3 SYSTEM REQUIREMENTS

This section describes where to find the LaTeX and latex2html software, how to install it and make it available to users. As such it is primarily intended for system adminstrators. It is suggested that general users first simply try using the software (Section ), and checking with their system adminstrators as to whether the packages are indeed already available only if it fails.

3.1 Getting and installing LaTeX

Section Incomplete

Contributions are welcomed (to george@lheavx.gsfc.nasa.gov)

3.2 Getting and installing latex2html

latex2html can be obtained via the WWW as a http://cbl.leeds.ac.uk/nikos/tex2html/latex2html.tar as well as a number of other sites.

Section Incomplete

Contributions are welcomed (to george@lheavx.gsfc.nasa.gov)

4 RUNNING LATEX, LATEX2HTML & ASSOCIATED S/W

This section describes how a user runs either the LATEX or latex2html software. It is assumed that all the necessary software has been installed and is accessible to then as described in Section 3.

4.1 Running LaTeX

Once one has written the LaTeX 'source-code' into a file (say called yourfile.tex), then LaTeX is run by:

latex yourfile.tex

(the .tex extension can be left off if there is only one period in the filename). LaTeX will dump various pieces of information during the run, along with any error or warning messages.

Errors will cause LaTeX to stop with a ? prompt along with some information regarding the nature of the error. Errors are usually the result of typographical errors in the *.tex file. One has a number of options when faced with the ? prompt (which can be listed by typing ? ? prompt) including getting a limited about of further help (h), skipping to be next error (s), quiting LaTeX (x), or editing your *.tex file (e). Further ionformation on the causes and solutions to errors is beyond the scope of this memo, but can be found in the LaTeX User's Guide & Reference Manual (paperback; ISBN 0-202-15790-X) by Leslie Lamport (Addison-Wesley Publishing Company).

Warnings are usually straighforward and are related to either the fact that LaTeX should be run again, or that something is missing or multiply defined. Again consultation of the LaTeX User's Guide & Reference Manual is advised. if the messages aren't 'obvious'. NOTE: Warning messages concerning undefined references will ALWAYS to produced on the initial LaTeX run of a document making use of the automatic cross-referencing facilities (see Section ).

Assuming successful completion, LaTeX will produce several files in the local directory with the yourfile root. Probably the most inportant is the *.dvi file (ie yourfile.dvi in the above example) which serves as the input to several associated software tasks (see the following sections). The other files produced depend somewhat in which features of LaTeX are used in the *.tex file. For example a *.toc is (only) produced if the LaTeX command \tableofcontents is included in the *.tex file. Most of these files are ASCII and can be inspected. Unless you are an expert, we'd recommend NOT deleting any of the files produced by a successful LaTeX run since many are also required by the associated software such as those listed in the following sections.

4.2 Running latex2html

Once one has run LaTeX (Section 4.1) one can run latex2html simply by:

latex2html yourfile.tex

(where yourfile.tex is the name of the *.tex file input to LaTeX). latex2html will pick up any of the other files which resulted from the LaTeX run (such as postscript files containing figures, tables of contents etc) based upon the contents of the *.tex file. Various pieces of information will be dumped during the latex2html run, along with any error or warning messages.

latex2html has a relatively large number of command-line options plus a bunch of default parameters & values in the .latex2html-init, which control where the output files are written, how the document is split, how images are included, what goes at the header and footer of the html pages etc. These are described in detail in the latex2html manual (see the http://cbl.leeds.ac.uk/nikos/tex2html/doc/latex2html/latex2html.html). Here briefly outline the features we most commonly use, and things to bear in mind:

the .latex2html-init file used to create this document is summarized in

$MAX_SPLIT_DEPTH = 8;	# Stop making separate files at this depth
$MAX_LINK_DEPTH = 4;    # Stop showing child nodes at this depth   
$NOLATEX = 0;           # 1 = do not pass unknown environments to Latex
$EXTERNAL_IMAGES = 0;   # 1 = leave the images outside the document 
$ASCII_MODE = 0;        # 1 = do not use any icons or internal images
$TITLE = "OGIP/95-001";
$DESTDIR = '.';         # Put the result in this directory 
$ADDRESS = "Ian M George (george@lheavx.gsfc.nasa.gov) (301) 286-6094<BR>\n$address_data[1]";
$NO_NAVIGATION = 0;	# 1 = do not put a navigation panel at the top of each page
$AUTO_NAVIGATION = 1;
$INDEX_IN_NAVIGATION = 1;
$CONTENTS_IN_NAVIGATION = 1;
$NEXT_PAGE_IN_NAVIGATION = 1;
$PREVIOUS_PAGE_IN_NAVIGATION = 1;
$INFO = 1;              # 0 = do not make a "About this document..." section 
$DONT_INCLUDE = "memo:psfig:dvipsfig:epsf:a4:memo:makeidx:times:margins:aaii2:" .
                "preprint:revtex:eqsecnum:aps:html:pictex:german:french:art12:" .
		"12pt:doublespace:float:harvard:tabls:twoside";
$REUSE = 1;
$SHOW_SECTION_NUMBERS = 1;
$CHILDLINE = "<BR> <HR>\n";
$LINE_WIDTH = 500;		
$WORDS_IN_PAGE = 300;	
$default_language = 'english';	
$WORDS_IN_NAVIGATION_PANEL_TITLES = 4;
$MATH_SCALE_FACTOR = 1.6;
$FIGURE_SCALE_FACTOR = 0;
$DEBUG = 0;

Rest of Section Incomplete

Contributions are welcomed (to george@lheavx.gsfc.nasa.gov)

4.3 Associated Software

In this Section we briefly review various software tasks and packages commonly used in association with LaTeX and latex2html. This list is not (nor intended to be) exhaustive.

4.3.1 Making PS files from LaTeX runs

A common requirement, once one has successfully run LaTeX on a document is to obtain a hard-copy. The most common way of doing this (at least in the OGIP) is to use the dvips program. As its name suggests, dvips takes the *.dvi produced by LaTeX and converts it to a postscript file which can then be printed on any postscript-compatible printer.

To run dvips on a file called (say) yourfile.dvi simply:

dvips yourfile

which will result in a file called yourfile.ps. There are many optional arguments to dvips ... section incomplete

Contributions are welcomed (to george@lheavx.gsfc.nasa.gov)

4.3.2 Viewing PS files

ghostview - Section Incomplete

Contributions are welcomed (to george@lheavx.gsfc.nasa.gov)

5 GENERAL COMMENTS ON WRITING GOOD LaTeX SOURCE

In this section we describe a few issues authors should consider when writing LaTeX documents, especially those which are to be converted using latex2html.

Contributions are welcomed (to george@lheavx.gsfc.nasa.gov)

5.1 Make use of internal cross-referencing

LaTeX provides the facility to automatically cross-reference various sections, tables, figures, pages etc whereby the author does not have to keep track of the actual section, table, figure, page numbers - LaTeX will insert the relevant values when it is run.

This is useful since it allows the author to change the order of such sections, figures, tables etc without having to go back through the text changing references to them. Furthermore this facility is particularly useful with documents to be processed using latex2html, since latex2html create hyperlinks to the relevant html page, figure, table etc allowing readers to easily find and view the referenced item (if desired).

Details on what items can be internally cross-referenced with LaTeX are listed in Section along with examples.

5.2 Make use of external cross-referencing

Details on how to reference external sources such as other files or other html pages are given in Section along with examples.

5.3 Include any postscript figures

In order for the document to be complete, any postscript 'figures' should be included by making use of LaTeX's (and latex2html's) ability to encapsulate then. How to do this is described with examples in Section . It might take a few attempts to get right, but its worth it - there's little more annoying to the reader than missing figures.

6 LaTeX HEADER REQUIREMENTS

This sections reviews the contents of the LaTeX header REQUIRED for the various features described elsewhere in this document.

6.1 latex2html requirements

A number of the functions described in Section involve commands which can be embedded in the LaTeX source file (ie the *.tex file) which are defined in the html.sty file supplied with the latex2html package.

Thus is order to use these commands, the html.sty file MUST be included as a argument of the \documentstyle command at the top of the LaTeX file.

For example, the first line of this document is:
\documentstyle[11pt,html]{article}

7 EXAMPLES OF THE USE OF LATEX AND LATEX2HTML

This section includes examples of some of the functionality and output which can be obtained using LaTeX and latex2html. It is by no means complete, and merely reflects the limited number of functions the authors are discovered so far.

Contributions are welcomed (to george@lheavx.gsfc.nasa.gov)

7.1 Cross-referencing

There are several types of cross-referencing possible, as described in the following sections.

7.1.1 Referencing parts of the same document

Use of this facility is particularly useful with documents to be processed using latex2html, since latex2html will not only insert the relevant values, but also create hyperlinks to the relevant html page, figure, table etc.

Automatic cross-referencing requires the following:

That the section/figure/table to be referenced be defined using the command:
\label{text}
(where text is a string of the author's choosing).
That the reference to this section/figure/table be made using the command:
\ref{text}
(where text is obviously the same string as above).

There is no limits on the number of \label{text} commands defined in a given file (though clearly each text string must be unique).

For example, the RUNNING LATEX & LATEX2HTML section of this document has the following command just after the \section command:
\label{Sec:running}
A cross-reference to this section can therefore be made using the \ref{} command as follows:
resulting in a cross-reference to Section~\ref{Sec:running}.
resulting in a cross-reference to Section 4.

NOTE: LaTeX actually operates by storing the locations of any sections, tables etc defined using the \label{} command in the *.aux file. In order for this is read, and the correct values be inserted into the output *.dvi file, LaTeX should be run at least twice. LaTeX should (obviously !) always be re-run if you get the following warning message:

LaTeX Warning: Label(s) may have changed. Rerun to get cross-references right.

7.1.2 Referencing other htmls

NOTE: The commands described in this section are defined in the html.sty file, and hence require it by included as part of the arugents to the \documentstyle command (See Section 6).

latex2html provides a number of commands which can be embedded in the LaTeX source code to emable hyperlinks to be generated to other html pages. The most useful is probably the
\htmladdnormallinkfoot{text}{URL}
command which results in the text being made into a hyperlink to the specified URL in the html document (ie by latex2html, but results in the URL being given as a footnote in LaTeX/DVIPS-produced hardcopy (see Section 4.3.1).

For example, the command:
\htmladdnormallinkfoot{Here is Ian George's personal biography}
{http://legacy.gsfc.nasa.gov/docs/bios/imgeorge.html}
and
\htmladdnormallinkfoot{here is Jane Turner's}
{http://legacy.gsfc.nasa.gov/docs/bios/turner.html}.
in the LaTeX source file will result in the following output:

http://legacy.gsfc.nasa.gov/docs/bios/imgeorge.html and http://legacy.gsfc.nasa.gov/docs/bios/turner.html. This facility is used throughout this document.

NOTE: the \htmladdnormallinkfoot{text}{URL} command fails when LaTeX is run if the URL contains an underscore (or any other symbol LaTeX considers a 'mathematical' symbol). In such cases, it is suggested that the \htmladdnormallink{text}{URL} command is used instead, which produces a hyperlink using latex2html, but does NOT produce a footnote using LaTeX.

7.2 Including HTML commands

latex2html allows raw html commands to be included within the LaTeX source by using the environment rawhtml.

For example, the commands:

\begin{rawhtml}
<hr>
<form>
<ol>
<li> <input type="checkbox" name="wp" value="checkbox1"> 
	Here is a dummy checkbox
<li> <input type="checkbox" name="wp" value="checkbox2"> 
	Here is another
</ol>
<input type="submit" value="Here a a dummy submit button">
</form>
<hr>
Is this ace or what ??!
<hr>
\end{rawhtml}

results in the following when processed by latex2html:

Is this ace or what ??!

(nothing when processed by LaTeX).

7.3 Including postscript files

Various 'macros' have been written to allow external postscript files to be incorporated into LaTeX documents. This is most useful when one wants to include graphical information such as figures, logos etc into the document.

Certain of these macros are also supported by (or rather work successfully/recommended with) latex2html. Furthermore latex2html enables additional author-flexibility of how & where the 'figures' are displayed in the resultant html document.

7.3.1 The psfig macro

Use of the psfig macro has been found to be the most successful at incorporating external postscript files into LaTeX documents, and at producing reasonable latex2html output.

In order to use this macro, the LaTeX document must contain the required definitions. This is most easily done by making use of the LaTeX \include command:

\include{psfig.tex}

somewhere soon after the \begin{document} command.

A copy of the psfig.tex is available from legacy.gsfc.nasa.gov via anonymous ftp or gopher as
caldb/docs/utilities/psfig.tex via the OGIP's anonymous ftp or gopher servers.

The following LaTeX code can then be used to include an external postscript file called fig1.ps in the LaTeX and html documents:

{\begin{figure}[tbh]
        \htmlimage{thumbnail=0.1}
        \centerline{
        \psfig{figure=fig1.ps,width=15cm}}
        \caption{This is the caption of the figure. 
	This particular example is actually the components of the PSPC
        {\it psf} versus off-axis angle at 0.188 keV.}
        \label{fig:fig1}
\end{figure}}

with the result shown in Figure .

Figure

Figure 1: This is the caption of the figure. This particular example is actually the components of the PSPC psf versus off-axis angle at 0.188 keV.

There are several points to note in the above example:

Firstly, it should be noted that in the LaTeX document, the placement of the 'figure' follows the normal LaTeX rules for floats. In the above example the [tbh] qualifier to the \begin{figure} commands instructs LaTeX to attempt to place the 'figure' in the following locations with the following priorities:

at the top of a page (the t in [tbh]),
at the bottom of a page (the b in [tbh]),
right here on the current page (the h in [tbh])
(if all else fails) the next available position.

As can be seen for them the inspection of the figure produced in the LaTeX document, the external postscipt file to be included (fig1.ps) is actually fairly large, and takes an entire page to be plotted along with the figure caption (at least for those funny US-sized pages). Thus the figure floats to the end of the document.

In contrast, in the latex2html version of the document, the figure (having been converted to a GIF image) is displayed exactly where it is defined in the LaTeX source code (ie in a location equivalent to h in the [tbh] qualifier).

Secondly there are many possible arguments to the \psfig command:

\psfig{file=, figure=, height=, width=, bbllx=, bblly=, bburx=, bbury=,
       rheight=, rwidth=, clip=, angle=, silent=}

where

file is the name of the external postscript file. If no path name is specified and the file is not found in the current directory, then it will be looked for in directory specified by the \psfigurepath environment variable.
figure is a synonym for file.
By default, the width and height of the figure are taken from the BoundingBox of the external postscript file, however:
- If width is specified, the figure is scaled so that it has the specified width. Its height changes proportionately.
- If height is specified, the figure is scaled so that it has the specified height. Its width changes proportionately.
- If both width and height are specified, the figure is scaled anamorphically.
bbllx, bblly, bburx, and bbury control the postscript BoundingBox. If these four values are specified before the file option, the \psfig will not try to open the postscript file.
rheight and rwidth are the reserved height and width of the figure, i.e., how big TeX actually thinks the figure is. They default to width and height.
The clip option ensures that no portion of the figure will appear outside its BoundingBox. clip= is a switch and takes no value, but the = must be present.
The angle option specifies the angle of rotation (in degrees, anti-clockwise).
The silent option makes \psfig work silently.

Besides the obvious figure (or file), the width, height and angle arguments are straightforward and allow novice users to satisfy most of their requirements.

Thirdly latex2html provides some control of the image size in the html version of the document via arguments to the \htmlimage command:

external to prevent the inlined images being created, but instead to produce a hyperlink to the image.
scale to control the overall size of the image
thumbnail to produce a (small) inlined image to be created in the html document, but also to produce a hyperlink to the full-size image.
map to turn the inlined image into an active image map.

These are further described in the latex2html manual (see the http://cbl.leeds.ac.uk/nikos/tex2html/doc/latex2html/latex2html.html) For most applications, we have found the thumbnail argument to most useful since it allows small inlined images to be produced speeding up load-time, but (assuming it is big enough !) still enables users to get a feel as to what the figure contains and hence whther they wish to bother viewing the full-sized image.

8 KNOWN BUGS & PROBLEM AREAS TO AVOID

This section lists a number of problems which have been encountered running LaTeX and latex2html on a variety of OGIP documents. In some cases solutions are even offered.

Contributions are welcomed (to george@lheavx.gsfc.nasa.gov)

8.1 Unrecognized TeX & LaTeX commands

Problem:
A number of Tex and LaTeX commands (especially those invoving font changes) appear not to have any effect on the html output. Examples include \underline, \it, \bf etc (which often result is 'standard'-style output under html). This is most likely due to the limited number of fonts available to html.

Solution:
None - either dont use these commands, or live with a difference between the pages generated using LaTeX and html.

8.2 Embedded TeX Commands

A few TeX commands have been found to produce unexpected html output as described in the following sections.

8.2.1 hskip

Problem:
The use of a construction of the form:
{\hskip 0.60in} XSPEC>
results in undesired HTML output of the form:
0.6in xspec>

Solution:
The use the LaTeX command:
\hspace{0.60in} XSPEC>
instead, which appears to work as expected under LaTeX, and have no effect undert html, eg:
xspec>

8.3 Problems with Mathematical Symbols

8.3.1 Unattractive white backgrounds

Problem:
Mathematical symbols (along with figures & tables - ie all GIFs) have a white background, rather than a background the same colour as the WWW viewer.

Solution:
This is caused by the giftrans routine having been turned-off during the latex2html run. It should be turned on (via the GIFTRANS environment variable in the latex2html.config file) and latex2html re-run. HOWEVER: remember that users who have changed their XMOSAIC (etc) default background colour to black will now be unable to see the tables, figures, symbols since the GIFs are displayed as black-on-black under html (see Section ).

8.3.2 Unreadable/distorted mini-GIFs

Problem:
The use of a construction of the form:
$\sim 0.11$
results in an unreadable/distorted mini-GIF.

Solution:
Separation of the $\sim$ from the numerical value, ie:
$\sim$ 0.11
is preferable: unfortunately the mathematical symbol can remain poor, but at least the numerical values are legible.

8.3.3 LaTeX fails on a htmladdnormallinkfoot command

Problem:
The \htmladdnormallinkfoot{text}{URL} command fails when LaTeX is run if the URL contains an underscore (or any other symbol LaTeX considers a 'mathematical' symbol).

Solution:
Use the \htmladdnormallink{text}{URL} command instead. This produces a hyperlink when used in conjunction with latex2html, but does NOT try to produce a footnote when used with LaTeX.

8.4 Problems with Tables & Figures

8.4.1 Invisible Tables & Figures

Problem:
People who have changed their XMOSAIC (etc) default background colour to black are unable to see the tables, figures, symbols since the GIFs are displayed as black-on-black under html.

Solution:
Re-run latex2html, but without running the giftrans routine (which can be turned off using via the GIFTRANS environment variable in the latex2html.config file). This will result in the background colour of all GIFs being set to white (whilst the foreground colour used for the text/image remains black) and hence visible. HOWEVER: remember that black is not the default background colour for most WWW viewers, and the GIFs with white backgrounds produced by not running giftrans may annoy users who do have kept their background colour the default when viewing documents with many inlined mathematical sysmbols (see Section 8.3.1).

8.4.2 Poor (low-resolution) Tables & Figures

Problem:
Under html the tables, figures etc (any/all GIFs) are generated successfully, but are of poor quality. This is most probably due to:

missing fonts, forcing latex2html to use an inappropriate one (an error message should be generated at run-time)
a problem with the installation, or number of dots-per-inch used by ghostscript

Solution:
Re-run latex2html have taken appropriate action as outlined above.

9 SOURCES OF FURTHER INFORMATION

Further information on latex2html is available on the WWW at the http://cbl.leeds.ac.uk/nikos/tex2html/doc/latex2html/latex2html.html, including an overview, the manual, bug reporting forms, etc etc.

ACKNOWLEDGMENTS

We would like to thank the numerous people who tested the contents and contributed valuable comments to this memo, and in particular http://legacy.gsfc.nasa.gov/docs/bios/white.html, http://legacy.gsfc.nasa.gov/docs/bios/arnaud.html, ....

File translated from T_EX by T_TH, version 3.84.
On 11 May 2010, 15:22.