% out.tex copyright 1992/3 Victor Eijkhout
%              copyright 2014--2016 Vafa Khalighi
%
%
%    This program is free software: you can redistribute it and/or modify
%    it under the terms of the GNU General Public License as published by
%    the Free Software Foundation, either version 3 of the License, or
%    (at your option) any later version.
%
%    This program is distributed in the hope that it will be useful,
%    but WITHOUT ANY WARRANTY; without even the implied warranty of
%    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
%    GNU General Public License for more details.
%
%    You should have received a copy of the GNU General Public License
%    along with this program.  If not, see <http://www.gnu.org/licenses/>.
%
%
\Chapter[chap:output] Output

Every page is formatted according to a `page grid' consisting of
three elements:

\Enumerate \item the page head, this is everything that's over the
running text;
\item the page foot, this is everything that is below the running
text;
\item the running text. \TeX\ acts as if text is on a long scroll,
and the running text part of a page is simply a portion cut off from
this scroll.\>
Either or both of the head and foot of the page can be empty, but
usually one of the two contains a page number.

\OutExample
\OptionsMacro:ManPageSize=raggedbottom:10pt topskip:12pt
 height:page=5cm width:page=6cm Stop
\DefinePageGrid:TestPage macro:ManPageSize
 pagerule textband:start text textband:stop
 pagerule band:start PageCounter band:stop Stop
\TestPage 
This page does not contain much special.\EjectPage
This page is hardly better.
\OutExampleStop

This example illustrates how you first define a page grid by
\refcs{DefinePageGrid}, and then activate it by calling its name. That
last action is in fact not necessary: each definition of a page grid
automatically installs that grid as the current one.

\Section Page dimensions

Most of the time it is easiest to specify the total height of a page,
that is, including head and bottom, but sometimes it is more
convenient to specify the height of the text, and let the head and
foot simply go over and under that.

In the first case you can give the command \refcs{Height} with
two parameters:
\Ver>\Height:Page=23.5cm<Rev or inside a page grid definition the
option \refopt{height}\n{:page=...}.

In the second case you can give the command
\Ver>\Height:Text=19.55cm<Rev or inside a page grid definition the
option \opt{height:text=...}.

In page grid definitions there is the additional option
\opt{height:lines=23}.

The \cs{Height} command cannot be used in a page grid definition.

\Section Positioning the page on the paper

If your printer driver is up to specs (and you have not done any
creative macro writing) it should have the upper left corner of the
text landing at $2.54$cm from the top and left side of the paper.
If the result is not to your liking, you can shift the page by
\Ver>\Distance:hoffset= ...
\Distance:voffset= ...<Rev
These offset parameters are zero ordinarily, and they indicate the
extra shift added to the customary $2.54$cm in horizontal and
vertical direction.
 
\Section Page head, foot, text

Somewhere in the page grid the option \refopt{text} has to appear. This
option has to be inside a \refopt{textband}:
\Ver>    textband:start text textband:stop<Rev
This is not a case of overspecification, because inside a textband
the text option can appear more than once. In this manner a multicolumn
page grid can be specified.

\def\sometext{Just a bit of words, words. }
\edef\sometext{\sometext\sometext\sometext}
\edef\sometext{\sometext\sometext\sometext\sometext}
\OutExample
\DefinePageGrid:TestPage macro:ManPageSize
 pagerule textband:start text hwhite:10pt text textband:stop
 pagerule band:start PageCounter band:stop Stop
\FlushRight:no \sometext
\OutExampleStop

Next to the option \opt{textband} there is \refopt{band}.
Both are ways of
creating a page wide band. The option \opt{band} is used for all
material that is not a text column, for instance footers, as in the
above examples.

The option \opt{band} can have one unusual parameter: \n{invisible}.
This makes the band act as if it has zero height or width, depending
on whether it is below or above the text, respectively.

\OutExample
\DefinePageGrid:TestPage macro:ManPageSize
 pagerule textband:start text hwhite:10pt text textband:stop
 pagerule 
 band:invisible block:start Style:bold PageCounter Spaces:2
     stickout:left band:stop Stop
\FlushRight:no \sometext
\OutExampleStop
 
\SubSection More about text bands

The text band is that part of the page that has the text in it. You can
also put other material in it, such as rules or white space.

\OutExample 
\DefinePageGrid:TestPage macro:ManPageSize pagerule 
 textband:start vrule white:3pt text white:3pt vrule textband:stop 
 pagerule band:start white:fillup PageCounter band:stop Stop
\TestPage This page contains some text, a bit more text,
and even more than that. In all still just a few lines.\EjectPage
This page contains more text, still more text, and still more. 
\OutExampleStop

In the previous example the width of the page was specified.
If we only give the width of the text, the page width is calculated
dynamically. 

\OutExample 
\DefinePageGrid:TestPage macro:ManPageSize
 textband:start vrule white:3pt text white:3pt vrule textband:stop
 pagerule band:start white:fillup PageCounter band:stop Stop
\noindent This page contains some text, a bit more text,
and even more than that. In all still just a few lines.\EjectPage
This page contains more text, still more text, and still more. 
\OutExampleStop

Note how the \refopt{pagerule} and \opt{band} objects stretch
with the page.


\SubSection Topskip

In between the page head and the text is some white space, the
topskip, with special properties. The topskip is defined from the
bottom of the head to the bottom of the first line of the text. If
the height of this first line varies from page to page the topskip
acts as a buffer, keeping the bottom-to-bottom distance constant.

Topskip is set by the option \refopt{topskip}, for example
\Ver>    topskip:25pt<Rev
but if this option is left out, the page grid uses the value of
\cs{topskip} that was current at the time of the definition.
Unfortunately there is no way to change this value after the definition.

\Section[sec:page-counter] The page number

The page number behaves as if it had been defined by
\Ver>\NewCounter:Page
\CounterRepresentation:Page=1<Rev
Thus you can use any command from section~\ref[sec:counters] on it.
For instance, you can have page numbers in roman numerals by 
specifying
\Ver>\CounterRepresentation:Page=I<Rev

The page number is typically used as the option \refopt{PageCounter},
but for some applications the corresponding command \refcs{PageCounter}
can be used.

If you process a \Lollipop\ document you see that everytime a page is
generated, an item such as \ver>[8,7]> is written on the log file or the
screen. Most of the time the two numbers will be the same, as in
\ver>[8,8]>, but they will differ if you have tinkered with the page
number. The first number is the `sheet counter': it counts how many
pages you have produced so far. The second number is the value of
\cs{PageCounter} for the page that was written out. Take a look at the
log file for this manual for an example.

