summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/breakurl
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
committerNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
commite0c6872cf40896c7be36b11dcc744620f10adf1d (patch)
tree60335e10d2f4354b0674ec22d7b53f0f8abee672 /macros/latex/contrib/breakurl
Initial commit
Diffstat (limited to 'macros/latex/contrib/breakurl')
-rw-r--r--macros/latex/contrib/breakurl/README84
-rw-r--r--macros/latex/contrib/breakurl/breakurl.dtx831
-rw-r--r--macros/latex/contrib/breakurl/breakurl.ins67
-rw-r--r--macros/latex/contrib/breakurl/breakurl.pdfbin0 -> 123540 bytes
4 files changed, 982 insertions, 0 deletions
diff --git a/macros/latex/contrib/breakurl/README b/macros/latex/contrib/breakurl/README
new file mode 100644
index 0000000000..abb7461dab
--- /dev/null
+++ b/macros/latex/contrib/breakurl/README
@@ -0,0 +1,84 @@
+README for breakurl, version 1.40 (2013/04/10)
+
+
+INTRODUCTION
+============
+
+The breakurl is an extension to hyperref package that allows line-breakable
+\url-like links when compiling via latex + dvips + ps2pdf.
+
+
+DESCRIPTION
+===========
+
+This package provides a command much like hyperref's \url that typesets a URL
+using a typewriter-like font. However, if the dvips driver is being used, the
+original \url doesn't allow line breaks in the middle of the created link: the
+link comes in one atomic piece. This package allows such line breaks in the
+generated links.
+
+Note that this package is intended only for those using the dvips driver.
+Users of the pdflatex driver already have this feature.
+
+
+INSTALLATION
+============
+
+Eventually breakurl may be pre-configured on your system. These instructions
+are relevant only if your LaTeX system complains about missing `breakurl.sty'.
+
+If you use MiKTeX, the utility "MiKTeX Package Manager" (Start menu > Programs
+> MiKTeX > Browse Packages or MiKTeX Package Manager) is your friend. Just
+select `breakurl' and click on Task > Install.
+
+Some Linux systems provide an easy way to install breakurl. As far as I know,
+recent Debian and Ubuntu distros provide the "texlive-latex-extra" system
+package in the default repository.
+
+If you need to do a manual installation (eventually needed under Unix-like
+systems), following instructions may come in handy:
+
+a) Download the package files from CTAN or the TUG server.
+
+b) Generate the `breakurl.sty' file:
+
+ latex breakurl.ins
+
+c) Install the file `breakurl.sty' into your TDS tree:
+
+ mkdir [prefix]/texmf/tex/latex/breakurl
+ cp breakurl.sty [prefix]/texmf/tex/latex/breakurl/
+
+ where `[prefix]' is the prefix of your TDS tree.
+
+d) Update the databases if necessary, eg. for teTeX:
+
+ mktexlsr [prefix]/texmf
+
+
+DOCUMENTATION
+=============
+
+Please see the breakurl.pdf for a more comprehensive description of the
+package, its options, issues, etc. Or generate a dvi version using the
+following:
+
+ latex breakurl.dtx
+
+
+LICENSE
+=======
+
+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.
+
+--
+Vilar da Camara Neto
+Manaus, Amazonas, Brazil
+breakurl@vilarneto.com
diff --git a/macros/latex/contrib/breakurl/breakurl.dtx b/macros/latex/contrib/breakurl/breakurl.dtx
new file mode 100644
index 0000000000..fca7e8d8bd
--- /dev/null
+++ b/macros/latex/contrib/breakurl/breakurl.dtx
@@ -0,0 +1,831 @@
+% \iffalse meta-comment
+%
+% Copyright (C) 2005,2006,2007,2008,2009 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>
+ [2013/04/10 v1.40 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{401}
+
+
+% \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.40}{2013/04/10}{New `anythingbreaks' option}
+% \changes{v1.30}{2009/01/24}{Breaks are now allowed before percent signs}
+% \changes{v1.23}{2008/07/15}{\string\hypersetup can now be used anywhere}
+% \changes{v1.22}{2008/04/05}{Corrected a misuse of \string\leavevmode which
+% generated blank lines inside tables}
+% \changes{v1.21}{2007/06/20}{\string\burlalt and \string\urlalt now work under
+% pdflatex; also bug fixes from Heiko Oberdiek}
+% \changes{v1.20}{2006/08/26}{Changes to reflect update of hyperref package}
+% \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}
+%
+% \newcommand{\pkg}[1]{\textsf{#1}}
+%
+% \title{The \pkg{breakurl} package\thanks{This document corresponds to
+% \textsf{breakurl}~\fileversion, dated~\filedate.}}
+% \author{Vilar Camara Neto \\
+% \texttt{breakurl@vilarneto.com}}
+% \date{April 10, 2013}
+%
+% \maketitle
+%
+% \StopEventually
+%
+% \sloppy
+%
+% \section{Introduction}
+%
+% The \pkg{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 one uses pdf\LaTeX{} to directly generate a PDF document,
+% 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 \pkg{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. Also, by default the |\url| command is turned into
+% a synonym of |\burl|, so there's no need to do a search-replace operation to
+% immediately start using the package.
+%
+%
+% \section{How to use it}
+% \label{sec:howtouse}
+%
+% At the preamble, just put |\usepackage{breakurl}| somewhere \emph{after}
+% |\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|. If, for
+% some reason, you want to preserve the original behavior 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 the same as 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 behavior 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}
+% and before occurrences of any of these:
+% \begin{center}
+% \begin{tabular}{l}
+% `|%|' (percent sign)
+% \end{tabular}
+% \end{center}
+%
+% Remember that (with exception of percent sign) breaks are only 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 the
+% default lists. 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 \pkg{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 behavior. Possible options are explained below:
+%
+% \begin{itemize}
+% \item |hyphenbreaks|\par
+% Instructs the package to allow line breaks after hyphens.
+%
+% \item |anythingbreaks|\par
+% Instructs the package to allow line breaks everywhere. This may be used as
+% a last-resort workaround when working with really, \emph{really} long URLs
+% that generate bad-looking outputs. You may see strange crowds of bracket
+% couples in the logs --- but, hey, you are the one that asked for trouble
+% anyway.
+%
+% \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 \pkg{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 \pkg{url} or
+% \pkg{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.
+%
+%
+% \subsection{Changelog}
+%
+% (presented in reverse chronological order)
+%
+% \begin{description}
+%
+% \item[v1.40] New \texttt{anythingbreaks} option.
+%
+% \item[v1.30] Breaks are now allowed before percent sign (|%|).
+%
+% \item[v1.23] |\hypersetup| now works anywhere.
+%
+% \item[v1.22] Corrected blank lines appearing inside tables.
+%
+% \item[v1.21] |\burlalt| and the synonym |\urlalt| now work with pdflatex.
+% Also, there are a couple of bug fixes (thank you again, Heiko).
+%
+% \item[v1.20] An update was needed because \pkg{hyperref}'s internals were
+% changed. (Thanks Heiko for sending the correction patch.) Troubleshooting
+% now includes a note about |\sloppy|.
+%
+% \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 across
+% pages.
+%
+% \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 \pkg{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 \pkg{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 \pkg{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}
+%
+% Here comes a few notes about known issues:
+%
+% \begin{itemize}
+%
+% \item I received some comments saying that in some cases \pkg{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|.
+%
+% \item If your compilation issues the following error:
+% \begin{quote}
+% |! Undefined control sequence.|\\
+% |<argument> \headerps@out| \ldots
+% \end{quote}
+% then you need to specify the |dvips| driver as an option to the
+% \pkg{hyperref} package, e.g.:
+% \begin{quote}
+% |\usepackage[dvips]{hyperref}|
+% \end{quote}
+%
+% However, this is related to old versions of \pkg{hyperref}. Currently the
+% package is able to automatically determine the driver in current versions.
+% It's probabily better to update your \LaTeX{} system.
+%
+% \item If everything compiles but sometimes URLs still don't respect the right
+% margin, don't blame the package yet :-) . Roughly speaking, by default the
+% right margin is a limit to be respected ``only if word spacing is okay'',
+% so it may be ignored even when URLs aren't used. Check the following
+% paragraph:
+%
+% \fussy
+%
+% Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Proin
+% zzzzzzzzzzzzzzzzzzzzzzz\ldots
+%
+% \sloppy
+%
+% To overcome this (and make right margins a hard limit) use the command
+% |\sloppy|, preferably before |\begin{document}|. This makes the previous
+% paragraph look like:
+%
+% Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Proin
+% zzzzzzzzzzzzzzzzzzzzzzz\ldots
+%
+% As a drawback word spacing becomes terrible, but now the text is kept
+% inside designed margins. You should decide what looks better.
+%
+% \item Umesh Vishwakarma reports that \pkg{breakurl} has issues \texttt{dv2dt}
+% and \texttt{dt2dv} tools. Unfortunately I don't have time to track this
+% down (actually I don't even know these tools), so contributions are
+% welcome.
+%
+% \end{itemize}
+%
+% \subsection{Acknowledgments}
+%
+% Thanks to Hendri Adriaens, Donald Arseneau, Dominik Derigs, Michael Friendly,
+% Morten Høgholm, David Le Kim, Damian Menscher, Tristan Miller, Heiko
+% Oberdiek, Christoph Schiller, Xiaotian Sun, Michael Toews, David Tulloh,
+% Adrian Vogel, Yu Zhang, and Jinsong Zhao for suggestions, bug reports,
+% comments, and corrections. A special thanks to the participants of
+% |comp.text.tex| newsgroups for their constant effort to help thousands of
+% people in the beautiful world of \TeX{} and \LaTeX.
+%
+%
+% \section{Source code}
+%
+% This section describes the |breakurl.sty| source code.
+%
+% The \pkg{breakurl} requires some packages, so let's include them:
+%
+% \begin{macrocode}
+\RequirePackage{xkeyval}
+\RequirePackage{ifpdf}
+% \end{macrocode}
+
+% Is the document being processed by pdf\LaTeX? (Actually, is there a PDF file
+% being directly generated?) Then, well, this package doesn't apply: let's just
+% define |\burl| to call the default |\url|.
+%
+% \begin{macrocode}
+\ifpdf
+ % Dummy package options
+ \DeclareOptionX{preserveurlmacro}{}
+ \DeclareOptionX{hyphenbreaks}{}
+ \DeclareOptionX{anythingbreaks}{}
+ \DeclareOptionX{vertfit}{}
+ \ProcessOptionsX\relax
+
+ \PackageWarning{breakurl}{%
+ You are using breakurl while processing via pdflatex.\MessageBreak
+ \string\burl\space will be just a synonym of \string\url.\MessageBreak}
+ \DeclareRobustCommand{\burl}{\url}
+ \DeclareRobustCommand*{\burlalt}{\hyper@normalise\burl@alt}
+ \def\burl@alt#1#2{\hyper@linkurl{\Hurl{#1}}{#2}}
+ \expandafter\endinput
+\fi
+% \end{macrocode}
+
+% Since \pkg{breakurl} is an extension to \pkg{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%
+ \MessageBreak
+ and add \string\usepackage\string{hyperref\string} before
+ \string\usepackage\string{breakurl\string}.}
+ \endinput
+}
+% \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
+\newif\if@burl@anythingbreaks\@burl@anythingbreaksfalse
+% \end{macrocode}
+
+% \DescribeMacro{\burl@toks}
+% The \pkg{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@charlistbefore}
+% \DescribeMacro{\burl@charlistafter}
+% \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@charlistbefore|) can be modified by the |hyphenbreaks| option.
+%
+% \begin{macrocode}
+\let\burl@charlistbefore\empty
+\let\burl@charlistafter\empty
+
+\def\burl@addtocharlistbefore{\g@addto@macro\burl@charlistbefore}
+\def\burl@addtocharlistafter{\g@addto@macro\burl@charlistafter}
+
+\bgroup
+ \catcode`\&=12\relax
+ \hyper@normalise\burl@addtocharlistbefore{%}
+ \hyper@normalise\burl@addtocharlistafter{:/.?#&_,;!}
+\egroup
+
+\def\burl@growmif#1#2{%
+ \g@addto@macro\burl@mif{\def\burl@ttt{#1}\ifx\burl@ttt\@nextchar#2\else}%
+}
+\def\burl@growmfi{%
+ \g@addto@macro\burl@mfi{\fi}%
+}
+\def\burl@defifstructure{%
+ \let\burl@mif\empty
+ \let\burl@mfi\empty
+ \expandafter\@tfor\expandafter\@nextchar\expandafter:\expandafter=%
+ \burl@charlistbefore\do{%
+ \expandafter\burl@growmif\@nextchar\@burl@breakbeforetrue
+ \burl@growmfi
+ }%
+ \expandafter\@tfor\expandafter\@nextchar\expandafter:\expandafter=%
+ \burl@charlistafter\do{%
+ \expandafter\burl@growmif\@nextchar\@burl@breakaftertrue
+ \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'.%
+ \MessageBreak
+ Adopting default `local'}
+ \@burl@fitstrutfalse\@burl@fitglobalfalse
+ \fi\fi\fi
+}
+
+\DeclareOptionX{preserveurlmacro}{\@preserveurlmacrotrue}
+\DeclareOptionX{hyphenbreaks}{%
+ \bgroup
+ \catcode`\&=12\relax
+ \hyper@normalise\burl@addtocharlistafter{-}%
+ \egroup
+}
+\DeclareOptionX{anythingbreaks}{%
+ \@burl@anythingbreakstrue
+}
+\DeclareOptionX{vertfit}[local]{\burl@setvertfit{#1}}
+
+\ProcessOptionsX\relax
+% \end{macrocode}
+
+% These supporting routines are modified versions of those found in the
+% \pkg{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
+ \burl@condpdflink{#1}%
+ \endgroup
+}
+
+\def\burl@condpdflink#1{%
+ \literalps@out{
+ /burl@bordercolor {\@urlbordercolor} def
+ /burl@border {\@pdfborder} def
+ }%
+ \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}%
+ \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}{%
+ \leavevmode
+ \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@breakbefore
+\newif\if@burl@breakafter
+\newif\if@burl@prevbreakafter
+
+\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
+ \@burl@prevbreakafterfalse
+ \@ifundefined{@urlcolor}{\Hy@colorlink\@linkcolor}{\Hy@colorlink\@urlcolor}%
+ \expandafter\@tfor\expandafter\@nextchar\expandafter:\expandafter=%
+ \burl@urltext\do{%
+ \if@burl@breakafter\@burl@prevbreakaftertrue
+ \else\@burl@prevbreakafterfalse\fi
+ \if@burl@anythingbreaks\@burl@breakbeforetrue\else\@burl@breakbeforefalse\fi
+ \@burl@breakafterfalse
+ \expandafter\burl@mif\burl@mfi
+ \if@burl@breakbefore
+ % Breakable if the current char is in the `can break before' list
+ \burl@flush\linebreak[0]%
+ \else
+ \if@burl@prevbreakafter
+ \if@burl@breakafter\else
+ % Breakable if the current char is not in any of the `can break'
+ % lists, but the previous is in the `can break after' list.
+ % This mechanism accounts for sequences of `break after' characters,
+ % where a break is allowed only after the last one
+ \burl@flush\linebreak[0]%
+ \fi
+ \fi
+ \fi
+ \expandafter\expandafter\expandafter\burl@toks
+ \expandafter\expandafter\expandafter{%
+ \expandafter\the\expandafter\burl@toks\@nextchar}%
+ }%
+ \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 PostScript processing
+% level. The supporting routines to do so are introduced in the PS 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
+% \pkg{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 a 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 a 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 [burl@border] /Color [burl@bordercolor]
+ /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 across pages. (|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/macros/latex/contrib/breakurl/breakurl.ins b/macros/latex/contrib/breakurl/breakurl.ins
new file mode 100644
index 0000000000..13b56ca640
--- /dev/null
+++ b/macros/latex/contrib/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
diff --git a/macros/latex/contrib/breakurl/breakurl.pdf b/macros/latex/contrib/breakurl/breakurl.pdf
new file mode 100644
index 0000000000..8b0d18cca3
--- /dev/null
+++ b/macros/latex/contrib/breakurl/breakurl.pdf
Binary files differ