summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/stex/doc/packages/stex-references.tex
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/stex/doc/packages/stex-references.tex')
-rw-r--r--macros/latex/contrib/stex/doc/packages/stex-references.tex90
1 files changed, 87 insertions, 3 deletions
diff --git a/macros/latex/contrib/stex/doc/packages/stex-references.tex b/macros/latex/contrib/stex/doc/packages/stex-references.tex
index 11de003e9b..3850d644ee 100644
--- a/macros/latex/contrib/stex/doc/packages/stex-references.tex
+++ b/macros/latex/contrib/stex/doc/packages/stex-references.tex
@@ -1,6 +1,90 @@
-\begin{sfragment}[id=sec.references]{Referencing Symbols and Statements}
-\textcolor{red}{TODO: references documentation}
-\end{sfragment}
+If we take features like \stexcode"\inputref" and \stexcode"\mhinput"
+(and the \stexcode"sfragment"-environment, see
+\sref[file=stex-document-structure]{sec:ds:intro}[in=../stex-manual,title={the \sTeX{}3 manual}]) seriously,
+and build large documents modularly from individually compiling documents for sections, chapters
+and so on, cross-referencing becomes an interesting problem.
+
+Say, we have a document |main.tex|, which \stexcode"\inputref"s a section
+|section1.tex|, which references a definition with label |some_definition| in
+|section2.tex| (subsequently also inputted in |main.tex|).
+Then the numbering of the definition will depend on the \emph{document context}
+in which the document fragment |section2.tex| occurs - in |section2.tex| itself
+(as a standalone document), it might be \emph{Definition 1}, in |main.tex| it might
+be \emph{Definition 3.1}, and in |section1.tex|, the definition \emph{does not even occur}, so
+it needs to be referenced by some other text.
+
+What we would want in that instance is an equivalent of \stexcode"\autoref", that takes
+the document context into account to yield something like \emph{Definition 1}, \emph{Definition 3.1}
+or ``\emph{Definition 1 in the section on Foo}'' respectively.
+
+The \stexcode"\sref" command attempts to do precisely that. Unlike plain \stexcode"\ref", \stexcode"\autoref"
+etc., \stexcode"\sref" refers to not just a \emph{label}, but instead a pair consisting of a \emph{label}
+and the \emph{document} in whose context we want to refer to it. Conversely, every \emph{document}
+(i.e. standalone compilable |.tex|-file) keeps track of the ``names'' (\emph{Definition 3.1} etc.) for every
+label as determined in the context of the document, and stores them in a dedicated file |\jobname.sref|.
+Additionally, every document has a ``\emph{reference name}'' (e.g. ``\emph{the section on Foo}'').
+This allows us to refer to ``label $x$ in document $D$'' to yield ``\emph{Definition 1 in the section on Foo}''.
+And of course, \sTeX can decide based on the current document to either refer to the label by its
+``full name'' or directly as e.g. \emph{Definition 3.1} depending on whether the label occurs in
+the current document anyway (and link to it accordingly).
+
+\paragraph{} For that to work, we need to supply (up to) three pieces
+of information:
+\begin{itemize}
+ \item The \emph{label} of the reference target (e.g. |some_definition|),
+ \item (optionally) the \emph{file}/document containing the reference target
+ (e.g. |section2|).
+ This is not strictly necessary, but allows for additional disambiguation
+ between possibly duplicate labels across files, and
+ \item (optionally) the document context, in which we want to
+ refer to the reference target (e.g. |main|).
+\end{itemize}
+Additionally, the document in which we want to reference a label needs
+a title for external references.
+
+
+\begin{function}{\sref}
+ \begin{syntax} \cs{sref}|[archive=|\meta{archive1}|,file=|\meta{file}|]|%
+ \Arg{label}|[archive=|\meta{archive2}|,in=|\meta{document-context}|,title=|\meta{title}|]| \end{syntax}
+ This command references \meta{label} (declared in \meta{file} in \meta{archive1}).
+ If the object (section, figure, etc.) with that label occurs ultimately
+ in the same document, \cs{sref} will ignore the second set of optional arguments
+ and simply defer to \cs{autoref} if that command exists, or \cs{ref} if the \pkg{hyperref}
+ package is not included.
+
+ If the referenced object does \emph{not} occur in the current document however,
+ \cs{sref} will refer to it by the object's name as it occurs in
+ the file \meta{document-context} in \meta{archive2}.
+
+For example, the reference to the \stexcode"sfragment"-environment above
+will appear as ``subsection 7.2.1 (Introduction) in the \sTeX{}3 manual''
+if you are reading this in the package documentation for |stex-references|
+directly, but as a linked ``subsection 7.2.1'' in the full documentation
+or manual. This is achieved using
+
+\stexcode"\sref[file=stex-document-structure]{sec:ds:intro}[in=../stex-manual,title={the \sTeX{}3 manual}]".
+
+\end{function}
+
+For a further example, the following:
+\begin{center}
+ \sref[file=../stex-doc]{part:extends}[in=../stex-doc,title={the full \sTeX{}3 documentation}]
+\end{center}
+will say ``Part III'' (and link accordingly) in the full documentation,
+and ``Part III (Extensions) in the full \sTeX{}3 documentation''
+everywhere else. This is achieved using
+
+\stexcode"\sref[file=../stex-doc]{part:extends}[in=../stex-doc,title={the full \sTeX{}3 documentation}]".
+
+\begin{function}{\extref}
+ \begin{syntax} \cs{sref}|[archive=|\meta{archive1}|,file=|\meta{file}|]|%
+ \Arg{label}|{archive=|\meta{archive2}|,in=|\meta{document-context}|,title=|\meta{title}|}| \end{syntax}
+ The \cs{extref}-command behaves exactly like \cs{sref}, but takes
+ \emph{required} the document context argument and will always use it
+ for generating the document text, regardless of whether the label
+ occurs in the current document.
+\end{function}
+
%%% Local Variables:
%%% mode: latex