\documentclass[pagesize=auto, parskip=half, headings=normal]{scrartcl} \usepackage{fixltx2e} \usepackage{etex} \usepackage{lmodern} \usepackage[T1]{fontenc} \usepackage{textcomp} \usepackage{hologo} \usepackage{microtype} \usepackage{hyperref} \newcommand*{\mail}[1]{\href{mailto:#1}{\texttt{#1}}} \newcommand*{\pkg}[1]{\textsf{#1}} \newcommand*{\cls}[1]{\textsf{#1}} \newcommand*{\cs}[1]{\texttt{\textbackslash#1}} \makeatletter \newcommand*{\cmd}[1]{\cs{\expandafter\@gobble\string#1}} \makeatother \newcommand*{\opt}[1]{\texttt{#1}} \newcommand*{\meta}[1]{\textlangle\textsl{#1}\textrangle} \newcommand*{\marg}[1]{\texttt{\{}\meta{#1}\texttt{\}}} \addtokomafont{title}{\rmfamily} \title{The \pkg{smartref} package\thanks{This manual corresponds to \pkg{smartref.sty}~v1.9, dated~2002/02/28.}} \author{Giuseppe Bilotta\thanks{\mail{bourbaki@bigfoot.com}}} \date{2002/02/28} \begin{document} \maketitle The purpose of this package is to extend the capability of the the \cmd{\ref} command; precisely, whenever a label is set, this package records, along with the label, the values of some other counters (which, can be selected by the user); then, the value of these counters can be recalled, with a command similar to \cmd{\pageref}; moreover, this package adds a command (\cmd{\s\meta{name}ref}) for each counter added, that displays something only if the value of the \meta{name} counter is changed from when the label is set. For example, let's say that we are using the \cls{amsbook} class, and we are numbering theorems within sections; when we want to refer to a theorem in another section, same chapter, we just say `\verb|as in theorem \ref{zorn}|'; but if we want to refer to a theorem in another chapter, we have to set a label for that chapter and then say `\verb|as in theorem \ref{zorn}, in chapter \ref{chapterofzorn}|'; if we, later on, move the referenced theorem (or the referencing line) in some other chapter, we might need to update the references; with this package, there's no need for that: you say, at the beginning of the document: % \begin{verbatim} \addtoreflist{chapter} \end{verbatim} % and then, every \cmd{\label} is recorded alongside with the chapter in which it occurred. When we refer to the theorem, we might now say % \begin{verbatim} theorem \ref{zorn}, chapter \chapterref{zorn} \end{verbatim} % if we are sure it will always be in another chapter, or % \begin{verbatim} theorem \ref{zorn}\schapterref{zorn} \end{verbatim} % where the second command prints nothing if the chapter is the same as the current, or prints `\verb|, chap. \chapterref{zorn}|' if the chapter has changed. Since this command sequence is supposed to be used with quite a frequency, it is not-so-short-handed by \cmd{\srefchapterref} (\cmd{\sref\meta{name}ref}, in general). Here's a complete list of the commands made available by this package. % \begin{quote} \cmd{\addtoreflist}\marg{name} \end{quote} % This is the first command called: it says that the \meta{name} counter is to be recorded alongside with all the (following) labels; please use it \emph{before} defining any label, because the result is unknown if the SmartReference list changes during use (nothing special should happen, anyhow; it should work correctly). The previous command defines a few commands, whose name depends on the counter chosen. The commands are: % \begin{quote} \cmd{\sget\meta{name}val}\texttt{\{}\cs{\meta{variable}}\texttt{\}}\marg{foo} \end{quote} % This command gets the value of counter \meta{name} recorded with label \meta{foo}, and puts this value in the chosen \cs{\meta{variable}}. \begin{quote} \cs{\meta{name}ref}\marg{foo} \end{quote} % This command prints the value of the counter \meta{name} recorded with label \meta{foo}. \begin{quote} \cs{if\meta{name}changed} \end{quote} % `If' construct for the next two commands: % \begin{quote} \cmd{\is\meta{name}changed}\marg{foo} \end{quote} % Checks whether the \meta{name} counter is changed from value recorded with \meta{foo}, and sets \cs{\meta{name}changed} accordingly \begin{quote} \cmd{\s\meta{name}ref}\marg{foo} \end{quote} % This command prints nothing if the value of \meta{name} is not different, but prints % \begin{quote} \ttfamily , \cmd{\short\meta{name}name} \cs{\meta{name}ref}\marg{foo} \end{quote} % if the value did change; the \cmd{\short\meta{name}name} should be defined by the user. It queries by using the previous command. \begin{quote} \cmd{\sref\meta{name}ref}\marg{foo} \end{quote} % Equivalent of `\cmd{\ref}\marg{foo}\cmd{\s\meta{name}ref}\marg{foo}'. \pagebreak[2] The only options accepted, as for now, are \opt{chapter} and \opt{part}; \opt{chapter} does the following: % \begin{itemize} \item adds the \texttt{chapter} counter to the smart list \item defines \cmd{\shortchaptername} to be `Cap.' if \pkg{babel} is loaded with option \opt{italian}, `Chap.' otherwise \item defines \cmd{\smartref} to be \cmd{\srefchapterref} \end{itemize} \opt{part} does the following: % \begin{itemize} \item adds the \texttt{part} counter to the smart list \item defines \cmd{\shortpartname} to be `Parte' if \pkg{babel} is loaded with option \opt{italian}, `Part' otherwise \item defines \cmd{\smartref} to be \cmd{\srefpartref} if previously undefined, or adds \cmd{\spartref} to previous definition of \cmd{\smartref} (saved in \cmd{\nopart@smartref}) otherwise (this is mainly to be used after the option \opt{chapter}). \end{itemize} As of version~1.6, the package comes with a small style file: % \begin{quote} \texttt{byname.sty}; \end{quote} % it can be used alone, or within \pkg{smartref}, when the option \opt{byname} is used; it adds the command % \begin{quote} \cmd{\byname}\marg{label} \end{quote} % that can be used when referencing to a section (subsection, etc) by name instead of number. As of version~1.8, the same style file also provides the command \cmd{\byshortname} that does the same as \cmd{\byname}, except that it uses the ``short'' name (the one provided in square brackets). Note that the references create by \pkg{smartref} and \pkg{byname} are \emph{not} hyperlink, when \pkg{hyperref} is active. Maybe in the future \dots (You can still have ``named'' links with \pkg{hyperref} using the \pkg{nameref} style file provided with \pkg{hyperref} itself). \medskip\centerline{$***$}\medskip Please send me any bugs, comments, suggestions, hacks, etc etc etc \dots Giuseppe Bilotta Email: \mail{bourbaki@bigfoot.com} Heartily thanks to James Kilfiger (\mail{mapdn@csv.warwick.ac.uk}) whose consulence has been essential (let me say vital) to the birth of this small package in its first revision (v0.1); it was him who gave me the idea to hack the \cmd{\label} command, and then encouraged me to put the newborn code in a package (and telling me how to do it!); it was also him that pointed out a potential bug in documents where chapters don't start on a page on their own (seems that the bug is not present, anyway \dots). \medskip\centerline{$***$} \section*{TODOs:} \begin{itemize} \item \pkg{Babel}: instead of \cmd{\chaptername} (for example), this package uses \cmd{\short\-chapter\-name}, and this is not yet changed by \pkg{Babel}; you can set it up to your short form of chapter. Please send me the short names, so that I can implement them. \item Maybe put an option (\opt{long}) to make \cmd{\short\meta{name}name} an alias for \cs{\meta{name}name} \item Options: If the option is not recognized, check if it's a counter, and add it; otherwise, do nothing \item Smartrefs: check for counters that get reset by other counters (section in chapter, etc); maybe link to the \cmd{\@addtoreset} internal command \dots \item \pkg{ByName}: refine, and add commands to do both references with a single command \end{itemize} \medskip\centerline{$***$} \section*{History:} \begin{labeling}{v1.9} \item[v0.1] First release (only did chapter and part). \item[v1.0] First customizable release. \item[v1.1] Made it work with \pkg{HyperRef}. \item[v1.5] Added \pkg{nameref.sty}: reference by name. \item[v1.6] Changed name to \pkg{byname.sty}, because of name conflict with style file from the \pkg{HyperRef} bundle. \item[v1.8] Fixed bugs in \pkg{smartref}, changed behaviour for unknown options, fixed bug in \pkg{byname} that actually prevented it from functioning properly. \item[v1.9] Fixed limitation with \hologo{AmSLaTeX}: would not handle \cmd{\labels} within equation because \hologo{AmSLaTeX} redefines the \cmd{\label} command for equations.\\ Made \cmd{\smartref} robust. \end{labeling} \end{document}