Debian Codegraph @

texmf-dist/source/latex/issuulinks/issuulinks.dtx

raw
1 % \iffalse
2 % $Id: issuulinks.dtx,v 1.6 2012-03-22 22:54:19 boris Exp $
3 %
4 % Copyright 2012, Boris Veytsman <[email protected]>
5 % This work may be distributed and/or modified under the
6 % conditions of the LaTeX Project Public License, either
7 % version 1.3 of this license or (at your option) any
8 % later version.
9 % The latest version of the license is in
10 % http://www.latex-project.org/lppl.txt
11 % and version 1.3 or later is part of all distributions of
12 % LaTeX version 2003/06/01 or later.
13 %
14 % This work has the LPPL maintenance status `maintained'.
15 %
16 % The Current Maintainer of this work is Boris Veytsman
17 %
18 % This work consists of the file issuulinks.dtx and the
19 % derived files issuulinks.sty, issuulinks.dtx.
20 %
21 % \fi
22 % \CheckSum{106}
23 %
24 %
25 %% \CharacterTable
26 %% {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
27 %% 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
28 %% Digits \0\1\2\3\4\5\6\7\8\9
29 %% Exclamation \! Double quote \" Hash (number) \#
30 %% Dollar \$ Percent \% Ampersand \&
31 %% Acute accent \' Left paren \( Right paren \)
32 %% Asterisk \* Plus \+ Comma \,
33 %% Minus \- Point \. Solidus \/
34 %% Colon \: Semicolon \; Less than \<
35 %% Equals \= Greater than \> Question mark \?
36 %% Commercial at \@ Left bracket \[ Backslash \\
37 %% Right bracket \] Circumflex \^ Underscore \_
38 %% Grave accent \` Left brace \{ Vertical bar \|
39 %% Right brace \} Tilde \~}
40 %
41 % \MakeShortVerb{|}
42 %
43 %\GetFileInfo{issuulinks.dtx}
44 % \title{Produce External Links Instead of Internal
45 % Ones\thanks{\copyright Boris Veytsman, 2012}}
46 % \author{Boris Veytsman\thanks{This work was partially supported by
47 % The Food and Agriculture Organization of the United Nations}}
48 % \date{\filedate, \fileversion}
49 % \maketitle
50 %
51 % \begin{abstract}
52 % A package to change automatic internal links in a document into
53 % external ones in the form
54 % \path{http://issue.com/action/page=PAGENUMBER} as required by
55 % \url{http://issuu.com}.
56 % \end{abstract}
57 %
58 % \tableofcontents
59 %
60 % \clearpage
61 %
62 %\section{Introduction}
63 %\label{sec:intro}
64 %
65 % PDF visualizer ISSUU (\url{http://issuu.com}) is a popular service
66 % allowing to show PDF documents ``one page a time''. Due to the way
67 % it is implemented, internal links in these documents are not
68 % allowed. Instead, they must be converted to external ones in the
69 % form \path{http://issuu.com/action/page?page=PAGENUMBER}.
70 %
71 % This package patches \textsf{hyperref} to produce external links in
72 % the required form instead of internal links created by |\ref|,
73 % |\cite| and other commands.
74 %
75 % Since the package redefines the internals of \textsf{hyperref}, you
76 % need to call it \emph{after} \textsf{hyperref}.
77 %
78 % The author is grateful to FAO UN which partially funded this work
79 % and to Matthieu Stigler, Adam Prakash \& Filippo Gheri for
80 % suggesting and testing this package.
81 %
82 %\section{Usage}
83 %\label{sec:usage}
84 %
85 % To use this package just add |\usepackage{issuulinks}| \emph{after}
86 % calling \textsf{hyperref}. By default all links will be converted
87 % into the form required by ISSUU.
88 %
89 % \DescribeMacro{\issuusetup}
90 % The command |\issuusetup|\marg{setup commands} might be used to
91 % customize the behavior of the package. At present the only
92 % customizable command is |prefix|, that sets the part of the link
93 % before |PAGENUMBER|by default
94 % |http://issuu.com/action/page?page=|. You can change it, for example,
95 % \begin{verbatim}
96 % \issuusetup{prefix={http://www.issuu.com/action/page?page=}}
97 % \end{verbatim}
98 %
99 % Otherwise the work of the package should be transparent for the
100 % user.
101 %
102 %\StopEventually{}
103 %
104 % \clearpage
105 %
106 % \section{Implementation}
107 % \label{sec:implementation}
108 %
109 %
110 %\subsection{Algorithm}
111 %\label{sec:alg}
112 %
113 % The idea is following. Whenever \textsf{hyperref} creates an
114 % internal anchor \marg{name}, we write to the aux file the command
115 % \cmd{\newISSUUlink}\marg{name}\marg{abspage}, where \marg{abspage}
116 % is the absolute page number (as different from the displayed page
117 % number). Then when \textsf{hyperref} creates an internal link to
118 % \marg{name}, we substitute this to a call to \url{http://issuu.com}
119 % with the corresponding page number.
120 %
121 %\subsection{Declarations}
122 %\label{sec:decl}
123 %
124 % We start with declaration, who we are:
125 %
126 % \changes{v1.0}{2012/02/27}{First released version}
127 % \begin{macrocode}
128 %<style>\NeedsTeXFormat{LaTeX2e}
129 %<*gobble>
130 \ProvidesFile{issuulinks.dtx}
131 %</gobble>
132 %<style>\ProvidesPackage{issuulinks}
133 [2012/03/22 v1.1 Links in ISSUU style]
134 % \end{macrocode}
135 %
136 % \begin{macrocode}
137 %<*gobble>
138 \documentclass{ltxdoc}
139 \usepackage{hypdoc}
140 \usepackage{url}
141 \CodelineIndex
142 \RecordChanges
143 \EnableCrossrefs
144 \begin{document}
145 \DocInput{issuulinks.dtx}
146 \end{document}
147 %</gobble>
148 %<*style>
149 % \end{macrocode}
150 %
151 %
152 %\subsection{Parameters}
153 %\label{sec:params}
154 %
155 % We use \textsf{keyval} to process options:
156 % \begin{macrocode}
157 \RequirePackage{xkeyval}
158 % \end{macrocode}
159 %
160 % \begin{macro}{\issuusetup}
161 % The shorthand for setting options:
162 % \begin{macrocode}
163 \def\issuusetup#1{\setkeys{ISL}{#1}}
164 % \end{macrocode}
165 % \end{macro}
166 %
167 % \begin{macro}{\ISL@prefix}
168 % The |prefix| macro:
169 % \begin{macrocode}
170 \define@key{ISL}{prefix}{\def\ISL@prefix{#1}}
171 \issuusetup{prefix={http://issuu.com/action/page?page=}}
172 % \end{macrocode}
173 %
174 % \end{macro}
175 %
176 %
177 %\subsection{Working with Aux File}
178 %\label{sec:file}
179 %
180 %
181 % \begin{macro}{\newISSUUlink}
182 % \changes{v1.1}{2012/03/22}{Added check for undefined/changed references}
183 % The page numbers in |\Hy@abspage| start from zero, so we need to
184 % increment them:
185 % \begin{macrocode}
186 \def\newISSUUlink#1#2{\@tempcnta=#2\relax\advance\@tempcnta by1\relax
187 \expandafter\xdef\csname ISL@link#1\endcsname{\the\@tempcnta}}
188 % \end{macrocode}
189 % Someone can use an aux file from the previous run, so we provide a
190 % safety valve:
191 % \begin{macrocode}
192 \AtBeginDocument{%
193 \if@filesw
194 \immediate\write\@mainaux{\string\providecommand\string\newISSUUlink[2]{}}%
195 \fi}
196 % \end{macrocode}
197 % At the end of document \LaTeX{} checks whether references might
198 % been changed or undefined. Here we plug in into this mechanism:
199 % \begin{macrocode}
200 \AtEndDocument{\let\newISSUUlink\@testISSUUlink}
201 % \end{macrocode}
202 % \end{macro}
203 %
204 % \begin{macro}{\@testISSUUlink}
205 % \changes{v1.1}{2012/03/22}{Added macro}
206 % Test whether this link is defined. If not, set |\@tempswa| to
207 % true---this will cause \LaTeX{} to issue a warning:
208 % \begin{macrocode}
209 \def\@testISSUUlink#1#2{\@tempcnta=#2\relax\advance\@tempcnta by1\relax
210 \edef\reserved@a{\the\@tempcnta}%
211 \expandafter\ifx\csname ISL@link#1\endcsname\reserved@a\else
212 \@tempswatrue
213 \fi}
214 % \end{macrocode}
215 %
216 % \end{macro}
217 %
218 %
219 %
220 %\subsection{Writing the Internal Link Information}
221 %\label{sec:writing}
222 %
223 % \begin{macro}{\new@pdflink}
224 % We patch |\new@pdflink| to write its argument into the aux file.
225 % Note that the counter |\Hy@abspage| stores the absolute page
226 % position in \textsl{hyperref}. We do not prevent writing the
227 % internal anchor in the catalog---probably a waste of time and
228 % bits, but somebody might rely on this for some other
229 % purpose\footnote{Actually I am too lazy to do otherwise\dots}.
230 % \begin{macrocode}
231 \let\new@pdflink@ISLorig=\new@pdflink
232 \def\new@pdflink#1{%
233 \@bsphack
234 \protected@write\@mainaux{}%
235 {\string\newISSUUlink{#1}{\the\Hy@abspage}}%
236 \@esphack
237 \new@pdflink@ISLorig{#1}}
238 % \end{macrocode}
239 % \end{macro}
240 %
241 %
242 %\subsection{Patching Internal Links}
243 %\label{sec:patching}
244 %
245 %
246 % \begin{macro}{\Hy@StartlinkName}
247 % The standard |\Hy@StartlinkName| is defined like this:
248 % \begin{verbatim}
249 % \def\Hy@StartlinkName#1#2{%
250 % \pdfstartlink attr{#1}goto name{#2}\relax
251 % }
252 % \end{verbatim}
253 % Here we are patching it. Note that we can have bad links if we use
254 % `old' aux file
255 % \begin{macrocode}
256 \def\Hy@StartlinkName#1#2{%
257 \expandafter\ifx\csname ISL@link#2\endcsname\relax
258 \PackageWarning{issuulinks}{The page number for an external link
259 is not defined. Setting it to 1. You need to rerun LaTeX to
260 get the page numbers right.}%
261 \expandafter\def\csname ISL@link#2\endcsname{1}\fi
262 \edef\Hy@pstringURI{\ISL@prefix\csname ISL@link#2\endcsname}%
263 \pdfstartlink attr{#1}%
264 user{%
265 /Subtype/Link%
266 \ifHy@pdfa /F 4\fi
267 /A<<%
268 /Type/Action%
269 /S/URI%
270 /URI(\Hy@pstringURI)%
271 \ifHy@href@ismap
272 /IsMap true%
273 \fi
274 \Hy@href@nextactionraw
275 >>%
276 }%
277 \relax
278 }
279 % \end{macrocode}
280 %
281 %
282 %
283 % \end{macro}
284 %
285 %
286 %
287 % \begin{macrocode}
288 %</style>
289 % \end{macrocode}
290 %\Finale
291 %\clearpage
292 %
293 %\PrintChanges
294 %\clearpage
295 %\PrintIndex
296 %
297 \endinput