\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}
