summaryrefslogtreecommitdiff
path: root/macros/plain/formats/lollipop/doc/manual/out.tex
diff options
context:
space:
mode:
Diffstat (limited to 'macros/plain/formats/lollipop/doc/manual/out.tex')
-rw-r--r--macros/plain/formats/lollipop/doc/manual/out.tex349
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