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