diff options
| author | Karl Berry <karl@freefriends.org> | 2017-09-01 01:32:22 +0000 |
|---|---|---|
| committer | Karl Berry <karl@freefriends.org> | 2017-09-01 01:32:22 +0000 |
| commit | 24b60599fe0fe2a672e102d295ab16b874bca2fd (patch) | |
| tree | 0345ab1080b9c1d9c525f39a039e0412bc527fbc /Master/texmf-dist/doc/latex/robustindex | |
| parent | d23537f56720850db3dedce1b78bd65bbd6d0b0a (diff) | |
robustindex (31aug17)
git-svn-id: svn://tug.org/texlive/trunk@45185 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/latex/robustindex')
| -rw-r--r-- | Master/texmf-dist/doc/latex/robustindex/README | 45 | ||||
| -rw-r--r-- | Master/texmf-dist/doc/latex/robustindex/README.md | 18 | ||||
| -rw-r--r-- | Master/texmf-dist/doc/latex/robustindex/robustindex.html | 43 | ||||
| -rw-r--r-- | Master/texmf-dist/doc/latex/robustindex/robustmanual.pdf | bin | 0 -> 103616 bytes | |||
| -rw-r--r-- | Master/texmf-dist/doc/latex/robustindex/robustmanual.tex | 105 | ||||
| -rw-r--r-- | Master/texmf-dist/doc/latex/robustindex/robustsample.pdf | bin | 116222 -> 178667 bytes | |||
| -rw-r--r-- | Master/texmf-dist/doc/latex/robustindex/robustsample.tex | 60 | ||||
| -rw-r--r-- | Master/texmf-dist/doc/latex/robustindex/stind.html | 46 |
8 files changed, 206 insertions, 111 deletions
diff --git a/Master/texmf-dist/doc/latex/robustindex/README b/Master/texmf-dist/doc/latex/robustindex/README deleted file mode 100644 index 0fb91812887..00000000000 --- a/Master/texmf-dist/doc/latex/robustindex/README +++ /dev/null @@ -1,45 +0,0 @@ - Package robustindex.sty, Wilberd van der Kallen Feb 2005. - http://www.math.uu.nl/people/vdkallen/stind.html - - This package addresses two issues. - - 1. Third parties often change the page numbers without rerunning makeindex. - (Yes, it happened also to my 1993 book.) - - One would like to make the page numbers in the index entries more robust. - We use the \pageref mechanism for that. Only after adding, deleting or - otherwise modifying an \index{entry}, or after changing the order of the - index entries, does one have to rerun makeindex. - Other changes do not matter, as long as one runs LaTeX or pdflatex twice. - - 2. The theindex environment does not create a hyperref destination. - - Therefore we introduce \indexincontents. - It does what \addcontentsline{toc}{chapter}{Index} or - \addcontentsline{toc}{section}{Index} should have done in the first place: - When one clicks on the link that displays the word Index, one actually ends - up in the index. - - Our package performs no miracles. But in simple situations all you need is - adding the \usepackage{robustindex} to the preamble. - - The implicit page range formation of makeindex is disabled. - Commands of the type \index{entry|editing command} are supported, - but much more naively than in the encapsulating mechanism of makeindex. - - If you use hyperref, choose the option hyperindex=false, because our method - to set up these hyperlinked indices is different. - We tested a little with - - \usepackage[plainpages=false,hyperindex=false]{hyperref} - - See robustsample.tex for more details and illustrations. - - There you find examples like - - \index{alpha!see beta} - \index{alpha!see also gamma\gobblepageref} - - \indexincontents % always put this before the index. - - See also robustglossary.sty diff --git a/Master/texmf-dist/doc/latex/robustindex/README.md b/Master/texmf-dist/doc/latex/robustindex/README.md new file mode 100644 index 00000000000..542ee83337a --- /dev/null +++ b/Master/texmf-dist/doc/latex/robustindex/README.md @@ -0,0 +1,18 @@ +Package robustindex.sty, Wilberd van der Kallen Feb 2017. + + This package uses \pageref to ensure that the page numbers in the index are synchronous + with the manuscript, even when a third party changes the page numbers and fails to + rerun makeindex. + + Some features of makeindex had to be disabled. + + https://www.staff.science.uu.nl/~kalle101/stind.html + +% Copyright 2005, 2017 Wilberd van der Kallen +% +% This file may be distributed under the conditions of the LaTeX Project Public +% License, either version 1.2 of this license or (at your option) any +% later version. The latest version of this license is in +% http://www.latex-project.org/lppl.txt +% and version 1.2 or later is part of all distributions of LaTeX +% version 1999/12/01 or later.
\ No newline at end of file diff --git a/Master/texmf-dist/doc/latex/robustindex/robustindex.html b/Master/texmf-dist/doc/latex/robustindex/robustindex.html deleted file mode 100644 index 2072acc9430..00000000000 --- a/Master/texmf-dist/doc/latex/robustindex/robustindex.html +++ /dev/null @@ -1,43 +0,0 @@ -<HTML> -<HEAD> -<TITLE>Robust index package for LaTeX</TITLE> -</HEAD> - -<BODY bgcolor="#FFFFFF"> -<H1><A NAME="top">Robust index package for LaTeX</A></H1> - -We are experimenting with a package -<A HREF="robustindex.sty">robustindex.sty</A> -that tries to remedy two problems. -<DL> -<DD><H2>Page numbers changed by third party without rerunning makeindex</H2> -Amazingly often a third party changes the page numbers without rerunning -makeindex. (Yes, it happened also to my 1993 book.) -<P>It is much nicer to have an index that adapts itself to all -changes but the adding/deleting of an \index{entry} command. -<P>Only after such adding and/or deleting do we want to run makeindex. -<DD><H2>Index contains no destination for hyperlink</H2> -The theindex environment lacks a destination for hyperlinks. -That is a nuisance when one wants to add the index to -the bookmarks or to the table of contents in a pdf file. -</DL> - -We have packages <A HREF="robustindex.sty">robustindex.sty</A> and - <A HREF="robustglossary.sty">robustglossary.sty</A>. They are used in - the sample file <A HREF="robustsample.tex">robustsample.tex</A>. -<P>After -<DL> -<DD>pdflatex <A HREF="robustsample.tex">robustsample.tex</A> -<DD>pdflatex robustsample.tex -<DD>makeindex robustsample -<DD>pdflatex robustsample.tex -<DD>pdflatex robustsample.tex -</DL> -you should have something like <A HREF="robustsample.pdf">this PDF file</A>. - -<BR><BR><BR> -<A HREF="http://www.math.uu.nl/people/vdkallen/">Wilberd van der Kallen</A> - - -</BODY> -</HTML> diff --git a/Master/texmf-dist/doc/latex/robustindex/robustmanual.pdf b/Master/texmf-dist/doc/latex/robustindex/robustmanual.pdf Binary files differnew file mode 100644 index 00000000000..829b5961b42 --- /dev/null +++ b/Master/texmf-dist/doc/latex/robustindex/robustmanual.pdf diff --git a/Master/texmf-dist/doc/latex/robustindex/robustmanual.tex b/Master/texmf-dist/doc/latex/robustindex/robustmanual.tex new file mode 100644 index 00000000000..df3a549df5f --- /dev/null +++ b/Master/texmf-dist/doc/latex/robustindex/robustmanual.tex @@ -0,0 +1,105 @@ +% robustmanual.tex +\documentclass{article} +\usepackage{makeidx} +\usepackage{robustindex} +\usepackage[hyperindex=false]{hyperref} + +\title {Manual of robustindex package} + +\author{Wilberd van der Kallen\index{Wilberd}} +\date{2017} + +\makeindex % obligatory with robustindex + +\begin{document} + +\maketitle + +\section*{Introduction} + +\index{discussion|(} + +Amazingly often a third party changes the page numbers without rerunning +makeindex. We therefore want to have an index in which the page numbers automatically synchronise with the document. + +The package \texttt{robustindex} achieves this +by invoking the \verb|\pageref| mechanism on automatically generated labels +of the form \verb|ind.2|, \verb|ind.4|, \dots. + +Only after adding/deleting/modifying an \verb|\index{|\textit{entry}\verb|}| +command, or after changing the order of \verb|\index{|\textit{entry}\verb|}| +commands, does one have to rerun makeindex. (How would you change the order? By moving a block of text that contains +an \verb!\index! command.) + +Make sure to run makeindex at least once after the last change to the \verb!\index! commands. +Keep an eye on the \TeX\ log file. It often contains a warning that you need to rerun \LaTeX\ or makeindex. + +\section*{Standard usage} +Put +$$ +\verb!\usepackage{makeidx}! +$$ +$$ +\verb!\usepackage{robustindex}! +$$ +$$\verb!\makeindex!$$ +in your preamble. +If you use the hyperref package, go against their advice and put +$$\verb!\usepackage{robustindex}! $$ +\emph{after} the hyperref declaration, \emph{or} +turn off \verb!hyperindex! as in +$$ +\verb!\usepackage[plainpages=false,hyperindex=false]{hyperref}!. +$$ + +That should be all. (You may have to trash old auxiliary files.) + +You can now use \index{alpha}\index{gamma|textbf} +$$\verb!\index{alpha}!$$ +$$\verb?\index{alpha!see beta}?$$ +$$\verb!\index{gamma|textbf}!$$ +$$\verb!\index{ampersand@\&|textbf}!$$ +in the usual manner. +\index{ampersand@\&|textbf} + +See \url{https://en.wikibooks.org/wiki/LaTeX/Indexing}.\\ + + + +The symbol \verb!|! has a special meaning inside an \verb!\index! command and cannot be escaped. +To get \verb!|! as output use the \LaTeX\ command \verb!\vert!. + + +We also have a command \verb!\gobblepageref! +used as in +$$\verb?\index{alpha!see also gamma\gobblepageref}?$$ +\index{alpha!see also gamma\gobblepageref} + +\subsection*{Page ranges} +Some features of makeindex had to be repurposed. +In particular, \emph{implicit} page ranges are no longer supported. + + +If you want a page range in the index you have to use +the \emph{explicit} page range mechanism of makeindex as in +$$\verb!\index{discussion|(}!$$% used above + +%\index{discussion}% inside range, hence would be suppressed. + +%\index{discussion|blah}% inside range, hence would be suppressed. + + + + +on the first page of the range, followed by +$$\verb!\index{discussion|)}!$$\index{discussion|)}on the last page of the range.\\ + +\subsection*{Table of contents} +If there is a table of contents and you want the index listed in it, put the command +$$\verb!\indexincontents!$$ +somewhere before the \verb!\printindex!. +\index{alpha!see beta} + +We now use $\verb!\printindex!$ to get an index (on a new page). +\printindex +\end{document} diff --git a/Master/texmf-dist/doc/latex/robustindex/robustsample.pdf b/Master/texmf-dist/doc/latex/robustindex/robustsample.pdf Binary files differindex 49ca44aa5f3..9c5280400c2 100644 --- a/Master/texmf-dist/doc/latex/robustindex/robustsample.pdf +++ b/Master/texmf-dist/doc/latex/robustindex/robustsample.pdf diff --git a/Master/texmf-dist/doc/latex/robustindex/robustsample.tex b/Master/texmf-dist/doc/latex/robustindex/robustsample.tex index 9e88837557c..14cf57ea1ec 100644 --- a/Master/texmf-dist/doc/latex/robustindex/robustsample.tex +++ b/Master/texmf-dist/doc/latex/robustindex/robustsample.tex @@ -25,18 +25,21 @@ \chapter*{Preface} \addcontentsline{toc}{chapter}{Preface} \markboth{Preface}{Preface} +This file illustrates some features of the \verb!robustindex! package. + +Although this is not a book, we have chosen the book style for illustration. + We will recall the purpose of \verb|robustindex.sty| in appendix \ref{purpose}. -Although this is not a book, we have chosen the book style for illustration. If you want to see how \verb|robustindex.sty| may be used, compare the file \verb|robustsample.tex| or appendix \ref{appendix} with the output. If you are interested in our usage of \verb|robustglossary.sty|, you must read -the file \verb|robustsample.tex|. +the source file \verb|robustsample.tex|. -This preface has an \emph{indexed term}.\index{indexed term} +This preface has an \emph{indexed term}.\index{indexed term} (You see this in the source file only.) % Let us pretend this page explains $\mathrm{Ext}^i_B(M,N)$. \glossary{$\mathrm{Ext}^i_B(M,N)$&Ext group in the category $\mathcal C_B$} @@ -60,13 +63,15 @@ Of course the index file {\it filename}.\texttt{ind} may be edited to remedy such flaws. Such editing will actually be the recommended way to achieve more complicated effects like the page ranges on page \pageref{range}, which also use several fonts in their page numbers. +That is actually bad style, but this file just illustrates features. Traditionally page ranges and fonts for page numbers could be done with the encapsulating construction of makeindex, but that construction is broken by our package. (The encapsulating construction uses the encap character $|$ in the argument of \verb|\index|.) -We have restored it to some extent, sufficient for common practice, + +We have restored encapsulating to some extent, sufficient for common practice, but our rules are more naive than those of makeindex. See the file \verb|robustsample.tex| for details. @@ -112,9 +117,9 @@ because of the roman page numbers in the beginning. % 2. One of the brackets "(" or ")", or one of those brackets followed by % a sequence as in type 1. % Any "(" must be matched by its ")", and this ")" must occur in a later -% \index command that shares the part before the "|". No intervening \index -% command may have this same part before the "|". -% So here we deviate from makeindex. +% \index command that shares the part before the "|". +% If an intervening \index command has this same part before the "|", +% then it does not appear in the index. % % Makeindex also attaches special meanings to @, !, ". These meanings stay, % but " can no longer be used to escape |. One must simply replace | with @@ -126,10 +131,17 @@ because of the roman page numbers in the beginning. % The name "risky" of the subentry is used for sorting by makeindex, and will % not be printed. % +% \index{page range|(textbf}% -% This belongs to the entry "page range". The previous +% This belongs to the entry "page range" in the index. The previous % \index command started a subentry of this entry. % +% The next three index commands do not contribute, as they occur +% before the page range is ended. +\index{page range!risky@this $\vert$is$\vert$ complicated|textbf}% +\index{page range!risky@this $\vert$is$\vert$ complicated}% +\index{page range!risky@this $\vert$is$\vert$ complicated|textbf}% +% \index{simpler!page range|(}% \index{simplest page range|(}% % encapsulating to be continued below @@ -142,7 +154,7 @@ because of the roman page numbers in the beginning. \usepackage{makeidx} \usepackage{robustindex} ... -...\index{Wilberd}} % on page i +...\author{Wilberd van der Kallen\index{Wilberd}} ... \makeindex % obligatory with robustindex @@ -158,26 +170,25 @@ because of the roman page numbers in the beginning. \index{alpha!see also gamma\gobblepageref} % on page 5 ... % For special effects you could simply edit filename.ind -% If you insist on using encapsulation,... -\index{...|...}... % on page 5 +% We illustrate our poor man's encapsulation. +\index{...|...}... % on page 6 \index{...|...}... % on page 7 \index{...|...}... % on page 9 .... -\indexincontents % always put this before the index. +\indexincontents % before the index. \printindex \end{document} \end{verbatim} % continuation of encapsulating -% +% We close a page range, but now the page number is in italic. +% This is bad style, but we are just illustrating a feature. \index{page range!risky@this $\vert$is$\vert$ complicated|)textit} % encapsulating to be continued below \chapter{Purpose of \texttt{robustindex.sty}}\label{purpose} -The package \texttt{robustindex} tries to remedy two problems. -\begin{itemize} -\item Amazingly often a third party changes the page numbers without rerunning +Amazingly often a third party changes the page numbers without rerunning makeindex. It is much nicer to have an index that adapts itself to all changes that do not involve \verb|\index{|\textit{entry}\verb|}| commands. @@ -191,11 +202,6 @@ command, or after changing the order of \verb|\index{|\textit{entry}\verb|}| commands, does one have to run makeindex. But then it is important that you do run makeindex, even when no warning is issued. The robustness has its limits. -\item The \texttt{theindex} environment lacks a destination for hyperlinks. -That is a nuisance when one wants add the index to -the bookmarks or to the table of contents in a pdf file: When one clicks on the -link that displays the word Index, one wants to end up in the index. -\end{itemize} % continuation of encapsulating % @@ -203,7 +209,7 @@ link that displays the word Index, one wants to end up in the index. \index{page range!risky@this $\vert$is$\vert$ complicated|texttt} % \index{page range!with risky label\label{range}} -% +% This label actually works and was used above in a \pageref{range} command. % \index{simpler!page range|)}% \index{simplest page range|)}% @@ -255,6 +261,14 @@ C_B$} \end{theglossary} -\indexincontents % always put this before the index. +% If you want the index in the table of contents, you may do +% +% \clearpage +% \phantomsection +% \addcontentsline{toc}{chapter}{\indexname} +% +% We have a command for this: + +\indexincontents % before \printindex \printindex \end{document} diff --git a/Master/texmf-dist/doc/latex/robustindex/stind.html b/Master/texmf-dist/doc/latex/robustindex/stind.html new file mode 100644 index 00000000000..ca9ab179a01 --- /dev/null +++ b/Master/texmf-dist/doc/latex/robustindex/stind.html @@ -0,0 +1,46 @@ +<HTML> +<HEAD> +<TITLE>Robust index package for LaTeX</TITLE> +</HEAD> + +<BODY> +<H1><A NAME="top">Robust index package for LaTeX</A></H1> + + +<H2>Page numbers changed by third party without rerunning makeindex</H2> +Amazingly often the page numbers in index entries are wrong because +a third party has changed the numbering of pages +without rerunning makeindex. (Yes, it happened also to my 1993 book.) +<P>It is much nicer to have an index that adapts itself to all +changes but the adding/deleting/rearranging of \index commands. +<P>Our package +<A HREF="robustindex.sty">robustindex.sty</A> +achieves this with the \pageref mechanism. +<P> +Here is our <A HREF="robustmanual.pdf">Manual for the robustindex package</A>. +<P>Just try what happens if you put +\usepackage{robustindex} in your preamble. Do read your TeX log file. + +<P>The sample file <A HREF="robustsample.tex">robustsample.tex</A> +illustrates more than you ever need. +It also requires the package + <A HREF="robustglossary.sty">robustglossary.sty</A>. + +<P>After +<DL> +<DD>pdflatex <A HREF="robustsample.tex">robustsample.tex</A> +<DD>makeindex robustsample +<DD>pdflatex robustsample.tex +<DD>pdflatex robustsample.tex +</DL> +you should have something like <A HREF="robustsample.pdf">this PDF file</A>. + + +<BR> + +<BR><BR><BR> +<A HREF="https://www.staff.science.uu.nl/~kalle101/">Wilberd van der Kallen</A> + + +</BODY> +</HTML> |