path: root/Master/texmf-dist/source/latex/issuulinks/issuulinks.dtx

% \iffalse
% $Id: issuulinks.dtx,v 1.6 2012-03-22 22:54:19 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{106}
%
%
%% \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/03/22 v1.1 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}
% \changes{v1.1}{2012/03/22}{Added check for undefined/changed references} 
% 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}   
% At the end of document \LaTeX{} checks whether references might
% been changed or undefined.  Here we plug in into this mechanism:
%    \begin{macrocode}
\AtEndDocument{\let\newISSUUlink\@testISSUUlink}
%    \end{macrocode}
% \end{macro}
% 
% \begin{macro}{\@testISSUUlink}
% \changes{v1.1}{2012/03/22}{Added macro} 
%   Test whether this link is defined.  If not, set |\@tempswa| to
%   true---this will cause \LaTeX{} to issue a warning:
%    \begin{macrocode}
\def\@testISSUUlink#1#2{\@tempcnta=#2\relax\advance\@tempcnta by1\relax
  \edef\reserved@a{\the\@tempcnta}%
  \expandafter\ifx\csname ISL@link#1\endcsname\reserved@a\else
     \@tempswatrue
  \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