url.sty 13.6 KB
Newer Older
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 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301
% url.sty  ver 1.2    19-Oct-1996   Donald Arseneau   asnd@triumf.ca
%
% A form of \verb that allows linebreaks at certain characters or 
% combinations of characters, accepts reconfiguration, and can usually
% be used in the argument to another command.  It is intended for email
% addresses, hypertext links, directories/paths, etc., which normally 
% have no spaces.  The font may be selected using the \urlstyle command, 
% and new url-like commands can be defined using \urldef.
%
% Usage:    Conditions:
% \url{ }   If the argument contains any "%", "#", or "^^", or ends with
%           "\", it can't be used in the argument to another command.  
%           The argument must not contain unbalanced braces.
% \url|  |  ...where "|" is any character not used in the argument and not 
%           "{".  The same restrictions as above except that the argument
%           may contain unbalanced braces.
% \xyz      for "\xyz" a defined-url;  this can be used anywhere, no matter
%           what characters it contains.
% 
% See further instructions after "\endinput"
%
\def\Url@ttdo{% style assignments for tt fonts or T1 encoding
\def\UrlBreaks{\do\.\do\@\do\\\do\/\do\!\do\_\do\|\do\%\do\;\do\>\do\]%
 \do\)\do\,\do\?\do\'\do\+\do\=}%
