From 41d4e60fba44409eb9361200ff517a6bf67936c6 Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Fri, 24 Sep 2010 00:06:55 +0000 Subject: now in generic (23sep10) git-svn-id: svn://tug.org/texlive/trunk@19866 c570f23f-e606-0410-a88d-b1316a301751 --- Master/texmf-dist/doc/generic/path/path-doc.pdf | Bin 0 -> 286785 bytes Master/texmf-dist/doc/generic/path/path-doc.tex | 146 ++++++++++++++++++++++++ 2 files changed, 146 insertions(+) create mode 100644 Master/texmf-dist/doc/generic/path/path-doc.pdf create mode 100644 Master/texmf-dist/doc/generic/path/path-doc.tex (limited to 'Master/texmf-dist/doc/generic/path') diff --git a/Master/texmf-dist/doc/generic/path/path-doc.pdf b/Master/texmf-dist/doc/generic/path/path-doc.pdf new file mode 100644 index 00000000000..184ef6eaff2 Binary files /dev/null and b/Master/texmf-dist/doc/generic/path/path-doc.pdf differ diff --git a/Master/texmf-dist/doc/generic/path/path-doc.tex b/Master/texmf-dist/doc/generic/path/path-doc.tex new file mode 100644 index 00000000000..e11b8c53618 --- /dev/null +++ b/Master/texmf-dist/doc/generic/path/path-doc.tex @@ -0,0 +1,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 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} -- cgit v1.2.3