rjlnewsp4.dtx

% \iffalse meta-comment
% 
% Copyright (C) 2017 by Robert J Lee <latex@rjlee.homelinux.org>
% --------------------------------------------------------------
% 
% This file may be distributed and/or modified under the
% conditions of the LaTeX Project Public License, either version 1.3
% 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.3 or later is part of all distributions of LaTeX 
% version 2005/12/01 or later.
%
% This work has the LPPL maintenance status ‘maintained’.
%
% The Current Maintainer of this work is Robert J Lee.
%
% This work consists of the files rjlnewsp4.dtx and rjlnewsp4.ins
% and the derived file rjlnewsp4.cls
% 
% \fi
% 
% \iffalse
%<*driver> 
\ProvidesFile{rjlnewsp4.dtx}
%</driver> 
%<package> \NeedsTeXFormat{LaTeX2e}[1999/12/01]
%<package> \ProvidesPackage{rjlnewsp4}
%<*package> 
[2017/06/27 v0.1 .dtx rjlnewsp4 file]
%</package> 
% 
%<*driver> 
\documentclass{ltxdoc}
\EnableCrossrefs         
\CodelineIndex
\RecordChanges
\usepackage{indentfirst}
\usepackage{relsize}
\begin{document}
\makeatletter
\makeatother
\DocInput{rjlnewsp4.dtx}
\end{document}
%</driver> 
% \fi
% 
% \CheckSum{0}
% 
% \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{v0.5}{2004/11/05}{Unstable version}
% 
% \GetFileInfo{rjlnewsp4.dtx}
% 
% \DoNotIndex{\newcommand,\newenvironment}
% 
% 
% \title{The \textsf{rjlnewsp4} class\thanks{This document
%     corresponds to \textsf{rjlnewsp4}~\fileversion, dated \filedate.}}
% \author{Robert J Lee \\ \texttt{latex@rjlee.homelinux.org}}
% 
% \maketitle
%
% \section{Introduction}
%
% \subsection{Features}
%
% \begin{itemize}
% \item Part of the newspaper typesetting package
% \item Determines the size of individual articles prior to
% typesetting, at various column counts.
% \item Accepts a layout file with the location of individual articles
% to perform final typesetting
% \end{itemize}
%
% \subsection{Background}
%
% There is still significant lack of support for decent
% newspaper-style output from \LaTeX, and this package is one intended
% to improve the situation. While several solutions have already been
% tried (many of which are available on \textsmaller{CTAN}), most seem
% to revolve around the |multicol| package, which is excellent for
% general multicolumn documents, but is far too strict in its
% implementation to allow for the styles of headings and column
% layouts found in all modern newspapers.
%
% The major limitation of |multicol| for newspapers is that it
% requires all text to be set to the same width throughout each
% multicolumn environment, which comes out of the fact that \TeX's
% page builder must build more than a whole page of text before it can
% determine the optimum place for each page break, and since text can
% only be set into lines once, its width must be known
% beforehand. This makes it difficult to change the width in any way
% that is page-aware. The usual solution --- and the solution used by
% |multicol| --- is to simply declare a rule that all text must be
% the same width; however, it is actually possible to change the width
% at any known point in the \textit{source} document.
%
% This package does not seek to avoid this limitation; indeed, the
% |multicol| package is used directly at the time of
% writing. This is simply the minimal code necessary to layout
% newspapers in paste-up style without human placement of
% articles. Once working, it is intended to remove the |multicol|
% code and replace it with our own implementation, to allow
% significant changes to the document.
%
% This package was born out of the realisation that each article could
% be set with a different width to the others --- even though
% typesetting each page with a different width would be hard, so if an
% article spilled across pages then its width could not easily be
% match different column widths on each page.
%
% The practical upshot of this is that, provided the user is prepared
% to accept that each article will have constant width, an efficient
% solution to the newspaper problem is possible.
%
% \subsection{Current Limitations}
%
% \begin{itemize}
% \item Currently, only one page is supported.
% \item The maximum length of any individual article is~16,384~points
%   (around 5 metres, or nearly 19 feet)
% \item A \texttt{C++} program is used to calculate a page layout.
%   This is still under development, so the ideal layout may change.
%   Generated layout files are stored to allow the final document to
%   be repeatedly generated through \TeX.
% \item Each page is a separate document, with no automated support
%   for continuation of articles between pages.
% \item No support is provided for changing the page size or
%   orientation when injecting a newspaper into another document
% \item The package provides its own document class.
%   Other formats may set up environments that conflict with
%   |rjlnewsp4|. it is especially easy to produce text that overtypes
%   the newspaper articles.
% \item Running in a |minipage| environment is untested, and unlikely
%   to work
% \item All articles must be in constant-width columns (although the
%   width may differ between articles). Magazine-style graphics that
%   descend into columns are not supported, except by injecting
%   |\parshape| and friends into the source text.
% \item An interface for the specification of alternate widths per
%   article is yet to be implemented.
% \item No support for many familiar markup constructs, including
%   footnotes or endnotes, page markers, running headers and so on. It
%   may be possible to add these in future.
% \item No support for page titles and similar; these are expected to
%   be added in the near future.
% \end{itemize}
%
% \subsection{Paste-Up Newspapers}
%
% \textit{Paste-up} refers to an early form of electronic typesetting
% for newspapers. An operator would type text into an electronic
% machine, which would typeset the text neatly into columns of a
% prescribed width. The operator would then cut the columns into
% lengths, and literally paste them onto the a master copy to form the
% newspaper.
%
% This package uses a similar technique to produce neatly typeset
% newspapers using \LaTeX, along with a couple of tricks to make the
% document look neater.
%
% \section{Usage}
% \subsection{Structure of a Newspaper}
% 
% \DescribeEnv{newspaper}|\begin{newspaper}|
%   \par\hspace{1in}\vdots\par
%   |\end{newspaper}|
%
% The |newspaper| environment encloses the entire newspaper. If used
% in the middle of a document, it will end the current page and embed
% a newspaper in one or more pages of its own.
% 
% Generally, a |newspaper| environment should surround each newspaper
% in your document. Unless specified otherwise, all other commands
% described below should appear in a |newspaper| environment.
% 
% \DescribeMacro{article}\marg{filename}\marg{headline}\oarg{subtitle}
% 
% Use inside |newspaper|
% 
% The |article| macro defines a single article for the
% newspaper. The |filename| determines the file from which this
% article is read.
% 
% The |headline| is the headline for the article.
%
% The optional |subtitle| is the subtitle for the article. This can be
% used for the author's name.
% 
% All text in the environment will be set out in balanced columns at
% the full page height.
% 
% \subsection{Changing the Appearance}
% 
% \DescribeMacro{\alleyleft}
% 
% Between two adjacent columns is a gap known as an \textit{alley},
% which prevents the reader's eye from jumping from one column to the
% next. In |rjlnewsp|, the alley is built up of two spaces (determined
% by |\alleyleft| and |\alleyright|) and a downrule (a vertical line,
% determined by |\downrulethick|).
% 
% This length holds the partial width of the alley. This is space
% added at the left-hand side of each column.
% 
% \DescribeMacro{\alleyright}
% 
% This length holds the partial width of the alley. This is space
% added at the right-hand side of each column.
% 
% \DescribeMacro{\downrulethick}
% 
% A vertical line, known as a downrule, normally appears in the alley
% between two adjacent columns. |\downrulethick| holds the width of the
% dark vertical lines between columns. To avoid these lines, set this
% length to~|0pt|.
%
% \DescribeMacro{\downruletop}
%
% If the rules between articles are drawn to their logical full
% length, the effect is to create a grid, with each article's columns
% surrounded by a complete paragraph box. This is usually considered
% to be too imposing, so newspapers add extra whitespace by stopping
% the rules a few points short of their natural termination.
% 
% The length |\downruletop| is extra space added to the top of a
% downrule, shortening it. It should usually be the same as
% |\downrulebottom|. By default, it is also the same as
% |\sideruleleft| and |\sideruleright|.
% 
% \DescribeMacro{\downrulebottom}
% 
% The length |\downrulebottom| is extra space added to the bottom of a
% downrule, shortening it. It should usually be the same as
% |\downruletop|. By default, it is also the same as
% |\sideruleleft| and |\sideruleright|.
%
% \DescribeMacro{\alleytop}
% 
% Between two vertically-adjacent articles is a gap known as an
% \textit{alley}, which indicates the end of one article and the start
% of the next. In |rjlnewsp|, the alley is built up of two spaces
% (determined by |\alleytop| and |\alleybottom|) and a rule (a
% horizontal line, determined by |\siderulethick|).
% 
% This length holds the partial width of the alley. This is space
% added at the top of each article (typically extra space above the
% headline, or space between the rule and the article body text if
% this is a continuation column).
% 
% \DescribeMacro{\alleybottom}
% 
% This length holds the partial width of the alley. This is space
% added at the bottom of each article column.
% 
% \DescribeMacro{\siderulethick}
% 
% A horizontal line, known as a rule, normally appears in the alley
% between vertically adjacent articles. Since there can be many
% ``rules'' in a newspaper, we call this a
% \textit{siderule}. |\siderulethick| holds the width of the 
% dark horizontal lines between articles. To avoid these lines, set
% this length to~|0pt|.
% 
% \DescribeMacro{\sideruleleft}
%
% The length |\sideruleleft| is extra space added to the left of a
% siderule, shortening it. It should usually be the same as
% |\sideruleright|. By default, it is also the same as
% |\downruletop| and |\downrulebottom|.
% 
% \DescribeMacro{\sideruleright}
% 
% The length |\sideruleright| is extra space added to the right of a
% siderule, shortening it. It should usually be the same as
% |\sideruleleft|. By default, it is also the same as
% |\downruletop| and |\downrulebottom|.
%
% \section{Implementation}
% \subsection{Preamble}
% 
%    \begin{macrocode}
\ProvidesClass{rjlnewsp4}[2017/07/12 Robert J Lee]
\NeedsTeXFormat{LaTeX2e}
%    \end{macrocode}
%
% There hasn't been a document class for newspapers before.
% Using |article| as a parent class seemed like a bad idea because it
% pulls in a lot of article-related notes for typesetting titles,
% articles, sections and so on that don't really apply to newspapers.
%
% Using |minimal| as a base class is also a bad idea for the reasons
% set out in that package. So instead we start from scratch.
%
% All document classes must define |\normalsize|, |\textwidth| and
% |\textheight|. |10pt| seems like a good standard to go with, and
% the page sizes have been copied from |minimal| until I can think of
% something better to use.
%    \begin{macrocode}
\renewcommand\normalsize{\fontsize{10pt}{12pt}\selectfont}
\setlength{\textwidth}{6.5in}
\setlength{\textheight}{8in}
%    \end{macrocode}
%
% We will handle any page numbers.
%    \begin{macrocode}
\pagenumbering{arabic}  % but no page numbers are printed because:
\pagestyle{empty}       % this is actually already in the kernel
%    \end{macrocode}
% 
% \section{Dependencies}
% Next declare our pagkage dependencies. Effort has been made to
% minimise our dependencies somewhat, but there are a few that are
% still used.
%
% |ifthen| provides a \LaTeX-style |\ifthenelse| macro, used mostly in
% validation.
%
% |forloop| is used to iterate through articles and columns.
%
% |multicol| is used as an easy way to build rectangular
% articles. This may be removed in a future release to provide more
% control over article spacing and to allow non-rectangular articles
% in the layout.
%
% Note that |eso-pic| is requiled later on, but only during the final
% layout. This provides a slightly convenient low-level primative that
% we use for setting text at exact coordinates on the page.
%    \begin{macrocode}
\RequirePackage{ifthen}
\RequirePackage{forloop}
%    \end{macrocode}
%
% The next section is copied from the article class. It sets up the
% options for |draft|, |final|, |10pt|, |11pt| and |12pt|.
% |draft| has been modified to also declare |\rjl@unbalance|; we want
% to show free vertical space in the final column so the editor knows
% how many column inches of text are available to fill.
%    \begin{macrocode}
\newcommand\@ptsize{0}
\DeclareOption{draft}{\setlength\overfullrule{5pt}\newcommand{\rjl@unbalance}{0}}
\DeclareOption{final}{\setlength\overfullrule{0pt}}
\DeclareOption{10pt}{\renewcommand\@ptsize{0}}
\DeclareOption{11pt}{\renewcommand\@ptsize{1}}
\DeclareOption{12pt}{\renewcommand\@ptsize{2}}
%    \end{macrocode}
%
% Standard lengths as per |article|. These may be tweaked before
% release to better support text in narrow columns.
%
%    \begin{macrocode}
\setlength\arraycolsep{5\p@}
\setlength\tabcolsep{6\p@}
\setlength\arrayrulewidth{.4\p@}
\setlength\doublerulesep{2\p@}
\setlength\tabbingsep{\labelsep}
\skip\@mpfootins = \skip\footins
\setlength\fboxsep{3\p@}
\setlength\fboxrule{.4\p@}
\setlength\columnsep{10\p@}
\setlength\columnseprule{0\p@}
%    \end{macrocode}
%
% \DescribeMacro{\verse}
% verse is copied from |article|.
% \DescribeMacro{\quotation}
% quotation is copied from |article|.
% \DescribeMacro{\quote}
% quote is copied from |article|.
% \DescribeMacro{\table}
% table is copied from |article|.
%    \begin{macrocode}
\newenvironment{verse}
               {\let\\\@centercr
                \list{}{\itemsep      \z@
                        \itemindent   -1.5em%
                        \listparindent\itemindent
                        \rightmargin  \leftmargin
                        \advance\leftmargin 1.5em}%
                \item\relax}
               {\endlist}
