path: root/macros/latex/contrib/eqlist/eqlist.dtx

% \def\fileversion{2.1}\def\filedate{2002/08/15}\def\docdate{2013/11/26}
%\iffalse These lines are necessary for the doc and docstrip utilities
%<*metainfo>

% With this package you can write lists with equal indentation.
% This package requires the eqparbox package.
%
% Author:
%
% M. V\"ath      martin@mvath.de
%
% The package may be distributed and/or modified under the conditions of
% the LaTeX Project Public License (version 1.3c or later).

%\fi
%
% \def\basename{eqlist}
%
%% \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
%%   Lower-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
%%   Digits        \0\1\2\3\4\5\6\7\8\9
%%   Exclamation   \!     Double quote  \"     Hash (number) \#
%%   Dollar        \$     Percent       \%     Ampersand     \&
%%   Acute accent  \'     Left paren    \(     Right paren   \)
%%   Asterisk      \*     Plus          \+     Comma         \,
%%   Minus         \-     Point         \.     Solidus       \/
%%   Colon         \:     Semicolon     \;     Less than     \<
%%   Equals        \=     Greater than  \>     Question mark \?
%%   Commercial at \@     Left bracket  \[     Backslash     \\
%%   Right bracket \]     Circumflex    \^     Underscore    \_
%%   Grave accent  \`     Left brace    \{     Vertical bar  \|
%%   Right brace   \}     Tilde         \~}
%
% \CheckSum{180}
%
% \newcommand{\cmdcite}[1]{\texttt{\textbackslash#1}}
% \newcommand{\envcite}[1]{\texttt{\{#1\}}}
% \newcommand{\optcite}[1]{\texttt{#1}}
% \newcommand{\filecite}[1]{\texttt{#1}}
% \newcommand{\bracemeta}[1]{\texttt{\{}\meta{#1}\texttt{\}}}
%
% \iffalse
%   \RecordChanges
% \fi
% \def\ChangesTab{}\let\orichanges\changes
% \def\changes#1#2#3{\orichanges{#1}{#2}{#3}
%   \expandafter\def\expandafter\ChangesTab\expandafter{\ChangesTab
%   \item[v#1 {\mdseries(\emph{#2})}] {#3.}}}
%
% \changes{2.1}{2013/11/26}{Update email, add license. Date/version remains the
%   same since only commments and documentation are modified}
% \changes{2.1}{2002/08/18}{Added \cmdcite{longitem} and the related
%   \cmdcite{eqlistauto} mechanism. The latter was suggested by
%   Rolf Niepraschk \texttt{Rolf.Niepraschk@ptb.de}. Changed default
%   of \cmdcite{eqlistlabel} and gave some comments on spaces at the end of
%   labels in the documentation. Documented special usage of
%   \cmdcite{makelabel}}
% \changes{1.2}{2001/08/17}{Added the \envcite{Eqlist} and \envcite{Eqlist*}
%   environments}
% \changes{1.1}{2001/08/16}{First release}
%
% \iffalse
%</metainfo>
%
% Everything between the following lines %<*driver> and %</driver> goes
% into the file eqlist.tex. Also, this is the only code executed, if
% this file here is run through latex.
%
%<*driver>
\documentclass{ltxdoc}
\OnlyDescription%% Comment this out, or
%%\AlsoImplementation%% uncomment this line, if you want to see the source.

%% If you want an index, uncomment one of the following lines.
%% After running latex a first time, you have to use
%%      makeindex -s gind.ist eqlist
%% Then run latex again.
%%\CodelineIndex% comment this out if you want an index referring to codelines
%%\PageIndex% comment this out if you want an index referring to pages
%%\OldMakeindex% uncomment this line, if your MakeIndex is pre-v2.9

\setlength\hfuzz{15pt}
\hbadness=7000
\begin{document}
\DocInput{eqlist.dtx}
\end{document}
%</driver>
%<*metainfo>
% \fi
%
% \MakeShortVerb{"}
% \def\itemcmd#1{\item[\mdseries\texttt{\textbackslash#1}]}
%
% \title{The \texttt{eqlist} package\thanks
%   {This package has version number \fileversion{}, last revised \filedate.
%   The package may be distributed and/or modified under the conditions of the
%   LaTeX Project Public License, either version 1.3c of this license or (at
%   your option) any later version. The latest version of this license is in
%   \texttt{http://www.latex-project.org/lppl.txt}, and version 1.3c or later
%   is part of all distributions of LaTeX version 2005/12/01 or later.}}
% \author{Martin V\"ath\\{\texttt{martin@mvath.de}}}
% \date{\docdate}
% \maketitle

% \begin{abstract}
% With this package you can write lists with equal indentation.
% This package requires the \filecite{eqparbox} package.
% \end{abstract}
%
% You may copy this package freely, as long as you distribute only unmodified
% and complete versions.
%
% \iffalse\tableofcontents\par\pagebreak\par\fi
%
% \section{Changes}
%
% \begin{description}
%    \ChangesTab
% \end{description}
%
% \section{Description}
%
% This package provides a list environment which sets a description-like list
% but with the difference that the indentation corresponds to the longest item
% of the list. The usage is simply
% \begin{quote}
% \DescribeEnv{eqlist}"\begin{eqlist}["\meta{optional modifications}"]"\\
% "\item[First item] Text"\\
% "\item[Second item] Text"\\
% "\longitem[A special very long item] Text"\\
% \dots\\
% "\end{eqlist}"
% \end{quote}
% and there is also the environment \DescribeEnv{eqlist*}\envcite{eqlist*}
% which is similar but has slightly different defaults
% (which make the list appear more compact).
% There is also the alternative call
% \begin{quote}
% \DescribeEnv{Eqlist}"\begin{Eqlist}["\meta{optional modifications}"]"\relax
%\bracemeta{tag}\\
% "\item[First item] Text"\\
% "\item[Second item] Text"\\
% "\longitem[A special very long item] Text"\\
% \dots\\
% "\end{eqlist}"
% \end{quote}
% and a corresponding \DescribeEnv{Eqlist*}\envcite{Eqlist*} environment.\par
%
% All texts within the list are indented by the length of the largest label
% (i.e.\ "\item" entry) plus "\labelsep". For the "Eqlist" or "Eqlist*"
% environment, all lists with the same \meta{tag} are treated equally in the
% sense that the indentation of these lists is determined by the largest
% "\item" of all these lists. In this case, you may also use the \meta{tag}
% for the \filecite{eqparbox} package to read or modify the length of the
% largest "\item" (which is internally treated as a "\eqparbox").\par
%
% \DescribeMacro{\longitem}"\longitem" is like "\item", but the corresponding
% label is excluded from the calculation of the longest "\item".
% The intention of "\longitem" is to allow exceptionally long labels to
% occur without forcing a corresponding extreme indentation
% of the whole list. If you want \LaTeX\ to decide automatically
% whether "\longitem" or "\item" should be used, you can use the
% "\eqlistauto" mechanism which is described later.
%
% The \meta{optional modifications} are any commands which are used to
% initialize the list: You can modify here essentially the same variables as
% for any \LaTeXe\ list. If this argument is not given, the default
% initializations \DescribeMacro{\eqlistinit}"\eqlistinit" respectively
% \DescribeMacro{\eqliststarinit}"\eqliststarinit" (for \envcite{eqlist*}
% and \envcite{Eqlist*}) are used:
% You can just modify these definitions to change the defaults.
% If you have given the argument \meta{optional modifications} and additionally
% want to use the defaults, you have to include the command "\eqlistinit"
% respectively "\eqliststarinit" into the argument
% \meta{optional modifications} (see the examples below).\par
%
% The macros "\eqlistinit" and "\eqliststarinit" both call
% \DescribeMacro{\eqlistinitpar}"\eqlistinitpar" which sets the values for
% "\parindent" and "\parskip" to the values outside the list
% (this is not standard in \LaTeXe, but I prefer this style; if you do not like
% this, use "\let\eqlistinit\relax").
%
% Currently, this is all which is done by "\eqlistinit"; for
% "\eqliststarinit" additionally the values of
% \DescribeMacro{\topsep}"\topsep" and \DescribeMacro{\itemsep}"\itemsep" are
% set to $0$. Note that currently \DescribeMacro{\partopsep}"\partopsep" is
% not changed from the \LaTeXe\ default. Note that the latter is by default
% positive which means that if you are in vertical mode before the list
% (e.g.\ if you have a "\par" in front of the list), you get slightly more
% space above the list.\par
%
% Before \meta{optional modifications} (or "\eqlistinit" respectively
% "\eqliststarinit") are expanded, the length of the largest label is already
% stored in
% \DescribeMacro{\labelwidth}"\labelwidth" and
% \DescribeMacro{\leftmargin}"\leftmargin". After your modifications,
% \DescribeMacro{\labelsep}"\labelsep" is added to the actual value of
% "\leftmargin".
%
% As usual, the layout of "\item"s is done by the command
% \DescribeMacro{\makelabel}"\makelabel". If you want, you can change the
% default initialization of this command in the \meta{optional modifications}
% argument. However, it is \emph{not} admissible to redefine this macro
% within the list.
% If you really want to change the layout of "\item"s in the middle of a list,
% you can initialize "\makelabel" to expand to another command whose
% definition you can change within the list instead of "\makelabel"
% (an example will be given later).
% The default value of \DescribeMacro{\makelabel}"\makelabel" is the
% content of \DescribeMacro{\eqlistlabel}"\eqlistlabel" which in turn is
% by default defined with
%    \begin{verbatim}
%       \def\eqlistlabel#1{#1}\end{verbatim}
%
% In version 1.1 and 1.2 of this package, the default was different:
% A space was added at the end. This has been changed, because by a bug
% (or feature?) in "\eqparbox" spaces at the end of an "\item" are
% ignored anyway.
% If you want to force a space at the end which will not be ignored,
% you have to hide it in a box:
%    \begin{verbatim}
%       \def\eqlistlabel#1{\mbox{#1 }}\end{verbatim}
% will force a space at the end of every "\item".\bigskip
%
% There is a special mechanism provided which will automatically decide for
% an "\item" depending on the length of its label whether it is treated as
% normal or whether it should be treated like a "\longitem": If you want to
% use this mechanism, you only have to insert the command
% \begin{quote}
% \DescribeMacro{\eqlistauto}"\eqlistauto{"\meta{maximal length}"}"
% \end{quote}
% either inside the \meta{optional modifications} argument or within the list.
% Here, \meta{maximal length} must be in a format which can be used within
% \TeX's internal "\ifdim" command. It describes the maximal length of the
% label such that the corresponding "\item" will be treated as usual---for
% longer labels the corresponding "\item" will be treated as a "\longitem".
% If you want to switch off the "\eqlistauto"-mechanism again, you can use
% the command
% \begin{quote}
% \DescribeMacro{\eqlistnoauto}"\eqlistnoauto"
% \end{quote}
% The commands "\eqlistauto" and "\eqlistnoauto" need not occur in matching
% pairs, and they can also be used several times within the same list:
% Only the latest of the corresponding commands takes effect for a
% corresponding "\item".
%
% Unfortunately, the "\eqlistauto" mechanism has a disadvantage: As long as
% it is in effect, the corresponding "\makelabel"s for the "\item"s are
% always executed twice (once to calculate the length and once for the actual
% typesetting). This can cause problems if e.g.\ counters in "\item"s are
% increased.
%
% The "\eqlistauto" mechanism only effects the "\item" command, not
% "\longitem": Even if the "\eqlistauto" mechanism is active, you can use
% "\longitem" which will have its original meaning (independent of the
% length of the label). This means in particular that the "\makelabel" is
% executed only once by "\longitem", no matter whether the "\eqlistauto"
% mechanism is active or not.
%
% \section{Examples}
% \begin{verbatim}
%   \begin{eqlist}[\eqliststarinit\def\makelabel#1{\bfseries#1:}\labelsep1em]
%   \item[Short label] Descriptive text
%   \item[A longer label] Descriptive text
%   \longitem[An exceptionally long label] Descriptive text
%   \item[Short again] Descriptive text
%   \end{eqlist}\end{verbatim}
% will produce an output like\medskip\newline
% \begin{tabular}{@{}l@{}l}
% \bfseries Short label:\hspace{1em}\null&Descriptive text\\
% \bfseries A longer label:\hspace{1em}\null&Descriptive text\\
% \multicolumn{2}{@{}l}{{\bfseries An exceptionally
% long label:\hspace{1em}}\null Descriptive text}\\
% \bfseries Short again:\hspace{1em}\null&Descriptive text
% \end{tabular}\bigskip\par
%
% The same output can be obtained using the "\eqlistauto" mechanism
% \begin{verbatim}
%   \begin{eqlist}[\eqliststarinit
%      \def\makelabel#1{\bfseries#1:}\labelsep1em\eqlistauto{3cm}]
%   \item[Short label] Descriptive text
%   \item[A longer label] Descriptive text
%   \item[An exceptionally long label] Descriptive text
%   \item[Short again] Descriptive text
%   \end{eqlist}\end{verbatim}
% or by using the "\eqlistauto" mechanism only locally:
% \begin{verbatim}
%   \begin{eqlist}[\eqliststarinit\def\makelabel#1{\bfseries#1:}\labelsep1em]
%   \item[Short label] Descriptive text
%   \item[A longer label] Descriptive text
%   \eqlistauto{0pt}
%   \item[An exceptionally long label] Descriptive text
%   \eqlistnoauto
%   \item[Short again] Descriptive text
%   \end{eqlist}\end{verbatim}
%
% The next example demonstrates how one can change the layout of labels
% within the list. Recall that it is forbidden to redefine "\makelabel".
% \begin{verbatim}
%   \begin{eqlist}[\eqliststarinit
%     \def\mylabel#1{\bfseries#1:}\def\makelabel{\mylabel}\labelsep1em]
%   \item[First label] Descriptive text
%   \item[Second label] Descriptive text
%   \def\mylabel#1{\slshape#1:}
%   \item[First new-style label] Descriptive text
%   \longitem[Second new-style label which is long] Descriptive text
%   \end{eqlist}\end{verbatim}
% The above example will produce an output as follows.\bigskip\newline
% \begin{tabular}{@{}l@{}l}
% \bfseries First label:\hspace{1em}\null&Descriptive text\\
% \bfseries Second label:\hspace{1em}\null&Descriptive text\\
% \slshape First new-style label:\hspace{1em}\null&Descriptive text\\
% \multicolumn{2}{@{}l}{{\slshape Second new-style label
% which is long:\hspace{1em}}\null Descriptive text}
% \end{tabular}
%
% \iffalse
%</metainfo>
% \fi
% \iffalse--------------------------------------------------------------\fi
% \StopEventually{\PrintChanges}
%           \section{Implementation}
%
% \newcommand{\nocomment}{}
% \setcounter{CodelineNo}{0}
% \iffalse--------------------------------------------------------------
%
%
%<*eqlist>
% \fi
%    \begin{macrocode}

\typeout{eqlist.sty by M. Vaeth: Revision 2.1}
\NeedsTeXFormat{LaTeX2e}
\ProvidesPackage{eqlist}[2002/08/15 v2.1]

\RequirePackage{eqparbox}

%    \end{macrocode}
% \begin{macro}{eqlist}\nocomment
%    \begin{macrocode}
\newenvironment{eqlist}[1][\eqlistinit]{\eql@start{#1}}{\eql@end}
%    \end{macrocode}
% \end{macro}
% \begin{macro}{eqlist*}\nocomment
%    \begin{macrocode}
\newenvironment{eqlist*}[1][\eqliststarinit]{\eql@start{#1}}{\eql@end}
%    \end{macrocode}
% \end{macro}
% \begin{macro}{Eqlist}\nocomment
%    \begin{macrocode}
\newenvironment{Eqlist}[2][\eqlistinit]{\eql@startp{#1}{#2}}{\eql@end}
%    \end{macrocode}
% \end{macro}
% \begin{macro}{Eqlist*}\nocomment
%    \begin{macrocode}
\newenvironment{Eqlist*}[2][\eqliststarinit]{\eql@startp{#1}{#2}}{\eql@end}

%    \end{macrocode}
% \end{macro}
% \begin{macro}{\eqlistinitpar}\nocomment
%    \begin{macrocode}
\ifx\eqlistinitpar\undefined
  \def\eqlistinitpar{\relax\listparindent\parindent\relax\parsep\parskip\relax}
\fi
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\eqlistinit}\nocomment
%    \begin{macrocode}
\ifx\eqlistinit\undefined
  \def\eqlistinit{\eqlistinitpar}
\fi
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\eqliststarinit}\nocomment
%    \begin{macrocode}
\ifx\eqliststarinit\undefined
  \def\eqliststarinit{\topsep0pt\relax\itemsep0pt\relax%\partopsep0pt\relax
    \eqlistinitpar}
\fi
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\eqlistlabel}\nocomment
%    \begin{macrocode}
\ifx\eqlistlabel\undefined
  \def\eqlistlabel#1{#1}
\fi

%    \end{macrocode}
% \end{macro}
% \begin{macro}{\eql@cnt}
% The counter "\eql@cnt" is used to generate ``unique'' names for the labels.
%    \begin{macrocode}
\newcount\eql@cnt\relax\eql@cnt=0

%    \end{macrocode}
% \end{macro}
% \begin{macro}{\eql@start}
% The macro "\eql@start" advances the counter "\eql@cnt" (globally!) and then
% starts a list, where for the initialization "\eql@mainprep" is called with
% the corresponding ``unique'' name and the argument.
%    \begin{macrocode}
\long\def\eql@start#1{\global\advance\eql@cnt by1\begin{list}{}{\expandafter
  \eql@mainprepn\expandafter{\romannumeral\eql@cnt}{#1}}}
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\eql@startp}
% The macro "\eql@startp" is similar to "\eql@start" with the difference that
% the first argument is used as the ``unique'' name instead of a counter.
% Thus, "\eql@startp" starts a list, where for the initialization
% "\eql@mainprep" is used with the corresponding arguments.
%    \begin{macrocode}
\long\def\eql@startp#1#2{\begin{list}{}{\eql@mainprep{#2}{#1}}}
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\eql@end}
%    \begin{macrocode}
\def\eql@end{\end{list}}

%    \end{macrocode}
% \end{macro}
% \begin{macro}{\eql@mainprep}
% In "\eql@mainprep", we allow the environment-specific commands and
% initialize
%   \begin{macro}{\eql@makelabel}"\eql@makelabel"\end{macro}
% which will become later our actual "\makelabel".
% We also save this definition into
%   \begin{macro}{\eql@normal}"\eql@normal"\end{macro}
% and (as always if "\eql@makelabel" is changed non-temporary) we also save it
% into
%   \begin{macro}{\eql@current}"\eql@current".\end{macro}
% Finally, "\makelabel" is initialized to "\eqlistlabel", and the
% length of the label (and the left margin) is initialized with
% the length of the corresponding eqparbox with the ``unique'' name "#1".
% Then the (default or user) initialization "#2" is executed.
% After this, "\makelabel" is replaced by "\eql@makelabel". The
% ``user'' definition of "\makelabel" is before saved into
%   \begin{macro}{\eql@long}"\eql@long".\end{macro}
%    \begin{macrocode}
\long\def\eql@mainprep#1#2{\let\longitem\eql@longitem
  \let\eqlistauto\eql@auto
  \let\eqlistnoauto\eql@noauto
  \def\eql@makelabel##1{\eqparbox[b]{#1}{\eql@long{##1}}\hfil}%
  \let\eql@normal\eql@makelabel
  \let\eql@current\eql@makelabel
  \setlength{\labelwidth}{\eqboxwidth{#1}}%
  \setlength{\leftmargin}{\labelwidth}%
  \let\makelabel\eqlistlabel
  #2\addtolength{\leftmargin}{\labelsep}%
  \let\eql@long\makelabel\def\makelabel{\eql@makelabel}}
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\eql@mainprepn}
% Despite of its definition, "\eql@mainprepn" actually expects two arguments:
% "\eql@mainprepn" does the same as "\eql@mainprep" with the difference that
% the first argument should be a unique roman number instead of a ``unique''
% name: The actual name is then obtained by prepending the text "eqlistbox"
% to the number. Note that the number must actually be roman, since otherwise
% (some release(s) of) the \filecite{eqparbox} package becomes confused.
%    \begin{macrocode}
\def\eql@mainprepn#1{\eql@mainprep{eqlistbox#1}}

%    \end{macrocode}
% \end{macro}
% \begin{macro}{\longitem}
% "\longitem" is essentially a call of "\item" with the difference that we
% redefine "\eql@makelabel" temporarily. To avoid usage outside of the intended
% environment, the actual code is put into
%   \begin{macro}{\eql@longitem}"\eql@longitem".\end{macro}
%    \begin{macrocode}
\newcommand{\longitem}{\eql@illlegal\longitem\item}
\def\eql@longitem[#1]{\let\eql@makelabel\eql@long
  \item[#1]\let\eql@makelabel\eql@current}

%    \end{macrocode}
% \end{macro}
% \begin{macro}{\eqlistauto}
% To avoid usage outside of the intended environment,
% the actual code is put into
%   \begin{macro}{\eql@auto}"\eql@auto".\end{macro}
%    \begin{macrocode}
\newcommand{\eqlistauto}[1]{\eql@illegal\eqlistauto}
\def\eql@auto#1{\def\eql@makelabel##1{\setbox0\hbox{\eql@long{##1}}%
    \ifdim#1>\wd0\relax
      \expandafter\eql@normal
    \else
      \expandafter\eql@long
    \fi{##1}}%
  \let\eql@current\eql@makelabel}
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\eqlistnoauto}
% To avoid usage outside of the intended environment,
% the actual code is put into
%   \begin{macro}{\eql@noauto}"\eql@noauto".\end{macro}
%    \begin{macrocode}
\newcommand{\eqlistnoauto}{\eql@illegal\eqlistnoauto}
\def\eql@noauto{\let\eql@makelabel\eql@normal\let\eql@current\eql@makelabel}
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\eql@illegal}
% Write error message in case a command is used outside of the intended
% environment.
%    \begin{macrocode}
\def\eql@illegal#1{\errmessage{\string#1
  can only be used in eqlist or Eqlist environment}}

%    \end{macrocode}
% \end{macro}
% \iffalse
%</eqlist>
% \fi
%
% \Finale\PrintIndex
%
% \iffalse
%<*metainfo>
% \fi
\iffalse -------------------------------------------------------------
%
% Just in case that for some reason the file `eqlist.ins' got lost:
% The content of this file is between the lines %<*insfile> and %</insfile>:
%
%\iffalse
%</metainfo>
%<*insfile>
\def\batchfile{eqlist.ins}
\input docstrip.tex
\keepsilent
\nopreamble
\generateFile{eqlist.sty}{f}{\from{eqlist.dtx}{eqlist}}
\generateFile{eqlist.tex}{f}{\from{eqlist.dtx}{driver}}
%%\generateFile{eqlist.ins.dup}{f}{\from{eqlist.dtx}{insfile}}

\Msg{***************************************************************}
\Msg{*}
\Msg{* To finish the installation, you have to move the}
\Msg{* file 'eqlist.sty' in a directory searched by TeX.}
\Msg{*}
\Msg{*}
\Msg{* Run the file 'eqlist.tex' through LaTeX to produce the}
\Msg{* documentation}
\Msg{*}
\Msg{*}
\Msg{***************************************************************}
\endbatchfile
%</insfile>
%<*metainfo>
% \fi
\fi
% \iffalse
%</metainfo>
% \fi
\endinput

%%% Local Variables: 
%%% mode: latex
%%% TeX-master: "eqlist.tex"
%%% End: