What are references?

References are a crafty way of referring to a another part of the document, so that you can rearrange the document freely and not mess up your references. Pretty much everything can be referred to — sections, tables, figures, etc.

Other kind of references are citations, which are references to other article, papers, books or such. See the BibTeX part of this help for further information on citations.

Sounds nice, so does it work in practice?

Using references is straightforward, just use the command \label{myref} to mark the part you want to refer to. Hint 1: insert the \label{} as soon as possible, preferably right in the beginning of sections or different environments. Hint 2: for environments in which \caption{} command is used — like tables and figures — insert the \label{} command after the \caption{} command.

After having your labels defined, you can just use the command \ref{myref} to do the referring. You can also refer to the page where the referrable thing resides with the command \pageref{myref}. Example:

You can refer to Table~\ref{table:pi} on page \pageref{table:pi}
before the actual reference\dots

  Variable & \multicolumn{2}{c}{Value} \\
  $\pi$ & 3 & 14159 \\ 
  $\pi^3$ & 31 & 01 \\
\caption{Some $\pi$ related rounded values}

and referring to Table~\ref{table:pi} works afterwards
works as well.

Yes... the reference system comes with LaTeX, so why gloat about?

When the document gets larger, you just cannot remember all those references anymore (and you have to search the for the references, which just wastes time) — this is where TeXlipse steps in: just type "\ref{" and hit ctrl + space (or what content assist is bound to on your system) and you see the list of available references (or if you remember the beginning of the reference, just type it in too to narrow down the shown references.) The command \pageref{} works in the same way.

If Highlight selected references and ... is turned on in the preferences, TeXlipse also highlights the label and all references of the currently selected reference or label in the current file.

But that's not all. If the cursor is on a reference you can use the magic F3 key (or use Open Declaration from the main or context menu) to jump to the correspondig label! How funky is that?

But I use \input{file} to separate my document into several more easily handled files... does this mess up things?

No worries. All references are searched from the LaTeX -files in the project and they will be available in the content assist menu and will be found by Open Declaration.

My special \label environment doesn't work...

Basic label commands and labels in self-defined commands are supported so that the first mandatory argument must be the label argument. More complex environments (e.g. lstlistings) might define their own label environments, which are not currently supported in TeXlipse.