trunk/Master/texmf-dist/source/latex/breakurl

git-svn-id: svn://tug.org/texlive/trunk@174 c570f23f-e606-0410-a88d-b1316a301751

2 files changed, 767 insertions, 0 deletions

diff --git a/Master/texmf-dist/source/latex/breakurl/breakurl.dtx b/Master/texmf-dist/source/latex/breakurl/breakurl.dtx
new file mode 100644
index 00000000000..ec9a4d64b86
--- /dev/null
+++ b/Master/texmf-dist/source/latex/breakurl/breakurl.dtx
@@ -0,0 +1,700 @@
+% \iffalse meta-comment
+%
+% Copyright (C) 2005 by Vilar Camara Neto.
+%
+% This file may be distributed and/or modified under the
+% conditions of the LaTeX Project Public License, either
+% version 1.2 of this license or (at your option) any later
+% version.  The latest version of this license is in:
+%
+%     http://www.latex-project.org/lppl.txt
+%
+% and version 1.2 or later is part of all distributions of
+% LaTeX version 1999/12/01 or later.
+%
+% Currently this work has the LPPL maintenance status "maintained".
+%
+% The Current Maintainer of this work is Vilar Camara Neto.
+%
+% This work consists of the files breakurl.dtx and
+% breakurl.ins and the derived file breakurl.sty.
+%
+% \fi
+%
+% \iffalse
+%<*driver>
+\ProvidesFile{breakurl.dtx}
+%</driver>
+%<package>\NeedsTeXFormat{LaTeX2e}[1999/12/01]
+%<package>\ProvidesPackage{breakurl}
+%<*package>
+    [2005/09/23 v1.10 Breakable hyperref URLs]
+%</package>
+%<*driver>
+\documentclass{ltxdoc}
+\usepackage[latin1]{inputenc}
+\usepackage[T1]{fontenc}
+\EnableCrossrefs
+\CodelineIndex
+\RecordChanges
+\begin{document}
+\DocInput{breakurl.dtx}
+\end{document}
+%</driver>
+% \fi
+
+% \CheckSum{371}
+
+
+% \CharacterTable
+%  {Upper-case    \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
+%   Lower-case    \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
+%   Digits        \0\1\2\3\4\5\6\7\8\9
+%   Exclamation   \!     Double quote  \"     Hash (number) \#
+%   Dollar        \$     Percent       \%     Ampersand     \&
+%   Acute accent  \'     Left paren    \(     Right paren   \)
+%   Asterisk      \*     Plus          \+     Comma         \,
+%   Minus         \-     Point         \.     Solidus       \/
+%   Colon         \:     Semicolon     \;     Less than     \<
+%   Equals        \=     Greater than  \>     Question mark \?
+%   Commercial at \@     Left bracket  \[     Backslash     \\
+%   Right bracket \]     Circumflex    \^     Underscore    \_
+%   Grave accent  \`     Left brace    \{     Vertical bar  \|
+%   Right brace   \}     Tilde         \~}
+%
+% \changes{v1.10}{2005/09/23}{Added the command \string\urlalt, allowing one to
+%   specify different values for displayed and actual link}
+% \changes{v1.01}{2005/09/22}{Fixed a bug when a page break occurs in the
+%   middle of a link}
+% \changes{v1.00}{2005/07/10}{Support for \string\UrlLeft and \string\UrlRight
+%   macros}
+% \changes{v0.04}{2005/04/24}{hyperref's `colorlinks' and `urlcolor' options
+%   are now working}
+% \changes{v0.03}{2005/03/23}{New `vertfit' option; compatibility with pdfeTeX
+%   engine}
+% \changes{v0.02}{2005/03/20}{Smarter (not segmented) links, optionally allows
+%   breaks after hyphens}
+% \changes{v0.01}{2005/03/05}{Initial version (first draft)}
+%
+% \GetFileInfo{breakurl.dtx}
+%
+% \title{The \textsf{breakurl} package\thanks{This document corresponds to
+% \textsf{breakurl}~\fileversion, dated~\filedate.}}
+% \author{Vilar Camara Neto \\
+% \texttt{neto@dcc.ufmg.br}}
+% \date{September 23, 2005}
+%
+% \maketitle
+%
+% \StopEventually
+%
+% \section{Introduction}
+%
+% The |hyperref| package brings a lot of interesting tools to ``boost''
+% documents produced by \LaTeX. For instance, a PDF file can have clickable
+% links to references, section headings, URLs, etc.
+%
+% Generating a link to a URL may be a concern if it stands near the end of a
+% line of text. When the document is being generated by pdf\LaTeX, there's no
+% problem: the driver can break a link across more than one line. However, the
+% |dvips| driver (used when one prefers the \LaTeX{} $\rightarrow$ DVI
+% $\rightarrow$ PostScript $\rightarrow$ PDF path), because of internal
+% reasons, can't issue line breaks in the middle of a link. Sometimes this
+% turns into a serious aesthetic problem, generating largely underfull/overfull
+% paragraphs; sometimes the final effect is so bad that the link can't even fit
+% inside the physical page limits.
+%
+% To overcome that |dvips| limitation, the |breakurl| package was designed with
+% a simple solution: it provides a command called |\burl| (it stands for
+% ``breakable URL''). Instead of generating one long, atomic link, this command
+% breaks it into small pieces, allowing line breaks between them. Each sequence
+% of pieces that stand together in one line are converted to a hot (clickable)
+% link in the PDF document.
+%
+%
+% \section{How to use it}
+% \label{sec:howtouse}
+%
+% At the preamble, just put a |\usepackage{breakurl}| somewhere \emph{after}
+% the |\usepackage{hyperref}|. The |\burl| command is defined and, by default,
+% the package also turns the |\url| command into a synonym of |\burl|. This
+% might come in handy, for example, if you use Bib\TeX{}, your |.bib|-file has
+% lots of |\url| commands and you don't want to replace them by
+% |\burl|.\footnote{Yes, \texttt{\string\burl} also works inside
+% bibliographies, since they are considered to be ``in the middle of the
+% document''.} If, for some reason, you want to preserve the original behaviour
+% of |\url| (i.e., it creates an unbreakable link), you must supply the
+% |preserveurlmacro| option to the package (see Section \ref{sec:pkgoptions}).
+%
+% In the middle of the document, the syntax of |\burl| (and its synonym |\url|)
+% is exactly like the original |\url|: |\burl|\marg{URL}, where \meta{URL} is,
+% of course, the address to point to. You don't need to care (escape) about
+% special characters like \texttt{\%}, \texttt{\&}, \texttt{\_}, and so on.
+%
+% Another handy command is |\burlalt|\marg{ActualURL}\marg{DisplayedURL}, where
+% \meta{ActualURL} is the actual link and \meta{DisplayedURL} is the link text
+% to be displayed in the document. For consistency, |\urlalt| is a synonym of
+% |\burlalt|, unless the |preserveurlmacro| package option is
+% specified.\footnote{The \texttt{\string\burlalt} command resembles
+% \texttt{\string\hyperref}'s \texttt{\string\href}, but since it works in a
+% different manner I decided not to call it ``\texttt{\string\bhref}''.}
+%
+% The default behaviour of the package is to break the link after any sequence
+% of these characters:
+%
+% \begin{center}
+% \begin{tabular}{lll}
+%   `|:|' (colon) &
+%   `|/|' (slash) &
+%   `|.|' (dot) \\
+%   `|?|' (question mark) &
+%   `|#|' (hash) &
+%   `|&|' (ampersand) \\
+%   `|_|' (underline) &
+%   `|,|' (comma) &
+%   `|;|' (semicolon) \\
+%   `|!|' (exclamation mark)
+% \end{tabular}
+% \end{center}
+%
+% You can add `|-|' (hyphen) to this list (see below), but read why I decided
+% to keep it out of the default list.
+%
+% Remember that breaks are allowed \emph{after} a sequence of these characters,
+% so a link starting with |http://| will never break before the second slash.
+%
+% Also note that I decided not to include the `|-|' (hyphen) character in this
+% default list. It's to avoid a possible confusion when someone encounters a
+% break after a hyphen, e.g.:
+%
+% \begin{quote}
+% Please visit the page at |http://internet-|\\
+% |page.com|, which shows\ldots
+% \end{quote}
+%
+% Here comes the doubt: the author is pointing to |http://internet-page.com| or
+% to |http://internetpage.com|? The |breakurl| package \emph{never} adds a
+% hyphen when a link is broken across lines --- so, the first choice would be
+% the right one ---, but we can't assume that the reader knows this rule; so, I
+% decided to disallow breaks after hyphens. Nevertheless, if you want to
+% overcome my decision, use the |hyphenbreaks| option:
+%
+% \begin{quote}
+%   |\usepackage[hyphenbreaks]{breakurl}|
+% \end{quote}
+%
+%
+% \subsection{Package options}
+% \label{sec:pkgoptions}
+%
+% \newcommand{\defmark}{$\triangleright$}
+% \newcommand{\sep}{$\mid$}
+%
+% When using the |\usepackage| command, you can give some options to customize
+% the package behaviour. Possible options are explained below:
+%
+% \begin{itemize}
+% \item |hyphenbreaks|\par
+%   Instructs the package to allow line breaks after hyphens.
+%
+% \item |preserveurlmacro|\par
+%   Instructs the package to leave the |\url| command exactly as it was before
+%   the package inclusion. Also, |\urlalt| isn't defined as a synonym of
+%   |\burlalt|. In either case (i.e., using |preserveurlmacro| or not), the
+%   breakable link is available via the |\burl| command.
+%
+% \item |vertfit=|\meta{criterion}\par
+%   Estabilishes how the link rectangle's height (and depth) will behave
+%   against the corresponding URL text's vertical range. There are three
+%   options for \meta{criterion}: |local| makes each rectangle fit tightly to
+%   its text's vertical range. This means that each line of a link broken
+%   across lines can have a rectangle with different vertical sizes. |global|
+%   first calculates the height (and depth) to enclose the entire link and
+%   preserves the measures, so the link maintains the vertical size across
+%   lines. |strut| goes even further and ensures that the rectangle's vertical
+%   range corresponds to |\strut|. With this option, rectangles in adjacent
+%   lines can overlap. The default is |vertfit=local|.
+% \end{itemize}
+%
+%
+% \subsection{Additional comments}
+%
+% As stated in the introduction, the |breakurl| is designed for those compiling
+% documents via \LaTeX{}, not pdf\LaTeX. In the latter case, the package
+% doesn't (re)define the |\url| command: it only defines |\burl| to be a
+% synonym of whatever |\url| is defined (e.g., via |url| or |hyperref|
+% packages). Of course, |\burl| may behave differently compared to
+% (non-pdf)\LaTeX, because then the system will use other rules to make line
+% breaks, spacing, etc.
+%
+% Also, this package was not designed to nor tested against other drivers: it's
+% compatible with dvips only. And don't forget to specify the driver (|dvips|)
+% to the |hyperref| package, i.e.:
+%
+% \begin{quote}
+% |\usepackage[dvips]{hyperref}|
+% \end{quote}
+%
+%
+% \subsection{Changelog}
+%
+% (presented in reverse chronological order)
+%
+% \begin{description}
+%
+% \item[v1.10] A new command, |\burlalt| (and the synonym |\urlalt|), allows
+%   one to specify different values for actual and displayed link.
+%
+% \item[v1.01] Fixed a bug that was happening when a link is split into more
+%   than one page.
+%
+% \item[v1.00] The |\UrlLeft| and |\UrlRight| (defined and explained in the
+%   |url| package) are now partially supported. By ``partially'' I mean:
+%   although the original (|url.sty|'s) documentation allows defining
+%   |\UrlLeft| as a command with one argument (things such
+%   \texttt{\string\def\string\UrlLeft\#1\string\UrlRight\{}\emph{do things
+%   with \#1}\texttt{\}}, this isn't expected to work with |breakurl|. Please
+%   use only the basic definition, e.g.: |\def\UrlLeft{<url:\ }|
+%   |\def\UrlRight{>}|.
+%
+% \item[v0.04] Corrected a bug that prevented URLs to be in color, in despite
+%   of |hyperref|'s |colorlinks| and |urlcolor| options. Added an error message
+%   if |vertfit| parameter is invalid.
+%
+% \item[v0.03] The package was tested against |pdfeTeX| engine (which may be
+%   the default for some |teTeX| distributions). Introduced a new package
+%   option, |vertfit|.
+%
+% \item[v0.02] The main issue of the initial release --- the odd-looking
+%   sequence of small links in the same line, if one uses |hyperref|'s link
+%   borders --- was resolved: now the package generates only one rectangle per
+%   line. Also, breaks after hyphens, which weren't allowed in the previous
+%   release, are now a users' option. Finally, the package can be used with
+%   pdf\LaTeX{} (in this case, |\burl| is defined to be a synonym of the
+%   original |\url| command).
+%
+% \item[v0.01] Initial release.
+%
+% \end{description}
+%
+%
+% \subsection{Troubleshooting}
+%
+% I received some comments saying that in some cases |breakurl| destroys the
+% formatting of the document: the left/right margins aren't respected,
+% justification becomes weird, etc. In all these cases, the problems were
+% corrected when other packages were upgraded, notabily |xkeyval|.
+%
+% If your compilation issues the following error:
+% \begin{quote}
+%   |! Undefined control sequence.|\\
+%   |<argument> \headerps@out| \ldots
+% \end{quote}
+% it's probabily because you forgot to specify the |dvips| driver as an option
+% to |hyperref|. Check if you have it:
+% \begin{quote}
+% |\usepackage[dvips]{hyperref}|
+% \end{quote}
+%
+%
+%
+% \subsection{Acknowledgments}
+%
+% Thanks to Hendri Adriaens, Donald Arseneau, Michael Friendly, Morten Høgholm,
+% David Le Kim, Damian Menscher, Tristan Miller, Christoph Schiller, Xiaotian
+% Sun, and David Tulloh for suggestions, bug reports, comments, and
+% corrections. A special thanks to the participants of |comp.text.tex|
+% newsgroups for their constant effort to help hundreds of people in the
+% beautiful world of \TeX/\LaTeX.
+%
+%
+% \section{Source code}
+%
+% This section describes the |breakurl.sty| source code.
+%
+% Since |breakurl| is an extension to |hyperref|, let's complain loudly if the
+% latter was not yet loaded:
+%
+%    \begin{macrocode}
+\@ifpackageloaded{hyperref}{}{%
+  \PackageError{breakurl}{The breakurl depends on hyperref package}%
+  {I can't do anything. Please type X <return>, edit the source file^^J%
+  and add \string\usepackage\string{hyperref\string} before
+  \string\usepackage\string{breakurl\string}.}
+  \endinput
+}
+%    \end{macrocode}
+
+% The |breakurl| requires some packages, so let's include them:
+%    \begin{macrocode}
+\RequirePackage{xkeyval}
+%    \end{macrocode}
+
+% The package options are handled by |\newif|s, which are declared and
+% initialised:
+%
+%    \begin{macrocode}
+\newif\if@preserveurlmacro\@preserveurlmacrofalse
+\newif\if@burl@fitstrut\@burl@fitstrutfalse
+\newif\if@burl@fitglobal\@burl@fitglobalfalse
+%    \end{macrocode}
+
+% \DescribeMacro{\burl@toks}
+% The |breakurl| package uses a token list to store characters and tokens until
+% a break point is reached:
+%
+%    \begin{macrocode}
+\newtoks\burl@toks
+%    \end{macrocode}
+
+% \DescribeMacro{\burl@charlist}
+% \DescribeMacro{\burl@defifstructure}
+% The following support routines are designed to build the conditional
+% structure that is the kernel of |\burl|: comparing each incoming character
+% with the list of ``breakable'' characters and taking decisions on that. This
+% conditional structure is built by |\burl@defifstructure| --- which is called
+% only at the end of package loading, because the character list (stored in
+% |\burl@charlist|) can be modified by the |hyphenbreaks| option.
+%
+%    \begin{macrocode}
+\def\burl@charlist{}
+\def\burl@addtocharlist#1{%
+  \expandafter\gdef\expandafter\burl@charlist\expandafter{%
+    \burl@charlist #1}%
+}
+
+\bgroup
+\catcode`\&=12\relax
+\hyper@normalise\burl@addtocharlist{:/.?#&_,;!}
+\egroup
+
+\def\burl@growmif#1{%
+  \expandafter\def\expandafter\burl@mif\expandafter{%
+    \burl@mif\def\burl@ttt{#1}\ifx\burl@ttt\@nextchar\@burl@breakabletrue\else
+  }%
+}
+\def\burl@growmfi{%
+  \expandafter\def\expandafter\burl@mfi\expandafter{\burl@mfi\fi}%
+}
+\def\burl@melse{%
+  \if@burl@breakable\burl@flush\linebreak[0]\@burl@breakablefalse\fi
+  \expandafter\expandafter\expandafter\burl@toks
+    \expandafter\expandafter\expandafter{%
+    \expandafter\the\expandafter\burl@toks\@nextchar}%
+}
+\def\burl@defifstructure{%
+  \def\burl@mif{}%
+  \def\burl@mfi{}%
+  \expandafter\@tfor\expandafter\@nextchar\expandafter:\expandafter=%
+    \burl@charlist\do{%
+    \expandafter\burl@growmif\@nextchar
+    \burl@growmfi
+  }%
+}
+
+\AtEndOfPackage{\burl@defifstructure}
+%    \end{macrocode}
+
+% The package options are declared and handled as follows:
+%
+%    \begin{macrocode}
+\def\burl@setvertfit#1{%
+  \lowercase{\def\burl@temp{#1}}%
+  \def\burl@opt{local}\ifx\burl@temp\burl@opt
+    \@burl@fitstrutfalse\@burl@fitglobalfalse
+  \else\def\burl@opt{strut}\ifx\burl@temp\burl@opt
+    \@burl@fitstruttrue\@burl@fitglobalfalse
+  \else\def\burl@opt{global}\ifx\burl@temp\burl@opt
+    \@burl@fitstrutfalse\@burl@fitglobaltrue
+  \else
+    \PackageWarning{breakurl}{Unrecognized vertfit option `\burl@temp'.^^J%
+    Adopting default `local'}
+    \@burl@fitstrutfalse\@burl@fitglobalfalse
+  \fi\fi\fi
+}
+
+\DeclareOptionX{preserveurlmacro}{\@preserveurlmacrotrue}
+\DeclareOptionX{hyphenbreaks}{\bgroup
+  \catcode`\&=12\relax\hyper@normalise\burl@addtocharlist{-}%
+  \egroup}
+\DeclareOptionX{vertfit}[local]{\burl@setvertfit{#1}}
+
+\ProcessOptionsX\relax
+%    \end{macrocode}
+
+% Is the document being processed by pdf\LaTeX? Then, well, this package
+% doesn't apply: let's just define |\burl| to call the default |\url|.
+%
+%    \begin{macrocode}
+\ifx\pdfoutput\undefined\else\ifx\pdfoutput\relax\else\ifcase\pdfoutput\else
+  \PackageWarning{breakurl}{%
+  You are using breakurl while processing via pdflatex.^^J%
+  \string\burl\space will be just a synonym of \string\url.^^J}
+  \DeclareRobustCommand{\burl}{\url}
+  \endinput
+\fi\fi\fi
+%    \end{macrocode}
+
+% These supporting routines are modified versions of those found in the
+% |hyperref| package. They were adapted to allow a link to be progressively
+% built, i.e., when we say ``put a link rectangle here'', the package will
+% decide if this will be made.
+%    \begin{macrocode}
+\def\burl@hyper@linkurl#1#2{%
+  \begingroup
+    \hyper@chars
+    \leavevmode
+    \burl@condpdflink{#1}%
+  \endgroup
+}
+
+\def\burl@condpdflink#1{%
+  \leavevmode
+  \if@burl@fitstrut
+    \sbox\pdf@box{#1\strut}%
+  \else\if@burl@fitglobal
+    \sbox\pdf@box{\burl@url}%
+  \else
+    \sbox\pdf@box{#1}%
+  \fi\fi
+  \dimen@\ht\pdf@box\dimen@ii\dp\pdf@box
+  \sbox\pdf@box{#1}%
+  \leavevmode
+  \ifdim\dimen@ii=\z@
+    \literalps@out{BU.SS}%
+  \else
+    \lower\dimen@ii\hbox{\literalps@out{BU.SS}}%
+  \fi
+  \ifHy@breaklinks\unhbox\else\box\fi\pdf@box
+  \ifdim\dimen@=\z@
+    \literalps@out{BU.SE}%
+  \else
+    \raise\dimen@\hbox{\literalps@out{BU.SE}}%
+  \fi
+  \pdf@addtoksx{H.B}%
+}
+%    \end{macrocode}
+
+% \DescribeMacro{\burl}
+% |\burl| prepares the catcodes (via |\hyper@normalise|) and calls the |\burl@|
+% macro, which does the actual work.
+%
+%    \begin{macrocode}
+\DeclareRobustCommand*{\burl}{%
+  \begingroup
+  \let\hyper@linkurl=\burl@hyper@linkurl
+  \catcode`\&=12\relax
+  \hyper@normalise\burl@
+}
+%    \end{macrocode}
+
+% \DescribeMacro{\burlalt}
+% |\burlalt| does the same as |\burl|, but calls another macro (|\burl@alt|)
+% to read two following arguments instead of only one.
+%
+%    \begin{macrocode}
+\DeclareRobustCommand*{\burlalt}{%
+  \begingroup
+  \let\hyper@linkurl=\burl@hyper@linkurl
+  \catcode`\&=12\relax
+  \hyper@normalise\burl@alt
+}
+%    \end{macrocode}
+
+% \DescribeMacro{\burl@}
+% \DescribeMacro{\burl@alt}
+% \DescribeMacro{\burl@@alt}
+% |\burl@| \marg{URL} just eats the next argument to define the URL address and
+% the link to be displayed. Both are used by |\burl@doit|.
+%
+% |\burl@alt| \marg{ActualURL} and |\burl@@alt| \marg{DisplayedURL} work
+% together to eat the two arguments (the actual URL to point to and the link
+% text to be displayed). Again, both are used by |\burl@doit|.
+%    \begin{macrocode}
+\newif\if@burl@breakable
+
+\bgroup
+\catcode`\&=12\relax
+\gdef\burl@#1{%
+  \def\burl@url{#1}%
+  \def\burl@urltext{#1}%
+  \burl@doit
+}
+
+\gdef\burl@alt#1{%
+  \def\burl@url{#1}%
+  \hyper@normalise\burl@@alt
+}
+\gdef\burl@@alt#1{%
+  \def\burl@urltext{#1}%
+  \burl@doit
+}
+%    \end{macrocode}
+
+% \DescribeMacro{\burl@doit}
+% |\burl@doit| works much like hyperref's |\url@| macro (actually, this code
+% macro was borrowed and adapted from the original |\url@|): it builds a series
+% of links, allowing line breaks between them. The characters are accumulated
+% and eventually flushed via the |\burl@flush| macro.
+%
+% Support for |\UrlLeft|/|\UrlRight|: The |\UrlRight| is emptied until the very
+% last flush (when it is restored). The |\UrlLeft| is emptied after the first
+% flush. So, any string defined in those macros are meant to be displayed only
+% before the first piece and after the last one, which (of course) is what we
+% expect to happen. Unfortunately, breaking doesn't happen inside those
+% strings, since they're not rendered verbatim (and so they aren't processed
+% inside the breaking mechanism).
+%
+%    \begin{macrocode}
+\gdef\burl@doit{%
+  \burl@toks{}%
+  \let\burl@UrlRight=\UrlRight
+  \let\UrlRight=\empty
+  \Hy@colorlink{\@ifundefined{@urlcolor}{\@linkcolor}{\@urlcolor}}%
+  \@burl@breakablefalse
+  \expandafter\@tfor\expandafter\@nextchar\expandafter:\expandafter=%
+    \burl@urltext\do{%
+    \expandafter\burl@mif\expandafter\burl@melse\burl@mfi
+    \if@burl@breakable
+      \expandafter\expandafter\expandafter\burl@toks
+        \expandafter\expandafter\expandafter{%
+        \expandafter\the\expandafter\burl@toks\@nextchar}%
+    \fi
+  }%
+  \let\UrlRight=\burl@UrlRight
+  \burl@flush
+  \literalps@out{BU.E}%
+  \Hy@endcolorlink
+  \endgroup
+}
+\egroup
+%    \end{macrocode}
+
+% \DescribeMacro{\burl@flush}
+% This macro flushes the characters accumulated during the |\burl@| processing,
+% creating a link to the URL.
+%
+%    \begin{macrocode}
+\def\the@burl@toks{\the\burl@toks}
+
+\def\burl@flush{%
+  \expandafter\def\expandafter\burl@toks@def\expandafter{\the\burl@toks}%
+  \literalps@out{/BU.L (\burl@url) def}%
+  \hyper@linkurl{\expandafter\Hurl\expandafter{\burl@toks@def}}{\burl@url}%
+  \global\burl@toks{}%
+  \let\UrlLeft=\empty
+}%
+%    \end{macrocode}
+
+% Now the synonyms |\url| and |\urlalt| are (re)defined, unless the
+% |preserveurlmacro| option is given.
+%
+%    \begin{macrocode}
+\if@preserveurlmacro\else\let\url\burl\let\urlalt\burlalt\fi
+%    \end{macrocode}
+
+% Internally, the package works as follows: each link segment (i.e., a list of
+% non-breakable characters followed by breakable characters) ends with a PDF
+% command that checks if the line ends here. If this check is true, then (and
+% only then) the PDF link rectangle is built, embracing all link segments of
+% this line.
+%
+% To make that work, we need some code to work at the PDF processing level.
+% The supporting routines to do so are introduced in the PDF dictionary
+% initialization block via specials. Each routine is explained below.
+%
+% The variables used here are: |burl@stx| and |burl@endx|, which defines the
+% link's horizontal range; |burl@boty| and |burl@topy|, which defines the
+% link's vertical range; |burl@llx|, |burl@lly|, |burl@urx|, and |burl@ury|,
+% which define the bounding box of the current link segment (they resemble the
+% |hyperref|'s |pdf@llx|--|pdf@ury| counterparts); and |BU.L|, which holds the
+% target URL.
+%    \begin{macrocode}
+\AtBeginDvi{%
+  \headerps@out{%
+    /burl@stx null def
+%    \end{macrocode}
+% |BU.S| is called whenever a link begins:
+%    \begin{macrocode}
+    /BU.S {
+      /burl@stx null def
+    } def
+%    \end{macrocode}
+% |BU.SS| is called whenever each link segment begins:
+%    \begin{macrocode}
+    /BU.SS {
+      currentpoint
+      /burl@lly exch def
+      /burl@llx exch def
+      burl@stx null ne {burl@endx burl@llx ne {BU.FL BU.S} if} if
+      burl@stx null eq {
+        burl@llx dup /burl@stx exch def /burl@endx exch def
+        burl@lly dup /burl@boty exch def /burl@topy exch def
+      } if
+      burl@lly burl@boty gt {/burl@boty burl@lly def} if
+    } def
+%    \end{macrocode}
+% |BU.SE| is called whenever each link segment ends:
+%    \begin{macrocode}
+    /BU.SE {
+      currentpoint
+      /burl@ury exch def
+      dup /burl@urx exch def /burl@endx exch def
+      burl@ury burl@topy lt {/burl@topy burl@ury def} if
+    } def
+%    \end{macrocode}
+% |BU.SE| is called whenever the entire link ends:
+%    \begin{macrocode}
+    /BU.E {
+      BU.FL
+    } def
+%    \end{macrocode}
+% |BU.FL| is called to conditionally flush the group of link segments that we
+% have so far. This is meant to be called at each line break:
+%    \begin{macrocode}
+    /BU.FL {
+      burl@stx null ne {BU.DF} if
+    } def
+%    \end{macrocode}
+% |BU.DF| is the routine to actually put the link rectangle in the PDF file:
+%    \begin{macrocode}
+    /BU.DF {
+      BU.BB
+      [ /H /I /Border [\@pdfborder] /Color [\@urlbordercolor]
+      /Action << /Subtype /URI /URI BU.L >> /Subtype /Link BU.B /ANN pdfmark
+      /burl@stx null def
+    } def
+%    \end{macrocode}
+% |BU.FF| adds margins to the calculated tight rectangle:
+%    \begin{macrocode}
+    /BU.BB {
+      burl@stx HyperBorder sub /burl@stx exch def
+      burl@endx HyperBorder add /burl@endx exch def
+      burl@boty HyperBorder add /burl@boty exch def
+      burl@topy HyperBorder sub /burl@topy exch def
+    } def
+%    \end{macrocode}
+% |BU.B| converts the coordinates into a rectangle:
+%    \begin{macrocode}
+    /BU.B {
+      /Rect[burl@stx burl@boty burl@endx burl@topy]
+    } def
+%    \end{macrocode}
+% Finally, we must redefine |eop|, which is called just when the page ends, to
+% handle links that are split into more than one page. (|eop-hook| isn't the
+% right place to do so, since this hook is called after the dictionaries were
+% reverted to a previous state, vanishing the rectangle coordinates.)
+%    \begin{macrocode}
+    /eop where {
+      begin
+      /@ldeopburl /eop load def
+      /eop { SDict begin BU.FL end @ldeopburl } def
+      end
+    } {
+      /eop { SDict begin BU.FL end } def
+    } ifelse
+  }%
+}
+%    \end{macrocode}
+%
+% \Finale
diff --git a/Master/texmf-dist/source/latex/breakurl/breakurl.ins b/Master/texmf-dist/source/latex/breakurl/breakurl.ins
new file mode 100644
index 00000000000..13b56ca6401
--- /dev/null
+++ b/Master/texmf-dist/source/latex/breakurl/breakurl.ins
@@ -0,0 +1,67 @@
+%%
+%% Copyright (C) 2005 by Vilar Camara Neto.
+%%
+%% This file may be distributed and/or modified under the
+%% conditions of the LaTeX Project Public License, either
+%% version 1.2 of this license or (at your option) any later
+%% version.  The latest version of this license is in:
+%%
+%%     http://www.latex-project.org/lppl.txt
+%%
+%% and version 1.2 or later is part of all distributions of
+%% LaTeX version 1999/12/01 or later.
+%%
+%% Currently this work has the LPPL maintenance status "maintained".
+%%
+%% The Current Maintainer of this work is Vilar Camara Neto.
+%%
+%% This work consists of the files breakurl.dtx and
+%% breakurl.ins and the derived file breakurl.sty.
+%%
+\input docstrip.tex
+\keepsilent
+\usedir{tex/latex/misc}
+
+\preamble
+
+This is a generated file.
+
+Copyright (C) 2005 by Vilar Camara Neto.
+
+This file may be distributed and/or modified under the
+conditions of the LaTeX Project Public License, either
+version 1.2 of this license or (at your option) any later
+version.  The latest version of this license is in:
+
+    http://www.latex-project.org/lppl.txt
+
+and version 1.2 or later is part of all distributions of
+LaTeX version 1999/12/01 or later.
+
+Currently this work has the LPPL maintenance status "maintained".
+
+The Current Maintainer of this work is Vilar Camara Neto.
+
+This work consists of the files breakurl.dtx and
+breakurl.ins and the derived file breakurl.sty.
+
+\endpreamble
+
+\generateFile{breakurl.sty}{n}{\from{breakurl.dtx}{package}}
+
+\obeyspaces
+\Msg{****************************************************}
+\Msg{*                                                  *}
+\Msg{* To finish the installation you have to move the  *}
+\Msg{* following file into a directory searched by TeX: *}
+\Msg{*                                                  *}
+\Msg{* breakurl.sty                                     *}
+\Msg{*                                                  *}
+\Msg{* To produce the documentation run the file        *}
+\Msg{* breakurl.dtx through LaTeX.                      *}
+\Msg{*                                                  *}
+\Msg{* Happy TeXing!                                    *}
+\Msg{*                                                  *}
+\Msg{****************************************************}
+
+\endbatchfile