Referencing Other Notes

Custom referencing commands

The default preamble, '/template/preamble.tex' contains the custom referencing commands \exhyperref and \excref which are just wrappers for the \hyperref and \cref commands. The usage is as follows. Suppose you have created a note and the reference for the note is NotePrefix (see Creating,-Deleting-and-Renaming-Notes#creating-new-notes)

\excref[label]{NotePrefix}

\exhyperref[label]{NotePrefix}{hyperlink text}

the label argument is optional, so for example \excref{NotePrefix} will just reference the top of the document with the corresponding prefix in the \externaldocument decoration. So, in the example above, if the file new_note_example.tex contained

\begin{thm} \label{theorem:example theorem}
This is an example.
\end{thm}

Then in another note, you could reference the theorem with cleverref using

\excref[theorem:example theorem]{NewNoteExample},

or put a hyperlink to the theorem with

\exhyperref[theorem:example theorem]{NewNoteExample}{Click here to go to the theorem}.

Running \excref adds the note prefix to the \cref output and if no label is provided just prints a hyperlink with link text \texttt{NotePrefix} to the note. It is perhaps illustrative to see an example.

Referencing Example

To give an example of referencing between notes we can run

python manage.py newnote main python manage.py newnote reference_example

Then this will create two files: /notes/slipbox/main.tex and /notes/slipbox/reference_example.tex. Both of these files will have the contents of `/template/note.tex'. If we edit main to

\RequirePackage{import}
\subimport{../template}{preamble.tex}

\title{Main Example}

\begin{document}
    \maketitle \currentdoc{note}
    %<*note>
     \begin{definition} \label{definition:example definition}
             This is an example definition
     \end{definition}
    %</note>
    %\printbibliography
\end{document}

And change reference_example.tex to

\RequirePackage{import}
\subimport{../template}{preamble.tex}

\title{Reference Example}

\begin{document}
    \maketitle \currentdoc{note}
    %<*note>
     \excref[definition:example definition]{Main} is in \exhyperref{Main}{the main file}. The exhyperref command also takes an optional argument being the label of the thing being referneced: \exhyperref[definition:example definition]{Main}{this text references the definition}. 
    %</note>
    %\printbibliography
\end{document}

then the referencing example file contains links to the definition in main. To compile these documents, create a folder in the root of the directory /pdf and then, from this directory run

pdflatex ../notes/slipbox/main.tex

pdflatex ../notes/slipbox/reference_example.tex

and the result should be

Alternatively you could run

python manage.py render_all_pdf or python manage.py render_all_html to render the notes either as pdf or html files.

How Note References Work

The LaTeX packages used to setup the note referencing are xr-hyper, hyperref and cleveref. The package xr-hyper sets up referencing between files. The command

\externaldocument[prefix-]{to_be_referenced}

in the preamble of a latex document allows labels from the file to_be_referenced to be accessed in the current file. For example, if the file to_be_referenced.tex contained

\begin{thm} \label{theorem:example theorem}
This is an example.
\end{thm}

Then the command \ref{prefix-theorem:example theorem} would reference the theorem as if it were in the same document. If this is then combined with hyperref and cleveref then these references become hyperlinks and \cref could be used instead of \ref for automatic descriptions. The path of the file to_be_referenced should be relative to where the file is being built, and it needs to be the path to the .aux file produced when the file to be referenced is rendered. At the moment, we recommend storing all note files in the /notes/slipbox folder (not in sub directories) so that there are no issues with building these files.

When the newnote command is run, the correct \externaldocument command is added to the file /notes/documents.tex which then allows any note to reference that note. By default, the prefix added to the \externaldocument is a capitalized version of the note name. So for example, if

python manage.py newnote new_note_example

is run, then the line

\externaldocument[NewNoteExample-]{new_note_eample}

will be added to documents.tex. To specify the prefix, the command

python manage.py newnote new_note_example SomethingElse

would add

\externaldocument[SomethingElse-]{new_note_example}

to /notes/documents.tex.

The \label{theorem:theorem name} in new_note_example could then be referenced using \ref{NewNoteExample-theorem:theorem name} from another note.