Debian Codegraph @

texmf-dist/source/latex/gatherenum/gatherenum.dtx

raw
1 % \iffalse meta-comment
2 % vim: tw=80 spl=en
3 %
4 %% File: gatherenum.dtx (C) Copyright 2016-2019 RIVAUD Julien
5 %%
6 %% It may be distributed and/or modified under the conditions of the
7 %% General Public License (GPL), either version 3 of this
8 %% license or (at your option) any later version.
9 %
10 %<*driver|package>
11 % The version of expl3 required is tested as early as possible, as
12 % some really old versions do not define \ProvidesExplPackage.
13 \NeedsTeXFormat{LaTeX2e}[1995/12/01]
14 \RequirePackage{expl3}[2018/06/19]
15 \def\ExplFileName{gatherenum}
16 \def\ExplFileDescription{Crossover between align* and enumerate}
17 \def\ExplFileDate{2019/09/29}
18 \def\ExplFileVersion{1.8}
19 %</driver|package>
20 %<*driver>
21 \documentclass[full]{l3doc}
22 \usepackage{gatherenum}
23 \begin{document}
24 \DocInput{\jobname.dtx}
25 \end{document}
26 %</driver>
27 % \fi
28 %
29 % \title{^^A
30 % The \textsf{\ExplFileName} package\\
31 % Gathered, display-like \env{enumerate}^^A
32 % \thanks{This file describes v\ExplFileVersion,
33 % last revised \ExplFileDate.}^^A
34 % }
35 %
36 % \author{^^A
37 % Julien ``\_FrnchFrgg\_'' \textsc{Rivaud}\thanks
38 % {^^A
39 % E-mail:
40 % \href{mailto:[email protected]}
41 % {[email protected]}^^A
42 % }^^A
43 % }
44 %
45 % \date{Released \ExplFileDate}
46 %
47 % \maketitle
48 %
49 % \begin{documentation}
50 %
51 % \section{Documentation}
52 %
53 % \subsection{Package description}
54 %
55 % This package (ab)uses the inline enumeration capabilities of \pkg{enumitem} to
56 % add a ``displayed'' enumeration mode, triggered by adding |gathered| to the
57 % key-val option list of the \env{enumerate} environment.
58 %
59 % The end result is similar to The end result is similar to a regular enumerate
60 % environment wrapped in a multicols environment, with the following advantages:
61 % \begin{itemize}
62 % \item \emph{gathered} enumerate can pack items depending on their actual
63 % width rather than a fixed, constant number per line;
64 % \item it fills items in a line-major order (instead of column-major order),
65 % which my students found less confusing.Your mileage may vary.
66 % \end{itemize}
67 %
68 % All settings of the standard enumeration that are relevant still apply to the
69 % gathered mode --- which would not have been the case with a separate
70 % inline enumeration like the \env{enumerate*} provided by \pkg{enumitem}.
71 %
72 % Individual items are separately boxed, to mimic the behavior of \env{align}.
73 % This package is not for you if you want free-flow enumeration in a paragraph,
74 % since \pkg{enumitem} already provides a reasonable one, and you probably do
75 % not want to share that many settings with regular \env{enumerate} due to the
76 % very different nature and look of inline enumerations.
77 %
78 % Say:
79 %\begin{verbatim}
80 % \setlist{enumerate}{label=\arabic*.}
81 % \begin{enumerate}
82 % \item Test
83 % \item $\int_a^b$ with math
84 % \item And another
85 % \item $f(x) = 6$
86 % \item $D(t) = 0$
87 % \item $d$~and~$d'$ are parallel
88 % \end{enumerate}
89 %\end{verbatim}
90 % produces:
91 % \setlist[enumerate]{label=\arabic*.}
92 % \begin{enumerate}
93 % \item Test
94 % \item $\int_a^b$ with math
95 % \item And another
96 % \item $f(x) = 6$
97 % \item $D(t) = 0$
98 % \item $d$~and~$d'$ are parallel
99 % \end{enumerate}
100 %
101 % Then:
102 %\begin{verbatim}
103 % \begin{enumerate}[gathered]
104 % \item Test
105 % \item $\int_a^b$ with math
106 % \item And another
107 % \item $f(x) = 6$
108 % \item $D(t) = 0$
109 % \item $d$~and~$d'$ are parallel
110 % \end{enumerate}
111 %\end{verbatim}
112 % will produce:
113 % \begin{enumerate}[gathered]
114 % \item Test
115 % \item $\int_a^b$ with math
116 % \item And another
117 % \item $f(x) = 6$
118 % \item $D(t) = 0$
119 % \item $d$~and~$d'$ are parallel
120 % \end{enumerate}
121 %
122 % \subsection{Customizing}
123 %
124 % Most of the changes are in fact done through the usual \pkg{enumitem}
125 % interface. |itemjoin| can be a useful setting to tweak. \pkg{gatherenum}
126 % provides several additional options:
127 %
128 % \begin{itemize}[noitemsep]
129 % \item |gatherformat| this is put just before every item content; the last
130 % token in that option can take an argument, which will be the unboxed
131 % item content. Note that since the item has already been typeset in an
132 % horizontal box, you cannot change the font family, shape or size at that
133 % point, but can add a frame around for instance.
134 % \item |center| display the items in a centered paragraph. This is the most
135 % display-like and is the default. Equivalent to |before*=\centering|.
136 % \item |alignleft| display the items in a left-aligned paragraph.\\
137 % Equivalent
138 % to |before*=\raggedright|.
139 % \end{itemize}
140 %
141 % Lastly, an example of something I use a lot:
142 %
143 % \bigskip
144 % \hrule\medskip
145 % Compute the following:
146 % \begin{enumerate}[gathered, label={$\alph* = {}$}, labelsep=0pt]
147 % \item $1+1$
148 % \item $\sin\left( 2\pi + \frac{\pi}{3} \right)$
149 % \item $\displaystyle \int_0^{+\infty} \mathrm{e}^{-t^2} \mathrm{d}t$
150 % \item $\varphi(52330)$
151 % \end{enumerate}
152 % \medskip\hrule
153 % \begin{verbatim}
154 % Compute the following:
155 % \begin{enumerate}[gathered, label={$\alph* = {}$}, labelsep=0pt]
156 % \item $1+1$
157 % \item $\sin\left( 2\pi + \frac{\pi}{3} \right)$
158 % \item $\displaystyle \int_0^{+\infty} \mathrm{e}^{-t^2} \mathrm{d}t$
159 % \item $\varphi(52330)$
160 % \end{enumerate}
161 % \end{verbatim}
162 % \hrule
163 %
164 % \end{documentation}
165 %
166 % \begin{implementation}
167 %
168 % \section{\pkg{\ExplFileName} implementation}
169 %
170 % \begin{macrocode}
171 %<*package>
172 %<@@=gatherenum>
173 % \end{macrocode}
174 %
175 % \begin{macrocode}
176 \ProvidesExplPackage
177 {\ExplFileName}{\ExplFileDate}{\ExplFileVersion}{\ExplFileDescription}
178 % \end{macrocode}
179 %
180 % We use \pkg{enumitem} as a base, and \pkg{xparse} to define our environment.
181 % \begin{macrocode}
182 \RequirePackage{enumitem}
183 \RequirePackage{xparse}
184 % \end{macrocode}
185 %
186 % \pkg{enumitem} has a mechanism to make the \env{enumerate} environment use
187 % settings and counters prefixed by \cs{enum} instead of \cs{enumerate}
188 % (because that's what \LaTeX\ does). We take advantage of that to define our
189 % internal enumeration, because we want to share settings and counter with
190 % \env{enumerate} since we will act as an option of that environment.
191 % \begin{macrocode}
192 \tl_set:Nn \enit@shortgatherenum {enum}
193 \newlist{gatherenum}{enumerate*}{3}
194 % \end{macrocode}
195 %
196 % Since \pkg{enumitem} inline enumerations are intended for pararaph-like
197 % enumerations, the item content is unpacked with \cs{unhbox} even in
198 % \emph{boxed} mode. That's not what we want, so we have to add another layer
199 % of boxing. While we're at it, we add a formatting command for the user
200 % to customize.
201 % \begin{macrocode}
202 \tl_new:N \l@@_itemformat
203 \cs_new_protected_nopar:Nn \@@_boxitem: {
204 \nobreak\skip_horizontal:n {\labelsep}
205 \hbox_set:Nn \enit@inbox {
206 \hbox:n {
207 \l@@_itemformat{\hbox_unpack:N \enit@inbox}
208 }
209 }
210 }
211 \enitkv@key{enumitem}{gatherformat}{\tl_set:Nn\l@@_itemformat{#1}}
212 % \end{macrocode}
213 %
214 % Now is the time to change the enumerate environment. We save the start and
215 % end of existing environment from \pkg{enumitem} to be able to fall back to
216 % it.
217 % \begin{macrocode}
218 \let\@@_save_enumerate:w\enumerate
219 \let\@@_save_endenumerate:w\endenumerate
220 \RenewDocumentEnvironment{enumerate}{ O{} }{
221 % \end{macrocode}
222 %
223 % The trigger for gathered enumeration is the \texttt{gathered} option given
224 % by the user in the list of local options. If there is no such option, we
225 % directly use the original \cs{endenumerate}.
226 %
227 % \begin{macrocode}
228 \clist_if_in:nnTF { #1 } { gathered } {
229 % \end{macrocode}
230 %
231 % To act more display-like, we ensure that running heads that are not already
232 % typeset are flushed now. This is especially important in the default
233 % centered typesetting: we don't want to center the theorem or enumerate heads
234 % along with our content.
235 % \begin{macrocode}
236 \if@inlabel
237 \leavevmode
238 \fi
239 \par
240 \centering
241 % \end{macrocode}
242 %
243 % Synchronise the current depth of gatherenum with that of enumerate
244 % (oddly \cs{enit@shortgatherenum} doesn't imply that). That enables us to get
245 % the right settings depending on depth (labels, mostly, since indention is
246 % irrelevant here).
247 % \begin{macrocode}
248 \int_set_eq:NN \enitdp@gatherenum \enitdp@enumerate
249 % \end{macrocode}
250 %
251 % Insert a display-like penalty, and start our inline enumeration. Since
252 % setting defaults for gatherenum would clobber (or a least mess with)
253 % the settings of normal enumerate, we give them here using the optional
254 % argument (recall that they share most counters and settings).
255 %
256 % We use a trivial align mode to ensure \pkg{enumitem} doesn't try to apply
257 % indention, alignment or spacing effects to the label. \meta{afterlabel} is
258 % a hook that enumitem calls after closing the \cs{hbox} with item content,
259 % after typesetting the label, but before unboxing the content. We use
260 % \cs{@@_boxitem:} defined before to ensure the content stays
261 % boxed.
262 % \begin{macrocode}
263 \penalty \predisplaypenalty
264 \gatherenum[
265 itemjoin=\skip_horizontal:n{1em plus 1fil},
266 #1,
267 mode=boxed,
268 align=none,
269 afterlabel=\@@_boxitem:,
270 ]
271 }{
272 \@@_save_enumerate:w[#1]
273 }
274 }{
275 % \end{macrocode}
276 %
277 % Finish the environment, either by closing the standard \env{enumerate}, or
278 % by ending our horizontal enumeration, and closing the paragraph. We are
279 % less strict on widows and clubs than normal.
280 % \begin{macrocode}
281 \clist_if_in:nnTF { #1 } { gathered } {
282 \endgatherenum
283 \unskip
284 \int_set_eq:NN \clubpenalty \interlinepenalty
285 \int_set_eq:NN \widowpenalty \interlinepenalty
286 \use:c{@ @ par}% avoid l3docstrip replacement of @
287 }{
288 \@@_save_endenumerate:w
289 }
290 }
291 % \end{macrocode}
292 %
293 % Last touches: a \texttt{gathered} key for \pkg{enumitem} so that it doesn't
294 % complain when it sees it (this enables us to keep the key in the list
295 % instead of filtering it with \cs{clist_remove_all:Nn}). Next is the trivial
296 % align mode we talked about earlier, and at last some shorthands for common
297 % layouts.
298 %
299 % \begin{macrocode}
300 \SetEnumitemKey{gathered}{}
301 \SetLabelAlign{none}{#1}
302 \SetEnumitemKey{centered}{before*=\centering}
303 \SetEnumitemKey{alignleft}{before*=\raggedright}
304 %</package>
305 % \end{macrocode}
306 %
307 % \end{implementation}