summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/enumitem
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/latex/enumitem')
-rw-r--r--Master/texmf-dist/doc/latex/enumitem/README72
-rw-r--r--Master/texmf-dist/doc/latex/enumitem/enumitem.pdfbin166851 -> 325585 bytes
-rw-r--r--Master/texmf-dist/doc/latex/enumitem/enumitem.tex1228
3 files changed, 926 insertions, 374 deletions
diff --git a/Master/texmf-dist/doc/latex/enumitem/README b/Master/texmf-dist/doc/latex/enumitem/README
index ccbadeaf525..d4e7156aac5 100644
--- a/Master/texmf-dist/doc/latex/enumitem/README
+++ b/Master/texmf-dist/doc/latex/enumitem/README
@@ -1,5 +1,5 @@
-Enumitem
-~~~~~~~~
+Enumitem 3.3
+~~~~~~~~~~~~
A package to customize the three basic lists (enumerate,
itemize and description) by means of a set of parameters,
@@ -11,25 +11,75 @@ design your own lists:
- changes applied globally or only in one of the three
types or even in a single list (including topsep) by
means of a sort of "inheritance",
+- inline lists,
- several description styles (which fix some bad
spacing, too),
- starting value and counter resuming,
- trivlists properly formatted,
-- control on page breaking
+- control on page breaking,
+- gathering of lists to be treated like a unit.
-Recent changes
-~~~~~~~~~~~~~~
-2.1 fixes a bug in resume* -- now it ignores the start key given
-in the previous list, since we want to continue it, not to restart
-it.
+Recent changes (3.0)
+~~~~~~~~~~~~~~~~~~~~
+
+1) Inline lists, with keys to set how items are joined (ie, the
+punctuation between items). Two modes are provided: `boxed' an
+`unboxed' -- with the former (the default) a different punctuation
+before the last item is allowed.
+2) \setlist is calc-savvy (eg, for use in loops), and you can set
+diferent lists and levels at once.
+3) All lengths related to labels can take the value * (and not only
+labelsep and leftmargin). Its behaviour has been made consistent and
+there is new value ! which does not compute the widest label.
+4) With \restartlist{list-name}, list counters can be restarted (in
+case you are using `resume').
+5) `resume*' can be combined with other keys.
+6) Lists can be gathered globally using series, so that they are
+considered a single list. To start a series just use
+series=<series-name> and then resume it with resume=<series-name> or
+resume*=<series-name>.
+7) The ``experimental'' fullwidth has been replaced by a new key
+`wide'.
+8) \SetLabelAlign defines new align values.
+9) You can define ``abstract'' values (eg, label=numeric) and
+new keys.
+
+Bug fixes (3.0)
+~~~~~~~~~~~~~~~
+
+- Star values (eg, leftmargin=*) could not be overriden
+and new values were ignored.
+- nolistsep as the first of several keys was not always
+recognized and therefore treated like a short label
+(ie, nol\roman*stsep).
+- labelwidth didn't always work (when there was a prior
+`widest' and *)
+- With align=right the label and the following text could
+overlap.
+- description didn't get the correct list level.
+- At some point (2.x?) \value* stopped working.
+
+3.1
+~~~
+- Fixed incompatibility with xkeyval
+
+3.2
+~~~
+- start and widest* are calc-savvy.
+- \value can be used with widest*
+- Some internal restrictions in \arabic and the like has been removed.
+It is more flexible at the cost of having a more ``relaxed'' error
+checking.
+
+3.3
+~~~
+- Using *-values with itemize and description didn't work.
-2.2 fixes a bug in some description styles, which didn't empty the
-box containing the labels.
_________________________________________________________________
Javier Bezos | http://www.tex-tipografia.com
.................................................................
-2009-05-18
+2011-07-14
diff --git a/Master/texmf-dist/doc/latex/enumitem/enumitem.pdf b/Master/texmf-dist/doc/latex/enumitem/enumitem.pdf
index f0705b8220f..f137f551d37 100644
--- a/Master/texmf-dist/doc/latex/enumitem/enumitem.pdf
+++ b/Master/texmf-dist/doc/latex/enumitem/enumitem.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/latex/enumitem/enumitem.tex b/Master/texmf-dist/doc/latex/enumitem/enumitem.tex
index ee15d9ff848..70e51ffaaef 100644
--- a/Master/texmf-dist/doc/latex/enumitem/enumitem.tex
+++ b/Master/texmf-dist/doc/latex/enumitem/enumitem.tex
@@ -2,10 +2,10 @@
% | Typeset this file to document enumitem.sty |
% +--------------------------------------------------+
%
-% Copyright (c) 2003-2009 by Javier Bezos.
+% Copyright (c) 2003-2011 by Javier Bezos.
% All Rights Reserved.
%
-% This file is part of the enumitem distribution release 2.2
+% This file is part of the enumitem distribution release 3.2
% -----------------------------------------------------------
%
% It may be distributed and/or modified under the
@@ -20,7 +20,19 @@
%
% The Current Maintainer of this work is Javier Bezos.
-\documentclass{article}
+\documentclass[a4paper]{ltxguide}
+
+\makeatletter
+\newenvironment{desc}
+ {\if@nobreak
+ \vskip-\lastskip
+ \vspace*{-2.5ex}%
+ \fi
+ \decl}
+ {\enddecl}
+\makeatother
+
+\newcommand\3{\unskip\enspace\fbox{\fontsize{4}{4}\selectfont NEW 3.0}}
\usepackage{hyperref}
@@ -36,7 +48,7 @@ find mistakes in the manual. Other packages by the same author:
\textsf{gloss} (with Jos\'e Luis D\'{\i}az), \textsf{accents,
tensind, esindex, dotlessi, titlesec, titletoc}.}}
-\date{Version 2.2\\2009-05-18}
+\date{Version 3.3\\2011-07-14}
\IfFileExists{enumitem.sty}{\usepackage{enumitem}}{}
@@ -58,13 +70,11 @@ tensind, esindex, dotlessi, titlesec, titletoc}.}}
When I began to use \LaTeX{} several year ago, two particular points
annoyed me because I found customizing them was very complicated
---headlines/footlines and lists. A new way to redefine the former is
-accomplished in my own \textit{titlesec} package, but none was
-availiable to customize the latter except:
+accomplished in my own \textsf{titlesec} package, but none was
+available to customize the latter except:
\begin{itemize}
\item \textsf{enumerate}, which just allows to change the label and
-it does it pretty well (or almost, as in Spanish a standard label is
-\textit{a}) which cannot be set with \verb|\emph{a})| and one must
-write \verb|\itshape a\/\upshape)|).
+it does it pretty well.
\item \textsf{mdwlist}, which only ``provides some vaguely useful
list-related commands and environments,'' as its manual states,
@@ -73,11 +83,9 @@ and not a coherent way of handling lists.
\item \textsf{paralist}, which provides lists within a paragraph (the
original purpose of this package), a few other hard-wired
specific changes and the optional argument of \textsf{enumerate}.
-Note \textsf{enumitem} does not allow grouping items within
-a paragraph yet.
\end{itemize}
-One of the main drawbacks of the standard \verb|list| is its weird
+One of the main drawbacks of the standard |list| is its weird
parameters, whose meaning is not always obvious. In order to provide
a cleaner interface two approaches were possible: either defining new
lists, or introducing a new syntax making the standard lists easier to
@@ -93,53 +101,59 @@ parameters of, say, enumerate and then in turn override
a few paremeters of a particular instance. The values will
be searched in the hierarchy.
-This is basically an advance of a project which I am working
-on which will add this kind of inheritance to other structures
-of \LaTeX{}.
-
\section{The package}
This package is intended to ease customizing the three
-basic list environments: \verb|enumerate|, \verb|itemize| and
-\verb|description|. It extends their syntax to allow
+basic list environments: |enumerate|, |itemize| and
+|description|. It extends their syntax to allow
an optional argument where a set of parameters in the
-form \verb|key=value| are available:
+form |key=value| are available:
\begin{itemize}
\item
Vertical spacing:
\begin{itemize}
-\item \verb|topsep|
-\item \verb|partopsep|
-\item \verb|parsep|
-\item \verb|itemsep|
+\item |topsep|
+\item |partopsep|
+\item |parsep|
+\item |itemsep|
\end{itemize}
\item
Horizontal spacing:
\begin{itemize}
-\item \verb|leftmargin|
-\item \verb|rightmargin|
-\item \verb|listparindent|
-\item \verb|labelwidth|
-\item \verb|labelsep|
-\item \verb|itemindent|
+\item |leftmargin|
+\item |rightmargin|
+\item |listparindent|
+\item |labelwidth|
+\item |labelsep|
+\item |itemindent|
\end{itemize}
\end{itemize}
-These are equivalent to the well known list parameters, but
-two of them, namely \verb|leftmargin| and \verb|labelsep|,
-can have in addition the special value of \verb|*| as
-described below.
+For example:
+\begin{verbatim}
+\begin{itemize}[itemsep=1ex,leftmargin=1cm]
+\end{verbatim}
+
+The keys above are equivalent to the well known list parameters---see a
+\LaTeX{} manual for a description of them. Next sections explains the
+extensions provided by |enumitem|.
-The following new parameters are provided:
-\begin{itemize}
+\section{Keys}
+
+This section describes the keys in displayed lists. Most of them are
+available in inline lists, where further keys are available (see
+\ref{s.inline}).
-\item \verb|font|. Sets the label font. Useful when the label is
-changed with the optional argument of \verb|\item|.
+\subsection{Label and cross references format}
-\item \verb|label|. Sets the label to be used in the current level.
-A set of starred versions of \verb|\alph|, \verb|\Alph|,
-\verb|\arabic|, \verb|\roman| and \verb|\Roman|, without argument
-stand for the current counter in \verb|enumerate|.\footnote{Actually,
+\begin{desc}
+|label=<commands>|
+\end{desc}
+
+Sets the label to be used in the current level.
+A set of starred versions of |\alph|, |\Alph|,
+|\arabic|, |\roman| and |\Roman|, without argument
+stand for the current counter in |enumerate|.\footnote{Actually,
the asterisk is currently the argument but things may change.
Consider them as starred variants and follow the corresponding
syntax.} Thus
@@ -147,33 +161,53 @@ syntax.} Thus
\begin{enumerate}[label=\emph{\alph*})]
\end{verbatim}
prints \textit{a}), \textit{b}), and so on (this is a
-standard style in Spanish).
+standard style in Spanish, and formerly used by Chicago, too).
-A fancier example (which looks ugly, but it is intended only
-to illustrate what is possible; requires \textsf{color} and
-\textsf{pifont}):
+It works with |\value|, too (provided the widest label is not to be
+computed or \verb|widest*| is used, see below). A fancier example
+(which looks ugly, but it is intended only to illustrate what is
+possible; requires \textsf{color} and \textsf{pifont}):
\begin{verbatim}
-\begin{enumerate}[label=\protect\fcolorbox{blue}{yellow}{\ding{\value*}},
+\begin{enumerate}[label=\protect\fcolorbox{blue}{yellow}{\protect\ding{\value*}},
start=172]
\end{verbatim}
-\item \verb|label*| is like \verb|label| but its value is appended to
-the current label. For example, the follollowing defines a
-\verb|legal| list (1., 1.1., 1.1.1., and so on):
+The value of |label| is a moving argument, and fragile commands must
+be protected \textit{except} the counters. Because of that, use of
+\verb|\value| is somewhat tricky, because \verb|\the| or \verb|\ifnum|
+expects an actual value, which is not the case when \verb|label| is
+being processed to replace internally the \verb|*| by the form with
+the counter argument. The best solution is usually encapsulating the
+logic inside a new ``counter'' with the help of
+\verb|\AddEnumerateCounter|.\footnote{Which is admittedly somewhat
+convoluted. A better way to accomplish this is on the way.}
+
+If you prefer setting labels like the \textsf{enumerate} package, use
+``short labels'' (see section \ref{s.short}).
+
+\begin{desc}
+|label*=<commands>|
+\end{desc}
+
+Like |label| but its value is appended to the parent label. For example, the follollowing defines a |legal| list (1.,
+1.1., 1.1.1., and so on):
\begin{verbatim}
\newlist{legal}{enumerate}{10}
\setlist[legal]{label*=\arabic*.}
\end{verbatim}
+\begin{desc}
+|ref=<commands>|
+\end{desc}
-\item \verb|ref|. By default, \verb|label| sets also the form of cross
-references and \verb|\the...|, but you can define a
-different format. For
+By default, |label| sets also the form of cross references and
+|\the...| (overriding the settings in previous hierarchical
+levels), but you can define a different format with this key. For
example, to remove the right parethesis:
\begin{verbatim}
\begin{enumerate}[label=\emph{\alph*}),ref=\emph{\alph*}]
\end{verbatim}
-In both \verb|label| and \verb|ref|, the counters can be
+In both |label| and |ref|, the counters can be
used as usual:
\begin{verbatim}
\begin{enumerate}[label=\theenumi.\arabic*.]
@@ -184,11 +218,11 @@ or
\end{verbatim}
(provided the current level is the second one).
-Note the \verb|label|s are \textit{not} accumulated to form
+Note the |label|s are \textit{not} accumulated to form
the reference. If you want, say, something like 1.\textit{a}
from 1) as first level and \textit{a}) as second level,
-you must set it with \verb|ref|. You may use
-\verb|\ref{level1}.\ref{level2}| with appropiate \verb|ref|
+you must set it with |ref|. You may use
+|\ref{level1}.\ref{level2}| with appropiate |ref|
settings, but as Robin Fairbairns points out in the \TeX{} FAQ
\begin{quote}
\dots{} [that] would be both tedious and error-prone. What is more, it
@@ -202,84 +236,160 @@ you might want something like:
... subitem \ref{level2} of item \ref{level1} ...
\end{verbatim}
-Both \verb|label| and \verb|ref| are moving arguments, and fragile
+The value of |ref| is a moving argument, and fragile
commands must be protected \textit{except} the counters.
-\item \verb|leftmargin=*|. Sets the label width to the width of
-the current label, using the default value of \textit{0} in
-\verb|\arabic*|, \textit{viii} in \verb|\roman*|, \textit{m} in
-\verb|\alph*| and similarly in uppercase forms. The left
-margin is then set to \verb|labelwidth| $+$ \verb|labelsep|.
-You can give a value to the key \verb|widest|, and it will
-be used to set the margin. For example:
+\begin{desc}
+|font=<commands>|\qquad\verb|format=<commands>|
+\end{desc}
+
+Sets the label font. Useful when the label is changed with the
+optional argument of |\item| and in \texttt{description}. The last
+command in |<commands>| can take an argument with the item label. In
+\texttt{description} class setting are in force, so you may want begin
+with \verb|\normalfont|. A synonymous is \texttt{format}.
+
+\begin{desc}
+|align=left|\qquad |align=right|\qquad |align=parleft|\3
+\end{desc}
+
+How the label is aligned (with relation to the label box edges).
+Three values are possible: |left|, the default |right| and
+\verb|parleft| (a parbox of width \verb|\labelwidth| with flush left
+text). The parameters controlling the label spacing should be
+properly set, either by hand or more conveniently with the |*|
+settings (see below):
\begin{verbatim}
-\begin{itemize}[label=\textbullet, leftmargin=*]
-\begin{enumerate}[label=\roman*), leftmargin=*, widest=iii]
+\begin{enumerate}[label=\Roman*., align=left, leftmargin=*]
\end{verbatim}
+(When the label box is supposed to have its natural width, use
+|left|.)
-Put in in other words, the label starts at the same place as the
-surrounding text (but see \verb|labelindent| below), then comes the
-label, the space after it as set by \verb|labelsep| and the item body.
+\begin{desc}
+|\SetLabelAlign{<value>}{<commands>}|\3
+\end{desc}
+
+New align types can be defined (or the existing ones redefined) with
+|\SetLabelAlign|; the predefined values are equivalent
+to:\footnote{Prior to version 3.0 the left alignments was incorrectly
+defined and the label and the text could overlap.}
+\begin{verbatim}
+\SetLabelAlign{right}{\hss\llap{#1}}
+\SetLabelAlign{left}{#1\hfil}
+\SetLabelAlign{parleft}{\strut\smash{\parbox[t]\labelwidth{\raggedright##1}}}
+\end{verbatim}
-\item \verb|labelsep=*|. Similar to the previous one
-but here the label sep is set to \verb|leftmargin| $-$
-\verb|labelwidth|.
+If the last thing in the definition is a skip (typically \verb|\hfil|), it is
+removed sometimes by description. If for some reason you want to avoid
+this, just add \verb|\null| at the end.
+
+
+\subsection{Horizontal spacing of labels}
+
+\begin{desc}
+|labelindent=<length>|\\
+\verb|\labelindent|
+\end{desc}
+
+This parameter is added in \textsf{enumitem} for the blank space from
+the margin of the enclosing list/text to the left edge of the label box. This
+means there is a redundancy because one of the parameters depends on
+the others, i.e., it has to be computed from the other values, as
+described below. There is a new counter length |\labelindent| which
+defaults to 0 pt. The five parameteres are related in the following
+way:
+\[
+\verb|\leftmargin|+\verb|\itemindent| =
+\verb|\labelindent|+\verb|\labelwidth|+\verb|\labelsep|
+\]
+
+\begin{desc}
+|leftmargin=!|\qquad|itemindent=!|\qquad|labelsep=!|
+\qquad|labelwidth=!|\qquad|labelindent=!|\3
+\end{desc}
+
+Sets which value is to be computed from the others. This is done
+after \textit{all} keys has been read. Explicit values are not lost, and
+so with the following hierarchical settings:
\begin{verbatim}
+leftmargin=2em
+labelindent=1em,leftmargin=!
+labelindent=!
+\end{verbatim}
+|leftmargin| is again 2em and |labelindent| is the computed parameter.
+The default is |labelindent=!|, but note some keys sets another value
+(\verb|wide| and description \verb|style|s).
+
+With |align=right| (the default), |labelindent=!| and
+|labelwidth=!| behave similarly in practice.
+
+\begin{desc}
+|leftmargin=*|\qquad|itemindent=*|\qquad|labelsep=*|
+\qquad|labelwidth=*|\qquad|labelindent=*|
+\end{desc}
+
+Like before, but |labelwidth| is set to the width of the current
+label, using the default value of \textit{0} in |\arabic*|,
+\textit{viii} in |\roman*|, \textit{m} in |\alph*| and
+similarly in uppercase forms (these values can be changed with
+|widest|, see below). Examples are:
+\begin{verbatim}
+\begin{itemize}[label=\textbullet, leftmargin=*]
+\begin{enumerate}[label=\roman*), leftmargin=*, widest=iii]
\begin{itemize}[label=\textbullet,
leftmargin=2pc, labelsep=*]
+\begin{enumerate}[label=\arabic*., leftmargin=2\parindent,
+ labelindent=\parindent, labelsep=*]
\end{verbatim}
-As before, the label starts at the same place as the surrounding text,
-then comes the label, the space after it and the item body. The
-difference between \verb|labelsep=*| and \verb|leftmargin=*| is that
-in the former the item body begins at a fixed place (namely,
-\verb|leftmargin|), while the latter begins at a variable place
+The most useful are |labelsep=*| and |leftmargin=*|.
+With the former the item body begins at a fixed place (namely,
+|leftmargin|), while with the latter begins at a variable place
depending on the label (but always the same within a list, of course).
-Most of times, what you would want is \verb|leftmargin=*|.
-
-Unfortunately, \verb|labelsep| has not a default value
-to be applied to all lists---simply the current value
-is used. If you nest a \verb|leftmargin=*| within a
-\verb|labelsep=*|, the value to compute the left margin
-is not what you could expect. The way \LaTeX{} assigns values
-to the list parameters is one of the things which makes
-redefining lists a mess, but with \textsf{enumitem} you can
-set default values for every list, as described below.
-In this case, all you need is:
+Most of times, what you would want is |leftmargin=*|.
+
+Unfortunately, \LaTeX{} does not define a default |labelsep| to
+be applied to all lists---simply the current value is used. With
+\textsf{enumitem} you can set default values for every list, as
+described below, and so, if you want to make sure |labelsep| is
+under your control, all you need is something like:
\begin{verbatim}
\setlist{itemsep=.5em}
\end{verbatim}
-% \textbf{Note.} Version 0.2 computes the values even with
-% the settings predefined by the classes (only partially
-% tested). Please, let me know if a class gives a wrong
-% result.
+|labelwidth=*| and |labelwidth=!| are synonymous.
-\item \verb|widest|. To be used in conjunction with any of the
-two previous keys, if desired. It overrides the default
-values for the label width. Sometimes, if lists are not very
-long, a value of \verb|a| for \verb|\alph| is more sensible
-than \verb|m|:
+\begin{desc}
+|widest=<string>|\qquad|widest*=<integer>|\3\qquad|widest|
+\end{desc}
+
+To be used in conjunction with the \texttt{*}-values, if
+desired. It overrides the default value for the widest
+printed counter. Sometimes, if lists are not very long, a value of
+|a| for |\alph| is more sensible than the default |m|:
\begin{verbatim}
\begin{enumerate}[leftmargin=*,widest=a] % Assume standard 2nd level
\end{verbatim}
+With no value, the default is restored. With |widest*|, the string is
+built using |<integer>| as the value of the counter (e.g., with
+\verb|\roman|,
+\verb|widest=viii| and \verb|widest*=8| are the same).
-\item \verb|labelindent|. Blank space before the label
-with \verb|leftmargin=*| and \verb|labelsep=*|, and in
-\verb|description|. Example:
-\begin{verbatim}
-\begin{enumerate}[label=\arabic*., leftmargin=2\parindent,
- labelindent=\parindent, labelsep=*]
-\end{verbatim}
+Since |\value| does not return a string but a number,
+|widest| and the \verb|*| values cannot be used with it.
+However, with \verb|widest*|, being a number, it is allowed.
+
+\subsection{More on horizontal spacing}
-Since \verb|\parindent| is not used as such inside lists, but instead
-is set internally to either \verb|itemindent| or \verb|listparindent|,
+Since |\parindent| is not used as such inside lists, but instead
+is set internally to either |\itemindent| or |\listparindent|,
when used as the value of a parameter \textsf{enumitem} returns the
global value, i. e., the value it has outside the outermost list.
-\end{itemize}
-The horizontal space in the left margin of the current level
-is distributed in the following way:
+The horizontal space in the left margin of the current level is
+distributed in the following way:\footnote{Admittedly, these figures
+are not exactly the clearest possible, and I intend to improve them in
+a future release}
\begin{center}
\begin{tabular}{cc}
\fbox{\fbox{\strut \texttt{labelindent}}
@@ -290,31 +400,48 @@ is distributed in the following way:
\texttt{leftmargin}
\end{tabular}
\end{center}
-Remember \verb|labelsep| spans part of \verb|leftmargin| and
-\verb|itemindent| if the latter is not zero. This is often
-somewhat confusing, so remember that if you want a separation
-between label and item \textit{body} of, say, 6pt, and the item
-indent is 8pt, then \verb|labelsep| should be $6 + 8$. The
-foregoing discussion about how the \verb|*| values are computed
-presumes \verb|itemindent| is 0 pt, but any other value it is
-taken into account.
-\begin{itemize}
-
-\item \verb|align|. How the label is aligned. Two values
-are possible: \verb|left| and the default \verb|right|.
-The parameters controlling the label spacing should be
-properly set, either by hand or more conveniently with
-the \verb|*| settings:
-\begin{verbatim}
-\begin{enumerate}[label=\Roman*., align=left, leftmargin=*]
-\end{verbatim}
+\begin{desc}
+\verb|labelsep*=<length>|\3
+\end{desc}
+
+Remember |labelsep| spans part of |leftmargin| and
+|itemindent| if the latter is not zero. This is often somewhat
+confusing, so a new key is provided---with \texttt{labelsep*} the
+value is reckoned from the left margin (it just sets |\labelsep|
+and then adds |\itemindent| to it, but in addition later changes to
+|itemindent| are taken into account):
+\begin{center}
+\begin{tabular}{cc}
+\fbox{\fbox{\strut \texttt{labelindent}}
+ \fbox{\strut \texttt{labelwidth}}
+ \fbox{\strut \texttt{labelsep*}}}
+&
+\fbox{\strut\texttt{itemindent}}\\
+\texttt{leftmargin}
+\end{tabular}
+\end{center}
+
+\begin{desc}
+|labelindent*=<length>|\3
+\end{desc}
-\item \verb|start|. Sets the number of the first item.
+Like |labelindent|, but it is reckoned from the left margin in
+the current list and not from that in the enclosing list/text.
-\item \verb|resume|. Makes the counter to be continued
-from the previous \verb|enumerate|, instead of resetting it
-to 1.
+\subsection{Numbering, stopping, and resuming}
+
+\begin{desc}
+|start=<integer>|
+\end{desc}
+Sets the number of the first item.
+
+\begin{desc}
+|resume|
+\end{desc}
+
+The counter continues from the previous |enumerate|,
+instead of being reset to 1.
\begin{verbatim}
\begin{enumerate}
\item First item.
@@ -322,124 +449,316 @@ to 1.
\end{enumerate}
Text.
\begin{enumerate}[resume]
-\item Third item
+\item Third item
\end{enumerate}
\end{verbatim}
-\item \verb|resume*| is like \verb|resume| but the options from the
-previous list are used, too. This option must be restricted to the
-optional argument in a environment (this is the only place where it
-makes sense) and further keys are not allowed. It should be used
-sparingly---if you are using it often, then very likely you want
-to define a new list (see below).
+This is done locally. If you want global resuming, see next section on series.
+
+\begin{desc}
+|resume*|
+\end{desc}
+
+Like |resume| but the options from the previous list are used,
+too. This option must be restricted to the optional argument in a
+environment (this is the only place where it makes sense). It should
+be used sparingly---if you are using it often, then very likely you
+want to define a new list (see \ref{s.clone}). Further keys are allowed, and
+in this case the saved options are overriden by those in the current
+list (i.e., the position of \texttt{resume*} does not matters). For
+example:
+\begin{verbatim}
+\begin{enumerate}[resume*,start=1] % or [start=1,resume*]
+\end{verbatim}
+uses the keys in the previuos \texttt{enumerate}, but restarts the
+counter.
+
+\subsection{Series}
+
+\begin{desc}
+|series=<series-name>|\3\\
+|<series-name>|\qquad|resume*=<series-name>|
+\qquad|resume=<series-name>|\3
+\end{desc}
+
+A new method (3.0) of continuing lists is by means of the key
+\texttt{series}, so that they behave like a unit. A list with key
+\texttt{series} is considered the starting list and its settings are
+stored \textit{globally}, so that they can be used later with
+\texttt{resume}/\texttt{resume*}. All these keys take a value with
+the series name (which must be different from existing keys):
+\begin{itemize}
+\item |resume=<series-name>| just continue numbering items in the
+series,
+\item |resume*=<series>| also applies the settings of the
+starting list,
+\item |<series>|, i.e., the series name used as a key, is an
+alternative to |resume*=<series>|.
+\end{itemize}
+For example:
+\begin{verbatim}
+\begin{enumerate}[label=\arabic*(a),leftmargin=1cm,series=lafter]
+\item A
+\item B
+\end{enumerate}
+\end{verbatim}
+You get: 1(a) 2(a). You can continue with:
+\begin{verbatim}
+\begin{enumerate}[label=\arabic*(b),resume*=lafter]
+ % or [label=\arabic*(b),lafter]
+\item A
+\item B
+\end{enumerate}
+\end{verbatim}
+You get: 3(b) 4(b). (But you can use |start=1|, if you like.)
+
+Note you can add further arguments, which are executed after those
+saved at the starting list and therefore take precedence over them --
+in particular, |resume*| itself takes precedence over a
+|start| (e.g., |start=1|) in the the starting list.
+
+Every time a series is started, several commands are defined
+internally, so to avoid wasting resources and use the same name for
+non-overlapping series.
+
+
+\subsection{Penalties}
+
+\begin{desc}
+|beginpenalty=<integer>|\qquad
+|midpenalty=<integer>|\qquad |endpenalty=<integer>|
+\end{desc}
+
+Set the penalty at the beginning of a list, between items and at the
+end of the list, respectively. Please, refer to your \LaTeX{} or
+\TeX{} manual about how penalties control page breaks. Unlike other
+parameters, when a list starts their values are not reset to the
+default, thus they apply to the child lists.
+\begin{desc}
+|before=<code>| \qquad |before*=<code>|
+\end{desc}
+
+Execute code before the list starts (more precisely, in the second
+argument of the |list| environment used to define them). The
+unstarred form sets the code to be executed, overriding any previous
+value, while the starred one adds the code to the existing one (in
+the setting hierarchy, see below, \textit{not} with relation to the
+enclosing list/text). It can contain, say, rules and text, but this
+has not been extensively tested. All calculations have been finished,
+and you can access and manipulate the list parameters. For example,
+to have both margins (left and right) set to the widest label:
+\begin{verbatim}
+\setlist{leftmargin=*,before=\setlength{\rightmargin}{\leftmargin}}
+\end{verbatim}
-\item \verb|beginpenalty|, \verb|midpenalty| and \verb|endpenalty| set
-the penalty at the beginning of a list, between items and at the end
-of the list. Please, refer to your \LaTeX{} or \TeX{} manual about
-how penalties control page breaks. Unlike other parameters, when a
-list starts their values are not reset to the default, thus they
-apply to the enclosed lists, too.
+\begin{desc}
+|after=<code>|\qquad|after*=<code>|
+\end{desc}
-\item \verb|before| and \verb|before*| executes code before the list
-starts (more precisely, in the second argument of the \verb|list|
-environment used to define them). The former sets the code to be
-executed, overriding any previous value, while the starred form adds
-the code to the existing one (in the setting hierarchy, see below,
-\textit{not} with relation to the enclosing list). It can contain,
-say, rules and text, but this has not been extensively tested.
+Same, but just before the list ends.
-\item \verb|after| and \verb|after*| is the same but just before
-the list ends.
+\subsection{Description styles}
-\end{itemize}
+A key available in |description|.
+\begin{desc}
+|style=<name>|
+\end{desc}
-A key are available in \verb|description|
-\begin{itemize}
-\item \verb|style|. Sets the \textit{style}, with the
-following values:
+Sets the description \textit{style}. |<name>| can be any of the
+following:
\begin{itemize}
-\item \verb|nextline|: if the label does not fit in the margin, the
-text continues in the next line, otherwise it is placed in a box of
-width \verb|leftmargin|, ie, the item body never sticks into the left
-margin.
+\item |standard|: like |description| in standard classes, although
+with other classes it could be somewhat different. The label is
+boxed. Sets \verb|itemindent=!|.
-\item \verb|sameline|: like \verb|nextline| but if the label does not
-fit in the margin the text continues in the same line.
+\item |unboxed|: much like the standard |description|, but
+the label is not boxed to avoid uneven spacing and unbroken labels if
+they are long. Sets \verb|itemindent=!|.
+
+\item |nextline|: if the label does not fit in the margin, the text
+continues in the next line, otherwise it is placed in a box of width
+|\leftmargin| $-$ |\labelsep|, i.e., the item body never sticks into
+the left margin. Sets \verb|labelwidth=!|.
+
+\item |sameline|: like |nextline| but if the label does not
+fit in the margin the text continues in the same line. Same as
+\verb|style=unboxed,labelwidth=!|.
+
+\item |multiline|: the label is placed in a parbox whose width is
+|leftmargin|, with several lines if
+necessary. Same as \verb|style=standard,align=parleft,labelwidth=!|.
+
+Three caveats: (1) mixing boxed and unboxed labels has not a
+well-defined behaviour, (2) when nesting list all combinations are
+allowed but not all make sense, and (3) nesting \verb|nextline| lists
+is not supported (it works, but its behaviour might change in the
+future, because the current one is not what one could expect).
-\item \verb|multiline|: the label is placed in a parbox whose width is
-\verb|leftmargin|, with several lines if necessary.
-\item \verb|unboxed|: much like the standard \verb|description|, but
-the label is not boxed to avoid uneven spacing and unbroken labels if
-they are long.
-\end{itemize}
-\end{itemize}
-A few predefined valueless keys might be useful:
-\begin{itemize}
-\item \verb|noitemsep| kills the space between items
-and paragraphs (ie, \verb|itemsep=0pt| and \verb|parsep=0pt|).
-\item \verb|nolistsep| kills all vertical spacing.
-\item \verb|fullwidth| is still somewhat experimental. The
-leftmargin is null and the label is part of the text. Here
-\verb|labelsep| sets the separation between the label and the first
-word.
-You may want to set \verb|itemindent| and \verb|listparindent|
-to \verb|\parindent|, too.
\end{itemize}
-% If you think the addition of \verb|\parskip| and \verb|\parsep|
-% is annoying, you can use \verb|listskip| ($=$ \verb|\topsep| $-$
-% \verb|\parskip|) and \verb|itemskip| ($=$ \verb|\itemsep| $-$
-% \verb|\parsep|).
+
+\subsection{Compact lists}
+
+\begin{desc}
+|noitemsep|\qquad|nolistsep|
+\end{desc}
+
+The key |noitemsep| kills the space between items and paragraphs
+(i.e., |itemsep=0pt| and |parsep=0pt|), while
+|nolistsep| kills all vertical spacing.
+
+\subsection{``Wide'' lists}
+
+\begin{desc}
+\verb|wide|\3\\
+\verb|wide=<parindent>|
+\end{desc}
+
+With this convenience key, the leftmargin is null and the label is
+part of the text---in other word, the items look like ordinary
+paragraphs.\footnote{\texttt{fullwidth} is deprecated.} Here |labelsep|
+sets the separation between the label and the first word. It is
+equivalent to
+\begin{verbatim}
+align=left, leftmargin=0pt, labelindent=\parindent,
+listparindent=\parindent, labelwidth=0pt, itemindent=!
+\end{verbatim}
+With |wide=<parindent>| you may set at once another value instead of
+|\parindent|. Of course, these keys can be overriden after
+\verb|wide|, too; for example, remembering that with left-aligned labels
+the text is pushed if the they are wider than |labelwidth|, you
+can set |labelwidth=1.5em| for a minimal width, or instead of
+|itemindent=!| you may prefer |itemindent=*|, which sets the
+minimal width to that of widest label. In level 2 you may prefer
+|labelindent=2\parindent|, and so on. You may also want to
+combine it with |noitemsep| or |nolistsep|.
+
+\section{Inline lists}
+\label{s.inline}
+
+\3
+
+\begin{desc}
+|inline| \qquad(package option)\\
+\texttt{enumerate*}\qquad\texttt{itemize*}\qquad
+\texttt{description*} \qquad(environments)
+\end{desc}
+
+With the package option \texttt{inline}, three environments for inline
+lists are defined: \texttt{enumerate*}, \texttt{itemize*}, and
+\texttt{description*}. They emulate the behaviour of
+\textsf{paralist} and \textsf{shortlst} in that labels and settings
+are shared with the displayed (ie, ``normal'') lists \texttt{enumerate},
+\texttt{itemize} and \texttt{description}, respectively (however,
+remember resuming is based on environment names, not on list types). This applies
+only to those created with \texttt{inline} -- inline lists created
+with |\newlist| as described below are independent and use their
+own labels and settings.
+
+\begin{desc}
+|itemjoin=<string>|\qquad|itemjoin*=<string>|
+\qquad|afterlabel=<string>|
+\end{desc}
+
+Format is set with keys \texttt{itemjoin} (default is a space), and
+\texttt{afterlabel} (default is |\nobreakspace|, ie, |~|).
+An additional key is \texttt{itemjoin*}, which, if set, is used
+instead of \texttt{itemjoin} before the last item. So, with
+\begin{verbatim}
+before=\unskip{: }, itemjoin={{; }}, itemjoin*={{, and }}
+\end{verbatim}
+the following punctuation between items is used:
+\begin{quote}
+Blah blah: (a) one; (b) two; (c) three, and (d) four. Blah blah
+\end{quote}
+
+\verb|itemjoin| is ignored in vertical mode (i.e., in mode unboxed
+and just after a quote, a displayed list and the like).
+
+\begin{desc}
+|mode=unboxed|\qquad|mode=boxed|
+\end{desc}
+
+Items are boxed, so floats are lost and nested lists are not allowed
+(remember many displayed elements are defined as lists). If using
+floats or lists inside inline lists is important, use an alternative
+``mode'', which you can activate with
+\texttt{mode=unboxed} (the default is \texttt{mode=boxes}). With it
+floats may be used freely, but misplaced |\item|s are not catched and
+\texttt{itemjoin*} is ignored (a warning is written to the log about
+this fact).
+
+\section{Global settings}
Global changes, to be applied to all of these list, are also
possible:
-\begin{itemize}
-\item \verb|\setenumerate[level]{format}|
-\item \verb|\setitemize[level]{format}|
-\item \verb|\setdescription{format}|
-\item \verb|\setlist[level]{format}|
-\end{itemize}
-Where \verb|level| is the list level in \verb|list|, and the
-corresponding level in \verb|enumerate| and \verb|itemize|. Without
-\verb|level|, the format applies to all levels. Here list does not
-mean any list but only the three ones handled by this package.
-Example:
+\begin{desc}
+|\setlist[enumerate,<levels>]{<format>}|\\
+|\setlist[itemize,<levels>]{<format>}|\\
+|\setlist[description,<levels>]{<format>}|\\
+|\setlist[<levels>]{<format>}|
+\end{desc}
+Where |<level>| is the list level (one or more) in |list|, and the
+corresponding levels in |enumerate| and
+|itemize|.\footnote{\verb|\string\setenumerate|,
+\verb|\string\setitemize| and \verb|\string\setdescription| are
+deprecated.} With no
+|<levels>|, the format applies to all of them. Here list does not
+mean any list but only the three ones handled by this package and
+those redefined by this package or defined with |\newlist| (see
+below). For example:
\begin{verbatim}
\setlist{noitemsep}
\setlist[1]{\labelindent=\parindent} % << Usually a good idea
-\setitemize{leftmargin=*}
-\setitemize[1]{label=$\triangleleft$}
-\setenumerate{labelsep=*, leftmargin=1.5pc}
-\setenumerate[1]{label=\arabic*., ref=\arabic*}
-\setenumerate[2]{label=\emph{\alph*}),
- ref=\theenumi.\emph{\alph*}}
-\setenumerate[3]{label=\roman*), ref=\theenumii.\roman*}
-\setdescription{font=\sffamily\bfseries}
-\end{verbatim}
-These setting are read in the following order: list,
-list at the current level, enumerate/itemize/description,
-and enumerate/itemize at the current level; if a key
-has several values, the last one, ie. the most specific
-one, is applied. Finally, the
-optional argument, if any, is applied. \LaTeX{} provides
-a set of macros to change many of these parameters, but
-setting them with the package is more consistent and
-sometimes more flexible at the cost of being more
-``explicit'' (and verbose).
-
-No attempt has been made (yet) to discriminate the font size
-(\verb|\normalsize|, \verb|\small|\dots). Suggestions are
-most welcome.
-
-\subsection{\textsf{enumerate}-like labels}
+\setlist[itemize]{leftmargin=*}
+\setlist[itemize,1]{label=$\triangleleft$}
+\setlist[enumerate]{labelsep=*, leftmargin=1.5pc}
+\setlist[enumerate,1]{label=\arabic*., ref=\arabic*}
+\setlist[enumerate,2]{label=\emph{\alph*}),
+ ref=\theenumi.\emph{\alph*}}
+\setlist[enumerate,3]{label=\roman*), ref=\theenumii.\roman*}
+\setlist[description]{font=\sffamily\bfseries}
+\end{verbatim}
+These setting are read in the following order: list, list at the
+current level, enumerate/itemize/description, and
+enumerate/itemize/description at the current level; if a key appears
+several times with different values, the last one, i.e., the most
+specific one, is applied. If we are resuming a series or a list with
+\texttt{resume*}, the saved keys are then applied. Finally, the
+optional argument (except \texttt{resume*}), if any, is applied.
+
+\LaTeX{} provides a set of macros to change many of these parameters,
+but setting them with the package is more consistent and sometimes
+more flexible at the cost of being more ``explicit'' (and verbose).
+
+The list specification can contain variables and counters, provided
+they are expandable, and counters are \textsf{calc}-savvy, so that if
+you load this package you can write things like:
+\begin{verbatim}
+\newcount{toplist}
+\setcount{toplist}{1}
+\newcommand{\mylistname}{enumerate}
+\setlist[\mylistname,\value{toplist}+1]{labelsep=\itemindent+2em]
+\end{verbatim}
+This allows defining lists within loops.
+
+Currently, a way to discriminate the font size is not provided
+(|\normalsize|, |\small|\dots).
+
+\section{\textsf{enumerate}-like labels}
+\label{s.short}
+
+\begin{desc}
+|shortlabels| (package option)
+\end{desc}
With the package option \texttt{shortlabels} you can use an
-\textsf{enumerate}-like syntax, where \verb|A|, \verb|a|, \verb|I|,
-\verb|i| and \verb|1| stand for \verb|\Alph*|, \verb|\alph*|,
-\verb|\Roman*|, \verb|\roman*| and \verb|\arabic*|. This is intended
+\textsf{enumerate}-like syntax, where |A|, |a|, |I|,
+|i| and |1| stand for |\Alph*|, |\alph*|,
+|\Roman*|, |\roman*| and |\arabic*|. This is intended
mainly as a sort of compatibility mode with the \textsf{enumerate}
package, and therefore the following special rule applies: if the very
first option (at any level) is not recognized as a valid key, then it
@@ -450,7 +769,7 @@ example:
...
\end{enumerate}
\end{verbatim}
-Although perhaps not so useful, you can omit \verb|label=| in the
+Although perhaps not so useful, you can omit |label=| in the
itemize environment under similar conditions, too:
\begin{verbatim}
\begin{itemize}[\textbullet]
@@ -458,61 +777,162 @@ itemize environment under similar conditions, too:
\end{itemize}
\end{verbatim}
-In addition, you can define new keys (or redefine them), which is
+\begin{desc}
+|\SetEnumerateShortLabel{<key>}{<replacement>}|
+\end{desc}
+
+With this command, you can define new keys (or redefine them), which is
particularly useful for enumerate to be adapted to especific
-typographical rules or to extend it for non-Latin scrips:
-\begin{verbatim}
-\SetEnumerateShortLabel{<key>}{<replacement>}
-\end{verbatim}
-where \verb|<replacement>| contains one of the starred versions of
+typographical rules or to extend it for non-Latin scrips. Here
+|<replacement>| contains one of the starred versions of
counters. For example:
\begin{verbatim}
\SetEnumerateShortLabel{i}{\textsc{\roman*}}
\end{verbatim}
-redefines \verb|i| so that items using this key are numbered with
-small caps roman numerals.
+redefines |i| so that items using this key are numbered with
+small caps roman numerals. The key has to be a single letter.
-\subsection{Cloning the three basic lists}
+\section{Cloning the basic lists}
+\label{s.clone}
-As of version 2.0 the three lists can be cloned so that you can
-define ``logical'' environments behaving like them. To define a
-new lists (or redefine a existing one), use \verb|\newlist| (or
-\verb|\renewlist|), which the following syntax:
-\begin{verbatim}
-\newlist{<name>}{<type>}{<max-depth>}
-\end{verbatim}
-where \verb|<type>| is \verb|enumerate|, \verb|itemize| or
-\verb|description|. Then you can (in fact you must, at least the
-label) set the new list with \verb|\setlist|:
+\begin{desc}
+|\newlist{<name>}{<type>}{<max-depth>}|\\
+|\renewlist{<name>}{<type>}{<max-depth>}|
+\end{desc}
+
+The three lists can be cloned so that you can define ``logical''
+environments behaving like them. To define a new lists (or redefine a
+existing one), use |\newlist| (or |\renewlist|), where |<type>| is
+|enumerate|, |itemize| or |description|.
+
+\begin{desc}
+\verb|\setlist[<names>,<levels>]{<keys/values>}|\\
+\verb|\setlist*[<names>,<levels>]{<keys/values>}|
+\end{desc}
+
+After creating a list, you can (in fact you
+must, at least the label) set the new list with |\setlist|:
\begin{verbatim}
\newlist{ingredients}{itemize}{1}
\setlist[ingredients]{label=\textbullet}
\newlist{steps}{enumerate}{2}
-\setlist[steps,1]{label=(\arabic*)}
-\setlist[steps,2]{label=(\arabic*)}
+\setlist[steps,1,2]{label=(\arabic*)}
\end{verbatim}
-The optional argument of \verb|\setlist| has an extended
-syntax---names say which lists applies the settings to, and numbers
-the level. Do not use this syntax in the three basic lists, but that
-above, except if you redefine them.
-
-\subsection{New counters}
-
-With
+Names in the optional argument of |\setlist| say which lists applies the
+settings to, and numbers say the level (it is calc-savvy). Several
+lists and/or several levels can be given, and all combinations are
+set; e.g.:
\begin{verbatim}
-\AddEnumerateCounter{<LaTeX counter>}{<TeX count>}{<widest label>}
+\setlist[enumerate,itemize,2,3]{...}
\end{verbatim}
-a counter representation is ``registered'' so that \textsf{enumitem}
+\noindent sets enumerate/2, enumerate/3, itemize/2 and itemize/3.
+No number (or 0) means ``all levels'' and no name means ``all lists''; no
+optional argument means ``all lists at all levels''.
+
+The three inline lists have types \texttt{enumerate*},
+\texttt{itemize*}, and \texttt{description*}, which are available
+always, even without the package option |inline| (which just defines
+three environments with these names).
+
+The starred form \verb|\setlist*| adds the settings to previous ones.
+
+\begin{desc}
+\verb|\setlistdepth{<integer>|\3
+\end{desc}
+
+By default, \LaTeX{} has a limit of 5 nesting levels, but when
+cloning list this value may be too short, and therefore you may want
+to set a new value. In levels below the 5th (or the deepest defined by a
+class), the settings of the last are used (i.e., \verb|\@listvi|).
+
+\section{More about counters}
+
+\subsection{New counter representation}
+
+\begin{desc}
+\verb|\AddEnumerateCounter{<LaTeX command>}{<internal command>}{<widest label>}|
+\end{desc}
+
+``Registers'' a counter representation so that \textsf{enumitem}
recognizes it. Intended mainly for non Latin scripts, but also useful
in Latin scripts. For example:
\begin{verbatim}
+\makeatletter
\def\ctext#1{\expandafter\@ctext\csname c@#1\endcsname}
\def\@ctext#1{\ifcase#1\or First\or Second\or Third\or
Fourth\or Fifth\or Sixth\fi}
+\makeatother
\AddEnumerateCounter{\ctext}{\@ctext}{Second}
\end{verbatim}
+A starred variant allows to give a number instead of a string as the
+widest label; for example, if the widest label is that corresponding
+to the value 2:\3
+\begin{verbatim}
+\AddEnumerateCounter*{\ctext}{\@ctmoreext}{2}
+\end{verbatim}
+This variant is to be preferred if the representation is not a plain
+string but it is styled, e.g.,
+with small caps. (The counter names can contain |@| even if not a letter.)
-\subsection{Package option \texttt{loadonly}}
+\subsection{Restarting \texttt{enumerate}s}
+
+\begin{desc}
+|\restartlist{<list-name>}|\3
+\end{desc}
+
+Currently, with
+\begin{verbatim}
+\setlist[enumerate]{resume}
+\end{verbatim}
+you can get a continuous numbering through a document. A new command has
+been added for restarting the counter in the middle of the document:
+\begin{verbatim}
+\restartlist{<list-name>}
+\end{verbatim}
+
+It is based solely in the list name, not the list type, which means
+\texttt{enumerate*} as defined with the package option \texttt{inline}
+is not the same as \texttt{enumerate}, because its name is different.
+
+\section{Generic keys and values}
+
+\begin{desc}
+|\SetEnumitemKey{<key>}{<replacement>}|\3
+\end{desc}
+
+With this command you can create your own (valueless) keys. For
+example:
+\begin{verbatim}
+\SetEnumitemKey{midsep}{topsep=3pt,partopsep=0pt}
+\end{verbatim}
+
+Keys so defined can then be used like the others.
+
+\begin{desc}
+|\SetEnumitemValue{<key>}{<string-value>}{<replacement>}|\3
+\end{desc}
+
+This commands provides a further abstraction layer for the
+|<key>=<value>| pairs. With it you can define logical names which
+are translated to the actual value. For example, with:
+\begin{verbatim}
+\SetEnumitemValue{label}{numeric}{\arabic*.}
+\SetEnumitemValue{leftmargin}{standard}{\parindent}
+\end{verbatim}
+you might say:
+\begin{verbatim}
+\begin{enumerate}[label=numeric,leftmargin=standard]
+\end{verbatim}
+So, you can left to the final design what |label=numeric| means.
+
+\section{Package options}
+
+Besides \verb|inline|, \verb|ignoredisplayed|, and \verb|shortlabels|,
+the following option is available.
+
+\begin{desc}
+\verb|loadonly|
+\end{desc}
With this package option the package is loaded but the three
lists are not redefined. You can create your own lists, yet, or
@@ -521,17 +941,19 @@ even redefine the existing ones.
\section{Three patterns}
Three list layouts could be considered very
-frequent. Let us apply the parameters above to define them.
+frequent. Let us apply the parameters above to define them. (Below
+are samples.)
The first pattern aligns the label with the surrounding
-\verb|\parindent| while the item body is indented depending
-on the label and a fixed \verb|labelsep|:
+|\parindent| while the item body is indented depending
+on the label and a fixed |labelsep|:
\begin{verbatim}
labelindent=\parindent,
leftmargin=*
\end{verbatim}
-A fairly frequent variant is when the label is aligned with
-the surrounding text:
+A fairly frequent variant is aligning the label with the
+surrounding text (rememeber |labelindent| is |0pt| by
+default):
\begin{verbatim}
leftmargin=*
\end{verbatim}
@@ -544,55 +966,56 @@ set with
\end{verbatim}
The second pattern aligns the item body with the surrounding
-\verb|\parindent|. In this case:
+|\parindent|. In this case:
\begin{verbatim}
leftmargin=\parindent
\end{verbatim}
-A third pattern would be to align the label with \verb|\parindent|
-and the item body with \verb|2\parindent|:
+A third pattern would be to align the label with |\parindent|
+and the item body with |2\parindent|:
\begin{verbatim}
labelindent=\parindent,
leftmargin=2\parindent,
itemsep=*
\end{verbatim}
Again, a variant would be to align the label with the surrounding
-text and the itembody with \verb|\parindent|:
+text and the itembody with |\parindent|:
\begin{verbatim}
leftmargin=\parindent,
itemsep=*
\end{verbatim}
-Note here \verb|\parindent| means the global value applied
+Note here |\parindent| means the global value applied
to normal paragraphs.
\section{The trivlist issue}
-\LaTeX{} uses a simplified version of \verb|list| named
-\verb|trivlist| to set displayed material, like \verb|center|,
-\verb|quote|, etc., even if conceptually they are not lists.
-Unfortunately, \verb|trivlist| uses the current list settings, which
-has the odd side effect that changing the vertical spacing of lists
-also changes sometimes the spacing in these environments.
+\LaTeX{} uses a simplified version of |list| named |trivlist| to set
+displayed material, like |center|, |verbatim|, \verb|tabbing|,
+\verb|theorem|, etc., even if conceptually they are not lists.
+Unfortunately, |trivlist| uses the current list settings, which has
+the odd side effect that changing the vertical spacing of lists also
+changes sometimes the spacing in these environments.
-This package modifies \verb|trivlist| so that the default settings for
-the current level (ie, those set by the corresponding \verb|clo|
+This package modifies |trivlist| so that the default settings for
+the current level (ie, those set by the corresponding |clo|
files) are set again. In standard \LaTeX{} that is usually redundand,
but if we want to fine tune lists, not resetting the default values
-could be a real issue (particularly if you use the \verb|nolistsep|
+could be a real issue (particularly if you use the |nolistsep|
option).
-A minimal control of vertical spacing has been made possible with
+A minimal control of vertical spacing has been made possible
+with\footnote{\verb|\string\setdisplayed| is deprecated.}
\begin{itemize}
-\item \verb|\setdisplayed[level]{format}|
+\item |\setlist[trivlist,<level>]{<keys/values>}|
\end{itemize}
-but \verb|trivlist| itself, which is not used directly very
+but |trivlist| itself, which is not used directly very
often, does not accept an optional argument. This feature
-is not intended as a full-fledge \verb|trivlist| formatter.
+is not intended as a full-fledge |trivlist| formatter.
-If for some reason you do not want to change \verb|trivlist|
+If for some reason you do not want to change |trivlist|
and preserve the original definition, you can use the
-package option \verb|ignoredisplayed|.
+package option |ignoredisplayed|.
\section{Samples}
@@ -603,15 +1026,19 @@ document again.
\else
-In these samples we set \verb|\setlist{noitemsep}|
+In these samples we set |\setlist{noitemsep}|
\setlist{noitemsep}
\small
-\vskip6pt
-\goodbreak
-\hrule
-\vskip6pt
+\newcommand{\newsample}{\vskip6pt\goodbreak\hrule height 1pt\vskip6pt}
+\newcommand{\samplesep}{\vskip6pt\goodbreak\hrule\vskip6pt}
+\newbox\vsep
+\setbox\vsep\hbox{\vrule height 2ex depth 16ex width 1pt}
+\dp\vsep0pt
+\newcommand\showsep{\leavevmode\llap{\copy\vsep}}
+
+\newsample
\begin{verbatim}
En un lugar de la Mancha, de cuyo nombre no quiero acordarme,
@@ -626,7 +1053,11 @@ Una olla de algo m\'{a}s vaca que carnero, salpic\'{o}n las m\'{a}s
noches, duelos y quebrantos los s\'{a}bados...
\end{verbatim}
-En un lugar de la Mancha, de cuyo nombre no quiero acordarme,
+The rule shows \verb|labelindent|.
+
+\samplesep
+
+\showsep En un lugar de la Mancha, de cuyo nombre no quiero acordarme,
no ha mucho tiempo que viv\'{\i}a un hidalgo de los de
\begin{enumerate}[labelindent=\parindent,leftmargin=*]
\item lanza en astillero,
@@ -637,15 +1068,15 @@ no ha mucho tiempo que viv\'{\i}a un hidalgo de los de
Una olla de algo m\'{a}s vaca que carnero, salpic\'{o}n las m\'{a}s
noches, duelos y quebrantos los s\'{a}bados...
+\newsample
-\vskip6pt
-\goodbreak
-\hrule
-\vskip6pt
+With |\begin{enumerate}[leftmargin=*] % labelindent=0pt by default|.
-With \verb|\begin{enumerate}[leftmargin=*]|
+The rule shows \verb|labelindent|.
-En un lugar de la Mancha, de cuyo nombre no quiero acordarme,
+\samplesep
+
+\noindent\showsep\hskip\parindent En un lugar de la Mancha, de cuyo nombre no quiero acordarme,
no ha mucho tiempo que viv\'{\i}a un hidalgo de los de
\begin{enumerate}[leftmargin=*]
\item lanza en astillero,
@@ -656,14 +1087,15 @@ no ha mucho tiempo que viv\'{\i}a un hidalgo de los de
Una olla de algo m\'{a}s vaca que carnero, salpic\'{o}n las m\'{a}s
noches, duelos y quebrantos los s\'{a}bados...
-\vskip6pt
-\goodbreak
-\hrule
-\vskip6pt
+\newsample
-With \verb|\begin{enumerate}[leftmargin=\parindent]|
+With |\begin{enumerate}[leftmargin=\parindent]|.
-En un lugar de la Mancha, de cuyo nombre no quiero acordarme,
+The rule shows \verb|leftmargin|.
+
+\samplesep
+
+\showsep En un lugar de la Mancha, de cuyo nombre no quiero acordarme,
no ha mucho tiempo que viv\'{\i}a un hidalgo de los de
\begin{enumerate}[leftmargin=\parindent]
\item lanza en astillero,
@@ -674,18 +1106,17 @@ no ha mucho tiempo que viv\'{\i}a un hidalgo de los de
Una olla de algo m\'{a}s vaca que carnero, salpic\'{o}n las m\'{a}s
noches, duelos y quebrantos los s\'{a}bados...
-\vskip6pt
-\goodbreak
-\hrule
-\vskip6pt
+\newsample
-With
-\begin{verbatim}
-\begin{enumerate}[labelindent=\parindent, leftmargin=*,
- label=\Roman*., widest=IV, align=left]
-\end{verbatim}
+With |\begin{enumerate}[labelindent=\parindent,|\allowbreak
+| leftmargin=*,|\allowbreak| label=\Roman*.,|\allowbreak
+| widest=IV,|\allowbreak| align=left]|.
-En un lugar de la Mancha, de cuyo nombre no quiero acordarme,
+The rule shows \verb|labelindent|.
+
+\samplesep
+
+\showsep En un lugar de la Mancha, de cuyo nombre no quiero acordarme,
no ha mucho tiempo que viv\'{\i}a un hidalgo de los de
\begin{enumerate}[labelindent=\parindent, leftmargin=*,
label=\Roman*., widest=IV, align=left]
@@ -697,14 +1128,13 @@ no ha mucho tiempo que viv\'{\i}a un hidalgo de los de
Una olla de algo m\'{a}s vaca que carnero, salpic\'{o}n las m\'{a}s
noches, duelos y quebrantos los s\'{a}bados...
-\vskip6pt
-\goodbreak
-\hrule
-\vskip6pt
+\newsample
-With \verb|\begin{enumerate}[label=\fbox{\arabic*}]|. A reference to
+With |\begin{enumerate}[label=\fbox{\arabic*}]|. A reference to
the first item is \ref{i:first}
+\samplesep
+
En un lugar de la Mancha, de cuyo nombre no quiero acordarme,
no ha mucho tiempo que viv\'{\i}a un hidalgo de los de
\begin{enumerate}[label=\fbox{\arabic*}]
@@ -716,26 +1146,25 @@ no ha mucho tiempo que viv\'{\i}a un hidalgo de los de
Una olla de algo m\'{a}s vaca que carnero, salpic\'{o}n las m\'{a}s
noches, duelos y quebrantos los s\'{a}bados...
-\vskip6pt
-\goodbreak
-\hrule
-\vskip6pt
+\newsample
With nested lists.
+\samplesep
+
\begin{verbatim}
En un lugar de la Mancha, de cuyo nombre no quiero acordarme,
no ha mucho tiempo que viv\'{\i}a un hidalgo de los de
-\begin{enumerate}[label=\alph*), labelindent=\parindent,
+\begin{enumerate}[label=(\alph*), labelindent=\parindent,
leftmargin=*, start=12]
- \item lanza en astillero,
- \begin{enumerate}[label=\alph{enumi}.\roman*), leftmargin=*, start=8]
- \item adarna antigua,
- \end{enumerate}
- \item roc\'{\i}n flaco, y
- \begin{enumerate}[label=\alph{enumi}.\roman*), leftmargin=*, resume]
- \item galgo corredor.
- \end{enumerate}
+\item lanza en astillero,
+\begin{enumerate}[label=(\alph{enumi}.\roman*), leftmargin=*, start=7]
+\item adarna antigua,
+\end{enumerate}
+\item roc\'{\i}n flaco, y
+\begin{enumerate}[label=(\alph{enumi}.\roman*), leftmargin=*, resume]
+\item galgo corredor.
+\end{enumerate}
\end{enumerate}
Una olla de algo m\'{a}s vaca que carnero, salpic\'{o}n las m\'{a}s
noches, duelos y quebrantos los s\'{a}bados...
@@ -743,25 +1172,21 @@ noches, duelos y quebrantos los s\'{a}bados...
En un lugar de la Mancha, de cuyo nombre no quiero acordarme,
no ha mucho tiempo que viv\'{\i}a un hidalgo de los de
-\begin{enumerate}[label=\alph*), labelindent=\parindent,
+\begin{enumerate}[label=(\alph*), labelindent=\parindent,
leftmargin=*, start=12]
\item lanza en astillero,
-\begin{enumerate}[label=\alph{enumi}.\roman*), leftmargin=*, start=7]
+\begin{enumerate}[label=(\alph{enumi}.\roman*), leftmargin=*, start=7]
\item adarna antigua,
\end{enumerate}
\item roc\'{\i}n flaco, y
-\begin{enumerate}[label=\alph{enumi}.\roman*), leftmargin=*, resume]
+\begin{enumerate}[label=(\alph{enumi}.\roman*), leftmargin=*, resume]
\item galgo corredor.
\end{enumerate}
\end{enumerate}
Una olla de algo m\'{a}s vaca que carnero, salpic\'{o}n las m\'{a}s
noches, duelos y quebrantos los s\'{a}bados...
-\vskip6pt
-\goodbreak
-\hrule
-\vskip6pt
-
+\newsample
\begin{verbatim}
En un lugar de la Mancha, de cuyo nombre no quiero acordarme,
@@ -777,6 +1202,8 @@ Una olla de algo m\'{a}s vaca que carnero, salpic\'{o}n las m\'{a}s
noches, duelos y quebrantos los s\'{a}bados...
\end{verbatim}
+\samplesep
+
En un lugar de la Mancha, de cuyo nombre no quiero acordarme,
no ha mucho tiempo que viv\'{\i}a un hidalgo de los de
\begin{description}[font=\sffamily\bfseries, leftmargin=3cm,
@@ -789,12 +1216,11 @@ no ha mucho tiempo que viv\'{\i}a un hidalgo de los de
Una olla de algo m\'{a}s vaca que carnero, salpic\'{o}n las m\'{a}s
noches, duelos y quebrantos los s\'{a}bados...
-\vskip6pt
-\goodbreak
-\hrule
-\vskip6pt
+\newsample
+
+Same, but with |sameline|.
-Same, but with \verb|sameline|.
+\samplesep
En un lugar de la Mancha, de cuyo nombre no quiero acordarme,
no ha mucho tiempo que viv\'{\i}a un hidalgo de los de
@@ -808,14 +1234,13 @@ no ha mucho tiempo que viv\'{\i}a un hidalgo de los de
Una olla de algo m\'{a}s vaca que carnero, salpic\'{o}n las m\'{a}s
noches, duelos y quebrantos los s\'{a}bados...
-\vskip6pt
-\goodbreak
-\hrule
-\vskip6pt
+\newsample
-Same, but with \verb|multiline|. Note the text overlaps if
+Same, but with |multiline|. Note the text overlaps if
the item body is too short.
+\samplesep
+
En un lugar de la Mancha, de cuyo nombre no quiero acordarme,
no ha mucho tiempo que viv\'{\i}a un hidalgo de los de
\begin{description}[font=\sffamily\bfseries, leftmargin=3cm,
@@ -823,7 +1248,7 @@ no ha mucho tiempo que viv\'{\i}a un hidalgo de los de
\item[Lo primero que ten\'{\i}a el Quijote] lanza en astillero,
\item[Lo segundo] adarna antigua,
\item[Lo tercero] roc\'{\i}n flaco, y
-\item[Y por \'{u}ltimo, lo cuarto] galgo corredor.
+\item[Y por \'{u}ltimo, lo cuar] galgo corredor.
\end{description}
Una olla de algo m\'{a}s vaca que carnero, salpic\'{o}n las m\'{a}s
noches, duelos y quebrantos los s\'{a}bados...
@@ -836,14 +1261,15 @@ noches, duelos y quebrantos los s\'{a}bados...
\subsection{\LaTeX{} lists}
-As it is well known, \LaTeX{} predefines three lists: enumerate,
-itemize and description. This is a very frequent classification which
-one can also find in, say, HTML. However, there is a more general
-model based in three fields---namely, label, title, and body---, so
-that enumerate and itemize has label (numbered and unnumbered) but
-no title, while description has title but no label. In this model,
-one can have a description with entries marked with labels, as for
-example:
+As it is well known, \LaTeX{} predefines three lists:
+\texttt{enumerate}, \texttt{itemize} and \texttt{description}. This
+is a very frequent classification which can also be found in, say,
+HTML. However, there is a more general model based in three
+fields---namely, label, title, and body---, so that enumerate and
+itemize has label (numbered and unnumbered) but no title, while
+description has title but no label. In this model, one can have a
+description with entries marked with labels, as for example (of
+course, this simple solution is far from satistactory):
\begin{verbatim}
\newcommand\litem[1]{\item{\bfseries #1,\enspace}}
\begin{itemize}[label=\textbullet]
@@ -871,20 +1297,96 @@ no ha mucho tiempo que viv\'{\i}a un hidalgo de los de
\hrule
\vskip6pt
-This format in not infrequent at all and I thing any future
-development of this package has to take it into account.
+This format in not infrequent at all and a tool for defining them is
+on the way and at a very advanced stage. It has not been include in
+version 3.0 because I'm not sure if the proper place is this package
+or \textsf{titlesec} and it is not stable enough yet.
\subsection{Known issues}
-Description styles other than the default one don't group
-labels if they are nested.
+\begin{itemize}
+
+\item
+List resuming is based on environment names, and when a
+|\newenvironment| contains a list you may want to use |\begin| and
+|\end|. Using the corresponding commands, however, is not an error,
+but it is your responsability to make sure the result is correct.
+
+\item
+It seems there is no way to catch a misspelled name in |\setlist|
+and a meaningless error ``Missing number, treated as zero'' is raised.
+
+\item The behaviour of mixed boxed labels (including enumerate and
+itemize) and unboxed labels is not well-defined. Similarly, resuming
+a series and a list at the same time is allowed, too, but again its
+behaviour is not well-defined.
+
+\end{itemize}
+
+\subsection{What's new in 3.0}
+
+\begin{itemize}
+\item Inline lists, with keys to set how items are joined (ie, the
+punctuation between items). Two modes are provided: \verb|boxed| and
+\verb|unboxed|.
+
+\item \verb|\setlist| is \textsf{calc}-savvy (eg, for use in loops),
+and you can set diferent lists and levels at once. \item All lengths
+related to labels can take the value \verb|*| (and not only
+\verb|labelsep| and \verb|leftmargin|). Its behaviour has been made
+consistent and there is new value \verb|!| which does not compute the
+widest label.
+
+\item With \verb|\restartlist{<list-name>}|, list counters can be restarted (in
+case you are using \verb|resume|).
+
+\item \verb|resume*| can be combined with other keys.
+
+\item Lists can be gathered globally using series, so that they are
+considered a single list. To start a series just use
+|series=<series-name>| and then resume it with |resume=<series-name>| or
+|resume*=<series-name>|.
+
+\item The ``experimental'' \verb|fullwidth| has been replaced by a new key
+\verb|wide|.
+
+\item|\SetLabelAlign| defines new align values.
-You must use the \LaTeX{} syntax for environments, with \verb|\begin|
-and \verb|\end|.
+\item You can define ``abstract'' values (eg, \verb|label=numeric|) and
+new keys.
+\end{itemize}
+
+\begin{itemize}
+\item (3.2) \verb|start| and \verb|widest*| are \textsf{calc}-savvy.
+\item (3.2) \verb|\value| can be used with \verb|widest*|.
+\item (3.2) Some internal restrictions in \verb|\arabic| and the like
+has been removed. It is more flexible at the cost of having a more
+``relaxed'' error checking.
+\end{itemize}
+\subsection{Bug fixes}
+
+\begin{itemize}
+\item Star values (eg, \verb|leftmargin=*|) could not be overriden
+and new values were ignored.
+\item \verb|nolistsep| as the first of several keys was not always
+recognized and therefore treated like a short label
+(i.e., \verb|nol\roman*stsep|).
+\item \verb|labelwidth| did not always work (when there was a prior
+\verb|widest| and \verb|*|)
+\item With \verb|align=right| the label and the following text could
+overlap.
+\item \verb|description| did not get the correct list level.
+\item At some point (2.x?) \verb|\value*| stopped working.
+\item (3.1) Unfortunately, \textsf{xkeyval} ``kills''
+\textsf{keyval}, so the lattest has been replicated in
+\textsf{enumitem}.
+\item (3.3) Fixes a serious bug -- with \verb|*| neither
+\verb|itemize| nor \verb|description| worked.
+\end{itemize}
\subsection{Acknowledgements}
I wish to thank particularly the comments and suggestions from Lars
-Madsen, which has found some bugs, too.
+Madsen, who has found some bugs, too.
\end{document}
generated by cgit v1.2.3 (git 2.39.1) at 2024-12-23 20:29:12 +0000