\newenvironment{quotation}
               {\list{}{\listparindent 1.5em%
                        \itemindent    \listparindent
                        \rightmargin   \leftmargin
                        \parsep        \z@ \@plus\p@}%
                \item\relax}
               {\endlist}
\newenvironment{quote}
               {\list{}{\rightmargin\leftmargin}%
                \item\relax}
               {\endlist}
\newcounter{table}
\renewcommand\thetable{\@arabic\c@table}
\def\fps@table{tbp}
\def\ftype@table{2}
\def\ext@table{lot}
\def\fnum@table{\tablename\nobreakspace\thetable}
\newenvironment{table}
               {\@float{table}}
               {\end@float}
\newenvironment{table*}
               {\@dblfloat{table}}
               {\end@dblfloat}
\newlength\abovecaptionskip
\newlength\belowcaptionskip
\setlength\abovecaptionskip{10\p@}
\setlength\belowcaptionskip{0\p@}
\long\def\@makecaption#1#2{%
  \vskip\abovecaptionskip
  \sbox\@tempboxa{#1: #2}%
  \ifdim \wd\@tempboxa >\hsize
    #1: #2\par
  \else
    \global \@minipagefalse
    \hb@xt@\hsize{\hfil\box\@tempboxa\hfil}%
  \fi
  \vskip\belowcaptionskip}
%    \end{macrocode}
%
% \DescribeMacro{\today}
% |\today| is a macro from |article|, so we'd better provide a definition.
%
% This version has been modified to put out dates in British format,
% with proper superscripts.
%
% To use the American-style default as per |article|, use the option
% |ltxtoday|.
%
% Some packages cause problems if you want this format; if you use a
% style such as |babel| --- which overrides the definition of |\today|
% in |english.ldf| at the start of the document --- or |datetime| or
% |datetime2| --- which redefines |\today| in the style file as well
% as giving many other options for date formatting.
%
% If you do want this format, the option |forcetoday| will also
% redefine |\today| at the start of the |newspaper| environment,
% overwriting any changes from other packages.
%    \begin{macrocode}
\newcommand{\rjl@today@}{%
  \number\day\textsuperscript{\ifcase\day th%0
    \or st\or nd\or rd\else th\fi}\,% \, shorter than \space due to superscript
  \ifcase\month\or
    January\or February\or March\or April\or May\or June\or
    July\or August\or September\or October\or November\or December\fi
    \space\number\year}
\newcommand{\today}{\rjl@today@}%
%    \end{macrocode}
%
% \DescribeMacro{\rjl@multicol@}
% Holds the name of the multicols environment to use for breaking text
% into multple columns. The |rjl@multicols| environment, defined by
% this class, is used by default; this may be modified by the
% |multicols| option.
%    \begin{macrocode}
\newcommand{\rjl@multicol@}{rjl@multicols}
%    \end{macrocode}
%
% \DescribeMacro{\DeclareOption}
% Here we process some class options.
% \begin{itemize}
% \item \texttt{draft} Draft option as per |article| (defined above);
% puts black rectangle on the page to mark where boxes have overfilled
% (where you need to reword the text or modify spacing
% registers). Also prevents stretching of the final column of an
% article, to preview the amount of free space left.
% \item \texttt{final} Final option as per |article|. This ensures
% that all options are printed in their final published form.
% \item \texttt{10pt} Selects a 10-point font
% \item \texttt{11pt} Selects an 11-point font
% \item \texttt{12pt} Selects a 12-point font
% \item \texttt{multicols} Load the |multicol| package and use its
% |multicols| environment for balancing articles. This may better
% balancing of article text than the built-in version, which simply
% stretches the final column. This is especially noticable when large
% items are inserted into the text. However; it is expected that
% |multicols| will only work with rectangular articles going forward.
% \item \texttt{multicol} Synonym for |multicols|. Mostly included
% because it is very easy to get confused between the |multicols|
% environment and the |multicol| package.
%    \begin{macrocode}
\DeclareOption{multicols}{\AtBeginDocument{\RequirePackage{multicol}}\renewcommand{\rjl@multicol@}{multicols}}
\DeclareOption{multicol}{\AtBeginDocument{\RequirePackage{multicol}}\renewcommand{\rjl@multicol@}{multicols}}
%    \end{macrocode}
% \item \texttt{unbalance} Normally an attempt is made to balance the
% text between the columns of an article; that is, to put the same
% amount of text into each column. The |draft| option prevents this
% and allows extra space at the end of the final column. If you want
% to produce this effect in a final (non-|draft|) document for some
% reason, use the |unbalance| option. NB: This does not work with
% |multicols|.
%    \begin{macrocode}
\DeclareOption{unbalance}{\newcommand{\rjl@unbalance}{1}}
%    \end{macrocode}
% \item \texttt{ltxtoday} Option that can be passed to use the
% US-style date format used by the standard |article| class.
%    \begin{macrocode}
\DeclareOption{ltxtoday}{
  \renewcommand{\today}{\ifcase\month\or
    January\or February\or March\or April\or May\or June\or
    July\or August\or September\or October\or November\or December\fi
    \space\number\day, \number\year}
}
%    \end{macrocode}
% \item \texttt{sizing} Passed by the C++ program to indicate that articles
% are being sized, to generate the layout file. Note that the file is
% generated in C++, not in \LaTeX. \textit{This option is ignored;
% sizing wil be performed if the |layout| option is not given}.
%    \begin{macrocode}
\DeclareOption{sizing}{%
% NB: We need this line. |\jobname.lay| is read by the C++ program.
  \typeout{Generating Layout file \jobname.lay}%
}
%    \end{macrocode}
% \item \texttt{layout} Instead of sizing, the article will be typeset
% using the layout file. Usually passed by the C++ program.
%    \begin{macrocode}
\DeclareOption{layoutnews}{%
  \typeout{This shalt be the final output. Reading \jobname.lay}%
  \newcommand{\rjl@dofinal}{}%
}
%    \end{macrocode}
% \item \texttt{forcetoday} Allow our |\today| command to overwrite
% the version used by |babel|, which does not use superscripts.
% \end{itemize}
%    \begin{macrocode}
\newcommand{\rjl@today}{}
\DeclareOption{forcetoday}{%
  \renewcommand{\rjl@today}{\renewcommand{\today}{\rjl@today@}}%
}%
\ProcessOptions%
% Copied from article:
\input{size1\@ptsize.clo}
\setlength\lineskip{1\p@}
\setlength\normallineskip{1\p@}
\renewcommand\baselinestretch{}
\@lowpenalty   51
\@medpenalty  151
\@highpenalty 301
%    \end{macrocode}
%
%
%    \begin{macrocode}
% \DescribeMacro{\theartfile}
% \DescribeMacro{\theheadline}
% \DescribeMacro{\thesubhead}
%      Get the file, headline and subhead
\newcommand{\theartfile}{}
\newcommand{\theheadline}{}
\newcommand{\thesubhead}{}
%    \end{macrocode}
%
% \begin{macro}{\headline}
% \marg{theheadline}
%
% Typesets the headline. Called automatically during article layout.
% By default, this is passed |\theheadline| which is a macro expanding to the
% user-supplied headline. By default, it typesets its argument in a larger font,
% bold and centered.
%
%    \begin{macrocode}
\newcommand{\headline}[1]{%
  \centerline{\large \textbf{#1}}%
  \vspace{-1em}%
  \par%
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\subheadline}
% \marg{thesubhead}
%
% Typesets the sub-headline. Called automatically during article layout.
% By default, this is passed |\thesubhead| which is a macro expanding to the
% user-supplied headline. By default, it typesets its argument in a slanted font
% and centered. This macro is called even if no subheadline is given.
%
%    \begin{macrocode}
\newcommand{\subheadline}[1]{%
  \centerline{\textsl{#1}}%
  \vspace{0.2em}%
  \par%
}
%    \end{macrocode}
% \end{macro}
%
% \DescribeMacro{rjl@mincols}\DescribeMacro{rjl@maxcols}
% Define counters used to store the range of column options for the
% current article:
%    \begin{macrocode}
\newcounter{rjl@mincols}
\newcounter{rjl@maxcols}
%    \end{macrocode}
%
% \begin{macro}{\rjl@readnumcols}
% |\rjl@readnumcols| is a macro to parse the human-entered number of
% columns (used in |\article| to parse the first optional parameter)e
%
% It is passed 4 single-character parameters from the user's input
% option, with subsequent parameters filled with |\relax|.
%
% Would be nice to do more validation here, but this'll do for parsing
% for now\dots
%    \begin{macrocode}
\def\rjl@readnumcols#1#2#3#4{
  \setcounter{rjl@mincols}{1}
  \setcounter{rjl@maxcols}{5}
  \ifthenelse{\equal{#1}{\relax}}{
      \ClassError{rjlnewsp4}{First optianal \string\article argument
        badly formatted}{The first argument must either be the maximum
        number of columns allowed, or (minimun)-(maximum)}
    }{
      \ifthenelse{\equal{#2}{\relax}}{
        \setcounter{rjl@maxcols}{#1}
      }{
        \ifthenelse{\equal{#3}{-}}{
          \setcounter{rjl@mincols}{#1}
          \setcounter{rjl@maxcols}{#4}
        }{
          \ifthenelse{\equal{#2}{-}}{
            \setcounter{rjl@mincols}{#1}
            \setcounter{rjl@maxcols}{#3}
          }{
            \ClassError{rjlnewsp4}{First optianal \string\article argument
              badly formatted}{The first argument must either be the maximum
              number of columns allowed, or (minimun)-(maximum)}
          }
        }
      }
  }
  \ifthenelse{\value{rjl@maxcols} < \value{rjl@mincols}}{
    \ClassError{rjlnewsp4}{First optianal \string\article\space argument
        is invalid}{The first argument must either be the maximum
        number of columns allowed, or (minimun)-(maximum); you cannot
        specify \arabic{rjl@mincols}--\arabic{rjl@maxcols}: maximum is
        less than minimum. Swapping maximum and minimun values.}
    \edef\rjl@tmp{\value{rjl@mincols}} % local
    \setcounter{rjl@maxcols}{\value{rjl@mincols}}
    \setcounter{rjl@mincols}{\rjl@tmp}
  }{}
  \ifthenelse{\value{rjl@mincols} < 1}{
    \ClassError{rjlnewsp4}{First optianal \string\article\space argument
        is invalid}{The first argument must either be the maximum
        number of columns allowed, or (minimun)-(maximum); you cannot
        specify \arabic{rjl@mincols}--\arabic{rjl@maxcols}: illegal
        minimum. Using 1--\arabic{rjl@maxcols} instead.}
    \setcounter{rjl@mincols}{1}
  }{}
  \ifthenelse{\value{rjl@mincols} > 9}{
    \ClassError{rjlnewsp4}{First optianal \string\article\space argument
        is invalid}{The first argument must either be the maximum
        number of columns allowed, or (minimun)-(maximum); you cannot
        specify \arabic{rjl@mincols}--\arabic{rjl@maxcols}: illegal
        minimum (only 9 columns supported). Using 9 columns instead.}
    \setcounter{rjl@mincols}{9}
    \setcounter{rjl@maxcols}{1}
  }{}
  \ifthenelse{\value{rjl@maxcols} < 1}{
    \ClassError{rjlnewsp4}{First optianal \string\article\space argument
        is invalid}{The first argument must either be the maximum
        number of columns allowed, or (minimun)-(maximum); you cannot
        specify \arabic{rjl@mincols}--\arabic{rjl@maxcols}: illegal
        maximum. Using \arabic{rjl@mincols}--\arabic{rjl@mincols} instead.}
    \setcounter{rjl@maxcols}{\value{rjl@mincols}}
  }{}
  \ifthenelse{\value{rjl@maxcols} > 9}{
    \ClassError{rjlnewsp4}{First optianal \string\article\space argument
        is invalid}{The first argument must either be the maximum
        number of columns allowed, or (minimun)-(maximum); you cannot
        specify \arabic{rjl@mincols}--\arabic{rjl@maxcols}: illegal
        maximum (only 9 columns supported). Using 9 columns instead.}
    \setcounter{rjl@maxcols}{9}
  }{}
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\article}
%  \marg{filename}
%  \marg{headline}
%  \oarg{subheadline}
%
% This is where we get the metainformation for an article.
% - \oarg{max cols}: Maximum number of columns to set an article
% at. Currently must be no more than 10. Default is 5.
% - \marg{filename}: stored in |\theartfile|
% - \marg{headline}: stored in |\theheadline|
% - \oarg{subheadline}: stored in |\thesubhead|
%   
% NB: increasing the number of column options will significantly
% increase the amount of time that it takes to process your document,
% and slightly increase the chance of finding a layout solution that
% better fills the page.
%    \begin{macrocode}
\newcommand{\article}[3][5]{
  \rjl@readnumcols#1\relax\relax\relax\relax
  \renewcommand{\theartfile}{#2}
  \renewcommand{\theheadline}{#3}
% If we are follewed by a [ char, then the optional subhead is present.
% In which case, read it in and then process article sizes.
% Otherwise, we process article sizes directly.
% This is a bit clunky due to \TeX's low-level handling of optional
% parameters, hence we need to declare the call twice (once for each
% control path).
  \@ifnextchar[{\rjl@readsubhead@and@process}{\renewcommand{\thesubhead}{}\rjl@process@article}%
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\rjl@readsubhead}
% This is used in the definition of |\article|. It consumes
% one argument in square brackets and assigns it to |\thesubhead|
%    \begin{macrocode}
\def\rjl@readsubhead@and@process[#1]{
  \renewcommand{\thesubhead}{#1}
  \rjl@process@article
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\rasterimage}
% \oarg{captionplacement} T or B, then I or E (default BI for internal bottom)
% \marg{caption} Text to display above or below the article content
% \oarg{incrudegraphics-args} Arguments to pass to |\includegraphics|;
% defaults to |width=|\textit{width}|,height=|\textit{height}
% \marg{width} Width of the article
% \marg{height} Height of the article
% \marg{filename} Filename of the image. \textsc{png}, \textsc{pdf},
% TODO: extra arguments to includegraphics; use the starred form to
% crop rather than extend outside the box
% \textsc{jpeg} are supported by |pdflatex|.
% Include an image from the given file, scaled to the given
% dimensions.
%
% Because I want to minimise required dependencies, this is only
% usefully defined if the |graphicx| package is loaded; otherwise we
% out out an error on use.
%
% Note that the |draft| option is passed to |graphicx| by
% \LaTeX\ automatically, and disables the output of images, to speed
% up the preview.
%
% The placement of the image and caption are handled by the |rasterarticle|
% envinonment, defined below.
%
% \LaTeX\ has very poor support for commands with multiple optional
% arguments, so this uses nexted calls in plain-\TeX style to fill in
% each optional argument in turn, before finally calling |\rjl@rasterimage|.
%    \begin{macrocode}
\newcommand{\rasterimage}{\@ifstar{\rjl@rasterimage@opts{*}}{\rjl@rasterimage@opts{}}}
\def\rjl@rasterimage@opts#1{\@ifnextchar[{\rjl@rasterimage@opts@{#1}}{\rjl@rasterimage{#1}{BI}}}
\def\rjl@rasterimage@opts@#1[#2]{\rjl@rasterimage@{#1}{#2}}
\def\rjl@rasterimage@#1#2{\@ifnextchar[{\rjl@rasterimage@opt{#1}{#2}}{\rjl@rasterimage{#1}{#2}{default}}}
\def\rjl@rasterimage@opt#1#2[#3]{\rjl@rasterimage{#1}{#2}{#3}}
\AtBeginDocument{
  \@ifpackageloaded{graphicx}{
    \newcommand{\rjl@rasterimage}[7]{
      \begin{rasterarticle}[#2]{#4}{#5}{#6}
        \typeout{graphin 1#1 2#2 3#3 4(#4) 5#5 6#6 7#7}
        \ifthenelse{\equal{#3}{default}}{
          \includegraphics#1[width=#5,height=#6]{#7}
        }{
          \includegraphics#1[#3]{#7}
        }
      \end{rasterarticle}
    }
  }{
    \newcommand{\rjl@rasterimage}[7][]{
      \ClassError{rjlnewsp4}{To use the \protect\rasterimage\space
        command, you musc include the graphicx package in your preamble%
      }{Add the line \protect\usepackage\protect{graphicx\protect} before
        \protect\begin\protect{document\protect} in your main .tex file}
    }
  }
}
%    \end{macrocode}
% \end{macro}
%
% \begin{environment}{rasterarticle}
% \oarg{captionplacement} T or B, then I or E (default BI for internal bottom)
% \marg{caption} Text to display above or below the article content
% \marg{width} Width of the article
% \marg{height} Height of the article

% Place a fixed-size item on the page (eg a photograph).
% The \LaTeX\ source inside the environment is evaluated inside a box
% of the given size.
%
% The |captionplacement| is a 2-letter code:
%\begin{itemize}
% \item[TI] \textbf{T}op, \textbf{I}nternal; the caption is placed
% above the content and the |height| specified includes the caption
% size (space of content is reduced to accommodate the caption)
% \item[TE] \textbf{T}op, \textbf{E}xternal: the caption is placed
% above the content and the |height| specified excludes the caption
% size (additional space is added to accommodate the caption)
% \item[BI] \textbf{B}ottom, \textbf{I}nternal; the caption is placed
% below the content and the |height| specified includes the caption
% size
% \item[BE] \textbf{B}ottom, \textbf{E}xternal: the caption is placed
% below the content and the |height| specified excludes the caption
% size
%\end{itemize}
%    \begin{macrocode}
\newenvironment{rasterarticle}[4][BI]{
  \typeout{Raster article #1}
  \setlength{\newsartwidth}{#3} % for output
  \hsize=#3\vsize=#4
  \rjl@ifflag{#1}{Tt}{\global\rjl@captiontoptrue}{}
  \rjl@ifflag{#1}{Bb}{\global\rjl@captiontopfalse}{}
  \rjl@ifflag{#1}{Ii}{\addtolength{\vsize}{\dimexpr\ht\@tempboxa+\dp\@tempboxa}}{}
  \rjl@ifflag{#1}{Ee}{}{}
  \renewcommand{\theheadline}{#2}
  \setbox\@tempboxa=\hbox to #3{\hfill\theheadline\hfill}
  \setbox\rjl@parabox\vbox\bgroup
  \ifrjl@captiontop\vbox{\usebox\@tempboxa}\fi
  \vbox\bgroup
}{
  \egroup
  \ifrjl@captiontop\else\vbox{\usebox\@tempboxa}\fi
  \egroup
  \rjl@process@article@raster
}
%    \end{macrocode}
%
%  \begin{macro}{\ifrjl@captiontop}
% This is a \LaTeX flag used inside |rasterarticle|, to determine if
% the caption should be drawn above or below the content. It is set by
% a call to |\rjl@ifflag| when reading the arguments, and evaluated
% once before the macro (for above) and once after (below). This will
% probably do the opposite of what you expect in a bottom-to-top language.
%    \begin{macrocode}
\newif\ifrjl@captiontop
%    \end{macrocode}
%   \end{macro}
% \end{environment}
%
% \begin{macro}{\rjl@ifflag}
% \marg{usertext}
% \marg{chars}
% \marg{macro}
%
% Executes |macro| if any characters in |chars| occur within
% |usertext|. All output is discarded. No ``else'' case is supported.
%
% This checks the first character, uses |\@gobble#1| to strip the
% first character, then calls itself recursively until |#1| is empty.
% It also recurses on |#2| using |\@gobble| to process any unprocessed
% flags.
%
% \LaTeX's temporary |\@tempboxa| (normally used for |\settowidth|
% etc) is commandeered to remove the trailing characters that would
% build up on the output.
%
% This is quite quick-and-dirty; in particular, |#3| may be
% expanded multiple times.
%
%    \begin{macrocode}
\newcommand{\rjl@ifflag}[3]{
  \setbox\@tempboxa\hbox{
    \rjl@readflag#2
    \ifthenelse{\equal{#2}{\rjl@flag}}{}{
      \edef\rjl@nextflag{\@gobble#2}
      \expandafter\rjl@ifflag\expandafter{#1}{\rjl@nextflag}{#3}
    }
    \ifthenelse{\equal{#1}{}}{}{
      \expandafter\@ifnextchar\rjl@flag{
        #3}{}#1
      \expandafter\rjl@ifflag\expandafter{\@gobble#1}{#2}{#3}
    }
  }
  \setbox\@tempboxa\box\voidb@x
}
\def\rjl@readflag#1{\edef\rjl@flag{#1}}
%    \end{macrocode}
% \end{macro}
%
%
% \subsection{Lengths affecting alleys between articles}
% TODO: Be more clear about the distinction between alleys and gutters.
%
% \DescribeMacro{alleyleft}
% |\alleyleft| is the space of an alley placed to the left a downrule
% between articles.
%    \begin{macrocode}
\newlength{\alleyleft}\setlength{\alleyleft}{0.06in}
%    \end{macrocode}
%
% \DescribeMacro{downrulethick}
% |\downrulethick| is the thickness of a downrule between articles.
%    \begin{macrocode}
\newlength{\downrulethick}\setlength{\downrulethick}{0.005in}
%    \end{macrocode}
%
% \DescribeMacro{downruletop}
% |\downruletop| is the gap at the top of a downrule between articles.
%    \begin{macrocode}
\newlength{\downruletop}\setlength{\downruletop}{0.25in}
%    \end{macrocode}
%
% \DescribeMacro{downrulerbottom}
% |\downrulebottom| is the gap at the bottom of a downrule between articles.
%    \begin{macrocode}
\newlength{\downrulebottom}\setlength{\downrulebottom}{0.25in}
%    \end{macrocode}
%
% \DescribeMacro{alleyright}
% |\alleyright| is the space of an alley placed to the right of a downrule
% between articles.
%    \begin{macrocode}
\newlength{\alleyright}\setlength{\alleyright}{0.06in}
%    \end{macrocode}
%
% Aside: Unsure if \textit{siderule} is the correct term;
% vertical space between articles is common in newspaper layouts but
% not often talked about; most references I've seen just call any
% horizontal line a ``rule''. Here we need to be specific about rules
% in an alley between articles, so we'll stick with it for now.
%
% \DescribeMacro{alleytop}
% |\alleytop| is the space of an alley placed to the top a siderule
% between articles.
%    \begin{macrocode}
\newlength{\alleytop}\setlength{\alleytop}{0.06in}
%    \end{macrocode}
%
% \DescribeMacro{siderulethick}
% |\siderulethick| is the thickness of a siderule between articles.
%    \begin{macrocode}
\newlength{\siderulethick}\setlength{\siderulethick}{0.005in}
%    \end{macrocode}
%
% \DescribeMacro{sideruleleft}
% |\sideruleleft| is the gap at the left of a siderule between articles.
%    \begin{macrocode}
\newlength{\sideruleleft}\setlength{\sideruleleft}{0.25in}
%    \end{macrocode}
%
% \DescribeMacro{siderulerright}
% |\siderulelright| is the gap at the bottom of a siderule between articles.
%    \begin{macrocode}
\newlength{\sideruleright}\setlength{\sideruleright}{0.25in}
%    \end{macrocode}
%
% \DescribeMacro{alleybottom}
% |\alleybottom| is the space of an alley placed to the bottom of a siderule
% between articles.
%    \begin{macrocode}
\newlength{\alleybottom}\setlength{\alleybottom}{0.06in}
%    \end{macrocode}
%
% \begin{macro}{\newscolwidth} 
% \begin{macro}{\newsartwidth} 
%   |\newscolwidth| (length) is the width of a column including
%   gutters/alleys.
%   It is set to 1.5" by default, but can be modified before an |\article|
%   is included to change the size of that article. TODO: test me.
%
%   |\newsartwidth| (length) is set automatically to the width of the article
%   currently being typeset, up to the current column. This can be
%   used to place dynamically-sized elements within an article;
%   however, it will be larger than the current |\newscolwidth| if the
%   article has multiple columns. TODO: This should really be the full
%   article width, and we should use an @ length internally
%
%    \begin{macrocode}
\newlength{\newscolwidth}
\setlength{\newscolwidth}{1.5in}
\newlength{\newsartwidth}
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
% \begin{macro}{\rjl@output@headlines@common}
% This routine outputs the headlines.
%
% It takes no parameters, but experts |\theheadline| and |\thesubhead|
% to be set.
% 
% We also define \DescribeMacro{\rjl@junkbox} a box register to hold
% the subheadline. This is so we can discard it without adding extra
% |\par|s (which take space) if it is empty.
%
% The subheadline is always rendered, but if it produces a box of 0pt
% \textit{height} or \textit{width} then it will not be allocated any
% space.
%    \begin{macrocode}
\newbox\rjl@junkbox
\newcommand{\rjl@output@headlines@common}{%
  \vspace*{\alleytop}%
  \vspace*{\siderulethick}%
  \vspace*{\alleybottom}%
  \headline{\theheadline}%
  \sbox{\rjl@junkbox}{\subheadline{\thesubhead}}%
  \ifdim\ht\rjl@junkbox=0pt%
  \else%
  \ifdim\wd\rjl@junkbox=0pt%
  \else%
  \noindent\usebox{\rjl@junkbox}%
  \fi\fi%
}
%    \end{macrocode}
% \end{macro}
% 
% \begin{macro}{\rjl@output@article@common@lengths}
% Simple macro to set common lengths for reading articles.
% Used by |\rjl@output@article@common| and also |splitarticle| environment
%    \begin{macrocode}
\newcommand{\rjl@output@article@common@lengths}{
  \noindent%
  \addtolength{\baselineskip}{0pt plus 0.125pt minus 0.5pt}% applies as local change
  \setlength{\parskip}{\smallskipamount}% depends on font size
  \setlength{\parindent}{1em}%
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\rjl@output@article@common}
% This common routine typesets the current article, setting
% |\colmnsep|.
%
% It takes no parameters, but experts
% |\rjl@numcols| to be set.
%
% It is called by both definitions of |\rjl@output@article|, so to
% ensure that the articles are output at the same dimensions as they
% are measured.
%
% It modifies |\baselineskip| and |\parskip|; both modifications apply
% only locally to the article output; however, they must be done here
% to ensure that both the sizing and the layout use the same spacing.
%    \begin{macrocode}
\newcommand{\rjl@output@article@common}{%
  \rjl@output@article@common@lengths%
  \ifthenelse{\equal{\rjl@numcols}{1}}{%
    \input{\theartfile}%
  }{%
    \setlength{\columnsep}{\dimexpr\alleyleft+\alleyright+\downrulethick\relax}%
    \expandafter\begin\expandafter{\rjl@multicol@}{\rjl@numcols}%
      \input{\theartfile}%
    \expandafter\end\expandafter{\rjl@multicol@}%
  }%
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\rjl@col@count}
% The |rjl@col@count| counter is used to iterate over the various
% options for the number of columns when sizing the articles.
%
% It is also used when outputting downrules within an article.
%    \begin{macrocode}
\newcounter{rjl@col@count}
%    \end{macrocode}
% \end{macro}
%
% \subsection{Modes of operation}
%
% This |\@ifundefined| splits the class into two distinct personalities.
% The first time we run, we output the size of the articles at various
% different widths to the log. This is read by the calling C++
% program, which in turn generates a |.lay| layout file.
% The else case assumes that the |.lay| file has been generated, and
% proceeds to simply typeset the newspaper with the given dimensions.
%
%    \begin{macrocode}
\@ifundefined{rjl@dofinal}{%
%    \end{macrocode}
%
% \subsection{Article Sizing Mode}
%
% \DescribeMacro{\@rjl@realvsize}
% This length is used internally to save and restore the page size when
% switching between output modes.
%    \begin{macrocode}
\newlength{\@rjl@realvsize}
%    \end{macrocode}
%
% \begin{macro}{\rjl@process@article}
%
% This is called after every |\article|.
% In this personality, it determines and output the
% size of the article when set at different widths.
%
%% eg with 2 columns:
%%% <alleyright>column1<alleyleft><downrulethik><alleyright><column2><alleyleft>
%    \begin{macrocode}
\newcommand{\rjl@process@article}{
  \stepcounter{rjl@maxcols}
  \setlength{\newsartwidth}{\newscolwidth}
  \forloop{rjl@col@count}{1}{\value{rjl@col@count}<\value{rjl@maxcols}}{
    \ifthenelse{\value{rjl@mincols} > \value{rjl@col@count}}{}{
      \xdef\rjl@numcols{\therjl@col@count}
      \rjl@output@article
    }
    \addtolength{\newsartwidth}{\newscolwidth}
  }
  \addtocounter{rjl@maxcols}{-1}
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\rjl@process@article}
%
% This is called after every |rasterarticle|.
% In this personality, it determines and output the
% size of the article.
%
%    \begin{macrocode}
\newcommand{\rjl@process@article@raster}{
  \typeout{RASTER:WIDTH,HEIGHT: \the\newsartwidth,\the\vsize}%
}
%    \end{macrocode}
% \end{macro}
%
% \begin{environment}{newspaper}
%   |newspaper| takes no arguments.
%
%   |\rjl@today| is called to fix the |\today| command if the
%   |forcetoday| option is used; it does nothing otherwise.
%
%   The |rjl@artsplitboxcounter| is reset to 0 to prevent the
%   split-article routine from using up box registers indefinitely.
%
%   The output routine is changed to \@rjl@outgetheight, which
%   captures each article in turn. The initial page width and height
%   are captured, and restored at the end of the environment. This
%   accommodates the |article| environment, which changes the page
%   sizes as seen by the page builder.
%
%   At the start of the environment, we lay out the title into a
%   temporary box (|\rjl@junkbox|), then output the page size (minus
%   the title box's height and depth) for the C++ code to read in.
%    \begin{macrocode}
\newenvironment{newspaper}{
  \rjl@today
  \setcounter{rjl@artsplitboxcounter}{0}
  \sbox{\rjl@junkbox}{\maketitle\mbox{end of title}}
  \setlength{\rjl@tmplen}{\dimexpr\paperheight -\ht\rjl@junkbox -\dp\rjl@junkbox \relax}
  \typeout{PAGESIZE: \the\paperwidth,\the\rjl@tmplen}
  \setlength{\@rjl@realvsize}{\vsize}
  \output{\rjl@outgetheight}
}{
  \global\let\rjlnumcols\relax
  \setlength{\vsize}{\@rjl@realvsize}
}
\newlength{\rjl@tmplen}
%    \end{macrocode}
% \end{environment}
% 
% 
% \begin{macro}{\rjl@output@article}
% \marg{columns}
%   The |rjl@output@article| macro is where the main input work is done.
%   
%   The \TeX primitives |\hsize| and |\vsize| are set to a page size of
%   the width of |columns| columns by |\maxdimen|, which effectively tells the
%   page builder to build a single page as large as it can, at a width
%   of |\hsize|. The output mode registered in the |newspaper|
%   environment then takes care of cutting and pasting this text to form
%   the newspaper itself.
%
%   At the end of the |article|, a |\par| is used to enter vertical mode
%   mode (committing any text, graphics or maths to the current
%   paragraph), then an |\eject| is used to force the output routine
%   to be called.
%    \begin{macrocode}
\newcommand{\rjl@output@article}{
  \global\setlength{\hsize}{\dimexpr\newsartwidth-\alleyleft-\alleyright\relax}
  \setlength{\vsize}{\maxdimen}
  \parbox[t]{\dimexpr\newsartwidth-\alleyleft-\alleyright\relax}{%
    \rjl@output@headlines@common%
    \rjl@output@article@common%
  }
  \mbox{\textbf{ENDOFART}} % sets the depth of the box
  \eject
}
%    \end{macrocode}
% \end{macro}
% 
%
% \DescribeMacro{\rjl@outgetheight} Gets the height of an output page
% (an article) and writes it to standard output.
%
% This is mostly plain \TeX\ as there aren't many equivalent \LaTeX
% \textbackslash box commands. First, we |\unvbox| the output box~255 into a junk
% box; this uses up box~255 to maintain the output routine's sanity
% check, discarding the entire output, and also strips any ``discardable
% space'' from the end of the page added by the |\eject|.
%
% Then, we can simply measure the length of the junk box to get the page
% height, which is output to the C++ program using |\typeout|.
%    \begin{macrocode}
\newcommand{\rjl@outgetheight}{%
  \setbox\rjl@junkbox\vbox{\unvbox\@cclv} %
  \typeout{COLS,WIDTH,HEIGHT,FILE: \rjl@numcols,\the\newsartwidth,\the\ht\rjl@junkbox,\theartfile}%
}
%    \end{macrocode}
%
%
%
% \DescribeMacro{\@rjl@output@art@tmp}
% \DescribeMacro{\@rjl@junkbox}
%   Box registers are allocated for use by the output routine.
%
%   |\@rjl@output@art@tmp| is used to store a temporary copy of the
%   entire typeset article in order to work out the optimal headline
%   width.
%
%   |\rjl@junkbox| is used to store the entire article supplied to the output
%   routine, so we can measure it's height.
%    \begin{macrocode}
\newbox\@rjl@output@art@tmp
\newbox\rjl@junkbox
%    \end{macrocode}
% 
%    \begin{macrocode}
}{%
\typeout{Generating the final document}%
%    \end{macrocode}
%
% \subsection{Generating the final document}
% The above pair of braces match the |\@ifundefined| just after
% |\ProcessPackageOptions|.
% We now begin the second identity of this document class; the form
% that outputs the final page.
%
% Our only dependency is |eso-pic|, which is used by |rjl@xy|. It's
% likely this will be taken out in future and an |\output|-hook used
% instead; however, it will be important to maintain compatibility
% with existing packages that provide an |\output|-hook.
%
%    \begin{macrocode}
\RequirePackage{eso-pic}
%    \end{macrocode}
%
%
% We assume there is a file named |\jobname.lay| which contains all
% the layout instructions. All we need to do is to define the commands
% used in this file for the duration of the |newspaper| environment,
% read in the articles, then at the end read in |\jobname.lay|.
%
% There are a number of solutions for this. I think I'm going to try
% first the |everypage| package as defined at
% |https://tex.stackexchange.com/questions/169808/what-are-the-ways-to-position-things-absolutely-on-the-page\5F#answer-169831|
%
%
% When processing articles, we need to store the layout information
% for later use in typesetting.
% We define a new counter, |rjl@art@counter|, which stores the number
% of articles processed.
% For each article, we define new commands |\rjl@headline|\textit{N},
% |\rjl@subhead|\textit{N} and |\rjl@artfile|\textit{N} to store the
% variables for later use.
% This is done using \TeX primitives for brevity, and for better control over
% where things are expanded.
%    \begin{macrocode}
\newcounter{rjl@art@counter}%
\setcounter{rjl@art@counter}{0}%
\newcommand{\rjl@process@article}{%
  \edef\rjl@theartid{\arabic{rjl@art@counter}}%
  \expandafter\xdef\csname rjl@headline\rjl@theartid\endcsname{\theheadline}%
  \expandafter\xdef\csname rjl@subhead\rjl@theartid\endcsname{\thesubhead}%
  \expandafter\xdef\csname rjl@artfile\rjl@theartid\endcsname{\theartfile}%
  \stepcounter{rjl@art@counter}% 0-based counter
}
%    \end{macrocode}
%
% \begin{macro}{\rjl@process@article@raster}
% To store a raster for reuse, we set the flag |\rjl@raster<id>| to
% the name of a box register. We use the same set of boxes as
% the |splitarticle| environment as these are already cleaned up at
% the end of each page.
%    \begin{macrocode}
\newcommand{\rjl@process@article@raster}{%
  \edef\rjl@theartid{\roman{rjl@art@counter}}%
  \stepcounter{rjl@artsplitboxcounter}%
  \xdef\rjl@splitboxrm{\roman{rjl@artsplitboxcounter}}%
  \@ifundefined{rjl@splitbox@\rjl@splitboxrm}{%
    \expandafter\newsavebox\csname rjl@splitbox@\rjl@splitboxrm\endcsname%
  }{}%
  \global\expandafter\setbox\csname rjl@splitbox@\rjl@splitboxrm\endcsname\vbox{\usebox{\rjl@parabox}}%
  \expandafter\xdef\csname rjl@raster\rjl@theartid\endcsname{rjl@splitbox@\rjl@splitboxrm}%
  \stepcounter{rjl@art@counter}% 0-based counter
}
%    \end{macrocode}
% \end{macro}
%
% \subsection{Coordinate System}
% The coordinates of the output are given as $x$ and $y$ coordinates,
% with the origin placed at the top of the article grid, just below
% the heading, to the right of the left margin. The positive $x$
% dimension is to the right and the positive $y$ dimension is down.
%
% Thus anything with a negative $x$ dimension will be off the page,
% and anything with a negative $y$ dimension will be overtyping the
% title.
%
% \DescribeMacro{\rjl@pageTopMargin}
% This length is set to a negative value equal to $0-h$, where $h$ is
% the height of the title box, including its depth. This is used by
% |rjl@xy| to position elements relative to the bottom of the title,
% which is the coordinate system of the layout file. It is set to
% |0pt| here and decreased once the title is laid out.
%    \begin{macrocode}
\newlength{\rjl@pageTopMargin}
\setlength{\rjl@pageTopMargin}{0in}
%    \end{macrocode}
%
% \begin{macro}{\rjl@xy}
% \oarg{pre-tokens}
% \marg{x}
% \marg{y}
% \marg{macro}
% Outputs the contents of \marg{macro} at the coordinates
% \marg{x},\marg{y} during the output routine. The \oarg{pre-tokens},
% if any, are expanded during the output routine before the
% coordinates are evaluated; this is useful to call the macro
% repeatedly using different values in a length register; because the
% output is delayed until the |\shipout| runs, the registers end up
% with the same value, so this parameter can be used to update the
% register's value before each macro call.
%
%    \begin{macrocode}
\newcommand{\rjl@xy}[4][]{%
 \AddToShipoutPictureFG*{\AtPageUpperLeft{\smash{#1}%
     \hspace*{\dimexpr #2\relax}% NB: starts at \hoffset
  \raisebox{\dimexpr\rjl@pageTopMargin-#3\relax}{#4}}}}% NB: starts at \voffset
%    \end{macrocode}
% \end{macro}
%
% The |eso-pic| package is used to define commands similar to
% the |\atxy| command described by this
% example\footnote{|https://tex.stackexchange.com/questions/169808/what-are-the-ways-to-position-things-absolutely-on-the-page\#answer-169831|}.
% The |everypage| didn't work out; it shifted everything an inch to
% the right; unsure why. This soluction was based on this example\footnote{https://tex.stackexchange.com/questions/30177/how-can-i-add-text-in-the-top-right-corner-of-a-page-without-using-fancyhdr\#answer-30185}.
%
% 3 commands are defined in this way:
% \begin{itemize}
% \item |\halley| typesets a horizontal rule. Arguments are (all as
% length units):
%  \begin{itemize}
%  \item Y coordinate of alley
%  \item X coordinate of left end
%  \item X width
%  \end{itemize}
% \item |\valley| typesets a downrule. Arguments are (all as
% length units):
%  \begin{itemize}
%  \item X coordinate of alley
%  \item Y coordinate of bottom end
%  \item Y height
%  \end{itemize}
% \item |\doarticle| typeset the article contents in a
% rectangle. Downrules are placed automatically between columns. Arguments are:
%  \begin{itemize}
%  \item article ID (numeric counter)
%  \item X coordinate of left edge (length unit)
%  \item Y coordinate of top edge (length unit)
%  \item Width (length unit)
%  \item Height in points (length unit)
%  \item Number of columns
%  \end{itemize}
% \end{itemize}
%
% You may be wondering why |\valley| refers to the bottom of the rule
% instead of the top. This is because |\rule| creates a line extending
% above the given coordinate, and it's easier to write out the bottom
% edge than to calculate the length in \TeX.
%
% Note to self: \cs{smash} taxes one argument, retains its ink, but
% sets the box component to 0-sized, thus allowing overtyping,
% according to the description at
% \texttt{https://www.tug.org/TUGboat/tb22-4/tb72perlS.pdf}. However,
% the \TeX Book says that, while it removes any depth, it only
% truncates the height to the current font size; it's intended for
% controlling the vertical layout of lines that contain items that
% extend above or below the normal line hight.
%
% We also add a tiny rubber length to |\baselineskip| and a slightly
% bigger one to |\parskip|; these help |multicol| to balance the last
% column. Note that |\parskip| default to |0pt plus 1pt| in |article|,
% but I found that more is often needed to help balance columns.
%
% We use a new length |\rjl@titleheight| to store the height of the title.
%    \begin{macrocode}
\newenvironment{newspaper}{%
  \rjl@today%
  \setlength{\hsize}{\paperwidth}%
  \setlength{\linewidth}{\paperwidth}%
  \setlength{\vsize}{\paperheight}%
  \setlength{\oddsidemargin}{0pt}%
  \setlength{\evensidemargin}{0pt}%
  \setlength{\leftmargin}{0pt}%
  \setlength{\rightmargin}{0pt}%
  \setlength{\topmargin}{0pt}%
}{%
  \input{\jobname.lay}
  \sbox{\rjl@junkbox}{\maketitle}%
  \setlength{\rjl@titleheight}{\dimexpr \ht\rjl@junkbox + \dp\rjl@junkbox \relax}%
  \addtolength{\rjl@pageTopMargin}{\dimexpr 0pt - \rjl@titleheight \relax}%
  \rjl@xy{0pt}{\dimexpr0pt - \dp\rjl@junkbox\relax}{\usebox{\rjl@junkbox}}%
%    \end{macrocode}
% The header boxes aren't put out by |\maketitle| as they depend on
% the size of the title box.
% Instead, we simply output the boxes half-way down the title page,
% and indented by the width of the boxes.
%    \begin{macrocode}
  \ifdefined\theLeftBoxText%
  \rjl@xy{\dimexpr \rjl@titleheight/2 \relax}{0pt}{
    \rjl@doheadbox{\theLeftBoxWidth}{\theLeftBoxHeight}{\theLeftBoxText}
  }
  \fi%
  \ifdefined\theRightBoxText%
  \rjl@xy{\dimexpr \paperwidth - \theRightBoxWidth - \rjl@titleheight - 2\hoffset \relax}{0pt}{%
    \rjl@doheadbox{\theRightBoxWidth}{\theRightBoxHeight}{\theRightBoxText}
  }%
  \fi%
  ~\eject % force page output; the actual content is done in page hooks.
}%
\newcommand{\rjl@doheadbox}[3]{
  \vspace{\dimexpr\voffset-\rjl@pageTopMargin\relax}\par
  \noindent\vbox to \dimexpr\voffset-\rjl@pageTopMargin\relax{ % pageTopMargin is negated and doesn't include voffset (which we need to for centring to look correct)
    \vspace{0pt} % 0-length line as aligns to baseline
    \vfill % center
    \noindent\fbox{\parbox[c][#2][c]{#1}{#3}}%
    \vfill % center
    \vspace{0pt} % 0-length depth to box
  }
}
\newlength{\rjl@titleheight}%
\newcommand{\halley}[3]{%
  \rjl@xy{%
    \dimexpr #2+\sideruleleft\relax}{#1}{\noindent\rule{%
      \dimexpr #3-\sideruleleft-\sideruleright\relax%
    }{\siderulethick}}}%
%    \end{macrocode}
% |\rjl@tmplen| is used to hold the length of each vertical alley. This is a
% workaround to the fact that the second argument of |\rjl@xy| is
% evaluated in horizontal mode, so |\dimexpr| can't be used
% there. Instead, the length is calculated in the first argument (which is
% evaluated first) and stored in this macro. We can't calculate it
% outside the macro (without a lot of messy |\expandafter| tags)
% because the processing of the |\rjl@xy| arguments are deferred until
% the page is laid out, so they'd all end up at the same width.
% There's probably a neater solution that could be obtained by
% rewriting |\rjl@xy| to expand its arguments immedately somehow.
%    \begin{macrocode}
\newlength{\rjl@tmplen}
\newcommand{\rjl@downrule}[1]{\noindent\rule{\downrulethick}{#1}}
\newcommand{\valley}[3]{%
  \rjl@xy[%
    \setlength{\rjl@tmplen}{\dimexpr #3-\downruletop-\downrulebottom\relax}% done here as global and evaled at pageout
  ]{#1}{%
    \dimexpr #2-\downrulebottom\relax}{\rjl@downrule{%{\noindent\rule{\downrulethick}{%
      \rjl@tmplen}}
}%
%    \end{macrocode}
%
% Note that some dimensions, like |\parindent|, need to be respecified
% when read in the output routine, or they default to |0.0pt|.
%    \begin{macrocode}
\newcommand{\doarticle}[6]{%
  \typeout{Doing article #1}%
  \rjl@xy{\dimexpr #2+\alleyright\relax}{\dimexpr #3+\alleybottom\relax}{%
    \parbox[t][\dimexpr #5-\alleytop-\alleybottom\relax][s]{%
      \dimexpr #4-\alleyleft-\alleyright\relax}{%
      \@ifundefined{rjl@raster\romannumeral#1}{%
        \renewcommand{\theheadline}{\csname rjl@headline#1\endcsname}%
        \renewcommand{\thesubhead}{\csname rjl@subhead#1\endcsname}%
        \renewcommand{\theartfile}{\csname rjl@artfile#1\endcsname}
        \xdef\rjl@numcols{#6}%
        \rjl@output@headlines@common%
        \rjl@output@article@common%
        \expandafter\let\csname rjl@headline#1\endcsname\relax%
        \expandafter\let\csname rjl@subhead#1\endcsname\relax%
        \expandafter\let\csname rjl@artfile#1\endcsname\relax%
      }{%
        % raster ``image''; just put out the box already rendered
        \edef\rjl@tmp{\csname rjl@raster\romannumeral#1\endcsname}
        \vspace*{\expandafter\dp\csname\rjl@tmp\endcsname}
        \expandafter\usebox\csname\rjl@tmp\endcsname
      }%
    }}%
%    \end{macrocode}
%
% intra-article downrules. These are currently set in the same way as
% normal downrules, but between article columns. The article has |#6|
% columns, so we need to place one at position $x_n = \#2 +
% \frac{\#4}{n+1} \forall n \in \{ 1 \mbox{..} (\#6-1) \}$
%
% This turns out to be quite fiddly, as we must past the correct
% values to the |\rjl@xy| macro, as it literally passes its values to
% the callback. This means we can't use a length register (like
% |\rjl@tmplen|) and pass it directly, as it could be modified several
% times before the page is output.
% Instead, we reimplement the downrule calculation here, with one box
% using \cs{hspace} struts to position the downrules.
%    \begin{macrocode}
  \rjl@xy[\rjl@calcheadheight]{%
    #2}{% we take \alleyright out because it's already in the column sep
    \dimexpr #3+#5-\downrulebottom\relax}{%
    \forloop{rjl@col@count}{1}{\value{rjl@col@count}<#6}{%
      \hspace{\dimexpr #4/#6\relax}%
      \rjl@downrule{\dimexpr #5 - \downruletop - \downrulebottom -\rjl@headheight -\alleybottom -\alleytop \relax}%
    }%
  }%
}
%    \end{macrocode}
%
%\begin{environment}{splitarticle}
% \marg{articleId} article ID (numeric counter)
% \marg{width} column width
% \marg{cols} number of columns
% The |splitarticle| environment is a more expressive form of |\doarticle|,
% which allows the caller to break away from the fixed-rectangle
% approach of laying out articles.
%
% The text is still typeset in columns, but each column is placed
% separately, and the |.lay| file must list downrules between columns
% explicitly.
%
% The headline is typeset seperately from the article body with the
% dimensions provided in the |\artheadline| command.
%
% The |multicols| option does not apply to this format.
%
% Implementation: First read the article into |\rjl@parabox| in the
% same way as |rjl@multicols|. Each column will split off and typeset
% a section of the document, as |rjl@multicols| does, except that it
% will typeset it at the given coordinates instead of building up a
% box to expand to.
%    \begin{macrocode}
\newenvironment{splitarticle}[3]{
  \renewcommand{\theartfile}{\csname rjl@artfile#1\endcsname}%
  \setlength{\rjl@colwidth}{\dimexpr #2-\alleyright-\alleyleft-\downrulethick\relax}%
  \setlength{\rjl@oldhsize}{\hsize}%
  \setlength{\rjl@oldvsize}{\vsize}%
  \xdef\rjl@numcols{#3}%
  \vsize=\maxdimen\hsize=\rjl@colwidth%
  \setbox\rjl@parabox\vbox{%
    \rjl@output@article@common@lengths%
    \input{\theartfile}}%
  \setlength{\hsize}{\rjl@oldhsize}%
  \setlength{\vsize}{\rjl@oldvsize}%
%    \end{macrocode}
%
% \begin{macro}{\artheadline}
% \marg{x-left}
% \marg{y-top}
% \marg{width}
% \marg{height}
%
% Simply outputs the headline for the article. Specifying the height
% doesn't centre the title by itself.
%    \begin{macrocode}
  \renewcommand{\artheadline}[4]{
    \rjl@xy{\dimexpr ##1+\alleyright\relax}{\dimexpr ##2+\alleybottom\relax}{%
      \parbox[t][\dimexpr ##4-\alleytop-\alleybottom\relax][s]{%
        \dimexpr ##3-\alleyleft-\alleyright\relax}{%
        \renewcommand{\theheadline}{\csname rjl@headline#1\endcsname}%
        \renewcommand{\thesubhead}{\csname rjl@subhead#1\endcsname}%
        \rjl@output@headlines@common%
      }
    }
  }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\artcolumn}
% \marg{x-left}
% \marg{y-top}
% \marg{height}
% Each column is typeset seperately with a specific |\artcolumn|
% command.
%    \begin{macrocode}
  \renewcommand{\artcolumn}[3]{
    \setlength{\rjl@boxlength}{\dimexpr ##3-\alleytop-\alleybottom\relax}%
    \stepcounter{rjl@artsplitboxcounter}
    \xdef\rjl@splitboxrm{\roman{rjl@artsplitboxcounter}}%
    % create a new savebox register if we don't already have one defined:
    \@ifundefined{rjl@splitbox@\rjl@splitboxrm}{%
      \expandafter\newsavebox\csname rjl@splitbox@\rjl@splitboxrm\endcsname%
    }{}%
    % TeX primative \setbox needed for \global to work, for box to still be set at end of page...
    %\rjl@splitcol% also outputs intra-column spacing, but that should be okay.
    %\global\expandafter\setbox\csname rjl@splitbox@\rjl@splitboxrm\endcsname\hbox{\rjl@splitcol}
    \rjl@splitcol@{rjl@splitbox@\rjl@splitboxrm}%
    \expandafter\rjl@artout\expandafter{\rjl@splitboxrm}%
               {##1+\alleyright}{##3-##2+\alleybottom}%
               {\dimexpr ##3-\alleytop-\alleybottom\relax}
  }%
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\rjl@artout}
% \marg{boxname} without leading rjl@splitbox@
% \marg{xpos} (evaluated inside |\dimexpr|\dots|\relax|)
% \marg{y-bottom} (evaluated inside |\dimexpr|\dots|\relax|)
% \marg{height} length to stretch box to
%
% This macro performs the actual |rjl@xy| call. It is in a seperate
% macro for the |\expandafter| magic in |\artcolumn| to work, so that
% the actual name of the box register is passed to the |\rjl@xy|,
% allowing the |\rjl@splitboxrm| macro to be reused on the next
% column.
%    \begin{macrocode}
  \renewcommand{\rjl@artout}[4]{
    \rjl@xy[%
      \xdef\rjl@splitbox{rjl@splitbox@##1}%
    ]{##2}{##3}{%
      \parbox[t][##4][s]{%
        \dimexpr \rjl@colwidth - \alleyleft - \alleyright\relax}{%
        \expandafter\usebox\csname\rjl@splitbox\endcsname}%
    }%
  }
%    \end{macrocode}
% \end{macro}
%
%    \begin{macrocode}
}{
%  \expandafter\let\csname rjl@headline#1\endcsname\relax%
%  \expandafter\let\csname rjl@subhead#1\endcsname\relax%
%  \expandafter\let\csname rjl@artfile#1\endcsname\relax%
  \renewcommand{\artheadline}[4]{\PackageError[rjlnewsp4.dtx]{\protect\artcolumn
      not allowed outside article environment}}
  \renewcommand{\artcolumn}{\PackageError[rjlnewsp4.dtx]{\protect\artcolumn
      not allowed outside article environment}}
  \renewcommand{\rjl@artout}[4]{}
}
\newcommand{\artheadline}[4]{\PackageError[rjlnewsp4.dtx]{\protect\artcolumn
    not allowed outside article environment}}
\newcommand{\artcolumn}{\PackageError[rjlnewsp4.dtx]{\protect\artcolumn
    not allowed outside article environment}}
\newcommand{\rjl@artout}[4]{}
%    \end{macrocode}
%
% End of the giant |\@ifundefined| that switches between sizing
% and layout mode.
%    \begin{macrocode}
}
%    \end{macrocode}
% \end{environment}
%
% \begin{macro}{rjl@artsplitboxcounter}
% This counter counts the number of box register macros that have been
% allocated to boxes to use in the |splitarticle| environment.
% The only way I can see to push a box onto the page at exact
% coordinates is to use the |rjl@xy| macro with |\usebox|, meaning
% each individual column needs its own box register for
% placement. Under \LaTeXe, there are many more box registers available
% than original~\TeX; however, they are still a limited resource. So
% we clear the boxes after each page and reset this counter.
%
% NB: \TeX\ seems not to provide a way to clear a box register, so
% instead, we merely reset the counter and allow boxes to be
% reused. The \textit{content} of the boxes are cleared by |\usebox|.
%
% As of time of writing, we only support one page, so the
% |\setcounter| is done inside the |newspaper| environment, which
% sort-of represents a page.
%    \begin{macrocode}
\newcounter{rjl@artsplitboxcounter}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\rjl@calcheadheight}
%
% this sets the length |\rjl@headheight| to
% the height of the headline, which is used when typesetting each
% article to set the length of the intrarticle downrules, so they
% don't overtype the heading.
%
%    \begin{macrocode}
\newcommand{\rjl@calcheadheight}{%
  \sbox{\rjl@headbox}{%
    \parbox{\textwidth}{%
      \rjl@output@headlines@common%
    }%
  }%
  \global\setlength{\rjl@headheight}{\ht\rjl@headbox}%
  \global\addtolength{\rjl@headheight}{\dp\rjl@headbox}%
}
\newsavebox\rjl@headbox
\newlength{\rjl@headheight}
\setlength{\rjl@headheight}{0pt}
%    \end{macrocode}
% \end{macro}
%
% \section{Typesetting the Title}
%
% Newspaper tend to use banner titles; that is, the top few inches of
% the first page is wholly given over to the title. There may also be
% headers and footers on subsequent pages, for footnotes, page
% numbers, repeating the name of the newspaper and so on.
%
% For now, we will define various title-like parameters, each with two
% macros. The macro |\foo| will take one parameter, set to the tokens
% to use as that value, and the macro |\thefoo| will produce this
% value. The exception to this is |\title| and |\@title| which are
% predefined by \LaTeX.
%
% The command |\maketitle| will produce the title; it will be called
% automatically.
%
% We do not define |\title|; this is given in |latex.ltx|
%    \begin{macrocode}
\gdef\@title{No title given}
%\renewcommand{\title}[1]{\renewcommand{\@title}{#1}}
%
\newcommand{\theedition}{Use ``\textbackslash edition'' to set the edition}
\newcommand{\edition}[1]{\renewcommand{\theedition}{#1}}
%
\newcommand{\thereleasedate}{Use ``\textbackslash releasedate'' to set the releasedate}
\newcommand{\releasedate}[1]{\renewcommand{\thereleasedate}{#1}}
%
\newcommand{\theeditor}{Use ``\textbackslash editor'' to set the editor}
\newcommand{\editor}[1]{\renewcommand{\theeditor}{#1}}
%
\newcommand{\theprice}{Use ``\textbackslash price'' to set the price text}
\newcommand{\price}[1]{\renewcommand{\theprice}{#1}}
%
\newcommand{\theIssuestring}{Issue \#\theedition, \thereleasedate}
%
\newcommand{\theFFooter}{}
\newcommand{\firstfooter}[1]{\renewcommand{\theFFooter}{#1}}
\newcommand{\theFooter}{}
\newcommand{\pagefooter}[1]{\renewcommand{\theFooter}{#1}}
\newcommand{\theHeader}{}
\newcommand{\pageheader}[1]{\renewcommand{\theHeader}{#1}}
%
\newcommand{\theAddress}{  \textbf{Newsdesk} \par Use ``\textbackslash address'' to set your contact details}
\newcommand{\address}[1]{\renewcommand{\theAddress}{#1}}
%
\newcommand{\theSubtitle}{}
\newcommand{\subtitle}[1]{\renewcommand{\theSubtitle}{#1}}
%
\newcommand{\copyr}[1]{\newcommand{\theCopyright}{#1}}
\newcommand{\copystring}{% NB: this copyright notice is designed to be legally valid in as many
% countries as possible.
  \ifdefined\theCopyright{Copyright \copyright\ \thereleasedate\ \theCopyright, All Right Reserved}\fi%
}
%
\newcommand{\theLeftBoxHeight}{38pt}
\newcommand{\theLeftBoxWidth}{1in}
\newcommand{\leftboxText}[1]{\newcommand{\theLeftBoxText}{#1}}
%
\newcommand{\theRightBoxHeight}{38pt}
\newcommand{\theRightBoxWidth}{1in}
\newcommand{\rightboxText}[1]{\newcommand{\theRightBoxText}{#1}}
%
\newlength{\titlemargin}\setlength{\titlemargin}{5pt}
\newlength{\titlelineskip}\setlength{\titlelineskip}{5pt}
% maketitle must return a box:
\newcommand{\maketitle}{%
  \parbox{\textwidth}{%
    \vspace*{\titlelineskip}
    \centerline{\Huge \@title}%
    \vspace*{\titlelineskip}%
    \ifthenelse{\equal{\theSubtitle}{}}{}{\vspace{2pt}\centerline{\theSubtitle}\vspace{\titlelineskip}}%
    \centerline{\theIssuestring}%
    \vspace*{\titlelineskip}%
    \raisebox{0pt}[0pt][0pt]{\centerline{Editor: \theeditor}}%
    \llap{\raisebox{0pt}[0pt][0pt]{\parbox{\textwidth}{\hspace*{\titlemargin}\copystring\hfill}}}%
    \llap{\raisebox{0pt}[0pt][0pt]{\parbox{\textwidth}{\hfill\theprice\hphantom{\hspace*{\titlemargin}}}}}%
    \vphantom{\theeditor\copystring\theprice}%
    \vspace*{\titlelineskip}%
  }%
}
%    \end{macrocode}
% \subsection{Breaking articles into columns}
%
% This can be done well using the |multicols| package; this provides
% excellent column balancing (especially with large objects within the
% article text) and support for footnotes, the |\columnbreak| command
% and various configuration parametecrs.
%
% However, |multicols| expects to output the resulting multi-column
% text directly onto the page; it does not supply access to the
% individual columns once they are laid out\footnote{It would be
% technically possible to access |multicol|'s internal box registers,
% but then |rjlnewsp4| would become vulnerable to changes
% in the |multicol| package definition, so this is not desirable}, and
% it is limited to boxes of equal width.
%
% The current implementation of |rjl@multicols| is also limited to
% boxes of equal width; however, it is trivial to supply a list of
% lengths instead to allow columns of different lengths to be
% supplied. This would allow an article to be broken into a
% non-rectangular area of the page.
%
% \DescribeMacro{rjl@paracounter} The counter |rjl@paracounter| is a
% loop counter holding the current column \textit{within the current
% article}. It starts at 1 and workis its way up to $n-1$, where $n$
% is the number of columns into which the current article will be
% broken. (The final column is handled separately after the loop.)
%
% \DescribeMacro{rjl@para@cols} The counter |rjl@para@cols| is used to
% hold the number of columns. We use a dedicated counter for this
% because we can't access |#1| in horizontal mode due to
% \LaTeXe\ limitations.
%    \begin{macrocode}
\newcounter{rjl@paracounter}
\newcounter{rjl@para@cols}
%    \end{macrocode}
%
% \DescribeMacro{\rjl@parabox}\DescribeMacro{\rjl@parabox@}
% |\rjl@parabox| is a box register into which we read the entire article
% contents. As we loop through each column, the text is split out of
% |\rjl@parabox| into a |\rjl@parabox@| until |\rjl@parabox| holds the
% text for the final column.
%    \begin{macrocode}
\newsavebox{\rjl@parabox}
\newsavebox{\rjl@parabox@}
%    \end{macrocode}
%
% \DescribeMacro{\rjl@boxlength} Length |\rjl@boxlength| Holds the
% text height of each column.
%
% \DescribeMacro{\rjl@oldhsize}\DescribeMacro{\rjl@oldvsize}
% |\rjl@oldhsize| and |\rjl@oldvsize| hold the |\hsize| and |\vsize|
% value to be restored at the end of the environment. This isn't
% strictly necessary, but good \TeX\ hygene.
%
% \DescribeMacro{\rjl@colwidth} |\rjl@colwidth| is a length register
% holding the text width. |\hsize| is set to this during the
% environment to ensure that the columns are captured with the correct
% width. This could be done entirely with |\dimexpr| expressions, but
% that would make the macro much harder to read.
%    \begin{macrocode}
\newlength{\rjl@boxlength}
\newlength{\rjl@oldhsize}
\newlength{\rjl@oldvsize}
\newlength{\rjl@colwidth}
%    \end{macrocode}
%
% \begin{macro}{\rjl@multicols}
% \marg{numCols}; the number of columns to break the environment
% into.
%
% This macro currently works the same as |multicols| from the
% |multicol| package in terms of its interface.
%
% In the start of the macro, we first set some save registers and then
% wrap the environment itself in a |\setbox| to store the environment
% content.
%
% At the end of the enviroment, we first issue a |\linebreak|. This
% ensures that we're not set on the same line as a sub-headline.
%
% We then issue a |\noindent|. This prevents \TeX from moving the
% article as if it were a paragraph to be indented.
%
% We then restore |\hsize| and |\vsize|, so that everything we do is
% working on the full page again.
%
% Next we use |\mbox\bgroup|, with a corresponding |\egroup| at the
% very end; this ensures that everything we output is connected
% together into one big horizontal box, and stops \TeX\ from helping
% us by moving a column onte a new ``line'' if things get too wide for
% |\hsize|.
%
% Then we use |forloop| to call |\rjl@splitcol| repeatedly for each
% column other than the last. This outputs the column of text itself.
%
% Finally we output whatever remains in |\rjl@parabox| to output the
% final column. We wrap this in a plain \TeX\ |\vbox| to force the
% height (especially with more columns, there may be fewer lines in
% the final column, so this stretches the text to fit). If the
% unbalance option is specified, we also add a |\vfill|. We wrap the
% |\vbox| in a plain \TeX\ |\hbox| to force the width, just in case
% anything is a significantly different horizontal size; this means
% we'll get an \textit{overfull \textbackslash hbox} warning if appropriate.
%    \begin{macrocode}
\newenvironment{rjl@multicols}[1]{%
  \setcounter{rjl@para@cols}{#1}% can't access #1 in horizontal mode, so grab it first
  \setlength{\rjl@colwidth}{\dimexpr\newscolwidth-\alleyright-\alleyleft-\downrulethick\relax}% for readability
  \setlength{\rjl@oldhsize}{\hsize}%
  \setlength{\rjl@oldvsize}{\vsize}%
  \vsize=\maxdimen\hsize=\rjl@colwidth%
  \setbox\rjl@parabox\vbox\bgroup%
}{\egroup%
  \linebreak\noindent%
  \setlength{\hsize}{\rjl@oldhsize}%
  \setlength{\vsize}{\rjl@oldvsize}%
  \setlength{\rjl@boxlength}{\dimexpr \dp\rjl@parabox + \ht\rjl@parabox \relax}%
  \setlength{\rjl@boxlength}{\dimexpr \rjl@boxlength / \value{rjl@para@cols} \relax}%
  \mbox\bgroup%
  \forloop{rjl@paracounter}{1}{\value{rjl@paracounter}<\value{rjl@para@cols}}{%
    \rjl@splitcol%
  }%
  \hbox to \rjl@colwidth{\vbox to \rjl@boxlength{\unvbox\rjl@parabox%
      \@ifundefined{rjl@unbalance}{}{\vfill}%
  }}%
  \hspace{-1in}% silence overfull hbox warnings
  \egroup%
}
%    \end{macrocode}
% \end{macro}
% 
% 
% \begin{macro}{\rjl@splitcol}
% This is used by the |\rjl@multicols| environment to break each
% column. It simply performs a plain \TeX\ |\vsplit| command to split
% off one column from |\rjl@parabox| into |\rjl@parabox@|, then
% outputs it, followed by the intra-column spacing.
%
% |\splittopskip| is a \TeX\ primitive glue automatically added to the
% top of the split-off vbox; we seem to trash the |\topskip| at the
% top of the article quite effectively, so we also set this to 0 so
% that the columns line up at the top edge. A plain-\TeX assignment is
% used to keep the length modification local to this group.
%
% |\splitmaxdepth| is another \TeX\ primitive affecting |\vsplit|; it
% sets a maximum limit on the height of the split-off material, so
% we'll set that to |\maxdimen| in another local assignment.
%    \begin{macrocode}
\newcommand{\rjl@splitcol}{%
  \splittopskip=0pt%
  \splitmaxdepth=\maxdimen%
  \setbox\rjl@parabox@=\vsplit\rjl@parabox to \rjl@boxlength%
  \hbox to \rjl@colwidth{\usebox{\rjl@parabox@}}\hspace{\alleyleft}\hspace{\downrulethick}\hspace{\alleyright}%
}
% \begin{macro}{\rjl@splitcol@}
% \marg{boxname}
% This alternate form saves to the box with the given name (excluding slash)
% and does not include spaces.
% The save is global; the caller must ensure that the box is cleared eventually
% if the memory is to be reclaimed.
%    \begin{macrocode}
\newcommand{\rjl@splitcol@}[1]{%
  \splittopskip=0pt%
  \splitmaxdepth=\maxdimen%
  \setbox\rjl@parabox@=\vsplit\rjl@parabox to \rjl@boxlength%
  \global\expandafter\setbox\csname#1\endcsname=\hbox to \rjl@colwidth{\usebox{\rjl@parabox@}}
}
%    \end{macrocode}
% \end{macro}
%
% \subsection{Postamble}
% Tidy up: make @ not a letter again
%    \begin{macrocode}
\makeatother
%    \end{macrocode}
% 
% \section{Licence}
% \input{lppl-1-3c.tex}
%
% \Finale
\endinput

% \endinput
% Local Variables: 
% mode: doctex
% TeX-master: "test.tex"
% End: