Star2HTML automatically adds some links to a document it converts; for example, the section headings in the contents list link to the section text. However, you can add extra links if you wish. These can be to other parts of your document (Internal links), or to other pages on the web (External links). A type of External link that is very common is one to another Starlink document; a special command is provided to create this.
If your document uses the cross-referencing facilities of LATEX (i.e. the \label{key}, \ref{key}
commands), then Star2HTML will automatically create a link from the \ref to the \label. The link
will normally be indicated by a small button, when viewed with a browser (the actual value will be
used if the -aux
switch of the star2html
command is used, but these values aren’t normally useful in
hypertext).
If you want to use some descriptive text for the link instead of the button (or if you want to add a new internal link), use the command:
text
is the text that will be highlighted as the link (it will also appear in the paper version of your
document as ordinary text). label
is the name of a label defined somewhere in your document by the
\label command.
For example, the source code for the heading of the current top-level section might be:
You could then create a link to this section by a reference like:
This will appear in both versions as:
but in the hypertext version, “Adding links” is indicated as a link. When activated, it will take the reader to that section.
As another example, the standard SST macros define a label for every routine description. If a reference is made to a routine, say PISAPLOT, in the main text, a link to the full description of the routine can be made by:
The word “PISAPLOT” will appear in both versions, but in the hypertext version it will be a link to the description of the routine.
To add a link to an external web page, use the command:
text
will appear in both versions, but in the hypertext version it will be a link to the web page with
the specified URL
.
To add the URL as a footnote in the paper version, use the following command instead:
The LATEX command \label allows cross-references within normal LATEX documents. Similarly, the Star2HTML command \xlabel allows hypertext links to be set up from other Starlink documents to your document. Its format is:
Other documents can create a link to it by using \xref. The format of \xref is:
text
will appear in both versions, but in the hypertext version it will be a link to the place labelled
label
(with \xlabel) in the Starlink document doc
.
Obviously, if other Starlink documents contain \xlabel commands, you can use \xref in your document to add links to them.
It will often be necessary to include both a \label and an \xlabel command at the same point in a document in order to anchor internal and external links to the same place. In this case, the name of the label can be the same in both commands since \xlabel modifies it to produce a different anchor name.
You can create a link to any Starlink document by a command like:
This link will take you to the beginning of the document as the templates contain an \xlabel with a blank label on the title page of the document. Not all Starlink documents are available in hypertext form but the link will even work in that case – browsers will usually just display the paper version.
There is one further step required to create a link to another local Starlink document – you must run
the hypertext linker hlink
, after running star2html
on your source file, so that the links between the
two documents can be resolved. If you do not do this then all the cross references will
be passed to the Starlink central document server for resolution. Thus, if your document
contains links to other Starlink documents, you can convert, link it locally, and view it
by:
The Starlink hypertext linker, hlink
, is more fully described in SUN/188.
If you want to label a complete section, for other documents to refer to, you should include an \xlabel as part of the section title. This is because the link will be to the exact point in the document where the \xlabel occurs, rather than to the start of the section (as with normal \ref and \label).
So that others can easily link to sections of your document, we recommend that you \xlabel all sections and subsections with the section title in lower case, non-alphanumeric characters removed and words separated by underscore.
For example, the subsection you are now reading has been labelled as follows:
and other documents can create a link to it by using \xref as in:
You can use the xlabel
command from the Unix shell to ensure that your document has the
recommended \xlabel’s for each section and subsection. The command:
# xlabel
document
Will produce a new version of the document, in file new
document, containing any additional required
\xlabel commands. It will also warn you if there are any duplicated section labels or if an existing
\xlabel differs from the recommendation. See the description of xlabel
(in Appendix B) for more
information on this.
When you are happy with the result, copy new
document back to document.
The SST routine description macros include an \xlabel command for each routine so, if you use them, your routines will already be labelled to allow links from other documents. By the same token, you can include links to routine descriptions in other documents which have used the SST macros.
For example: