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 LATEX2
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
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
[title] with meaningful text, and writing the document. The following sections will help you do
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:
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.
Star2HTML comprises two Perl scripts and a set of templates.
star2html command invokes one of the Perl scripts which calls the LATEX2
HTML utility to
do the actual conversion to hypertext format. LATEX2
HTML is described in its own
(MUD/152). However, you shouldn’t need to refer to it unless you have specialised needs. Always use
star2html command rather than the
latex2html command to convert Starlink documents to
The templates have two functions:
HTML. These are used to link Starlink documents together.
The templates are based on LATEX2 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”