summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/breakurl
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2006-01-11 23:51:29 +0000
committerKarl Berry <karl@freefriends.org>2006-01-11 23:51:29 +0000
commit2a340e777d903b208f4f22b1a4259ad7651da213 (patch)
treed04c80f60608705879525066ae441f92b3e04362 /Master/texmf-dist/source/latex/breakurl
parentcd6906267ce325ecb49c22738421c06ee2b0279f (diff)
trunk/Master/texmf-dist/source/latex/breakurl
git-svn-id: svn://tug.org/texlive/trunk@174 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source/latex/breakurl')
-rw-r--r--Master/texmf-dist/source/latex/breakurl/breakurl.dtx700
-rw-r--r--Master/texmf-dist/source/latex/breakurl/breakurl.ins67
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