From 2c82ae3369984eafc23b0efad01e947b2c9b8f33 Mon Sep 17 00:00:00 2001
From: Karl Berry <karl@freefriends.org>
Date: Mon, 25 Jan 2010 00:22:04 +0000
Subject: idxlayout update (24jan10)

git-svn-id: svn://tug.org/texlive/trunk@16812 c570f23f-e606-0410-a88d-b1316a301751
---
 .../source/latex/idxlayout/idxlayout.dtx           | 86 ++++++++++++++--------
 1 file changed, 57 insertions(+), 29 deletions(-)

(limited to 'Master/texmf-dist/source/latex/idxlayout/idxlayout.dtx')

diff --git a/Master/texmf-dist/source/latex/idxlayout/idxlayout.dtx b/Master/texmf-dist/source/latex/idxlayout/idxlayout.dtx
index 47522bd4970..3e2ea493016 100644
--- a/Master/texmf-dist/source/latex/idxlayout/idxlayout.dtx
+++ b/Master/texmf-dist/source/latex/idxlayout/idxlayout.dtx
@@ -61,7 +61,7 @@
 %
 % \fi
 %
-% \CheckSum{344}
+% \CheckSum{354}
 %
 % \CharacterTable
 %  {Upper-case    \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
@@ -117,13 +117,13 @@
 % Besides being cumbersome for unversed \LaTeX\ users,\footnote{In the
 % words of user InsideMan on \textsf{mrunix.de}, November 27, 2009
 % (authors translation): ``I didn't believe this to be so laborious. I'd
-% rather have guessed there is a package option to cater for it.''} this
-% approach is prone to break index-related options the document class
-% might provide (e.\,g. for including the index in the table of
-% contents). To address this, the \ila/ package offers a key--value
-% interface to configure index layout parameters while emulating and
-% extending the relevant functionality of the standard, \KOMA/- and
-% \mem/ classes.
+% rather have guessed there is a package option to cater for it.''} the
+% do-it-yourself approach is prone to break index-related options the
+% document class might provide (e.\,g. for including the index in the
+% table of contents). To address this, the \ila/ package offers a
+% key--value interface to configure index layout parameters while
+% emulating and extending the relevant functionality of the standard,
+% \KOMA/- and \mem/ classes.
 %
 % Note that \ila/ stays on the \LaTeX\ side of things. If you want to
 % add letter headings to each index group or to change the delimiter
@@ -184,9 +184,9 @@
 % \item Columns will be balanced on the last index page.
 %
 % \item If you are using a class that lacks the |\chapter| command (or
-% \mem/ with the option \textsf{article}), the index will behave like a
-% normal |\section*|, i.\,e. it will not automatically start a new
-% page.\footnote{However, if you typeset your document in
+% \mem/ with the option \textsf{article}), the index will basically
+% behave like a normal |\section*|, i.\,e. it will not automatically
+% start a new page.\footnote{However, if you typeset your document in
 % \textsf{twocolumn} mode, \ila/ will temporarily switch to
 % \textsf{onecolumn}, causing a page break in the process.} The first
 % index page will also not use a special pagestyle like \textsf{plain}
@@ -221,6 +221,13 @@
 % index of first lines in a book of poetry'' \cite[p.
 % \textsc{xxix}]{Wil09}.
 %
+% \changes{v0.4a}{2010/01/24}{New option \textsf{unbalanced}}
+%
+% \item[unbalanced]\SpecialOptIndex{unbalanced} A boolean option that,
+% if enabled, switches off the balancing of columns on the last index
+% page. The default value is \textsf{false}. You may simply specify
+% \textsf{unbalanced}, which is equivalent to \textsf{unbalanced=true}.
+%
 % \item[columnsep]\SpecialOptIndex{columnsep} The space between index
 % columns. The default value is 35\,pt. As this is required for
 % compatibility rather than suggested by typographic considerations, you
@@ -259,10 +266,12 @@
 %
 % \item[indentunit]\SpecialOptIndex{indentunit} A length that serves as
 % a building block for other indentation lengths. The default value is
-% 20\,pt. The default values of the options \textsf{hangindent},
-% \textsf{subindent} and \textsf{subsubindent} will be set in accordance
-% with the chosen values of \textsf{itemlayout} and \textsf{indentunit}
-% (see table~\vref{tab:indents}).
+% 20\,pt. You may want to match the value of \textsf{indentunit} with
+% that of the \TeX\ length |\parindent|. The default values of the
+% options \textsf{hangindent}, \textsf{subindent} and
+% \textsf{subsubindent} will be set in accordance with the chosen values
+% of \textsf{itemlayout} and \textsf{indentunit} (see
+% table~\vref{tab:indents}).
 %
 % \item[hangindent]\SpecialOptIndex{hangindent} Use this option to
 % override the default value of \textsf{hangindent}.
