What's the best way to reference examples?

Question

I am writing a programming book on AWK in Latex and I have hundreds of code examples, for example,

awk '1; { print "" }'

I am curious how can I reference the example later in the book. At the current stage it's example #3, but if I add one before it, I'd like the numbering to update automatically, and I'd also like to make a clickable link in the final pdf, that would bring the user to the example.

Thanks!

Answer 1

You will probably want to use a package to help with pretty-printing the code snippets. Two popular choices for the job are the listings and minted packages.

Both packages provide a listing environment that can be cross-referenced similar to a table, figure or equation. The names of all listings used in your document can also be gathered together in a big list using \listoflistings, similar to a table of contents.

See the package documentation for more details.

Answer 2

In short you tag a reference with

\ref{type:Name}

and you reference that tag with

\label{type:Name}

For more info have a look at the appropriate page at the wikibook. There are also more specialized packages for referencing, but the concept is always the same.

As you have hundreds of examples, try to find a suitable, naming convention for your examples.

Update

For inter-document linking check the hypperef package