summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/titleref/titleref.tex
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
committerNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
commite0c6872cf40896c7be36b11dcc744620f10adf1d (patch)
tree60335e10d2f4354b0674ec22d7b53f0f8abee672 /macros/latex/contrib/titleref/titleref.tex
Initial commit
Diffstat (limited to 'macros/latex/contrib/titleref/titleref.tex')
-rw-r--r--macros/latex/contrib/titleref/titleref.tex89
1 files changed, 89 insertions, 0 deletions
diff --git a/macros/latex/contrib/titleref/titleref.tex b/macros/latex/contrib/titleref/titleref.tex
new file mode 100644
index 0000000000..6d184ed2c9
--- /dev/null
+++ b/macros/latex/contrib/titleref/titleref.tex
@@ -0,0 +1,89 @@
+\documentclass[a4paper]{article}
+\usepackage[a4paper]{geometry}
+\usepackage{miscdoc}
+\usepackage[scaled=0.85]{luximono}
+\begin{document}
+\title{The \Package{titleref} package}
+\author{Donald Arseneau\thanks{Documentation file assembled by Robin
+ Fairbairns}}
+\date{5th April 2005, version 3.1}
+\maketitle
+
+The package provides a command \cs{titleref} to cross-reference the
+titles of sections (etc.). The \cs{label} command is changed to
+remember the title for such a reference. You can use \cs{titleref}
+just as you use \cs{ref} and \cs{pageref}.
+
+Titles for numbered sectioning units and for floats with captions are
+the same as the respective \textsc{toc}, \textsc{lof}, or \textsc{lot}
+entry (even when no \textsc{toc}, or whatever, is printed). When a
+short title is provided (\cmdinvoke{section}[short]{long}, etc.\@) it
+will be used for the \cs{titleref}. This is especially useful for
+figure captions. Unnumbered sections take their title reference from
+the printed title. Beware!~--- This turns the title into a moving
+argument when it normally is not, and will cause weird errors if there
+are `fragile' commands present.
+
+Enumerated lists do not have titles and simply inherit the title of
+their section.
+
+The format of the title reference is controlled by the command
+\cs{theTitleReference}, which can be redefined with \cs{renewcommand}.
+It takes two parameters: the number and the title. The number is
+just the regular \cs{ref} and it is WRONG in unnumbered sections.
+Beware! The default definition is the unadorned title. You could
+do, for example,
+\cmdinvoke{renewcommand}{\cs{theTitleReference}}[2]{\#1\cs{\ }\cs{emph}{\#2}}
+
+The title of the current section is also available without \cs{label}:
+use the command \cs{currenttitle} to generate a \cs{titleref} to the
+current section. If you have redefined \cs{theTitleReference} to
+print the number with the title, be aware that the two may not
+correspond: in a numbered list the number will show the current item
+but the title will show the current section, while in an unnumbered
+section the number will show some previous section number.
+
+\section*{Options: \option[usetoc] and \option[nostar]}
+
+In the default operation, the titles are recorded by a command
+inserted into the various sectioning commands (\cs{@sect},
+\cs{@ssect}, \cs{@chapter}, \cs{@schapter}, \cs{@part}, \cs{@spart},
+and \cs{@caption}). If this creates conflicts with some other
+package, you can use an entirely different method by specifying
+\cmdinvoke{usepackage}[usetoc]{titleref}. As the name implies, this
+option records the titles from the table-of-contents entry without
+redefining the sectioning commands. (This method was used in older
+versions of the package.)
+
+Since there are no \textsc{toc} entries for the `star' versions of
+sectioning commands, they are still redefined. The additional option
+\option[nostar] (\cmdinvoke{usepackage}[usetoc,nostar]{titleref})
+prevents the redefinitions, but then "\cs{section*}" will not generate
+a title reference. If you try to refer to the title of an unnumbered
+section while \option[nostar] is in effect, you will get the title of
+the previous section.
+
+Under the \option[usetoc] option, the current title will always be
+overridden by an \cs{addcontentsline} command before the \cs{label},
+even for starred section commands under the \option[nostar] option.
+
+The big problem with the \option[usetoc] method is that \cs{titleref}
+will not refer to a \cs{label} which was given in the title or caption
+itself; the label must be placed after the sectioning command or the
+caption. If you make a title-reference to a label given in a title,
+you will get a warning message.
+
+\section*{Compatibility}
+
+The package was early in the field with this functionality, but it now
+has competitors. The package \emph{will not} work with other packages
+that manipulate the labelling mechanism, such as \Package{hyperref};
+for that title references with \Package{hyperref} you must use the
+\Package{nameref} package in place of \Package{titleref}.
+
+The \Package{zref} package also diddles with the \cs{label}--\cs{ref}
+mechanism, and will equally not work with \Package{titleref}.
+\Package{zref} itself doesn't provide a title reference facility: you
+need to use \Package{hyperref} and \Package{nameref} for that.
+
+\end{document}