new latex package issuulinks (28feb12)

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

2 files changed, 306 insertions, 0 deletions

diff --git a/Master/texmf-dist/source/latex/issuulinks/issuulinks.dtx b/Master/texmf-dist/source/latex/issuulinks/issuulinks.dtx
new file mode 100644
index 00000000000..8223de7cf2f
--- /dev/null
+++ b/Master/texmf-dist/source/latex/issuulinks/issuulinks.dtx
@@ -0,0 +1,277 @@
+% \iffalse
+% $Id: issuulinks.dtx,v 1.5 2012-02-28 01:48:35 boris Exp $
+%
+% Copyright 2012, Boris Veytsman <borisv@lk.net>
+% This work may be distributed and/or modified under the
+% conditions of the LaTeX Project Public License, either
+% version 1.3 of this license or (at your option) any 
+% later version.
+% The latest version of the license is in
+%    http://www.latex-project.org/lppl.txt
+% and version 1.3 or later is part of all distributions of
+% LaTeX version 2003/06/01 or later.
+%
+% This work has the LPPL maintenance status `maintained'.
+%
+% The Current Maintainer of this work is Boris Veytsman
+%
+% This work consists of the file issuulinks.dtx and the
+% derived files issuulinks.sty, issuulinks.dtx. 
+%
+% \fi 
+% \CheckSum{83}
+%
+%
+%% \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         \~} 
+%
+% \MakeShortVerb{|}
+%
+%\GetFileInfo{issuulinks.dtx}
+% \title{Produce External Links Instead of Internal
+% Ones\thanks{\copyright Boris Veytsman, 2012}}  
+% \author{Boris Veytsman\thanks{This work was partially supported by
+% The Food and Agriculture Organization of the United Nations}}
+% \date{\filedate, \fileversion}
+% \maketitle
+%
+% \begin{abstract}
+%   A package to change automatic internal links in a document into
+%   external ones in the form
+%   \path{http://issue.com/action/page=PAGENUMBER} as required by
+%   \url{http://issuu.com}.
+% \end{abstract}
+%
+% \tableofcontents
+%
+% \clearpage
+%
+%\section{Introduction}
+%\label{sec:intro}
+%
+% PDF visualizer ISSUU (\url{http://issuu.com}) is a popular service
+% allowing to show PDF documents ``one page a time''.  Due to the way
+% it is implemented, internal links in these documents are not
+% allowed.  Instead, they must be converted to external ones in the
+% form \path{http://issuu.com/action/page?page=PAGENUMBER}.  
+%
+% This package patches \textsf{hyperref} to produce external links in
+% the required form instead of internal links created by |\ref|,
+% |\cite| and other commands.
+%
+% Since the package redefines the internals of \textsf{hyperref}, you
+% need to call it \emph{after} \textsf{hyperref}.
+% 
+% The author is grateful to FAO UN which partially funded this work
+% and to Matthieu Stigler, Adam Prakash \& Filippo Gheri for
+% suggesting and testing this package.
+% 
+%\section{Usage}
+%\label{sec:usage}
+%
+%  To use this package just add |\usepackage{issuulinks}| \emph{after}
+%  calling \textsf{hyperref}.  By default all links will be converted
+%  into the form required by ISSUU.
+%
+% \DescribeMacro{\issuusetup}
+% The command |\issuusetup|\marg{setup commands} might be used to
+% customize the behavior of the package.  At present the only
+% customizable command is |prefix|, that sets the part of the link
+% before |PAGENUMBER|by default 
+% |http://issuu.com/action/page?page=|.  You can change it, for example,
+% \begin{verbatim}
+% \issuusetup{prefix={http://www.issuu.com/action/page?page=}}
+% \end{verbatim}
+%
+% Otherwise the work of the package should be transparent for the
+% user.   
+%
+%\StopEventually{}
+%
+% \clearpage
+% 
+% \section{Implementation}
+% \label{sec:implementation}
+% 
+%
+%\subsection{Algorithm}
+%\label{sec:alg}
+%
+% The idea is following.  Whenever \textsf{hyperref} creates an
+% internal anchor \marg{name}, we write to the aux file the command
+% \cmd{\newISSUUlink}\marg{name}\marg{abspage}, where \marg{abspage}
+% is the absolute page number (as different from the displayed page
+% number).  Then when \textsf{hyperref} creates an internal link to
+% \marg{name}, we substitute this to a call to \url{http://issuu.com}
+% with the corresponding page number. 
+%
+%\subsection{Declarations}
+%\label{sec:decl}
+% 
+%  We start with declaration, who we are:
+%
+% \changes{v1.0}{2012/02/27}{First released version}
+%    \begin{macrocode}
+%<style>\NeedsTeXFormat{LaTeX2e}
+%<*gobble>
+\ProvidesFile{issuulinks.dtx}
+%</gobble>
+%<style>\ProvidesPackage{issuulinks}
+[2012/02/27 v1.0 Links in ISSUU style]
+%    \end{macrocode}
+%
+%    \begin{macrocode}
+%<*gobble>
+\documentclass{ltxdoc}
+\usepackage{hypdoc}
+\usepackage{url}
+\CodelineIndex
+\RecordChanges
+\EnableCrossrefs
+\begin{document}
+  \DocInput{issuulinks.dtx}
+\end{document}
+%</gobble> 
+%<*style>
+%    \end{macrocode}
+%
+%
+%\subsection{Parameters}
+%\label{sec:params}
+%
+% We use \textsf{keyval} to process options:
+%    \begin{macrocode}
+\RequirePackage{xkeyval}
+%    \end{macrocode}
+% 
+% \begin{macro}{\issuusetup}
+%   The shorthand for setting options:
+%    \begin{macrocode}
+\def\issuusetup#1{\setkeys{ISL}{#1}}
+%    \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\ISL@prefix}
+%   The |prefix| macro:
+%    \begin{macrocode}
+\define@key{ISL}{prefix}{\def\ISL@prefix{#1}}
+\issuusetup{prefix={http://issuu.com/action/page?page=}}
+%    \end{macrocode}
+%   
+% \end{macro}
+%
+%
+%\subsection{Working with Aux File}
+%\label{sec:file}
+%
+%
+% \begin{macro}{\newISSUUlink}
+% The page numbers in |\Hy@abspage| start from zero, so we need to
+% increment them:
+%    \begin{macrocode}
+\def\newISSUUlink#1#2{\@tempcnta=#2\relax\advance\@tempcnta by1\relax
+  \expandafter\xdef\csname ISL@link#1\endcsname{\the\@tempcnta}}
+%    \end{macrocode}
+% Someone can use an aux file from the previous run, so we provide a
+% safety valve:
+%    \begin{macrocode}
+\AtBeginDocument{%
+  \if@filesw
+  \immediate\write\@mainaux{\string\providecommand\string\newISSUUlink[2]{}}%
+  \fi}
+%    \end{macrocode}   
+% \end{macro}
+% 
+%
+%
+%\subsection{Writing the Internal Link Information}
+%\label{sec:writing}
+%
+% \begin{macro}{\new@pdflink}
+%   We patch |\new@pdflink| to write its argument into the aux file.
+%   Note that the counter |\Hy@abspage| stores the absolute page
+%   position in \textsl{hyperref}.  We do not prevent writing the
+%   internal anchor in the catalog---probably a waste of time and
+%   bits, but somebody might rely on this for some other
+%   purpose\footnote{Actually I am too lazy to do otherwise\dots}.
+%    \begin{macrocode}
+\let\new@pdflink@ISLorig=\new@pdflink
+\def\new@pdflink#1{%
+  \@bsphack
+  \protected@write\@mainaux{}%
+         {\string\newISSUUlink{#1}{\the\Hy@abspage}}%
+  \@esphack
+  \new@pdflink@ISLorig{#1}}
+%    \end{macrocode}   
+% \end{macro}
+%
+%
+%\subsection{Patching Internal Links}
+%\label{sec:patching}
+% 
+%
+% \begin{macro}{\Hy@StartlinkName}
+%   The standard |\Hy@StartlinkName| is defined like this:
+% \begin{verbatim}
+% \def\Hy@StartlinkName#1#2{%
+%   \pdfstartlink attr{#1}goto name{#2}\relax
+% }
+% \end{verbatim}
+% Here we are patching it.  Note that we can have bad links if we use
+% `old' aux file
+%    \begin{macrocode}
+\def\Hy@StartlinkName#1#2{%
+  \expandafter\ifx\csname ISL@link#2\endcsname\relax
+    \PackageWarning{issuulinks}{The page number for an external link
+      is not defined.  Setting it to 1.  You need to rerun LaTeX to
+      get the page numbers right.}%
+    \expandafter\def\csname ISL@link#2\endcsname{1}\fi
+  \edef\Hy@pstringURI{\ISL@prefix\csname ISL@link#2\endcsname}%
+  \pdfstartlink attr{#1}%
+  user{%
+       /Subtype/Link%
+       \ifHy@pdfa /F 4\fi
+       /A<<%
+         /Type/Action%
+         /S/URI%
+         /URI(\Hy@pstringURI)%
+         \ifHy@href@ismap
+           /IsMap true%
+         \fi
+         \Hy@href@nextactionraw
+       >>%
+      }%
+      \relax
+}
+%    \end{macrocode}
+% 
+%
+%  
+% \end{macro}
+%
+%
+%
+%    \begin{macrocode}
+%</style>
+%    \end{macrocode}
+%\Finale
+%\clearpage
+%
+%\PrintChanges
+%\clearpage
+%\PrintIndex
+%
+\endinput
diff --git a/Master/texmf-dist/source/latex/issuulinks/issuulinks.ins b/Master/texmf-dist/source/latex/issuulinks/issuulinks.ins
new file mode 100644
index 00000000000..796ac004c05
--- /dev/null
+++ b/Master/texmf-dist/source/latex/issuulinks/issuulinks.ins
@@ -0,0 +1,29 @@
+%
+% Doctrip file for issuulinks
+% This file is in public domain
+% $Id: issuulinks.ins,v 1.1 2012-02-23 23:14:53 boris Exp $
+%
+\def\batchfile{issuulinks.ins}
+\input docstrip
+\keepsilent
+\showprogress
+
+
+\askforoverwritefalse
+
+\generate{%
+  \file{issuulinks.sty}{\from{issuulinks.dtx}{style}}}
+
+\obeyspaces
+\Msg{*****************************************************}%
+\Msg{* Congratulations!  You successfully  generated the *}%
+\Msg{* issuulinks package.                               *}%
+\Msg{*                                                   *}%
+\Msg{* Please move the file issuulinks.sty to where      *}%
+\Msg{* LaTeX files are kept in your system.  The  manual *}%
+\Msg{* for the package is in the file issuulinks.pdf.    *}%
+\Msg{*                                                   *}%
+\Msg{* The package is released under LPPL                *}%
+\Msg{*                                                   *}%
+\Msg{* Happy TeXing!                                     *}%
+\Msg{*****************************************************}%
\ No newline at end of file