5 Common conversion problems

 5.1 Things to avoid
 5.2 Things that rarely look right
 5.3 Irritants
 5.4 Using the htmladdimg command to replace figures
 5.5 Hints from the Starlink Software Librarian

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}

instead of:

  \font\ssttt=cmtt10 scaled 1095

or

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

instead of:

  \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
  \latex{for latex readers.}
  \html{HTML readers.}

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
  
  for HTML readers.

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:

  \htmladdnormallink{My home page at RAL}{http://star.rl.ac.uk/\~{}me}

instead of:

  \htmladdnormallink{My home page at RAL}{http://star.rl.ac.uk/~me}

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:

  \htmladdimg{<URL>}

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: