2 Using a template

The templates are skeleton LATEX documents with preambles giving the document a standard style and extra hypertext facilities. They are stored in directory /star/share and have filenames which are based on the name of the Starlink document class for which they have been designed (sun.tex, ssn.tex, etc.).

Changing the place-holders in the template will be trivial for LATEX experts, but it can be intimidating for novices, so the process is described in detail below.

2.1 Changing place-holders

The sections of the template you need to change are contained between comments like:

% ? Section description
...
% ? End of section description

Some just indicate where you should put any special commands required by your document, others contain sections of code which should be commented in or out (with %) depending upon your requirements and yet others contain place-holders indicated by being enclosed in brackets, [number] for example. Change the place-holders as appropriate for your document. Some place-holders may not be relevant to your document, in which case delete the lines that contain them.

The section headings to look for are:

% ? Specify used packages

Any LATEX extension packages which are used in your document should be listed here in a usepackage command like:

The section contains commented out commands for the commonly-used graphicx package – don’t forget to use the draft option of the package to save time when writing your document.

% ? Document identification

Replace or delete the following place-holders:

• [number].[version] – replace with the sequence number and version number of the document code (like 199.3).
• [author] – the name of the author (or authors).
• [date] – the date of issue (like 3 June 1997).
• [title] – the main title of the document.
• [software-version] – the version number of the software being described (like Version 1.1-2). If you are not writing about a software package, or there is no version number, delete this line.
• [manual-type] – the type of manual you are writing (like User’s Manual). If this line isn’t appropriate, delete it.
• [Text of abstract] – every document, except the most trivial, should have an abstract. Put the text of the abstract here. It will appear under the heading “Abstract” on the front page of the paper version. In the hypertext version, it will appear in the first section of the document and will be given the title Abstract. If you don’t want to supply an abstract, delete this line, and also delete the other sections which are used to create abstracts:
% ? Heading for abstract if used
...
% ? End of heading for abstract

and

% ? New section for abstract if used
...
% ? End of new section for abstract

and

% ? Document Abstract. (if used)
...
% ? End of document abstract

One point to note is that if you want to include a paragraph break in your abstract, you must use the \par command rather than just leaving a blank line in the text.

% ? Document specific \providecommand or \newenvironment commands

Use this section to add any extra definitions that you want to use in the body of your text. Most documents don’t have anything added to this section, but some (e.g. SUN/95) define a large number of new commands here. Just leave this section alone if you don’t want to add anything to it.

% ? Add picture here if required for the LaTeX version
% ? Add picture here if required for the hypertext version

Use these sections to add any pictures that you want to display on the front page of your document. Just leave the sections alone if you don’t want to add a picture in this position.

SUN/9 gives details of how to include PostScript files in LATEX documents and there are examples of simple \includegraphics commands in both sections but you will probably need something more elaborate. PostScript files can be included in both versions or you can use \htmladdimg{<URL>} to include a .gif file for the hypertext document.

This section is required for Starlink documents but may be deleted by others. The statement specified in the \stardoccopyright command will appear at the bottom of the second page of the paper version; the HTML version will, by default, have the copyright statement in the footer of each page.

Copyright is assigned to STFC by default.

% ? Latex document Table of Contents (if used)

Delete this entire section if you don’t want a table of contents in the paper version (you will always get one in the hypertext version). We recommend that you always include this section unless your document is short and unstructured.

2.2 Using SST macros

If your document uses the standard macros defined for the Simple Software Tools (SST) package on VMS, then you should add the command:

\input{sst}

to the “Document specific …commands” section of the template. The new definitions are a direct replacement for the old macros and should not cause any problems for existing documents unless you have modified the old macros. If you have done so, you must work out how to incorporate your changes into the new definitions.