summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/imakeidx
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2013-03-28 23:10:57 +0000
committerKarl Berry <karl@freefriends.org>2013-03-28 23:10:57 +0000
commit00633214cca4f6c180bfb4707bcd752e0258b472 (patch)
treebbbaf6a2e9d34cde2ce39aaccc8d065584c85ad7 /Master/texmf-dist/source/latex/imakeidx
parent5850fed93904f9c801051e5315f42df42b066580 (diff)
imakeidx (28mar13)
git-svn-id: svn://tug.org/texlive/trunk@29542 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source/latex/imakeidx')
-rw-r--r--Master/texmf-dist/source/latex/imakeidx/imakeidx.dtx110
1 files changed, 106 insertions, 4 deletions
diff --git a/Master/texmf-dist/source/latex/imakeidx/imakeidx.dtx b/Master/texmf-dist/source/latex/imakeidx/imakeidx.dtx
index bcac4894408..12320d3a96d 100644
--- a/Master/texmf-dist/source/latex/imakeidx/imakeidx.dtx
+++ b/Master/texmf-dist/source/latex/imakeidx/imakeidx.dtx
@@ -43,7 +43,7 @@ and the derived files imakeidx.sty and imakeidx.pdf.
%<package>\NeedsTeXFormat{LaTeX2e}[2005/12/01]
%<package>\ProvidesPackage{imakeidx}%
%<*package>
- [2012/10/22 v1.2e Package for typesetting indices in a synchronous mode]
+ [2013/03/26 v1.3 Package for typesetting indices in a synchronous mode]
%</package>
%<*driver>
\documentclass{ltxdoc}
@@ -53,6 +53,7 @@ and the derived files imakeidx.sty and imakeidx.pdf.
\def\Kvalue#1{\textsf{\textsl{#1}}}
\def\pack#1{\textsf{#1}}
\def\class#1{\textsf{\itshape#1}}
+\def\opz#1{\texttt{#1}}
\usepackage{multicol}
\usepackage[T1]{fontenc}
\usepackage[utf8]{inputenc}
@@ -347,7 +348,8 @@ and the derived files imakeidx.sty and imakeidx.pdf.
% as |\vspace{36pt}| (default is \cs{bigskip}), controlling the
% spacing between the prologue and the index proper. The command
% affects only the next index produced by \cs{printindex} and is best
-% placed just before this command.
+% placed just before this command. Please read ahead for further
+% information on the use of tho command.
% \Item[printindex] with the syntax:\\*[1ex]
% \cs{printindex}\oarg{name}\\[1ex]
% is used to typeset the particular index named \meta{name}; if no
@@ -355,7 +357,7 @@ and the derived files imakeidx.sty and imakeidx.pdf.
% \cs{jobname.ind} is typeset. Actually this command activates all
% the mechanism of closing the output to the raw index file, shelling
% out, possibly calling the \prog{splitindex} script in order to
-% divide the single raw file generated by \progpdflatex{} into
+% divide the single raw file generated by the typesetting engine into
% distinct raw files according to the default or specified
% \meta{name}s for each index, calling the sorting and
% formatting program on each of these split raw files (unless
@@ -396,7 +398,7 @@ and the derived files imakeidx.sty and imakeidx.pdf.
% When the \texttt{original} option is set, maybe implicitly because
% of \texttt{twocolumn}, \cs{indexsetup} and the keys
% \Kvalue{columns}, \Kvalue{columnsep} and \Kvalue{columnseprule} for
-% \cs{makeindex} have no effect.
+% \cs{makeindex} have no effect. Please read more on this matter further~on.
%
% \section{If something goes wrong}\label{sec:wrong}
% Since \pack{imakeidx} relies on good cooperation between package
@@ -548,6 +550,106 @@ and the derived files imakeidx.sty and imakeidx.pdf.
% documents with multiple indices.
%
% \subsection{Conflicts}
+%
+% \subsection{Two columm typesetting and index prologue}
+% As it has been already mentioned, it is possible to use the command
+% |\indexprologue| to write some text before the index proper gets typeset;
+% an optional space may be used in place of the default one-line spacing
+% between the index title, the prologue and the index body.
+%
+% This facility relies on a particular feature of the |multicols|
+% environment, that \pack{imakeidx} uses to instruct the typesetting
+% program to typeset the index with a specified number of balanced columns.
+% The choice of |multicols| has been made because it balances the
+% columns in the last page; the declaration |\twocolum| does not
+% perform the same way, and, if used, it makes |\printindex| typeset
+% the index in two-column mode with an unbalanced last column.
+%
+% In the previous sections it has been clearly stated that any
+% configuration of the way \pack{imakeidx} typesets the indices
+% is bypassed if the option \opz{original} has been specified
+% either explicitly or implicitly. It is implicitly specified
+% if the option \opz{twocolumn} is specified in the class
+% declaration statement.
+% Why? Because if two column typesetting is desired for the whole
+% document, it is not clear if the index has to be typeset in one
+% column within each column of the document, or if it should be
+% typeset in two column mode after a |\onecolumn| command is being
+% issued; the results are not the same: with the former method the
+% columns remain unbalanced, while the latter has balanced columns.
+% Furthermore the |\onecolum| command forces a page break; without
+% the |\onecolumn| command if the index is treated as a chapter,
+% there is a page break, while if it is configured to be typeset
+% as a section there is no forced page brake. With this plethora
+% of combinations we decided to avoid any configuration of the
+% index typesetting and left the decision to the user. This
+% requires the user to practice some ingenuity in order to obtain
+% what he expects.
+%
+% First of all the user shall not specify the \opz{twocolumn}
+% option to the class. Secondly the user asks for the use of
+% \pack{imakeidx} and sets up the single or multiple |\makindex|
+% commands. thirdly he loads all other packages required for his
+% document; possibly he uses also \pack{geometry} in order to
+% specify a specific page layout. He shall specify the |\twocolumn|
+% declaration after the above has been completed, in any case
+% after the \pack{imakeidx} package has been loaded and the single
+% or multiple |\makeindex| commands are configured.
+%
+% A good example might be this one:
+%\begin{verbatim}
+%\documentclass[a4paper,11pt]{book}
+%\usepackage{imakeidx}
+%\indexsetup{level=\section*,toclevel=section,noclearpage}
+%\makeindex[title=Index of places,columns=1]
+%\twocolumn
+%\usepackage[T1]{fontenc}
+%\usepackage{lmodern}
+%\usepackage[italian,english]{babel}
+%\usepackage[utf8]{inputenc}
+%\usepackage[a4paper,margin={1in,1in},binding=3mm]{geometry}
+%\usepackage[english]{varioref}
+%\usepackage[hang]{caption}
+%\begin{document}
+%...
+%\indexprologue{This index lists all the residences where Lady Esther
+%lived during the time span described in the book.}
+%\printindex
+%\end{document}
+%\end{verbatim}
+% In this way the index is typeset as a ``section'', not as a
+% ``chapter'', in one column mode within the two column document
+% style; the indicated prologue is typeset between the index
+% title ``Index of places'' and the start of the index proper.
+%
+% On the opposite the following code:
+%\begin{verbatim}
+%\documentclass[a4paper,11pt]{book}
+%\usepackage{imakeidx}
+%\makeindex[title=Index of places,columns=2]
+%\twocolumn
+%\usepackage[T1]{fontenc}
+%\usepackage{lmodern}
+%\usepackage[italian,english]{babel}
+%\usepackage[utf8]{inputenc}
+%\usepackage[a4paper,margin={1in,1in},binding=3mm]{geometry}
+%\usepackage[english]{varioref}
+%\usepackage[hang]{caption}
+%\begin{document}
+%...
+%\onecolumn
+%\indexprologue{This index lists all the residences where Lady Esther
+%lived during the time span described in the book.}
+%\printindex
+%\end{document}
+%\end{verbatim}
+% produces an index typeset as a ``chapter'', starting on a new page;
+% it is typeset in two balanced columns. The prologue is typeset where it should.
+% The ingenious reader can experiment mixing the various settings
+% used in these two examples in order to find out what benefits or
+% disadvantages one can obtain with settings that are not physically
+% impossible, but that may be aesthetically conflicting with one another.
+
% \subsubsection{Class \class{memoir}}
%
% The first public version of this package was not compatible with the