Cross references are a way to point to a portion of a document elsewhere in the document.

In print, let us say that you want to reference the first section. A reference to this section will look like

as said in section 1

If you use the hyperref package, LaTeX references will act as hyperlinks in the resulting PDF file. This will kook like

as said in section 1

Clicking on the blue 1 digit will bring the focus of the PDF document to the first section of the document. Unfortunately, this is unpractical in complex/large documents because, when switching to the first section of the document, the reader will lose view of the context in which the reference was made. In practice, the reader has to memorize the context before going to the first section, which can be quite a strain in complex documents.

In Documents Live, we do things differently.

But, before we detail the implementation of cross references in Documents Live, let us first explain how cross references are created and used in the LaTeX language.

To create a cross reference, you must add a label to the object you want to reference. You do this by using the \label command after the object declaration. Let us give an example with a theorem of type summary.

\begin{summary}\label{labelName}
... summary content ...
\end{summary}

To reference the summary elsewhere in running text, you use the \ref command. Here is an example.

Essentially, gnus behave as described in \ref{labelName}.

We have assigned a label to the Introduction section 1. The reference is the blue number 1 in the previous sentence. If you click on it, the browser focus will not move to the introduction, but instead, the content of the introduction will be inserted below this very paragraph to let you see the reference in context.

To dismiss the content of the reference, click on it if you click on the section title, this will simply collapse the section.

If you are not happy with a simple number to represent the reference, you can pass an optional parameter to the \ref command which will specify which text should be displayed as a pointer to the reference. Let us do this now.

We have assigned a label to the Introduction section. The code is

We have assigned a label to the \ref{intro}[Introduction section].

The advantage of the Documents Live ecosystem is that it supports site-wide cross references. As a example, we are going to implement a reference to the Introduction section of the “A LaTeX guide for web publishing” article, which is the the first article in this guide. Naturally, the first thing to do is to attribute a label to this section in the source code.

Assume that this has been done and that the label for the remote section is also intro. Next, we compile the corresponding article.

There remains to create a reference in this document. If we use \ref{intro}, the reference will point to the introduction of this document. So, obviously, we must proceed differently.

The right thing to do is to go to the introductory article and activate the “fetch labels” functionality. To do so, click on the blue floating button, at the bottom left, that says Grab labels. If it is a red button that says Stop grabbing labels, this means that the label grabbing functionality is already active.

When you are done with label grabbing, click on the Stop grabbing labels button to return to normal behavior.

This action modifies the effect of a click in the document (“A LaTeX guide for web publishing” here).

Click somewhere in the text of the introduction. A dialog appears below the text that lets you select the object for which you want to get the label in a list. This is because the object on which you click may belong to a nested set of Documents Live obtects. For instance, a paragraph generally is part of a section.

Here the list is features the current paragraph and its surrounding section. Choose the section, and the label for the introduction will be pasted to the clipboard. In this case, the clipboard says A-LaTeX-guide-for-web-publishing/intro.

Now return to edit this very document, insert a \ref command somewhere in the text, and paste the cross site label inside the curly braces. Let us do this now.

The code

To have an overview of this guide, read the \ref{A-LaTeX-guide-for-web-publishing/LaTeX-intro}[introduction of the guide].

results in:

To have an overview of this guide, read the introduction of the guide.

Click to check the reference!