titleref own pkg, doc

git-svn-id: svn://tug.org/texlive/trunk@18404 c570f23f-e606-0410-a88d-b1316a301751

1 files changed, 152 insertions, 0 deletions

diff --git a/Master/texmf-dist/tex/latex/titleref/titleref.sty b/Master/texmf-dist/tex/latex/titleref/titleref.sty
new file mode 100644
index 00000000000..33b09411d21
--- /dev/null
+++ b/Master/texmf-dist/tex/latex/titleref/titleref.sty
@@ -0,0 +1,152 @@
+%  TITLEREF.STY  ver 3.1  2001-04-05   Donald Arseneau   <asnd@triumf.ca>
+%  This is free unsupported software, released to the public domain.
+%
+%  This package provides a "\titleref" command to cross-reference the titles 
+%  of sections.  The "\label" command is changed to remember the title for 
+%  such a reference.  Use "\titleref" just like "\ref" and "\pageref".  
+%
+%  Titles for numbered sectioning units and for floats with captions are
+%  the same as the respective TOC, LOF, or LOT entry (even when no TOC is
+%  printed).  When a short title is provided ("\section[short]{long}")
+%  it will be used for the "\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
+%  "\theTitleReference", which can be redefined with "\renewcommand".
+%  It takes two parameters: the number and the title. The number is
+%  just the regular "\ref" and it is WRONG in unnumbered sections.
+%  Beware!  The default definition is the unadorned title.  You could
+%  do, for example, "\renewcommand{\theTitleReference}[2]{#1\ \emph{#2}}".
+%
+%  The title of the current section is also available without "\label":
+%  Use the command "\currenttitle" to generate a "\titleref" to the current
+%  section.  If you have redefined "\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, but in an unnumbered section the number will show
+%  some previous section number.
+%
+%  Options:  [usetoc]  and  [nostar]
+%
+%  In the default operation, the titles are recorded by a command inserted
+%  into the various sectioning commands ("\@sect", "\@ssect", "\@chapter",
+%  "\@schapter", "\@part", "\@spart", and "\@caption").  If this creates
+%  conflicts with some other package, you can use an entirely different
+%  method by specifying "\usepackage[usetoc]{titleref}".  As the name
+%  implies, this option records the titles from the table-of-contents
+%  entry without redefining the sectioning commands.  (This is the method
+%  used in older versions.)
+%
+%  Since there are no TOC entries for the `star' versions of sectioning 
+%  commands, they are still redefined.  The additional option "[nostar]"
+%  ("\usepackage[usetoc,nostar]{titlerrf}") prevents the redefinitions,
+%  but then "\section*" will not generate a title reference.  If you try
+%  to refer to the title of an unnumbered section while "[nostar]" is in
+%  effect, you will get the title of the previous section.
+%
+%  Under the "[usetoc]" option, the current title will always be overridden
+%  by an "\addcontentsline" command before the "\label", even for starred
+%  section commands under the "[nostar]" option.
+%
+%  The big problem with the "[usetoc]" method is that "\titleref" will
+%  not refer to a "\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.
+%
+\NeedsTeXFormat{LaTeX2e}
+\ProvidesPackage{titleref}[2001/04/05 v3.1 \space 
+    Cross-references with titles.]
+
+\newcommand{\theTitleReference}[2]{#2}
+%
+\let\TR@old@label\label
+%
+% This redefinition of \label is intended to work with other redirections
+% of \label, if they record extra information in a similar way.
+\def\label#1{\@bsphack\begingroup
+  \protected@edef\@currentlabel{\protect\TR@TitleReference
+      {\@currentlabel}{\TR@currentTitle}}%
+  \TR@old@label{#1}%
+  \endgroup \@esphack}%
+%
+\def\TR@gettitle#1{\begingroup \let\protect\@unexpandable@protect
+    \let\label\TR@nestwarn \let\index\@gobble \let\glossary\@gobble
+    \let\markboth\@gobbletwo \let\@mkboth\@gobbletwo \let\markright\@gobble
+    \edef\@tempa{\noexpand\def\noexpand\TR@currentTitle{#1}}%
+  \expandafter\endgroup\@tempa}
+%
+\let\TR@nestwarn\@gobble
+%
+\let\TR@TitleReference\@firstoftwo
+%
+% Allow aux file to be used after titleref is removed:
+\AtBeginDocument{\immediate\write\@mainaux{\string\let
+  \string\TR@TitleReference\string\@firstoftwo}}
+%
+\DeclareRobustCommand{\titleref}[1]{\begingroup \let\numberline\@gobble
+  \let\TR@TitleReference\TR@theTR % interrupt recursion of \ref
+  \ref{#1}\endgroup}
+%
+\DeclareRobustCommand{\currenttitle}{\begingroup \let\numberline\@gobble
+  \theTitleReference\@currentlabel\TR@currentTitle\endgroup}
+%
+%
+\def\TR@theTR{0}
+\DeclareOption{usetoc}{\edef\TR@theTR{1\TR@theTR}}%
+\DeclareOption{nostar}{\edef\TR@theTR{\TR@theTR 1}}%
+\ProcessOptions\relax
+%
+%  Put hooks in "star" commands if not [usetoc,nostar]
+\ifnum\TR@theTR<100
+%
+\AtBeginDocument{\let\TR@old@ssect\@ssect
+  \def\@ssect#1#2#3#4#5{\TR@gettitle{#5}\TR@old@ssect{#1}{#2}{#3}{#4}{#5}}%
+ \@ifundefined{@schapter}{}{\let\TR@old@schapter\@schapter
+  \def\@schapter#1{\TR@gettitle{#1}\TR@old@schapter{#1}}}
+ \@ifundefined{@spart}{}{\let\TR@old@spart\@spart
+  \def\@spart#1{\TR@gettitle{#1}\TR@old@spart{#1}}}
+}
+%
+\fi
+%
+%  Put hooks in other commands if not [usetoc]
+\ifnum\TR@theTR<9
+%
+\AtBeginDocument{%
+ \let\TR@old@sect\@sect \def\@sect#1#2#3#4#5#6[#7]{\TR@gettitle{#7}%
+  \TR@old@sect{#1}{#2}{#3}{#4}{#5}{#6}[{#7}]}%
+ \@ifundefined{@chapter}{}{\AtBeginDocument{\let\TR@old@chapter\@chapter
+  \def\@chapter[#1]{\TR@gettitle{#1}\TR@old@chapter[{#1}]}}}
+ \@ifundefined{@part}{}{\AtBeginDocument{\let\TR@old@part\@part
+  \def\@part[#1]{\TR@gettitle{#1}\TR@old@part[{#1}]}}}%
+ \let\TR@old@caption\@caption \long\def\@caption#1[#2]#3{\TR@gettitle{#2}%
+  \TR@old@caption{#1}[{#2}]{#3}}
+}
+%
+\else % [usetoc], hook into \addcontentsline and prohibit labels in titles
+%
+\DeclareRobustCommand\TR@nestwarn[1]{\PackageWarning{titleref}%
+  {Label \string"#1\string" was put in a title,\MessageBreak
+   so the \noexpand\titleref is incorrect}}
+%
+\let\TR@old@addcontentsline\addcontentsline
+%
+\def\addcontentsline#1#2#3{%
+  \TR@old@addcontentsline{#1}{#2}{#3}%
+  \TR@gettitle{\relax#3}}
+%
+\fi
+%
+\let\TR@currentTitle\@empty
+%
+% proper definition:
+\def\TR@theTR{\let\TR@TitleReference\@firstoftwo \theTitleReference}
+%
+\endinput % the end