summaryrefslogtreecommitdiff
path: root/texmf-dist/doc/latex/artthreads/artthreads_man.tex
blob: a8d7ff659b0b6b8898db3cd38c68552e79f82ee3 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
\documentclass{article}
\usepackage[fleqn]{amsmath}
\usepackage[
    web={centertitlepage,designv,forcolorpaper,tight*,latextoc,pro},
    eforms,aebxmp
]{aeb_pro}
\usepackage{graphicx,array,fancyvrb}
\usepackage{aeb_mlink}
%\usepackage{myriadpro}
%\usepackage{calibri}
\usepackage[altbullet]{lucidbry}

\usepackage[!viewMagWin,!preview]{artthreads}
\usepackage{lipsum,multicol}
\raggedcolumns

%\previewOn\pmpvOn

\makeatletter
\renewenvironment{quote}[1][]
   {\def\@rgi{#1}\ifx\@rgi\@empty
    \let\rghtm\@empty\else\def\rghtm{\rightmargin\leftmargin}\fi
    \list{}{\rghtm} %{\rightmargin\leftmargin}%
    \item\relax}
   {\endlist}
\makeatother
\renewcommand{\hproportionwebtitle}{.8}

%\usepackage{makeidx}
%\makeindex
\usepackage{acroman}
\usepackage[active]{srcltx}

\newcommand{\FmtMP}[2][0pt]{\mbox{}\marginpar{\raisebox{#1}{\parbox{\marginparwidth}{\slshape\raggedleft\small#2}}}}
\addtolength{\marginparwidth}{1in}

\let\uif\textsf

\leftmargini\amtIndent\relax

\urlstyle{tt}

\DeclareDocInfo
{
    university={\AcroTeX.Net},
    title={The \textsf{artthreads} Package
    \texorpdfstring{\\[1ex]\Large}{: }Creating article threads for multi-column documents},
    author={D. P. Story},
    email={dpstory@acrotex.net},
    subject=Documentation for artthreads package,
    talksite={\url{www.acrotex.net}},
    version={1.3.1, 2020/07/09},
    Keywords={LaTeX, article threads, multi-column documents, AcroTeX},
    copyrightStatus=True,
    copyrightNotice={Copyright (C) \the\year, D. P. Story},
    copyrightInfoURL={http://www.acrotex.net}
}

\universityLayout{fontsize=Large}
\titleLayout{fontsize=LARGE}
\authorLayout{fontsize=Large}
\tocLayout{fontsize=Large,color=aeb}
\sectionLayout{indent=-62.5pt,fontsize=large,color=aeb}
\subsectionLayout{indent=-31.25pt,color=aeb}
\subsubsectionLayout{indent=0pt,color=aeb}
\subsubDefaultDing{\texorpdfstring{$\bullet$}{\textrm\textbullet}}

\optionalPageMatter{%
\setThreadInfo{title=Stop!,author=D. P. Story,
    subject=Some early advice,keywords={AeB, PDF, LaTeX}}%
\begin{center}
\fcolorbox{blue}{webyellow}{%\previewOn
\begin{minipage}{.67\linewidth}%
\bArticle{lift=\baselineskip-1pt,shift=-\fboxsep-\fboxrule,width=\linewidth+2\fboxsep+2\fboxrule,height=13\baselineskip+\fboxsep+6pt}%
\textbf{\textcolor{red}{Stop!}} Before you read this documentation, take a
moment to change your preferences: On your menu system of \app{Adobe
Acrobat/Reader}, select
\textsf{Edit\,>\,\penalty0Preferences\,>\,\penalty0General}, and \emph{clear
the checkbox} for the item named \textsf{Make Hand tool select text \&
images}, as listed under \textsf{Basic Tools} on that dialog box.
(\textsf{Ctrl+K} or \textsf{Command+K} is the shortcut to the \textsf{Preferences}
dialog box on \app{Windows} or \app{Mac OS}, respectively.) This makes
reading an article thread much easier. Look for the hand icon with a down
arrow on it.\medskip

Article threads are an \app{Adobe Reader}/\app{Acrobat} feature. To my knowledge, they
have not been implemented in any other PDF viewer. So, a PDF containing article threads
must be viewed in \app{Adobe Reader} or \app{Acrobat}\hfill\dps
\end{minipage}}
\end{center}
}

\def\bART{\placeImage{Art-Start}{10bp}{10bp}}
\def\cART{\placeImage{Art-Down}{10bp}{10bp}}
\def\rART{\placeImage{Art-Up}{10bp}{10bp}}
\def\eART{\placeImage{Art-End}{10bp}{10bp}}
\def\bARTDC{\placeImage{Art-StartDC}{10bp}{10bp}}
\def\cARTDC{\placeImage{Art-DownDC}{10bp}{10bp}}
\def\rARTDC{\placeImage{Art-UpDC}{10bp}{10bp}}
\def\eARTDC{\placeImage{Art-EndDC}{10bp}{10bp}}


\declareMultiImages
{%
    {path=article_icons.pdf,page=0,placement={Art-Start}}
    {path=article_icons.pdf,page=1,placement={Art-Down}}
    {path=article_icons.pdf,page=2,placement={Art-Up}}
    {path=article_icons.pdf,page=3,placement={Art-End}}
% New DC icons
    {path=article_icons.pdf,page=4,placement={Art-StartDC}}
    {path=article_icons.pdf,page=5,placement={Art-DownDC}}
    {path=article_icons.pdf,page=6,placement={Art-UpDC}}
    {path=article_icons.pdf,page=7,placement={Art-EndDC}}
}
%\begin{docassembly}
%\insertPreDocAssembly
%\addWatermarkFromFile({
%    bOnTop:false,
%    cDIPath:"C:/Users/Public/Documents/ManualBGs/Manual_BG_Print_AeB.pdf"
%});
%\executeSave();
%\end{docassembly}

\chngDocObjectTo{\newDO}{doc}
\begin{docassembly}
\insertPreDocAssembly
var titleOfManual="The artthreads Package";
var manualfilename="Manual_BG_Print_artthreads.pdf";
var manualtemplate="Manual_BG_Brown.pdf"; // Blue, Green, Brown
var _pathToBlank="C:/Users/Public/Documents/ManualBGs/"+manualtemplate;
var doc;
var buildIt=false;
if ( buildIt ) {
    console.println("Creating new " + manualfilename + " file.");
    doc = \appopenDoc({cPath: _pathToBlank, bHidden: true});
    var _path=this.path;
    var pos=_path.lastIndexOf("/");
    _path=_path.substring(0,pos)+"/"+manualfilename;
    \docSaveAs\newDO ({ cPath: _path });
    doc.closeDoc();
    doc = \appopenDoc({cPath: manualfilename, oDoc:this, bHidden: true});
    f=doc.getField("ManualTitle");
    f.value=titleOfManual;
    doc.flattenPages();
    \docSaveAs\newDO({ cPath: manualfilename });
    doc.closeDoc();
} else {
    console.println("Using the current "+manualfilename+" file.");
}
var _path=this.path;
var pos=_path.lastIndexOf("/");
_path=_path.substring(0,pos)+"/"+manualfilename;
\addWatermarkFromFile({
    bOnTop:false,
    bOnPrint:false,
    cDIPath:_path
});
\executeSave();
\end{docassembly}

\begin{document}


\maketitle

\selectColors{linkColor=black}
\tableofcontents
\selectColors{linkColor=webgreen}

\setAddToBorder{addtow=5bp,addtoh=0bp}

%\newcommand\showArtPanel[1][Article]{\pushButton[
%    \CA{#1}\A{\Named{ArticleThreads}
%    \Next{/S/Thread /D(\threadTitle)}}]{Btn}{}{11bp}}


\section{Introduction}

\setThreadInfo{title=Introduction,author=D. P. Story,
    subject=Introduction to article threads,keywords={AeB, PDF, LaTeX}}%


%\makebox[0pt][r]{\showArtPanel[Intro]\relax\kern11bp}%
%\showArticlePaneRead
%\showArticlePaneRead[\CA{Intro}]{}{11bp}

\begin{multicols}{2}
\noindent\makebox[0pt][r]{\pushButton[\CA{Intro}\A{\Thread{Introduction}}]{BtnIntro}{}{11bp}\kern11bp}%
\bArticle{lift=\baselineskip,width=\linewidth,height=2.5in}%
\noindent Through the commands of the \pkg{artthreads} package, you can
create \textit{article threads}, a concept/feature of \app{Adobe
Reader/Acrobat} that has been around since the product's beginning. The use
of article threads typically only makes sense in a document in which the text
is in a multi-column format, or, perhaps, a single narrow column.

When a document uses a multiple column format, it is often difficult, or at
the very least inconvenient, to read it. When document page is fit into the viewing
window, the text may be too small to read. This requires the reader, that's
you, to adjust the magnification (zoom) level of the page to fit a column of
text comfortably in the application window.\vadjust{\noindent
\cArticle{lift=2\baselineskip,width=\linewidth,height=2.5in}}
Once the column is fitted, additional navigation is needed to move the window
view down one column, then up to the top of the next column. Think of trying
to read a digital newspaper with many columns. Such navigation is tedious and
distracts from reading the information being presented.

Set the article threads after the composition of the document is completed.
The method of setting the threads is \emph{very visual} not automatic as in
the \pkg{threadcol} package of Scott Patkin.

\end{multicols}

\section{Navigating an article thread}

\setThreadInfo{title=Navigation,author=D. P. Story,
    subject=Navigation to article threads,keywords={AeB, PDF, LaTeX}}%

%\makebox[0pt][r]{\showArtPanel[Navigate]\kern11bp}%
%\showArticlePaneRead[\CA{Navigate}]{}{11bp}

\begin{multicols}{2}
\noindent\makebox[0pt][r]{\pushButton[\CA{Navigate}\A{\Thread{Navigation}}]{BtnNavi}{}{11bp}\kern11bp}%
\bArticle{lift=\baselineskip,width=\linewidth,height=4.2in}%
\noindent Perhaps you've noticed the `Intro' button on exhibit in this
previous section or the `Navigate' button in this section as well. Clicking
these buttons reveals the \mlsetLink[\linktxtcolor{red}\A{\shArticlesPaneActn}]{\kern0pt\sffamily Articles \normalfont panel} in the left-hand navigation
pane. Listed there are all the articles created for this documentation.
Right-clicking on any of the listed article names brings up a context menu;
select \textsf{Read Article} to begin reading or choose \textsf{Properties}
to see the thread info, which (may) include the title, author, subject, and
keywords.

\paragraph*{Begin an article thread.} There are two of ways to begin
reading a thread: (1)~first open the \textsf{Article} pane
(\textsf{View\,\penalty0>\penalty0\,\penalty0Show/Hide\,\penalty0>\,\penalty0Navigation
Panes\,>\,Articles}), left-click an article title and select \textsf{Read
Article}, or simple double-click an article title; or (2) place your mouse
pointer over text, if it changes to a hand with an arrow on it (\bART), the text is
part of an article thread, simply click on it to begin.

\paragraph*{Navigating a thread.} Once you have initiated \textsf{Read
Article}, you can navigate through the article thread using any of the
following methods\vadjust{\noindent
\cArticle{lift=2\baselineskip,width=\linewidth,height=4.2in}}: (1)~click in
an area when the mouse is a hand icon with an arrow on it (\cART) to move forward
(shift-click to move back (\rART)); (2) press the \textsf{Enter} key to move forward
(or shift+\textsf{Enter} to move back); or (3) the page down (or page up)
keys will also move you around within the thread. At the end of the thread, you'll
see this hand icon \eART.

There may be problems in getting the hand icon with the arrow on it to
appear, if this is the case, open the \textsf{Preferences} menu,
\textsf{Edit\,>\,\penalty0Preferences\,>\,\penalty0General}, and \emph{clear
the checkbox} for the item named \textsf{Make Hand tool select text \&
images}, as listed under \textsf{Basic Tools} on that dialog box.
(\textsf{Ctrl+K} or \textsf{Command+K} is the shortcut to the Preferences
dialog box on \app{Windows} and \app{Mac OS}, respectively.)

\paragraph*{Exploring threads.} Now that you have explored the operation of
article threads and see how they work, the next thing to do is to see how
they are created with the \pkg{artthreads} package.
\end{multicols}

It should be noted that in recent versions of \app{DC}, the thread icons are
changed from \bART, \cART, \rART, and {\eART} to \bARTDC, \cARTDC,
\rARTDC, and \eARTDC, respectively.

\section{Creating article threads}

We begin by including the \pkg{artthreads} package in your document.
\begin{Verbatim}[xleftmargin=\amtIndent,commandchars=!()]
\usepackage[!ameta(options)]{artthreads}
\end{Verbatim}
The \pkg{artthreads} package brings in the \pkg{fitr} package
(\url{http://ctan.org/pkg/fitr}), many commands from that package are used.
All options of \pkg{artthreads} are passed to \pkg{fitr}.

\setThreadInfo{title=Package options,author=D. P. Story,
    subject=options of the artthreads package,keywords={AeB, PDF, LaTeX}}%


\paragraph*{Package options.}
The package has ten options: six driver options and four viewing
options.
\begin{multicols}{2}\previewOn\viewMagWinOn
\setAddToBorder{addtow=10bp,addtoh=10bp}
\begin{itemize}
\item \bArticle{lift=\baselineskip,width=\linewidth,height=2.5in}%
    \textbf{Driver Options:} The major driver options are \opt{dvips} (the
    default), \opt{pdftex}, \opt{luatex}, and \opt{xetex}; there are two
    minor driver options, these are \opt{dvipdfm} and \opt{dvipdfmx}. If
    you specify \opt{dvips}, it is assumed the PDF creator is \app{Adobe
    Distiller}.\footnote{You can use \app{dvips\,->\,ps2pdf} if there
    are no document JavaScripts.}

    The \pkg{artthreads} package uses the driver of the \pkg{web} package,
    if it is loaded; otherwise \pkg{artthreads} auto-detects for
    \app{pdflatex}, \app{lualatex} and \app{xelatex}. If no driver is
    passed and no driver is automatically detected, the \app{dvips} driver
    is used.

\setAddToBorder{addtow=0bp,addtoh=0bp}

    \item \cArticle{lift=\baselineskip,width=\linewidth,height=2.5in}%
        \textbf{Viewing Options:} When you specify \texttt{preview}, the
        bounding boxes for the article threads are shown in the
        dvi-previewer (or the PDF document); you can turn off this preview
        by specifying \texttt{!preview} (or removing \texttt{preview}
        entirely from the option list). The other option type is
        \texttt{viewMagWin}. When this option is specified, the viewing window, a
        rectangular region, becomes visible in the dvi-previewer (or in the
        PDF document); specifying \texttt{!viewMagWin} turns off this type
        of preview.

%\item[] The effects of the viewing options will be illustrated later in this
%document, see \autoref{previewEx} on page~\pageref*{previewEx}.
\end{itemize}
\end{multicols}\noindent
You'll notice the two rectangular regions around the left column. The inner
one is made visible by the \texttt{preview} option (or locally by
\cs{previewOn}), you can see that it covers `precisely' the text of the
item. The outer rectangle is exposed by the \texttt{viewMagWin} option (or
locally by \cs{viewMagWinOn}). When you view the thread -- and you do not
define an `extra' border around the viewing area -- the inner rectangle is
used. The text in this inner rectangle may not be entirely adequate for
reading as it is very `tight' around the text. It is for this reason, we
expand the viewing area by a specified amount. Compare the reading comfort of
the left column versus the right column. (Try viewing the column thread with
a narrow application window.)

You may have noticed that the viewer returns to the same page view the page
was in prior to reading the thread.

\paragraph*{The article info.} The specifications for an article thread require
it to have a title, and to optionally have key-values for author, subject, and keywords.
\bVerb\takeMeasure{\string\setThreadInfo\{title=\ameta{text},author=\ameta{text},}%
\begin{dCmd}[commandchars=!()]{\bxSize}
\setThreadInfo{title=!ameta(text),author=!ameta(text),
!qquad(subject=!ameta(text),keywords={!ameta(list)})}
\end{dCmd}
\endgroup\noindent If no value of \texttt{title} is provided, \pkg{artthreads} uses
a generated value of \texttt{thread-\ameta{num}}. The \cs{setThreadInfo}
command must appear prior to the opening the thread (see \cs{bArticle} below)
to which it applies, if it does not, a {\LaTeX} error occurs. The drivers
\opt{dvips} and \opt{xetex} (\opt{dvipdfm}, \opt{dvipdfmx}) support all four
keys; however, \opt{pdftex} and \opt{lualatex} only supports the
\texttt{title} key.

\paragraph*{The article thread commands.} There is one command
(\cs{bArticle}) for beginning an article thread, and another (\cs{cArticle})
to continue that thread.
\bVerb\takeMeasure{\string\bArticle\darg{\meta{KV-pairs}}}%
\begin{dCmd}[commandchars=!()]{\bxSize}
\bArticle{!meta(KV-pairs)}
\cArticle{!meta(KV-pairs)}
\end{dCmd}
\endgroup\noindent Before illustrating \cs{bArticle} and \cs{cArticle}, the
\meta{KV-pairs} are described first.
\begin{itemize}
\item \texttt{width=\ameta{length}}: The value of \opt{width} sets the
    width of the thread to \ameta{length}; \ameta{length} is usually, but
    not always, \cs{linewidth}. Dimension arithmetic is supported with the
    value of \opt{width}; for example, \texttt{width=\cs{linewidth}\,+\,3pt}.

\item \texttt{height=\ameta{length}}: The value of \opt{height} sets the
    height of the thread to \ameta{length}. As with the \opt{width} key,
    dimension arithmetic is supported by \opt{height}; for
    example, \texttt{height=3in\,+\,2\cs{baselineskip}}.

\item \texttt{lift=\ameta{length}}: This key-value lifts (raises) the
    article thread window up (or down) by an amount of \ameta{length}; for
    example, \texttt{lift=15pt} (or \texttt{lift=-15pt}). The default is a
    lift of \texttt{0pt}. Dimension arithmetic is supported.

\item \texttt{shift=\ameta{length}}: The amount of horizontal shift of the
    article thread; positive to the right, negative to the left. For
    example, \texttt{shift=-1in} shifts the button/viewing window 1 inch to
    the left. The default is \texttt{0pt}. Dimension arithmetic is supported.
\end{itemize}
One last command before the examples.

\paragraph*{Setting the expanded (add to) border.} It is often convenient to
set the basic thread dimensions (\texttt{width=\cs{linewidth},height=3in}),
but is harder to expand and position the thread to a wider or higher thread
region. Use the \cs{setAddToBorder} command to expand, or add to, the
dimensions of the thread rectangular dimensions.
\bVerb\takeMeasure{\string\setAddToBorder\darg{addtow=\ameta{length},addtoh=\ameta{length}}}%
\begin{dCmd}[commandchars=!()]{\bxSize}
\setAddToBorder{addtow=!ameta(length),addtoh=!ameta(length)}
\end{dCmd}
\endgroup\noindent The \opt{addtow} key adds \ameta{length} to the left and right
sides of the rectangular boundary of the thread; \opt{addtoh} adds
\ameta{length} to the top and bottom of the rectangular boundary of the
thread. The default dimensions for these two keys are \texttt{0pt}.
\begin{multicols}{2}\setThreadInfo{title=Illustrate \string\\setAddToBorder}%
\noindent\setAddToBorder{addtow=10bp,addtoh=10bp}\previewOn\viewMagWinOn
{\small\verb|\setAddToBorder{addtow=10bp,|\\
\null\quad\verb|addtoh=10bp}|}\\\vadjust{\noindent\bArticle{lift=3\baselineskip,width=\linewidth,height=6\baselineskip}}%
In this column we've set a \texttt{10bp} border around the thread. When you click
on the reading area, the viewer should zoom to the width of the wider rectangle.
\vfill
\columnbreak
\noindent\setAddToBorder{addtow=4bp,addtoh=4bp}\previewOn\viewMagWinOn
{\small\verb|\setAddToBorder{addtow=4bp,|\\
\null\quad\verb|addtoh=4bp}|}\\\vadjust{\noindent\cArticle{lift=3\baselineskip,width=\linewidth,height=6\baselineskip}}%
In this column, we've set a \texttt{4bp} border. Again, when you click on the
reading area, the viewer should zoom to the width of the wider rectangle.
\end{multicols}
\newtopic\noindent\textbf{Tip:} The values of \opt{addtow} and \opt{addtoh} should be in big
points (\texttt{bp}) for greater accuracy as these are converted to
Postscript or PDF dimensions, depending on the driver.

\paragraph*{Methodology with examples.} Now we've come to final part of this
documentation, a description of the methodology, accompanied by examples. As
pointed out early in this documentation, the method for applying the article
threads is very visual. Compose your document content first, and then insert the
document threads.
\begin{center}\previewOn\viewMagWinOn
\begin{minipage}{.8\linewidth}\parindent=20pt\relax
We illustrate the techniques in a single column with a generous width.
First we declare our add to border dimension and article info
\begin{Verbatim}[xleftmargin=\amtIndent,fontsize=\small]
\setAddToBorder{addtow=4bp,addtoh=4bp}
\setThreadInfo{title=Methodology,author=D. P. Story}
\end{Verbatim}
There are two places to begin a thread: (1) at the very beginning of a paragraph;
and (2) from within a paragraph. Method~(1) is preferred. We begin the next paragraph
with
\begin{Verbatim}[xleftmargin=\amtIndent,fontsize=\small]
\noindent\bArticle{lift=\baselineskip,
    width=\linewidth,height=1in+3\baselineskip}%
Now we begin our deep thoughts...
\end{Verbatim}
\end{minipage}
\end{center}
\setAddToBorder{addtow=4bp,addtoh=4bp}
\setThreadInfo{title=Methodology,author=D. P. Story}

\def\pi{\noindent\makebox[0pt][r]{\ding{182}\hskip\marginparsep}}
\def\pii{\noindent\makebox[0pt][r]{\ding{183}\hskip\marginparsep}}
\def\piii{\noindent\makebox[0pt][r]{\ding{184}\hskip\marginparsep}}

\begin{center}\previewOn\viewMagWinOn
\begin{minipage}{.8\linewidth}\parindent=\amtIndent\relax
\newtopic\noindent\bArticle{lift=\baselineskip,width=\linewidth,height=1in+3\baselineskip}%
\pi\indent
Now we begin our deep thoughts. During this development phase, the options
\opt{preview} and \opt{viewMagWin} should be in effect. In a \EXT{DVI}
viewer, we can see the bounding rectangles. We can see it is too low, too long
and so on. For users of \app{pdflatex}, \app{xelatex}, etc., view your
documents in the \EXT{DVI} previewer first (or view them as a \EXT{PDF}).
I've used \texttt{lift=\string\baselineskip} to raise up the thread rectangle
by that mount to enclose the first line. The value of \opt{width} is usually
\cs{linewidth}, but the value of \opt{height} may have to be adjusted, in this
example, I've ``tweaked'' the \texttt{1in} by \texttt{3\string\baselineskip}.
\end{minipage}
\end{center}

\begin{center}\previewOn\viewMagWinOn
\begin{minipage}{.8\linewidth}\parindent=\amtIndent\relax
\newtopic\pii Naturally, after you're satisfied, you then remove
\opt{preview} and \opt{viewMagWin} or change them to
\opt{!preview} and \opt{!viewMagWin}. Another possible location is from within
a paragraph, here, we continue the previous thread using the \cs{cArticle} command
in conjunction with the \cs{vadjust} {\TeX} primitive\vadjust{\noindent
\cArticle{lift=5\baselineskip,width=\linewidth,height=2in+\baselineskip}}.
Between the end of the word `primitive' and the period (.) ending the sentence, I've placed,
\begin{Verbatim}[fontsize=\small]
primitive\vadjust{\noindent\cArticle{lift=5\baselineskip,
    width=\linewidth,height=2in+\baselineskip}}. Between the
\end{Verbatim}
We chose \texttt{lift=5\string\baselineskip} because the
original positioning of the thread rectangle was too low by about five lines.
The value of \texttt{height} was chosen to cover the paragraph once the
complete paragraph was composed.
\end{minipage}
\end{center}

\previewOff\viewMagWinOff
\begin{center}
\begin{minipage}{.8\linewidth}\parindent=20pt\relax
We now declare \verb|\previewOff\viewMagWinOff|.

\noindent\piii\cArticle{lift=\baselineskip,width=\linewidth,height=.5in+3\baselineskip}\indent
Of course, in this example, it was entirely unnecessary to insert the
\cs{cArticle} mid-paragraph, it would have been better placed at the
beginning of the paragraph. Placing \cs{cArticle} mid-paragraph is useful for
multi-column formats. When the paragraph flows from the first column the
second column, use the \cs{vadjust} technique to cover the portion of the
text that flows to the right column.
\end{minipage}
\end{center}
By the way, notice the use of \cs{noindent}, this is
oftentimes needed to position the article thread in the left margin of the
text block.

\paragraph*{Continuing a thread from one page to the next.} To continue
reading across a page boundary, continue the thread on the previous page
using \cs{cArticle}. For example, the most recent thread begins with
paragraph~\ding{182} (\cs{bArticle}) and continues with paragraph~\ding{183}
and~\ding{184} (\cs{cArticle}). Paragraphs~\ding{182} and~\ding{183} are on
the previous page, while paragraph~\ding{184} is on this page. As you read
this thread, paragraph~\ding{182} is presented first, followed by
paragraph~\ding{183}, and finally, paragraph~\ding{185} on the subsequent
page.

\paragraph*{The demo files.} The demo file \texttt{article\_tech.tex}
reproduces the discussion on methods, it is found in the \texttt{examples}
folder.

\setThreadInfo{title=Final Thread,{author=D. P. Story, Ph.D.}}

\newtopic\noindent In this documentation, I've covered the content with many article threads; normally,
for multi-column content, one thread per column is sufficient. The thread for this article continues
on to the next page, as this Lipsum text illustrates.
\begin{multicols}{2} %\previewOn
\noindent\bArticle{lift=\baselineskip,width=\linewidth,height=4.1in-\baselineskip}\relax
\lipsum[2]

\lipsum[4]

\noindent\cArticle{lift=4\baselineskip,width=\linewidth,height=4.1in-\baselineskip}\indent
\lipsum[6]

\lipsum[7]

\noindent\cArticle{lift=11\baselineskip,width=\linewidth,height=6.25in+\baselineskip}\indent
\lipsum[10]

\lipsum[12]

\noindent\cArticle{lift=2\baselineskip,width=\linewidth,height=6.25in+\baselineskip}\indent
\lipsum[14]

\lipsum[16]

\end{multicols}

\paragraph*{The demo file.} The demo file for this package is \texttt{article\_tst.tex},
available in the \texttt{examples} folder.

\section{Other navigation commands}

There are several commands for creating links or push button actions that
open the \uif{Articles} pane and/or begin reading a specified article.

\paragraph*{Manipulating the \uif{Articles} pane.} The following two commands represent
actions that toggle the \uif{Articles} pane (\cs{shArticlesPaneActn}) or just open/show the \uif{Articles} pane (\cs{sArticlesPaneActn}).
\bVerb\takeMeasure{\string\shArticlesPaneReadActn}%
\setlength{\dimen0}{\bxSize}%
\def\1{\rlap{\hskip\dimen0\relax\sffamily(Toggle Articles pane action)}}
\def\2{\rlap{\hskip\dimen0\relax\sffamily(Show Articles pane action)}}
\def\3{\rlap{\hskip\dimen0\relax\sffamily(Toggle Articles pane and read article action)}}
\def\4{\rlap{\hskip\dimen0\relax\sffamily(Show Articles pane and read article action)}}
\begin{dCmd}[commandchars=!()]{\bxSize}
!1\shArticlesPaneActn
!2\sArticlesPaneActn
!3\shArticlesPaneReadActn
!4\sArticlesPaneReadActn
\end{dCmd}
\eVerb For example,
\begin{quote}
    \setLink[\A{\shArticlesPaneActn}]{Toggle \uif{Articles} pane}\\
    \verb!\setLink[\A{\shArticlesPaneActn}]{Toggle \textsf{Articles} pane}!\\[3pt]
    \setLink[\A{\sArticlesPaneActn}]{Show \uif{Articles} pane}\\
    \verb!\setLink[\A{\sArticlesPaneActn}]{Show \textsf{Articles} pane}!
\end{quote}
These two actions can be used by push buttons as well.

\paragraph*{Reading a thread.} To create an action to read a thread with a title of \ameta{thread-title},
use \cs{Thread\darg{\ameta{thread-title}}}. For example,
\begin{quote}
    Read about the \setLink[\A{\Thread{Package options}}]{Package options}.\\
    \verb~\setLink[\A{\Thread{Package options}}]{Package options}.~
\end{quote}
Again notice that the viewer returns you to the jumping off point after
you've finished reading the thread. The \cs{Thread\darg{\ameta{thread-title}}}
action can be part of a push button action as well.

\paragraph*{Some push buttons.} \pkg{artthreads} has some push buttons with common actions,
these are,
\bVerb\takeMeasure{\string\toggleArticlePaneRead[\ameta{KV-pairs}]\darg{\ameta{wd}}\darg{\ameta{ht}}}%
\begin{dCmd}[commandchars=!()]{\bxSize}
\toggleArticlePane[!ameta(KV-pairs)]{!ameta(wd)}{!ameta(ht)}
\toggleArticlePaneRead[!ameta(KV-pairs)]{!ameta(wd)}{!ameta(ht)}
\showArticlePane[!ameta(KV-pairs)]{!ameta(wd)}{!ameta(ht)}
\showArticlePaneRead[!ameta(KV-pairs)]{!ameta(wd)}{!ameta(ht)}
\end{dCmd}
\eVerb The names of the commands describe the action they perform. However,
the commands \cs{toggleArticlePaneRead} and \cs{showArticlePaneRead} require special comment.
Each begins an article thread, but which article thread?
\begin{quote}%\previewOn\pmpvOn
    \showArticlePaneRead{}{11bp}\\[2bp]
    \verb!\showArticlePaneRead{}{11bp}!
\end{quote}
Without any further qualifiers, this button begins reading the thread as
determined by the value of the \texttt{title} key of the last
\cs{setThreadInfo} command declared. So, the above push button should begin
the thread titled ``\threadTitle''. However, to program the button to begin
reading the thread titled \ameta{thread-title}, use the following syntax:
\begin{Verbatim}[xleftmargin=\amtIndent,commandchars=!()]
\showArticlePaneRead[!textbf(\cmd{\readArticle{!ameta(thread-title)}})]{}{11bp}
\end{Verbatim}
We illustrate by using \cs{showArticlePaneRead} to read the thread with title
``Package options,'' and the same action in a link.
\begin{quote} %\previewOn\pmpvOn
    \showArticlePaneRead[\cmd{\readArticle{Package options}}]{}{11bp}\\[2bp]
    \verb~\showArticlePaneRead[\cmd{\readArticle{Package options}}]{}{11bp}~\\[4bp]
    \setLink[\cmd{\readArticle{Package options}}\A{\sArticlesPaneReadActn}]{Show \textsf{Articles} pane and read the Package options article}\\[2bp]
    \verb~\setLink[\cmd{\readArticle{Package options}}~\\
    \null\quad\verb~\A{\sArticlesPaneReadActn}]{Show \textsf{Articles} pane~\\
    \null\quad\verb~and read the Package options article}~
\end{quote}

\subparagraph*{Tooltips for push buttons.} The tooltips for the commands
\cs{toggleArticlePane} and \cs{showArticlePane} are \textsf{Toggle Articles
Pane} and \textsf{Show Articles Pane}, respectively. These can be localized
using the \cs{TU} key if \pkg{eforms}; for example,
\begin{Verbatim}[xleftmargin=\amtIndent,fontsize=\small,commandchars={|()}]
\showArticlePane[|textbf(\TU{Umschalten der Artikel Schaltfl\"{a}che})]{}{11bp}
\end{Verbatim}
which may be German for \textsf{Toggle Articles Pane}.

For the other two, \cs{toggleArticlePaneRead} and \cs{showArticlePaneRead}, two convenience
commands are defined.
\bVerb\takeMeasure{\string\tooltipTogglePaneRead\darg{\ameta{text}}}%
\begin{dCmd}[commandchars=!()]{\bxSize}
\tooltipTogglePaneRead{!ameta(text)}
\tooltipShowPaneRead{!ameta(text)}}
\end{dCmd}
\eVerb The values of \ameta{text} allows for the inclusion of the command
\cs{threadTitle}, which expands to the current title of the thread article.
The default definitions are,
\begin{Verbatim}[xleftmargin=\amtIndent]
\tooltipTogglePaneRead{Toggle Articles pane and
  read the article \threadTitle}
\tooltipShowPaneRead{Show Articles pane and
  read the article \threadTitle}
\end{Verbatim}
If you roll over the button at the top of the this page, its tooltip will read \textsf{Show Articles pane and
  read the article Package options}. The two commands may be declare with an appropriate language localization.

\setThreadInfo{%
    title=J\"{u}rgen's Thread,
    author={D. P. Story, J\"{u}rgen},
    subject=Discussion of the PDFDocEncloding Character Set,
    keywords={AeB, PDF, LaTeX}
}

%\previewOn
\noindent\bArticle{lift=-\medskipamount-4pt,width=\linewidth,height=5\baselineskip+6pt}%
\paragraph*{Beyond Basic ASCII.} Begin by reading \setLink[\cmd{\readArticle{J\"{u}rgen's Thread}}\linktxtcolor{red}\A{\Thread{\threadTitle}}]{J\"{u}rgen's Thread}.
The examples of this reference and, for the most part in the sample
files, use Basic ASCII as the thread titles; however, the full PDFDocEncoding
character set is also supported. The sample file \texttt{article\_tech.tex}
provides a more complete discussion of this topic, as well as a more
complicated example. Check out the
\setLink[\linktxtcolor{red}\A{\sArticlesPaneActn}]{\textsf{Articles}} pane to
see the title of this thread listed.

\section{My retirement}

Now, I simply must get back to it. \dps

\end{document}