### 5 Common conversion problems

We have already mentioned that Star2HTML uses LATEX2HTML to do the conversion to hypertext. LATEX2HTML usually makes a good attempt at this conversion. However, it can produce disappointing results, particularly for complex sections, such as the cover page and subroutine/application descriptions in Starlink documents.

Some LATEX structures cannot be translated into HTML. Normally, LATEX2HTML handles these by either ignoring them, or by passing them back to LATEX for processing and then converting the result to in-line images (complex maths symbols, for example). The result occasionally requires tweaking by hand. Sometimes the result is so poor that you need to re-write parts of your document in order to generate a more acceptable result.

#### 5.1 Things to avoid

##### 5.1.1 Raw TEX

LATEX2HTML is designed to deal with LATEX commands of the form \command{arg1}{arg2}... and cannot, in general, deal satisfactorily with raw TEX commands. If this problem occurs, you’ll notice “=” signs in inappropriate places, or missing parts in your hypertext version. The only thing to do is to use LATEX equivalents of the TEX commands.

For example use:

\newfont{\ssttt}{cmtt10 scaled 1095}

\font\ssttt=cmtt10 scaled 1095

or

\providecommand{\_}{\texttt\symbol{95}}

\providecommand{\_}{\tt\char’137}

and so on.

##### 5.1.2 Parboxes

These are always translated into GIFs and often have an incorrect size. Try to avoid them if possible. If you can’t, you might have to fix things by hand.

#### 5.2 Things that rarely look right

##### 5.2.1 Tabbing environments

Don’t use the tabbing environment – the converter makes a mess of it and the only solution is to edit the HTML files. Use the tabular environment instead.

#### 5.3 Irritants

##### 5.3.1 Unwanted blank lines

Consider the source text:

Some text

You’d expect the generated text to look like:

Some text for latex readers.

in the paper version, and

Some text for HTML readers.

in the hypertext version. However, the hypertext version comes out like:

Some text

because the \latex line is replaced by a blank line and consequently ends up as a paragraph break. To get around this you must include some text on the \latex line, as in:

Some text \latex{for latex readers.} \html{for HTML readers.}

Or you could get the same effect using the \latexhtml command:

Some text \latexhtml{for latex readers.}{for HTML readers.}
##### 5.3.2 Tildas in URLs

To get a tilda into a URL, use:

which just throws away the tilda.

#### 5.4 Using the htmladdimg command to replace figures

The \htmladdimg command is used to display an image stored in an external file. Its form is:

where the URL is the hypertext address of the image (probably just the name of an image.gif file in the default directory).

It is tempting to use this command to replace existing figures with better colour graphics. However, you cannot use this command inside a figure environment. Instead, you should use something like:

\begin{latexonly}
\begin{figure}
\label{This figure}

body of figure

\caption{Latex eps version}
\end{figure}
\end{latexonly}

However, you will not get a figure number in the caption.

#### 5.5 Hints from the Starlink Software Librarian

The following list of recommendations was compiled by the Starlink Software Librarian, Martin Bly, who has issued many Starlink documents submitted for release and has noted the things that have caused him trouble:

• Don’t reference specific version numbers of documents, e.g. use “SSN/26” rather than “SSN/26.1”.
• Use a / to separate document-type from document-number, e.g. use “SSN/26” rather than “SSN26” or “SSN 26”.
• In the paper version of your document, the first page (page 1) of the main body of your text should appear on the right-hand-side when it is printed double-sided (or sent for photocopying), otherwise your document looks amateurish. This main body is preceded by the title page, abstract, and contents list (which have page numbers written in Roman numerals).

You can ensure the correct layout by including a \cleardoublepage immediately before your “page 1”. The latest templates include this automatically but you should check existing documents for this problem.

• Use \begin{quote}\end{quote} to surround \begin{verbatim}\end{verbatim} texts. If the area of text is large or long, use \small inside the quote environment.