enumitem 3.3 (14jul11)

git-svn-id: svn://tug.org/texlive/trunk@23242 c570f23f-e606-0410-a88d-b1316a301751

1 files changed, 865 insertions, 363 deletions

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}