1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/doc-src/url.sty Mon May 10 15:17:14 1999 +0200
1.3 @@ -0,0 +1,268 @@
1.4 +% url.sty ver 1.1 6-Feb-1996 Donald Arseneau asnd@triumf.ca
1.5 +%
1.6 +% A form of \verb that allows linebreaks at certain characters or
1.7 +% combinations of characters, accepts reconfiguration, and can usually
1.8 +% be used in the argument to another command. It is intended for email
1.9 +% addresses, hypertext links, directories/paths, etc., which normally
1.10 +% have no spaces. The font may be selected using the \urlstyle command,
1.11 +% and new url-like commands can be defined using \urldef.
1.12 +%
1.13 +% Usage: Conditions:
1.14 +% \url{ } If the argument contains any "%", "#", or "^^", or ends with
1.15 +% "\", it can't be used in the argument to another command.
1.16 +% The argument must not contain unbalanced braces.
1.17 +% \url| | ...where "|" is any character not used in the argument and not
1.18 +% "{". The same restrictions as above except that the argument
1.19 +% may contain unbalanced braces.
1.20 +% \xyz for "\xyz" a defined-url; this can be used anywhere, no matter
1.21 +% what characters it contains.
1.22 +%
1.23 +% See further instructions after "\endinput"
1.24 +
1.25 +\def\url@ttstyle{%
1.26 +\@ifundefined{selectfont}{\def\UrlFont{\tt}}{\def\UrlFont{\ttfamily}}%
1.27 +\def\UrlBreaks{\do\.\do\@\do\\\do\/\do\!\do\_\do\|\do\%\do\;\do\>\do\]%
1.28 + \do\)\do\,\do\?\do\'\do\+\do\=\do@url@hyp}%
1.29 +\def\UrlBigBreaks{\do\:}%
1.30 +\def\UrlNoBreaks{\do\(\do\[\do\{\do\<}% (unnecessary)
1.31 +\def\UrlSpecials{\do\ {\ }}%
1.32 +\def\UrlOrds{\do\*\do\-}% any ordinary characters that aren't usually
1.33 +}
1.34 +\def\url@rmstyle{%
1.35 +\@ifundefined{selectfont}{\def\UrlFont{\rm}}{\def\UrlFont{\rmfamily}}%
1.36 +\def\UrlBreaks{\do\.\do\@\do\/\do\!\do\%\do\;\do\]\do\)\do\,\do\?\do@url@hyp
1.37 + \do\+\do\=}%
1.38 +\def\UrlBigBreaks{\do\:}%
1.39 +\def\UrlNoBreaks{\do\(\do\[\do\{}% prevents breaks after *next* character
1.40 +\def\UrlSpecials{\do\<{\langle}\do\>{\rangle\penalty\relpenalty}\do\_{\_%
1.41 + \penalty\@m}\do\|{\mid}\do\{{\lbrace}\do\}{\rbrace\penalty\relpenalty}\do
1.42 + \\{\mathbin{\backslash}}\do\~{\mathord{{}^{\textstyle\sim}}}\do\ {\ }}%
1.43 +\def\UrlOrds{\do\'\do\"\do\-}%
1.44 +}
1.45 +\def\url@sfstyle{\url@rmstyle
1.46 +\@ifundefined{selectfont}{\def\UrlFont{\sf}}{\def\UrlFont{\sffamily}}%
1.47 +}
1.48 +\def\url@samestyle{\ifdim\fontdimen\thr@@\font=\z@ \url@ttstyle \else
1.49 + \url@rmstyle \fi \def\UrlFont{}}
1.50 +
1.51 +\def\do@url@hyp{}% by default, no breaks after hyphens
1.52 +
1.53 +\@ifundefined{strip@prefix}{\def\strip@prefix#1>{}}{}
1.54 +\@ifundefined{verbatim@nolig@list}{\def\verbatim@nolig@list{\do\`}}{}
1.55 +
1.56 +\def\Url{\relax\ifmmode\@nomatherr$\fi
1.57 + \UrlFont $\fam\z@ \textfont\z@\font
1.58 + \let\do\@makeother \dospecials % verbatim catcodes
1.59 + \catcode`{\@ne \catcode`}\tw@ % except braces
1.60 + \medmuskip0mu \thickmuskip\medmuskip \thinmuskip\medmuskip
1.61 + \@tempcnta\fam\multiply\@tempcnta\@cclvi
1.62 + \let\do\set@mathcode \UrlOrds % ordinary characters that were special
1.63 + \advance\@tempcnta 8192 \UrlBreaks % bin
1.64 + \advance\@tempcnta 4096 \UrlBigBreaks % rel
1.65 + \advance\@tempcnta 4096 \UrlNoBreaks % open
1.66 + \let\do\set@mathact \UrlSpecials % active
1.67 + \let\do\set@mathnolig \verbatim@nolig@list % prevent ligatures
1.68 + \@ifnextchar\bgroup\Url@z\Url@y}
1.69 +
1.70 +\def\Url@y#1{\catcode`{11 \catcode`}11
1.71 + \def\@tempa##1#1{\Url@z{##1}}\@tempa}
1.72 +\def\Url@z#1{\def\@tempa{#1}\expandafter\expandafter\expandafter\Url@use
1.73 + \expandafter\strip@prefix\meaning\@tempa\, \relax\m@th$\endgroup}
1.74 +\let\Url@use\@empty
1.75 +
1.76 +\def\set@mathcode#1{\count@`#1\advance\count@\@tempcnta\mathcode`#1\count@}
1.77 +\def\set@mathact#1#2{\mathcode`#132768 \lccode`\~`#1\lowercase{\def~{#2}}}
1.78 +\def\set@mathnolig#1{\ifnum\mathcode`#1<32768
1.79 + \lccode`\~`#1\lowercase{\edef~{\mathchar\number\mathcode`#1_{\/}}}%
1.80 + \mathcode`#132768 \fi}
1.81 +
1.82 +\def\urldef#1#2{\begingroup \setbox\z@\hbox\bgroup
1.83 + \def\Url@z{\Url@def{#1}{#2}}#2}
1.84 +\expandafter\ifx\csname DeclareRobustCommand\endcsname\relax
1.85 + \def\Url@def#1#2#3{\m@th$\endgroup\egroup\endgroup
1.86 + \def#1{#2{#3}}}
1.87 +\else
1.88 + \def\Url@def#1#2#3{\m@th$\endgroup\egroup\endgroup
1.89 + \DeclareRobustCommand{#1}{#2{#3}}}
1.90 +\fi
1.91 +
1.92 +\def\urlstyle#1{\csname url@#1style\endcsname}
1.93 +
1.94 +% Sample (and default) configuration:
1.95 +%
1.96 +\newcommand\url{\begingroup \Url}
1.97 +%
1.98 +\newcommand\path{\begingroup \urlstyle{tt}\Url}
1.99 +%
1.100 +% too many styles define \email like \address, so I will not define it.
1.101 +% \newcommand\email{\begingroup \urlstyle{rm}\Url}
1.102 +
1.103 +% Process LaTeX \package options
1.104 +%
1.105 +\urlstyle{tt}
1.106 +\@ifundefined{ProvidesPackage}{}{
1.107 + \ProvidesPackage{url}[1996/02/06 \space ver 1.1 \space
1.108 + Verb mode for urls, email addresses, and file names]
1.109 + \DeclareOption{hyphens}{\def\do@url@hyp{\do\-}}% allow breaks after hyphens
1.110 + \DeclareOption{obeyspaces}{\let\Url@use\relax}
1.111 + \ProcessOptions
1.112 +\ifx\Url@use\relax \def\Url@use#1 #2{#1\ifx\relax#2\@empty\else
1.113 + \penalty\relpenalty\ #2\expandafter\Url@use\fi}\fi
1.114 +}
1.115 +
1.116 +\endinput
1.117 +%
1.118 +% url.sty ver 1.1 6-Feb-1996 Donald Arseneau asnd@reg.triumf.ca
1.119 +%
1.120 +% This package defines "\url", a form of "\verb" that allows linebreaks,
1.121 +% and can often be used in the argument to another command. It can be
1.122 +% configured to print in different formats, and is particularly useful for
1.123 +% hypertext links, email addresses, directories/paths, etc. The font may
1.124 +% be selected using the "\urlstyle" command and pre-defined text can be
1.125 +% stored with the "\urldef" command. New url-like commands can be defined,
1.126 +% and a "\path" command is provided this way.
1.127 +%
1.128 +% Usage: Conditions:
1.129 +% \url{ } If the argument contains any "%", "#", or "^^", or ends with
1.130 +% "\", it can't be used in the argument to another command.
1.131 +% The argument must not contain unbalanced braces.
1.132 +% \url| | ...where "|" is any character not used in the argument and not
1.133 +% "{". The same restrictions as above except that the argument
1.134 +% may contain unbalanced braces.
1.135 +% \xyz for "\xyz" a defined-url; this can be used anywhere, no matter
1.136 +% what characters it contains.
1.137 +%
1.138 +% The "\url" command is fragile, and its argument is likely to be very
1.139 +% fragile, but a defined-url is robust.
1.140 +%
1.141 +% Package Option: obeyspaces
1.142 +% Ordinarily, all spaces are ignored in the url-text. The "[obeyspaces]"
1.143 +% option allows spaces, but may introduce spurious spaces when a url
1.144 +% containing "\" characters is given in the argument to another command.
1.145 +% So if you need to obey spaces should say "\usepackage[obeyspaces]{url}",
1.146 +% and if you need both spaces and backslashes, use a `defined-url' for
1.147 +% anything with "\".
1.148 +%
1.149 +% Package Option: hyphens
1.150 +% Ordinarily, breaks are not allowed after "-" characters because this
1.151 +% leads to confusion. (Is the "-" part of the address or just a hyphen?)
1.152 +% The package option "[hyphens]" allows breaks after explicit hyphen
1.153 +% characters. The "\url" command will *never ever* hyphenate words.
1.154 +%
1.155 +% Defining a defined-url:
1.156 +% Take for example the email address "myself%node@gateway.net" which could
1.157 +% not be given (using "\url" or "\verb") in a caption or parbox due to the
1.158 +% percent sign. This address can be predefined with
1.159 +% \urldef{\myself}\url{myself%node@gateway.net} or
1.160 +% \urldef{\myself}\url|myself%node@gateway.net|
1.161 +% and then you may use "\myself" instead of "\url{myself%node@gateway.net}"
1.162 +% in an argument, and even in a moving argument like a caption because a
1.163 +% defined-url is robust.
1.164 +%
1.165 +% Style:
1.166 +% You can switch the style of printing using "\urlstyle{tt}", where "tt"
1.167 +% can be any defined style. The pre-defined styles are "tt", "rm", "sf",
1.168 +% and "same" which all allow the same linebreaks but different fonts --
1.169 +% the first three select a specific font and the "same" style uses the
1.170 +% current text font. You can define your own styles with different fonts
1.171 +% and/or line-breaking by following the explanations below. The "\url"
1.172 +% command follows whatever the currently-set style dictates.
1.173 +%
1.174 +% Alternate commands:
1.175 +% It may be desireable to have different things treated differently, each
1.176 +% in a predefined style; e.g., if you want directory paths to always be
1.177 +% in tt and email addresses to be rm, then you would define new url-like
1.178 +% commands as follows:
1.179 +%
1.180 +% \newcommand\email{\begingroup \urlstyle{rm}\Url}
1.181 +% \newcommand\directory{\begingroup \urlstyle{tt}\Url}
1.182 +%
1.183 +% You must follow this format closely, and NOTE that the final command is
1.184 +% "\Url", not "\url". In fact, the "\directory" example is exactly the
1.185 +% "\path" definition which is pre-defined in the package. If you look
1.186 +% above, you will see that "\url" is defined with
1.187 +% \newcommand\url{\begingroup \Url}
1.188 +% I.e., using whatever url-style has been selected.
1.189 +%
1.190 +% You can make a defined-url for these other styles, using the usual
1.191 +% "\urldef" command as in this example:
1.192 +%
1.193 +% \urldef{\myself}{\email}{myself%node.domain@gateway.net}
1.194 +%
1.195 +% which makes "\myself" act like "\email{myself%node.domain@gateway.net}",
1.196 +% if the "\email" command is defined as above. The "\myself" command is
1.197 +% robust.
1.198 +%
1.199 +% Defining styles:
1.200 +% Before describing how to customize the printing style, it is best to
1.201 +% mention something about the unusual implementation of "\url". Although
1.202 +% the material is textual in nature, and the font specification required
1.203 +% is a text-font command, the text is actually typeset in *math* mode.
1.204 +% This allows the context-sensitive linebreaking, but also accounts for
1.205 +% the default behavior of ignoring spaces. Now on to defining styles.
1.206 +%
1.207 +% To change the font or the list of characters that allow linebreaks, you
1.208 +% could redefine the commands "\UrlFont", "\UrlBreaks", "\UrlSpecials" etc.
1.209 +% directly in the document, but it is better to define a new `url-style'
1.210 +% (following the example of "\url@ttstyle" and "\url@rmstyle") which defines
1.211 +% all of "\UrlBigbreaks", "\UrlNoBreaks", "\UrlBreaks", "\UrlSpecials", and
1.212 +% "\UrlFont".
1.213 +%
1.214 +% Changing font:
1.215 +% The "\UrlFont" command selects the font. The definition of "\UrlFont"
1.216 +% done by the pre-defined styles varies to cope with a variety of LaTeX
1.217 +% font selection schemes, but it could be as simple as "\def\UrlFont{\tt}".
1.218 +% In addition to setting "\UrlFont", some characters will probably need
1.219 +% to be defined in the "\UrlSpecials" list because most fonts don't have
1.220 +% all the standard input characters. See the definition of "\url@rmstyle",
1.221 +% which implements "\urlstyle{rm}". Or even better, follow the definition
1.222 +% of "\url@sfstyle", which executes "\url@rmstyle" and then redefines
1.223 +% just "\UrlFont". The nominal format for each special character "c"
1.224 +% in the "\UrlSpecials" list is: "\do\c{<definition>}", but you can
1.225 +% include other definitions too.
1.226 +%
1.227 +% Changing linebreaks:
1.228 +% The list of characters that allow line-breaks is given by "\UrlBreaks"
1.229 +% and "\UrlBigBreaks", which have the format "\do\c" for character "c".
1.230 +% The differences are that `BigBreaks' have a lower penalty and have
1.231 +% different breakpoints when in sequence (as in "http://"): `BigBreaks'
1.232 +% are treated as mathrels while `Breaks' are mathbins (see The TeXbook,
1.233 +% p.170). In particular, a series of `BigBreak' characters will break at
1.234 +% the end and only at the end; a series of `Break' characters will break
1.235 +% after the first and after every following *pair*; there will be no
1.236 +% break after a `Break' character if a `BigBreak' follows. In the case
1.237 +% of "http://" it doesn't matter whether ":" is a `Break' or `BigBreak' --
1.238 +% the breaks are the same in either case; but for DECnet nodes with "::"
1.239 +% it is important to prevent breaks *between* the colons, and that is why
1.240 +% colons are `BigBreaks'.
1.241 +%
1.242 +% It is possible for characters to prevent breaks after the next following
1.243 +% character (I use this for parentheses). Specify these in "\UrlNoBreaks".
1.244 +%
1.245 +% You can do arbitrarily complex things with characters by making them
1.246 +% active in math mode (mathcode hex-8000) and specifying the definition(s)
1.247 +% in "\UrlSpecials". This is used in the rm and sf styles to handle
1.248 +% several characters that are not present in fonts.
1.249 +%
1.250 +% If all this sounds confusing ... well, it is! But I hope you won't need
1.251 +% to redefine breakpoints -- the default assignments seem to work well for
1.252 +% a wide variety of applications. If you do need to make changes, you can
1.253 +% test for breakpoints using regular math mode and the characters "+=(a".
1.254 +%
1.255 +% Yet more flexibility:
1.256 +% You can also set up url.sty to do multiple things with the verbatim text
1.257 +% by defining "\Url@use", but the format of the definition is special:
1.258 +%
1.259 +% \def\Url@use#1\,{ ... do things with #1 ... }
1.260 +%
1.261 +% Yes, that is "#1" followed by "\," then the definition. For example,
1.262 +% to put a hypertext link in the DVI file:
1.263 +%
1.264 +% \def\Url@use#1\,{\special{html:<a href="#1">}#1\special{html:</a>}}
1.265 +%
1.266 +% The End
1.267 +% ver 1.1 6-Feb-1996:
1.268 +% Fix hyphens that wouldn't break and ligatures that weren't suppressed.
1.269 +
1.270 +Test file integrity: ASCII 32-57, 58-126: !"#$%&'()*+,-./0123456789
1.271 +:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcdefghijklmnopqrstuvwxyz{|}~