Debian Codegraph @

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

raw
1 % \iffalse meta-comment
2 %
3 %% File: dashundergaps.dtx (C) Copyright 2018-2021 Frank Mittelbach
4 %
5 % It may be distributed and/or modified under the conditions of the
6 % LaTeX Project Public License (LPPL), either version 1.3c of this
7 % license or (at your option) any later version. The latest version
8 % of this license is in the file
9 %
10 % https://www.latex-project.org/lppl.txt
11 %
12 %
13 % The development version of the bundle can be found below
14 %
15 % https://github.com/FrankMittelbach/fmitex/
16 %
17 % for those people who are interested or want to report an issue.
18 %
19
20 \def\dashundergapsdate {2021-03-05} % don't forget to also adjust build.lua!
21 \def\dashundergapsversion{v2.0h}
22
23 %<*driver>
24 \let\fmipagebreak\pagebreak
25
26 \RequirePackage[nohyphen]{underscore} % no hyphen after undercore
27 % in csname
28 \documentclass
29 [final]
30 {l3doc-TUB}
31
32 \setcounter{page}{1}
33
34 % fix for _TF undefined,
35 % https://github.com/latex3/latex3/issues/477#issuecomment-419458783
36 \ExplSyntaxOn
37 \cs_set_protected:Npn \__codedoc_typeset_TF:
38 {
39 \group_begin:
40 \exp_args:No \__codedoc_if_macro_internal:nT \l__codedoc_tmpa_tl
41 { \color[gray]{0.5} }
42 \itshape TF
43 \group_end:
44 }
45 \ExplSyntaxOff
46
47 % fix for doc/ltugboat issue
48 \def\pfill{~%
49 \leaders\hbox to.6em{\hss .\hss}\hskip 0em plus 1fill
50 \kern-1.5em
51 \penalty500
52 \kern 1.5em
53 \strut\nobreak
54 \leaders\hbox to.6em{\hss .\hss}\hskip 0em plus 1fil
55 \null~\ignorespaces}%
56
57 \usepackage{dashundergaps,multicol}
58 \EnableCrossrefs
59 \CodelineIndex
60 \begin{document}
61 \DocInput{dashundergaps.dtx}
62 \addtolength\signaturewidth{42pt}
63 \makesignature
64 \end{document}
65 %</driver>
66 %
67 % \fi
68 %
69 %
70 % \newcommand\option[1]{\texttt{#1}}
71 %
72 % \DoNotIndex{}
73 %
74 % \title{The \texttt{dashundergaps} package\thanks{This is a
75 % reimplementation (using \texttt{expl3}, the \LaTeX3 programming
76 % language) of a package originally written by Luca Merciadri in
77 % 2010. The current package version is \dashundergapsversion\
78 % dated \dashundergapsdate.}}
79 % \author{Frank Mittelbach}
80 % \address{Mainz, Germany}
81 % \netaddress{https://www.latex-project.org}
82 % \personalURL{https://ctan.org/pkg/dashundergaps}
83 %
84 % \maketitle
85 %
86 % \begin{abstract}
87 % The \pkg{dashundergaps} package offers the possibility to replace
88 % material in running text with white space in order to build up forms
89 % that can be filled in at a later time.
90 %
91 % By default the gaps are underlined and followed by a gap number in
92 % parentheses, but many other designs are possible, e.g., dashes or
93 % dots instead of the underline, no gap numbers or a different format
94 % for them, gap widening for easier fill-in, etc.
95 %
96 % There is also a teacher's mode which shows the normally hidden text
97 % in a special (customizable) format.
98 %
99 % \medskip
100 %
101 % This is another article in a series of \TUB{} articles
102 % describing small packages to introduce coding practices using the
103 % \pkg{expl3} programming language. See~\cite{tub-wao-code} for the
104 % first article in the series.
105 % For more details on \pkg{expl3} refer to~\cite{expl3}.
106 %
107 % \end{abstract}
108 %
109 % \tableofcontents
110 %
111 %
112 % \section{Introduction}
113 %
114 % The \pkg{dashundergaps} package provides a single command \cs{gap}
115 % which takes one argument and produces a gap of the width of that
116 % argument. To better mark this gap it is underlined in some form (could be
117 % a solid line, a dashed or dotted line or even a \uwave{wriggling
118 % line}). Furthermore, gaps can be numbered to be able to easily
119 % refer to them. Figure~\ref{fig:puzzle} shows an example in the form of a
120 % fill-in puzzle.
121 %
122 %
123 % \newcommand\puzzletext{%
124 % \begin{quote}
125 % \addtolength\baselineskip{3pt}
126 % The initial `E.' in Donald E. Knuth's name stands for \gap{Ervin}.
127 % The well-known answer to the Ultimate Question \gap*{of Life, the
128 % Universe, and Everything} is 42 according to \gap{Douglas Adams}.
129 % The first edition of \gap{The \LaTeX{} Companion} celebrates its silver
130 % anniversary in 2019. Historically speaking, \texttt{expl3} stands for
131 % \gap{\textbf{EX}perimental \textbf{P}rogramming \textbf{L}anguage
132 % \textbf{3}} even though it is a production language these days.
133 % \end{quote}}
134 %
135 %
136 % \dashundergapssetup{
137 % ,gap-number-format = \,\textsuperscript{\normalfont
138 % (\thegapnumber)}
139 % ,gap-font = \itshape
140 % ,teacher-gap-format = underline
141 % ,gap-widen
142 % }
143 %
144 % \begin{figure}
145 % \centering
146 % \setlength\fboxsep{10pt}
147 % \noindent\hspace{-\marginparwidth}\fbox{\begin{minipage}{1.20\textwidth}
148 % \puzzletext
149 %
150 % \bigskip
151 %
152 % And here are some hints for the puzzle if you want to fill it out:
153 % \begin{quote}
154 % \begin{multicols}{2}
155 % \begin{enumerate}
156 % \item If only everything would be that easy\newline to answer.
157 % \item The author of the book ``Last Chance To~See'' and of a famous
158 % radio~show.
159 % \item Back then known as the doggie book.
160 % \item Old names die hard.\\
161 % \mbox{} ^^A manual to get same height
162 % \end{enumerate}
163 % \end{multicols}
164 % \end{quote}
165 % The answers are given in Section~\ref{sec:answer}, showing the gaps
166 % filled in using the so-called teacher mode, which~can be
167 % activated or deactivated at any point in the document.\raggedright
168 % \end{minipage}}
169 % \caption{A fill-in puzzle using \pkg{dashundergaps}}\label{fig:puzzle}
170 % \end{figure}
171 %
172 % As you see there, some gaps are numbered with a superscript number (not the
173 % default setting) while others aren't. How this is done and how to
174 % change the result is explained in the next section.
175 %
176 % There also exists a ``teacher mode'' in which the gaps are filled
177 % with the text given in the argument. This can be used to show the
178 % correct answers of a test (as we do in Section~\ref{sec:answer}) or
179 % to give a sample fill-in for a form, to help people fill it out
180 % correctly. The ``teacher mode'' produces the same line breaks
181 % because it ensures that the fill-ins take the same amount of space as the
182 % gaps.
183 %
184 % Another important feature is the possibility to artificially widen the
185 % gaps, compared to the textual material in the argument. After all,
186 % when a form is filled by hand people typically need more space to
187 % write some text compared to the same text being typeset. So making the
188 % gaps simply as wide as the material likely results in too little
189 % space.
190 %
191 %
192 % \section{The user interface}
193 %
194 %
195 % The \pkg{dashundergaps} package is built as a small application on top
196 % of the \pkg{ulem} package, a package that defines several commands for
197 % underlining \meta{simple-text} in various ways.
198 % \begin{function}{\uline,\uuline,\uwave,\dashuline,\dotuline}
199 % \begin{syntax}
200 % \cs{uline}\Arg{simple-text} \cs{uwave}\Arg{simple-text} ...
201 % \end{syntax}
202 % This means that by loading
203 % \pkg{dashundergaps} the \pkg{ulem} commands such as \cs{uline},
204 % \cs{uwave} and so forth are automatically made available.
205 % These commands are used to do most of
206 % the work and the current package only makes sure that, instead of the
207 % words, empty boxes of the same width are used by \pkg{ulem}. This
208 % way we get underlined gaps of the right size.
209 %
210 % By default, \pkg{ulem} changes \cs{emph} to underline text, so
211 % for this application, it is loaded with the option \texttt{normalem} to
212 % prevent that from happening.
213 %
214 % \end{function}
215 %
216 %
217 %
218 % \begin{function}{\gap}
219 % \begin{syntax}
220 % \cs{gap}*\oarg{style}\Arg{text}
221 % \end{syntax}
222 % \noindent\llap{\small\smash{\begin{tabular}[t]{r@{ = }l} ^^A really low-level hacked
223 % \multicolumn{2}{c}{}\\
224 % \multicolumn{2}{c}{\hspace*{-1.2pc}Possible \meta{style}s:}\\[3pt]
225 % \texttt{u} & \cs{uline} \\
226 % \texttt{d} & \cs{uuline} \\
227 % \texttt{w} & \cs{uwave} \\
228 % \texttt{b} & \meta{blank} \\
229 % \texttt{-} & \cs{dashuline} \\
230 % \texttt{.} & \cs{dotuline}
231 % \end{tabular}}\ }^^A
232 % The main command provided by the package is \cs{gap} which expects a
233 % mandatory \meta{text} argument containing the material that is used
234 % to produce the gap (and is normally invisible). By default the gap is
235 % underlined, though that can be changed.
236 % \end{function} ^^A not really meant for no parindent and positive
237 % ^^A parskip ...
238 % \vspace{\parskip} ^^A ... thus manual fix for now
239 %
240 %
241 % The optional \meta{style} argument explicitly defines a certain type
242 % of underlining: |u| stands for normal underlining (via \cs{uline}),
243 % |d| for double underlining (via \cs{uuline}),
244 % |w| for a wavy line (via \cs{uwave}), |b| for blank (i.e., no
245 % underlining whatsoever), ``|-|'' for a dash-line (via \cs{dashuline})
246 % and finally ``|.|''\ for underlining with dots (via \cs{dotuline}).
247 %
248 % In the default configuration gaps are numbered using the counter
249 % \texttt{gapnumber} and this number is shown in parentheses after
250 % the gap. With the star form the generation of the number is
251 % toggled, i.e., if it would be produced because of the current
252 % option settings it will be suppressed; if it is suppressed through
253 % an option it will be typeset. This way one can select the most
254 % convenient setting via an option for the whole document and use
255 % |*| to toggle it as needed.
256 %
257 % Since \cs{gap} uses \pkg{ulem}'s commands it inherits the limitations
258 % of these commands; notably, only simple text can be used in the
259 % \meta{text} argument. For example, a \cs{footnote} couldn't be used
260 % in the argument (but then that wouldn't make much sense in a gap,
261 % would~it?).
262 %
263 % Another important (and sometimes annoying) restriction is that any
264 % brace group or command with arguments inside the \pkg{ulem}
265 % commands is set as if is is inside an \cs{mbox}, in particular it will
266 % not break across lines. For example \verb=\gap{\emph{...}}= will
267 % show this behavior. The \pkg{dashundergaps} package tries
268 % mediate as best as possible, e.g., \verb=\gap{\mytext}= works,
269 % but in other cases you have to live with this limitation.
270 %
271 % \begin{function}{\TeacherModeOn,\TeacherModeOff}
272 % \begin{syntax}
273 % \cs{TeacherModeOn} \texttt{\,\% show gap material}
274 % \cs{TeacherModeOff} \texttt{\% do not show gap material}
275 % \end{syntax}
276 % Also supported is a teacher mode in which the material for the gaps is
277 % visible. This can be used to show the expected answers in case \cs{gap}
278 % is used for preparing tests, or to show a sample fill-in of a form.
279 % The teacher mode can be turned on or off anywhere in the document
280 % using \cs{TeacherModeOn} or \cs{TeacherModeOff},
281 % respectively. Alternatively, it can also be set via an option, as we
282 % will see below.
283 % \end{function}
284 %
285 % \begin{function}{\dashundergapssetup}
286 % \begin{syntax}
287 % \cs{dashundergapssetup}\Arg{comma-separated key-value list}
288 % \end{syntax}
289 % The package can be loaded with a number of options (discussed in
290 % Section~\ref{sec:options}). A likely better approach is to set any
291 % options with the declaration \cs{dashundergapssetup} which is normally
292 % used in the preamble, but can be used throughout the document
293 % to change settings on the fly. It only changes explicitly given options
294 % so it can be used to overwrite some defaults but leave everything
295 % else unchanged.
296 % \end{function}
297 %
298 %
299 %
300 %
301 %
302 %
303 %
304 %
305 % \subsection{Options to customize the gap display}\label{sec:options}
306 %
307 % All of the package options are implemented as key/value options.
308 % For boolean options one can give just the option name as a short
309 % form for setting the option to |true|. Most options can be specified
310 % during package loading in the optional argument of
311 % \cs{usepackage}. However if the value requires some \LaTeX{} code
312 % (e.g., \option{gap-font}, which expects a font declaration command)
313 % then this will not work due to some limitations in the current
314 % \LaTeX{} package loader. For such options use
315 % \cs{dashundergapssetup} instead, which will always work.
316 %
317 % \subsubsection{Gap modes}
318 %
319 % The general processing mode is defined through the following options:
320 % \begin{description}
321 % \item[\option{teacher-mode}] Boolean that turns on teacher mode (i.e., the gap
322 % material will be visible if set to |true|). Its default is
323 % |false|.
324 % \item[\option{gap-mode}] Boolean that is the inverse of \option{teacher-mode}
325 % and just provided for convenience, i.e., an abbreviation
326 % for \option{teacher-mode}|=false|.
327 % \item[\option{teachermode}] Alternative name for \option{teacher-mode} because
328 % that is what it was called in the first package release.
329 % \end{description}
330 %
331 % \subsubsection{Gap formatting}
332 %
333 % Formatting of the gaps is handled by the following six options:
334 % \begin{description}
335 % \item[\option{gap-format}] A choice option defining how the gap is
336 % marked. It accepts the following values: |underline| (default),
337 % |double-underline|,
338 % |dash|, |dot|, |wave|, |blank|.
339 % \item[\option{gap-format-adjust}] A boolean (default |true|). If set, the
340 % ``line'' below the gap is raised to be roughly at the baseline,
341 % which normally looks better when there is no text above the line.
342 % \item[\option{teacher-gap-format}] Another choice option, with the
343 % same values as \option{gap-format}, used when we
344 % are in ``teacher mode'', but this time
345 % the default is |blank| as normally the gap text is typeset in the bold
346 % font and is therefore already identifiable, with no need for additional
347 % underlining. However, depending on the circumstances it
348 % might be helpful to keep the underlining (or use a different kind of
349 % underlining) while in ``teacher mode''.
350 % \item[\option{gap-font}] This option expects a font directive as its value,
351 % e.g., |\bfseries| (which is also the default). Using this option
352 % without supplying a value is equivalent to supplying an empty
353 % value. It will be used to determine the font for the gap material
354 % regardless of the mode. This is important to ensure that the gaps
355 % always have the same width regardless of whether or not the material
356 % is shown.
357 %
358 % For the example puzzle above it was set to |\itshape|, which you can
359 % see in the puzzle answer.
360 % \item[\option{dash}] Short name for \option{gap-format}|=dash|.
361 % \item[\option{dot}] Short name for \option{gap-format}|=dot|.
362 % \end{description}
363 %
364 % \subsubsection{Gap numbers}
365 %
366 % Producing the gap numbers is handled by the following options:
367 % \begin{description}
368 % \item[\option{gap-numbers}] Boolean that determines whether or not gap numbers
369 % are displayed. Default is |true|.
370 %
371 % \item[\option{gap-number-format}] Code that is executed when a gap number is
372 % produced. Default is \verb*|\textnormal{ (\thegapnumber)}|.
373 % \item[\option{numbers}] Short name for \option{gap-numbers}.
374 % \end{description}
375 %
376 % There is also a way to control displaying the total number of gaps:
377 % \begin{description}
378 % \item[\option{display-total-gaps}] Boolean to determine if the total number of
379 % gaps should be shown at the very end of the document. Default is
380 % |false|.
381 % \item[\option{displaynbgaps}] This is just another name for the same boolean;
382 % it was used in the first version of the package.
383 % \end{description}
384 %
385 %
386 %
387 % \subsubsection{Gap widening}
388 %
389 % Finally, for extending the gap width we have these options:
390 % \begin{description}
391 % \item[\option{gap-widen}] Boolean that decides if the gaps should be made wider
392 % or not (default is |false| but mainly for historical reasons).
393 % \item[\option{gap-extend-minimum}] Minimum of extra space that should be added
394 % to each gap if gap widening is active. Default is |20pt|, i.e.,
395 % |10pt| on either side.
396 % \item[\option{gap-extend-percent}] Percentage (as a number) by which the gap should be made
397 % wider if widening is active. The result is compared to
398 % \option{gap-extend-minimum} and the larger of the two is
399 % used. Default is |20|.
400 % \item[\option{widen}] Short name for \option{gap-widen}.
401 % \end{description}
402 %
403 %
404 %
405 %
406 % \section{Differences from the original package}
407 %
408 % The main user interface of the two versions is identical, so it is
409 % possible to use the new version as a drop-in replacement for the
410 % old. However, the feature set in form of key/value options has been
411 % greatly extended, offering functionality previously
412 % unavailable. Furthermore, a number of bugs have been corrected (and
413 % possibly new ones introduced).
414 %
415 % \begin{itemize}
416 % \item
417 % Stray spaces in the definition of \cs{gap} (that showed up in
418 % the output) have been eliminated.
419 % \item
420 % Various combinations of options that didn't work are now possible.
421 % \item
422 % Explicit hyphenations |\-| showed up in gap mode, now they can be used.
423 % \item
424 % Nesting isn't possible for obvious reasons, but the fact is now
425 % detected and catered to by ignoring the inner gap requests after
426 % generating an error.
427 % \item
428 % Option names have been normalized (though the original names are
429 % still available).
430 % \item
431 % The option \option{phantomtext} is no longer necessary, though still
432 % supported (with a warning) as a no-op.
433 % \item
434 % The names of the \LaTeX{} counters used have changed, so if you
435 % directly addressed them that would need changing.
436 % \item
437 % The font used in teacher mode (by default boldface) is now also
438 % used if gap mode is chosen, to ensure that the output in all
439 % modes produces identical line breaks; for the same reason, the
440 % \pkg{ulem} machinery is always used, even if not underlining (or
441 % dashing, etc.).
442 % \item The gaps can be extended by a percentage or by a minimum
443 % amount to ensure that there is enough space to fill in the text
444 % (given that hand-written text is typically wider than typeset
445 % material); the values are adjustable.
446 % \item
447 % \cs{gap} now has an optional argument through which you can
448 % explicitly request the type of underlining you want to use.
449 % \item
450 % \cs{gap} also supports a star form which toggles the setting of gap numbers.
451 % \item
452 % The use of \cs{label} within the \cs{gap} command argument allows for
453 % later reference to that gap by its number (provided a gap number is typeset).
454 % \item The implementation is done with \texttt{expl3}, the programming
455 % language for \LaTeX3. Although invisible to the user, in some sense
456 % that was the main purpose of
457 % the exercise: to see how easy it is to convert a package and use
458 % the extended features of \texttt{expl3}.
459 % \end{itemize}
460 %
461 %
462 % \section{Solution to the puzzle} \label{sec:answer}
463 %
464 % \TeacherModeOn
465 %
466 % Here we repeat the puzzle from above with \cs{TeacherModeOn}.
467 % \par\smallskip
468 % \noindent\hfill\llap{\setlength\fboxsep{10pt}
469 % \fbox{\begin{minipage}{1.2\textwidth}
470 % \puzzletext
471 % \end{minipage}\hskip\marginparsep}}
472 % \par\smallskip
473 % This was produced using the following changes to the defaults:
474 % \begin{verbatim}
475 % \dashundergapssetup{
476 % ,gap-number-format = \,\textsuperscript{\normalfont
477 % (\thegapnumber)}
478 % ,gap-font = \itshape
479 % ,teacher-gap-format = underline
480 % ,gap-widen
481 % }
482 % \end{verbatim}
483 % As you can see we use |\itshape| for the font (to be able to show
484 % the bold face in one of the answers) and also force underlining in
485 % teacher mode to better show the gap widening. The gap number is
486 % raised and we separate it a tiny bit from the gap material. We also
487 % use \cs{normalfont} in the formatting to ensure that the gap number
488 % is set upright and not in italic shape.
489 %
490 %
491 % \StopEventually{
492 % \begin{thebibliography}{1}
493 %\bibitem{tub-wao-code}
494 % Frank Mittelbach.
495 % \newblock The \pkg{widows-and-orphans} package.
496 % \newblock \textsl{TUG}boat 39:3,
497 % \ifx\thisissuepageref\undefined ^^A undefined if non-TUGboat
498 % 20018.\\
499 % \else \thisissuepageref{mitt-widows-code}, 2018.\fi
500 % \newblock \url{https://ctan.org/pkg/widows-and-orphans}
501 % \bibitem{expl3}
502 % \LaTeX3 Project Team.
503 % \newblock A collection of articles on \pkg{expl3}.\\
504 % \url{https://latex-project.org/publications/indexbytopic/l3-expl3/}
505 %\end{thebibliography}
506 % \ifx\thisissuepageref\undefined ^^A is this TUB production ??? if not gen index
507 % \setlength\IndexMin{200pt} \PrintIndex
508 % \fi}
509 %
510 %
511 % \newpage
512 %
513 %
514 % \DoNotIndex{\ ,\advance,\begingroup,\bgroup,\def,\else,\endgroup,\fi}
515 % \DoNotIndex{\hbox,\ifx,\kern,\let,\lower,\@M,\@empty,\c@gapnumber}
516 % \DoNotIndex{\c@totalgapnumber,\hb@xt@,\LA@penalty,\UL@box,\UL@leaders}
517 % \DoNotIndex{\UL@leadtype,\UL@setULdepth,\UL@skip,\UL@start,\z@,\ULdepth}
518 % \DoNotIndex{\ULon,\vrule,\wd,\@width,\UL@putbox,\markoverwith}
519 % \DoNotIndex{\char,\cs_new:Npn,\cs_set:Npn,\dim_new:N,\font,\global,\hyphenchar}
520 % \DoNotIndex{\setbox,\string,\UL@hyphenbox,\UL@start}
521 % \DoNotIndex{\tl_new:N,\tl_set:Nn,\ifnum,\UL@stop,\dim_set:Nn,\box}
522 % \DoNotIndex{\discretionary,\sixly,\p@,\usepackage,\ignorespaces}
523 % \DoNotIndex{\cs_set_eq:NN}
524 %
525 %
526 %
527 % \section{The implementation}
528 %
529 % \subsection{Loading and fixing/changing \pkg{ulem}}
530 %
531 % The first thing to do is to load \pkg{ulem} without changing \cs{emph}
532 % or \cs{em}:
533 % \begin{macrocode}
534 %<*package>
535 \RequirePackage[normalem]{ulem}
536 % \end{macrocode}
537 %
538 % The code in this section follows \LaTeXe{} conventions, i.e., models
539 % the commands as they look in the \pkg{ulem} package.
540 %
541 % \begin{macro}{\dotuline}
542 % The dots produced by \cs{dotuline} depend on the current font,
543 % which is a somewhat questionable design\Dash if you underline a text
544 % with a single bold word somewhere inside it will change the
545 % shape of the dot line. So we always use the \cs{normalfont}
546 % dot (this is not done in the original definition).
547 % \changes{v2.0f}{2020/01/22}{Adjusted definition to new ulem release}
548 % \begin{macrocode}
549 \protected\def\dotuline{\leavevmode\bgroup
550 \UL@setULdepth
551 \ifx\UL@on\UL@onin \advance\ULdepth2\p@\fi
552 \markoverwith{\begingroup
553 % \advance\ULdepth0.08ex
554 \lower\ULdepth\hbox{\normalfont \kern.1em .\kern.04em}%
555 \endgroup}%
556 \ULon}
557 % \end{macrocode}
558 % \end{macro}
559 %
560 %
561 %
562 % \begin{macro}{\uwave}
563 % The original \cs{uwave} used a hard-wired value of |3.5pt| for
564 % the lowering. We change that to be based on the current
565 % value of \cs{ULdepth} so that the user (or this package here)
566 % can change the placement.
567 % \changes{v2.0f}{2020/01/22}{Adjusted definition to new ulem release}
568 % \begin{macrocode}
569 \protected\def\uwave{\leavevmode\bgroup
570 \UL@setULdepth
571 \advance\ULdepth 0.6\p@
572 \markoverwith{\lower\ULdepth\hbox{\sixly \char58}}\ULon}
573 % \end{macrocode}
574 % \end{macro}
575 %
576 %
577 % \begin{macro}[int]{\fmdug@ublank}
578 % \cs{fmdug@ublank} underlines with blanks. Normally not especially useful
579 % (which is why we make it internal),
580 % but if we want to have \pkg{ulem} acting, but without actually
581 % visibly underlining, this is the command to use.
582 % \begin{macrocode}
583 \def\fmdug@ublank{\bgroup\let\UL@leadtype\@empty\ULon}
584 % \end{macrocode}
585 % \end{macro}
586 %
587 %
588 %
589 % \begin{macro}[int]{\UL@dischyp}
590 % \begin{macro}[int]{\UL@putbox}
591 % We need to do a little patching to ensure that nothing is output
592 % by the \pkg{ulem} commands if we don't want it to. So the next two
593 % commands are from \pkg{ulem} with |\box| replaced by
594 % |\fmdug@box| so that we can change the behavior.
595 % \begin{macrocode}
596 \def\UL@dischyp{\global\setbox\UL@hyphenbox\hbox
597 {\ifnum \hyphenchar\font<\z@ \string-\else \char\hyphenchar\font \fi}%
598 \kern\wd\UL@hyphenbox \LA@penalty\@M
599 \UL@stop \kern-\wd\UL@hyphenbox
600 \discretionary{\fmdug@box\UL@hyphenbox}{}{}\UL@start}
601 % \end{macrocode}
602 %
603 % \begin{macrocode}
604 \def\UL@putbox{\ifx\UL@start\@empty \else % not inner
605 \vrule\@width\z@ \LA@penalty\@M
606 {\UL@skip\wd\UL@box \UL@leaders \kern-\UL@skip}%
607 \fmdug@box\UL@box \fi}
608 % \end{macrocode}
609 % \end{macro}
610 % \end{macro}
611 %
612 %
613 %
614 % \begin{macro}[int]{\fmdug@box}
615 % By default we output the box in the commands above, but when we
616 % don't want to output anything visible we change the definition to
617 % generate a box with empty content but the right size.
618 % \begin{macrocode}
619 \let\fmdug@box\box
620 % \end{macrocode}
621 % \end{macro}
622 %
623 %
624 %
625 %
626 %
627 %
628 %
629 % \subsection{The main implementation part}
630 %
631 % The rest of the package is written in \texttt{expl3}. We use
632 % \texttt{fmdug} as our internal prefix.
633
634 % \begin{macrocode}
635 %<@@=fmdug>
636 % \end{macrocode}
637 %
638 % We need the package \pkg{xparse} for specifying the document-level
639 % interface commands and \pkg{l3keys2e} to use the \pkg{expl3} key
640 % value methods within \LaTeXe{}. These packages automatically
641 % require \pkg{expl3} so there is no need to load that explicitly
642 % and nowadays the core of \pkg{xparse} is part of the \LaTeX{} kernel.
643 % \begin{macrocode}
644 \RequirePackage{l3keys2e}
645 % \end{macrocode}
646 %
647 % As the code uses some functions from \pkg{expl3} that got
648 % introduced sometime in 2018 we need to require a fairly recent
649 % version (the date is somewhat arbitrarily picked).
650 % \begin{macrocode}
651 \@ifpackagelater{expl3}{2018-06-24}
652 {}
653 {%
654 \PackageError{dashundergaps}{Support package l3kernel too old}
655 {%
656 Please install an up to date version of l3kernel\MessageBreak
657 using your TeX package manager or from CTAN.\MessageBreak
658 \MessageBreak
659 Loading dashundergaps will abort!%
660 }%
661 \endinput
662 }
663 % \end{macrocode}
664 %
665 % Here we introduce the package and specify its version number:
666 % \begin{macrocode}
667 \ProvidesExplPackage{dashundergaps}
668 {\dashundergapsdate}
669 {\dashundergapsversion}
670 {Dashing and underlining phantom text}
671 % \end{macrocode}
672 %
673 %
674 % \subsubsection{User interface commands}
675 %
676
677 % \begin{macro}{\gap}
678 % The \cs{gap} command parses for a star, optional and mandatory
679 % argument and then calls \cs{@@_gap:nnn} to do the work.
680 % \changes{v2.0g}{2020/02/11}{Expand argument up front to work around
681 % ulem restrictions if possible (gh/10)}
682 % \begin{macrocode}
683 \DeclareDocumentCommand \gap { som }
684 {
685 % \end{macrocode}
686 % We try to expand as much as possible up front to avoid the
687 % \pkg{ulem} limitations:
688 % \begin{macrocode}
689 \protected@edef\next{#3}
690 % \end{macrocode}
691 % Use the \enquote{content} of \cs{next} in the processing:
692 % \begin{macrocode}
693 \@@_gap:nno {#1}{#2}{ \next } }
694 % \end{macrocode}
695 % \end{macro}
696 %
697 %
698 % \begin{macro}{\dashundergapssetup}
699 % Change options anywhere.
700 % \begin{macrocode}
701 \NewDocumentCommand \dashundergapssetup { m }
702 { \keys_set:nn {fmdug} {#1} \ignorespaces }
703 % \end{macrocode}
704 % \end{macro}
705 %
706 %
707 % \begin{macro}{\TeacherModeOn}
708 % \begin{macro}{\TeacherModeOff}
709 % We provide shortcuts for turning teacher mode on or off.
710 % \begin{macrocode}
711 \DeclareDocumentCommand \TeacherModeOn {}
712 { \bool_set_true:N \l_@@_teacher_bool }
713 \DeclareDocumentCommand \TeacherModeOff {}
714 { \bool_set_false:N \l_@@_teacher_bool }
715 % \end{macrocode}
716 % \end{macro}
717 % \end{macro}
718 %
719 %
720 %
721 %
722 % \subsubsection{Counters}
723 %
724 % \begin{macro}[int]{\c@gapnumber}
725 % We have one user-level counter which is referenceable and holds
726 % the gap number of the current gap. It can be reset to 0 to
727 % restart counting.
728 % \begin{macrocode}
729 \newcounter{gapnumber}
730 % \end{macrocode}
731 % \end{macro}
732 %
733 %
734 % \begin{macro}[int]{\c@totalgapnumber}
735 % We also keep track of all gaps ever made using another user-level
736 % counter. Since this one is supposed to keep track of the total
737 % number of gaps, it makes little sense to modify it at the
738 % document level. However, there may be use cases even for that and
739 % more importantly, by making it a user-level counter it is
740 % possible to refer to the total number of gaps easily, e.g., via
741 % \cs{thetotalgapnumber}.
742 % ^^A\makeatletter\@endparpenalty=10000\makeatother
743 % \begin{macrocode}
744 \newcounter{totalgapnumber}
745 % \end{macrocode}
746 % \end{macro}
747
748 % \begin{macro}{\l_@@_extend_dim}
749 % A help register to calculate the gap width later on.
750 % \begin{macrocode}
751 \dim_new:N \l_@@_extend_dim
752 % \end{macrocode}
753 % \end{macro}
754 %
755 %
756 %
757 % \begin{macro}{\l_@@_extra_left_gap_tl}
758 % \begin{macro}{\l_@@_extra_right_gap_tl}
759 % Two scratch token lists to enlarge the gap on the left or right side.
760 % \begin{macrocode}
761 \tl_new:N \l_@@_extra_left_gap_tl
762 \tl_new:N \l_@@_extra_right_gap_tl
763 % \end{macrocode}
764 % \end{macro}
765 % \end{macro}
766 %
767 %
768 % \begin{macro}{\l_@@_gap_format_tl}
769 % \begin{macro}{\l_@@_teacher_gap_format_tl}
770 % The gap formatting is normally handled by a \pkg{ulem}
771 % command; which one depends on the options used. To record the
772 % choice we store it in a token list (one for normal and one for
773 % teacher mode).
774 % \begin{macrocode}
775 \tl_new:N \l_@@_gap_format_tl
776 \tl_new:N \l_@@_teacher_gap_format_tl
777 % \end{macrocode}
778 % \end{macro}
779 % \end{macro}
780 %
781 % \subsubsection{Messages}
782 %
783 % \begin{macrocode}
784 \msg_new:nnn {dashundergaps} {deprecated}
785 { The~ #1~ `#2'~ you~ used~ \msg_line_context: \ is~ deprecated~ and~
786 there~ is~ no~ replacement.~ Since~ I~ will~ not~ guarantee~ that~
787 #1~ `#2'~ will~ be~ kept~ forever~ I~ strongly~ encourage~ you~
788 to~ remove~ it~ from~ your~ document. }
789 % \end{macrocode}
790 %
791 % \begin{macrocode}
792 \msg_new:nnnn {dashundergaps} {nested}
793 { The~ \gap command~ can't~ be~ nested! }
794 { Nesting~ doesn't~ make~ much~ sense~ as~ the~ inner~ one~
795 wouldn't~ be~ visible.~ ~ To~ allow~ further~ processing~ it~ is~
796 handled~ as~ if~ it~ hasn't~ been~ asked~ for. }
797 % \end{macrocode}
798 %
799 %
800 % \begin{macrocode}
801 \msg_new:nnnn {dashundergaps} {gap-format-value}
802 { Unknown~ value~ for~ key~ '#1 gap-format'! }
803 { Supported~ values~ are~ 'underline',~ 'double-underline',\\
804 'dash',~ 'dot',~ 'wave'~ or~ 'blank'. }
805 % \end{macrocode}
806 %
807 %
808 %
809 % \subsubsection{Option handling}
810 %
811 % Here we define all the possible option keys for use either as package
812 % options or inside
813 % \cs{dashundergapssetup}. These are all straightforward assignments
814 % to variables. These internal variables are declared by the key
815 % declarations if unknown, so they are not separately declared beforehand.
816 % \begin{macrocode}
817 \keys_define:nn {fmdug}
818 {
819 % ====================================
820 ,teacher-mode .bool_set:N = \l_@@_teacher_bool
821 ,teacher-mode .default:n = true
822 ,teacher-mode .initial:n = false
823 % ------------------
824 ,gap-mode .bool_set_inverse:N = \l_@@_teacher_bool
825 % ====================================
826 ,gap-format
827 .choice:
828 % \end{macrocode}
829 %
830 % In the case of dashes and even more so in the case of dots, it looks
831 % fairly ugly if they are below the baseline as if there were text
832 % above. We therefore raise them up a bit if the option
833 % \texttt{gap-format-adjust} is given (which is the default).
834 %
835 % In the case of dots we undo
836 % exactly the amount by which they are lowered in \pkg{ulem} so
837 % that they end up precisely at the baseline, in case they are
838 % followed by a real dot. In other cases we stay a bit below the baseline.
839 %
840 % The same is done below when the optional argument is
841 % evaluated. But we don't do this in teacher mode since there we
842 % \emph{will} have text above and we don't want to bump into that.
843 %
844 % \begin{macrocode}
845 ,gap-format / underline
846 .code:n = \tl_set:Nn \l_@@_gap_format_tl
847 { \@@_gap_format_adjust:n{.4pt} \uline }
848 ,gap-format / double-underline
849 .code:n = \tl_set:Nn \l_@@_gap_format_tl
850 { \@@_gap_format_adjust:n{2pt} \uuline }
851 ,gap-format / dash
852 .code:n = \tl_set:Nn \l_@@_gap_format_tl
853 { \@@_gap_format_adjust:n{0pt} \dashuline }
854 ,gap-format / dot
855 .code:n = \tl_set:Nn \l_@@_gap_format_tl
856 { \@@_gap_format_adjust:n{-.08ex} \dotuline }
857 ,gap-format / wave
858 .code:n = \tl_set:Nn \l_@@_gap_format_tl
859 { \@@_gap_format_adjust:n{1pt} \uwave }
860 ,gap-format / blank
861 .code:n = \tl_set:Nn \l_@@_gap_format_tl { \fmdug@ublank }
862 ,gap-format / unknown
863 .code:n = \msg_error:nnn{dashundergaps}{gap-format-value}{}
864 ,gap-format
865 .initial:n = underline
866 % ====================================
867 % \end{macrocode}
868 % This controls the raising of the gap underline by some
869 % amount. We implement it as a |.choice| even though it looks like
870 % a boolean.
871 %\begingroup\hfuzz=15pt
872 % \begin{macrocode}
873 ,gap-format-adjust
874 .choice:
875 ,gap-format-adjust / true
876 .code:n = \cs_set:Npn \@@_gap_format_adjust:n ##1
877 { \setlength\ULdepth {##1} }
878 ,gap-format-adjust / false
879 .code:n = \cs_set_eq:NN \@@_gap_format_adjust:n \use_none:n
880 ,gap-format-adjust
881 .default:n = true
882 ,gap-format-adjust
883 .initial:n = true
884 ,adjust .meta:n = { gap-format-adjust }
885 % ====================================
886 ,teacher-gap-format
887 .choice:
888 ,teacher-gap-format / underline
889 .code:n = \tl_set:Nn \l_@@_teacher_gap_format_tl { \uline }
890 ,teacher-gap-format / double-underline
891 .code:n = \tl_set:Nn \l_@@_teacher_gap_format_tl { \uuline }
892 ,teacher-gap-format / dash
893 .code:n = \tl_set:Nn \l_@@_teacher_gap_format_tl { \dashuline }
894 ,teacher-gap-format / dot
895 .code:n = \tl_set:Nn \l_@@_teacher_gap_format_tl { \dotuline }
896 ,teacher-gap-format / wave
897 .code:n = \tl_set:Nn \l_@@_teacher_gap_format_tl { \uwave }
898 ,teacher-gap-format / blank
899 .code:n = \tl_set:Nn \l_@@_teacher_gap_format_tl { \fmdug@ublank }
900 ,teacher-gap-format / unknown
901 .code:n = \msg_error:nnn{dashundergaps}{gap-format-value}{teacher-}
902 ,teacher-gap-format
903 .initial:n = blank
904 % ====================================
905 ,gap-widen .bool_set:N = \l_@@_gap_widen_bool
906 ,gap-widen .default:n = true
907 ,gap-widen .initial:n = false
908 % ------------------
909 ,widen .meta:n = { gap-widen }
910 % ------------------
911 ,gap-extend-minimum .dim_set:N = \l_@@_gap_min_dim
912 ,gap-extend-minimum .initial:n = 20pt
913 % ------------------
914 ,gap-extend-percent .tl_set:N = \l_@@_gap_percent_tl
915 ,gap-extend-percent .initial:n = 20
916 % ====================================
917 ,gap-numbers .bool_set:N = \l_@@_number_bool
918 ,gap-numbers .default:n = true
919 ,gap-numbers .initial:n = true
920 % ------------------
921 ,numbers .meta:n = { gap-numbers }
922 % ------------------
923 ,gap-number-format .tl_set:N = \l_@@_gapnum_format_tl
924 ,gap-number-format .initial:n = \textnormal{\space (\thegapnumber)}
925 % ====================================
926 ,display-total-gaps .bool_gset:N = \g_@@_display_total_gaps_bool
927 ,display-total-gaps .default:n = true
928 ,display-total-gaps .initial:n = false
929 % ====================================
930 ,gap-font .tl_set:N = \l_@@_font_tl
931 ,gap-font .default:n =
932 ,gap-font .initial:n = \bfseries
933 % \end{macrocode}
934 % And finally the original options, now as aliases:
935 % \begin{macrocode}
936 % ====================================
937 ,teachermode .meta:n = { teacher-mode }
938 ,dash .meta:n = { gap-format = dash }
939 ,dot .meta:n = { gap-format = dot }
940 ,displaynbgaps .meta:n = { display-total-gaps }
941 % ------------------
942 ,phantomtext
943 .code:n = \msg_warning:nnnn{dashundergaps}{deprecated}
944 {option}{phantomtext}
945 % ====================================
946 }
947 % \end{macrocode}
948 %\endgroup
949 %
950 %
951 % \begin{macro}{\@@_gap:nnn}
952 % At last, here comes the action. \cs{@@_gap:nn} expects three
953 % arguments: |#1| identifies if a star was present, |#2| indicates
954 % what kind of ``underlining'' is wanted (anything not recognized
955 % is ignored, in particular ``--NoValue--'' if \cs{gap} was used
956 % without an optional argument) and |#3| is the material to produce
957 % a gap for.
958 % \begin{macrocode}
959 \cs_new:Npn\@@_gap:nnn #1#2#3 {
960 % \end{macrocode}
961 %
962 % \begin{macrocode}
963 \group_begin:
964 % \end{macrocode}
965 % Define the font used inside the gap. We need to do this up front
966 % since we want to measure the text (and that needs the correct
967 % font already).
968 % \begin{macrocode}
969 \l_@@_font_tl
970 % \end{macrocode}
971 % Nesting is not supported so inside the gap we redefine
972 % \cs{@@_gap:nnn} to raise an error and just return the third argument if it is
973 % encountered again.
974 % \begin{macrocode}
975 \cs_set:Npn \@@_gap:nnn ##1##2##3
976 {
977 \msg_error:nn{dashundergaps}{nested}
978 ##3
979 }
980 % \end{macrocode}
981 % We always increment the counter for the total number of gaps, but
982 % increment the |gapnumber| only if we are displaying it. For the latter one
983 % we use \cs{refstepcounter} to make it referenceable.
984 % \begin{macrocode}
985 \stepcounter{totalgapnumber}
986 \bool_xor:nnT { #1 } { \l_@@_number_bool }
987 { \refstepcounter{gapnumber} }
988 % \end{macrocode}
989 % Next we prepare for widening if that is being asked for: Measure
990 % the width of the text and then set \cs{l_@@_extend_dim} to be the
991 % requested percentage divided by two of that width (since we add
992 % it later on both sides).
993 % \begin{macrocode}
994 \bool_if:NTF \l_@@_gap_widen_bool
995 {
996 \settowidth \l_@@_extend_dim {#3}
997 \dim_set:Nn \l_@@_extend_dim
998 { \l_@@_gap_percent_tl \l_@@_extend_dim / 200 }
999 % \end{macrocode}
1000 % Then compare it to the minimum / 2 and choose whatever is larger.
1001 % \begin{macrocode}
1002 \dim_compare:nNnT \l_@@_extend_dim < { .5\l_@@_gap_min_dim }
1003 { \dim_set:Nn \l_@@_extend_dim { .5\l_@@_gap_min_dim } }
1004 % \end{macrocode}
1005 % Now we prepare what needs to go to the left and the right of the gap.
1006 % \begin{macrocode}
1007 \tl_set:Nn \l_@@_extra_left_gap_tl
1008 { \hbox_to_wd:nn\l_@@_extend_dim{} \allowbreak }
1009 \tl_set:Nn \l_@@_extra_right_gap_tl
1010 { \allowbreak \hbox_to_wd:nn\l_@@_extend_dim{} }
1011 }
1012 % \end{macrocode}
1013 % And if no widening is asked for we clear these two token lists so
1014 % they don't do anything.
1015 % \begin{macrocode}
1016 {
1017 \tl_clear:N \l_@@_extra_left_gap_tl
1018 \tl_clear:N \l_@@_extra_right_gap_tl
1019 }
1020 % \end{macrocode}
1021 % Next comes deciding the gap format. If in teacher mode it will be
1022 % whatever is in \cs{l_@@_teacher_gap_tl}. Otherwise, either it is
1023 % based on the content of the optional argument or, if that is not
1024 % given or unknown, it will be \cs{l_@@_gap_format_tl}.
1025 % \begin{macrocode}
1026 \bool_if:NTF \l_@@_teacher_bool
1027 { \l_@@_teacher_gap_format_tl }
1028 {
1029 % \end{macrocode}
1030 % But before we execute any of the \pkg{ulem} commands we make sure
1031 % that they do not output text.
1032 % \begin{macrocode}
1033 \cs_set:Npn \fmdug@box ##1 {\hbox_to_wd:nn{\box_wd:N ##1}{}}
1034 \str_case:nnF {#2}
1035 {
1036 {u} { \@@_gap_format_adjust:n{.4pt} \uline }
1037 {d} { \@@_gap_format_adjust:n{2pt} \uuline }
1038 {w} { \@@_gap_format_adjust:n{1pt} \uwave }
1039 {b} { \fmdug@ublank }
1040 {.} { \@@_gap_format_adjust:n{-.08ex} \dotuline }
1041 {-} { \@@_gap_format_adjust:n{0pt} \dashuline }
1042 }
1043 { \l_@@_gap_format_tl }
1044 }
1045 % \end{macrocode}
1046 % Whatever was decided as the gap format, it needs one argument,
1047 % i.e., the material (with possible gap extension on both sides).
1048 % \begin{macrocode}
1049 {\l_@@_extra_left_gap_tl #3 \l_@@_extra_right_gap_tl }
1050 % \end{macrocode}
1051 % Finally we typeset the gap number if that was requested.
1052 % \begin{macrocode}
1053 \bool_xor:nnT { #1 } { \l_@@_number_bool }
1054 { \l_@@_gapnum_format_tl }
1055 % \end{macrocode}
1056 % Close the group from above to keep any of the redefinitions confined.
1057 % \begin{macrocode}
1058 \group_end:
1059 }
1060 % \end{macrocode}
1061 %
1062 % \begin{macrocode}
1063 \cs_generate_variant:Nn \@@_gap:nnn {nno}
1064 % \end{macrocode}
1065 % \end{macro}
1066 %
1067 %
1068 %
1069 % \begin{macro}{\@@_display_total_gaps:}
1070 % This command will display the total number of gaps if
1071 % requested. The hard-wired formatting comes from the first
1072 % version of the package.
1073 % \begin{macrocode}
1074 \cs_new:Npn \@@_display_total_gaps: {
1075 \vfill \centering
1076 \bfseries Total~ Gaps:~ \thetotalgapnumber
1077 }
1078 % \end{macrocode}
1079 % \end{macro}
1080 %
1081 %
1082 %
1083 % \subsubsection{Closing shop}
1084 %
1085 % At the end of the document we typeset the total number of gaps if requested.
1086 % \begin{macrocode}
1087 \AtEndDocument{
1088 \bool_if:NT \g_@@_display_total_gaps_bool
1089 \@@_display_total_gaps:
1090 }
1091 % \end{macrocode}
1092 % So what remains to be done is executing all options passed to the
1093 % package via \cs{usepackage}.
1094 % \begin{macrocode}
1095 \ProcessKeysPackageOptions{fmdug}
1096 %</package>
1097 % \end{macrocode}
1098 %
1099 % \Finale
1100 %
1101 %
1102 \endinput