summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/issuulinks/issuulinks.dtx
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2012-02-28 23:47:35 +0000
committerKarl Berry <karl@freefriends.org>2012-02-28 23:47:35 +0000
commitf7da2a17818db423b8221e8e0e3b743e1ff9abca (patch)
treeef3181fb602ef44a8d8c06930dfeeabd61822592 /Master/texmf-dist/source/latex/issuulinks/issuulinks.dtx
parent7e858432b363bfd725a253e408a5363af514ba64 (diff)
new latex package issuulinks (28feb12)
git-svn-id: svn://tug.org/texlive/trunk@25534 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source/latex/issuulinks/issuulinks.dtx')
-rw-r--r--Master/texmf-dist/source/latex/issuulinks/issuulinks.dtx277
1 files changed, 277 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