\Section[sec:page:tests] Page tests

The page grid definition can set/query several properties of the
page. The following tests have been provided (see
section~\ref[sec:tests] for tests):
\Ver>\DefineTest:IsRightPage
\DefineTest:IsLeftPage
\DefineTest:FirstPage
\DefineTest:LastPage
\DefineTest:FlushBottom<Rev
\Itemize\item The tests for left/right pages are done by
 testing whether the page number of odd or even.
\item The first/last page tests can be used either for the whole
document, or for a file that's loaded as an \cs{InputFile}.
\item The first page test doesn't work at present.
\>

\OutExample
\DefinePageGrid:TestPage macro:ManPageSize
 pagerule textband:start text textband:stop pagerule
 band:start ifIsLeftPage else hwhite:fillup fi PageCounter 
     band:stop Stop \SetCounter:Page=12
This is a left hand page. \EjectPage 
This page is on the right side of a spread. 
\OutExampleStop

\Section[sec:head/foot] Running heads / footers

Above it was explained how pages can be given a head and foot part.
Quite often you want changing information in such parts, for instance
the head of a left page often contains the number or title of section
that was current when that page started; the head of a right page
often contains the number or title of the section that was current
when that page ended.

In \Lollipop\ all constructs that have a title or a counter can have
that information referenced in page grids.
\Description\item \refcs{FirstPlaced}:SectionTitle
Take the title of the first section that started on this page, or
the last one that started before this page if no section started on
this page.\item \refcs{LastPlaced}:SubSectionCounter
Take the title of the last subsection that started on this page, or
the last one that started before this page if no subsection started
on this pgae.\item \refcs{PreviousPlaced}:SectionCounter
Take the counter value of the last section that started before this
page.\>

\OutExample
\DefinePageGrid:TestPage macro:ManPageSize
 pagerule textband:start text textband:stop pagerule 
 band:start Style:italic FirstPlaced:HeadTitle
            white:fillup PageCounter band:stop Stop
\DefineHeading:TestHeading Style:bold 
 line:start TestHeadingCounter Spaces:2 title line:stop Stop
