******************************************************************************
Extension internals
******************************************************************************

References between distinct PDF documents
==============================================================================

Resolving of references
------------------------------------------------------------------------------

.. uml::

    LaTeXBuilder -> LaTeXBuilder: assemble_doctree
    LaTeXBuilder -> BuildEnvironment: resolve_references
    BuildEnvironment -> StandardDomain: resolve_xref
    StandardDomain -> StandardDomain: build_reference_node
    StandardDomain -> LaTeXBuilder: get_relative_uri
    LaTeXBuilder -> LaTeXBuilder: get_target_uri
    alt Sphinx' builtin LaTeXBuilder
        LaTeXBuilder -> LaTeXBuilder: Check that reference\nis in current LaTeX\noutput document
        LaTeXBuilder ->]: raise NoUri
    else This extension
        LaTeXBuilder --> StandardDomain: Inter-document URI string\nfor reference node
    end

Resolving of references
------------------------------------------------------------------------------

.. uml::

    LaTeXWriter -> document: walkabout
    ... Traverse document tree ...
    document -> LaTeXTranslator: visit_reference
    ... Traverse document tree ...

******************************************************************************
Extension internals
******************************************************************************

References between distinct PDF documents
==============================================================================

Sphinx references point to the source file of their targets. That matches the
HTML builder well, because generally one source file turns into one HTML
output file. However, the LaTeX builder generally puts multiple source files
into a single output file.

#. Collect ``latex_document`` nodes:
   iterate over all source files and traverse their doctrees.
#. Assemble doctrees of ``latex_document`` nodes:
   use Sphinx' built-in assembling logic.
#. Determine which source files went into which ``latex_document`` nodes:
   traverse the doctree of each ``latex_document`` node looking for
   ``start_of_file`` nodes.

Resolving of references
------------------------------------------------------------------------------

.. uml::

    LaTeXBuilder -> LaTeXBuilder: assemble_doctree
    LaTeXBuilder -> BuildEnvironment: resolve_references
    BuildEnvironment -> StandardDomain: resolve_xref
    StandardDomain -> StandardDomain: build_reference_node
    StandardDomain -> LaTeXBuilder: get_relative_uri
    LaTeXBuilder -> LaTeXBuilder: get_target_uri
    alt Sphinx' builtin LaTeXBuilder
        LaTeXBuilder -> LaTeXBuilder: Check that reference\nis in current LaTeX\noutput document
        LaTeXBuilder ->]: raise NoUri
    else This extension
        LaTeXBuilder --> StandardDomain: Inter-document URI string\nfor reference node
    end

Resolving of references
------------------------------------------------------------------------------

.. uml::

    LaTeXWriter -> document: walkabout
    ... Traverse document tree ...
    document -> LaTeXTranslator: visit_reference
    ... Traverse document tree ...

Expand notes on inter-doc reference functionality
Expand notes on inter-doc reference functionality
