Debian Codegraph @

doc/path.sty

raw
1 %%% @texfile{
2 %%% author = "Philip Taylor",
3 %%% version = "3.04",
4 %%% date = "25 July 1992",
5 %%% time = "17:07 EDT",
6 %%% filename = "path.sty",
7 %%% address = "The Computer Centre
8 %%% RHBNC, University of London
9 %%% Egham Hill
10 %%% Egham, Surrey TW20 0EX, ENGLAND",
11 %%% telephone = "Tel: +44 784 443172",
12 %%% FAX = "Fax: +44 784 434348",
13 %%% checksum = "06928 345 1934 14197",
14 %%% email = "[email protected] (Internet)",
15 %%% codetable = "ISO/ASCII",
16 %%% keywords = "file name, filename, path name, pathname,
17 %%% discretionary, discretionaries",
18 %%% supported = "yes",
19 %%% docstring = {Computer filenames, host names, and e-mail
20 %%% addresses tend to be long strings that
21 %%% cause line breaking problems for TeX.
22 %%% Sometimes rather long strings are
23 %%% encountered; here are two examples:
24 %%%
25 %%% Friesland%rz.informatik.uni-hamburg.dbp.de%[email protected]
26 %%%
27 %%% mighty-mouse-gw.scrc.symbolics.com
28 %%%
29 %%% This file defines a macro, \path|...|,
30 %%% similar to LaTeX's \verb|...| macro, that
31 %%% sets the text in the typewriter font,
32 %%% allowing hyphen-less line breaks at
33 %%% punctuation characters.
34 %%%
35 %%% The default set of punctuation characters is
36 %%% defined as
37 %%%
38 %%% \discretionaries |~!@$%^&*()_+`-=#{"}[]:;'<>,.?\/|
39 %%%
40 %%% However, you can change it as needed, for example:
41 %%%
42 %%% \discretionaries +@%!.+
43 %%%
44 %%% would assign to it the set @ % ! . which
45 %%% commonly occur in electronic mail addresses.
46 %%%
47 %%% The delimiter characters surrounding the
48 %%% arguments to \discretionaries and \path
49 %%% will normally be a punctuation character not
50 %%% found in the argument, and not otherwise
51 %%% significant to TeX. In particular, backslash
52 %%% cannot be used as a delimiter. In the rare
53 %%% event that this is required, set
54 %%%
55 %%% \specialpathdelimiterstrue
56 %%%
57 %%% This practice is not recommended, because TeX
58 %%% then runs about four times slower while it is
59 %%% typesetting \path\...\ requests.
60 %%% \specialpathdelimitersfalse is the normal
61 %%% setting.
62 %%%
63 %%% This file may be used in Plain TeX or AmSTeX by
64 %%%
65 %%% \input path.sty
66 %%%
67 %%% and in LaTeX by
68 %%%
69 %%% \documentstyle[...,path,...]{...}
70 %%%
71 %%% The checksum field above contains a CRC-16
72 %%% checksum as the first value, followed by the
73 %%% equivalent of the standard UNIX wc (word
74 %%% count) utility output of lines, words, and
75 %%% characters. This is produced by Robert
76 %%% Solovay's checksum utility.}
77 %%% }
78 %
79 % ======================================================================
80 %
81 % History of the \path macro
82 %
83 % An early prototype of this code which was developed by Nelson H. F.
84 % Beebe <[email protected]> used a recursive macro to peel off one
85 % character at a time, then with a nest of \ifx statements, test for
86 % each punctuation character, and if one is found, insert discretionary
87 % linebreaks in the form of \- or \penalty0. While this usually works,
88 % it is not entirely satisfactory, because the nested \ifx statements
89 % are ugly, and the recursion can exhaust TeX's macro stack for
90 % arguments longer than about 30 characters.
91 %
92 % A second version by NHFB built upon the ideas used by the LaTeX
93 % \verb|...| macro; this was mostly successful, but was flawed by its
94 % inability to handle at least the three characters ^ [ ], by loss of
95 % use of @ for naming internal private macros, and by its inability to
96 % allow the set of characters at which breaks are permissible.
97 %
98 % The problem was then passed off to Philip Taylor, who wrote this third
99 % version which fully solves the problem. Phil therefore gets the
100 % author credit in the file header above. [Gee, thanks ! ** Phil]
101 %
102 % Then Karl Berry <[email protected]> made minor changes in July 1992.
103 %
104 % Revision history (reverse time order):
105 %
106 % 3.04 [22-Jul-1992]
107 % (changes by [email protected], with Phil's blessing):
108 % 1) use \edef to avoid wasting a count register merely to save the
109 % catcode of @.
110 %
111 % 2) Expand a macro \pathafterhook (if it's defined) once \path is
112 % entirely finished, for the benefit of macros using \path.
113 %
114 % 3) % all blank lines and post-}'s, in the (highly unusual) case that
115 % the file is being read in horizontal mode. Use only one %, not
116 % three, so the comments can be easily removed automatically.
117 %
118 % 4) Remove the \endinput from the end of the file. What does it add?
119 %
120 %
121 % 3.03 [03-Dec-1991]
122 % Problem: A \path|...| entry in a LaTeX index is set with an
123 % preceding blank line.
124 % Solution: Add \leavevmode before \hbox{}; without it, an extra blank
125 % line gets typeset before every invocation of \path in a
126 % LaTeX theindex environment.
127 % Diagnosis: To avoid hyphenation, the expansion of \path starts with
128 % an \hbox{} (c.f. the TeXbook, p. 454); LaTeX indices are
129 % basically set in vertical mode, with each index entry a
130 % paragraph in its own right; when an \hbox {} is
131 % encountered in vmode, it is typeset in vmode, and TeX
132 % continues; the first real character is encountered, and
133 % TeX enters unrestricted horizontal mode. The \hbox {} and
134 % the first character are therefore on separate lines,
135 % separated by \baselineskip.
136 %
137 %
138 % 3.02 [23-Oct-1991 13:45:12]
139 % First released version.
140 % ======================================================================
141 %
142 \immediate\write16{path.sty version 3.04 <25 Jul 1992>}%
143 %
144 % The use of `\path' as a temporary control sequence is a kludge, but
145 % it's a reasonably simple way to accomplish making @ a letter (to
146 % provide ``concealed'' control sequences) without overwriting something
147 % (without an `@' in its name) that might already be defined.
148 %
149 \edef\path{\the\catcode`@}%
150 \catcode`@ = 11
151 \let\@oldatcatcode = \path
152 %
153 %
154 % and then declare two \count variables with concealed names
155 %
156 \newcount \c@tcode
157 \newcount \c@unter
158 %
159 %
160 % and a boolean variable with an open name, to specify the nature of
161 % the delimiters which will be associated with the \path command
162 %
163 \newif \ifspecialpathdelimiters
164 %
165 %
166 % We need to define control sequences which expand to both
167 % active and passive spaces ...
168 %
169 \begingroup
170 \catcode `\ = 10
171 \gdef \passivesp@ce { }%
172 \catcode `\ = 13\relax%
173 \gdef\activesp@ce{ }%
174 \endgroup
175 %
176 %
177 % \discretionaries will define a macro \discr@ti@n@ri@s which will
178 % make every character between the first and final <delim> a
179 % discretionary breakpoint.
180 %
181 \def \discretionaries % <delim> <chars> <delim>
182 % start a group (ended in \discr@ti@naries ),
183 % make every character (apart from space) active,
184 % then transfer control to \discr@tionaries ...
185 {\begingroup
186 \c@tcodes = 13
187 \discr@tionaries
188 }%
189 %
190 %
191 % \discr@tionaries will receive as parameter the initial <delim>
192 % which will delimit the set of discretionaries; this <delim>
193 % will be active.
194 %
195 \def \discr@tionaries #1% <delim>
196 % knowing the initial <delim>, define \discr@ti@naries with a
197 % delimited parameter structure, the final delimiter being
198 % the second instance of <delim>
199 {\def \discr@ti@naries ##1#1% <chars> <delim>
200 % \discr@ti@naries will receive as parameter the set of
201 % characters which are to be made discretionaries; it ends the
202 % group and then defines \discr@ti@n@ries, a tail-recursive
203 % macro, which will quietly process each of the
204 % discretionaries in turn ...
205 {\endgroup
206 \def \discr@ti@n@ries ####1% <char> or <delim>
207 % by checking to see if it has reached the end of the
208 % list, i.e. comparing its parameter with the known final
209 % <delim> ...
210 {\if \noexpand ####1\noexpand #1%
211 % if they match, there is no more to do ...
212 \let \n@xt = \relax
213 \else
214 % otherwise the character becomes active and is
215 % defined as a discretionary with the three texts
216 % <self> <empty> <self>, thus suppressing true
217 % hyphenation; the macro then prepares to process
218 % the next character.
219 \catcode `####1 = 13
220 \def ####1{\discretionary
221 {\char `####1}{}{\char `####1}}%
222 \let \n@xt = \discr@ti@n@ries
223 \fi
224 % here either tail recursion occurs, if there are more
225 % characters to process, or tail recursion ceases if all
226 % have been exhausted
227 \n@xt
228 }%
229 % of course, none of this must take place during the \stress
230 % {call} of \discretionaries; execution is deferred until
231 % another macro such as \path calls the concealed action
232 % macro \discr@ti@n@ri@s; we therefore define this macro to
233 % have the desired effect.
234 \def \discr@ti@n@ri@s {\discr@ti@n@ries ##1#1}%
235 }%
236 % and finally invoke \discr@ti@naries to process the set of
237 % discretionary characters; it will take everything up to the
238 % second instance of <delim> as its parameter (and therefore as the
239 % set of characters to be processed).
240 \discr@ti@naries
241 }%
242 %
243 %
244 % If desired, you can define \pathafterhook to be anything.
245 %
246 \let\pathafterhook = \relax
247 %
248 %
249 % \path, which is the user interface to \p@th, first checks to see
250 % whether \specialpathdelimiters is <true> or <false>; if <true>, it
251 % needs to take special action to ensure that \stress {all} characters
252 % (apart from <space>) are acceptable as delimiters; this is very
253 % time-consuming, and should be avoided if at all possible. It also
254 % defines \endp@th, to close the appropriate number of groups, and
255 % finally transfers control to \p@th.
256 %
257 \def \path
258 {\ifspecialpathdelimiters
259 \begingroup
260 \c@tcodes = 12
261 \def \endp@th {\endgroup \endgroup \pathafterhook}%
262 \else
263 \def \endp@th {\endgroup \pathafterhook}%
264 \fi
265 \p@th
266 }%
267 %
268 %
269 % \p@th, which has essentially the same syntax as \discretionaries,
270 % expects to be followed by a <delim>, a <path>, and a second instance
271 % of <delim>; it will typeset <path> in the \tt font with hyphenation
272 % inhibited --- breaks (but not true hyphenation) are allowed at any
273 % or all of the special characters which have
274 % previously been declared as \discretionaries.
275 %
276 \def \p@th #1% <delim>
277 % it starts by opening a group (ended in \p@@th) ...
278 % switches to \tt, and inhibits hyphenation;
279 % allows breaks at \discretionaries; saves the
280 % catcode of the initial <delim>, because if it has also been
281 % declared within \discretionaries, the initial and final <delim>
282 % won't match (which would be a disaster); \c@tcode is overloaded,
283 % but there is no conflict that I can detect ...
284 % invokes \discr@ti@n@ri@s to render active the set of special
285 % characters which have previously been declared as
286 % \discretionaries; each of these characters will expand to a real
287 % \discretionary, with replacement texts <self> <null> <self>; and
288 % re-instates the catcode of the initial <delim>.
289 {\begingroup
290 \tt
291 \c@tcode = \catcode `#1
292 \discr@ti@n@ri@s
293 \catcode `\ = \active
294 \expandafter \edef \activesp@ce {\passivesp@ce \hbox {}}%
295 \catcode `#1 = \c@tcode
296 % it next defines an inner macro \p@@th with delimited parameter
297 % structure, the final delimiter being the same as the initial
298 % delimiter which it has itself received as #1.
299 \def \p@@th ##1#1% <chars> <delim>
300 % Within \p@@th,
301 % permissible breakpoints are specified,
302 % the path is typeset,
303 % and the group(s) ended.
304 {\leavevmode \hbox {}##1%
305 \endp@th
306 }%
307 \p@@th
308 }%
309 %
310 %
311 % \c@tcodes expects to be followed by the r-h-s of a numeric assignment
312 %optionally including the assignment operator; it saves the value of the
313 %r-h-s in \c@tcode, and invokes \c@tc@des.
314 %
315 \def \c@tcodes {\afterassignment \c@tc@des \c@tcode}%
316 %
317 %
318 % \c@tc@des uses the value saved in \c@tcode, and assigns it to the
319 % \catcode of all characters with the single exception of <space>, which
320 % retains its normal catcode of 10; on exit, every single character
321 % apart from <space> will have the catcode which followed \c@tcodes.
322 % The code is optimised to avoid unnecessary usage of save-stack space.
323 %
324 \def \c@tc@des
325 {\c@unter = 0
326 \loop
327 \ifnum \catcode \c@unter = \c@tcode
328 \else
329 \catcode \c@unter = \c@tcode
330 \fi
331 \ifnum \c@unter < 255
332 \advance \c@unter by 1
333 \repeat
334 \catcode `\ = 10
335 }%
336 %
337 %
338 % Restore the original catcode of commercial-at.
339 \catcode `\@ = \@oldatcatcode
340 %
341 %
342 % Define a default set of discretionary break characters to include all
343 % punctuation characters except vertical bar.
344 %
345 \discretionaries |~!@$%^&*()_+`-=#{}[]:";'<>,.?\/|%