\def\UrlBigBreaks{\do\:\do@url@hyp}%
\def\UrlNoBreaks{\do\(\do\[\do\{\do\<}% (unnecessary)
\def\UrlSpecials{\do\ {\ }}%
\def\UrlOrds{\do\*\do\-\do\~}% any ordinary characters that aren't usually
}
\def\Url@do{% style assignments for OT1 fonts except tt
\def\UrlBreaks{\do\.\do\@\do\/\do\!\do\%\do\;\do\]\do\)\do\,\do\?\do\+\do\=}%
\def\UrlBigBreaks{\do\:\do@url@hyp}%
\def\UrlNoBreaks{\do\(\do\[\do\{}% prevents breaks after *next* character
\def\UrlSpecials{\do\<{\langle}\do\>{\mathbin{\rangle}}\do\_{\_%
 \penalty\@m}\do\|{\mid}\do\{{\lbrace}\do\}{\mathbin{\rbrace}}\do
 \\{\mathbin{\backslash}}\do\~{\mathord{{}^{\textstyle\sim}}}\do\ {\ }}%
\def\UrlOrds{\do\'\do\"\do\-}%
}
\def\url@ttstyle{%
\@ifundefined{selectfont}{\def\UrlFont{\tt}}{\def\UrlFont{\ttfamily}}\Url@ttdo
}
\def\url@rmstyle{%
\@ifundefined{selectfont}{\def\UrlFont{\rm}}{\def\UrlFont{\rmfamily}}\Url@do
}
\def\url@sfstyle{%
\@ifundefined{selectfont}{\def\UrlFont{\sf}}{\def\UrlFont{\sffamily}}\Url@do
}
\def\url@samestyle{\ifdim\fontdimen\thr@@\font=\z@ \url@ttstyle \else
  \url@rmstyle \fi \def\UrlFont{}}

\@ifundefined{strip@prefix}{\def\strip@prefix#1>{}}{}
\@ifundefined{verbatim@nolig@list}{\def\verbatim@nolig@list{\do\`}}{}

\def\Url{\relax\ifmmode\@nomatherr$\fi 
 \UrlFont $\fam\z@ \textfont\z@\font 
 \let\do\@makeother \dospecials % verbatim catcodes
 \catcode`{\@ne \catcode`}\tw@ % except braces 
 \medmuskip0mu \thickmuskip\medmuskip \thinmuskip\medmuskip
 \@tempcnta\fam\multiply\@tempcnta\@cclvi 
 \let\do\set@mathcode \UrlOrds % ordinary characters that were special
 \advance\@tempcnta 8192 \UrlBreaks % bin
 \advance\@tempcnta 4096 \UrlBigBreaks % rel
 \advance\@tempcnta 4096 \UrlNoBreaks % open
 \let\do\set@mathact \UrlSpecials % active
 \let\do\set@mathnolig \verbatim@nolig@list % prevent ligatures 
 \@ifnextchar\bgroup\Url@z\Url@y}

\def\Url@y#1{\catcode`{11 \catcode`}11
  \def\@tempa##1#1{\Url@z{##1}}\@tempa}
\def\Url@z#1{\def\@tempa{#1}\expandafter\expandafter\expandafter\Url@Hook
  \expandafter\strip@prefix\meaning\@tempa\UrlRight\m@th$\endgroup}
\def\Url@Hook{\UrlLeft}
\let\UrlRight\@empty
\let\UrlLeft\@empty

\def\set@mathcode#1{\count@`#1\advance\count@\@tempcnta\mathcode`#1\count@}
\def\set@mathact#1#2{\mathcode`#132768 \lccode`\~`#1\lowercase{\def~{#2}}}
\def\set@mathnolig#1{\ifnum\mathcode`#1<32768
   \lccode`\~`#1\lowercase{\edef~{\mathchar\number\mathcode`#1_{\/}}}%
   \mathcode`#132768 \fi}

\def\urldef#1#2{\begingroup \setbox\z@\hbox\bgroup
  \def\Url@z{\Url@def{#1}{#2}}#2}
\expandafter\ifx\csname DeclareRobustCommand\endcsname\relax
  \def\Url@def#1#2#3{\m@th$\endgroup\egroup\endgroup
    \def#1{#2{#3}}}
\else
  \def\Url@def#1#2#3{\m@th$\endgroup\egroup\endgroup
    \DeclareRobustCommand{#1}{#2{#3}}}
\fi

\def\urlstyle#1{\csname url@#1style\endcsname}

% Sample (and default) configuration:
%
\newcommand\url{\begingroup \Url}
%
\newcommand\path{\begingroup \urlstyle{tt}\Url}
%
% too many styles define \email like \address, so I will not define it.
% \newcommand\email{\begingroup \urlstyle{rm}\Url}

% Process LaTeX \package options
%
\urlstyle{tt}
\let\Url@sppen\@M
\def\do@url@hyp{}% by default, no breaks after hyphens

\@ifundefined{ProvidesPackage}{}{
  \ProvidesPackage{url}[1996/10/19 \space ver 1.2 \space 
       Verb mode for urls, email addresses, and file names]
  \DeclareOption{hyphens}{\def\do@url@hyp{\do\-}}% allow breaks after hyphens
  \DeclareOption{obeyspaces}{\let\Url@Hook\relax}% a flag for later
  \DeclareOption{spaces}{\let\Url@sppen\relpenalty}
  \DeclareOption{T1}{\let\Url@do\Url@ttdo}
  \ProcessOptions
\ifx\Url@Hook\relax % [obeyspaces] was declared
  \def\Url@Hook#1\UrlRight\m@th{\edef\@tempa{\noexpand\UrlLeft
    \Url@retain#1\Url@nosp\, }\@tempa\UrlRight\m@th}
  \def\Url@retain#1 {#1\penalty\Url@sppen\ \Url@retain}
  \def\Url@nosp\,#1\Url@retain{}
\fi
}

\endinput
%
% url.sty  ver 1.2    19-Oct-1996   Donald Arseneau   asnd@reg.triumf.ca
%
% This package defines "\url", a form of "\verb" that allows linebreaks,
% and can often be used in the argument to another command.  It can be
% configured to print in different formats, and is particularly useful for 
% hypertext links, email addresses, directories/paths, etc.  The font may 
% be selected using the "\urlstyle" command and pre-defined text can be 
% stored with the "\urldef" command. New url-like commands can be defined, 
% and a "\path" command is provided this way. 
%
% Usage:    Conditions:
% \url{ }   If the argument contains any "%", "#", or "^^", or ends with 
%           "\", it can't be used in the argument to another command.  
%           The argument must not contain unbalanced braces.
% \url|  |  ...where "|" is any character not used in the argument and not 
%           "{".  The same restrictions as above except that the argument
%           may contain unbalanced braces.
% \xyz      for "\xyz" a defined-url;  this can be used anywhere, no matter
%           what characters it contains.
% 
% The "\url" command is fragile, and its argument is likely to be very
% fragile, but a defined-url is robust.
%
% Package Option:  obeyspaces
% Ordinarily, all spaces are ignored in the url-text.  The "[obeyspaces]" 
% option allows spaces, but may introduce spurious spaces when a url
% containing "\" characters is given in the argument to another command.  
% So if you need to obey spaces you can say "\usepackage[obeyspaces]{url}",
% and if you need both spaces and backslashes, use a `defined-url' for 
% anything with "\".
%
% Package Option:  hyphens
% Ordinarily, breaks are not allowed after "-" characters because this 
% leads to confusion. (Is the "-" part of the address or just a hyphen?)  
% The package option "[hyphens]" allows breaks after explicit hyphen 
% characters.  The "\url" command will *never ever* hyphenate words.
%
% Package Option:  spaces
% Likewise, breaks are not usually allowed after spaces under the 
% "[obeyspaces]" option, but giving the options "[obeyspaces,spaces]"
% will allow breaks at those spaces.
%
% Package Option:  T1
% This signifies that you will be using T1-encoded fonts which contain
% some characters missing from most older (OT1) encoded TeX fonts.  This
% changes the default definition for "\urlstyle{rm}".
% 
% Defining a defined-url:
% Take for example the email address "myself%node@gateway.net" which could
% not be given (using "\url" or "\verb") in a caption or parbox due to the
% percent sign.  This address can be predefined with 
%    \urldef{\myself}\url{myself%node@gateway.net}   or
%    \urldef{\myself}\url|myself%node@gateway.net|
% and then you may use "\myself" instead of "\url{myself%node@gateway.net}"
% in an argument, and even in a moving argument like a caption because a
% defined-url is robust.
%
% Style: 
% You can switch the style of printing using "\urlstyle{tt}", where "tt"
% can be any defined style.  The pre-defined styles are "tt", "rm", "sf", 
% and "same" which all allow the same linebreaks but different fonts -- 
% the first three select a specific font and the "same" style uses the
% current text font.  You can define your own styles with different fonts 
% and/or line-breaking by following the explanations below.  The "\url" 
% command follows whatever the currently-set style dictates.
%
% Alternate commands:
% It may be desireable to have different things treated differently, each
% in a predefined style; e.g., if you want directory paths to always be 
% in tt and email addresses to be rm, then you would define new url-like
% commands as follows:
%
%    \newcommand\email{\begingroup \urlstyle{rm}\Url}
%    \newcommand\directory{\begingroup \urlstyle{tt}\Url}
%
% You must follow this format closely, and NOTE that the final command is 
% "\Url", not "\url".  In fact, the "\directory" example is exactly the 
% "\path" definition which is pre-defined in the package.  If you look 
% above, you will see that "\url" is defined with
%    \newcommand\url{\begingroup \Url}
% I.e., using whatever url-style has been selected.
%
% You can make a defined-url for these other styles, using the usual 
% "\urldef" command as in this example:
%
%    \urldef{\myself}{\email}{myself%node.domain@gateway.net}
%
% which makes "\myself" act like "\email{myself%node.domain@gateway.net}",
% if the "\email" command is defined as above.  The "\myself" command 
% would then be robust.
%
% Defining styles:
% Before describing how to customize the printing style, it is best to 
% mention something about the unusual implementation of "\url".  Although
% the material is textual in nature, and the font specification required
% is a text-font command, the text is actually typeset in *math* mode.
% This allows the context-sensitive linebreaking, but also accounts for
% the default behavior of ignoring spaces.  Now on to defining styles.
%
% To change the font or the list of characters that allow linebreaks, you
% could redefine the commands "\UrlFont", "\UrlBreaks", "\UrlSpecials" etc.
% directly in the document, but it is better to define a new `url-style' 
% (following the example of "\url@ttstyle" and "\url@rmstyle") which defines 
% all of "\UrlBigbreaks", "\UrlNoBreaks", "\UrlBreaks", "\UrlSpecials", and 
% "\UrlFont".
%
% Changing font:
% The "\UrlFont" command selects the font.  The definition of "\UrlFont"
% done by the pre-defined styles varies to cope with a variety of LaTeX
% font selection schemes, but it could be as simple as "\def\UrlFont{\tt}".
% Depending on the font selected, some characters may need to be defined 
% in the "\UrlSpecials" list because many fonts don't contain all the 
% standard input characters.  
%
% Changing linebreaks:
% The list of characters that allow line-breaks is given by "\UrlBreaks" 
% and "\UrlBigBreaks", which have the format "\do\c" for character "c". 
% The differences are that `BigBreaks' have a lower penalty and have 
% different breakpoints when in sequence (as in "http://"): `BigBreaks' 
% are treated as mathrels while `Breaks' are mathbins (see The TeXbook, 
% p.170). In particular, a series of `BigBreak' characters will break at 
% the end and only at the end; a series of `Break' characters will break 
% after the first and after every following *pair*; there will be no 
% break after a `Break' character if a `BigBreak' follows.  In the case 
% of "http://" it doesn't matter whether ":" is a `Break' or `BigBreak' --
% the breaks are the same in either case; but for DECnet nodes with "::"
% it is important to prevent breaks *between* the colons, and that is why 
% colons are `BigBreaks'.
%
% It is possible for characters to prevent breaks after the next following 
% character (I use this for parentheses).  Specify these in "\UrlNoBreaks". 
%
% You can do arbitrarily complex things with characters by making them 
% active in math mode (mathcode hex-8000) and specifying the definition(s)
% in "\UrlSpecials".  This is used in the rm and sf styles for OT1 font
% encoding to handle several characters that are not present in those
% computer-modern style fonts.  See the definition of "\Url@do", which 
% is used by both "\url@rmstyle" and "\url@sfstyle"; it handles missing 
% characters via "\UrlSpecials".  The nominal format for setting each 
% special character "c" is: "\do\c{<definition>}", but you can include 
% other definitions too.
%
%
% If all this sounds confusing ... well, it is!  But I hope you won't need 
% to redefine breakpoints -- the default assignments seem to work well for 
% a wide variety of applications.  If you do need to make changes, you can 
% test for breakpoints using regular math mode and the characters "+=(a".
%
% Yet more flexibility:
% You can also customize the verbatim text by defining "\UrlRight" and/or 
% "\UrlLeft", e.g., for ISO formatting of urls surrounded by "<  >", define
%
%    \renewcommand\url{\begingroup \def\UrlLeft{<url: }\def\UrlRight{>}%
%        \urlstyle{tt}\Url}
%
% The meanings of "\UrlLeft" and "\UrlRight" are *not* reproduced verbatim.
% This lets you use formatting commands there, but you must be careful not
% to use TeX's special characters ("\^_%~#$&{}" etc.) improperly.
% You can also define "\UrlLeft" to reprocess the verbatim text, but the 
% format of the definition is special:
%
%    \def\UrlLeft#1\UrlRight{ ... do things with #1 ... }
%
% Yes, that is "#1" followed by "\UrlRight" then the definition.  For 
% example, to put a hyperTeX hypertext link in the DVI file:
%
%    \def\UrlLeft#1\UrlRight{\special{html:<a href="#1">}#1\special{html:</a>}}
%
% Revision History:
% ver 1.1 6-Feb-1996:  
% Fix hyphens that wouldn't break and ligatures that weren't suppressed.
% ver 1.2 19-Oct-1996:
% Package option for T1 encoding; Hooks: "\UrlLeft" and "\UrlRight".  
%
% The End