summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/ncctools/source/nccrules.dtx
blob: 0542215c436793e2f6d753f293d6cb16c567444a (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
% \iffalse
%%
%% File: nccrules.dtx Copyright (C) 2005 by Alexander I. Rozhenko
%%
%<package>\NeedsTeXFormat{LaTeX2e}
%<package>\ProvidesPackage{nccrules}
%<package>      [2005/05/13 v1.0 More rules (NCC)]
%
% \changes{v1.0}{2005/05/13}{This version was uploaded to CTAN}
%
%<*driver>
\let\makeindex\relax
\documentclass{ltxdoc}
\usepackage{nccrules}
\newfootnoterule{starred}{\mboxfill[1.5\width][s]{$*$}}
\newfootnoterule{dotted}{\mboxfill[2\width][s]{.}}
\newfootnotedashrule{double}{}{.4 1 .4}
\newfootnotedashrule{dashed}{3 3}{.4}
\newfootnotedashrule{dotdashed}{4 2 1 2 4 -4}{.6}
\newfootnotedashrule{ddotdashed}{6 2 1 2 1 2 6 -6}{.6}
\GetFileInfo{nccrules.sty}
\begin{document}
\title{The \textsf{nccrules} package\thanks{This file
        has version number \fileversion, last
        revised \filedate.}}
\author{Alexander I. Rozhenko\\rozhenko@oapmg.sscc.ru}
\date{\filedate}
\maketitle
\DocInput{nccrules.dtx}
\end{document}
%</driver>
% \fi
% This package implements
% |\dashrule| and |\dashrulefill| commands,
% that simplify composing of dashed
% lines and dashed multilines. Two kinds of footnote rule generation
% commands are also introduced: |\newfootnoterule| creates a footnote
% rule with an arbitrary contents and |\newfootnotedashrule| creates
% a footnote rule based on dash rule.
%
% \tableofcontents
%
% \section{User Interface}
%
% \subsection{Dash Rules}
%
% \DescribeMacro\dashrule
% The command
% \begin{quote}
% |\dashrule|\oarg{raise}\marg{h-pattern}\marg{v-pattern}
% \end{quote}
% prepares a dash rule. Its syntax is quite similar to the |\rule| command
% except that \meta{h-pattern} and \meta{v-pattern} can contain a list of
% sizes delimited with spaces. List sizes are interpreted as follows:
% size, space, size, space, etc. In other words, every odd size is a
% size of rule part and every even size is a space between neighbour parts.
% If the last size in the list is even
% (means a space), its space value is divided by two and
% is added before the first rule part and after the last rule part.
% Units in sizes can be omitted. In this case, pt-units are supposed.
% Examples:
% \begin{center}
% \begin{tabular}{@{}l@{\qquad\qquad}l@{}}
% x\dashrule[.5ex]{10mm}{1pt}x &
% |x\dashrule[.5ex]{10mm}{1pt}x| \\
% x\dashrule{5mm 3 3 3 5mm}{.4}x &
% |x\dashrule{5mm 3 3 3 5mm}{.4}x| \\
% x\dashrule{1}{3 2 3}x&
% |x\dashrule{1}{3 2 3}x|\\
% x\dashrule{2 2}{2 2}x &
% |x\dashrule{2 2}{2 2}x|\\
% x\dashrule{5 3 1 3 5 10}{1 1 0.4 1 1}x &
% |x\dashrule{5 3 1 3 5 10}{1 1 0.4 1 1}x|
% \end{tabular}
% \end{center}
%
% \DescribeMacro\dashrulefill
% The command
% \begin{quote}
% |\dashrulefill|\oarg{raise}\oarg{leader-type}\marg{h-pattern}\marg{v-pattern}
% \end{quote}
% fills a free space with a dash rule. The rule is composed from the 1st,
% 3rd, and 4th arguments of the command and is repeated as more times as
% necessary to fill a free horizontal space. The rest of space after filling is
% stored depending on \meta{leader-type} used. Default leader type
% is ``aligned leaders'': every rule is aligned to the multiple of its width
% counted from the left boundary of filled box. Other cases are: |c| means
% centered leaders (all extra spaces are collected at both ends of fill
% area), |x| means distributed leaders (extra spaces are uniformly
% distributed between every dash rule), and |s| means stretched leaders
% (the space in h-pattern going after the last rule size is considered as
% stretchable space and rules are stretched to the whole width of the
% fill area).
%
% Example:
% \begin{flushleft}
% |\noindent x\dashrulefill{2 2}{2}\mbox{}\\|\\
% |xxxxx\dashrulefill[.4ex]{2 2}{2}\mbox{}\\|\\
% |\mbox{}\dashrulefill[.4ex]{4 4}{2}\mbox{}\\|\\
% |\mbox{}\dashrulefill[.4ex][c]{4 4}{2}\mbox{}\\|\\
% |\mbox{}\dashrulefill[.4ex][x]{4 4}{2}\mbox{}\\|\\
% |\mbox{}\dashrulefill[.4ex][s]{4 4}{2}\mbox{}\\|\\
% |\mbox{}\dashrulefill[.4ex][s]{4 2 1 2 4 -4}{1}\mbox{}\\[1ex]|\\
% |\mbox{}\dashrulefill[0mm][c]{2 3}{2 3 2 3 2}\mbox{}\\|\\
% |\mbox{}\dashrulefill{5 3 1 3 5}{1 1 0.4 1 1}\mbox{}\\|\\
% |\mbox{}\dashrulefill[0mm][c]{5 3 1 3 5}{1 1 0.4 1 1}\mbox{}\\[-2ex]|\\
% |\mbox{}\hrulefill|
% \end{flushleft}
%
% It produces the following:
%
% \noindent x\dashrulefill{2 2}{2}\mbox{}\\
% xxxxx\dashrulefill[.4ex]{2 2}{2}\mbox{}\\
% \mbox{}\dashrulefill[.4ex]{4 4}{2}\mbox{}\\
% \mbox{}\dashrulefill[.4ex][c]{4 4}{2}\mbox{}\\
% \mbox{}\dashrulefill[.4ex][x]{4 4}{2}\mbox{}\\
% \mbox{}\dashrulefill[.4ex][s]{4 4}{2}\mbox{}\\
% \mbox{}\dashrulefill[.4ex][s]{4 2 1 2 4 -4}{1}\mbox{}\\[1ex]
% \mbox{}\dashrulefill[0mm][c]{2 3}{2 3 2 3 2}\mbox{}\\
% \mbox{}\dashrulefill{5 3 1 3 5}{1 1 0.4 1 1}\mbox{}\\
% \mbox{}\dashrulefill[0mm][c]{5 3 1 3 5}{1 1 0.4 1 1}\mbox{}\\[-2ex]
% \mbox{}\hrulefill
%
% \subsection{Custom Footnote Rules}
%
% In |manyfoot| package, you can separate footnote levels
% with custom footnote rules. In this package we provide two ways for
% creation such rules. All footnote rules should follow the following
% contract: they must be prepared as |\hrule| or |\hbox|; the total height
% of rule or box must be compensated with kerns. Usually a negative
% kern is inserted before a footnote rule and a nonnegative kern is
% inserted after the rule. The sum of both kerns and of total height of
% rule must be equal to zero. We follow this contract in footnote rules
% created with this package.
%
% In |manyfoot| package, every footnote rule must have a name
% |\|\meta{prefix}|footnoterule|. So, we need to specify the prefix only
% when a new footnote rule is constructed. Next that we need to specify is
% a rule width. If width is omitted, the default width of |0.4\columnwidth|
% is used. The footnote rule generation commands described below
% are used in the preamble only.
%
% \DescribeMacro\newfootnoterule
% The command
% \begin{quote}
% |\newfootnoterule|\marg{prefix}\oarg{width}\marg{rule code}
% \end{quote}
% produces a custom user-defined rule.
% The \meta{rule code} must be stretchable to the given width.
% The |\mboxfill| command from the |mboxfill| package is useful in it.
% Examples:
% \begin{quote}
% |\newfootnoterule{starred}{\mboxfill[1.5\width][s]{$*$}}|\\
% |\newfootnoterule{dotted}{\mboxfill[2\width][s]{.}}|
% \end{quote}
% The |\starredfootnoterule| and |\dottedfootnoterule| commands
% are created here. They produce the following rules:
%
% \vspace{3mm}
% \starredfootnoterule
% \dottedfootnoterule
%
% \DescribeMacro\newfootnotedashrule
% The command
% \begin{quote}
% |\newfootnotedashrule|\marg{prefix}\oarg{width}\marg{h-pattern}\marg{v-pattern}
% \end{quote}
% produces a dash footnote rule. The special case, when \meta{h-pattern}
% is empty means the solid rule. Examples:
% \begin{quote}
% |\newfootnotedashrule{double}{}{.4 1 .4}|\\
% |\newfootnotedashrule{dashed}{3 3}{.4}|\\
% |\newfootnotedashrule{dotdashed}{4 2 1 2 4 -4}{.6}|\\
% |\newfootnotedashrule{ddotdashed}{6 2 1 2 1 2 6 -6}{.6}|
% \end{quote}
% The following rules are created here:
% |\doublefootnoterule|, |\dashedfootnoterule|,
% |\dotdashedfootnoterule|, and |\ddotdashedfootnoterule|.
% They produce the following rules:
%
% \vspace{2mm}%
% \doublefootnoterule
% \dashedfootnoterule
% \dotdashedfootnoterule
% \ddotdashedfootnoterule
%
% \StopEventually{}
%
% \section{The Implementation}
%
% The |mboxfill| package is required here:
%    \begin{macrocode}
%<*package>
\RequirePackage{mboxfill}
%    \end{macrocode}
%
% \begin{macro}{\dashrule}
% |\dashrule|\oarg{raise}\marg{h-pattern}\marg{v-pattern}
%    \begin{macrocode}
\newcommand\dashrule{}
\DeclareRobustCommand*\dashrule[3][\z@]{%
  \setbox\@tempboxa\vbox{}%
  \NCC@composedash{\NCC@vdash{#2}}{#3}%
  \setlength\@tempdima{#1}\leavevmode
  \raise\@tempdima\hbox{%
    \vbox to\@tempdimc{\vss\unvbox\@tempboxa\vss}}%
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\dashrulefill}
% |\dashrulefill|\oarg{raise}\oarg{leader-type}\marg{h-pattern}\marg{v-pattern}\\
% This command is a composition of the |\mboxfill| and
% |\dashrule| commands. A trick is applied here:
% we decrease dash rule width on the value of last space
% in it and then apply |\mboxfill|.
%    \begin{macrocode}
\newcommand*\dashrulefill[1][\z@]{%
  \@ifnextchar[{\NCC@dashfill{#1}}{\NCC@dashfill{#1}[]}%
}
\def\NCC@dashfill#1[#2]#3#4{%
  \NCC@composedash{}{#3}%
  \advance\@tempdimb-\@tempdimc
  \setbox\@tempboxa\hb@xt@-\@tempdimb
    {\hss\dashrule[#1]{#3}{#4}\hss}%
  \mboxfill[\@tempdimc][#2]{\box\@tempboxa}%
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\NCC@composedash}
% |\NCC@composedash|\marg{action}\marg{pattern} parses the pattern
% and calls the action when a rule size is parsed. At this point,
% the |\@tempdima| contains a size parsed and |\@tempdimb| contains
% the previous space. In |\@tempdimc|, the whole rule size is calculated.
%    \begin{macrocode}
\def\NCC@composedash#1#2{%
  \@tempdimb\z@ % Last space
  \@tempdimc\z@ % Accumulator
  \@tempswatrue % True value means producing an entry
  \NCC@parsedash#2 ! !\@nil{%
    \advance\@tempdimc\@tempdima
    \if@tempswa #1\@tempswafalse \else
      \@tempdimb\@tempdima \@tempswatrue
    \fi
  }%
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\NCC@parsedash}
% Pattern parser:
%    \begin{macrocode}
\def\NCC@parsedash#1 #2\@nil#3{%
  \if/#1/\else % Empty arg. ignored
    \ifx#1!\else % Exclamation mark ends the list
      \@defaultunits\@tempdima#1pt\relax\@nnil
      #3\NCC@parsedash#2\@nil{#3}%
    \fi
  \fi
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\NCC@vdash}
% |\NCC@vdash|\marg{h-pattern} is
% applied when a vertical dash is composed.
% |\@tempdimb| contains the required skip,
% |\@tempdima| contains the rule height.
%    \begin{macrocode}
\def\NCC@vdash#1{%
  \setbox\@tempboxa\vbox{%
    \unvbox\@tempboxa \vskip\@tempdimb
    \setbox\@tempboxa\hbox{}%
    \@tempskipa\@tempdima % Save rule height in \@tempskipa
    \NCC@composedash{\NCC@hdash}{#1}%
    \hb@xt@\@tempdimc{\hss\unhbox\@tempboxa\hss}%
  }%
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\NCC@hdash}
% This action is applied when a horizontal dash is composed.
% |\@tempdimb| contains the required skip,
% |\@tempdima| contains the rule width,
% |\@tempskipa| contains the rule height.
%    \begin{macrocode}
\def\NCC@hdash{%
  \setbox\@tempboxa\hbox{%
    \unhbox\@tempboxa \kern\@tempdimb
    \vrule \@width\@tempdima \@height\@tempskipa
  }%
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\NCC@fnoterule}
% |\NCC@fnoterule|\marg{width}\marg{rule code}\\
% This is the footnote rule producing command.
% As usual, two kerns must be inserted surround the rule: a negative
% kern before the rule and a nonnegative kern after the rule.
% The sum of kern values and of the total rule height must
% vanish. Kerns are calculated in such a way to vertically center
% the rule relative to 2.8pt distance top to the current position.
% If the total height of rule is greater than 5.6pt, the rule is moved
% up on the total rule height (the kern after the rule is zero in this case).
%    \begin{macrocode}
\def\NCC@fnoterule#1#2{%
  \setlength\@tempdima{#1}%
  \setbox\@tempboxa\hb@xt@\@tempdima{#2}%
  \@tempdima\ht\@tempboxa \advance\@tempdima\dp\@tempboxa
  \@tempdimb 2.8\p@ \@tempdimc .5\@tempdima
  \ifdim\@tempdimc>\@tempdimb \@tempdimb\@tempdimc \fi
  \advance\@tempdimb\@tempdimc
  \kern-\@tempdimb
  \box\@tempboxa
  \advance\@tempdimb -\@tempdima
  \kern\@tempdimb
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\NCC@fnotedashrule}
% |\NCC@fnotedashrule|\marg{width}\marg{h-pattern}\marg{v-pattern}\\
% Produces the rule based on |\dashrulefill|. A special case of empty
% \meta{h-pattern} means the solid (maybe multi-line) rule.
%    \begin{macrocode}
\def\NCC@fnotedashrule#1#2#3{%
  \NCC@fnoterule{#1}{\def\@tempa{#2}%
    \ifx\@tempa\@empty
      \@tempskipb\@tempdima \dashrule{\@tempskipb}{#3}%
    \else
      \dashrulefill[\z@][s]{#2}{#3}%
    \fi
  }%
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\NCC@fnotecreate}
% |\NCC@fnotecreate|\marg{prefix}\marg{body}\\
% Creates a footnote rule whose name is composed from the
% given \meta{prefix} and |footnoterule|. For example if the prefix
% is |dashed|, the |\dashedfootnoterule| command will be created.
%    \begin{macrocode}
\def\NCC@fnotecreate#1{%
  \edef\@tempa{\noexpand\newcommand*%
    \expandafter\noexpand\csname #1footnoterule\endcsname}%
  \@tempa
}
\@onlypreamble\NCC@fnotecreate
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\NCC@fnoteprepare}
% |\NCC@fnoteprepare|\marg{driver}\marg{prefix}\oarg{width}\\
% Prepares a footnote rule command. The \meta{driver} is a command
% that will be called for collecting rule code (it gets more arguments
% from the input). When a driver prepares the code, it calls the
% |\NCC@fnotecreate| command. If \meta{width} is omitted, the standard
% width of |0.4\columnwidth| is used.
%    \begin{macrocode}
\def\NCC@fnoteprepare#1#2{%
  \@ifnextchar[{#1{#2}}{#1{#2}[.4\columnwidth]}%
}
\@onlypreamble\NCC@fnoteprepare
%    \end{macrocode}
% \end{macro}
%
% Footnote rule creation driver has the following syntax:
% \begin{quote}
% |\|\meta{driver}\marg{prefix}\oarg{width}\meta{more arguments}
% \end{quote}
%
% \begin{macro}{\newfootnoterule}
% |\newfootnoterule|\marg{prefix}\oarg{width}\marg{rule code}
%    \begin{macrocode}
\newcommand\newfootnoterule{\NCC@fnoteprepare\NCC@fnotedriver}
\def\NCC@fnotedriver#1[#2]#3{%
  \NCC@fnotecreate{#1}{\NCC@fnoterule{#2}{#3}}%
}
\@onlypreamble\newfootnoterule
\@onlypreamble\NCC@fnotedriver
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\newfootnotedashrule}
% |\newfootnotedashrule|\marg{prefix}\oarg{width}\marg{h-pattern}\marg{v-pattern}
%    \begin{macrocode}
\newcommand\newfootnotedashrule{\NCC@fnoteprepare\NCC@fnotedashdriver}
\def\NCC@fnotedashdriver#1[#2]#3#4{%
  \NCC@fnotecreate{#1}{\NCC@fnotedashrule{#2}{#3}{#4}}%
}
\@onlypreamble\newfootnotedashrule
\@onlypreamble\NCC@fnotedashdriver
%</package>
%    \end{macrocode}
% \end{macro}
\endinput