Cross-referencing across chapters (or books)

A fundamental problem when writing a book and stand-alone chapters arises with cross-referencing. In a book file it makes sense to refer to an equation in any chapter, say (4.23), while in a stand-alone chapter references to equations or sections in other stand-alone documents will not work. That is, LaTeX has a native mechanism for this, the xr package, where one can register a set of .aux files for other LaTeX documents and refer directly to these labels and get them right. It is then possible to write something like

see (\eqref{sec:results:u:eq}) in \cite{Hansen_2011b}

and get it out as

see (2.37) in [12]

provided our .tex file contains \externaldocument{myother} and the label sec:results:u:eq is defined in myother.aux. DocOnce has generalized this feature so it works for non-LaTeX formats as well. It is called generalized cross-references. You can then write such references across chapters and get all labels right whether you produce the entire book or individual chapters.

Here is an example on a generalized reference to an equation in another chapter:

The world's most famous equation is ref[(ref{setup:fake:Emc2})][ in
cite{Langtangen_dobook_fake}][
as found in the document "Some document":
"http://hplgit.gthub.io/setup4book-doconce/doc/pub/fake"
cite{Langtangen_dobook_fake}].

This sentence is rendered as follows in the present format (sphinx):

The world’s most famous equation is as found in the document Some document [Ref4].

More detailed information about generalized cross-references is found in the DocOnce manual. In particular, one has to insert # Externaldocuments: commands in all main_*.do.txt files that includes files with generalized references.

Tip: Limit generalized references to those strictly needed

Books often contain a lot of cross references, and making generalized references out of all them can be quite some job. A convenient way of saving boring work is to enclose nice-to-have, yet not strictly needed, references in Mako or Preprocess if statements (typically if BOOK == "book") such that they appear in the full book but not in individual chapters.

However, if individual chapters in HTML are to be one official format of the book, you should make the chapters identical to the book and make generalized references out of all references to other chapters.