# source:doc/LaTeXmacros/enumitem/enumitem.tex@71b5d4d3

Last change on this file since 71b5d4d3 was 9724df0, checked in by Peter A. Buhr <pabuhr@…>, 6 years ago

update latex macros, and user and refrat manuals

• Property mode set to 100644
File size: 49.5 KB
Line
1% +--------------------------------------------------+
2% | Typeset this file to document enumitem.sty       |
3% +--------------------------------------------------+
4%
5% Copyright (c) 2003-2011 by Javier Bezos.
7%
8% This file is part of the enumitem distribution release 3.5.2
9% ------------------------------------------------------------
10%
11% It may be distributed and/or modified under the
12% conditions of the LaTeX Project Public License, either version 1.3
15%   http://www.latex-project.org/lppl.txt
16% and version 1.3 or later is part of all distributions of LaTeX
17% version 2003/12/01 or later.
18%
19% This work has the LPPL maintenance status "maintained".
20%
21% The Current Maintainer of this work is Javier Bezos.
22
23\documentclass[a4paper]{ltxguide}
24
25\makeatletter
26\newenvironment{desc}
27  {\if@nobreak
28     \vskip-\lastskip
29     \vspace*{-2.5ex}%
30   \fi
31   \decl}
32  {\enddecl}
33\makeatother
34
35\newcommand\3{\unskip\enspace\fbox{\fontsize{4}{4}\selectfont NEW 3.0}}
36
37\usepackage{hyperref}
38
39%\usepackage{pslatex}
40
41\title{Customizing lists\\with the\\\textsf{enumitem} package}
42
43\author{Javier Bezos\footnote{For bug reports, comments and
44suggestions go to \href{http://www.tex-tipografia.com/enumitem.html}%
45{\texttt{http://www.tex-tipografia.com/enumitem.html}}.
46English is not my strong point, so contact me when you
47find mistakes in the manual. Other packages by the same author:
48\textsf{gloss} (with Jos\'e Luis D\'{\i}az), \textsf{accents,
49tensind, esindex, dotlessi, titlesec, titletoc}.}}
50
51\date{Version 3.5.2\\2011-09-28}
52
53\IfFileExists{enumitem.sty}{\usepackage{enumitem}}{}
54
59
60\raggedright
61\parindent1.8em
62\parskip0pt
63
64\begin{document}
65
66\maketitle
67
68\section{Introduction}
69
70When I began to use \LaTeX{} several year ago, two particular points
71annoyed me because I found customizing them was very complicated
72---headlines/footlines and lists.  A new way to redefine the former is
73accomplished in my own \textsf{titlesec} package, but none was
74available to customize the latter except:
75\begin{itemize}
76\item \textsf{enumerate}, which just allows to change the label and
77it does it pretty well.
78
79\item \textsf{mdwlist}, which only provides some vaguely useful
80list-related commands and environments,'' as its manual states,
81and not a coherent way of handling lists.
82
83\item \textsf{paralist}, which provides lists within a paragraph (the
84original purpose of this package), a few other hard-wired
85specific changes and the optional argument of \textsf{enumerate}.
86\end{itemize}
87
88One of the main drawbacks of the standard |list| is its weird
89parameters, whose meaning is not always obvious.  In order to provide
90a cleaner interface two approaches were possible: either defining new
91lists, or introducing a new syntax making the standard lists easier to
92customize.  For marks I took the first approach in titlesec, just
93because I did not manage to find a satisfactory solution with the
94\LaTeX{} internal macros, but since lists are in some sense more
95complete'' than sections and marks, I have taken here the second
96approach.
97
98In the interface a sort of inheritance'' is used. You can
99set globally the behaviour of lists and then override several
100parameters of, say, enumerate and then in turn override
101a few paremeters of a particular instance. The values will
102be searched in the hierarchy.
103
104\section{The package}
105
106This package is intended to ease customizing the three
107basic list environments: |enumerate|, |itemize| and
108|description|. It extends their syntax to allow
109an optional argument where a set of parameters in the
110form |key=value| are available:
111\begin{itemize}
112\item
113Vertical spacing:
114\begin{itemize}
115\item |topsep|
116\item |partopsep|
117\item |parsep|
118\item |itemsep|
119\end{itemize}
120\item
121Horizontal spacing:
122\begin{itemize}
123\item |leftmargin|
124\item |rightmargin|
125\item |listparindent|
126\item |labelwidth|
127\item |labelsep|
128\item |itemindent|
129\end{itemize}
130\end{itemize}
131
132For example:
133\begin{verbatim}
134\begin{itemize}[itemsep=1ex,leftmargin=1cm]
135\end{verbatim}
136
137The keys above are equivalent to the well known list parameters---see a
138\LaTeX{} manual for a description of them.  Next sections explains the
139extensions provided by |enumitem|.
140
141\section{Keys}
142
143This section describes the keys in displayed lists. Most of them are
144available in inline lists, where further keys are available (see
145\ref{s.inline}).
146
147\subsection{Label and cross references format}
148
149\begin{desc}
150|label=<commands>|
151\end{desc}
152
153Sets the label to be used in the current level.
154A set of starred versions of |\alph|, |\Alph|,
155|\arabic|, |\roman| and |\Roman|, without argument
156stand for the current counter in |enumerate|.\footnote{Actually,
157the asterisk is currently the argument but things may change.
158Consider them as starred variants and follow the corresponding
159syntax.} Thus
160\begin{verbatim}
161\begin{enumerate}[label=\emph{\alph*})]
162\end{verbatim}
163prints \textit{a}), \textit{b}), and so on (this is a
164standard style in Spanish, and formerly used by Chicago, too).
165
166It works with |\value|, too (provided the widest label is not to be
167computed or \verb|widest*| is used, see below).  A fancier example
168(which looks ugly, but it is intended only to illustrate what is
169possible; requires \textsf{color} and \textsf{pifont}):
170\begin{verbatim}
171\begin{enumerate}[label=\protect\fcolorbox{blue}{yellow}{\protect\ding{\value*}},
172                  start=172]
173\end{verbatim}
174
175The value of |label| is a moving argument, and fragile commands must
176be protected \textit{except} the counters.  Because of that, use of
177\verb|\value| is somewhat tricky, because \verb|\the| or \verb|\ifnum|
178expects an actual value, which is not the case when \verb|label| is
179being processed to replace internally the \verb|*| by the form with
180the counter argument.  The best solution is usually encapsulating the
181logic inside a new counter'' with the help of
183convoluted.  A better way to accomplish this is on the way.}
184
185If you prefer setting labels like the \textsf{enumerate} package, use
186short labels'' (see section \ref{s.short}).
187
188\begin{desc}
189|label*=<commands>|
190\end{desc}
191
192Like |label| but its value is appended to the parent label.  For example, the follollowing defines a |legal| list (1.,
1931.1., 1.1.1., and so on):
194\begin{verbatim}
195\newlist{legal}{enumerate}{10}
196\setlist[legal]{label*=\arabic*.}
197\end{verbatim}
198
199\begin{desc}
200|ref=<commands>|
201\end{desc}
202
203By default, |label| sets also the form of cross references and
204|\the...| (overriding the settings in previous hierarchical
205levels), but you can define a different format with this key.  For
206example, to remove the right parethesis:
207\begin{verbatim}
208\begin{enumerate}[label=\emph{\alph*}),ref=\emph{\alph*}]
209\end{verbatim}
210In both |label| and |ref|, the counters can be
211used as usual:
212\begin{verbatim}
213\begin{enumerate}[label=\theenumi.\arabic*.]
214\end{verbatim}
215or
216\begin{verbatim}
217\begin{enumerate}[label=\arabic{enumi}.\arabic*.]
218\end{verbatim}
219(provided the current level is the second one).
220
221Note the |label|s are \textit{not} accumulated to form
222the reference. If you want, say, something like 1.\textit{a}
223from 1) as first level and \textit{a}) as second level,
224you must set it with |ref|. You may use
225|\ref{level1}.\ref{level2}| with appropiate |ref|
226settings, but as Robin Fairbairns points out in the \TeX{} FAQ
227\begin{quote}
228\dots{} [that] would be both tedious and error-prone. What is more, it
229would be undesirable, since you would be constructing a visual
230representation which is inflexible (you could not change all the
231references to elements of a list at one fell swoop).
232\end{quote}
233This is sensible and I recommend to follow the advice, but sometimes
234you might want something like:
235\begin{verbatim}
236... subitem \ref{level2} of item \ref{level1} ...
237\end{verbatim}
238
239The value of |ref| is a moving argument, and fragile
240commands must be protected \textit{except} the counters.
241
242\begin{desc}
244\end{desc}
245
246Sets the label font.  Useful when the label is changed with the
247optional argument of |\item| and in \texttt{description}.  The last
248command in |<commands>| can take an argument with the item label.  In
249\texttt{description} class setting are in force, so you may want begin
250with \verb|\normalfont|. A synonymous is \texttt{format}.
251
252\begin{desc}
254\end{desc}
255
256How the label is aligned (with relation to the label box edges).
257Three values are possible: |left|, the default |right| and
258\verb|parleft| (a parbox of width \verb|\labelwidth| with flush left
259text).  The parameters controlling the label spacing should be
260properly set, either by hand or more conveniently with the |*|
261settings (see below):
262\begin{verbatim}
263\begin{enumerate}[label=\Roman*., align=left, leftmargin=*]
264\end{verbatim}
265(When the label box is supposed to have its natural width, use
266|left|.)
267
268\begin{desc}
269|\SetLabelAlign{<value>}{<commands>}|\3
270\end{desc}
271
272New align types can be defined (or the existing ones redefined) with
273|\SetLabelAlign|; the predefined values are equivalent
274to:\footnote{Prior to version 3.0 the left alignments was incorrectly
275defined and the label and the text could overlap.}
276\begin{verbatim}
277\SetLabelAlign{right}{\hss\llap{#1}}
278\SetLabelAlign{left}{#1\hfil}
279\SetLabelAlign{parleft}{\strut\smash{\parbox[t]\labelwidth{\raggedright##1}}}
280\end{verbatim}
281
282If the last thing in the definition is a skip (typically \verb|\hfil|), it is
283removed sometimes by description. If for some reason you want to avoid
284this, just add \verb|\null| at the end.
285
286Although primarily intended for the alignment, this commands has other
287uses (as in the provided \verb|parleft|).  For example, with the
288following all labels with |align=right| are set as superscripts:
289\begin{verbatim}
290\SetLabelAlign{right}{\hss\llap{\textsuperscript{#1}}}
291\end{verbatim}
292(A new name is also possible, of course.)
293
294If you want the internal settings for \texttt{align} and \texttt{font}
295be ignored, you can override the \textsf{enumitem} definition of
296\verb|\makelabel| in \texttt{before}:
297\begin{verbatim}
298\begin{description}[before={\renewcommand\makelabel[1]{\ref{##1}}}]
299\end{verbatim}
300(Alternatively, define a macro and use \verb|\let|.)
301
302\subsection{Horizontal spacing of labels}
303
304\begin{desc}
305|labelindent=<length>|\\
306\verb|\labelindent|
307\end{desc}
308
309This  parameter is added in \textsf{enumitem} for the blank space from
310the margin of the enclosing list/text to the left edge of the label box.  This
311means there is a redundancy because one of the parameters depends on
312the others, i.e., it has to be computed from the other values, as
313described below.  There is a new counter length |\labelindent| which
314defaults to 0 pt. The five parameteres are related in the following
315way:
316$317\verb|\leftmargin|+\verb|\itemindent| = 318\verb|\labelindent|+\verb|\labelwidth|+\verb|\labelsep| 319$
320
321\begin{desc}
324\end{desc}
325
326Sets which value is to be computed from the others. This is done
327after \textit{all} keys has been read. Explicit values are not lost, and
328so with the following hierarchical settings:
329\begin{verbatim}
330leftmargin=2em
331labelindent=1em,leftmargin=!
332labelindent=!
333\end{verbatim}
334|leftmargin| is again 2em and |labelindent| is the computed parameter.
335The default is |labelindent=!|, but note some keys sets another value
336(\verb|wide| and description \verb|style|s).
337
338With |align=right| (the default), |labelindent=!| and
339|labelwidth=!| behave similarly in practice.
340
341\begin{desc}
344\end{desc}
345
346Like before, but |labelwidth| is set to the width of the current
347label, using the default value of \textit{0} in |\arabic*|,
348\textit{viii} in |\roman*|, \textit{m} in |\alph*| and
349similarly in uppercase forms (these values can be changed with
350|widest|, see below).  Examples are:
351\begin{verbatim}
352\begin{itemize}[label=\textbullet, leftmargin=*]
353\begin{enumerate}[label=\roman*), leftmargin=*, widest=iii]
354\begin{itemize}[label=\textbullet,
355                leftmargin=2pc, labelsep=*]
356\begin{enumerate}[label=\arabic*., leftmargin=2\parindent,
357                  labelindent=\parindent, labelsep=*]
358\end{verbatim}
359
360The most useful are |labelsep=*| and |leftmargin=*|.
361With the former the item body begins at a fixed place (namely,
362|leftmargin|), while with the latter begins at a variable place
363depending on the label (but always the same within a list, of course).
364Most of times, what you would want is |leftmargin=*|.
365
366Unfortunately, \LaTeX{} does not define a default |labelsep| to
367be applied to all lists---simply the current value is used.  With
368\textsf{enumitem} you can set default values for every list, as
369described below, and so, if you want to make sure |labelsep| is
370under your control, all you need is something like:
371\begin{verbatim}
372\setlist{itemsep=.5em}
373\end{verbatim}
374
375|labelwidth=*| and |labelwidth=!| are synonymous.
376
377\begin{desc}
379\end{desc}
380
381To be used in conjunction with the \texttt{*}-values, if
382desired.  It overrides the default value for the widest
383printed counter.  Sometimes, if lists are not very long, a value of
384|a| for |\alph| is more sensible than the default |m|:
385\begin{verbatim}
386\begin{enumerate}[leftmargin=*,widest=a] % Assume standard 2nd level
387\end{verbatim}
388With no value, the default is restored. With |widest*|, the string is
389built using |<integer>| as the value of the counter (e.g., with
390\verb|\roman|,
391\verb|widest=viii| and \verb|widest*=8| are the same).
392
393Since |\value| does not return a string but a number,
394|widest| and the \verb|*| values cannot be used with it.
395However, with \verb|widest*|, being a number, it is allowed.
396
397\subsection{More on horizontal spacing}
398
399Since |\parindent| is not used as such inside lists, but instead
400is set internally to either |\itemindent| or |\listparindent|,
401when used as the value of a parameter \textsf{enumitem} returns the
402global value, i.  e., the value it has outside the outermost list.
403
404The horizontal space in the left margin of the current level is
405distributed in the following way:\footnote{Admittedly, these figures
406are not exactly the clearest possible, and I intend to improve them in
407a future release}
408\begin{center}
409\begin{tabular}{cc}
410\fbox{\fbox{\strut \texttt{labelindent}}
411  \fbox{\strut \texttt{labelwidth}}
412  \fbox{\strut \texttt{labelsep} $-$ \texttt{itemintent}}}
413&
414\fbox{\strut\texttt{itemindent}}\\
415\texttt{leftmargin}
416\end{tabular}
417\end{center}
418
419\begin{desc}
420\verb|labelsep*=<length>|\3
421\end{desc}
422
423Remember |labelsep| spans part of |leftmargin| and
424|itemindent| if the latter is not zero.  This is often somewhat
425confusing, so a new key is provided---with \texttt{labelsep*} the
426value is reckoned from the left margin (it just sets |\labelsep|
427and then adds |\itemindent| to it, but in addition later changes to
428|itemindent| are taken into account):
429\begin{center}
430\begin{tabular}{cc}
431\fbox{\fbox{\strut \texttt{labelindent}}
432  \fbox{\strut \texttt{labelwidth}}
433  \fbox{\strut \texttt{labelsep*}}}
434&
435\fbox{\strut\texttt{itemindent}}\\
436\texttt{leftmargin}
437\end{tabular}
438\end{center}
439
440\begin{desc}
441|labelindent*=<length>|\3
442\end{desc}
443
444Like |labelindent|, but it is reckoned from the left margin in
445the current list and not from that in the enclosing list/text.
446
447\subsection{Numbering, stopping, and resuming}
448
449\begin{desc}
450|start=<integer>|
451\end{desc}
452Sets the number of the first item.
453
454\begin{desc}
455|resume|
456\end{desc}
457
458The counter continues from the previous |enumerate|,
459instead of being reset to 1.
460\begin{verbatim}
461\begin{enumerate}
462\item First item.
463\item Second item.
464\end{enumerate}
465Text.
466\begin{enumerate}[resume]
467\item Third item
468\end{enumerate}
469\end{verbatim}
470
471This is done locally. If you want global resuming, see next section on series.
472
473\begin{desc}
474|resume*|
475\end{desc}
476
477Like |resume| but the options from the previous list are used,
478too.  This option must be restricted to the optional argument in a
479environment (this is the only place where it makes sense).  It should
480be used sparingly---if you are using it often, then very likely you
481want to define a new list (see \ref{s.clone}).  Further keys are allowed, and
482in this case the saved options are overriden by those in the current
483list (i.e., the position of \texttt{resume*} does not matters).  For
484example:
485\begin{verbatim}
486\begin{enumerate}[resume*,start=1] % or [start=1,resume*]
487\end{verbatim}
488uses the keys in the previuos \texttt{enumerate}, but restarts the
489counter.  If there is a series of a certain list with
490\texttt{resume*}, options are taken from the list previous to the
491first one, except for \texttt{start}.
492
493\subsection{Series}
494
495\begin{desc}
496|series=<series-name>|\3\\
499\end{desc}
500
501A new method (3.0) of continuing lists is by means of the key
502\texttt{series}, so that they behave like a unit.  A list with key
503\texttt{series} is considered the starting list and its settings are
504stored \textit{globally}, so that they can be used later with
505\texttt{resume}/\texttt{resume*}.  All these keys take a value with
506the series name (which must be different from existing keys):
507\begin{itemize}
508\item |resume=<series-name>| just continue numbering items in the
509series,
510\item |resume*=<series>| also applies the settings of the
511starting list,
512\item |<series>|, i.e., the series name used as a key, is an
513alternative to |resume*=<series>|.
514\end{itemize}
515For example:
516\begin{verbatim}
517\begin{enumerate}[label=\arabic*(a),leftmargin=1cm,series=lafter]
518\item A
519\item B
520\end{enumerate}
521\end{verbatim}
522You get: 1(a)  2(a). You can continue with:
523\begin{verbatim}
524\begin{enumerate}[label=\arabic*(b),resume*=lafter]
525                 % or [label=\arabic*(b),lafter]
526\item A
527\item B
528\end{enumerate}
529\end{verbatim}
530You get: 3(b)  4(b). (But you can use |start=1|, if you like.)
531
532Note you can add further arguments, which are executed after those
533saved at the starting list and therefore take precedence over them --
534in particular, |resume*| itself takes precedence over a
535|start| (e.g., |start=1|) in the the starting list.
536
537Every time a series is started, several commands are defined
538internally, so to avoid wasting resources and use the same name for
539non-overlapping series.
540
541
542\subsection{Penalties}
543
544\begin{desc}
547\end{desc}
548
549Set the penalty at the beginning of a list, between items and at the
551\TeX{} manual about how penalties control page breaks.  Unlike other
552parameters, when a list starts their values are not reset to the
553default, thus they apply to the child lists.
554\begin{desc}
556\end{desc}
557
558Execute code before the list starts (more precisely, in the second
559argument of the |list| environment used to define them).  The
560unstarred form sets the code to be executed, overriding any previous
561value, while the starred one adds the code to the existing one (in
562the setting hierarchy, see below, \textit{not} with relation to the
563enclosing list/text).  It can contain, say, rules and text, but this
564has not been extensively tested.  All calculations have been finished,
565and you can access and manipulate the list parameters.  For example,
566to have both margins (left and right) set to the widest label:
567\begin{verbatim}
568\setlist{leftmargin=*,before=\setlength{\rightmargin}{\leftmargin}}
569\end{verbatim}
570
571\begin{desc}
573\end{desc}
574
575Same, but just before the list ends.
576
577\subsection{Description styles}
578
579A key available in |description|.
580\begin{desc}
581|style=<name>|
582\end{desc}
583
584Sets the description \textit{style}. |<name>| can be any of the
585following:
586\begin{itemize}
587
588\item |standard|: like |description| in standard classes, although
589with other classes it could be somewhat different.  The label is
590boxed.  Sets \verb|itemindent=!|.
591
592\item |unboxed|: much like the standard |description|, but
593the label is not boxed to avoid uneven spacing and unbroken labels if
594they are long. Sets \verb|itemindent=!|.
595
596\item |nextline|: if the label does not fit in the margin, the text
597continues in the next line, otherwise it is placed in a box of width
598|\leftmargin| $-$ |\labelsep|, i.e., the item body never sticks into
599the left margin.  Sets \verb|labelwidth=!|.
600
601\item |sameline|: like |nextline| but if the label does not
602fit in the margin the text continues in the same line. Same as
603\verb|style=unboxed,labelwidth=!|.
604
605\item |multiline|: the label is placed in a parbox whose width is
606|leftmargin|, with several lines if
607necessary. Same as \verb|style=standard,align=parleft,labelwidth=!|.
608
609Three caveats: (1) mixing boxed and unboxed labels has not a
610well-defined behaviour, (2) when nesting list all combinations are
611allowed but not all make sense, and (3) nesting \verb|nextline| lists
612is not supported (it works, but its behaviour might change in the
613future, because the current one is not what one could expect).
614
615
616
617\end{itemize}
618
619
620\subsection{Compact lists}
621
622\begin{desc}
624\end{desc}
625
626The key |noitemsep| kills the space between items and paragraphs
627(i.e., |itemsep=0pt| and |parsep=0pt|), while
628|nosep| kills all vertical spacing.\footnote{The key
629\texttt{nolistsep}, now deprecated, introduced a thin stretch, which
630was not the intended behaviour.}
631
632\subsection{Wide'' lists}
633
634\begin{desc}
635\verb|wide|\3\\
636\verb|wide=<parindent>|
637\end{desc}
638
639With this convenience key, the leftmargin is null and the label is
640part of the text---in other word, the items look like ordinary
641paragraphs.\footnote{\texttt{fullwidth} is deprecated.} Here |labelsep|
642sets the separation between the label and the first word.  It is
643equivalent to
644\begin{verbatim}
645align=left, leftmargin=0pt, labelindent=\parindent,
646listparindent=\parindent, labelwidth=0pt, itemindent=!
647\end{verbatim}
648With |wide=<parindent>| you may set at once another value instead of
649|\parindent|.  Of course, these keys can be overriden after
650\verb|wide|, too; for example, remembering that with left-aligned labels
651the text is pushed if the they are wider than |labelwidth|, you
652can set |labelwidth=1.5em| for a minimal width, or instead of
653|itemindent=!| you may prefer |itemindent=*|, which sets the
654minimal width to that of widest label.  In level 2 you may prefer
655|labelindent=2\parindent|, and so on.  You may also want to
656combine it with |noitemsep| or |nolistsep|.
657
658\section{Inline lists}
659\label{s.inline}
660
661\3
662
663Inline lists are horizontal'' lists set as ordinary text inside a
664paragraph.  With this package you can create inline lists, as
665explained below, with \verb|\newlist|, which have their own labels and
666counters.  However, in most cases inline versions of standard lists,
667with the same labelling schema, will be enough -- the package option
668\verb|inline| does that.
669
670
671\begin{desc}
675\end{desc}
676
677With the package option \texttt{inline}, three environments for inline
678lists are defined: \texttt{enumerate*}, \texttt{itemize*}, and
679\texttt{description*}.  They emulate the behaviour of
680\textsf{paralist} and \textsf{shortlst} in that labels and settings
681are shared with the displayed (ie, normal'') lists \texttt{enumerate},
682\texttt{itemize} and \texttt{description}, respectively (however,
683remember resuming is based on environment names, not on list types).  This applies
684only to those created with \texttt{inline} -- inline lists created
685with |\newlist| as described below are independent and use their
686own labels and settings. Note as well \verb|inline| is not required
687if you needn't inline versions of standard lists.
688
689\begin{desc}
692\end{desc}
693
694Format is set with keys \texttt{itemjoin} (default is a space), and
695\texttt{afterlabel} (default is |\nobreakspace|, ie, |~|).
696An additional key is \texttt{itemjoin*}, which, if set, is used
697instead of \texttt{itemjoin} before the last item.  So, with
698\begin{verbatim}
699before=\unskip{: }, itemjoin={{; }}, itemjoin*={{, and }}
700\end{verbatim}
701the following punctuation between items is used:
702\begin{quote}
703Blah blah: (a) one; (b) two; (c) three, and (d) four. Blah blah
704\end{quote}
705
706\verb|itemjoin| is ignored in vertical mode (i.e., in mode unboxed
707and just after a quote, a displayed list and the like).
708
709\begin{desc}
711\end{desc}
712
713Items are boxed, so floats are lost and nested lists are not allowed
714(remember many displayed elements are defined as lists).  If using
715floats or lists inside inline lists is important, use an alternative
716mode'', which you can activate with
717\texttt{mode=unboxed} (the default is \texttt{mode=boxes}).  With it
718floats may be used freely, but misplaced |\item|s are not catched and
719\texttt{itemjoin*} is ignored (a warning is written to the log about
720this fact).
721
722\section{Global settings}
723
724Global changes, to be applied to all of these list, are also
725possible:
726\begin{desc}
727|\setlist[enumerate,<levels>]{<format>}|\\
728|\setlist[itemize,<levels>]{<format>}|\\
729|\setlist[description,<levels>]{<format>}|\\
730|\setlist[<levels>]{<format>}|
731\end{desc}
732Where |<level>| is the list level (one or more) in |list|, and the
733corresponding levels in |enumerate| and
734|itemize|.\footnote{\verb|\string\setenumerate|,
735\verb|\string\setitemize| and \verb|\string\setdescription| are
736deprecated.}  With no
737|<levels>|, the format applies to all of them.  Here list does not
738mean any list but only the three ones handled by this package and
739those redefined by this package or defined with |\newlist| (see
740below).  For example:
741\begin{verbatim}
742\setlist{noitemsep}
743\setlist[1]{\labelindent=\parindent} % << Usually a good idea
744\setlist[itemize]{leftmargin=*}
745\setlist[itemize,1]{label=$\triangleleft$}
746\setlist[enumerate]{labelsep=*, leftmargin=1.5pc}
747\setlist[enumerate,1]{label=\arabic*., ref=\arabic*}
748\setlist[enumerate,2]{label=\emph{\alph*}),
749                      ref=\theenumi.\emph{\alph*}}
750\setlist[enumerate,3]{label=\roman*), ref=\theenumii.\roman*}
751\setlist[description]{font=\sffamily\bfseries}
752\end{verbatim}
753These setting are read in the following order: list, list at the
754current level, enumerate/itemize/description, and
755enumerate/itemize/description at the current level; if a key appears
756several times with different values, the last one, i.e.,  the most
757specific one, is applied.  If we are resuming a series or a list with
758\texttt{resume*}, the saved keys are then applied.  Finally, the
759optional argument (except \texttt{resume*}), if any, is applied.
760
761\LaTeX{} provides a set of macros to change many of these parameters,
762but setting them with the package is more consistent and sometimes
763more flexible at the cost of being more explicit'' (and verbose).
764
765The list specification can contain variables and counters, provided
766they are expandable, and counters are \textsf{calc}-savvy, so that if
767you load this package you can write things like:
768\begin{verbatim}
769\newcount{toplist}
770\setcount{toplist}{1}
771\newcommand{\mylistname}{enumerate}
772\setlist[\mylistname,\value{toplist}+1]{labelsep=\itemindent+2em]
773\end{verbatim}
774This allows defining lists within loops.
775
776Currently, a way to discriminate the font size is not provided
777(|\normalsize|, |\small|\dots).
778
779\section{\textsf{enumerate}-like labels}
780\label{s.short}
781
782\begin{desc}
783|shortlabels| (package option)
784\end{desc}
785
786With the package option \texttt{shortlabels} you can use an
787\textsf{enumerate}-like syntax, where |A|, |a|, |I|,
788|i| and |1| stand for |\Alph*|, |\alph*|,
789|\Roman*|, |\roman*| and |\arabic*|.  This is intended
790mainly as a sort of compatibility mode with the \textsf{enumerate}
791package, and therefore the following special rule applies: if the very
792first option (at any level) is not recognized as a valid key, then it
793will be considered a label with the \textsf{enumerate}-like syntax.  For
794example:
795\begin{verbatim}
796\begin{enumerate}[i), labelindent=\parindent]
797...
798\end{enumerate}
799\end{verbatim}
800Although perhaps not so useful, you can omit |label=| in the
801itemize environment under similar conditions, too:
802\begin{verbatim}
803\begin{itemize}[\textbullet]
804...
805\end{itemize}
806\end{verbatim}
807
808\begin{desc}
809|\SetEnumerateShortLabel{<key>}{<replacement>}|
810\end{desc}
811
812With this command, you can define new keys (or redefine them), which is
813particularly useful for enumerate to be adapted to especific
814typographical rules or to extend it for non-Latin scrips. Here
815|<replacement>| contains one of the starred versions of
816counters. For example:
817\begin{verbatim}
818\SetEnumerateShortLabel{i}{\textsc{\roman*}}
819\end{verbatim}
820redefines |i| so that items using this key are numbered with
821small caps roman numerals. The key has to be a single letter.
822
823\section{Cloning the basic lists}
824\label{s.clone}
825
826\begin{desc}
827|\newlist{<name>}{<type>}{<max-depth>}|\\
828|\renewlist{<name>}{<type>}{<max-depth>}|
829\end{desc}
830
831The three lists can be cloned so that you can define logical''
832environments behaving like them.  To define a new lists (or redefine a
833existing one), use |\newlist| (or |\renewlist|), where |<type>| is
834|enumerate|, |itemize| or |description|.
835
836If <type> is |enumerate|, a set of counters with names |<name>i|,
837|<name>ii|, |<name>iii|, |<name>iv|, etc.  (depending on <max-depth>)
838is defined.  Don't use an arbitrarily large number for <max-depth>, to
839avoid creating too many counters.  Then you can use those counters in
840labels; e.  g., if you have defined a list named \texttt{steps}, you
841can define a label with:
842\begin{verbatim}
843label=\arabic{stepsii}.\arabic{stepsi}
844\end{verbatim}
845
846\begin{desc}
847\verb|\setlist[<names>,<levels>]{<keys/values>}|\\
848\verb|\setlist*[<names>,<levels>]{<keys/values>}|
849\end{desc}
850
851After creating a list, you can (in fact you
852must, at least the label) set the new list with |\setlist|:
853\begin{verbatim}
854\newlist{ingredients}{itemize}{1}
855\setlist[ingredients]{label=\textbullet}
856\newlist{steps}{enumerate}{2}
857\setlist[steps,1,2]{label=(\arabic*)}
858\end{verbatim}
859Names in the optional argument of |\setlist| say which lists applies the
860settings to, and numbers say the level (it is calc-savvy).  Several
861lists and/or several levels can be given, and all combinations are
862set; e.g.:
863\begin{verbatim}
864\setlist[enumerate,itemize,2,3]{...}
865\end{verbatim}
866\noindent sets enumerate/2, enumerate/3, itemize/2 and itemize/3.
867No number (or 0) means all levels'' and no name means all lists''; no
868optional argument means all lists at all levels''.
869
870The three inline lists have types \texttt{enumerate*},
871\texttt{itemize*}, and \texttt{description*}, which are available
872always, even without the package option |inline| (which just defines
873three environments with these names).
874
875The starred form \verb|\setlist*| adds the settings to previous ones.
876
877\begin{desc}
878\verb|\setlistdepth{<integer>|\3
879\end{desc}
880
881By default, \LaTeX{} has a limit of 5 nesting levels, but when
882cloning list this value may be too short, and therefore you may want
883to set a new value. In levels below the 5th (or the deepest defined by a
884class), the settings of the last are used (i.e., \verb|\@listvi|).
885
887
888\subsection{New counter representation}
889
890\begin{desc}
892\end{desc}
893
894Registers'' a counter representation so that \textsf{enumitem}
895recognizes it.  Intended mainly for non Latin scripts, but also useful
896in Latin scripts.  For example:
897\begin{verbatim}
898\makeatletter
899\def\ctext#1{\expandafter\@ctext\csname c@#1\endcsname}
900\def\@ctext#1{\ifcase#1\or First\or Second\or Third\or
901Fourth\or Fifth\or Sixth\fi}
902\makeatother
904\end{verbatim}
905A starred variant allows to give a number instead of a string as the
906widest label; for example, if the widest label is that corresponding
907to the value 2:\3
908\begin{verbatim}
910\end{verbatim}
911This variant is to be preferred if the representation is not a plain
912string but it is styled, e.g.,
913with small caps. (The counter names can contain |@| even if not a letter.)
914
915\subsection{Restarting \texttt{enumerate}s}
916
917\begin{desc}
918|\restartlist{<list-name>}|\3
919\end{desc}
920
921Currently, with
922\begin{verbatim}
923\setlist[enumerate]{resume}
924\end{verbatim}
925you can get a continuous numbering through a document.  A new command has
926been added for restarting the counter in the middle of the document:
927\begin{verbatim}
928\restartlist{<list-name>}
929\end{verbatim}
930
931It is based solely in the list name, not the list type, which means
932\texttt{enumerate*} as defined with the package option \texttt{inline}
933is not the same as \texttt{enumerate}, because its name is different.
934
935\section{Generic keys and values}
936
937\begin{desc}
938|\SetEnumitemKey{<key>}{<replacement>}|\3
939\end{desc}
940
941With this command you can create your own (valueless) keys.  For
942example:
943\begin{verbatim}
944\SetEnumitemKey{midsep}{topsep=3pt,partopsep=0pt}
945\end{verbatim}
946
947Keys so defined can then be used like the others. Another example is
948multicolumn lists, with \textsf{multicol}:
949\begin{verbatim}
950\SetEnumitemKey{twocol}{
951  itemsep=1\itemsep,
952  parsep=1\parsep,
953  before=\raggedcolumns\begin{multicols}{2},
954  after=\end{multicols}}
955\end{verbatim}
956
957(The settings for \texttt{itemsep} and \texttt{parsep} kill the
958stretch and shrink parts.  Of course, you may want to define a
959new list.)
960
961Note the package may introduce new keys in the future, so
962\verb|\SetEnumitemKey| is a potential source of forward
963incompatibilities.  However, it's safe using a non-letter character
964other than hyphen or star in the key name (e.g., \verb|:name| or
965\verb|2_col|).
966
967\begin{desc}
968|\SetEnumitemValue{<key>}{<string-value>}{<replacement>}|\3
969\end{desc}
970
971This commands provides a further abstraction layer for the
972|<key>=<value>| pairs.  With it you can define logical names which
973are translated to the actual value.  For example, with:
974\begin{verbatim}
975\SetEnumitemValue{label}{numeric}{\arabic*.}
976\SetEnumitemValue{leftmargin}{standard}{\parindent}
977\end{verbatim}
978you might say:
979\begin{verbatim}
980\begin{enumerate}[label=numeric,leftmargin=standard]
981\end{verbatim}
982So, you can left to the final design what |label=numeric| means.
983
984\section{Package options}
985
986Besides \verb|inline|, \verb|ignoredisplayed|, and \verb|shortlabels|,
987the following option is available.
988
989\begin{desc}
991\end{desc}
992
993With this package option the package is loaded but the three
994lists are not redefined. You can create your own lists, yet, or
995even redefine the existing ones.
996
997\section{Three patterns}
998
999Three list layouts could be considered very
1000frequent. Let us apply the parameters above to define them. (Below
1001are samples.)
1002
1003The first pattern aligns the label with the surrounding
1004|\parindent| while the item body is indented depending
1005on the label and a fixed |labelsep|:
1006\begin{verbatim}
1007labelindent=\parindent,
1008leftmargin=*
1009\end{verbatim}
1010A fairly frequent variant is aligning the label with the
1011surrounding text (rememeber |labelindent| is |0pt| by
1012default):
1013\begin{verbatim}
1014leftmargin=*
1015\end{verbatim}
1016The former looks better in the first level while the latter
1017seems preferable in subsequent ones. That can be easily
1018set with
1019\begin{verbatim}
1020\setlist{leftmargin=*}
1021\setlist[1]{labelindent=\parindent} % Only the level 1
1022\end{verbatim}
1023
1024The second pattern aligns the item body with the surrounding
1025|\parindent|. In this case:
1026\begin{verbatim}
1027leftmargin=\parindent
1028\end{verbatim}
1029
1030A third pattern would be to align the label with |\parindent|
1031and the item body with |2\parindent|:
1032\begin{verbatim}
1033labelindent=\parindent,
1034leftmargin=2\parindent,
1035itemsep=*
1036\end{verbatim}
1037Again, a variant would be to align the label with the surrounding
1038text and the itembody with |\parindent|:
1039\begin{verbatim}
1040leftmargin=\parindent,
1041itemsep=*
1042\end{verbatim}
1043
1044Note here |\parindent| means the global value applied
1045to normal paragraphs.
1046
1047\section{The trivlist issue}
1048
1049\LaTeX{} uses a simplified version of |list| named |trivlist| to set
1050displayed material, like |center|, |verbatim|, \verb|tabbing|,
1051\verb|theorem|, etc., even if conceptually they are not lists.
1052Unfortunately, |trivlist| uses the current list settings, which has
1053the odd side effect that changing the vertical spacing of lists also
1054changes sometimes the spacing in these environments.
1055
1056This package modifies |trivlist| so that the default settings for
1057the current level (ie, those set by the corresponding |clo|
1058files) are set again. In standard \LaTeX{} that is usually redundand,
1059but if we want to fine tune lists, not resetting the default values
1060could be a real issue (particularly if you use the |nolistsep|
1061option).
1062
1063A minimal control of vertical spacing has been made possible
1064with\footnote{\verb|\string\setdisplayed| is deprecated.}
1065\begin{itemize}
1066\item |\setlist[trivlist,<level>]{<keys/values>}|
1067\end{itemize}
1068but |trivlist| itself, which is not used directly very
1069often, does not accept an optional argument. This feature
1070is not intended as a full-fledge |trivlist| formatter.
1071
1072If for some reason you do not want to change |trivlist|
1073and preserve the original definition, you can use the
1074package option |ignoredisplayed|.
1075
1076\section{Samples}
1077
1078\expandafter\ifx\csname setenumerate\endcsname\relax
1079
1080Please, install first the package and then typeset this
1081document again.
1082
1083\else
1084
1085In these samples we set |\setlist{noitemsep}|
1086
1087\setlist{noitemsep}
1088\small
1089
1090\newcommand{\newsample}{\vskip6pt\goodbreak\hrule height 1pt\vskip6pt}
1091\newcommand{\samplesep}{\vskip6pt\goodbreak\hrule\vskip6pt}
1092\newbox\vsep
1093\setbox\vsep\hbox{\vrule height 2ex depth 16ex width 1pt}
1094\dp\vsep0pt
1095\newcommand\showsep{\leavevmode\llap{\copy\vsep}}
1096
1097\newsample
1098
1099\begin{verbatim}
1100En un lugar de la Mancha, de cuyo nombre no quiero acordarme,
1101no ha mucho tiempo que viv\'{\i}a un hidalgo de los de
1102\begin{enumerate}[labelindent=\parindent,leftmargin=*]
1103  \item lanza en astillero,
1105  \item roc\'{\i}n flaco, y
1106  \item galgo corredor.
1107\end{enumerate}
1108Una olla de algo m\'{a}s vaca que carnero, salpic\'{o}n las m\'{a}s
1109noches, duelos y quebrantos los s\'{a}bados...
1110\end{verbatim}
1111
1112The rule shows \verb|labelindent|.
1113
1114\samplesep
1115
1116\showsep En un lugar de la Mancha, de cuyo nombre no quiero acordarme,
1117no ha mucho tiempo que viv\'{\i}a un hidalgo de los de
1118\begin{enumerate}[labelindent=\parindent,leftmargin=*]
1119\item lanza en astillero,
1121\item roc\'{\i}n flaco, y
1122\item galgo corredor.
1123\end{enumerate}
1124Una olla de algo m\'{a}s vaca que carnero, salpic\'{o}n las m\'{a}s
1125noches, duelos y quebrantos los s\'{a}bados...
1126
1127\newsample
1128
1129With |\begin{enumerate}[leftmargin=*] % labelindent=0pt by default|.
1130
1131The rule shows \verb|labelindent|.
1132
1133\samplesep
1134
1135\noindent\showsep\hskip\parindent En un lugar de la Mancha, de cuyo nombre no quiero acordarme,
1136no ha mucho tiempo que viv\'{\i}a un hidalgo de los de
1137\begin{enumerate}[leftmargin=*]
1138\item lanza en astillero,
1140\item roc\'{\i}n flaco, y
1141\item galgo corredor.
1142\end{enumerate}
1143Una olla de algo m\'{a}s vaca que carnero, salpic\'{o}n las m\'{a}s
1144noches, duelos y quebrantos los s\'{a}bados...
1145
1146\newsample
1147
1148With |\begin{enumerate}[leftmargin=\parindent]|.
1149
1150The rule shows \verb|leftmargin|.
1151
1152\samplesep
1153
1154\showsep En un lugar de la Mancha, de cuyo nombre no quiero acordarme,
1155no ha mucho tiempo que viv\'{\i}a un hidalgo de los de
1156\begin{enumerate}[leftmargin=\parindent]
1157\item lanza en astillero,
1159\item roc\'{\i}n flaco, y
1160\item galgo corredor.
1161\end{enumerate}
1162Una olla de algo m\'{a}s vaca que carnero, salpic\'{o}n las m\'{a}s
1163noches, duelos y quebrantos los s\'{a}bados...
1164
1165\newsample
1166
1167With |\begin{enumerate}[labelindent=\parindent,|\allowbreak
1168| leftmargin=*,|\allowbreak| label=\Roman*.,|\allowbreak
1169| widest=IV,|\allowbreak| align=left]|.
1170
1171The rule shows \verb|labelindent|.
1172
1173\samplesep
1174
1175\showsep En un lugar de la Mancha, de cuyo nombre no quiero acordarme,
1176no ha mucho tiempo que viv\'{\i}a un hidalgo de los de
1177\begin{enumerate}[labelindent=\parindent, leftmargin=*,
1178                  label=\Roman*., widest=IV, align=left]
1179\item lanza en astillero,
1181\item roc\'{\i}n flaco, y
1182\item galgo corredor.
1183\end{enumerate}
1184Una olla de algo m\'{a}s vaca que carnero, salpic\'{o}n las m\'{a}s
1185noches, duelos y quebrantos los s\'{a}bados...
1186
1187\newsample
1188
1189With |\begin{enumerate}[label=\fbox{\arabic*}]|. A reference to
1190the first item is \ref{i:first}
1191
1192\samplesep
1193
1194En un lugar de la Mancha, de cuyo nombre no quiero acordarme,
1195no ha mucho tiempo que viv\'{\i}a un hidalgo de los de
1196\begin{enumerate}[label=\fbox{\arabic*}]
1197\item \label{i:first}lanza en astillero,
1199\item roc\'{\i}n flaco, y
1200\item galgo corredor.
1201\end{enumerate}
1202Una olla de algo m\'{a}s vaca que carnero, salpic\'{o}n las m\'{a}s
1203noches, duelos y quebrantos los s\'{a}bados...
1204
1205\newsample
1206
1207With nested lists.
1208
1209\samplesep
1210
1211\begin{verbatim}
1212En un lugar de la Mancha, de cuyo nombre no quiero acordarme,
1213no ha mucho tiempo que viv\'{\i}a un hidalgo de los de
1214\begin{enumerate}[label=(\alph*), labelindent=\parindent,
1215     leftmargin=*, start=12]
1216\item lanza en astillero,
1217\begin{enumerate}[label=(\alph{enumi}.\roman*), leftmargin=*, start=7]
1219\end{enumerate}
1220\item roc\'{\i}n flaco, y
1221\begin{enumerate}[label=(\alph{enumi}.\roman*), leftmargin=*, resume]
1222\item galgo corredor.
1223\end{enumerate}
1224\end{enumerate}
1225Una olla de algo m\'{a}s vaca que carnero, salpic\'{o}n las m\'{a}s
1226noches, duelos y quebrantos los s\'{a}bados...
1227\end{verbatim}
1228
1229En un lugar de la Mancha, de cuyo nombre no quiero acordarme,
1230no ha mucho tiempo que viv\'{\i}a un hidalgo de los de
1231\begin{enumerate}[label=(\alph*), labelindent=\parindent,
1232     leftmargin=*, start=12]
1233\item lanza en astillero,
1234\begin{enumerate}[label=(\alph{enumi}.\roman*), leftmargin=*, start=7]
1236\end{enumerate}
1237\item roc\'{\i}n flaco, y
1238\begin{enumerate}[label=(\alph{enumi}.\roman*), leftmargin=*, resume]
1239\item galgo corredor.
1240\end{enumerate}
1241\end{enumerate}
1242Una olla de algo m\'{a}s vaca que carnero, salpic\'{o}n las m\'{a}s
1243noches, duelos y quebrantos los s\'{a}bados...
1244
1245\newsample
1246
1247\begin{verbatim}
1248En un lugar de la Mancha, de cuyo nombre no quiero acordarme,
1249no ha mucho tiempo que viv\'{\i}a un hidalgo de los de
1250\begin{description}[font=\sffamily\bfseries, leftmargin=3cm,
1251    style=nextline]
1252  \item[Lo primero que ten\'{\i}a el Quijote] lanza en astillero,
1254  \item[Lo tercero] roc\'{\i}n flaco, y
1255  \item[Y por \'{u}ltimo, lo cuarto] galgo corredor.
1256\end{description}
1257Una olla de algo m\'{a}s vaca que carnero, salpic\'{o}n las m\'{a}s
1258noches, duelos y quebrantos los s\'{a}bados...
1259\end{verbatim}
1260
1261\samplesep
1262
1263En un lugar de la Mancha, de cuyo nombre no quiero acordarme,
1264no ha mucho tiempo que viv\'{\i}a un hidalgo de los de
1265\begin{description}[font=\sffamily\bfseries, leftmargin=3cm,
1266    style=nextline]
1267\item[Lo primero que ten\'{\i}a el Quijote] lanza en astillero,
1269\item[Lo tercero] roc\'{\i}n flaco, y
1270\item[Y por \'{u}ltimo, lo cuarto] galgo corredor.
1271\end{description}
1272Una olla de algo m\'{a}s vaca que carnero, salpic\'{o}n las m\'{a}s
1273noches, duelos y quebrantos los s\'{a}bados...
1274
1275\newsample
1276
1277Same, but with |sameline|.
1278
1279\samplesep
1280
1281En un lugar de la Mancha, de cuyo nombre no quiero acordarme,
1282no ha mucho tiempo que viv\'{\i}a un hidalgo de los de
1283\begin{description}[font=\sffamily\bfseries, leftmargin=3cm,
1284    style=sameline]
1285\item[Lo primero que ten\'{\i}a el Quijote] lanza en astillero,
1287\item[Lo tercero] roc\'{\i}n flaco, y
1288\item[Y por \'{u}ltimo, lo cuarto] galgo corredor.
1289\end{description}
1290Una olla de algo m\'{a}s vaca que carnero, salpic\'{o}n las m\'{a}s
1291noches, duelos y quebrantos los s\'{a}bados...
1292
1293\newsample
1294
1295Same, but with |multiline|. Note the text overlaps if
1296the item body is too short.
1297
1298\samplesep
1299
1300En un lugar de la Mancha, de cuyo nombre no quiero acordarme,
1301no ha mucho tiempo que viv\'{\i}a un hidalgo de los de
1302\begin{description}[font=\sffamily\bfseries, leftmargin=3cm,
1303    style=multiline]
1304\item[Lo primero que ten\'{\i}a el Quijote] lanza en astillero,
1306\item[Lo tercero] roc\'{\i}n flaco, y
1307\item[Y por \'{u}ltimo, lo cuar] galgo corredor.
1308\end{description}
1309Una olla de algo m\'{a}s vaca que carnero, salpic\'{o}n las m\'{a}s
1310noches, duelos y quebrantos los s\'{a}bados...
1311
1312\fi
1313
1314\normalsize
1315
1316\section{Afterword}
1317
1318\subsection{\LaTeX{} lists}
1319
1320As it is well known, \LaTeX{} predefines three lists:
1321\texttt{enumerate}, \texttt{itemize} and \texttt{description}.  This
1322is a very frequent classification which can also be found in, say,
1323HTML. However, there is a more general model based in three
1324fields---namely, label, title, and body---, so that enumerate and
1325itemize has label (numbered and unnumbered) but no title, while
1326description has title but no label.  In this model, one can have a
1327description with entries marked with labels, as for example (of
1328course, this simple solution is far from satistactory):
1329\begin{verbatim}
1330\newcommand\litem[1]{\item{\bfseries #1,\enspace}}
1331\begin{itemize}[label=\textbullet]
1332\litem{Lo primero que ten\'{\i}a el Quijote} lanza en astillero,
1333... etc.
1334\end{verbatim}
1335
1336\vskip6pt
1337\goodbreak
1338\hrule
1339\vskip6pt
1340
1341\newcommand\litem[1]{\item{\bfseries #1,\enspace}}
1342En un lugar de la Mancha, de cuyo nombre no quiero acordarme,
1343no ha mucho tiempo que viv\'{\i}a un hidalgo de los de
1344\begin{itemize}[label=\textbullet]
1345\litem{Lo primero que ten\'{\i}a el Quijote} lanza en astillero,
1347\litem{Lo tercero} roc\'{\i}n flaco, y
1348\litem{Y por \'{u}ltimo, lo cuarto} galgo corredor.
1349\end{itemize}
1350
1351\vskip6pt
1352\goodbreak
1353\hrule
1354\vskip6pt
1355
1356This format in not infrequent at all and a tool for defining them is
1357on the way and at a very advanced stage. It has not been include in
1358version 3.0 because I'm not sure if the proper place is this package
1359or \textsf{titlesec} and it is not stable enough yet.
1360
1361\subsection{Known issues}
1362
1363\begin{itemize}
1364
1365\item
1366List resuming is based on environment names, and when a
1367|\newenvironment| contains a list you may want to use |\begin| and
1368|\end|.  Using the corresponding commands, however, is not an error,
1369but it is your responsability to make sure the result is correct.
1370
1371\item
1372It seems there is no way to catch a misspelled name in |\setlist|
1373and a meaningless error Missing number, treated as zero'' is raised.
1374
1375\item The behaviour of mixed boxed labels (including enumerate and
1376itemize) and unboxed labels is not well-defined.  The same applies to
1377boxed and unboxed inline lists (which could even raise an error).
1378Similarly, resuming a series and a list at the same time is allowed,
1379too, but again its behaviour is not well-defined.
1380
1381\item (3.5.2) An incompatibility with 2.x has popped up -- if you were
1382using the optional argument to pass a value to a \verb|\ref| or other
1383macro requiring expandable macros, an error is raised. A quick fix
1384is letting \verb|\makelabel| to |\descriptionlabel| in \texttt{before}.
1385
1386\end{itemize}
1387
1388\subsection{What's new in 3.0}
1389
1390\begin{itemize}
1391\item Inline lists, with keys to set how items are joined (ie, the
1392punctuation between items).  Two modes are provided: \verb|boxed|  and
1393\verb|unboxed|.
1394
1395\item \verb|\setlist| is \textsf{calc}-savvy (eg, for use in loops),
1396and you can set diferent lists and levels at once.  \item All lengths
1397related to labels can take the value \verb|*| (and not only
1398\verb|labelsep| and \verb|leftmargin|).  Its behaviour has been made
1399consistent and there is new value \verb|!| which does not compute the
1400widest label.
1401
1402\item With \verb|\restartlist{<list-name>}|, list counters can be restarted (in
1403case you are using \verb|resume|).
1404
1405\item \verb|resume*| can be combined with other keys.
1406
1407\item Lists can be gathered globally using series, so that they are
1408considered a single list.  To start a series just use
1409|series=<series-name>| and then resume it with |resume=<series-name>| or
1410|resume*=<series-name>|.
1411
1412\item The experimental'' \verb|fullwidth| has been replaced by a new key
1413\verb|wide|.
1414
1415\item|\SetLabelAlign| defines new align values.
1416
1417\item You can define abstract'' values (eg, \verb|label=numeric|) and
1418new keys.
1419\end{itemize}
1420
1421\begin{itemize}
1422\item (3.2) \verb|start| and \verb|widest*| are \textsf{calc}-savvy.
1423\item (3.2) \verb|\value| can be used with \verb|widest*|.
1424\item (3.2) Some internal restrictions in \verb|\arabic| and the like
1425has been removed.  It is more flexible at the cost of having a more
1426relaxed'' error checking.
1427\end{itemize}
1428\subsection{Bug fixes}
1429
1430\begin{itemize}
1431\item Star values (eg, \verb|leftmargin=*|) could not be overriden
1432and new values were ignored.
1433\item \verb|nolistsep| as the first of several keys was not always
1434recognized and therefore treated like a short label
1435(i.e., \verb|nol\roman*stsep|).
1436\item \verb|labelwidth| did not always work (when there was a prior
1437\verb|widest| and \verb|*|)
1438\item With \verb|align=right| the label and the following text could
1439overlap.
1440\item \verb|description| did not get the correct list level.
1441\item At some point (2.x?) \verb|\value*| stopped working.
1442\item (3.1) Unfortunately, \textsf{xkeyval} kills''
1443\textsf{keyval}, so the lattest has been replicated in
1444\textsf{enumitem}.
1445\item (3.3) Fixes a serious bug -- with \verb|*| neither
1446\verb|itemize| nor \verb|description| worked.
1447\item (3.4) Fixes bad spacing in mode boxed (misplaced \verb|\unskip|
1448before the first item and wrong spacefactor between items).
1449\item (3.4) \verb|nolistsep| did not work as intended, but since the
1450error has been there for several years, a new key \verb|nosep| is
1451provided.
1452\item (3.4) The issue with \verb|nolistsep| with \verb|shortlabels|
1453(see above) was not fixed in all cases. Hopefully now it is.
1454\item (3.5.0) Fixed the fix related to the spacefactor between items.
1455\item (3.5.0) Fixed a problem with nested boxed inline lists.
1456\item (3.5.1) \texttt{resume*} only worked once, and subsequent ones
1457bahaved like \texttt{resume}.
1458\item (3.5.2) Fixed |\setlist*|, which didn't work.
1459\end{itemize}
1460
1461
1462\subsection{Acknowledgements}
1463
1464I wish to thank particularly the comments and suggestions from Lars
1465Madsen, who has found some bugs, too.
1466
1467\end{document}
Note: See TracBrowser for help on using the repository browser.