Debian Codegraph @

texmf-dist/doc/latex/url/url.tex

raw
1 \documentclass[a4paper,11pt]{article}
2 \usepackage[T1]{fontenc}
3 \usepackage{lmodern}
4 \usepackage{miscdoc,url,booktabs,microtype}
5 \addtolength\textwidth{1cm}
6 \addtolength\oddsidemargin{-.5cm}
7 \addtolength\evensidemargin{-.5cm}
8 \raggedbottom
9 \setlength\parskip{4pt plus 2pt}
10
11 \begin{document}
12 \title{\texttt{url.sty} version 3.4}
13 \date{2013-09-16}
14 \author{Donald Arseneau%
15 \thanks{Thanks to Robin Fairbairns for documentation conversion!}}
16 \maketitle
17
18 % url.sty ver 3.4 16-Sep-2013 Donald Arseneau [email protected]
19 % Copyright 1996-2013 Donald Arseneau, Vancouver, Canada.
20 % This program can be used, distributed, and modified under the terms
21 % of the LaTeX Project Public License, version 2 or later.
22
23 The package defines a form of \cs{verb} command that allows linebreaks
24 at certain characters or combinations of characters, accepts
25 reconfiguration, and can usually be used in the argument to another
26 command. It is intended for formatting email addresses, hypertext links,
27 directories/paths, etc., which normally have no spaces. The font used
28 may be selected using the \cs{urlstyle} command, and new url-like
29 commands may be defined using \cs{urldef}.
30 This package does not make hyper-links! For that purpose, see the hyperref
31 package (or some other deprecated ones).
32
33 \begin{center}
34 \begin{tabular}{lp{3.5in}}
35 \toprule
36 Usage & Conditions \\
37 \midrule
38 \verb+\url{ }+ & The argument must not contain unbalanced braces.
39 If used in the argument to another command, the
40 \cs{url} argument cannot contain any ``\verb+%+'',
41 ``\verb+#+'', or ``\verb+^^+'', or end with
42 ``\verb+\+''.\\
43 \verb+\url| |+ & where ``\texttt{|}'' is any character not used
44 in the argument and not ``\verb+{+'' or a space.
45 The same restrictions apply as above except that
46 the argument may contain unbalanced braces.\\
47 \cs{xyz} & for the defined-url ``\cs{xyz}''; such a command can be
48 used anywhere, no matter what characters it contains. \\
49 \bottomrule
50 \end{tabular}
51 \end{center}
52
53 \noindent The ``\cs{url}'' command is fragile, and its argument is likely to be
54 very fragile, but a defined-url is robust.
55
56 \section{Package options}
57
58 \newitem Package Option: \texttt{obeyspaces}
59
60 Ordinarily, all spaces are ignored in the url-text. The
61 ``\texttt{[obeyspaces]}'' option allows spaces, but may introduce
62 spurious spaces when a url containing ``\cs{}'' characters is given in
63 the argument to another command.
64 So if you need to obey spaces you can say
65 ``\cs{usepackage}\texttt{[obeyspaces]\char`\{url\char`\}}'', and if
66 you need both spaces and backslashes, use a defined-url.
67
68 \newitem Package Option: \texttt{hyphens}
69
70 Ordinarily, breaks are not allowed after ``\texttt{-}'' characters
71 because this leads to confusion. (Is the ``\texttt{-}'' part of the
72 address or just a hyphen?)
73 The package option ``\texttt{[hyphens]}'' allows breaks after explicit
74 hyphen characters. The \cs{url} command will \textbf{never ever}
75 hyphenate words.
76
77 \newitem Package Option: \texttt{spaces}
78
79 Likewise, given the ``\texttt{[obeyspaces]}'' option, breaks are not
80 usually allowed after the spaces, but if you give the options
81 ``\texttt{[obeyspaces,spaces]}'', \cs{url} will allow breaks at those
82 spaces.
83 \begin{quote}
84 Note that it seems logical to allow the sole option
85 ``\texttt{[spaces]}'' to let input spaces indicate break points, but
86 not to display them in the output. This would be easy to implement,
87 but is left out to avoid(?)\ confusion.
88 \end{quote}
89
90 \newitem Package Option: \texttt{lowtilde}
91
92 Normal treatment of the \verb+~+ character is to use the font's
93 ``\cs{textasciitilde}'' character, if it has one (or claims to).
94 Otherwise, the character is faked using a mathematical ``\cs{sim}''.
95 The ``\texttt{[lowtilde]}'' option causes a faked character to be used
96 always (and a bit lower than usual).
97
98 \newitem Package Option: \texttt{allowmove}
99
100 This option suppresses the test for \cs{url} being used in a so-called
101 moving argument (check ``fragile command''). Using it will enable \cs{url}
102 to function in more contexts, but when it does fail, the error message
103 may be incomprehensible.
104
105
106 \section{Defining a defined-url}
107
108 Take for example the email address ``\url{myself%[email protected]}"
109 which could not be given (using ``\cs{url}'' or ``\cs{verb}'') in a
110 caption or parbox due to the percent sign. This address can be
111 predefined with
112 \begin{quote}
113 \verb|\urldef{\myself}\url{myself%[email protected]}| or\\
114 \verb+\urldef{\myself}\url|myself%[email protected]|+
115 \end{quote}
116 and then you may use ``\cs{myself}'' instead of
117 ``\verb+\url{myself%[email protected]}+''
118 in an argument, and even in a moving argument like a caption because a
119 defined-url is robust.
120
121 \section{Style}
122
123 You can switch the style of printing using ``\verb+\urlstyle{+$xx$\verb+}+'',
124 where ``$xx$'' can be any defined style. The pre-defined styles are
125 ``\texttt{tt}'', ``\texttt{rm}'', ``\texttt{sf}'' and ``\texttt{same}''
126 which all allow the same linebreaks but use different fonts~--- the
127 first three select a specific font and the ``\texttt{same}'' style
128 uses the current text font. You can define your own styles with
129 different fonts and/or line-breaking by following the explanations
130 below. The ``\cs{url}'' command follows whatever the currently-set
131 style dictates.
132
133 \section{Alternate commands}
134
135 It may be desireable to have different things treated differently, each
136 in a predefined style; e.g., if you want directory paths to always be
137 in typewriter and email addresses to be roman, then you would define new
138 url-like commands as follows:
139 \begin{quote}
140 \verb+\DeclareUrlCommand+\meta{command}\verb+{+\meta{settings}\verb+}+\\
141 \verb+\DeclareUrlCommand\email{\urlstyle{rm}}+\\
142 \verb+\DeclareUrlCommand\directory{\urlstyle{tt}}+.
143 \end{quote}
144 In fact, this \cs{directory} example is exactly the \cs{path}
145 definition which might be pre-defined by the package. Furthermore,
146 basic \cs{url} is defined with
147 \begin{quote}
148 \verb+\DeclareUrlCommand\url{}+,
149 \end{quote}
150 without any \emph{settings}, so it uses whatever \cs{urlstyle}
151 and other settings are already in effect.
152
153 You can make a defined-url for these other styles, using the usual
154 \cs{urldef} command as in this example:
155 \begin{quote}
156 \verb+\urldef{\myself}{\email}{myself%[email protected]}+
157 \end{quote}
158 which makes \cs{myself} act like
159 \verb+\email{myself%[email protected]}+,
160 if the \cs{email} command is defined as above. The \cs{myself}
161 command would then be robust.
162
163 \section{Defining styles}
164
165 Before describing how to customize the printing style, it is best to
166 mention something about the unusual implementation of \cs{url}. Although
167 the material is textual in nature, and the font specification required
168 is a text-font command, the text is actually typeset in \emph{math} mode.
169 This allows the context-sensitive linebreaking, but also accounts for
170 the default behavior of ignoring spaces. (Maybe that underlying design
171 will eventually change.) Now on to defining styles.
172
173 To change the font or the list of characters that allow linebreaks, you
174 could redefine the commands \cs{UrlFont}, \cs{UrlBreaks},
175 \cs{UrlSpecials}, etc., directly in the document, but it is better to
176 define a new `url-style' (following the example of \cs{url@ttstyle}
177 and \cs{url@rmstyle}) which defines all of \cs{UrlBigbreaks},
178 \cs{UrlNoBreaks}, \cs{UrlBreaks}, \cs{UrlSpecials}, and \cs{UrlFont}.
179
180 \subsection{Changing font}
181 The \cs{UrlFont} command selects the font. The definition of
182 \cs{UrlFont} done by the pre-defined styles varies to cope with a
183 variety of \LaTeX{} font selection schemes, but it could be as simple
184 as \verb+\def\UrlFont{\tt}+. Depending on the font selected, some
185 characters may need to be defined in the \cs{UrlSpecials} list because
186 many fonts don't contain all the standard input characters.
187
188 \subsection{Changing linebreaks}
189 The list of characters after which line-breaks are permitted is
190 given by the two commands (list macros)
191 \cs{UrlBreaks} and \cs{UrlBigBreaks}. They consist of repeating
192 \cs{do}\cs{c} for each relevant character \texttt{c}.
193
194 The differences are that `BigBreaks' typically have a lower penalty (more
195 easily chosen) and do not break within a repeating sequence (e.g.,
196 ``\verb+DEC::NODE+'').
197 (For gurus: `BigBreaks' are treated as mathrels while `Breaks' are mathbins;
198 see \textit{The TeXbook}, p.\,170.) The result is that a series of
199 consecutive `BigBreak'
200 characters will break at the end and only at the end; a series of
201 `Break' characters will break after the first and after every following
202 \emph{pair}; there will be no break between a `Break' character and a
203 following `BigBreak' char; breaks are permitted when a `BigBreak'
204 character is followed by `Break' or any other char. In the case
205 of \texttt{http://} it doesn't matter whether \texttt{:} is a
206 `Break' or `BigBreak'~--- the breaks are the same in either case; but
207 for (now ancient) \emph{DECnet} addresses using \texttt{::} it was
208 important to prevent breaks \emph{between} the colons, and that is why
209 colons are `BigBreaks'. (The only other `BigBreak' character is,
210 optionally, the hyphen; slashes are regular `Break's.)
211
212 It is possible for characters to prevent breaks after the next
213 following character (this is used for parentheses). Specify these in
214 \cs{UrlNoBreaks}.
215
216 You can allow some spacing around the breakable characters by assigning
217 \begin{quote}
218 \verb+\Urlmuskip = 0mu plus 1mu+
219 \end{quote}
220 (with \texttt{mu} units because of math mode).
221 You can change the penalties used for BigBreaks and Breaks by assigning
222 \begin{quote}
223 \verb+\mathchardef\UrlBreakPenalty=100+\\
224 \verb+\mathchardef\UrlBigBreakPenalty=100+
225 \end{quote}
226 The default penalties are \cs{binoppenalty} and \cs{relpenalty}.
227 These have such odd non-\LaTeX{} syntax because I don't expect people
228 to need to change them often. (The \verb+\mathchardef+ does not relate to
229 math mode; it is only a way to store a number without consuming registers.)
230
231 \subsubsection{Arbitrary character actions}
232
233 You can do arbitrarily complex things with characters by specifying
234 their definition(s) in \cs{UrlSpecials}. This makes them `active' in
235 math mode (mathcode \texttt{"8000}). The format for setting
236 each special character \texttt{c} is:
237 \verb+\do\c{+\meta{definition}\verb+}+, but other definitions not
238 following this style can also be included.
239
240 Here is an example to make ``\texttt{!}''\ inside \cs{url} force a line break
241 instead of being treated verbatim (it uses \LaTeX's \cs{g@addto@macro}):
242
243 \begin{quote}
244 \verb+\makeatletter \g@addto@macro\UrlSpecials{\do\!{\newline}}+
245 \end{quote}
246
247 Here is another overly-complicated example to put extra flexible
248 muglue around each ``\texttt{/}'' character, except when followed
249 by another ``\texttt{/}'', as in ``\texttt{http://}'', where extra
250 spacing looks poor.
251
252 \begin{quote}
253 \begin{verbatim}
254 % what we'll insert before and after each (lone) slash:
255 \newmuskip\Urlslashmuskip
256 \Urlslashmuskip=2mu plus2mu minus2mu
257
258 % change what / does:
259 \g@addto@macro\UrlSpecials{\do\/{\Urlspaceyslash}}
260
261 % need to look ahead:
262 \def\Urlspaceyslash{\futurelet\Urlssnext\finishUrlspaceyslash}
263
264 \def\finishUrlspaceyslash{%
265 \mskip\Urlslashmuskip % extra space before
266 \mathchar8239 % "202f, i.e., binary op, \fam, / char
267 % if we see //, eliminate the extra space to taste:
268 \ifx\Urlssnext/\mskip-\Urlslashmuskip
269 \else\mskip\Urlslashmuskip \fi
270 }
271 \end{verbatim}
272 \end{quote}
273
274 If this sounds confusing~\dots{} well, it is! But I hope you
275 won't need to redefine breakpoints~--- the default assignments seem to
276 work well for a wide variety of applications. If you do need to make
277 changes, you can test for breakpoints using regular math mode and the
278 characters ``\texttt{+=(a}''.
279
280
281 \section{Yet more flexibility}
282 You can also customize the presentation of verbatim text by defining
283 \cs{UrlRight} and/or \cs{UrlLeft}. An example for ISO formatting of
284 urls surrounded by \verb+< >+ is
285 \begin{quote}
286 \begin{verbatim}
287 \DeclareUrlCommand\url{\def\UrlLeft{<url:\ }\def\UrlRight{>}%
288 \urlstyle{tt}}
289 \end{verbatim}
290 \end{quote}
291 The meanings of \cs{UrlLeft} and \cs{UrlRight} are \emph{not}
292 reproduced verbatim. This lets you use formatting commands there, but
293 you must be careful not to use \TeX's special characters
294 (\verb+\^_%~#$&{}+ etc.)\ improperly. You can also define \cs{UrlLeft}
295 to reprocess the verbatim text, but the format of the definition is special:
296 \begin{quote}
297 \verb+\def\UrlLeft#1\UrlRight{+\,\dots\ do things with \verb+#1+ \dots\,\verb+}+
298 \end{quote}
299 Yes, that is \verb+#1+ followed by \cs{UrlRight} then the definition (a \TeX\
300 macro with delimited arguments). For example, to produce a hyper\TeX\ hypertext
301 link:
302 \begin{quote}
303 \verb+\def\UrlLeft#1\UrlRight{%+\\
304 \verb+ \special{html:<a href="#1">}#1\special{html:</a>}}+
305 \end{quote}
306 Using this technique, \path{url.sty} can provide a convenient
307 interface for performing various operations on verbatim text. You
308 don't even need to print out the argument! For greatest efficiency in
309 such obscure applications, you can define a null url-style where all
310 the lists like \cs{UrlBreaks} are empty.
311
312 Please note that this method is \emph{not} how the hyperref package
313 manages urls for its \cs{url} command, even though it makes use of
314 \path{url.sty}. Instead, hyperref's \cs{url} reads its argument in
315 a less-verbatim manner than described above, produces its hyperlink,
316 and invokes \cs{nolinkurl} to format the text. \cs{nolinkurl} is
317 the \cs{url} command descibed herein.
318
319 \end{document}
320
321
322 %%% Local Variables:
323 %%% mode: latex
324 %%% TeX-master: t
325 %%% End: