.. !split

Cross-referencing across chapters (or books)
============================================

.. index:: cross-referencing

.. index:: generalized references

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

.. code-block:: latex

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

and get it out as

.. code-block:: text

        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.

.. index:: ref generalized reference

.. index:: refch generalized reference

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

.. code-block:: doconce

        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 below box could be typeset as .. admonition: Attention
   but we have decided not to do so since the admon needs a title
   (the box formatting is therefore just ignored)

The world's most famous equation is 
as found in the document `Some document <http://hplgit.gthub.io/setup4book-doconce/doc/pub/fake>`__
[Ref3]_.


More detailed information about generalized cross-references is
found in the `DocOnce manual <http://hplgit.github.io/doconce/doc/pub/manual/html/manual.html#generalized-cross-referencing>`__.
In particular, one has to insert ``# Externaldocuments:`` commands in
all ``main_*.do.txt`` files that includes files with generalized
references.


.. admonition:: 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.