1 Introduction

Starlink documents (SUN, SGP, etc.) are produced by LATEX. Star2HTML converts Starlink documents to HTML for use on the World Wide Web. It has the potential to make the entire set of Starlink documents appear as a single hypertext document by linking all the separate documents together. It allows a single document source file (.tex) to produce a paper version (when processed by LATEX) and a hypertext version (when processed by LATEX2HTML).

1.1 Getting started

Copy one of the Starlink template documents into a working directory:

This file is a skeleton LATEX source file and will give your document a standard style and extra hypertext facilities.

Get a paper copy to look at (or use xdvi if you prefer):

You’ve produced a Starlink User Note! It’s got a title page with an abstract, a contents page, and third page (page 1) containing the body of the document.

You’ve got a paper version of the document. Now use Star2HTML to produce a hypertext version:

A lot of alarming messages, dots, and general gobbledygook appear on your screen. Don’t worry about it – this is Unix not Windows. You now have a hypertext version of the document. It’s stored in a new directory called sun.htx (which will have a lot of files in it, none of which need concern you). Notice that you’ve produced a paper version and a hypertext version from the same source file (sun.tex).

Now use a web browser to look at the hypertext version:

Compare the two versions.

The same information is there, it’s just been rearranged on the page. Some extra information has been added to the hypertext version. There’s a navigation band at the top (you may have to scroll up to see it), a button to get hardcopy, a couple of entries in the contents list, and some extra identification at the bottom. Also, some elements in the header (like CCLRC) appear as hypertext links to external pages that describe what they are.

Star2HTML and the templates do all this automatically. All you have to worry about is filling in the template (and deleting the bits you don’t want), replacing those place-holders (like [author] and [title] with meaningful text, and writing the document. The following sections will help you do this.

1.2 Converting an existing document

A basic conversion of an existing LATEX document can be done very quickly. It consists of incorporating the appropriate template in the source file, and then changing (or deleting) the place-holders. However, to get the best from the system, some additional tasks are required.

To convert an existing LATEX document, edit it to:

(1)

Incorporate one of the Star2HTML document templates and adapt it to your document.

(2)

Add extra hypertext links to your document and allow other Starlink hypertext documents to link to your document.

(3)

Adapt the two versions (paper and hypertext) of your document to their respective media.

(4)

Correct any formatting problems in the hypertext version that result from the conversion process.

These four tasks are described in later sections of this document.

Start with task 1 (see “Using a template”, Section 2), which will produce a basic conversion of your document. You can sort out any linking, formatting, and media problems later.

Run the converted document through LATEX to make sure you haven’t harmed the paper version. Then produce a hypertext version, using star2html, and check the result, using showme. Use the commands shown in “Getting started” (Section 1.1).

Sometimes the hypertext version doesn’t look right on the screen. You’ve got formatting problems. Check the common problems in Section 5 for possible solutions.

1.3 Some background

Star2HTML comprises two Perl scripts and a set of templates.

The star2html command invokes one of the Perl scripts which calls the LATEX2HTML utility to do the actual conversion to hypertext format. LATEX2HTML is described in its own manual¹ (MUD/152). However, you shouldn’t need to refer to it unless you have specialised needs. Always use the star2html command rather than the latex2html command to convert Starlink documents to hypertext.

The templates have two functions:

• Provide LATEX definitions for standard styles of Starlink document.
• Add extra LATEX commands to the basic repertoire provided by LATEX2HTML. These are used to link Starlink documents together.

The templates are based on LATEX2$\epsilon$ and all documents should now be produced using this.

The second Perl script, xlabel, is a utility to help in labelling sections of the hypertext document so that other documents can link to them. Its use is described in “Labelling sections” (Section 3.4).