Debian Codegraph @

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

raw
1 % \iffalse meta-comment
2 %
3 % Copyright (C) 2013 by Scott Pakin <[email protected]>
4 % -------------------------------------------------------
5 %
6 % This file may be distributed and/or modified under the
7 % conditions of the LaTeX Project Public License, either version 1.3c
8 % of this license or (at your option) any later version.
9 % The latest version of this license is in:
10 %
11 % http://www.latex-project.org/lppl.txt
12 %
13 % and version 1.3c or later is part of all distributions of LaTeX
14 % version 2008/05/04 or later.
15 %
16 % \fi
17 %
18 % \iffalse
19 %<*driver>
20 \ProvidesFile{threadcol.dtx}
21 %</driver>
22 %<package>\NeedsTeXFormat{LaTeX2e}[1999/12/01]
23 %<package>\ProvidesPackage{threadcol}
24 %<*package>
25 [2013/01/06 v1.0 Convert columns to PDF article threads]
26 %</package>
27 %
28 %<*driver>
29 \documentclass{ltxdoc}
30 \usepackage{threadcol}
31 \usepackage{graphicx}
32 \usepackage{hyperref}
33 \EnableCrossrefs
34 \CodelineIndex
35 \RecordChanges
36 \setthreadname{User documentation}
37 \begin{document}
38 \sloppy
39 \DocInput{threadcol.dtx}
40 \setthreadname{Developer documentation}
41 % \PrintChanges
42 \setthreadname{}
43 \makeatletter
44 \let\orig@index@prologue=\index@prologue
45 \def\index@prologue{%
46 \phantomsection\addcontentsline{toc}{section}{Index}
47 \orig@index@prologue
48 }%
49 \makeatother
50 \PrintIndex
51 \end{document}
52 %</driver>
53 % \fi
54 %
55 % \CheckSum{119}
56 %
57 % \CharacterTable
58 % {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
59 % 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
60 % Digits \0\1\2\3\4\5\6\7\8\9
61 % Exclamation \! Double quote \" Hash (number) \#
62 % Dollar \$ Percent \% Ampersand \&
63 % Acute accent \' Left paren \( Right paren \)
64 % Asterisk \* Plus \+ Comma \,
65 % Minus \- Point \. Solidus \/
66 % Colon \: Semicolon \; Less than \<
67 % Equals \= Greater than \> Question mark \?
68 % Commercial at \@ Left bracket \[ Backslash \\
69 % Right bracket \] Circumflex \^ Underscore \_
70 % Grave accent \` Left brace \{ Vertical bar \|
71 % Right brace \} Tilde \~}
72 %
73 %
74 % \changes{v1.0}{2013/01/06}{Initial version}
75 %
76 % \GetFileInfo{threadcol.dtx}
77 %
78 % \DoNotIndex{\@empty,\box,\copy,\def,\else,\fi,\gdef,\global}
79 % \DoNotIndex{\hss,\ifx,\let}
80 % \DoNotIndex{\MessageBreak,\newcommand,\protect}
81 % \DoNotIndex{\setbox,\space,\vbox}
82 %
83 % ^^A Define a few helper commands.
84 % \DeclareRobustCommand{\pkgname}[1]{\mbox{\textsf{#1}}\SortIndex{#1}{\textsf{#1}}}
85 % \DeclareRobustCommand{\acro}[1]{\textsc{\MakeLowercase{#1}}}
86 % \DeclareRobustCommand{\menu}[1]{\textit{#1}~$\to$ }
87 % \DeclareRobustCommand{\menuentry}[1]{\textit{#1}}
88 % \makeatletter
89 % \DeclareRobustCommand{\panel}[1]{\textit{#1}}
90 % \DeclareRobustCommand{\kbd}[1]{\textit{#1}}
91 % \DeclareRobustCommand{\AAR}{Adobe Acrobat\slash Reader}
92 %
93 % ^^A Specify this document's metadata.
94 % \title{The \textsf{threadcol} package\thanks{This document
95 % corresponds to \textsf{threadcol}~\fileversion, dated \filedate.}}
96 % \author{Scott Pakin \\ \texttt{[email protected]}}
97 % \hypersetup{^^A
98 % pdftitle={The threadcol package},
99 % pdfauthor={Scott Pakin},
100 % pdfsubject={Organize document columns into PDF "article threads"},
101 % pdfkeywords={LaTeX, PDF, article threads, beads, automatic column scrolling}
102 % }
103 %
104 % \maketitle
105 %
106 % \section{Introduction}
107 % \label{sec:introduction}
108 %
109 % Consider the following situation: You have a two-column \acro{PDF}
110 % file that you want to read on your computer (or tablet or whatever).
111 % Because you have a relatively small screen---and/or less-than-perfect
112 % eyesight---you zoom in to more easily read the text. You read the
113 % first column of the first page, then scroll back to the top of the
114 % page and over to the right to read the second column, then scroll left
115 % to read the first column of the second page, then scroll up and over
116 % to read the second column, and so forth. With all this distracting
117 % scrolling, it's easy to lose track of where you were or what you were
118 % reading.
119 %
120 % The \pkgname{threadcol} package helps you avoid this situation for the
121 % \LaTeX\ documents you create. It puts every column into a \acro{PDF}
122 % ``article thread''. A user can then opt to have his \acro{PDF} reader
123 % automatically scroll through the document in proper reading order. In
124 % \AAR\ this is accomplished simply by clicking any place in the
125 % document window where the mouse pointer is shown as a hand with an
126 % arrow in it. The user can scroll forward by clicking in the document
127 % window or pressing \kbd{Enter} and backward by shift-clicking or
128 % pressing \kbd{Shift}+\kbd{Enter}. See the \AAR\ \menuentry{Help}
129 % documents for more information.
130 %
131 % \AAR\ provide an \Acrobatmenu{ArticleThreads}{Articles navigation
132 % panel} that lists all of the document's article threads and lets the
133 % user jump to a specified thread. Figure~\ref{fig:articles-ar9} shows
134 % what the \panel{Articles} panel looks like in Adobe Reader~9 on Linux.
135 % The panel may have to be displayed explicitly by the user. This can
136 % be done by right-clicking on the navigation-panel button list and
137 % selecting \menuentry{Articles}. Alternatively, in \AAR~9, one can
138 % also follow the \menu{View}\menu{Navigation
139 % Panels}\menuentry{Articles} menu path or in \AAR~X and~XI the
140 % \menu{View}\menu{Show/Hide}\menu{Navigation
141 % Panels}\menuentry{Articles} menu path. If \panel{Articles} appears
142 % as a pop-up, it can be docked simply by dragging the tab to the
143 % navigation panel.
144 %
145 % \begin{figure}[htbp]
146 % \centering
147 % \includegraphics[width=\linewidth]{articles-ar9}
148 % \caption{The \panel{Articles} button and navigation panel in Adobe Reader~9}
149 % \label{fig:articles-ar9}
150 % \end{figure}
151 %
152 % I don't know if any \acro{PDF} readers other than Adobe's provide
153 % special viewing of threads.
154 %
155 % \bigskip
156 %
157 % Although \pkgname{threadcol} is most beneficial to two-column
158 % documents, it nevertheless also works with single-column
159 % documents---and even documents that switch between the two using
160 % |\onecolumn| and |\twocolumn|. In fact, although it is typeset in a
161 % single column, this document is itself threaded using
162 % \pkgname{threadcol}. Section~\ref{sec:implementation}, which presents
163 % the commented \pkgname{threadcol} source code, lies in a thread
164 % entitled, ``Developer documentation''.
165 % Sections~\ref{sec:introduction}--\ref{sec:limitations}
166 % and~\ref{sec:future-work} lie in a thread entitled, ``User
167 % documentation''. What this structure implies is that you can
168 % double-click ``User documentation'' in the
169 % \Acrobatmenu{ArticleThreads}{Articles navigation panel} then
170 % repeatedly click (or press \kbd{Enter}) on the document's text to read
171 % all of the user documentation while automatically skipping the
172 % developer documentation. Likewise, double-clicking on ``Developer
173 % documentation'' takes you right to that, bypassing all of the user
174 % documentation.
175 %
176 % Indexes are not normally read from start to finish so this document's
177 % index is omitted from both the ``User documentation'' and ``Developer
178 % documentation'' threads.
179 %
180 %
181 % \section{Usage}
182 % \label{sec:usage}
183 %
184 % One of the \pkgname{threadcol} package's goals is simplicity. All you
185 % have to do is include a
186 % \begin{verbatim}
187 \usepackage{threadcol}
188 % \end{verbatim}
189 % \unskip\noindent
190 % in your document's preamble for \pkgname{threadcol} to do its work.
191 %
192 % \bigskip
193 %
194 % \DescribeMacro{\setthreadname}
195 % One bit of customization that \pkgname{threadcol} does provide,
196 % however, is control over the name of the article thread. By default,
197 % this is ``Entire document''. However, if you prefer a different name,
198 % you can write |\setthreadname{|\meta{name}|}| to change the name of
199 % the article thread to \meta{name}. It is in fact permissible to
200 % invoke |\setthreadname| multiple times and with different names. In
201 % this case, \pkgname{threadcol} produces one thread per unique name.
202 % For example, the document shown in Figure~\ref{fig:articles-ar9} used
203 % two threads in the following manner:
204 %
205 % \bigskip
206 % \begingroup
207 % \obeylines
208 % |\setthreadname{Some thread}|
209 % \meta{Text for the first thread}
210 % |\setthreadname{Another thread}|
211 % \meta{Text for the second thread}
212 % |\setthreadname{Some thread}|
213 % \meta{More text for the first thread}
214 % \endgroup
215 % \bigskip
216 %
217 % \noindent
218 % When the user clicks on the ``Some thread'' thread, navigation
219 % automatically bypasses all text in the ``Another thread'' thread and
220 % vice versa. One caveat is that in the current version of
221 % \pkgname{threadcol}, |\setthreadname| issues a |\clearpage| command to
222 % ensure that text is assigned to the correct thread. Hence,
223 % \pkgname{threadcol} cannot currently be used for sophisticated
224 % magazine- or newspaper-style documents with intertwined threads
225 % weaving through the pages. Still, it may be useful for coarsely
226 % divided units of text.
227 %
228 % As a special case, specifying an empty thread name
229 % (i.e.,~|\setthreadname{}|) stops adding text to threads. This can be
230 % useful for a document's front matter and back matter, which may not
231 % belong in any thread's normal reading order.
232 %
233 %
234 % \section{Limitations}
235 % \label{sec:limitations}
236 %
237 % \pkgname{threadcol} is a fairly simple package. As such, it has a
238 % number of limitations, including the following:
239 %
240 % \begin{enumerate}
241 % \item \pkgname{threadcol} requires pdf\LaTeX\ or Lua\LaTeX; it does
242 % nothing when used with ordinary \LaTeX\ or
243 % X\lower0.5ex\hbox{\kern-.15em\reflectbox{E}}\kern-0.1667em\LaTeX\@.
244 % The package also relies on \pkgname{etoolbox}, which requires
245 % \mbox{$\varepsilon$-\TeX} support, but this is provided by all
246 % modern \TeX\ distributions.
247 %
248 % \item \pkgname{threadcol} is incompatible with the
249 % \pkgname{fixltx2e} and \pkgname{cuted} packages. These packages
250 % redefine \LaTeX's text-output routines in a manner that confuses
251 % \pkgname{threadcol}.
252 %
253 % \item Marginal notes (|\marginpar|) are not included in threads.
254 % The same is true for text that sticks out into the margin
255 % (e.g.,~using |\llap| or |\rlap|), such as the macro names in
256 % Section~\ref{sec:implementation}.
257 %
258 % \item As mentioned in Section~\ref{sec:usage}, threads currently
259 % must begin on their own page. Hence, |\setthreadname| forces a
260 % page break, which is often undesirable.
261 %
262 % \item \pkgname{threadcol} does not recognize columns created using
263 % the |multicols| environment from the \pkgname{multicol} package.
264 % These appear to \pkgname{threadcol} as a single column.
265 %
266 % \item No attempt is made to preserve proper reading order beyond
267 % page and column order. For example, if a page ends with the first
268 % part of a sentence and the next page begins with a top float, the
269 % thread will present the text in that same order: the first part of
270 % the sentence, then the float, then the second part of the
271 % sentence. Even worse, \pkgname{threadcol} is oblivious to
272 % footnotes that span columns; it will show the first column of
273 % text, including the first part of a long footnote, then the second
274 % column of text, which ends with the second part of the long
275 % footnote.
276 %
277 % \item The package has not been tested thoroughly. Consequently,
278 % there are probably many more limitations than those listed above.
279 % \end{enumerate}
280 %
281 %
282 % \StopEventually{^^A
283 %
284 % \setthreadname{User documentation}
285 %
286 % \section{Future work}
287 % \label{sec:future-work}
288 %
289 % A future version of \pkgname{threadcol} may address some of the
290 % limitations described in Section~\ref{sec:limitations}. In addition,
291 % it would great if the package could integrate seamlessly with the
292 % \pkgname{flowfram} package, where \acro{PDF} article threads would
293 % make a lot of sense.
294 %
295 % One far more difficult change to implement would be to make
296 % \pkgname{threadcol} cognizant of the ``true'' reading order, perhaps
297 % with help from the author. For example, the author could specify the
298 % point at which the thread should jump to a floating figure before
299 % jumping back to the corresponding text.
300 %
301 % In practice, \LaTeXe's output routines can be quite arcane, especially
302 % with regards to the handling of inserts (e.g.,~floats and footnotes).
303 % Getting \pkgname{threadcol} to do more than what it currently does is
304 % likely beyond my current level of \LaTeX\ expertise.
305 %
306 % }
307 %
308 % \setthreadname{Developer documentation}
309 %
310 % \section{Implementation}
311 % \label{sec:implementation}
312 %
313 % This section is intended for developers and advanced users to learn
314 % how \pkgname{threadcol} is implemented. Most readers can ignore this
315 % section.
316 %
317 % \bigskip
318 %
319 % We begin by loading a few helper packages upon which we rely:
320 % \pkgname{ifpdf} to ensure that we have access to |\pdfstartthread| and
321 % |\pdfendthread| and \pkgname{etoolbox} for the |\patchcmd| macro.
322 % \begin{macrocode}
323 \RequirePackage{ifpdf}
324 \RequirePackage{etoolbox}
325 % \end{macrocode}
326 %
327 % \begin{macro}{\thrcl@thread@name}
328 % Define the name of the current thread. This is what shows up in the
329 % \Acrobatmenu{ArticleThreads}{\panel{Articles} navigation panel} in
330 % Adobe Acrobat and Adobe Reader.
331 % \begin{macrocode}
332 \def\thrcl@thread@name{Entire document}
333 % \end{macrocode}
334 % \end{macro}
335 %
336 % \begin{macro}{\setthreadname}
337 % Let the author change the name of the current thread
338 % (i.e.,~|\thrcl@thread@name|). The starred version suppresses the
339 % |\clearpage|.
340 % \begin{macrocode}
341 \newcommand*{\setthreadname}{%
342 \@ifstar{\gdef\thrcl@thread@name}{\clearpage\gdef\thrcl@thread@name}%
343 }
344 % \end{macrocode}
345 % \end{macro}
346 %
347 % \begin{macro}{\thrcl@threaded@box}
348 % This is a copy of the column box but surrounded by |\pdfstartthread|
349 % and |\pdfendthread|.
350 % \begin{macrocode}
351 \newbox\thrcl@threaded@box
352 % \end{macrocode}
353 % \end{macro}
354 %
355 % \begin{macro}{\thrcl@box}
356 % Mimic \TeX's |\box| primitive but wrap the given box within a
357 % |\pdfstartthread| and |\pdfendthread|. If |\thrcl@thread@name| is
358 % empty, however, invoke |\box| directly.
359 % \begin{macrocode}
360 \def\thrcl@box#1{%
361 \ifx\thrcl@thread@name\@empty
362 \box#1
363 \else
364 \setbox\thrcl@threaded@box=\vbox{%
365 \pdfstartthread name {\thrcl@thread@name}%
366 \copy#1
367 \pdfendthread
368 }%
369 \box\thrcl@threaded@box
370 \fi
371 }
372 % \end{macrocode}
373 % \end{macro}
374 %
375 % \begin{macro}{\thrcl@orig@outputpage}
376 % We want |\thrcl@outputdblcol| to use the original |\@outputpage| but
377 % all other invocations to use our modified |\@outputpage|.
378 % \begin{macrocode}
379 \let\thrcl@orig@outputpage=\@outputpage
380 % \end{macrocode}
381 % \end{macro}
382 %
383 % \begin{macro}{\thrcl@patchcmd}
384 % Wrap \pkgname{etoolbox}'s 5-argument |\patchcmd| with a 3-argument
385 % version that uses hard-wired success and failure operations. The
386 % whole command is executed only if all of the previous
387 % |\thrcl@patchcmd| commands succeeded.
388 % \begin{macrocode}
389 \def\thrcl@patchcmd#1#2#3{%
390 \ifx\thrcl@patches@succeeded Y
391 \patchcmd{#1}{#2}{#3}{}{\let\thrcl@patches@succeeded=N}%
392 \fi
393 }
394 % \end{macrocode}
395 % \end{macro}
396 %
397 % \begin{macro}{\thrcl@outputdblcol}
398 % \begin{macro}{\thrcl@outputpage}
399 % \begin{macro}{\thrcl@comdblflelt}
400 % \begin{macro}{\thrcl@patches@succeeded}
401 % Replace |\box| with |\thrcl@box| in \LaTeXe's |\@outputdblcol| and
402 % |\@outputpage| macros, which are used to output a column in,
403 % respectively, a two-column document or a one-column document. To
404 % avoid nesting of |\pdfstartthread|\dots\linebreak[0]|\pdfendthread|,
405 % we replace calls to |\@outputpage| with calls to
406 % |\thrcl@orig@outputpage| in |\@outputdblcol|.
407 %
408 % Because there we need to apply multiple patches, we attempt to patch
409 % copies of |\@outputdblcol|, |\@outputpage|, and |\@comdblflelt| and
410 % replace the originals only if all changes are successful. We store
411 % ``|Y|'' in |\thrcl@patches@succeeded| if this is the case,
412 % otherwise~``|N|''.
413 % \begin{macrocode}
414 \let\thrcl@outputdblcol=\@outputdblcol
415 \let\thrcl@outputpage=\@outputpage
416 \let\thrcl@comdblflelt=\@comdblflelt
417 \let\thrcl@patches@succeeded=Y
418 \ifpdf
419 % \end{macrocode}
420 % We're in \acro{PDF}-generating mode. Apply all of our patches.
421 % \begin{macrocode}
422 \thrcl@patchcmd
423 {\thrcl@outputdblcol}%
424 {\box\@leftcolumn\hss}%
425 {\thrcl@box\@leftcolumn\hss}%
426 \thrcl@patchcmd
427 {\thrcl@outputdblcol}%
428 {\box\@outputbox\hss}%
429 {\thrcl@box\@outputbox\hss}%
430 \thrcl@patchcmd
431 {\thrcl@outputdblcol}%
432 {\@outputpage}%
433 {\thrcl@orig@outputpage}%
434 \thrcl@patchcmd
435 {\thrcl@outputdblcol}%
436 {\@outputpage}%
437 {\thrcl@orig@outputpage}%
438 \thrcl@patchcmd
439 {\thrcl@outputpage}%
440 {\box\@outputbox}%
441 {\thrcl@box\@outputbox}%
442 \thrcl@patchcmd
443 {\thrcl@comdblflelt}%
444 {\box}%
445 {\thrcl@box}%
446 \ifx\thrcl@patches@succeeded Y
447 % \end{macrocode}
448 % All of our patches succeeded. We can finally redefine
449 % |\@outputdblcol|, |\@outputpage|, and |\@comdblflelt| for real.
450 % \begin{macrocode}
451 \global\let\@outputdblcol=\thrcl@outputdblcol
452 \global\let\@outputpage=\thrcl@outputpage
453 \global\let\@comdblflelt=\thrcl@comdblflelt
454 \else
455 % \end{macrocode}
456 % Issue a warning message if any patch failed. This should happen only
457 % if a class or package redefines |\@outputdblcol|, |\@outputpage|, or
458 % |\@comdblflelt| in a manner incompatible with \LaTeXe's default
459 % definition.
460 % \begin{macrocode}
461 \PackageError{threadcol}{Failed to patch the output routine}{%
462 The threadcol package needs to modify LaTeX's
463 \protect\@outputdblcol\space macro to\MessageBreak
464 incorporate support for PDF article threads. These
465 modifications failed,\MessageBreak
466 presumably due to a class or package that redefined
467 \protect\@outputdblcol\space in a\MessageBreak
468 form incompatible with what threadcol expects.%
469 }%
470 \fi
471 \else
472 % \end{macrocode}
473 % We're not in \acro{PDF}-generating mode. Warn the author that
474 % the package will do nothing.
475 % \begin{macrocode}
476 \PackageWarningNoLine{threadcol}{%
477 This package has an effect only when running\MessageBreak
478 pdfLaTeX or LuaLaTeX and only when in\MessageBreak
479 PDF-generating mode%
480 }%
481 \fi
482 % \end{macrocode}
483 % \end{macro}
484 % \end{macro}
485 % \end{macro}
486 % \end{macro}
487 %
488 % \Finale
489 \endinput