8.1 Cross-references

You can use the \label{label} command to attach a label to a position in your document. This label can be used to create a hyperlink to this position from any other point in the document. This is done using the \link command:

  \link{anchor}{label}

   This parameter can be set in the
   \link{configuration panel}{sect:con-panel} to influence ...

The \link command does not do anything exciting in the printed document. It simply typesets the text anchor. If you also want a reference in the LaTeX output, you will have to add a reference using \ref or \pageref. Sometimes you will want to place the reference directly behind the anchor text. In that case you can use the optional argument to \link:

   This parameter can be set in the
   \link{configuration
     panel}[~(Section~\ref{sect:con-panel})]{sect:con-panel} to
   influence ... 

The starred version \link* suppresses the anchor in the printed version, so that we can write

   We will see \link*{later}[in Section~\ref{sl}]{sl}
   how this is done.

   We will see \link*{later}[in Section~\Ref]{sl}
   how this is done.

   \link{Such a file}{ipe-file} is at
   the same time ... a legal \LaTeX{}
   file\texonly{---see Section~\Ref}.

Note that when you use LaTeX's \ref command, the label does not mark a position in the document, but a certain object, like a section, equation etc. It sometimes requires some care to make sure that both the hyperlink and the printed reference point to the right place, and sometimes you will have to place the label twice. The HTML-label tends to be placed before the interesting object--a figure, say--, while the LaTeX-label tends to be put after the object (when the \caption command has set the counter for the label). In such cases you can use the new Label environment. It puts the HTML-label at the beginning of the text, but the latex label at the end. For instance, you can correctly refer to a figure using:

   \begin{figure}
     \begin{Label}{fig:wonderful}
       %% here comes the figure itself
       \caption{Isn't it wonderful?}
     \end{Label}
   \end{figure}

A special case occurs for section headings. Always place labels after the heading. In that way, the LaTeX reference will be correct, and the Hyperlatex converter makes sure that the link will actually lead to a point directly before the heading--so you can see the heading when you follow the link.

After a while, you may notice that in certain situations Hyperlatex has a hard time dealing with a label. The reason is that although it seems that a label marks a position in your node, the HTML-tag to set the label must surround some text. If there are other HTML-tags in the neighborhood, Hyperlatex may not find an appropriate contents for this container and has to add a space in that position (which may sometimes mess up your formatting). In such cases you can help Hyperlatex by using the Label environment, showing Hyperlatex how to make a label tag surrounding the text in the environment.

Note that Hyperlatex uses the argument of a \label command to produce a mnemonic HTML-label in the HTML file, but only if it is a legal URL.

In certain situations--for instance when it is to be expected that documents are going to be printed directly from web pages, or when you are porting a LaTeX-document to Hyperlatex--it makes sense to mimic the standard way of referencing in LaTeX, namely by simply using the number of a section as the anchor of the hyperlink leading to that section. Therefore, the \ref command is implemented in Hyperlatex. It's default definition is

   \newcommand{\ref}[1]{\link{\htmlref{#1}}{#1}}

   see Section~\ref{sec:cross-references}