2 Using a template

 2.1 Changing place-holders
 2.2 Using SST macros

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
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:

% ? 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.

% ? Latex Copyright Statement

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:


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.