@@ -472,7 +481,7 @@
 % Announce the name and version of the package, which requires \LaTeXe.
 %    \begin{macrocode}
 \NeedsTeXFormat{LaTeX2e}
-\ProvidesPackage{idxlayout}[2010/01/10 v0.4 Configurable index layout]
+\ProvidesPackage{idxlayout}[2010/01/24 v0.4a Configurable index layout]
 %    \end{macrocode}
 % Besides \textsf{multicol}, we require the packages \textsf{kvoptions}
 % (to conveniently specify options as key--value pairs) and
@@ -562,10 +571,16 @@
 %    \end{macrocode}
 % \end{macro}
 % \end{macro}
+% \textsf{kvoptions} is used to define the boolean option
+% \textsf{unbalanced} which is responsible for switching off the
+% \textsf{multicol} balancing output routine.
+%    \begin{macrocode}
+\DeclareBoolOption{unbalanced}
+%    \end{macrocode}
 % \begin{macro}{\ila@indentunit}
-% The key \textsf{indentunit} is also defined and set using
-% \textsf{keyval} commands so that its associated length can be used to
-% set other lengths.
+% The key \textsf{indentunit} is defined and set using \textsf{keyval}
+% commands so that its associated length can be used to set other
+% lengths.
 %    \begin{macrocode}
 \newlength{\ila@indentunit}
 \define@key{ila}{indentunit}{\setlength{\ila@indentunit}{#1}}
@@ -575,7 +590,7 @@
 % \begin{macro}{\ila@hangindent}
 % \begin{macro}{\ila@subindent}
 % \begin{macro}{\ila@subsubindent}
-% We finally use \textsf{kvoptions} to define the keys
+% We use \textsf{kvoptions} again to define the keys
 % \textsf{hangindent}, \textsf{subindent} and \textsf{subsubindent}.
 % Setting their default values is deferred to the definition of the
 % functions of the ``radio button'' key \textsf{itemlayout}.
@@ -899,7 +914,9 @@
 % |\multicolsep| is set to 0\,pt, again in order to avoid excessive
 % vertical space after the index heading. Also, the \mem/ lengths
 % |\indexcolsep| and |\indexrule| (now responsive to the \ila/ options
-% \textsf{columnsep} and \textsf{rule}) are put in charge.
+% \textsf{columnsep} and \textsf{rule}) are put in charge. Note that in
+% order to be effective, this has to be done before opening a
+% |multicols| environment.
 %    \begin{macrocode}
   \setlength{\multicolsep}{\z@}%
   \setlength{\columnsep}{\indexcolsep}%
@@ -908,15 +925,21 @@
 % If a single-column index is requested, we simply execute
 % |\ila@prologue|, switch to |\indexfont| and typeset a possible
 % prenote. In case of two or more columns, we do all this inside the
-% first optional argument of a properly chosen |multicols| environment
-% and specify the value of \textsf{minspace} as its second optional
-% argument.
+% first optional argument of a properly chosen |multicols| (or, if the
+% boolean option \textsf{unbalanced} is enabled, |multicols*|)
+% environment and specify the value of \textsf{minspace} as its second
+% optional argument.
 %    \begin{macrocode}
   \ifnumcomp{\theidxcols}{<}{\tw@}{%
     \ila@prologue\indexfont\ila@prenote
   }{%
-    \begin{multicols}{\theidxcols}%
-        [\ila@prologue\indexfont\ila@prenote][\ila@minspace]%
+    \ifbool{ila@unbalanced}{%
+      \begin{multicols*}{\theidxcols}%
+          [\ila@prologue\indexfont\ila@prenote][\ila@minspace]%
+    }{%
+      \begin{multicols}{\theidxcols}%
+          [\ila@prologue\indexfont\ila@prenote][\ila@minspace]%
+    }%
   }%
 %    \end{macrocode}
 % We set |\parskip| to 0\,pt plus 0.3\,pt (exactly as in the standard
@@ -927,13 +950,18 @@
   \indexjustific
   \let\item\@idxitem
 %    \end{macrocode}
-% At the end of |theindex|, we close a possible |multicols| environment
-% and switch back to \textsf{twocolumn} mode, if necessary.
+% At the end of |theindex|, we close a possible |multicols| (or
+% |multicols*|) environment and switch back to \textsf{twocolumn} mode,
+% if necessary.
 %    \begin{macrocode}
 }{%
   \ifnumcomp{\theidxcols}{<}{\tw@}{%
   }{%
-    \end{multicols}%
+    \ifbool{ila@unbalanced}{%
+      \end{multicols*}%
+    }{%
+      \end{multicols}%
+    }%
   }%
   \ifbool{@restonecol}{%
   }{%
-- 
cgit v1.2.3