\TestHeading A first section\par And some text.\EjectPage
This page contains text. \TestHeading A second Section\par
And more text.
\OutExampleStop

The commands \cs{FirstPlaced} and \cs{PreviousPlaced} are typically
used on left pages; \cs{LastPlaced} is more common on right pages.
You can test on what sort of page you are; see
section~\ref[sec:page:tests].

\OutExample
\DefinePageGrid:TestPage macro:ManPageSize
 pagerule textband:start text textband:stop pagerule 
 band:start Style:italic 
     ifIsLeftPage FirstPlaced:HeadTitle white:fillup fi
     PageCounter
     ifIsRightPage white:fillup LastPlaced:HeadTitle fi
     band:stop Stop \SetCounter:Page=10
\DefineHeading:TestHeading Style:bold 
 line:start TestHeadingCounter Spaces:2 title line:stop Stop
\TestHeading A first section\par And some text.
\TestHeading Second section\par More text.\EjectPage
\TestHeading Third section\par Is on the right page.
\TestHeading Fourth section\par Concludes this page.
\OutExampleStop


\Section Alternating page grids

In \Lollipop\ it is very easy to switch page grids with the option
\refopt{NextPageGrid}: you simply specify
 \Ver>    NextPageGrid:otherpage<Rev as one of the options
in the definition. If no next grid is indicated, the same page grid keeps
being used continuously until another page grid is activated
explicitly.

\OutExample
\DefinePageGrid:LTestPage macro:ManPageSize
 pagerule textband:start text textband:stop pagerule 
 band:start Style:italic
     PageCounter white:fillup FirstPlaced:HeadTitle   
     band:stop NextPageGrid:RTestPage Stop
\DefinePageGrid:RTestPage macro:ManPageSize
 pagerule textband:start text textband:stop pagerule 
 band:start Style:italic 
     LastPlaced:HeadTitle white:fillup PageCounter
     band:stop NextPageGrid:LTestPage Stop
\SetCounter:Page=42
\DefineHeading:TestHeading Style:bold 
 line:start TestHeadingCounter Spaces:2 title line:stop Stop
\LTestPage
\TestHeading A first section\par And some text.
\TestHeading Second section\par More text.\EjectPage
\TestHeading Third section\par Is on the right page.
\TestHeading Fourth section\par Concludes this page.
\OutExampleStop

Another very useful application of this mechanism is to have a
special definition for the opening page of a chapter. This manual uses a
one-shot page grid \cs{EmptyPage} to remove the header and footer on the
title page. It installs \cs{LeftPage} as the next grid.

\Section Additional User Control

\SubSection Elementary manipulation

There are a few commands for simple page manipulation:
\Description\item \refcs{EjectPage}
The current page is filled up with white space, and
a new page is started.\item \refcs{ToRecto}
As \cs{EjectPage} but if the next page is a left page (meaning
that the page number is even) then the page number is increased by
one, so that the next page is a right hand page.\item \refcs{ToVerso}
As \cs{ToRecto}, except that the next page is a left page.
\>

Additionally, \refcs{NoPages} lets
all formatting and updating of values be performed, but
no pages are written to the dvi file;
\refcs{PagesOut}
reverts the effect of previous command. Note that \cs{NoPages} does not
incur any savings in time: full processing of the document is performed.
 
When a page is finished it rests in box \refcs{WholePage}. Then a call is
made  to \refcs{CurrentShipout}, which is by default
\ver>\shipout\box\WholePage>. However, you are free to define it
otherwise. If your \cs{CurrentShipout} does not actually ship out pages,
you may want to set \refcs{CountSheetsno} to prevent the effective page
counter from being updated.

Redefining \cs{CurrentShipout} usually goes together with
\refcs{SuspendOutput} and \refcs{ResumeOutput}. These commands
temporarily save the page number and the current state of the page,
including the current definition of \cs{CurrentOutput}. (This is necessary
because a number of parameters concerned are changed by global
assignments.) See the definition of \cs{OutputExample} in the appendix of
this manual for an elaborate example. 

If you want to see te output routines in action, specify
\Ver>\Trace:out<Rev In addition \Ver>\Trace:mark<Rev tells you what
information is being saved for running head and foot lines.

\endinput

% 2014/04/12 Made `output' capitalized.
% 92/11/20 Left right output examples
% 93/01/17 New description of \CurrentShipout