B Producing a document

B.1 Starting or revising a document

When starting a new document, copy the appropriate template file from /star/docs into your own directory and change the variable information; then add your own text. This procedure is explained in some detail in SUN/199. Produce your original file in the form of a .tex file ready for processing by LATEX and Star2HTML.

When updating a document, copy the existing file from /star/docs and edit that; do not start from a private copy as your submitted file may have been edited by a Librarian before final issue, and the changes (such as spelling corrections) will be lost and have to be done again.

B.2 Using LATEX

For all but the simplest of notes you will probably wish to use a text processing program. Starlink recommends LATEX. Don’t use TEX unless you enjoy making life difficult for yourself and others; LATEX is much easier. In our experience, the output from TEX source is inferior to that of standard Starlink LATEX documents, and invariably has idiosyncratic style and format.

SC/9 contains many examples of how to use LATEX and shows the style preferred by Starlink. SUN/9 describes how to use LATEX. There are lots of books about LATEX to help you use it properly. The basic reference is the book by Leslie Lamport listed in the References.

B.3 Using Star2HTML

If possible, you should add hypertext links to your document and use Star2HTML to produce the hypertext version. This procedure is explained in SUN/199. The basic procedure for checking the hypertext version of your document from within your working directory is as follows:

This will display your hypertext document (in this case, sgp28.tex) in a window running a web browser.

B.4 Submitting a document for distribution

When you have finished your document, tell the Software Librarian (starlink@jiscmail.ac.uk) where your file is. If necessary, send paper copies of any additional material, such as diagrams, which is required in the final document, but which doesn’t appear in hardcopy derived from your file. The Librarians may edit your file to make it conform to Starlink standards, and will then produce a paper master and get copies made. They will also distribute the file in a software release, and send several copies to every Starlink Site Manager for users.