diff options
Diffstat (limited to 'macros/plain/formats/lollipop/doc/manual/out.tex')
-rw-r--r-- | macros/plain/formats/lollipop/doc/manual/out.tex | 349 |
1 files changed, 349 insertions, 0 deletions
diff --git a/macros/plain/formats/lollipop/doc/manual/out.tex b/macros/plain/formats/lollipop/doc/manual/out.tex new file mode 100644 index 0000000000..23dab4395d --- /dev/null +++ b/macros/plain/formats/lollipop/doc/manual/out.tex @@ -0,0 +1,349 @@ +% 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 |