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