3 Adding links

 3.1 Internal links
 3.2 External links
 3.3 Links between Starlink documents
 3.4 Labelling sections
 3.5 Links to routine descriptions

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.

3.1 Internal links

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:

  \htmlref{text}{label}

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:

  \section{\label{adding_links}Adding links}

You could then create a link to this section by a reference like:

  ... refer to the \htmlref{Adding links}{adding_links} section.

This will appear in both versions as:

  ... refer to the Adding links section.

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:

  \htmlref{PISAPLOT}{PISAPLOT}

The word “PISAPLOT” will appear in both versions, but in the hypertext version it will be a link to the description of the routine.

3.2 External links

To add a link to an external web page, use the command:

  \htmladdnormallink{text}{URL}

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:

  \htmladdnormallinkfoot{text}{URL}

3.3 Links between Starlink documents

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:

  \xlabel{label}

Other documents can create a link to it by using \xref. The format of \xref is:

  \xref{text}{doc}{label}

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:

  \xref{SUN/x}{sunx}{}

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:

  # star2html sunx
  # hlink
  # showme ./sunx

The Starlink hypertext linker, hlink, is more fully described in SUN/188.

3.4 Labelling sections

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:

  \subsection{\xlabel{labelling_sections}Labelling sections}

and other documents can create a link to it by using \xref as in:

  See SUN/199 for more on
  \xref{labelling sections}{sun199}{labelling_sections}.

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:

# xlabeldocument

Will produce a new version of the document, in file newdocument, 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 newdocument back to document.

3.5 Links to routine descriptions

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:

  \xref{CHR\_LEN}{sun40}{CHR_LEN} finds the used length of a string.