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.
The sections of the template you need to change are contained between comments like:
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
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:
and
and
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.
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.
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.