From df85c77bc36e66a3a4906a68fe15b323017b457d Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Tue, 31 Dec 2013 23:17:24 +0000 Subject: url (31dec13) git-svn-id: svn://tug.org/texlive/trunk@32528 c570f23f-e606-0410-a88d-b1316a301751 --- Master/texmf-dist/doc/latex/url/url.pdf | Bin 243941 -> 260786 bytes Master/texmf-dist/doc/latex/url/url.tex | 295 +++++++++++++++++--------------- Master/texmf-dist/tex/latex/url/url.sty | 209 ++-------------------- 3 files changed, 171 insertions(+), 333 deletions(-) diff --git a/Master/texmf-dist/doc/latex/url/url.pdf b/Master/texmf-dist/doc/latex/url/url.pdf index 46c5ee7460b..ef4066d19bc 100644 Binary files a/Master/texmf-dist/doc/latex/url/url.pdf and b/Master/texmf-dist/doc/latex/url/url.pdf differ diff --git a/Master/texmf-dist/doc/latex/url/url.tex b/Master/texmf-dist/doc/latex/url/url.tex index 3bebec565dd..a53a3a8fa54 100644 --- a/Master/texmf-dist/doc/latex/url/url.tex +++ b/Master/texmf-dist/doc/latex/url/url.tex @@ -1,49 +1,56 @@ -\documentclass[a4paper]{article} +\documentclass[a4paper,11pt]{article} \usepackage[T1]{fontenc} \usepackage{lmodern} -\usepackage{miscdoc,url,booktabs} +\usepackage{miscdoc,url,booktabs,microtype} +\addtolength\textwidth{1cm} +\addtolength\oddsidemargin{-.5cm} +\addtolength\evensidemargin{-.5cm} +\raggedbottom +\setlength\parskip{4pt plus 2pt} + \begin{document} -\title{\texttt{url.sty} version 3.3} -\date{2006-04-12, documentation 2010-01-20} -\author{Donald Arseneau\\ - edited as a \LaTeX{} document by Robin Fairbairns} +\title{\texttt{url.sty} version 3.4} +\date{2013-09-16} +\author{Donald Arseneau% + \thanks{Thanks to Robin Fairbairns for documentation conversion!}} \maketitle -% url.sty ver 3.3 12-Apr-2006 Donald Arseneau asnd@triumf.ca -% Copyright 1996-2006 Donald Arseneau, Vancouver, Canada. +% url.sty ver 3.4 16-Sep-2013 Donald Arseneau asnd@triumf.ca +% Copyright 1996-2013 Donald Arseneau, Vancouver, Canada. % This program can be used, distributed, and modified under the terms -% of the LaTeX Project Public License. +% of the LaTeX Project Public License, version 2 or later. The package defines a form of \cs{verb} command 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, +command. It is intended for formatting email addresses, hypertext links, directories/paths, etc., which normally have no spaces. The font used may be selected using the \cs{urlstyle} command, and new url-like commands may be defined using \cs{urldef}. +This package does not make hyper-links! For that purpose, see the hyperref +package (or some other deprecated ones). \begin{center} \begin{tabular}{lp{3.5in}} \toprule Usage & Conditions \\ \midrule - \verb+\url{ }+ & If the argument contains any ``\verb+%+'', - ``\verb+#+'' or ``\verb+^^+'', or ends with - ``\cs{}'', it can't be used in the argument to - another command.\\ - & The argument must not contain unbalanced braces.\\ + \verb+\url{ }+ & The argument must not contain unbalanced braces. + If used in the argument to another command, the + \cs{url} argument cannot contain any ``\verb+%+'', + ``\verb+#+'', or ``\verb+^^+'', or end with + ``\verb+\+''.\\ \verb+\url| |+ & where ``\texttt{|}'' is any character not used - in the argument and not ``\verb+{+'' or a - space. The same restrictions apply as above - except that the argument may contain - unbalanced braces.\\ - \cs{xyz} & for ``\cs{xyz}'' a defined-url; such a command can be + in the argument and not ``\verb+{+'' or a space. + The same restrictions apply as above except that + the argument may contain unbalanced braces.\\ + \cs{xyz} & for the defined-url ``\cs{xyz}''; such a command can be used anywhere, no matter what characters it contains. \\ \bottomrule \end{tabular} \end{center} -The ``\cs{url}'' command is fragile, and its argument is likely to be +\noindent The ``\cs{url}'' command is fragile, and its argument is likely to be very fragile, but a defined-url is robust. \section{Package options} @@ -54,7 +61,6 @@ Ordinarily, all spaces are ignored in the url-text. The ``\texttt{[obeyspaces]}'' option allows spaces, but may introduce spurious spaces when a url containing ``\cs{}'' characters is given in the argument to another command. - So if you need to obey spaces you can say ``\cs{usepackage}\texttt{[obeyspaces]\char`\{url\char`\}}'', and if you need both spaces and backslashes, use a defined-url. @@ -64,22 +70,21 @@ you need both spaces and backslashes, use a defined-url. Ordinarily, breaks are not allowed after ``\texttt{-}'' characters because this leads to confusion. (Is the ``\texttt{-}'' part of the address or just a hyphen?) - The package option ``\texttt{[hyphens]}'' allows breaks after explicit hyphen characters. The \cs{url} command will \textbf{never ever} hyphenate words. \newitem Package Option: \texttt{spaces} -Likewise, breaks are not usually allowed after spaces under the -``\texttt{[obeyspaces]}'' option, but if you give the options +Likewise, given the ``\texttt{[obeyspaces]}'' option, breaks are not +usually allowed after the spaces, but if you give the options ``\texttt{[obeyspaces,spaces]}'', \cs{url} will allow breaks at those spaces. \begin{quote} Note that it seems logical to allow the sole option ``\texttt{[spaces]}'' to let input spaces indicate break points, but not to display them in the output. This would be easy to implement, - but is left out to avoid(?) confusion. + but is left out to avoid(?)\ confusion. \end{quote} \newitem Package Option: \texttt{lowtilde} @@ -90,6 +95,14 @@ Otherwise, the character is faked using a mathematical ``\cs{sim}''. The ``\texttt{[lowtilde]}'' option causes a faked character to be used always (and a bit lower than usual). +\newitem Package Option: \texttt{allowmove} + +This option suppresses the test for \cs{url} being used in a so-called +moving argument (check ``fragile command''). Using it will enable \cs{url} +to function in more contexts, but when it does fail, the error message +may be incomprehensible. + + \section{Defining a defined-url} Take for example the email address ``\url{myself%node@gateway.net}" @@ -107,15 +120,15 @@ defined-url is robust. \section{Style} -You can switch the style of printing using ``\verb+\urlstyle{xx}+'', -where ``\emph{\texttt{xx}}'' can be any defined style. The -pre-defined styles are ``\texttt{tt}'', ``\texttt{rm}'', -``\texttt{sf}'' and ``\texttt{same}'' which all allow the same -linebreaks but use different fonts~--- the first three select a -specific font and the ``\texttt{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 ``\cs{url}'' -command follows whatever the currently-set style dictates. +You can switch the style of printing using ``\verb+\urlstyle{+$xx$\verb+}+'', +where ``$xx$'' can be any defined style. The pre-defined styles are +``\texttt{tt}'', ``\texttt{rm}'', ``\texttt{sf}'' and ``\texttt{same}'' +which all allow the same linebreaks but use different fonts~--- the +first three select a specific font and the ``\texttt{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 ``\cs{url}'' command follows whatever the currently-set +style dictates. \section{Alternate commands} @@ -124,29 +137,23 @@ in a predefined style; e.g., if you want directory paths to always be in typewriter and email addresses to be roman, then you would define new url-like commands as follows: \begin{quote} -\begin{verbatim} -\DeclareUrlCommand\email{\urlstyle{rm}} -\DeclareUrlCommand\directory{\urlstyle{tt}} -\end{verbatim} + \verb+\DeclareUrlCommand+\meta{command}\verb+{+\meta{settings}\verb+}+\\ + \verb+\DeclareUrlCommand\email{\urlstyle{rm}}+\\ + \verb+\DeclareUrlCommand\directory{\urlstyle{tt}}+. \end{quote} - In fact, this \cs{directory} example is exactly the \cs{path} -definition which is pre-defined in the package. If you look above, -you will see that \cs{url} is defined with +definition which might be pre-defined by the package. Furthermore, +basic \cs{url} is defined with \begin{quote} -\begin{verbatim} -\DeclareUrlCommand\url{} -\end{verbatim} + \verb+\DeclareUrlCommand\url{}+, \end{quote} -I.e., using whatever \cs{urlstyle} and other settings are already in -effect. +without any \emph{settings}, so it uses whatever \cs{urlstyle} +and other settings are already in effect. You can make a defined-url for these other styles, using the usual \cs{urldef} command as in this example: \begin{quote} -\begin{verbatim} -\urldef{\myself}{\email}{myself%node.domain@gateway.net} -\end{verbatim} +\verb+\urldef{\myself}{\email}{myself%node.domain@gateway.net}+ \end{quote} which makes \cs{myself} act like \verb+\email{myself%node.domain@gateway.net}+, @@ -160,7 +167,8 @@ mention something about the unusual implementation of \cs{url}. Although the material is textual in nature, and the font specification required is a text-font command, the text is actually typeset in \emph{math} mode. This allows the context-sensitive linebreaking, but also accounts for -the default behavior of ignoring spaces. Now on to defining styles. +the default behavior of ignoring spaces. (Maybe that underlying design +will eventually change.) Now on to defining styles. To change the font or the list of characters that allow linebreaks, you could redefine the commands \cs{UrlFont}, \cs{UrlBreaks}, @@ -178,66 +186,102 @@ characters may need to be defined in the \cs{UrlSpecials} list because many fonts don't contain all the standard input characters. \subsection{Changing linebreaks} -The list of characters that allow line-breaks is given by -\cs{UrlBreaks} and \hspace{1in}\penalty-1\hspace{-1in} -\cs{UrlBigBreaks}, which have the format -\cs{do}\cs{c} for each character \texttt{c}. - -The differences are that `BigBreaks' usually have a lower penalty and -have different breakpoints when in sequence (as in \texttt{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 -\emph{pair}; there will be no break after a `Break' character if a -`BigBreak' follows. In the case of \texttt{http://} it doesn't matter -whether \texttt{:"} is a `Break' or `BigBreak'~--- the breaks are the -same in either case; but for \emph{DECnet} nodes with \texttt{::} it -is important to prevent breaks \emph{between} the colons, and that is -why colons are `BigBreaks'. +The list of characters after which line-breaks are permitted is +given by the two commands (list macros) +\cs{UrlBreaks} and \cs{UrlBigBreaks}. They consist of repeating +\cs{do}\cs{c} for each relevant character \texttt{c}. + +The differences are that `BigBreaks' typically have a lower penalty (more +easily chosen) and do not break within a repeating sequence (e.g., +``\verb+DEC::NODE+''). +(For gurus: `BigBreaks' are treated as mathrels while `Breaks' are mathbins; +see \textit{The TeXbook}, p.\,170.) The result is that a series of +consecutive `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 +\emph{pair}; there will be no break between a `Break' character and a +following `BigBreak' char; breaks are permitted when a `BigBreak' +character is followed by `Break' or any other char. In the case +of \texttt{http://} it doesn't matter whether \texttt{:} is a +`Break' or `BigBreak'~--- the breaks are the same in either case; but +for (now ancient) \emph{DECnet} addresses using \texttt{::} it was +important to prevent breaks \emph{between} the colons, and that is why +colons are `BigBreaks'. (The only other `BigBreak' character is, +optionally, the hyphen; slashes are regular `Break's.) It is possible for characters to prevent breaks after the next -following character (I use this for parentheses). Specify these in +following character (this is used for parentheses). Specify these in \cs{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 \cs{UrlSpecials}. This is used in the \texttt{rm} -and \texttt{sf} styles for OT1 font encoding to handle several -characters that are not present in those computer-modern style fonts. -See the definition of \cs{Url@do}, which is used by both -\cs{urlrmstyle} and \cs{url@sfstyle}; it handles missing characters -via \cs{UrlSpecials}. The nominal format for setting each special -character \texttt{c} is: \verb+\do\c{+\meta{definition}\verb+}+, but -you can include other definitions too. - -If all this sounds confusing~\dots{} 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 \texttt{+=(a}. - You can allow some spacing around the breakable characters by assigning \begin{quote} -\begin{verbatim} -\Urlmuskip = 0mu plus 1mu -\end{verbatim} +\verb+\Urlmuskip = 0mu plus 1mu+ \end{quote} +(with \texttt{mu} units because of math mode). You can change the penalties used for BigBreaks and Breaks by assigning \begin{quote} -\begin{verbatim} -\mathchardef\UrlBreakPenalty=100 -\mathchardef\UrlBigBreakPenalty=100 -\end{verbatim} +\verb+\mathchardef\UrlBreakPenalty=100+\\ +\verb+\mathchardef\UrlBigBreakPenalty=100+ \end{quote} The default penalties are \cs{binoppenalty} and \cs{relpenalty}. These have such odd non-\LaTeX{} syntax because I don't expect people -to need to change them often. +to need to change them often. (The \verb+\mathchardef+ does not relate to +math mode; it is only a way to store a number without consuming registers.) + +\subsubsection{Arbitrary character actions} + +You can do arbitrarily complex things with characters by specifying +their definition(s) in \cs{UrlSpecials}. This makes them `active' in +math mode (mathcode \texttt{"8000}). The format for setting +each special character \texttt{c} is: +\verb+\do\c{+\meta{definition}\verb+}+, but other definitions not +following this style can also be included. + +Here is an example to make ``\texttt{!}''\ inside \cs{url} force a line break +instead of being treated verbatim (it uses \LaTeX's \cs{g@addto@macro}): + +\begin{quote} +\verb+\makeatletter \g@addto@macro\UrlSpecials{\do\!{\newline}}+ +\end{quote} + +Here is another overly-complicated example to put extra flexible +muglue around each ``\texttt{/}'' character, except when followed +by another ``\texttt{/}'', as in ``\texttt{http://}'', where extra +spacing looks poor. + +\begin{quote} +\begin{verbatim} +% what we'll insert before and after each (lone) slash: +\newmuskip\Urlslashmuskip +\Urlslashmuskip=2mu plus2mu minus2mu + +% change what / does: +\g@addto@macro\UrlSpecials{\do\/{\Urlspaceyslash}} + +% need to look ahead: +\def\Urlspaceyslash{\futurelet\Urlssnext\finishUrlspaceyslash} + +\def\finishUrlspaceyslash{% + \mskip\Urlslashmuskip % extra space before + \mathchar8239 % "202f, i.e., binary op, \fam, / char + % if we see //, eliminate the extra space to taste: + \ifx\Urlssnext/\mskip-\Urlslashmuskip + \else\mskip\Urlslashmuskip \fi + } +\end{verbatim} +\end{quote} + +If this sounds confusing~\dots{} 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 ``\texttt{+=(a}''. + \section{Yet more flexibility} -You can also customize the verbatim text by defining \cs{UrlRight} -and/or \cs{UrlLeft}, e.g., for ISO formatting of urls surrounded by -\verb+< >+, define +You can also customize the presentation of verbatim text by defining +\cs{UrlRight} and/or \cs{UrlLeft}. An example for ISO formatting of +urls surrounded by \verb+< >+ is \begin{quote} \begin{verbatim} \DeclareUrlCommand\url{\def\UrlLeft{}% @@ -246,20 +290,18 @@ and/or \cs{UrlLeft}, e.g., for ISO formatting of urls surrounded by \end{quote} The meanings of \cs{UrlLeft} and \cs{UrlRight} are \emph{not} reproduced verbatim. This lets you use formatting commands there, but -you must be careful not to use TeX's special characters -(\verb+\^_%~#$&{}+ etc.) improperly. You can also define \cs{UrlLeft} +you must be careful not to use \TeX's special characters +(\verb+\^_%~#$&{}+ etc.)\ improperly. You can also define \cs{UrlLeft} to reprocess the verbatim text, but the format of the definition is special: \begin{quote} -\begin{verbatim} -\def\UrlLeft#1\UrlRight{ ... do things with #1 ... } -\end{verbatim} +\verb+\def\UrlLeft#1\UrlRight{+\,\dots\ do things with \verb+#1+ \dots\,\verb+}+ \end{quote} -Yes, that is \verb+#1+ followed by \cs{UrlRight} then the definition. For -example, to put a hyperTeX hypertext link in the DVI file: +Yes, that is \verb+#1+ followed by \cs{UrlRight} then the definition (a \TeX\ +macro with delimited arguments). For example, to produce a hyper\TeX\ hypertext +link: \begin{quote} -\begin{verbatim} -\def\UrlLeft#1\UrlRight{\special{html:}#1\special{html:}} -\end{verbatim} +\verb+\def\UrlLeft#1\UrlRight{%+\\ +\verb+ \special{html:}#1\special{html:}}+ \end{quote} Using this technique, \path{url.sty} can provide a convenient interface for performing various operations on verbatim text. You @@ -267,42 +309,15 @@ don't even need to print out the argument! For greatest efficiency in such obscure applications, you can define a null url-style where all the lists like \cs{UrlBreaks} are empty. +Please note that this method is \emph{not} how the hyperref package +manages urls for its \cs{url} command, even though it makes use of +\path{url.sty}. Instead, hyperref's \cs{url} reads its argument in +a less-verbatim manner than described above, produces its hyperlink, +and invokes \cs{nolinkurl} to format the text. \cs{nolinkurl} is +the \cs{url} command descibed herein. -\noindent\begin{verbatim} -% -% 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". -% ver 1.3 21-Jul-1997: -% Prohibit spaces as delimiter characters; change ascii tilde in OT1. -% ver 1.4 02-Mar-1999: -% LaTeX license; moving-argument-error -% ver 1.5 28-Mar-1999: -% possibility of spacing around break characters; re-settable penalties -% ver 1.6 20-Jun-2002: -% un-double #, fix obeyed-spaces, ignore trailing %, hook for hyperref -% (\Url@HyperHook), no macros in pre-processed url string (in \Url@String), -% limit catcode change of ~. -% ver 3.0 June 2003/Nov 2003: -% \DeclareUrlCommand; make font encoding automatic (only a few inputenc characters -% are supported yet - needs refactoring); reverse penalties. -% ver 3.1 Mar 2004: -% Remove spurious spaces in \url@XXstyle commands. -% ver 3.2 June 2005: -% Fix cmsy-symbols in tt bug (from 3.0); LY1 encoding bug; Enable plain -% with miniltx (again); Define the \urldef for hyperref; Lower "sim" tilde -% a little; fix \lowercase error in \UrlSpecials handling. -% ver 3.3 April 2006: -% Fix some encoding bugs and remove 8-bit characters. lowtilde option -% The End -\end{verbatim} \end{document} -Test file integrity: ASCII 32-57, 58-126: !"#$%&'()*+,-./0123456789 -:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcdefghijklmnopqrstuvwxyz{|}~ - %%% Local Variables: %%% mode: latex diff --git a/Master/texmf-dist/tex/latex/url/url.sty b/Master/texmf-dist/tex/latex/url/url.sty index 30baf537521..801214f6dfa 100644 --- a/Master/texmf-dist/tex/latex/url/url.sty +++ b/Master/texmf-dist/tex/latex/url/url.sty @@ -1,7 +1,7 @@ -% url.sty ver 3.3 12-Apr-2006 Donald Arseneau asnd@triumf.ca -% Copyright 1996-2006 Donald Arseneau, Vancouver, Canada. +% url.sty ver 3.4 16-Sep-2013 Donald Arseneau asnd@triumf.ca +% Copyright 1996-2013 Donald Arseneau, Vancouver, Canada. % This program can be used, distributed, and modified under the terms -% of the LaTeX Project Public License. +% of the LaTeX Project Public License, version 2 or later. % % A form of \verb that allows linebreaks at certain characters or % combinations of characters, accepts reconfiguration, and can usually @@ -20,14 +20,17 @@ % \urldef\xyz\url{ } % \xyz a defined-url: "\xyz" can be used anywhere, no matter what % characters it contains. -% \DeclareUrlCommand\abc{settings}: makes \abc{ } like \url{ } +% \DeclareUrlCommand\abc{settings}: makes \abc{ } like \url{ } with settings % -% See further instructions after "\endinput" +% See url.tex/url.pdf for documentation. Some info after \endinput % +% Required catcodes during loading: letters @ = letter, +% ` = > < . [ ] + - digits = other, +% { } \ ~ # % $ _ ^ = their normal % default style assignments \def\UrlBreaks{\do\.\do\@\do\\\do\/\do\!\do\_\do\|\do\;\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\<}% % any ordinary characters that aren't usually: @@ -77,7 +80,7 @@ % \Url sets up the reading the argument verbatim if possible \def\Url{% \Url@movingtest - \ifmmode\@nomatherr$\fi %$ + \ifmmode\@inmatherr$\fi %$ \let\do\@makeother \dospecials % verbatim catcodes \catcode`{\@ne \catcode`}\tw@ % with exceptions \catcode`\ =10 % allow "\url {x}" @@ -151,7 +154,7 @@ \lccode`\~`#1\lowercase{\endgroup\def~}{#2}} \def\set@mathnolig#1{\ifnum\mathcode`#1<32768 \begingroup\lccode`\~`#1\lowercase{\endgroup - \edef~}{\mathchar\number\mathcode`#1_{\/}}% + \edef~}{\mathchar\number\mathcode`#1\sb{\/}}% \mathcode`#1=32768 \fi} \def\Url@movingtest{\begingroup @@ -212,7 +215,7 @@ \@ifundefined{ProvidesPackage}{ }{\ProvidesPackage - {url}[2006/04/12 \space ver 3.3 \space Verb mode for urls, etc.] + {url}[2013/09/16 \space ver 3.4 \space Verb mode for urls, etc.] \DeclareOption{hyphens}{\def\do@url@hyp{\do\-}}% allow breaks after hyphens \DeclareOption{obeyspaces}{\let\Url@ObeySp\relax}% a flag for later \DeclareOption{spaces}{\def\Url@sppen{\UrlBreakPenalty}} @@ -272,190 +275,8 @@ %\ifx\urldebug\@undefined \def\urldebug{01}\fi \endinput -% -% url.sty ver 3.3 12-Apr-2006 Donald Arseneau asnd@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 -% "{" or a space. 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. (Note that it seems logical to -% allow the sole option "[spaces]" to let input spaces indicate break -% points, but not to display them in the output. This would be easy to -% implement, but is left out to avoid(?) confusion.) -% -% Package Option: lowtilde -% Normal treatment of the ~ character is to use the font's "\textasciitilde" -% character, if it has one (or claims to). Otherwise, the character is -% faked using a mathematic "\sim". The "[lowtilde]" option causes a -% faked character to be used always (and a bit lower than usual). -% -% 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 typewriter and email addresses to be roman, then you would define new -% url-like commands as follows: -% -% \DeclareUrlCommand\email{\urlstyle{rm}} -% \DeclareUrlCommand\directory{\urlstyle{tt}} -% -% 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 -% \DeclareUrlCommand\url{} -% I.e., using whatever "\urlstyle" and other settings are already in effect. -% -% 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' usually 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{}", 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". -% -% You can allow some spacing around the breakable characters by assigning -% \Urlmuskip = 0mu plus 1mu -% You can change the penalties used for BigBreaks and Breaks by assigning -% \mathchardef\UrlBreakPenalty=100 \mathchardef\UrlBigBreakPenalty=100 -% The default penalties are "\binoppenalty" and "\relpenalty". These have -% such odd non-LaTeX syntax because I don't expect people to need to -% change them often. -% -% 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 -% -% \DeclareUrlCommand\url{\def\UrlLeft{}% -% \urlstyle{tt}} -% -% 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:}#1\special{html:}} -% -% Using this technique, url.sty can provide a convenient interface for -% performing various operations on verbatim text. You don't even need -% to print out the argument! For greatest efficiency in such obscure -% applications, you can define a null url-style where all the lists like -% "\UrlBreaks" are empty. +% For documentation, please see accompanying url.tex (url.pdf) +% Package Options: obeyspaces, hyphens, spaces, lowtilde % % Revision History: % ver 1.1 6-Feb-1996: @@ -483,6 +304,8 @@ % a little; fix \lowercase error in \UrlSpecials handling. % ver 3.3 April 2006: % Fix some encoding bugs and remove 8-bit characters. lowtilde option +% ver 3.4 Sept 2013: +% \@nomatherr->\@inmatherr. & is now another \UrlBreak character. % The End Test file integrity: ASCII 32-57, 58-126: !"#$%&'()*+,-./0123456789 -- cgit v1.2.3