diff options
author | Karl Berry <karl@freefriends.org> | 2018-06-24 21:57:27 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2018-06-24 21:57:27 +0000 |
commit | c4bb697eced0fab994df2daf28104ba68e977bcc (patch) | |
tree | 2325a1699a36aa9597b42fd85b0c51de0f44adb1 /Master/texmf-dist/source/latex/dashundergaps | |
parent | dd42876a9fee2d151acc9477f3f9faf2e1475ce2 (diff) |
dashundergaps (24jun18)
git-svn-id: svn://tug.org/texlive/trunk@48081 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source/latex/dashundergaps')
-rw-r--r-- | Master/texmf-dist/source/latex/dashundergaps/dashundergaps.dtx | 800 | ||||
-rw-r--r-- | Master/texmf-dist/source/latex/dashundergaps/dashundergaps.ins | 67 |
2 files changed, 867 insertions, 0 deletions
diff --git a/Master/texmf-dist/source/latex/dashundergaps/dashundergaps.dtx b/Master/texmf-dist/source/latex/dashundergaps/dashundergaps.dtx new file mode 100644 index 00000000000..cd0067807bf --- /dev/null +++ b/Master/texmf-dist/source/latex/dashundergaps/dashundergaps.dtx @@ -0,0 +1,800 @@ +% \iffalse meta-comment +% +%% File: dashundergaps.dtx (C) Copyright 2018 Frank Mittelbach +% +% It may be distributed and/or modified under the conditions of the +% LaTeX Project Public License (LPPL), either version 1.3c of this +% license or (at your option) any later version. The latest version +% of this license is in the file +% +% https://www.latex-project.org/lppl.txt +% +% +% The development version of the bundle can be found below +% +% https://github.com/FrankMittelbach/fmitex/ +% +% for those people who are interested or want to report an issue. +% +%<*driver> +\documentclass{l3doc} +\usepackage{dashundergaps,multicol} +\EnableCrossrefs +\CodelineIndex +\begin{document} + \DocInput{dashundergaps.dtx} +\end{document} +%</driver> +% +% \fi +% +% +% \newcommand\option[1]{\texttt{#1}} +% +% \title{The \texttt{dashundergaps} package\thanks{A reimplementation of +% a package originally written by Luca Merciadri in 2010.}} +% \author{Frank Mittelbach} +% +% \maketitle +% +% \begin{abstract} +% The \pkg{dashundergaps} package offers the possibility to replace +% material in running text with white space in order to build up forms +% that can be filled in at a later time. +% +% By default the gaps are underlined and followed by a gap number in +% parentheses, but many other designs are possible, e.g., dashes or +% dots instead of the underline, no gap numbers or a different format +% for them, gap widening for easier fill-in, etc. +% +% There is also a teacher's mode which shows the normally hidden text +% in a special (customizable) format. +% \end{abstract} +% +% \section{Introduction} +% +% The \pkg{dashundergaps} package provides a single command \cs{gap} +% which takes its argument and produces a gap of a width matching its +% width. To better mark this gap it is underlined in some form (could be +% a solid line, a dashed or dotted line or even a \uwave{wriggling +% line}). Furthermore, each gap might be numbered to be able to easily +% refer to it. Here is an example in form of a puzzle: +% +% +% \newcommand\puzzletext{% +% \begin{quote} +% The initial `E.' in Donald E. Knuth's name stands for \gap*{Erwin}. +% The well-known answer to the Ultimate Question \gap{of Life, the +% Universe, and Everything} is 42 according to \gap{Douglas Adams}. +% The first edition of \gap{The \LaTeX{} Companion} celebrates silver +% anniversary in 2019. Historically speaking, \texttt{expl3} stands for +% \gap{\textbf{EX}perimental \textbf{P}rogramming \textbf{L}anguage +% \textbf{3}} even though it is a production language these days. +% \end{quote}} +% +% \dashundergapssetup{ +% ,gap-number-format = \,\textsuperscript{\normalfont(\thegapnumber)} +% ,gap-font = \itshape +% ,teacher-gap-format = underline +% ,gap-widen +% } +% +% \puzzletext +% And here are some hints for it if you want to fill it out: +% \begin{quote} +% \begin{multicols}{2} +% \begin{enumerate} +% \item If everything would be that easy to answer. +% \item The author of ``Last Chance To See'' and a famous +% radio~show. +% \item Back then known as the doggie book. +% \item Old names die hard.\\ +% \mbox{} % manual to get same height +% \end{enumerate} +% \end{multicols} +% \end{quote} +% The answer is given in Section~\ref{sec:answer} that shows the gaps +% filled in, which is due to a, so called, teacher mode that can be activated. +% +% As you see some gaps are numbered with a superscript number (not the +% default setting) while others aren't. How this is done and how to +% change the result is explained in the next section. +% +% There also exists a ``teacher mode'' in which the the gaps are filled +% with the text given in the argument. This can be used to show the +% correct answers of some test (as we do in Section~\ref{sec:answer}) or +% to give a sample fill-in for some form, to help people to fill it out +% correctly. The ``teacher mode'' will produce the same line breakings +% because ensures that the fill-ins take the same about of space as the +% gaps. +% +% Another important feature is the possibility to artificially widen the +% gaps (compared to the textual material in the argument). After all, +% when a form is filled by hand people typically need more space to +% write some text compared to the same text being typeset. So making the +% gaps simply as wide as the material may result in too little +% space. +% +% +% \section{The user interface} +% +% +% The \pkg{dashundergaps} package is built as a small application on top +% of the \pkg{ulem} package, a package that defines a number of commands for +% underling \meta{simple-text} in various ways. +% \begin{function}{\uline,\uwave,\dashuline,\dotuline} +% \begin{syntax} +% \cs{uline}\Arg{simple-text} \cs{uwave}\Arg{simple-text} % etc. +% \end{syntax} +% This means that by loading +% \pkg{dashundergaps} the \pkg{ulem} commands such as \cs{uline}, +% \cs{uwave} and so forth are automatically made available. +% These commands are used to do most of +% the work and the current package only makes sure that instead of the +% words empty boxes of the same width are are used by \pkg{ulem}. This +% way we get underlined gaps of the right size. +% +% \end{function} +% +% By default, \pkg{ulem} would change \cs{emph} to underline text, so +% for this application it is loaded with the option \texttt{normalem} to +% prevent that from happening. +% +% +% +% \begin{function}{\gap} +% \begin{syntax} +% \cs{gap}*\oarg{type}\Arg{text} +% \end{syntax} +% The main command provided by the package is \cs{gap} which expects a +% mandatory \meta{text} argument containing the material that is used +% to produce the gap (and normally invisible). By default the gap is +% underlined (though that could be changed). +% +% The optional \meta{style} argument explicitly defines a certain type +% of underlining: |u| stands for normal underlining (via \cs{uline}), +% |w| for a wave line (via \cs{uwave}), |b| for blank (i.e., no +% underlining whatsoever), ``|-|'' for a dash-line (via \cs{dashuline}) +% and finally ``|.|'' for underlining with dots (via \cs{dotuline}). +% +% By default gaps are numbered using the counter \texttt{gapnumber} +% and this number is shown in parentheses after the gap. With the star +% form the generation of the number can be toggled, i.e., if it is +% normally produced because of the current option settings it will be +% suppressed, if it is suppressed through an option it will be +% typeset. This way one can select the most convenient setting via an +% option for the whole document and use the |*| to toggle it +% occasionally. +% +% Since \cs{gap} uses \pkg{ulem} commands it inherits the limitations +% of these commands, in that only simple text can be used in the +% \meta{text} argument. For example, a \cs{footnote} couldn't be used +% in that place (but then that wouldn't make much sense in a gap, +% would it?). +% +% \end{function} +% +% \begin{function}{\TeacherModeOn,\TeacherModeOff} +% \begin{syntax} +% \cs{TeacherModeOn} \texttt{\% show gap material}\\ +% \cs{TeacherModeOff} \texttt{\% stop showing gap material} +% \end{syntax} +% There also exists a teacher mode in which the material for the gaps is +% visible. This can be used to show the expected answers in case \cs{gap} +% is used for preparing tests, or to show a sample fill-in of a form. +% The teacher mode can be turned on or off anywhere in the document +% using \cs{TeacherModeOn} or \cs{TeacherModeOff}, +% respectively. Alternatively, it can also be set via an option, as we +% will see below. +% \end{function} +% +% \begin{function}{\dashundergapssetup} +% \begin{syntax} +% \cs{dashundergapssetup}\Arg{key-value list} +% \end{syntax} +% The package can be loaded with a number of options (discussed in +% Section~\ref{sec:options}). A probably better approach is to set any +% options with the declaration \cs{dashundergapssetup} which is normally +% used in the preamble, but can in fact be used throughout the document +% to change settings on the fly. It only changes options explicitly +% given so can be used to overwrite some defaults but leave everything +% else unchanged. +% \end{function} +% +% +% +% +% +% +% +% +% \subsection{Options to customize the gap display}\label{sec:options} +% +% All of the package options are implemented as key/value options. In +% case of boolean options one can just give the option name as a short +% for setting the option to |true|. Most options can be used during +% package loading in the optional argument of \cs{usepackage}. However +% if the value requires some \LaTeX{} code (e.g., \option{gap-font} that +% expects a font declaration command) then this will not work due to +% some limitations in the current \LaTeX{} package loader. For such +% options use +% \cs{dashundergapssetup} instead which will always work. +% +% \subsubsection{Gap modus} +% +% The general processing mode is defined through the following options: +% \begin{description} +% \item[teacher-mode] Boolean that turns on teacher mode (i.e., the gap +% material will be come visible if set to |true|). It's default is +% |false|. +% \item[gap-mode] Boolean that is the inverse of \option{teacher-mode} +% and just provided for convenience, i.e., you can use it as a short +% form for \option{teacher-mode}|=false|. +% \item[teachermode] Alternative name for \option{teacher-mode} because +% that is what it was called in the first package release. +% \end{description} +% +% \subsubsection{Gap formatting} +% +% Formatting of the gaps is handled by the following five options: +% \begin{description} +% \item[gap-format] A choice option that defines how the gap is +% marked. It accepts the following values: |underline| (default), +% |dash|, |dot|, |wave| or |blank|. +% \item[teacher-gap-format] Another choice option to be used in case we +% are in ``teacher mode''. It accepts the same values, but this time +% the default is |blank| as normally the gap text is typeset in bold +% font and is therefore already identifiable and doesn't additionally +% underlining or some sort. However, depending on the circumstances it +% might be helpful to keep the underlining (or use a different kind of +% underlining) while in ``teacher mode''. +% \item[gap-font] This option expects a font directive as its value, +% e.g., |\bfseries| (which is also the default). Using this option +% without suppling a value is equivalent to supplying an empty +% value. It will be used to determine the font for the gap material +% regardless of the mode. This is important to ensure that the gaps +% always have the same width regardless of whether or not the material +% is shown. +% +% For the example puzzle above it was set to |\itshape| which you can +% see in the puzzle answer. +% \item[dash] Short name for \option{gap-format}|=dash|. +% \item[dot] Short name for \option{gap-format}|=dot|. +% \end{description} +% +% \subsubsection{Gap numbers} +% +% Producing the gap numbers is handled by the following options: +% \begin{description} +% \item[gap-numbers] Boolean that determines whether nor not gap numbers +% are displayed. Default is |true|. +% \item[gap-number-format] Code that is executed if gap number are +% produced. Default is \verb*|\textnormal{ (\thegapnumber)}|. +% \item[numbers] Short name for \option{gap-numbers}. +% \end{description} +% +% There is also a way to control displaying the total number of gaps: +% \begin{description} +% \item[display-total-gaps] Boolean to determine if the total number of +% gaps should be shown at the very end of the document. Default is +% |false|. +% \item[displaynbgaps] This is just another name for the same boolean +% that was used in the first version of the package. +% \end{description} +% +% +% +% \subsubsection{Gap widening} +% +% Finally, for extending the gap width we have these options: +% \begin{description} +% \item[gap-widen] Boolean that decides if the gaps should be made wider +% or not (default is |false| but mainly for historical reasons. +% \item[gap-extend-minimum] Minimum of extra space that should be added +% to each gap if gap widening is active. Default is |10pt|. +% \item[gap-extend-percent] Percentage (as a number) by which the gap should be made +% wider if widening is active. The result is compared to +% \option{gap-extend-minimum} and the larger of the two is +% used. Default is |20|. +% \item[widen] Short name for \option{gap-widen}. +% \end{description} +% +% +% +% +% \section{Differences to the original package} +% +% The main user interface of the two versions is identical so that it is +% possible to use the new version as a drop-in replacement for the +% old. However, the feature set in form of key/value options has be +% greatly extended offering functionality that have been previously +% unavailable. Furthermore a number of bugs have been corrected (and +% possibly new ones introduced). +% +% \begin{itemize} +% \item +% Stray spaces in the definition of \cs{gap} (that showed up in +% the output) have been eliminated; +% \item +% Various combinations of options that didn't work are now possible; +% \item +% Nesting isn't possible for obvious reasons, but the fact is now +% detected and catered for by ignoring the inner gap requests after +% generating an error; +% \item +% Option names have been normalized (though the original names are +% still available); +% \item +% The option \option{phantomtext} is no longer necessary, though still +% supported (with a warning) as a no-op; +% \item +% The names of the \LaTeX{} counters used have changed, so if you +% directly addressed them that would need changing; +% \item +% The font used in teacher mode (by default boldface) is now also +% being used if gap mode is chosen, to ensure that the output in all +% modes will produce identical line breaks; For that reason the +% pkg{ulem} machinery is always used, even if not underlining (or +% dashing, etc.) is needed. +% \item The gaps can be extended by a percentage or by some minimal +% amount to ensure that there is enough space to fill in the text +% (given that hand-written text is typically wider than typeset +% material. The values are adjustable; +% \item +% \cs{gap} has now an optional argument through which you can +% explicitly request the type on underlining you want to use; +% \item +% It also supports a star form which toggles the setting of gap numbers; +% \item +% The Use of \cs{label} within the \cs{gap} command argument allows to +% later refer to that gap by its number (provided a gap number is typeset); +% \item The implementation is done with \texttt{expl3} the programming +% language for \LaTeX3. +% \end{itemize} +% +% \section{Solution to the puzzle} \label{sec:answer} +% +% \TeacherModeOn +% +% Here we repeat the puzzle from above with \cs{TeacherModeOn}. +% \puzzletext +% This was produced using the following changes to the defaults: +% \begin{verbatim} +% \dashundergapssetup{ +% ,gap-number-format = \,\textsuperscript{\normalfont(\thegapnumber)} +% ,gap-font = \itshape +% ,teacher-gap-format = underline +% ,gap-widen +% } +% \end{verbatim} +% As you can see we use |\itshape| for the font (to be able to show +% the bold face in one of the answers) and also forced underlining in +% teacher mode to better show the gap widening. The gap number is +% raised and we separate it a tiny bit from the gap material. We also +% use \cs{normalfont} in the formatting to ensure that the gap number +% is set upright and not in italic shape. +% +% +% \StopEventually{\setlength\IndexMin{200pt} \PrintIndex } +% +% \DoNotIndex{\ ,\advance,\begingroup,\bgroup,\def,\else,\endgroup,\fi} +% \DoNotIndex{\hbox,\ifx,\kern,\let,\lower,\@M,\@empty,\c@gapnumber} +% \DoNotIndex{\c@totalgapnumber,\hb@xt@,\LA@penalty,\UL@box,\UL@leaders} +% \DoNotIndex{\UL@leadtype,\UL@setULdepth,\UL@skip,\UL@start,\z@,\ULdepth} +% \DoNotIndex{\ULon,\vrule,\wd,\@width,\UL@putbox,\markoverwith} +% +% \section{The Implementation} +% +% \subsection{Loading and fixing \pkg{ulem}} +% +% First thing to do is to load \pkg{ulem} without changing \cs{emph} +% or \cs{em}: +% \begin{macrocode} +%<*package> +\RequirePackage[normalem]{ulem} +% \end{macrocode} +% +% The code in this section follows \LaTeXe{} conventions, i.e., models +% the commands like they look in \pkg{ulem} itself. +% +% \begin{macro}{\dotuline} +% The dot produce by \cs{dotuline} depends on the current font +% which is a somewhat questionable design (if you underline a part +% with a single bold word somewhere inside it will change the +% shape of the dot line). So we always use the \cs{normalfont} dot. +% \begin{macrocode} +\def\dotuline{\bgroup + \UL@setULdepth + \markoverwith{\begingroup + \advance\ULdepth0.08ex + \lower\ULdepth\hbox{\normalfont \kern.1em .\kern.04em}% + \endgroup}% + \ULon} +% \end{macrocode} +% \end{macro} + + + +% \begin{macro}[int]{\@ublank} +% \cs{@ublank} underlines with blanks. Normally not really useful +% (which is why we make it internal), +% but when we want to have \pkg{ulem} acting---but without actually +% underlining with something visible---that is the command to use. +% \begin{macrocode} +\def\@ublank{\bgroup\let\UL@leadtype\@empty\ULon} +% \end{macrocode} +% \end{macro} + + + +% \begin{macro}[int]{\phantom@putbox} +% This is going to be a replacement for \cs{UL@putbox} when we want +% \pkg{ulem} to underline something but show a gap instead of the material. +% \begin{macrocode} +\def\phantom@putbox{\ifx\UL@start\@empty \else % not inner + \vrule\@width\z@ \LA@penalty\@M + {\UL@skip\wd\UL@box \UL@leaders \kern-\UL@skip}% + \hb@xt@\wd\UL@box{}% +\fi} +% \end{macrocode} +% \end{macro} +% +% +% +% \subsection{The main implementation part} +% +% The rest of the package is written in \texttt{expl3}. We use +% \texttt{fmdug} as our internal prefix. + +% \begin{macrocode} +%<@@=fmdug> +% \end{macrocode} +% +% We need \pkg{xparse} and \pkg{l3keys2e} +% \begin{macrocode} +\RequirePackage{xparse,l3keys2e} +% \end{macrocode} +% +% \begin{macrocode} +\ProvidesExplPackage + {dashundergaps} + {2018/06/24} + {v2.0a} + {Dashing and underlining (phantom) text} +% \end{macrocode} +% +% +% \subsubsection{User interface commands} +% + +% \begin{macro}{\gap} +% Gap takes a star, optional and mandatory +% argument and calls \cs{@@_gap:nnn} to do the work. +% \begin{macrocode} +\DeclareDocumentCommand \gap { som } { \@@_gap:nnn {#1}{#2}{#3} } +% \end{macrocode} +% \end{macro} +% +% +% \begin{macro}{\dashundergapssetup} +% Change options anywhere. +% \begin{macrocode} +\NewDocumentCommand \dashundergapssetup { m } + { \keys_set:nn {fmdug} {#1} \ignorespaces } +% \end{macrocode} +% \end{macro} +% +% +% \begin{macro}{\TeacherModeOn} +% \begin{macro}{\TeacherModeOff} +% We provide shortcuts for turning teacher mode on or off. +% \begin{macrocode} +\DeclareDocumentCommand \TeacherModeOn {} + { \bool_set_true:N \l_@@_teacher_bool } +\DeclareDocumentCommand \TeacherModeOff {} + { \bool_set_true:N \l_@@_teacher_bool } +% \end{macrocode} +% \end{macro} +% \end{macro} +% +% +% +% +% \subsubsection{Counters} +% +% \begin{macro}[int]{\c@gapnumber} +% We have one user-level counter which is referenceable and holds +% the gap number of the current gap. It can be reset to 0 to +% restart counting. +% \begin{macrocode} +\newcounter{gapnumber} +% \end{macrocode} +% \end{macro} +% +% +% \begin{macro}[int]{\c@totalgapnumber} +% We also keep track of all gaps ever made using another user-level counter. +% \begin{macrocode} +\newcounter{totalgapnumber} +% \end{macrocode} +% \end{macro} + +% \begin{macro}{\l_@@_extend_dim} +% A help register to calculate the gap width later on. +% \begin{macrocode} +\dim_new:N \l_@@_extend_dim +% \end{macrocode} +% \end{macro} + + + +% \begin{macro}{\l_@@_extra_left_gap_tl} +% \begin{macro}{\l_@@_extra_right_gap_tl} +% Two scratch token lists to enlarge the gap on the left or right side. +% \begin{macrocode} +\tl_new:N \l_@@_extra_left_gap_tl +\tl_new:N \l_@@_extra_right_gap_tl +% \end{macrocode} +% \end{macro} +% \end{macro} +% +% +% +% \subsubsection{Messages} +% +% \begin{macrocode} +\msg_new:nnn {dashundergaps} {deprecated} + { + The~ #1~ `#2'~ you~ used~ \msg_line_context: \ is~ deprecated~and~ there~ + is~ no~ replacement.~ Since~ I~ will~ not~ guarantee~ that~ #1~ `#2'~ + will~ be~ kept~ forever~ I~ strongly~ encourage~ you~ to~ remove~ it~ + from~ your~ document. + } +% \end{macrocode} +% +% \begin{macrocode} +\msg_new:nnnn {dashundergaps} {nested} + { The~ \gap command~ can't~ be~ tested! } + { Nesting~ doesn't~ make~ much~ sense~ as~ the~ inner~ one~ wouldn't~ be~ + visible.~ ~ To~ allow~ continuation~ it~ is~ handled~ as~ if~ it~ wasn't~ + been~ asked~ for. } +% \end{macrocode} +% +% +% +% +% \subsubsection{Option handling} +% +% Here we define all option keys for use as package options or inside +% \cs{dashundergapssetup}. these are all straight forward assignments +% to variables. These internal variables are declared by the key +% declarations if unknown, so they are not separately declared before. +% \begin{macrocode} +\keys_define:nn {fmdug} + { + % ==================================== + ,teacher-mode .bool_set:N = \l_@@_teacher_bool + ,teacher-mode .default:n = true + ,teacher-mode .initial:n = false + % ------------------ + ,gap-mode .bool_set_inverse:N = \l_@@_teacher_bool + % ==================================== + ,gap-format + .choice: + ,gap-format / underline + .code:n = \tl_set:Nn \l_@@_gap_format_tl { \uline } + ,gap-format / dash + .code:n = \tl_set:Nn \l_@@_gap_format_tl { \dashuline } + ,gap-format / dot + .code:n = \tl_set:Nn \l_@@_gap_format_tl { \dotuline } + ,gap-format / wave + .code:n = \tl_set:Nn \l_@@_gap_format_tl { \uwave } + ,gap-format / blank + .code:n = \tl_set:Nn \l_@@_gap_format_tl { \@ublank } + ,gap-format / unknown + .code:n = \tl_set:Nn \l_@@_gap_format_tl { #1 } + ,gap-format + .initial:n = underline + % ==================================== + ,teacher-gap-format + .choice: + ,teacher-gap-format / underline + .code:n = \tl_set:Nn \l_@@_teacher_gap_format_tl { \uline } + ,teacher-gap-format / dash + .code:n = \tl_set:Nn \l_@@_teacher_gap_format_tl { \dashuline } + ,teacher-gap-format / dot + .code:n = \tl_set:Nn \l_@@_teacher_gap_format_tl { \dotuline } + ,teacher-gap-format / wave + .code:n = \tl_set:Nn \l_@@_teacher_gap_format_tl { \uwave } + ,teacher-gap-format / blank + .code:n = \tl_set:Nn \l_@@_teacher_gap_format_tl { \@ublank } + ,teacher-gap-format / unknown + .code:n = \tl_set:Nn \l_@@_teacher_gap_format_tl { #1 } + ,teacher-gap-format + .initial:n = blank + % ==================================== + ,gap-widen .bool_set:N = \l_@@_gap_widen_bool + ,gap-widen .default:n = true + ,gap-widen .initial:n = false + % ------------------ + ,widen .meta:n = { gap-widen } + % ------------------ + ,gap-extend-minimum .dim_set:N = \l_@@_gap_min_dim + ,gap-extend-minimum .initial:n = 10pt + % ------------------ + ,gap-extend-percent .tl_set:N = \l_@@_gap_percent_tl + ,gap-extend-percent .initial:n = 20 + % ==================================== + ,gap-numbers .bool_set:N = \l_@@_number_bool + ,gap-numbers .default:n = true + ,gap-numbers .initial:n = true + % ------------------ + ,numbers .meta:n = { gap-numbers } + % ------------------ + ,gap-number-format .tl_set:N = \l_@@_gapnum_format_tl + ,gap-number-format .initial:n = \textnormal{\space (\thegapnumber)} + % ==================================== + ,display-total-gaps .bool_gset:N = \g_@@_display_total_gaps_bool + ,display-total-gaps .default:n = true + ,display-total-gaps .initial:n = false + % ==================================== + ,gap-font .tl_set:N = \l_@@_font_tl + ,gap-font .default:n = + ,gap-font .initial:n = \bfseries +% \end{macrocode} +% And finally the original options: +% \begin{macrocode} + % ==================================== + ,teachermode .meta:n = { teacher-mode } + ,dash .meta:n = { gap-format = dash } + ,dot .meta:n = { gap-format = dot } + ,displaynbgaps .meta:n = { display-total-gaps } + % ------------------ + ,phantomtext + .code:n = \msg_warning:nnnn{dashundergaps}{deprecated} + {option}{phantomtext} + % ==================================== + } +% \end{macrocode} +% +% +% \begin{macro}{\@@_gap:nnn} +% And here finally comes the action. \cs{@@_gap:nn} expects two +% arguments: |#1| indicates what kind of ``underlining'' is wanted +% (anything not recognized is ignored, in particular +% ``--NoValue--'' if \cs{gap} was used without optional argument) +% and |#2| is the material to produce a gap for. +% \begin{macrocode} +\cs_new:Npn\@@_gap:nnn #1#2#3 { +% \end{macrocode} +% +% \begin{macrocode} + \group_begin: +% \end{macrocode} +% Define the font used inside the gap. We need to do this up front +% since we want to measure the text (and that needs the correct +% font already). +% \begin{macrocode} + \l_@@_font_tl +% \end{macrocode} +% Nesting is not supported so inside the gap we redefine +% \cs{@@_gap:nnn} to raise an error and just return the third argument if it is +% encountered again. +% \begin{macrocode} + \cs_set:Npn \@@_gap:nnn ##1##2##3 + { + \msg_error:nn{dashundergaps}{nested} + ##3 + } +% \end{macrocode} +% We increment the counter for the total number of gaps always, but +% the |gapnumber| only if we are displaying it. For the latter one +% we use \cs{refstepcounter} to make it referenceable. +% \begin{macrocode} + \stepcounter{totalgapnumber} + \bool_xor:nnT { #1 } { \l_@@_number_bool } + { \refstepcounter{gapnumber} } +% \end{macrocode} +% Next we prepare for widening if that is being asked for: Measure +% the with of the text and then set \cs{l_@@_extend_dim} to be the +% requested percentage divided by two of that width (since we add +% it later on both sides. + +% Then compare it to the minimum / 2 and choose whatever is larger. +% \begin{macrocode} + \bool_if:NTF \l_@@_gap_widen_bool + { + \settowidth \l_@@_extend_dim {#3} + \dim_set:Nn \l_@@_extend_dim + { \l_@@_gap_percent_tl \l_@@_extend_dim / 200 } +% + \dim_compare:nNnT \l_@@_extend_dim < { .5\l_@@_gap_min_dim } + { \dim_set:Nn \l_@@_extend_dim { .5\l_@@_gap_min_dim } } +% \end{macrocode} +% Now we prepare what needs to go to the left and the right of the gap. +% \begin{macrocode} + \tl_set:Nn \l_@@_extra_left_gap_tl + { \hbox_to_wd:nn\l_@@_extend_dim{} \allowbreak } + \tl_set:Nn \l_@@_extra_right_gap_tl + { \allowbreak \hbox_to_wd:nn\l_@@_extend_dim{} } + } +% \end{macrocode} +% And if no widening is asked for we clear these two token lists so +% that they don't do anything. +% \begin{macrocode} + { + \tl_clear:N \l_@@_extra_left_gap_tl + \tl_clear:N \l_@@_extra_right_gap_tl + } +% \end{macrocode} +% Next comes deciding the gap format. If in teacher mode it will be +% whatever is in \cs{l_@@_teacher_gap_tl}. Otherwise it is either +% based on the content of the optional argument or if that is not +% given or unknown it will be \cs{l_@@_gap_format_tl}. +% \begin{macrocode} + \bool_if:NTF \l_@@_teacher_bool + { \l_@@_teacher_gap_format_tl } + { \cs_set_eq:NN \UL@putbox \phantom@putbox + \str_case:nnF {#2} + { + {u} { \uline } + {w} { \uwave } + {b} { \@ublank } + {.} { \dotuline } + {-} { \dashuline } + } + { \l_@@_gap_format_tl } + } +% \end{macrocode} +% Whatever was decided as gap format it needs one argument, +% i.e., the material (with possible gap extension on both sides. +% \begin{macrocode} + {\l_@@_extra_left_gap_tl #3 \l_@@_extra_right_gap_tl } +% \end{macrocode} +% Finally we typeset the gap number is that was requested. +% \begin{macrocode} + \bool_xor:nnT { #1 } { \l_@@_number_bool } + { \l_@@_gapnum_format_tl } +% \end{macrocode} +% +% \begin{macrocode} + \group_end: +} +% \end{macrocode} +% \end{macro} +% +% +% +% \begin{macro}{\@@_display_total_gaps:} +% This command will display the total number of gaps if +% requested. The hard-wired formatting comes from the first +% version of the package. +% \begin{macrocode} +\cs_new:Npn \@@_display_total_gaps: { + \vfill \centering + \bfseries Total~ Gaps:~ \thetotalgapnumber +} +% \end{macrocode} +% \end{macro} +% +% +% +% \subsubsection{Closing shop} +% +% At the end of the document we typeset the total number of gaps if requested. +% \begin{macrocode} +\AtEndDocument{ + \bool_if:NT \g_@@_display_total_gaps_bool + \@@_display_total_gaps: +} +% \end{macrocode} +% So what remains to be done is execute all options passed to the +% package via \cs{usepackage}. +% \begin{macrocode} +\ProcessKeysPackageOptions{fmdug} +%<*package> +% \end{macrocode} +% +% \Finale +% +\endinput diff --git a/Master/texmf-dist/source/latex/dashundergaps/dashundergaps.ins b/Master/texmf-dist/source/latex/dashundergaps/dashundergaps.ins new file mode 100644 index 00000000000..389a83ef0a9 --- /dev/null +++ b/Master/texmf-dist/source/latex/dashundergaps/dashundergaps.ins @@ -0,0 +1,67 @@ +%% +%% This file will generate fast loadable files and documentation +%% driver files from the dtx file(s) in this package when run through +%% LaTeX or TeX. +%% +%% Copyright 2018 Frank Mittelbach +%% +%% +%% This file is part of the dashundergaps Bundle for LaTeX. +%% ------------------------------------------------------- +%% +%% It may be distributed and/or modified under the +%% conditions of the LaTeX Project Public License, either version 1.3c +%% of this license or (at your option) any later version. +%% The latest version of this license is in +%% http://www.latex-project.org/lppl.txt +%% and version 1.3c or later is part of all distributions of LaTeX +%% version 2005/12/01 or later. +%% +%% In particular, NO PERMISSION is granted to modify the contents of this +%% file since it contains the legal notices that are placed in the files +%% it generates. +%% +%% +%% +%% --------------- start of docstrip commands ------------------ +%% +\input l3docstrip + +\keepsilent + +\usedir{tex/latex/contrib/dashundergaps} + +\preamble + +This is a generated file. + +Copyright 2018 Frank Mittelbach + +This file was generated from file(s) of the LaTeX `dashundergaps Bundle'. +-------------------------------------------------------------------------- + +It may be distributed and/or modified under the +conditions of the LaTeX Project Public License, either version 1.3c +of this license or (at your option) any later version. +The latest version of this license is in + http://www.latex-project.org/lppl.txt +and version 1.3c or later is part of all distributions of LaTeX +version 2005/12/01 or later. + +This file may only be distributed together with a copy of the LaTeX +`Tools Bundle'. You may however distribute the LaTeX `Tools Bundle' +without such generated files. + +The newest sources can be found below + + https://github.com/FrankMittelbach/fmitex/ + +where one can also log issues in case there are any. + + +\endpreamble + + +\generate{\file{dashundergaps.sty}{\from{dashundergaps.dtx}{package}}} + +\endbatchfile |