summaryrefslogtreecommitdiff
path: root/texmf-dist/source/latex/artthreads/artthreads.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'texmf-dist/source/latex/artthreads/artthreads.dtx')
-rw-r--r--texmf-dist/source/latex/artthreads/artthreads.dtx390
1 files changed, 390 insertions, 0 deletions
diff --git a/texmf-dist/source/latex/artthreads/artthreads.dtx b/texmf-dist/source/latex/artthreads/artthreads.dtx
new file mode 100644
index 00000000..3eda0771
--- /dev/null
+++ b/texmf-dist/source/latex/artthreads/artthreads.dtx
@@ -0,0 +1,390 @@
+%\iffalse
+%<*copyright>
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%% artthreads.sty package, 2016-04-09 %%
+%% Copyright (C) 2016 D. P. Story %%
+%% dpstory@uakron.edu %%
+%% %%
+%% This program can redistributed and/or modified under %%
+%% the terms of the LaTeX Project Public License %%
+%% Distributed from CTAN archives in directory %%
+%% macros/latex/base/lppl.txt; either version 1 of the %%
+%% License, or (at your option) any later version. %%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%</copyright>
+%<package>\NeedsTeXFormat{LaTeX2e}[1997/12/01]
+%<package>\ProvidesPackage{artthreads}
+%<package> [2016/04/09 v1.1 Support for article threads (dps)]
+%<*driver>
+\documentclass{ltxdoc}
+\usepackage[colorlinks,hyperindex]{hyperref}
+\usepackage{fancyvrb,array,calc}
+%\pdfstringdefDisableCommands{\let\\\textbackslash}
+%\EnableCrossrefs \CodelineIndex
+\RecordChanges
+\bgroup\ttfamily
+\gdef\brpr#1{\char123\relax#1\char125\relax}\egroup
+\def\ameta#1{\ensuremath{\langle\textsl{\texttt{#1}}\rangle}}
+\def\meta#1{\textsl{\texttt{#1}}}
+\def\SUB#1{\ensuremath{{}_{\mbox{\scriptsize\ttfamily#1}}}}
+\def\cs#1{\texttt{\bslash#1}}
+\DeclareRobustCommand{\tmspace}[3]{%
+ \ifmmode\mskip#1#2\else\kern#1#3\fi\relax}
+\renewcommand{\,}{\tmspace+\thinmuskip{.1667em}}
+\let\thinspace\,
+\renewcommand{\!}{\tmspace-\thinmuskip{.1667em}}
+\let\negthinspace\!
+\renewcommand{\:}{\tmspace+\medmuskip{.2222em}}
+\let\medspace\:
+\newcommand{\negmedspace}{\tmspace-\medmuskip{.2222em}}
+\renewcommand{\;}{\tmspace+\thickmuskip{.2777em}}
+\let\thickspace\;
+\newcommand{\negthickspace}{\tmspace-\thickmuskip{.2777em}}
+\makeatletter
+\renewcommand{\paragraph}
+ {\@startsection{paragraph}{4}{0pt}{6pt}{-3pt}
+ {\normalfont\normalsize\bfseries}}
+\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
+\begin{document}
+\def\CMD#1{\textbackslash#1}
+ \GetFileInfo{artthreads.sty}
+ \title{\textsf{artthreads}: Support for article threads}
+ \author{D. P. Story\\
+ Email: \texttt{dpstory@acrotex.net}}
+ \date{processed \today}
+ \maketitle
+ \tableofcontents
+ \let\Email\texttt
+ \renewenvironment{theglossary}{%
+ \let\efill\relax
+ \begin{itemize}}{\end{itemize}}
+ \value{GlossaryColumns}=1
+ \DocInput{artthreads.dtx}
+ \PrintIndex
+\end{document}
+%</driver>
+% \fi
+% \MakeShortVerb{|}
+% \StopEventually{}
+%
+% \DoNotIndex{\def,\edef,\gdef,\xdef,\global,\long,\let}
+% \DoNotIndex{\expandafter,\string,\the,\ifx,\else,\fi}
+% \DoNotIndex{\csname,\endcsname,\relax,\begingroup,\endgroup}
+% \DoNotIndex{\DeclareTextCommand,\DeclareTextCompositeCommand}
+% \DoNotIndex{\space,\@empty,\special}
+%
+% \begin{macrocode}
+%<*package>
+% \end{macrocode}
+%
+% \section{Introduction}
+% This package is used to create \textit{article threads} around blocks of content. Generally,
+% article threads are used with multi-column documents, such as newspapers or newsletters, or
+% anything that uses a multi-column format.
+%
+% The creation of the article threads should occur as the final step of the document composition.
+% There is nothing automatic about placing the threads, {\TeX} does not lend itself to the creation
+% of the threads. For the purpose of placing the threads, the options \texttt{preview} and
+% \texttt{viewMagWin} are integral.
+%
+% \section{Options and Required Packages}
+% \begin{macrocode}
+\RequirePackage{xkeyval}
+\RequirePackage{ifpdf}[2006/02/20]
+\RequirePackage{ifxetex}[2006/08/21]
+\@ifundefined{ifpdfmarkup}{\newif\ifpdfmarkup}{}\pdfmarkupfalse
+\ifpdf\else\ifxetex\else\pdfmarkuptrue\fi\fi
+% \end{macrocode}
+% \paragraph*{Driver options.} Three options, \DescribeMacro{dvips,dvipsone}\texttt{dvips} (the default)
+% and \texttt{dvipsone}, both of which require \textbf{Adobe Distiller}
+% as the PDF creator; the \DescribeMacro{pdftex}\texttt{pdftex} allows for the same functionality
+% for the \textsf{pdflatex} executable. We also support \DescribeMacro{xetex,dvipdfm,dvipdfmx}\texttt{dvipdfm}
+% and its extensions.
+%
+% \paragraph*{Preview options.} The \DescribeMacro{preview}\texttt{preview}
+% option is a carry over from \textsf{eforms}. When selected, all form fields are outlined; useful when
+% setting the location of fields in a dvi previewer. The other option is \texttt{viewMagWin}
+% \DescribeMacro{viewMagWin} will show the viewing windows surrounding the target. This is the rectangle
+% that will be jumped to. Use this option to adjust the size of the window to your needs.
+% When either of the last two options has an exclamation point prior, that means to
+% turn off the switch. You can conveniently use \texttt{viewMagWin} to see the viewing window,
+% then change it to \DescribeMacro{!viewMagWin}\texttt{!viewMagWin} to remove the visible window. Cool.
+% Similarly, you can turn off \texttt{preview} using \DescribeMacro{!preview}\texttt{!preview}.
+% \begin{macrocode}
+% \end{macrocode}
+% All options are passed to the \textsf{fitr} package, which contains a lot of the code
+% used in this package.
+% \begin{macrocode}
+\DeclareOptionX{pdftex}{\PassOptionsToPackage{\CurrentOption}{fitr}}
+% \end{macrocode}
+% Distiller based drivers.
+% \begin{macrocode}
+\DeclareOptionX{dvips}{\PassOptionsToPackage{\CurrentOption}{fitr}}
+\DeclareOptionX{dvipsone}{\PassOptionsToPackage{\CurrentOption}{fitr}}
+% \end{macrocode}
+% \textsf{dvipdfm} and its variants.
+% \begin{macrocode}
+\DeclareOptionX{dvipdfm}{\PassOptionsToPackage{\CurrentOption}{fitr}}
+\DeclareOptionX{dvipdfmx}{\PassOptionsToPackage{\CurrentOption}{fitr}}
+\DeclareOptionX{xetex}{\PassOptionsToPackage{\CurrentOption}{fitr}}
+% \end{macrocode}
+% \begin{macrocode}
+\DeclareOptionX{preview}{\PassOptionsToPackage{\CurrentOption}{fitr}}
+\DeclareOptionX{!preview}{\PassOptionsToPackage{\CurrentOption}{fitr}}
+\DeclareOptionX{viewMagWin}{\PassOptionsToPackage{\CurrentOption}{fitr}}
+\DeclareOptionX{!viewMagWin}
+ {\PassOptionsToPackage{\CurrentOption}{fitr}}
+\ProcessOptionsX
+% \end{macrocode}
+% \section{The Main Code}
+% We require the package \textsf{fitr}, as we use many commands from that package.
+% We pass all options to \textsf{fitr}.
+% \begin{macrocode}
+\RequirePackage{fitr}[2016/04/04]
+% \end{macrocode}
+% Some scratch counters, lengths, boxes.
+% \begin{macrocode}
+\newif\ifnewarticle
+\newcounter{artthrdcnt}
+\def\CntArt{0}\def\CntArtInfo{0}
+\def\inc@CntMacro#1{{\@tempcnta#1\relax\advance\@tempcnta1\relax
+ \xdef#1{\the\@tempcnta}}}
+\def\artM@rk{[\space}
+% \end{macrocode}
+% \paragraph*{Key-values for \cs{setThreadInfo}} We set up
+% key-values\DescribeMacro{title}\DescribeMacro{author}\DescribeMacro{subject}^^A
+% \DescribeMacro{keywords} for the thread \textsf{Info} dictionary. Only the title
+% is required, that's why a default value of \texttt{thread-<num>} is otherwise provided.
+% \begin{macrocode}
+\define@key{artthrd}{title}[]{\def\threadTitle{#1}}
+ \let\threadTitle\@empty
+\define@key{artthrd}{author}[]{\def\threadAuthor{#1}}
+ \let\threadAuthor\@empty
+\define@key{artthrd}{keywords}[]{\def\threadKeywords{#1}}
+ \let\threadKeywords\@empty
+\define@key{artthrd}{subject}[]{\def\threadSubject{#1}}
+ \let\threadSubject\@empty
+% \end{macrocode}
+% Use \DescribeMacro{\setThreadInfo}\cmd{\setThreadInfo} prior to the opening of a
+% new thread using \cs{cArticle}. Through its key-values, set the title, author,
+% keywords, and subject of the thread. For \textsf{pdftex}, only title is supported.
+% \begin{macrocode}
+\newcommand{\setThreadInfo}[1]{\inc@CntMacro\CntArtInfo
+ \let\threadTitle\@empty\let\threadAuthor\@empty
+ \let\threadKeywords\@empty\let\threadSubject\@empty
+ \setkeys{artthrd}{#1}\ifx\threadTitle\@empty
+ \def\threadTitle{thread-\CntArtInfo}\fi
+}
+\def\bArtErrMsg{When starting a new article thread
+ (\string\cArticle)\MessageBreak
+ first use \string\setThreadInfo\space to set the title,\MessageBreak
+ author, subject, and keywords}
+% \end{macrocode}
+% \paragraph*{Additional key-values for threads} In addition to the key-values provided
+% by \textsf{fitr}, we provide a few more. The two keys
+% \DescribeMacro{addtow}\texttt{addtow} and \DescribeMacro{addtoh}\texttt{addtoh}
+% adds to the reading border of the threads. These are set through the
+% command \DescribeMacro{\setAddToBorder}\cs{setAddToBorder}. For the most part,
+% choices for \texttt{addtow} (add to the width) and \texttt{addtoh} (add to the height)
+% should be set for the whole document. Initially, \texttt{addtow=0,addtoh=0}.
+% \begin{macrocode}
+\define@key{@rtthrd}{addtow}[0]{%
+ \fitr@defaultbp{\artthrd@@addtow}{#1}}
+\def\artthrd@@addtow{0}
+\define@key{@rtthrd}{addtoh}[0]{%
+ \fitr@defaultbp{\artthrd@@addtoh}{#1}}
+\def\artthrd@@addtoh{0}
+\newcommand{\setAddToBorder}[1]{\setkeys{@rtthrd}{#1}}
+% \end{macrocode}
+% The \DescribeMacro{\bArticle}\cmd{\bArticle} is used to start an article thread. The thread
+% may continue with \cs{cArticle}. Both commands have a required argument, consisting of
+% key-values defined by \textsf{fitr}.
+% The following is the syntax, with appropriate keys defined in \texttt{fitr}.
+% \begin{quote}\ttfamily
+% \string\cArticle\char123lift=\ameta{length},width=\ameta{length},height=\ameta{length}\char125
+% \end{quote}
+% \begin{macrocode}
+\newcommand{\bArticle}{\begingroup\inc@CntMacro\CntArt
+ \ifnum\CntArt=\CntArtInfo\relax\else
+ \PackageError{artthreads}{\bArtErrMsg}{See package documentation
+ for \string\setThreadInfo}\fi
+ \newarticletrue\set@rectart
+}
+% \end{macrocode}
+% The only difference between \DescribeMacro{\cArticle}\cmd{\cArticle} and
+% \cmd{\bArticle} is the stepping of the counter \cmd{\CntArt}
+% and the setting of the switch \cmd{ifnewarticle}.
+% \begin{macrocode}
+\newcommand{\cArticle}{\begingroup\newarticlefalse\set@rectart}
+% \end{macrocode}
+% \cmd{\set@rectart} continues \cs{bArticle}/\cs{cArticle}.
+% \begin{macrocode}
+\newcommand{\set@rectart}[1]{\def\fitr@artrect@argi{#1}%
+ \edef\temp@exp{\noexpand\setkeys{fitr}{#1}}\temp@exp
+ \set@@rectart}
+% \end{macrocode}
+% \cmd{\set@@rectart} is the main command for building the thread.
+% \begin{macrocode}
+\def\set@@rectart{\def\fitr@setBL{0pt}%
+ \@ifundefined{ef@Bbox}{\let\fitr@FLB@ction\Bbox}%
+ {\let\fitr@FLB@ction\ef@Bbox}%
+ \get@fitr@dimen{%
+ \parbox[\fitr@@refPt][\fitr@@height]{\fitr@@width}%
+ {\kern0pt\fitr@FLB@ction{\fitr@@width}{\fitr@@height}\kern0pt}%
+ }%
+ \makebox[0pt][l]{\hspace*{\fitr@@shift}\smash{%
+ \raisebox{\fitr@@lift-\fitr@setBL}{%
+% \end{macrocode}
+% Actually insert the thread code here by inserting \cs{setThre@d}.
+% \begin{macrocode}
+ \setThre@d{\artthrd@@addtow}{\artthrd@@addtoh}%
+ \unhbox\fitr@bbox
+ \fitr@urxury@fixup{\artthrd@@addtow}{\artthrd@@addtoh}{}%
+ }}}\setlength{\fboxsep}{0pt}%
+% \end{macrocode}
+% Now place an extended border around the viewing area
+% \begin{macrocode}
+ \ifviewMagWin
+ \fitr@length=\artthrd@@addtow bp
+ \fitr@length=2\fitr@length
+ \addtolength{\fitr@length}{\fitr@@width}%
+ \edef\fitr@@width{\the\fitr@length}%
+ \fitr@length=\artthrd@@addtoh bp
+ \fitr@length=2\fitr@length
+ \addtolength{\fitr@length}{\fitr@@height}%
+ \edef\fitr@@height{\the\fitr@length}%
+ \setlength\fitr@length{-\artthrd@@addtow bp}%
+ \addtolength\fitr@length{\fitr@@shift}%
+ \makebox[0pt][l]{\hspace*{\fitr@length}\smash{%
+ \setlength\fitr@length{\fitr@@lift-\fitr@setBL}%
+ \if\fitr@@refPt b%
+ \addtolength\fitr@length{-\artthrd@@addtoh bp}\else
+ \if\fitr@@refPt t%
+ \addtolength\fitr@length{\artthrd@@addtoh bp}%
+ \fi\fi
+ \raisebox{\fitr@length}%
+ {\fbox{\parbox[\fitr@@refPt][\fitr@@height]%
+ {\fitr@@width}{\kern0pt\hfill\vfill\kern0pt}}}}%
+ }%
+ \fi
+\endgroup}
+% \end{macrocode}
+% \paragraph*{Driver dependent macros} The \cs{ThrBbox} macros perform different tasks
+% depending on the driver.
+% \begin{macrocode}
+\if@fitr@dvipdfm
+% \end{macrocode}
+% For the \textsf{dvipdfm} and friends
+% \begin{macrocode}
+\def\ThrBbox#1#2{%
+ \fitr@length=#1bp
+ \fitr@length=2\fitr@length
+ \advance\fitr@length\wd\fitr@bbox
+ \edef\fitr@xetex@view@width{\the\fitr@length}%
+ \fitr@length=#2bp
+ \advance\fitr@length\ht\fitr@bbox
+ \edef\fitr@xetex@view@height{\the\fitr@length}%
+ \fitr@length=#2bp
+ \advance\fitr@length\dp\fitr@bbox
+ \edef\fitr@xetex@view@depth{\the\fitr@length}%
+}\else\ifx\fitr@driver\fitr@pdftex@driver
+% \end{macrocode}
+% For the \textsf{pdftex} and friends
+% \begin{macrocode}
+\def\ThrBbox#1#2{%
+ \fitr@length=#1bp
+ \fitr@length=2\fitr@length
+ \advance\fitr@length\wd\fitr@bbox
+ \edef\fitr@pdftex@view@width{\the\fitr@length}%
+ \fitr@length=#2bp
+ \advance\fitr@length\ht\fitr@bbox
+ \edef\fitr@pdftex@view@height{\the\fitr@length}%
+ \fitr@length=#2bp
+ \advance\fitr@length\dp\fitr@bbox
+ \edef\fitr@pdftex@view@depth{\the\fitr@length}%
+}\else\ifx\fitr@driver\fitr@dvipsone@driver
+% \end{macrocode}
+% For the \textsf{dvipsone} driver
+% \begin{macrocode}
+\def\ThrBbox#1#2{%
+ currentpoint 2 copy %
+ \the\fitr@depth\space add #2\space PDFtoTeX add % y1
+ exch #1\space PDFtoTeX sub exch % x1
+ 4 2 roll exch
+ \the\fitr@width\space add #1\space PDFtoTeX add exch % x2
+ \the\fitr@height\space sub #2\space PDFtoTeX sub} % y2
+\else\ifx\fitr@driver\fitr@dvips@driver
+% \end{macrocode}
+% For the \textsf{dvips} driver
+% \begin{macrocode}
+\def\ThrBbox#1#2{% Uses \fitr@bbox
+ currentpoint 2 copy %
+ \the\fitr@depth\space SPtoDvips add
+ #2\space BPToDvips add % y1
+ exch #1\space BPToDvips sub exch % x1
+ 4 2 roll exch
+ \the\fitr@width\space SPtoDvips add
+ #1\space BPToDvips add exch % x2
+ \the\fitr@height \space SPtoDvips sub
+ #2\space BPToDvips sub} % y2
+\fi\fi\fi\fi
+% \end{macrocode}
+% \paragraph*{Code to set the thread} The \cs{setThre@d} macros are driver dependent.
+% \begin{macrocode}
+\def\setThre@d#1#2{%
+ \fitr@defaultbp{\aWd}{#1}\fitr@defaultbp{\aHt}{#2}%
+ \edef\tmp@exp{\noexpand\set@rtThrd{\aWd}{\aHt}}\tmp@exp
+}
+\if@fitr@dvipdfm
+% \end{macrocode}
+% For the \textsf{dvipdfm} and friends
+% \begin{macrocode}
+\def\set@rtThrd#1#2{\ThrBbox{#1}{#2}%
+ \smash{\raisebox{-\fitr@xetex@view@height+#2bp}%
+ {\makebox[0pt][l]{\hspace*{-#1bp}%
+ \@pdfm@mark{thread @artthrd\CntArt\space
+ width \fitr@xetex@view@width\space
+ height \fitr@xetex@view@height\space
+ depth \fitr@xetex@view@depth\space
+ << /Title (\threadTitle)
+\ifnewarticle
+ /Author (\threadAuthor)
+ /Subject (\threadSubject)
+ /Keywords (\threadKeywords)
+\fi >>}}}}}\else\ifx\fitr@driver\fitr@pdftex@driver
+% \end{macrocode}
+% \textsf{pdftex} and friends
+% \begin{macrocode}
+\def\set@rtThrd#1#2{\ThrBbox{#1}{#2}%
+ \makebox[0pt][l]{\hspace*{-#1bp}%
+ \pdfthread
+ width \fitr@pdftex@view@width\space
+ height \fitr@pdftex@view@height\space
+ depth \fitr@pdftex@view@depth\space
+ name {\threadTitle}}}\else
+% \end{macrocode}
+% For drivers that use PostScript and the \textbf{pdfmark}.
+% \changes{v1.1}{2016/04/09}{Removed the Page key and dependence on the refcount package}
+% \begin{macrocode}
+\def\set@rtThrd#1#2{\literalps@out{\artM@rk
+ /Rect [\ThrBbox{\artthrd@@addtow}{\artthrd@@addtoh}]
+ /Title (\threadTitle)
+\ifnewarticle
+ /Author (\threadAuthor)
+ /Subject (\threadSubject)
+ /Keywords (\threadKeywords)
+\fi
+ /ARTICLE pdfmark}}
+\fi\fi
+% \end{macrocode}
+% \begin{macrocode}
+%</package>
+% \end{macrocode}
+%\Finale
+\endinput