%\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
