dashundergaps (19nov18)

git-svn-id: svn://tug.org/texlive/trunk@49198 c570f23f-e606-0410-a88d-b1316a301751

2 files changed, 479 insertions, 220 deletions

diff --git a/Master/texmf-dist/source/latex/dashundergaps/dashundergaps.dtx b/Master/texmf-dist/source/latex/dashundergaps/dashundergaps.dtx
index cd0067807bf..f26f362baac 100644
--- a/Master/texmf-dist/source/latex/dashundergaps/dashundergaps.dtx
+++ b/Master/texmf-dist/source/latex/dashundergaps/dashundergaps.dtx
@@ -16,13 +16,52 @@
 %
 % for those people who are interested or want to report an issue.
 %
+
+\def\dashundergapsdate   {2018/11/18}
+\def\dashundergapsversion{v2.0d}
+
 %<*driver>
-\documentclass{l3doc}
+\let\fmipagebreak\pagebreak
+
+\RequirePackage[nohyphen]{underscore}    % no hyphen after undercore
+                                         %   in csname
+\documentclass
+    [final]
+    {l3doc-TUB}
+
+
+\setcounter{page}{1}       
+
+% fix for _TF undefined,
+% https://github.com/latex3/latex3/issues/477#issuecomment-419458783
+\ExplSyntaxOn
+\cs_set_protected:Npn \__codedoc_typeset_TF:
+  {
+    \group_begin:
+      \exp_args:No \__codedoc_if_macro_internal:nT \l__codedoc_tmpa_tl
+        { \color[gray]{0.5} }
+      \itshape TF
+    \group_end:
+  }
+\ExplSyntaxOff
+
+% fix for doc/ltugboat issue
+\def\pfill{~%
+           \leaders\hbox to.6em{\hss .\hss}\hskip 0em plus 1fill
+           \kern-1.5em
+           \penalty500
+           \kern 1.5em
+           \strut\nobreak
+           \leaders\hbox to.6em{\hss .\hss}\hskip 0em plus 1fil
+           \null~\ignorespaces}%
+
 \usepackage{dashundergaps,multicol}
 \EnableCrossrefs
 \CodelineIndex
 \begin{document}
   \DocInput{dashundergaps.dtx}
+\addtolength\signaturewidth{42pt}
+\makesignature
 \end{document}
 %</driver>
 %
