% out.tex copyright 1992/3 Victor Eijkhout % copyright 2014 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 . % % \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\Height:Text=19.55cm\Distance:hoffset= ... \Distance:voffset= ... textband:start text textband:stop topskip:25pt\NewCounter:Page \CounterRepresentation:Page=1\CounterRepresentation:Page=I[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 \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 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\Trace:mark