| 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: |