Debian Codegraph @

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

raw
1 % \iffalse meta-comment
2 %
3 % Copyright (C) 2013 by Scott Pakin <[email protected]>
4 % -------------------------------------------------------
5 %
6 % This file may be distributed and/or modified under the
7 % conditions of the LaTeX Project Public License, either version 1.3c
8 % of this license or (at your option) any later version.
9 % The latest version of this license is in:
10 %
11 % http://www.latex-project.org/lppl.txt
12 %
13 % and version 1.3c or later is part of all distributions of LaTeX
14 % version 2006/05/20 or later.
15 %
16 % \fi
17 %
18 % \iffalse
19 %<*driver>
20 \ProvidesFile{dashrule.dtx}
21 %</driver>
22 %<package>\NeedsTeXFormat{LaTeX2e}[1999/12/01]
23 %<package>\ProvidesPackage{dashrule}
24 %<*package>
25 [2013/03/28 v1.3 Dashed rules]
26 %</package>
27 %
28 %<*driver>
29 \documentclass{ltxdoc}
30 \usepackage{dashrule}
31 \usepackage{titlesec}
32 \EnableCrossrefs
33 \CodelineIndex
34 \RecordChanges
35 \begin{document}
36 \DocInput{dashrule.dtx}
37 \PrintChanges
38 \PrintIndex
39 \end{document}
40 %</driver>
41 % \fi
42 %
43 % \CheckSum{64}
44 %
45 % \CharacterTable
46 % {Upper-case \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
47 % Lower-case \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
48 % Digits \0\1\2\3\4\5\6\7\8\9
49 % Exclamation \! Double quote \" Hash (number) \#
50 % Dollar \$ Percent \% Ampersand \&
51 % Acute accent \' Left paren \( Right paren \)
52 % Asterisk \* Plus \+ Comma \,
53 % Minus \- Point \. Solidus \/
54 % Colon \: Semicolon \; Less than \<
55 % Equals \= Greater than \> Question mark \?
56 % Commercial at \@ Left bracket \[ Backslash \\
57 % Right bracket \] Circumflex \^ Underscore \_
58 % Grave accent \` Left brace \{ Vertical bar \|
59 % Right brace \} Tilde \~}
60 %
61 %
62 % \changes{v1.0}{2001/04/23}{Initial version}
63 %
64 % \GetFileInfo{dashrule.dtx}
65 %
66 % \DoNotIndex{\addtocounter,\csname,\DeclareRobustCommand,\def,\else,\empty}
67 % \DoNotIndex{\endcsname,\expandafter,\fi,\hbox,\hskip,\hspace,\ifodd,\ifx}
68 % \DoNotIndex{\let,\mbox,\newcounter,\relax,\setcounter}
69 %
70 % ^^A Precede every section title with a dashed rule.
71 % \titleformat{\section}
72 % {\unskip\vskip 2.3ex plus 0.2ex
73 % \vbox{\noindent\hdashrule[0pt][x]{\fill}{1pt}{5pt}\rule{5pt}{1pt}}
74 % \vskip 2.3ex plus 0.2ex}
75 % {\normalfont\Large\bfseries\thesection}
76 % {1em}
77 % {\normalfont\Large\bfseries}
78 %
79 %
80 % \title{The \textsf{dashrule} package\thanks{This document
81 % corresponds to \textsf{dashrule}~\fileversion, dated \filedate.}}
82 % \author{Scott Pakin \\ \texttt{[email protected]}}
83 %
84 % \maketitle
85 %
86 % \begin{abstract}
87 % The \textsf{dashrule} package makes it easy to draw a huge variety
88 % of dashed rules (i.e., lines) in \LaTeX. \textsf{dashrule} provides
89 % a command, |\hdashrule|, which is a cross between \LaTeX's |\rule|
90 % and PostScript's |setdash| command. |\hdashrule| draws horizontally
91 % dashed rules using the same syntax as |\rule| but with an
92 % additional, |setdash|-like parameter that specifies the pattern of
93 % dash segments and the space between those segments. Because
94 % \textsf{dashrule}'s rules are constructed internally using |\rule|
95 % (as opposed to, e.g., PostScript |\special|s) they are fully
96 % compatible with every \LaTeX{} back-end processor.
97 % \end{abstract}
98 %
99 %
100 % \section{Usage}
101 %
102 % \DescribeMacro{\hdashrule}
103 % \LaTeX's |\rule| command draws a rectangular blob of ink with a given
104 % width, height, and distance above the baseline. The
105 % \textsf{dashrule} package introduces an analogous command,
106 % |\hdashrule|, which draws the same blob of ink, but horizontally
107 % dashed. |\hdashrule| takes five parameters, two of which are
108 % optional:
109 %
110 % \bigskip
111 % \noindent\hspace{-\leftmargini}%
112 % \fbox{\texttt{\string\hdashrule}
113 % \oarg{raise} \oarg{leader} \marg{width} \marg{height} \marg{dash}}
114 % \bigskip
115 %
116 % The \meta{raise}, \meta{width}, and \meta{height} parameters have the
117 % same meaning as in \LaTeX's |\rule| macro: the distance to raise the
118 % rule above the baseline and the width and height of the rule.
119 %
120 % Because |\hdashrule| is implemented in terms of \TeX's primitive
121 % leader commands (|\leaders|, |\cleaders|, and |\xleaders|), the dash
122 % pattern must be repeated an integral number of times. \meta{leader}
123 % specifies what to do with the extra whitespace (always less than the
124 % width of the dash pattern) that this requirement introduces. The
125 % default, which corresponds to \TeX's |\leaders| command, adds space to
126 % both ends of the rule so the dash patterns from multiple |\hdashrule|s
127 % line up. If \meta{leader} is~|c|, which corresponds to \TeX's
128 % |\cleaders| command, an equal amount of whitespace is added to both
129 % ends of the rule. If \meta{leader} is~|x|, which corresponds to
130 % \TeX's |\xleaders| command, the whitespace is divided up, and the same
131 % amount of whitespace separates each repetition of the dash pattern.
132 %
133 % The \meta{dash} argument specifies the dash pattern and is analogous
134 % to the \textit{array} argument to PostScript's |setdash| function.
135 % That is, it is a list of space-separated \meta{dimen}s that alternate
136 % ``on'' and ``off'' distances. For instance, ``|2pt 1pt|'' means a
137 % 2\,pt.\ rule, followed by a 1\,pt.\ gap, followed by a 2\,pt.\ rule,
138 % followed by a 1\,pt.\ gap, and so forth. An odd number of
139 % \meta{dimen}s is no different; ``|2pt|'' alternates 2\,pt.\ rules and
140 % 2\,pt.\ gaps, and ``|1pt 2pt 3pt|'' repeats ``1\,pt.\ rule,
141 % 2\,pt.\ gap, 3\,pt.\ rule, 1\,pt.\ gap, 2\,pt.\ rule, 3\,pt.\ gap.''
142 % As a special case, an empty \meta{dash} argument draws a solid rule.
143 %
144 %
145 % \section{Examples}
146 %
147 % The following are some typical ways to use |\hdashrule|. Each example
148 % changes from the previous in only one parameter. For clarity,
149 % underlines are used to indicate modified text, and the rule is
150 % bracketed by an upper- and lowercase~``X''.
151 %
152 % \begin{center}
153 % \renewcommand{\arraystretch}{1.5}
154 % \newcommand{\chg}[1]{\underbar{\texttt{#1}}}
155 % \begin{tabular}{l@{\qquad}l}
156 % |\rule{2cm}{1pt}| &
157 % X\rule{2cm}{1pt}x \\
158 %
159 % |\|\chg{hdashrule}|{2cm}{1pt}|\chg{\char`\{\char`\}} &
160 % X\hdashrule{2cm}{1pt}{}x \\
161 %
162 % |\hdashrule{2cm}{1pt}{|\chg{1pt}|}| &
163 % X\hdashrule{2cm}{1pt}{1pt}x \\
164 %
165 % |\hdashrule{|\chg{4cm}|}{1pt}{1pt}| &
166 % X\hdashrule{4cm}{1pt}{1pt}x \\
167 %
168 % |\hdashrule|\chg{[0.5ex]}|{4cm}{1pt}{1pt}| &
169 % X\hdashrule[0.5ex]{4cm}{1pt}{1pt}x \\
170 %
171 % |\hdashrule[0.5ex]{4cm}{1pt}{|\chg{3mm}|}| &
172 % X\hdashrule[0.5ex]{4cm}{1pt}{3mm}x \\
173 %
174 % |\hdashrule[0.5ex]{4cm}{|\chg{1mm}|}{3mm}| &
175 % X\hdashrule[0.5ex]{4cm}{1mm}{3mm}x \\
176 %
177 % |\hdashrule[0.5ex]{4cm}{1mm}{3mm |\chg{3pt}|}| &
178 % X\hdashrule[0.5ex]{4cm}{1mm}{3mm 3pt}x \\
179 %
180 % |\hdashrule[0.5ex]{4cm}{1mm}{%| \\[-1.5ex]
181 % | 3mm 3pt |\chg{1mm 2pt}|}| &
182 % X\hdashrule[0.5ex]{4cm}{1mm}{3mm 3pt 1mm 2pt}x \\
183 % \end{tabular}
184 % \end{center}
185 %
186 % \bigskip
187 % \noindent
188 % These next examples show the effect of using different leader types.
189 % Each leader is used with both a 4\,cm~wide rule and a 3\,cm~wide rule.
190 %
191 % \begin{center}
192 % \renewcommand{\arraystretch}{1.25}
193 % \newcommand{\chg}[1]{\underbar{\texttt{#1}}}
194 % \begin{tabular}{l@{\qquad}l}
195 % |\hdashrule[0.5ex]{4cm}{1mm}{8mm 2pt}| &
196 % X\hdashrule[0.5ex]{4cm}{1mm}{8mm 2pt}x \\
197 %
198 % |\hdashrule[0.5ex]{3cm}{1mm}{8mm 2pt}| &
199 % X\hdashrule[0.5ex]{3cm}{1mm}{8mm 2pt}x \\[2ex]
200 %
201 % |\hdashrule[0.5ex]|\chg{[c]}|{4cm}{1mm}{8mm 2pt}| &
202 % X\hdashrule[0.5ex][c]{4cm}{1mm}{8mm 2pt}x \\
203 %
204 % |\hdashrule[0.5ex]|\chg{[c]}|{3cm}{1mm}{8mm 2pt}| &
205 % X\hdashrule[0.5ex][c]{3cm}{1mm}{8mm 2pt}x \\[2ex]
206 %
207 % |\hdashrule[0.5ex][|\chg{x}|]{4cm}{1mm}{8mm 2pt}| &
208 % X\hdashrule[0.5ex][x]{4cm}{1mm}{8mm 2pt}x \\
209 %
210 % |\hdashrule[0.5ex][|\chg{x}|]{3cm}{1mm}{8mm 2pt}| &
211 % X\hdashrule[0.5ex][x]{3cm}{1mm}{8mm 2pt}x \\
212 % \end{tabular}
213 % \end{center}
214 %
215 % \noindent
216 % Notice how the dashes in the first pair of |\hdashrule|s line up; the
217 % rules in the second pair each have an equal amount of whitespace on
218 % either side of the rule; and the rules in the third pair have extra
219 % spaces within the dash pattern itself instead of around it. The
220 % |x|~qualifier is rarely useful for dashed rules because it alters the
221 % pattern itself. However, |x| does enable rules with long dashes to
222 % better fill a comparatively small width, as in the following example:
223 %
224 % \begin{center}
225 % \renewcommand{\arraystretch}{1.25}
226 % \begin{tabular}{l@{\qquad}l}
227 % |\hdashrule[0.5ex][x]{3in}{2pt}{2cm 0pt}| \\
228 % X\hdashrule[0.5ex][x]{3in}{2pt}{2cm 0pt}x
229 % \end{tabular}
230 % \end{center}
231 %
232 % \noindent
233 % The gaps in the above are clearly wider than~|0pt|, but they \emph{are}
234 % evenly spaced.
235 %
236 %
237 % \section{Differences from \texttt{setdash}}
238 %
239 % |\hdashrule| is different from PostScript's |setdash| command in the
240 % following ways:
241 %
242 % \begin{itemize}
243 % \item |setdash| takes on/off values in terms of PostScript points
244 % (\TeX{} ``big points'' or~``|bp|''), while |\hdashrule| requires
245 % explicit units.
246 %
247 % \item There is no equivalent of |setdash|'s \textit{offset}
248 % parameter to specify a starting offset into the pattern. If you're
249 % desperate you can fake \textit{offset} with a leading |\rule| and
250 % |\hspace|.
251 % \end{itemize}
252 %
253 %
254 % \StopEventually{^^A
255 % \section{Future Work}
256 %
257 % \textsf{dashrule} \fileversion{} supports only horizontally dashed
258 % rules. Future versions (if any) may support vertically dashed rules
259 % as well. For the time being, the \textsf{graphicx} package's
260 % \texttt{\string\rotatebox} can be used to define a
261 % \texttt{\string\vdashrule} in terms of a rotated
262 % \texttt{\string\hdashrule}.
263 %
264 % The next logical step after adding a \texttt{\string\vdashrule} is
265 % to support dashed rectangles, which would be composed of
266 % \texttt{\string\hdashrule}s and \texttt{\string\vdashrule}s. Other
267 % possible enhancements would be a way of drawing dotted lines,
268 % presumably composed from the limited set of circle characters
269 % available in \LaTeX's fonts.
270 % }
271 %
272 %
273 % \section{Implementation}
274 %
275 % We load the \textsf{ifmtarg} package to help check if the final
276 % argument to |\hdashrule| is empty.
277 % \begin{macrocode}
278 \RequirePackage{ifmtarg}
279 % \end{macrocode}
280 %
281 % \begin{macro}{\hdr@do@rule}
282 % This macro is exactly like \LaTeX's |\rule| except that the optional
283 % argument is required, and it has the side effect of pointing
284 % |\hdr@do@something| to |\hdr@do@skip|.
285 % \begin{macrocode}
286 \def\hdr@do@rule[#1]#2#3{%
287 \rule[#1]{#2}{#3}%
288 \let\hdr@do@something=\hdr@do@skip
289 }
290 % \end{macrocode}
291 % \end{macro}
292 %
293 % \begin{macro}{\hdr@do@skip}
294 % This macro takes the same arguments as |\hdr@do@rule|, but instead of
295 % drawing a rule, it inserts an equivalent amount of horizontal
296 % whitespace. Additionally, it points |\hdr@do@something| to
297 % |\hdr@do@rule| as a side effect.
298 % \begin{macrocode}
299 \def\hdr@do@skip[#1]#2#3{%
300 \hspace*{#2}%
301 \let\hdr@do@something=\hdr@do@rule
302 }
303 % \end{macrocode}
304 % \end{macro}
305 %
306 % \begin{macro}{\c@hdr@segments}
307 % \begin{macro}{\hdr@tally@segments}
308 % Dash patterns containing an odd number of segments are treated
309 % differently from dash patterns containing an even number of segments.
310 % We therefore define a macro, |\hdr@tally@segments|, which counts the
311 % number of space-separated segments in a dash pattern and stores the
312 % tally in the |hdr@segments| counter. Note that |hdr@segments| should
313 % be initialized to~|0| before invoking |\hdr@tally@segments|.
314 % \begin{macrocode}
315 \newcounter{hdr@segments}
316 \def\hdr@tally@segments#1 {%
317 \ifx#1!%
318 \else
319 \addtocounter{hdr@segments}{1}%
320 \expandafter\hdr@tally@segments
321 \fi
322 }
323 % \end{macrocode}
324 % \end{macro}
325 % \end{macro}
326 %
327 % \begin{macro}{\hdashrule}
328 % This is the only macro in \textsf{dashrule}'s external interface.
329 % (|\hdashrule@ii| does most of the work for |\hdashrule|, though.) All
330 % |\hdashrule| itself does is invoke |\hdashrule@i| with its first
331 % optional argument or~|0.0pt| if none was provided. |\hdashrule@i|, in
332 % turn, invokes |\hdashrule@ii| with the two optional arguments,
333 % supplying |\empty| as the default value of the second optional
334 % argument.
335 % \changes{v1.1}{2008/04/27}{Preceded the invocation of
336 % \texttt{\string\string\string\@testopt} with an empty box so that
337 % \texttt{\string\string\string\hdashrule} can now begin a paragraph}
338 % \begin{macrocode}
339 \DeclareRobustCommand{\hdashrule}{\mbox{}\@testopt{\hdashrule@i}{0pt}}
340 % \end{macrocode}
341 % \end{macro}
342 %
343 % \begin{macro}{\hdashrule@i}
344 % Supply |\empty| as the default second argument and call
345 % |\hdashrule@ii|.
346 % \begin{macrocode}
347 \def\hdashrule@i[#1]{\@testopt{\hdashrule@ii[#1]}\empty}
348 % \end{macrocode}
349 % \end{macro}
350 %
351 % \begin{macro}{\hdashrule@ii}
352 % Now we can do the real work for |\hdashrule|. |\hdashrule@ii| takes
353 % the following parameters:
354 %
355 % \begin{center}
356 % \begin{tabular}{ccccc}
357 % |#1| & |#2| & |#3| & |#4| & |#5| \\
358 % \oarg{raise} & \oarg{leader} & \marg{width} & \marg{height} & \marg{dash}
359 % \end{tabular}
360 % \end{center}
361 %
362 % \noindent
363 % The \meta{raise}, \meta{width}, and \meta{height} parameters have the
364 % same meaning as in \LaTeX's |\rule| macro. \meta{leader} specifies
365 % the \TeX\ leader function to use to fill \meta{width} amount of
366 % space. It should be |c| for |\cleaders|, |x| for |\xleaders|, or
367 % nothing for ordinary |\leaders|. The \meta{dash} argument specifies
368 % the dash pattern and is analogous to the \textit{array} argument to
369 % PostScript's |setdash| function. That is, it is a list of
370 % space-separated \meta{dimen}s that alternate ``on'' and ``off''
371 % distances.
372 % \begin{macrocode}
373 \def\hdashrule@ii[#1][#2]#3#4#5{%
374 % \end{macrocode}
375 % \end{macro}
376 %
377 % If the final argument, \meta{dash}, is empty, we fall back to using an
378 % ordinary |\rule| command. This is not terribly useful in practice but
379 % does make |\hdashrule| behave more like PostScript's |setdash|.
380 % \begin{macrocode}
381 \@ifmtarg{#5}{%
382 \rule[#1]{#3}{#4}%
383 }{%
384 % \end{macrocode}
385 % Here begins the common case, in which the \meta{dash} argument is
386 % nonempty.
387 %
388 % \begin{macro}{\hdr@do@something}
389 % The |\hdr@do@something| alias alternates between |\hdr@do@rule|
390 % and |\hdr@do@skip|, starting with |\hdr@do@rule|.
391 % \begin{macrocode}
392 \let\hdr@do@something=\hdr@do@rule
393 % \end{macrocode}
394 % \end{macro}
395 %
396 % \begin{macro}{\hdr@parse@dash}
397 % For every space-separated \meta{dimen} in \meta{dash}, we invoke
398 % |\hdr@do@something| to draw a rule or a space, as appropriate. We
399 % define |\hdr@parse@dash| within |\hdashrule@ii| so we don't have to
400 % pass in |\hdashrule@ii|'s~|#1| and~|#4| on every invocation.
401 % \begin{macrocode}
402 \def\hdr@parse@dash##1 {%
403 \ifx##1!%
404 \else
405 \hdr@do@something[#1]{##1}{#4}%
406 \expandafter\hdr@parse@dash
407 \fi
408 }%
409 % \end{macrocode}
410 % We now count the number of segments in the dash pattern so we can
411 % determine if we have an even or odd number of them.
412 % \begin{macrocode}
413 \setcounter{hdr@segments}{0}%
414 \hdr@tally@segments#5 !
415 % \end{macrocode}
416 % Finally, we invoke |\leaders|, |\cleaders|, or |\xleaders| to draw the
417 % dashed line, repeating the pattern until \meta{width} space is filled.
418 % The trick here is that odd-lengthed pattern descriptions must be
419 % repeated to yield the complete pattern. For instance, the pattern
420 % ``|1pt|'' is actually short for ``1\,pt.\ rule, 1\,pt.\ space,'' and
421 % ``|2pt 4pt 6pt|'' is an abridged version of ``2\,pt.\ rule, 4\,pt.\
422 % space, 6\,pt.\ rule, 2\,pt.\ space, 4\,pt.\ rule, 6\,pt.\ space.''
423 % Although it is valid to repeat even-lengthed patterns as well---an
424 % earlier draft of |\hdashrule@ii| did just that---this produces
425 % inferior results because \TeX's various leader commands do not split
426 % boxes. The longer the pattern, the less likely it will fit snugly
427 % into the given width.
428 % \changes{v1.2}{2009/08/08}{Ended the rule with an empty box to enable
429 % \texttt{\string\string\string\hdashrule} to work within a
430 % \texttt{tabular} cell. Thanks to Piazza Luca for the bug report}
431 % \changes{v1.3}{2013/03/28}{Prevented spurious spaces from being introduced
432 % into the output. Thanks to Halil \c{S}en for the bug report}
433 % \begin{macrocode}
434 \ifodd\c@hdr@segments
435 \csname#2leaders\endcsname
436 \hbox{\hdr@parse@dash#5 #5 ! }%
437 \hskip#3%
438 \else
439 \csname#2leaders\endcsname
440 \hbox{\hdr@parse@dash#5 ! }%
441 \hskip#3%
442 \fi
443 \mbox{}%
444 }%
445 }
446 % \end{macrocode}
447 % \end{macro}
448 %
449 % \Finale
450 \endinput