From 371ccb95f6e45efc2b42d558fba7d4e4fc9d1ae3 Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Mon, 19 Nov 2018 21:55:47 +0000 Subject: dashundergaps (19nov18) git-svn-id: svn://tug.org/texlive/trunk@49198 c570f23f-e606-0410-a88d-b1316a301751 --- .../source/latex/dashundergaps/dashundergaps.dtx | 697 ++++++++++++++------- .../source/latex/dashundergaps/dashundergaps.ins | 2 +- 2 files changed, 479 insertions(+), 220 deletions(-) (limited to 'Master/texmf-dist/source/latex/dashundergaps') 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} % % @@ -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 -- cgit v1.2.3