@@ -31,9 +70,17 @@
 %
 % \newcommand\option[1]{\texttt{#1}}
 %
-% \title{The \texttt{dashundergaps} package\thanks{A reimplementation of
-%     a package originally written by Luca Merciadri in 2010.}}
+% \DoNotIndex{}
+%
+% \title{The \texttt{dashundergaps} package\thanks{This is a
+%    reimplementation (using \texttt{expl3}, the \LaTeX3 programming
+%    language) of a package originally written by Luca Merciadri in
+%    2010. The current package version is \dashundergapsversion\
+%    dated \dashundergapsdate.}}
 % \author{Frank Mittelbach}
+% \address{Mainz, Germany}
+% \netaddress{https://www.latex-project.org}
+% \personalURL{https://ctan.org/pkg/dashundergaps}
 %
 % \maketitle
 %
@@ -49,70 +96,97 @@
 %
 %   There is also a teacher's mode which shows the normally hidden text
 %   in a special (customizable) format.
+%
+%   \medskip
+%
+%    This is another article in a series of \TUB{} articles
+%    describing small packages to introduce coding practices using the
+%    \pkg{expl3} programming language. See~\cite{tub-wao-code} for the
+%    first article in the series.
+%   For more details on \pkg{expl3} refer to~\cite{expl3}.
+%
 % \end{abstract}
 %
+% \tableofcontents
+%
+%
 % \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
+% which takes one argument and produces a gap of the width of that
+% argument. 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:
+%   line}). Furthermore, gaps can be numbered to be able to easily
+% refer to them. Figure~\ref{fig:puzzle} shows an example in the form of a
+%    fill-in 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
+%   \addtolength\baselineskip{3pt}
+%   The initial `E.' in Donald E. Knuth's name stands for \gap{Ervin}.
+%   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
+%   The first edition of \gap{The \LaTeX{} Companion} celebrates its 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-number-format  = \,\textsuperscript{\normalfont
+%                                            (\thegapnumber)}
 %   ,gap-font           = \itshape
 %   ,teacher-gap-format = underline
 %   ,gap-widen
 % }
 %
+% \begin{figure}
+%  \centering
+%   \setlength\fboxsep{10pt}
+%   \noindent\hspace{-\marginparwidth}\fbox{\begin{minipage}{1.20\textwidth}
 % \puzzletext
-% And here are some hints for it if you want to fill it out:
+%
+% \bigskip
+%
+% And here are some hints for the puzzle 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
+%   \item If only everything would be that easy\newline to answer.
+%   \item The author of the book ``Last Chance To~See'' and of a famous
 %     radio~show.
 %   \item Back then known as the doggie book.
 %   \item Old names die hard.\\
-%     \mbox{}                      % manual to get same height
+%     \mbox{}                      ^^A 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
+% The answers are given in Section~\ref{sec:answer}, showing the gaps
+% filled in using the so-called teacher mode, which~can be
+%    activated or deactivated at any point in the document.\raggedright
+% \end{minipage}}
+% \caption{A fill-in puzzle using \pkg{dashundergaps}}\label{fig:puzzle}
+% \end{figure}
+%
+% As you see there, 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
+% There also exists a ``teacher mode'' in which 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
+% correct answers of a test (as we do in Section~\ref{sec:answer}) or
+% to give a sample fill-in for a form, to help people fill it out
+% correctly. The ``teacher mode'' produces the same line breaks
+% because it ensures that the fill-ins take the same amount 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,
+% 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
+% gaps simply as wide as the material likely results in too little
 % space.
 %
 %
@@ -120,66 +194,79 @@
 %
 %
 % 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}
+% of the \pkg{ulem} package, a package that defines several commands for
+% underlining \meta{simple-text} in various ways.
+% \begin{function}{\uline,\uuline,\uwave,\dashuline,\dotuline}
 %   \begin{syntax}
-% \cs{uline}\Arg{simple-text}  \cs{uwave}\Arg{simple-text}  % etc.
+% \cs{uline}\Arg{simple-text}  \cs{uwave}\Arg{simple-text}  ...
 %   \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
+%   the work and the current package only makes sure that, instead of the
+%   words, empty boxes of the same width 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
+% By default, \pkg{ulem} changes \cs{emph} to underline text, so
+% for this application, it is loaded with the option \texttt{normalem} to
 % prevent that from happening.
 %
+% \end{function}
+%
 %
 %
 % \begin{function}{\gap}
 %   \begin{syntax}
-% \cs{gap}*\oarg{type}\Arg{text}
+%      \cs{gap}*\oarg{style}\Arg{text}
 %   \end{syntax}
+%   \noindent\llap{\small\smash{\begin{tabular}[t]{r@{ = }l} ^^A really low-level hacked
+%     \multicolumn{2}{c}{}\\
+%     \multicolumn{2}{c}{\hspace*{-1.2pc}Possible \meta{style}s:}\\[3pt]
+%     \texttt{u} & \cs{uline} \\
+%     \texttt{d} & \cs{uuline} \\
+%     \texttt{w} & \cs{uwave} \\
+%     \texttt{b} & \meta{blank} \\
+%     \texttt{-} & \cs{dashuline} \\
+%     \texttt{.} & \cs{dotuline}
+%   \end{tabular}}\ }^^A
 %   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).
+%   to produce the gap (and is normally invisible). By default the gap is
+%   underlined, though that can be changed.
+% \end{function}    ^^A not really meant for no parindent and positive
+%                   ^^A parskip ...
+% \vspace{\parskip} ^^A ... thus manual fix for now
+%
 %
 %   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
+%   |d| for double underlining (via \cs{uuline}),
+%   |w| for a wavy 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
+%   and finally ``|.|''\ for underlining with dots (via \cs{dotuline}).
+%
+%   In the default configuration 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 is
+%   toggled, i.e., if it would be 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
+%   |*| to toggle it as needed.
+%
+%   Since \cs{gap} uses \pkg{ulem}'s commands it inherits the limitations
+%   of these commands; notably, 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}
+%   in the argument (but then that wouldn't make much sense in a gap,
+%   would~it?).
 %
 % \begin{function}{\TeacherModeOn,\TeacherModeOff}
 %   \begin{syntax}
-%     \cs{TeacherModeOn}  \texttt{\% show gap material}\\
-%     \cs{TeacherModeOff} \texttt{\% stop showing gap material}
+%     \cs{TeacherModeOn}   \texttt{\,\% show gap material}
+%     \cs{TeacherModeOff}  \texttt{\% do not show gap material}
 %   \end{syntax}
-% There also exists a teacher mode in which the material for the gaps is
+% Also supported is 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
@@ -190,14 +277,14 @@
 %
 % \begin{function}{\dashundergapssetup}
 %   \begin{syntax}
-% \cs{dashundergapssetup}\Arg{key-value list}
+% \cs{dashundergapssetup}\Arg{comma-separated 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
+% Section~\ref{sec:options}). A likely 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
+% used in the preamble, but can be used throughout the document
+% to change settings on the fly. It only changes explicitly given options
+% so it can be used to overwrite some defaults but leave everything
 % else unchanged.
 % \end{function}
 %
@@ -210,76 +297,82 @@
 %
 % \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.
+% All of the package options are implemented as key/value options. 
+% For boolean options one can give just the option name as a short
+% form for setting the option to |true|. Most options can be specified
+% during package loading in the optional argument of
+% \cs{usepackage}. However if the value requires some \LaTeX{} code
+% (e.g., \option{gap-font}, which 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}
+% \subsubsection{Gap modes}
 %
 % 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
+% \item[\option{teacher-mode}] Boolean that turns on teacher mode (i.e., the gap
+%   material will be visible if set to |true|). Its 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
+% \item[\option{gap-mode}] Boolean that is the inverse of \option{teacher-mode}
+%   and just provided for convenience, i.e., an abbreviation
+%   for \option{teacher-mode}|=false|.
+% \item[\option{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:
+% Formatting of the gaps is handled by the following six options:
 % \begin{description}
-% \item[gap-format] A choice option that defines how the gap is
+% \item[\option{gap-format}] A choice option defining 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
+%   |double-underline|,
+%   |dash|, |dot|, |wave|, |blank|.
+% \item[\option{gap-format-adjust}] A boolean (default |true|). If set, the
+%     ``line'' below the gap is raised to be roughly at the baseline,
+%     which normally looks better when there is no text above the line.
+% \item[\option{teacher-gap-format}] Another choice option, with the
+%   same values as \option{gap-format}, used when we
+%   are in ``teacher mode'', but this time
+%   the default is |blank| as normally the gap text is typeset in the bold
+%   font and is therefore already identifiable, with no need for additional
+%   underlining. 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,
+% \item[\option{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
+%   without supplying 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
+%   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|.
+% \item[\option{dash}] Short name for \option{gap-format}|=dash|.
+% \item[\option{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
+% \item[\option{gap-numbers}] Boolean that determines whether or not gap numbers
 %   are displayed. Default is |true|.
-% \item[gap-number-format] Code that is executed if gap number are
+%
+% \item[\option{gap-number-format}] Code that is executed when a gap number is
 %   produced. Default is \verb*|\textnormal{ (\thegapnumber)}|.
-% \item[numbers] Short name for \option{gap-numbers}.
+% \item[\option{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
+% \item[\option{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.
+% \item[\option{displaynbgaps}] This is just another name for the same boolean;
+%   it was used in the first version of the package.
 % \end{description}
 %
 %
@@ -288,106 +381,147 @@
 %
 % 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
+% \item[\option{gap-widen}] Boolean that decides if the gaps should be made wider
+%   or not (default is |false| but mainly for historical reasons).
+% \item[\option{gap-extend-minimum}] Minimum of extra space that should be added
+%   to each gap if gap widening is active. Default is |20pt|, i.e.,
+%   |10pt| on either side.
+% \item[\option{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}.
+% \item[\option{widen}] Short name for \option{gap-widen}.
 % \end{description}
 %
 %
 %
 %
-% \section{Differences to the original package}
+% \section{Differences from the original package}
 %
-% The main user interface of the two versions is identical so that it is
+% The main user interface of the two versions is identical, so 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
+% old. However, the feature set in form of key/value options has been
+% greatly extended, offering functionality 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;
+%   the output) have been eliminated.
 % \item
-%   Various combinations of options that didn't work are now possible;
+%   Various combinations of options that didn't work are now possible.
+% \item
+%   Explicit hyphenations |\-| showed up in gap mode, now they can be used.
 % \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;
+%   detected and catered to by ignoring the inner gap requests after
+%   generating an error.
 % \item
 %   Option names have been normalized (though the original names are
-%   still available);
+%   still available).
 % \item
 %   The option \option{phantomtext} is no longer necessary, though still
-%   supported (with a warning) as a no-op;
+%   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;
+%   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
+%   used if gap mode is chosen, to ensure that the output in all
+%   modes produces identical line breaks; for the same reason, the
+%   \pkg{ulem} machinery is always used, even if not underlining (or
+%   dashing, etc.).
+% \item The gaps can be extended by a percentage or by a minimum
 %   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;
+%   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;
+%   \cs{gap} now has an optional argument through which you can
+%   explicitly request the type of underlining you want to use.
 % \item
-%   It also supports a star form which toggles the setting of gap numbers;
+%   \cs{gap} 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.
+%   The use of \cs{label} within the \cs{gap} command argument allows for
+%   later reference 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. Although invisible to the user, in some sense
+%     that was the main purpose of
+%     the exercise: to see how easy it is to convert a package and use
+%     the extended features of \texttt{expl3}.
 % \end{itemize}
 %
+%
 % \section{Solution to the puzzle} \label{sec:answer}
 %
 % \TeacherModeOn
 %
 % Here we repeat the puzzle from above with \cs{TeacherModeOn}.
-% \puzzletext
+% \par\smallskip
+% \noindent\hfill\llap{\setlength\fboxsep{10pt}
+%                      \fbox{\begin{minipage}{1.2\textwidth}
+%                      \puzzletext
+% \end{minipage}\hskip\marginparsep}}
+% \par\smallskip
 % This was produced using the following changes to the defaults:
 % \begin{verbatim}
 %   \dashundergapssetup{
-%     ,gap-number-format  = \,\textsuperscript{\normalfont(\thegapnumber)}
+%     ,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
+% the bold face in one of the answers) and also force 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  }
+% \StopEventually{
+% \begin{thebibliography}{1}
+%\bibitem{tub-wao-code}
+% Frank Mittelbach.
+% \newblock The \pkg{widows-and-orphans} package.
+% \newblock \textsl{TUG}boat 39:3,
+%   \ifx\thisissuepageref\undefined ^^A undefined if non-TUGboat
+%     20018.\\
+%   \else \thisissuepageref{mitt-widows-code}, 2018.\fi
+% \newblock  \url{https://ctan.org/pkg/widows-and-orphans}
+% \bibitem{expl3}
+% \LaTeX3 Project Team.
+% \newblock A collection of articles on \pkg{expl3}.\\
+%    \url{https://latex-project.org/publications/indexbytopic/l3-expl3/}
+%\end{thebibliography}
+% \ifx\thisissuepageref\undefined    ^^A is this TUB production ??? if not gen index
+%    \setlength\IndexMin{200pt}  \PrintIndex
+% \fi}
+%
+%
+% \newpage
+%
 %
 % \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}
+% \DoNotIndex{\char,\cs_new:Npn,\cs_set:Npn,\dim_new:N,\font,\global,\hyphenchar}
+% \DoNotIndex{\setbox,\string,\UL@hyphenbox,\UL@start}
+% \DoNotIndex{\tl_new:N,\tl_set:Nn,\ifnum,\UL@stop,\dim_set:Nn,\box}
+% \DoNotIndex{\discretionary,\sixly,\p@,\usepackage,\ignorespaces}
+% \DoNotIndex{\cs_set_eq:NN}
+%
+%
 %
-% \section{The Implementation}
+% \section{The implementation}
 %
-% \subsection{Loading and fixing \pkg{ulem}}
+% \subsection{Loading and fixing/changing \pkg{ulem}}
 %
-% First thing to do is to load \pkg{ulem} without changing \cs{emph}
+% The first thing to do is to load \pkg{ulem} without changing \cs{emph}
 % or \cs{em}:
 %    \begin{macrocode}
 %<*package>
@@ -395,13 +529,14 @@
 %    \end{macrocode}
 %
 % The code in this section follows \LaTeXe{} conventions, i.e., models
-% the commands like they look in \pkg{ulem} itself.
+% the commands as they look in the \pkg{ulem} package.
 %
 %  \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
+%     The dots produced by \cs{dotuline} depend on the current font,
+%     which is a somewhat questionable design\Dash if you underline a text %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.
+%     shape of the dot line. So we  always use the \cs{normalfont}
+%     dot (this is not done in the original definition).
 %    \begin{macrocode}
 \def\dotuline{\bgroup
   \UL@setULdepth
@@ -410,34 +545,76 @@
      \lower\ULdepth\hbox{\normalfont \kern.1em .\kern.04em}%
      \endgroup}%
   \ULon}
+\MakeRobust\dotuline
 %    \end{macrocode}
 %  \end{macro}
-
-
-
-%  \begin{macro}[int]{\@ublank}
-%    \cs{@ublank} underlines with blanks. Normally not really useful
+%
+%
+%
+%  \begin{macro}{\uwave}
+%    The original \cs{uwave} used a hard-wired value of |3.5pt| for
+%     the lowering. We change that to be based on the current
+%     value of \cs{ULdepth} so that the user (or this package here)
+%     can change the placement.
+%    \begin{macrocode}
+\def\uwave{\bgroup
+  \UL@setULdepth
+  \advance\ULdepth 0.6\p@
+  \markoverwith{\lower\ULdepth\hbox{\sixly \char58}}\ULon}
+\MakeRobust\uwave
+%    \end{macrocode}
+%  \end{macro}
+%
+%
+%  \begin{macro}[int]{\fmdug@ublank}
+%    \cs{fmdug@ublank} underlines with blanks. Normally not especially 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.
+%    but if we want to have \pkg{ulem} acting, but without actually
+%    visibly underlining, this is the command to use.
 %    \begin{macrocode}
-\def\@ublank{\bgroup\let\UL@leadtype\@empty\ULon}
+\def\fmdug@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{macro}[int]{\UL@dischyp}
+%  \begin{macro}[int]{\UL@putbox}
+%   We need to do a little patching to ensure that nothing is output
+%   by the \pkg{ulem} commands if we don't want it to. So the next two
+%   commands are from \pkg{ulem} with |\box| replaced by
+%   |\fmdug@box| so that we can change the behavior.
+%    \begin{macrocode}
+\def\UL@dischyp{\global\setbox\UL@hyphenbox\hbox
+   {\ifnum \hyphenchar\font<\z@ \string-\else \char\hyphenchar\font \fi}%
+   \kern\wd\UL@hyphenbox \LA@penalty\@M 
+   \UL@stop \kern-\wd\UL@hyphenbox
+   \discretionary{\fmdug@box\UL@hyphenbox}{}{}\UL@start}
+%    \end{macrocode}
+%    
 %    \begin{macrocode}
-\def\phantom@putbox{\ifx\UL@start\@empty \else % not inner
+\def\UL@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}
+  \fmdug@box\UL@box  \fi}
 %    \end{macrocode}
 %  \end{macro}
+%  \end{macro}
+%
+%
+%
+%  \begin{macro}[int]{\fmdug@box}
+%    By default we output the box in the commands above, but when we
+%    don't want to output anything visible we change the definition to
+%    generate a box with empty content but the right size.
+%    \begin{macrocode}
+\let\fmdug@box\box
+%    \end{macrocode}
+%  \end{macro}
+%
+%
+%
+%
 %
 %
 %
@@ -450,17 +627,20 @@
 %<@@=fmdug>
 %    \end{macrocode}
 %
-% We need \pkg{xparse} and \pkg{l3keys2e}
+% We need the package \pkg{xparse} for specifying the document-level
+%    interface commands and \pkg{l3keys2e} to use the \pkg{expl3} key
+%    value  methods within \LaTeXe{}. These packages automatically
+%    require \pkg{expl3} so there is no need to load that explicitly.
 %    \begin{macrocode}
 \RequirePackage{xparse,l3keys2e}
 %    \end{macrocode}
 %
+% Here we introduce the package and specify its version number:
 %    \begin{macrocode}
-\ProvidesExplPackage
-  {dashundergaps}
-  {2018/06/24}
-  {v2.0a}
-  {Dashing and underlining (phantom) text}
+\ProvidesExplPackage{dashundergaps}
+                    {\dashundergapsdate}
+                    {\dashundergapsversion}
+                    {Dashing and underlining phantom text}
 %    \end{macrocode}
 %
 %
@@ -468,8 +648,8 @@
 %
 
 %  \begin{macro}{\gap}
-%    Gap takes a star, optional and mandatory
-%    argument and calls \cs{@@_gap:nnn} to do the work.
+%    The \cs{gap} command parses for a star, optional and mandatory
+%    argument and then calls \cs{@@_gap:nnn} to do the work.
 %    \begin{macrocode}
 \DeclareDocumentCommand \gap { som } { \@@_gap:nnn {#1}{#2}{#3} }
 %    \end{macrocode}
@@ -492,7 +672,7 @@
 \DeclareDocumentCommand \TeacherModeOn  {}
                         { \bool_set_true:N \l_@@_teacher_bool }
 \DeclareDocumentCommand \TeacherModeOff {}
-                        { \bool_set_true:N \l_@@_teacher_bool }
+                        { \bool_set_false:N \l_@@_teacher_bool }
 %    \end{macrocode}
 %  \end{macro}
 %  \end{macro}
@@ -513,7 +693,15 @@
 %
 %
 %  \begin{macro}[int]{\c@totalgapnumber}
-%    We also keep track of all gaps ever made using another user-level counter.
+%    We also keep track of all gaps ever made using another user-level
+%    counter. Since this one is supposed to keep track of the total
+%    number of gaps, it makes little sense to modify it at the
+%    document level. However, there may be use cases even for that and
+%    more importantly, by making it a user-level counter it is
+%\fmipagebreak
+%    possible to refer to the total number of gaps easily, e.g., via
+%    \cs{thetotalgapnumber}.
+% ^^A\makeatletter\@endparpenalty=10000\makeatother
 %    \begin{macrocode}
 \newcounter{totalgapnumber}
 %    \end{macrocode}
@@ -525,9 +713,9 @@
 \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.
@@ -539,36 +727,54 @@
 %  \end{macro}
 %
 %
+%  \begin{macro}{\l_@@_gap_format_tl}
+%  \begin{macro}{\l_@@_teacher_gap_format_tl}
+%    The gap formatting is normally handled by a \pkg{ulem}
+%    command; which one depends on the options used. To record the
+%    choice we store it in a token list (one for normal and one for
+%    teacher mode).
+%    \begin{macrocode}
+\tl_new:N \l_@@_gap_format_tl
+\tl_new:N \l_@@_teacher_gap_format_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.
-  }
+  { 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. }
+  { The~ \gap command~ can't~ be~ nested! }
+  { Nesting~ doesn't~ make~ much~ sense~ as~ the~ inner~ one~
+    wouldn't~ be~ visible.~ ~ To~ allow~ further~ processing~ it~ is~
+    handled~ as~ if~ it~ hasn't~ been~ asked~ for. }
 %    \end{macrocode}
 %
 %
+%    \begin{macrocode}
+\msg_new:nnnn {dashundergaps} {gap-format-value}
+  { Unknown~ value~ for~ key~ '#1 gap-format'! }
+  { Supported~ values~ are~ 'underline',~ 'double-underline',\\
+    'dash',~ 'dot',~ 'wave'~ or~ 'blank'. }
+%    \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
+% Here we define all the possible option keys for use either as package
+% options or inside
+% \cs{dashundergapssetup}. These are all straightforward assignments
 % to variables. These internal variables are declared by the key
-% declarations if unknown, so they are not separately declared before.
+% declarations if unknown, so they are not separately declared beforehand.
 %    \begin{macrocode}
 \keys_define:nn {fmdug}
      {
@@ -581,25 +787,70 @@
        % ====================================
       ,gap-format
          .choice:
+%    \end{macrocode}
+%
+%    In the case of dashes and even more so in the case of dots, it looks
+%    fairly ugly if they are below the baseline as if there were text
+%    above. We therefore raise them up a bit if the option
+%    \texttt{gap-format-adjust} is given (which is the default).
+%
+%    In the case of dots we undo
+%    exactly the amount by which they are lowered in \pkg{ulem} so
+%    that they end up precisely at the baseline, in case they are
+%    followed by a real dot. In other cases we stay a bit below the baseline.
+%
+%     The same is done below when the optional argument is
+%     evaluated. But we don't do this in teacher mode since there we
+%     \emph{will} have text above and we don't want to bump into that.
+%
+%    \begin{macrocode}
       ,gap-format / underline
-         .code:n = \tl_set:Nn \l_@@_gap_format_tl { \uline }
+         .code:n = \tl_set:Nn \l_@@_gap_format_tl
+                              { \@@_gap_format_adjust:n{.4pt} \uline }
+      ,gap-format / double-underline
+         .code:n = \tl_set:Nn \l_@@_gap_format_tl
+                              { \@@_gap_format_adjust:n{2pt} \uuline }
       ,gap-format / dash
-         .code:n = \tl_set:Nn \l_@@_gap_format_tl { \dashuline }
+         .code:n = \tl_set:Nn \l_@@_gap_format_tl
+                           { \@@_gap_format_adjust:n{0pt} \dashuline }
       ,gap-format / dot
-         .code:n = \tl_set:Nn \l_@@_gap_format_tl { \dotuline  }
+         .code:n = \tl_set:Nn \l_@@_gap_format_tl
+                         { \@@_gap_format_adjust:n{-.08ex} \dotuline }
       ,gap-format / wave
-         .code:n = \tl_set:Nn \l_@@_gap_format_tl { \uwave  }
+         .code:n = \tl_set:Nn \l_@@_gap_format_tl
+                              { \@@_gap_format_adjust:n{1pt} \uwave }
       ,gap-format / blank
-         .code:n = \tl_set:Nn \l_@@_gap_format_tl { \@ublank  }
+         .code:n = \tl_set:Nn \l_@@_gap_format_tl { \fmdug@ublank  }
       ,gap-format / unknown
-         .code:n = \tl_set:Nn \l_@@_gap_format_tl { #1 }
+         .code:n = \msg_error:nnn{dashundergaps}{gap-format-value}{}
       ,gap-format
          .initial:n = underline
        % ====================================
+%    \end{macrocode}
+%     This controls the raising of the gap underline by some
+%     amount. We implement it as a |.choice| even though it looks like
+%     a boolean.
+%\begingroup\hfuzz=15pt
+%    \begin{macrocode}
+       ,gap-format-adjust
+         .choice:
+       ,gap-format-adjust / true
+         .code:n = \cs_set:Npn \@@_gap_format_adjust:n ##1
+                               { \setlength\ULdepth {##1} }
+       ,gap-format-adjust / false
+         .code:n = \cs_set_eq:NN \@@_gap_format_adjust:n \use_none:n
+      ,gap-format-adjust
+         .default:n = true
+      ,gap-format-adjust
+         .initial:n = true
+      ,adjust .meta:n = { gap-format-adjust }
+       % ====================================
       ,teacher-gap-format
          .choice:
      ,teacher-gap-format / underline
          .code:n = \tl_set:Nn \l_@@_teacher_gap_format_tl { \uline }
+      ,teacher-gap-format / double-underline
+         .code:n = \tl_set:Nn \l_@@_teacher_gap_format_tl { \uuline }
       ,teacher-gap-format / dash
          .code:n = \tl_set:Nn \l_@@_teacher_gap_format_tl { \dashuline }
       ,teacher-gap-format / dot
@@ -607,9 +858,9 @@
       ,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 }
+         .code:n = \tl_set:Nn \l_@@_teacher_gap_format_tl { \fmdug@ublank }
       ,teacher-gap-format / unknown
-         .code:n = \tl_set:Nn \l_@@_teacher_gap_format_tl { #1 }
+         .code:n = \msg_error:nnn{dashundergaps}{gap-format-value}{teacher-}
       ,teacher-gap-format
          .initial:n = blank
        % ====================================
@@ -620,7 +871,7 @@
       ,widen                 .meta:n = { gap-widen }
        % ------------------
       ,gap-extend-minimum .dim_set:N = \l_@@_gap_min_dim
-      ,gap-extend-minimum .initial:n = 10pt
+      ,gap-extend-minimum .initial:n = 20pt
        % ------------------
       ,gap-extend-percent .tl_set:N  = \l_@@_gap_percent_tl
       ,gap-extend-percent .initial:n = 20
@@ -642,7 +893,7 @@
       ,gap-font   .default:n =
       ,gap-font   .initial:n = \bfseries
 %    \end{macrocode}
-%    And finally the original options:
+%    And finally the original options, now as aliases:
 %    \begin{macrocode}
        % ====================================
       ,teachermode   .meta:n =  { teacher-mode }
@@ -656,13 +907,14 @@
        % ====================================
      }
 %    \end{macrocode}
+%\endgroup
 %
 %
 %  \begin{macro}{\@@_gap:nnn}
-%    And here finally comes the action. \cs{@@_gap:nn} expects two
+%    At last, here 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)
+%    ``--NoValue--'' if \cs{gap} was used without an optional argument)
 %    and |#2| is the material to produce a gap for.
 %    \begin{macrocode}
 \cs_new:Npn\@@_gap:nnn #1#2#3 {
@@ -687,8 +939,8 @@
         ##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 always increment the counter for the total number of gaps, but
+%    increment the |gapnumber| only if we are displaying it. For the latter one
 %    we use \cs{refstepcounter} to make it referenceable.
 %    \begin{macrocode}
     \stepcounter{totalgapnumber}
@@ -696,18 +948,18 @@
       { \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
+%    the width 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.
+%    it later on both sides).
 %    \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 }
-%
+%    \end{macrocode}
+%    Then compare it to the minimum / 2 and choose whatever is larger.
+%    \begin{macrocode}
        \dim_compare:nNnT \l_@@_extend_dim < { .5\l_@@_gap_min_dim }
           { \dim_set:Nn \l_@@_extend_dim { .5\l_@@_gap_min_dim } }
 %    \end{macrocode}
@@ -720,7 +972,7 @@
       }
 %    \end{macrocode}
 %    And if no widening is asked for we clear these two token lists so
-%    that they don't do anything.
+%    they don't do anything.
 %    \begin{macrocode}
       {
         \tl_clear:N \l_@@_extra_left_gap_tl
@@ -728,35 +980,41 @@
       }
 %    \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}.
+%    whatever is in \cs{l_@@_teacher_gap_tl}. Otherwise, either it is
+%    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
+      {
+%    \end{macrocode}
+%    But before we execute any of the \pkg{ulem} commands we make sure
+%    that they do not output text.
+%    \begin{macrocode}
+        \cs_set:Npn   \fmdug@box ##1 {\hbox_to_wd:nn{\box_wd:N ##1}{}}
         \str_case:nnF {#2}
             {
-              {u} { \uline }
-              {w} { \uwave }
-              {b} { \@ublank }
-              {.} { \dotuline }
-              {-} { \dashuline }
+              {u} { \@@_gap_format_adjust:n{.4pt}   \uline  }
+              {d} { \@@_gap_format_adjust:n{2pt}    \uuline }
+              {w} { \@@_gap_format_adjust:n{1pt}    \uwave  }
+              {b} { \fmdug@ublank }
+              {.} { \@@_gap_format_adjust:n{-.08ex} \dotuline }
+              {-} { \@@_gap_format_adjust:n{0pt}   \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.
+%    Whatever was decided as the 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.
+%    Finally we typeset the gap number if that was requested.
 %    \begin{macrocode}
     \bool_xor:nnT { #1 } { \l_@@_number_bool }
                   { \l_@@_gapnum_format_tl }
 %    \end{macrocode}
-%
+%    Close the group from above to keep any of the redefinitions confined.
 %    \begin{macrocode}
   \group_end:
 }
@@ -788,7 +1046,7 @@
               \@@_display_total_gaps:
 }
 %    \end{macrocode}
-%  So what remains to be done is execute all options passed to the
+%  So what remains to be done is executing all options passed to the
 %    package via \cs{usepackage}.
 %    \begin{macrocode}
 \ProcessKeysPackageOptions{fmdug}
@@ -797,4 +1055,5 @@
 %
 % \Finale
 %
+%
 \endinput
diff --git a/Master/texmf-dist/source/latex/dashundergaps/dashundergaps.ins b/Master/texmf-dist/source/latex/dashundergaps/dashundergaps.ins
index 389a83ef0a9..20ebf84d7a4 100644
--- a/Master/texmf-dist/source/latex/dashundergaps/dashundergaps.ins
+++ b/Master/texmf-dist/source/latex/dashundergaps/dashundergaps.ins
@@ -49,7 +49,7 @@ 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'
+`dashundergaps Bundle'. You may however distribute the `dashundergaps Bundle'
 without such generated files.
 
 The newest sources can be found below