| 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 |