summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/generic/path/path-doc.tex
blob: 9f28e3674e267cc9df599e5d2a985604e537ee59 (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
\documentclass[pagesize=auto, fontsize=11pt, DIV=9]{scrartcl}

\usepackage{fixltx2e}
\usepackage{etex}
\usepackage{lmodern}
\usepackage[T1]{fontenc}
\usepackage{textcomp}
\usepackage{hologo}
\usepackage{microtype}
\usepackage{hyperref}

\newcommand*{\mail}[1]{\href{mailto:#1}{\texttt{#1}}}
\newcommand*{\bmail}[1]{\href{mailto:#1}{\texttt{<#1>}}}
\newcommand*{\pkg}[1]{\textsf{#1}}
\newcommand*{\cs}[1]{\texttt{\textbackslash#1}}
\makeatletter
\newcommand*{\cmd}[1]{\cs{\expandafter\@gobble\string#1}}
\makeatother
\newcommand*{\env}[1]{\texttt{#1}}

\addtokomafont{title}{\rmfamily}
\deffootnote{1em}{0.5em}{\textsuperscript{\thefootnotemark}}

\title{The \pkg{path} package\thanks{This manual corresponds to \pkg{path.sty}~v3.03b, dated~22 July 1997.}}
\author{Philip Taylor\thanks{The Computer Centre\newline RHBNC, University of London\newline Egham Hill\newline Egham, Surrey TW20 0EX, ENGLAND\newline Tel: +44 1784 443172\newline Fax: +44 1784 434348\newline\mail{P.Taylor@Vms.Rhbnc.Ac.Uk}}}
\date{22 July 1997}


\begin{document}

\maketitle

\noindent
Computer filenames, host names, and e-mail
addresses tend to be long strings that
cause line breaking problems for \TeX\@.
Sometimes rather long strings are
encountered, such as:
%
\begin{verbatim}
  mighty-mouse-gw.scrc.symbolics.com
\end{verbatim}
%
This file defines a macro, \verb+\path|...|+, similar to \LaTeX's
\verb+\verb|...|+ macro, that sets the text in the typewriter font,
allowing hyphen-less line breaks at punctuation characters.  The macro
\verb+\pathafterhook+ is expanded after the work of \verb+\path|...|+ is
done.

The default set of punctuation characters is
defined as
%
\begin{verbatim}
  \discretionaries |~!@$%^&*()_+`-=#{"}[]:;'<>,.?\/|
\end{verbatim}
%
However, you can change it as needed, for
example
%
\begin{verbatim}
  \discretionaries +@%!.+
\end{verbatim}
%
would assign to it the set \verb+@ % ! .+ which
commonly occur in electronic mail addresses.

The delimiter characters surrounding the
arguments to \cmd{\discretionaries} and \cmd{\path}
will normally be a punctuation character not
found in the argument, and not otherwise
significant to \TeX\@.  In particular, backslash
cannot be used as a delimiter.  In the rare
event that this is required, set
%
\begin{verbatim}
  \specialpathdelimiterstrue
\end{verbatim}
%
This practice is not recommended, because \TeX\ %
then runs about four times slower while it is
typesetting \verb+\path\...\+ requests.
\cmd{\specialpathdelimitersfalse} is the normal
setting.

This file may be used in \hologo{plainTeX} or \hologo{AmSTeX}
by
%
\begin{verbatim}
  \input path.sty
\end{verbatim}
%
and in \LaTeX\ by
%
\begin{verbatim}
  \usepackage {path}
\end{verbatim}

The \texttt{checksum} field above, if present, contains
a CRC-16 checksum as the first value, followed
by the equivalent of the standard UNIX \texttt{wc} (word
count) utility output of lines, words, and
characters.  This is produced by Robert
Solovay's \texttt{checksum} utility.


\section*{The \cmd{\path} Macro}

An early prototype of this code which was developed by Nelson~H.~F.
Beebe \bmail{beebe@math.utah.edu} used a recursive macro to peel off one
character at a time, then with a nest of \verb+\ifx+ statements, test for
each punctuation character, and if one is found, insert discretionary
linebreaks in the form of \cmd{\-} or \verb+\penalty0+\@.  While this usually works,
it is not entirely satisfactory, because the nested \verb+\ifx+ statements
are ugly, and the recursion can exhaust \TeX's macro stack for
arguments longer than about 30~characters.

A second version by NHFB built upon the ideas used by the \LaTeX\ %
\verb+\verb|...|+ macro; this was mostly successful, but was flawed by its
inability to handle at least the three characters \verb+^ [ ]+, by loss of
use of \texttt{@} for naming internal private macros, and by its inability to
allow the set of characters at which breaks are permissible.

The problem was then passed off to Philip Taylor, who wrote this third
version which fully solves the problem.  Phil therefore gets the
author credit in the file header above.  [Gee, thanks~!  $**$ Phil]


\minisec{Revision history (reverse time order):}

\medskip

\noindent
\begin{tabular}{@{} p{0.14\linewidth} @{} p{0.86\linewidth} @{}}
  \multicolumn{2}{@{}l@{}}{3.03b [22-Jul-1997]} \\
  Summary:   & No code changes.  An out-of-date example removed, the syntax for \LaTeXe\ changed to ``\verb+\usepackage {path}+'', and the ``checksum'' comments modified to indicate that the checksum is not necessarily present.  The initial opening brace re-positioned to align with the matching closing brace, and the inner closing brace re-positioned to align with the inner opening brace.  A check made to ensure that no \textsf{\textlangle tab\textrangle} characters are present. \\[\bigskipamount]
  \multicolumn{2}{@{}l@{}}{3.03a [22-Jul-1997]} \\
  Summary:   & No code changes from V3.03; e-mail addresses, telephone numbers, etc.\ amended to reflect current situation.  Checksum removed. \\[\bigskipamount]
  \multicolumn{2}{@{}l@{}}{3.03 [03-Dec-1991]} \\
  Problem:   & A \verb+\path|...|+ entry in a \LaTeX\ index is set with an preceding blank line. \\
  Solution:  & Add \cmd{\leavevmode} before \verb+\hbox{}+; without it, an extra blank line gets typeset before every invocation of \cmd{\path} in a \LaTeX\ \env{theindex} environment. \\
  Diagnosis: & To avoid hyphenation, the expansion of \cmd{\path} starts with an \verb+\hbox{}+ (c.\,f.\ the \TeX book, p.~454); \LaTeX\ indices are basically set in vertical mode, with each index entry a paragraph in its own right; when an \verb+\hbox {}+ is encountered in vmode, it is typeset in vmode, and \TeX\ continues; the first real character is encountered, and \TeX\ enters unrestricted horizontal mode.  The \verb+\hbox {}+ and the first character are therefore on separate lines, separated by \cmd{\baselineskip}. \\[\bigskipamount]
  \multicolumn{2}{@{}l@{}}{3.02 [23-Oct-1991 13:45:12]} \\
  \multicolumn{2}{@{}l@{}}{First released version.}  
\end{tabular}

\end{document}