% \iffalse meta-comment
%
% Copyright (C) 2013 by Scott Pakin <scott+thrcl@pakin.org>
% -------------------------------------------------------
%
% This file may be distributed and/or modified under the
% conditions of the LaTeX Project Public License, either version 1.3c
% 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.3c or later is part of all distributions of LaTeX
% version 2008/05/04 or later.
%
% \fi
%
% \iffalse
%<*driver>
\ProvidesFile{threadcol.dtx}
%</driver>
%<package>\NeedsTeXFormat{LaTeX2e}[1999/12/01]
%<package>\ProvidesPackage{threadcol}
%<*package>
[2013/01/06 v1.0 Convert columns to PDF article threads]
%</package>
%
%<*driver>
\documentclass{ltxdoc}
\usepackage{threadcol}
\usepackage{graphicx}
\usepackage{hyperref}
\EnableCrossrefs
\CodelineIndex
\RecordChanges
\setthreadname{User documentation}
\begin{document}
\sloppy
\DocInput{threadcol.dtx}
\setthreadname{Developer documentation}
% \PrintChanges
\setthreadname{}
\makeatletter
\let\orig@index@prologue=\index@prologue
\def\index@prologue{%
\phantomsection\addcontentsline{toc}{section}{Index}
\orig@index@prologue
}%
\makeatother
\PrintIndex
\end{document}
%</driver>
% \fi
%
% \CheckSum{119}
%
% \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.0}{2013/01/06}{Initial version}
%
% \GetFileInfo{threadcol.dtx}
%
% \DoNotIndex{\@empty,\box,\copy,\def,\else,\fi,\gdef,\global}
% \DoNotIndex{\hss,\ifx,\let}
% \DoNotIndex{\MessageBreak,\newcommand,\protect}
% \DoNotIndex{\setbox,\space,\vbox}
%
% ^^A Define a few helper commands.
% \DeclareRobustCommand{\pkgname}[1]{\mbox{\textsf{#1}}\SortIndex{#1}{\textsf{#1}}}
% \DeclareRobustCommand{\acro}[1]{\textsc{\MakeLowercase{#1}}}
% \DeclareRobustCommand{\menu}[1]{\textit{#1}~$\to$ }
% \DeclareRobustCommand{\menuentry}[1]{\textit{#1}}
% \makeatletter
% \DeclareRobustCommand{\panel}[1]{\textit{#1}}
% \DeclareRobustCommand{\kbd}[1]{\textit{#1}}
% \DeclareRobustCommand{\AAR}{Adobe Acrobat\slash Reader}
%
% ^^A Specify this document's metadata.
% \title{The \textsf{threadcol} package\thanks{This document
% corresponds to \textsf{threadcol}~\fileversion, dated \filedate.}}
% \author{Scott Pakin \\ \texttt{scott+thrcl@pakin.org}}
% \hypersetup{^^A
% pdftitle={The threadcol package},
% pdfauthor={Scott Pakin},
% pdfsubject={Organize document columns into PDF "article threads"},
% pdfkeywords={LaTeX, PDF, article threads, beads, automatic column scrolling}
% }
%
% \maketitle
%
% \section{Introduction}
% \label{sec:introduction}
%
% Consider the following situation: You have a two-column \acro{PDF}
% file that you want to read on your computer (or tablet or whatever).
% Because you have a relatively small screen---and/or less-than-perfect
% eyesight---you zoom in to more easily read the text. You read the
% first column of the first page, then scroll back to the top of the
% page and over to the right to read the second column, then scroll left
% to read the first column of the second page, then scroll up and over
% to read the second column, and so forth. With all this distracting
% scrolling, it's easy to lose track of where you were or what you were
% reading.
%
% The \pkgname{threadcol} package helps you avoid this situation for the
% \LaTeX\ documents you create. It puts every column into a \acro{PDF}
% ``article thread''. A user can then opt to have his \acro{PDF} reader
% automatically scroll through the document in proper reading order. In
% \AAR\ this is accomplished simply by clicking any place in the
% document window where the mouse pointer is shown as a hand with an
% arrow in it. The user can scroll forward by clicking in the document
% window or pressing \kbd{Enter} and backward by shift-clicking or
% pressing \kbd{Shift}+\kbd{Enter}. See the \AAR\ \menuentry{Help}
% documents for more information.
%
% \AAR\ provide an \Acrobatmenu{ArticleThreads}{Articles navigation
% panel} that lists all of the document's article threads and lets the
% user jump to a specified thread. Figure~\ref{fig:articles-ar9} shows
% what the \panel{Articles} panel looks like in Adobe Reader~9 on Linux.
% The panel may have to be displayed explicitly by the user. This can
% be done by right-clicking on the navigation-panel button list and
% selecting \menuentry{Articles}. Alternatively, in \AAR~9, one can
% also follow the \menu{View}\menu{Navigation
% Panels}\menuentry{Articles} menu path or in \AAR~X and~XI the
% \menu{View}\menu{Show/Hide}\menu{Navigation
% Panels}\menuentry{Articles} menu path. If \panel{Articles} appears
% as a pop-up, it can be docked simply by dragging the tab to the
% navigation panel.
%
% \begin{figure}[htbp]
% \centering
% \includegraphics[width=\linewidth]{articles-ar9}
% \caption{The \panel{Articles} button and navigation panel in Adobe Reader~9}
% \label{fig:articles-ar9}
% \end{figure}
%
% I don't know if any \acro{PDF} readers other than Adobe's provide
% special viewing of threads.
%
% \bigskip
%
% Although \pkgname{threadcol} is most beneficial to two-column
% documents, it nevertheless also works with single-column
% documents---and even documents that switch between the two using
% |\onecolumn| and |\twocolumn|. In fact, although it is typeset in a
% single column, this document is itself threaded using
% \pkgname{threadcol}. Section~\ref{sec:implementation}, which presents
% the commented \pkgname{threadcol} source code, lies in a thread
% entitled, ``Developer documentation''.
% Sections~\ref{sec:introduction}--\ref{sec:limitations}
% and~\ref{sec:future-work} lie in a thread entitled, ``User
% documentation''. What this structure implies is that you can
% double-click ``User documentation'' in the
% \Acrobatmenu{ArticleThreads}{Articles navigation panel} then
% repeatedly click (or press \kbd{Enter}) on the document's text to read
% all of the user documentation while automatically skipping the
% developer documentation. Likewise, double-clicking on ``Developer
% documentation'' takes you right to that, bypassing all of the user
% documentation.
%
% Indexes are not normally read from start to finish so this document's
% index is omitted from both the ``User documentation'' and ``Developer
% documentation'' threads.
%
%
% \section{Usage}
% \label{sec:usage}
%
% One of the \pkgname{threadcol} package's goals is simplicity. All you
% have to do is include a
% \begin{verbatim}
\usepackage{threadcol}
% \end{verbatim}
% \unskip\noindent
% in your document's preamble for \pkgname{threadcol} to do its work.
%
% \bigskip
%
% \DescribeMacro{\setthreadname}
% One bit of customization that \pkgname{threadcol} does provide,
% however, is control over the name of the article thread. By default,
% this is ``Entire document''. However, if you prefer a different name,
% you can write |\setthreadname{|\meta{name}|}| to change the name of
% the article thread to \meta{name}. It is in fact permissible to
% invoke |\setthreadname| multiple times and with different names. In
% this case, \pkgname{threadcol} produces one thread per unique name.
% For example, the document shown in Figure~\ref{fig:articles-ar9} used
% two threads in the following manner:
%
% \bigskip
% \begingroup
% \obeylines
% |\setthreadname{Some thread}|
% \meta{Text for the first thread}
% |\setthreadname{Another thread}|
% \meta{Text for the second thread}
% |\setthreadname{Some thread}|
% \meta{More text for the first thread}
% \endgroup
% \bigskip
%
% \noindent
% When the user clicks on the ``Some thread'' thread, navigation
% automatically bypasses all text in the ``Another thread'' thread and
% vice versa. One caveat is that in the current version of
% \pkgname{threadcol}, |\setthreadname| issues a |\clearpage| command to
% ensure that text is assigned to the correct thread. Hence,
% \pkgname{threadcol} cannot currently be used for sophisticated
% magazine- or newspaper-style documents with intertwined threads
% weaving through the pages. Still, it may be useful for coarsely
% divided units of text.
%
% As a special case, specifying an empty thread name
% (i.e.,~|\setthreadname{}|) stops adding text to threads. This can be
% useful for a document's front matter and back matter, which may not
% belong in any thread's normal reading order.
%
%
% \section{Limitations}
% \label{sec:limitations}
%
% \pkgname{threadcol} is a fairly simple package. As such, it has a
% number of limitations, including the following:
%
% \begin{enumerate}
% \item \pkgname{threadcol} requires pdf\LaTeX\ or Lua\LaTeX; it does
% nothing when used with ordinary \LaTeX\ or
% X\lower0.5ex\hbox{\kern-.15em\reflectbox{E}}\kern-0.1667em\LaTeX\@.
% The package also relies on \pkgname{etoolbox}, which requires
% \mbox{$\varepsilon$-\TeX} support, but this is provided by all
% modern \TeX\ distributions.
%
% \item \pkgname{threadcol} is incompatible with the
% \pkgname{fixltx2e} and \pkgname{cuted} packages. These packages
% redefine \LaTeX's text-output routines in a manner that confuses
% \pkgname{threadcol}.
%
% \item Marginal notes (|\marginpar|) are not included in threads.
% The same is true for text that sticks out into the margin
% (e.g.,~using |\llap| or |\rlap|), such as the macro names in
% Section~\ref{sec:implementation}.
%
% \item As mentioned in Section~\ref{sec:usage}, threads currently
% must begin on their own page. Hence, |\setthreadname| forces a
% page break, which is often undesirable.
%
% \item \pkgname{threadcol} does not recognize columns created using
% the |multicols| environment from the \pkgname{multicol} package.
% These appear to \pkgname{threadcol} as a single column.
%
% \item No attempt is made to preserve proper reading order beyond
% page and column order. For example, if a page ends with the first
% part of a sentence and the next page begins with a top float, the
% thread will present the text in that same order: the first part of
% the sentence, then the float, then the second part of the
% sentence. Even worse, \pkgname{threadcol} is oblivious to
% footnotes that span columns; it will show the first column of
% text, including the first part of a long footnote, then the second
% column of text, which ends with the second part of the long
% footnote.
%
% \item The package has not been tested thoroughly. Consequently,
% there are probably many more limitations than those listed above.
% \end{enumerate}
%
%
% \StopEventually{^^A
%
% \setthreadname{User documentation}
%
% \section{Future work}
% \label{sec:future-work}
%
% A future version of \pkgname{threadcol} may address some of the
% limitations described in Section~\ref{sec:limitations}. In addition,
% it would great if the package could integrate seamlessly with the
% \pkgname{flowfram} package, where \acro{PDF} article threads would
% make a lot of sense.
%
% One far more difficult change to implement would be to make
% \pkgname{threadcol} cognizant of the ``true'' reading order, perhaps
% with help from the author. For example, the author could specify the
% point at which the thread should jump to a floating figure before
% jumping back to the corresponding text.
%
% In practice, \LaTeXe's output routines can be quite arcane, especially
% with regards to the handling of inserts (e.g.,~floats and footnotes).
% Getting \pkgname{threadcol} to do more than what it currently does is
% likely beyond my current level of \LaTeX\ expertise.
%
% }
%
% \setthreadname{Developer documentation}
%
% \section{Implementation}
% \label{sec:implementation}
%
% This section is intended for developers and advanced users to learn
% how \pkgname{threadcol} is implemented. Most readers can ignore this
% section.
%
% \bigskip
%
% We begin by loading a few helper packages upon which we rely:
% \pkgname{ifpdf} to ensure that we have access to |\pdfstartthread| and
% |\pdfendthread| and \pkgname{etoolbox} for the |\patchcmd| macro.
% \begin{macrocode}
\RequirePackage{ifpdf}
\RequirePackage{etoolbox}
% \end{macrocode}
%
% \begin{macro}{\thrcl@thread@name}
% Define the name of the current thread. This is what shows up in the
% \Acrobatmenu{ArticleThreads}{\panel{Articles} navigation panel} in
% Adobe Acrobat and Adobe Reader.
% \begin{macrocode}
\def\thrcl@thread@name{Entire document}
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{\setthreadname}
% Let the author change the name of the current thread
% (i.e.,~|\thrcl@thread@name|). The starred version suppresses the
% |\clearpage|.
% \begin{macrocode}
\newcommand*{\setthreadname}{%
\@ifstar{\gdef\thrcl@thread@name}{\clearpage\gdef\thrcl@thread@name}%
}
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{\thrcl@threaded@box}
% This is a copy of the column box but surrounded by |\pdfstartthread|
% and |\pdfendthread|.
% \begin{macrocode}
\newbox\thrcl@threaded@box
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{\thrcl@box}
% Mimic \TeX's |\box| primitive but wrap the given box within a
% |\pdfstartthread| and |\pdfendthread|. If |\thrcl@thread@name| is
% empty, however, invoke |\box| directly.
% \begin{macrocode}
\def\thrcl@box#1{%
\ifx\thrcl@thread@name\@empty
\box#1
\else
\setbox\thrcl@threaded@box=\vbox{%
\pdfstartthread name {\thrcl@thread@name}%
\copy#1
\pdfendthread
}%
\box\thrcl@threaded@box
\fi
}
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{\thrcl@orig@outputpage}
% We want |\thrcl@outputdblcol| to use the original |\@outputpage| but
% all other invocations to use our modified |\@outputpage|.
% \begin{macrocode}
\let\thrcl@orig@outputpage=\@outputpage
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{\thrcl@patchcmd}
% Wrap \pkgname{etoolbox}'s 5-argument |\patchcmd| with a 3-argument
% version that uses hard-wired success and failure operations. The
% whole command is executed only if all of the previous
% |\thrcl@patchcmd| commands succeeded.
% \begin{macrocode}
\def\thrcl@patchcmd#1#2#3{%
\ifx\thrcl@patches@succeeded Y
\patchcmd{#1}{#2}{#3}{}{\let\thrcl@patches@succeeded=N}%
\fi
}
% \end{macrocode}
% \end{macro}
%
% \begin{macro}{\thrcl@outputdblcol}
% \begin{macro}{\thrcl@outputpage}
% \begin{macro}{\thrcl@comdblflelt}
% \begin{macro}{\thrcl@patches@succeeded}
% Replace |\box| with |\thrcl@box| in \LaTeXe's |\@outputdblcol| and
% |\@outputpage| macros, which are used to output a column in,
% respectively, a two-column document or a one-column document. To
% avoid nesting of |\pdfstartthread|\dots\linebreak[0]|\pdfendthread|,
% we replace calls to |\@outputpage| with calls to
% |\thrcl@orig@outputpage| in |\@outputdblcol|.
%
% Because there we need to apply multiple patches, we attempt to patch
% copies of |\@outputdblcol|, |\@outputpage|, and |\@comdblflelt| and
% replace the originals only if all changes are successful. We store
% ``|Y|'' in |\thrcl@patches@succeeded| if this is the case,
% otherwise~``|N|''.
% \begin{macrocode}
\let\thrcl@outputdblcol=\@outputdblcol
\let\thrcl@outputpage=\@outputpage
\let\thrcl@comdblflelt=\@comdblflelt
\let\thrcl@patches@succeeded=Y
\ifpdf
% \end{macrocode}
% We're in \acro{PDF}-generating mode. Apply all of our patches.
% \begin{macrocode}
\thrcl@patchcmd
{\thrcl@outputdblcol}%
{\box\@leftcolumn\hss}%
{\thrcl@box\@leftcolumn\hss}%
\thrcl@patchcmd
{\thrcl@outputdblcol}%
{\box\@outputbox\hss}%
{\thrcl@box\@outputbox\hss}%
\thrcl@patchcmd
{\thrcl@outputdblcol}%
{\@outputpage}%
{\thrcl@orig@outputpage}%
\thrcl@patchcmd
{\thrcl@outputdblcol}%
{\@outputpage}%
{\thrcl@orig@outputpage}%
\thrcl@patchcmd
{\thrcl@outputpage}%
{\box\@outputbox}%
{\thrcl@box\@outputbox}%
\thrcl@patchcmd
{\thrcl@comdblflelt}%
{\box}%
{\thrcl@box}%
\ifx\thrcl@patches@succeeded Y
% \end{macrocode}
% All of our patches succeeded. We can finally redefine
% |\@outputdblcol|, |\@outputpage|, and |\@comdblflelt| for real.
% \begin{macrocode}
\global\let\@outputdblcol=\thrcl@outputdblcol
\global\let\@outputpage=\thrcl@outputpage
\global\let\@comdblflelt=\thrcl@comdblflelt
\else
% \end{macrocode}
% Issue a warning message if any patch failed. This should happen only
% if a class or package redefines |\@outputdblcol|, |\@outputpage|, or
% |\@comdblflelt| in a manner incompatible with \LaTeXe's default
% definition.
% \begin{macrocode}
\PackageError{threadcol}{Failed to patch the output routine}{%
The threadcol package needs to modify LaTeX's
\protect\@outputdblcol\space macro to\MessageBreak
incorporate support for PDF article threads. These
modifications failed,\MessageBreak
presumably due to a class or package that redefined
\protect\@outputdblcol\space in a\MessageBreak
form incompatible with what threadcol expects.%
}%
\fi
\else
% \end{macrocode}
% We're not in \acro{PDF}-generating mode. Warn the author that
% the package will do nothing.
% \begin{macrocode}
\PackageWarningNoLine{threadcol}{%
This package has an effect only when running\MessageBreak
pdfLaTeX or LuaLaTeX and only when in\MessageBreak
PDF-generating mode%
}%
\fi
% \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
%
% \Finale
\endinput