diff options
author | Karl Berry <karl@freefriends.org> | 2014-04-24 17:50:01 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2014-04-24 17:50:01 +0000 |
commit | cbfc368620bf1ec89c0feff3230ec1c082999975 (patch) | |
tree | 5a5f99b91bb93f046950a9f4b48880c7b09de987 /Master/texmf-dist/doc/otherformats | |
parent | 6e7d419dedc358b0393e9318e9b338168004bcd8 (diff) |
lollipop, new format
git-svn-id: svn://tug.org/texlive/trunk@33658 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/otherformats')
22 files changed, 5209 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/otherformats/lollipop/README b/Master/texmf-dist/doc/otherformats/lollipop/README new file mode 100644 index 00000000000..51cc0b3cd3e --- /dev/null +++ b/Master/texmf-dist/doc/otherformats/lollipop/README @@ -0,0 +1,80 @@ +About Lollipop and its manual. + +You have obtained a package containing the Lollipop format +and its manual. + + +The manual uses only Computer Modern, but there are a few +lines in `lollipop-manual.tex' that allow you to switch easily to Times +and Helvetica on Macintosh and Unix systems. + +The manual is a pretty good illustration of the power of +Lollipop, but there is also a file 'address.tex' which +contains example macros for an address book. + +Lollipop is still under development. The manual contains +some remarks about what is still to be done. If you have any +questions, remarks, suggestions (or if you want to voice +your appreciation :-) , feel free to contact me: + + Vafa Khalighi + persian-tex@tug.org + +Here is how much of TeX's memory you used: + 1194 strings out of 495844 + 16212 string characters out of 6190699 + 74602 words of memory out of 5000000 + 3495 multiletter control sequences out of 15000+600000 + 11241 words of font info for 40 fonts, out of 8000000 for 9000 + 19 hyphenation exceptions out of 8191 + 27i,4n,24p,187b,448s stack positions out of + 5000i,500n,10000p,200000b,80000s +Output written on lollipop-manual.pdf (59 pages, 334502 bytes). + + +History so far: + +0.9 October 1992, first public release + +0.91 Unannounced update + TeX3 based lolplain + penalties and white space in embedded constructs + splittopskip set equal to topskip + +0.92 November 1992, update for friends and family + Copyright notices added + math family setting for \rm, \bf, \tt + bugs in penalties corrected + +0.93 December 1992, official update + Lots of nobreaks in pre/post-tex material of constructs + Synonym counters repaired + Topskip and raggedbottom in state of repair + +0.94 December 1992, unofficial update + Adaptive distances + +0.95 January 1993, unofficial update + Short titles, rewritten external files, + address book example format. + +0.97 4 April 2014, organized and updated + files and also generated various formats. + +0.98 6 April 2014, changed all lollipop filenames + to start with `lollipop' prefix, and fixed typewriter font. + +0.99 9 April 2014, improved ini files, and the error in + address.tex example fixed. + +1.00 11 April 2014, updated lollipop-plain.tex and manual. + +1.01 12 April 2014, Updated lollipop-text.tex (changed "#1 cs to \"#1 cs + to be compatible with plain; also we can not make + " active since it is used by xetex for font selection, new ini + file xelollipop.ini + +1.02 16 April 2014, Updated lollipop-text.tex (defined \EveryParagraph, + \EveryMath, and \EveryDisplay), defined \PointSizeScriptSizes:12 + +1.03 19 April 2014, Fixed the wrong numbering of nested enumerate lists
\ No newline at end of file diff --git a/Master/texmf-dist/doc/otherformats/lollipop/lollipop.tex b/Master/texmf-dist/doc/otherformats/lollipop/lollipop.tex new file mode 100644 index 00000000000..842b0123407 --- /dev/null +++ b/Master/texmf-dist/doc/otherformats/lollipop/lollipop.tex @@ -0,0 +1,129 @@ +% lollipop.tex; master file for the Lollipop tex format. +% This file and all input files and all files for the manual +% (with the exception of hyphen.tex and btxmac.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 <http://www.gnu.org/licenses/>. +% +% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%%%%%%%%%%%%%%%% L O L L I P O P T E X %%%%%%%%%%%%%%%%%% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% +% o +% L O L L I P O P +% | | +% +\catcode`\@=11 + +\input lollipop-plain + +\input lollipop-tools + +\input lollipop-define + +\input lollipop-fonts +\input lollipop-fontdefs + +\input lollipop-text + +\input lollipop-document + +\input lollipop-heading + +\input lollipop-output + +\input lollipop-float + +\input lollipop-lists + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\frenchspacing +\showboxdepth=7 \showboxbreadth=300 +\errorcontextlines=\maxdimen + +\let\willbeunhskip\unhskip + +\Typeface:ComputerModern +\Pointsize:10 +\Style:bold \Style:slant \Style:italic \Style:roman + +\Distance:verbatimwhiteleft=levelindent +\Distance:verbatimwhitebefore={0pt plus 1pt} +\Distance:verbatimwhiteafter={0pt plus 1pt} + +%\tracingmacros=2\tracingcommands\tracingmacros +\DefineTextBlock:Ver + whitebefore:verbatimwhitebefore whiteafter:verbatimwhiteafter + breakbefore:200 breakafter:-100 + whiteleft:verbatimwhiteleft + command:vVer text Stop + +\DefinePageGrid:RightPage height:page=8in width:page=5in + textband:start text textband:stop + vwhite:12pt + band:start PageCounter band:stop + Stop +\RightPage + +\hyphenation{Eijk-hout dis-cre-tio-na-ry al-ign-ment met-hod + met-hods} + +% v0.9 First public release October 1992 +% v0.91 TeX3 based lolplain, penalties in embedded constructs, +% splittopskip +% v0.92 Copyright notices added, math family setting, +% bugs in penalties corrected +% v0.93 Nobreaks in constructs, synonym counters, start floats +% v0.94 Adaptive distances and counters +% v0.95 BibTeX, short titles, improved external handling, +% \CurrentOutput changed +% v0.96 repair: counters, ToExternal, option:title=Smthng, +% changed copyright status! fontdefs file, late externals +% EmptyList -> IsEmp... +% +% v0.97 Update and organized files and generated various +% formats for Lollipop. +% +% v0.98 Changed filenames; the new filename has now +% "lollipop-" prefix, and fixed typewriter font. +% +% v0.99 Improved ini files, and the error in address.tex +% example fixed. +% +% v1.00 Updated lollipop-plain.tex. +% +% v1.01 Updated lollipop-text.tex (changed "#1 cs to \"#1 cs +% to be compatible with plain; also we can not make +% " active since it is used by xetex for font selection, +% new ini file xelollipop.ini +% +%v1.02 Updated lollipop-text.tex (defined \EveryParagraph, +% \EveryMath, and \EveryDisplay), defined +% \PointSizeScriptSizes:12 +% +%v1.03 Fixed the wrong numbering of nested enumerate lists +% +\edef\fmtname{\lolli@name}%defined in Tools +\def\fmtversion{v1.03, 19 April 2014} +\append@to@list{everyjob}{\message{ +>>>> This is Lollipop TeX (\fmtversion) <<<<}} + +\makeatother +\errorstopmode +\endinput diff --git a/Master/texmf-dist/doc/otherformats/lollipop/manual/address.tex b/Master/texmf-dist/doc/otherformats/lollipop/manual/address.tex new file mode 100644 index 00000000000..26da950a505 --- /dev/null +++ b/Master/texmf-dist/doc/otherformats/lollipop/manual/address.tex @@ -0,0 +1,187 @@ +% address book macros +% copyright 1993 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 <http://www.gnu.org/licenses/>. +% +% +% These macros are based on the Lollipop macro package, +% copyright 1992/3 Victor Eijkhout +% copyright 2014 Vafa Khalighi +% +% Format this file twice to get external files right. +% + +% Some general options. +% Please use another typeface if you have it! +% +\Distance:whitebefore=0pt \Distance:whiteafter=0pt +\AlwaysIndent:no \FlushRight:no +%\TypeFace:macHelvetica \PointSize:7 \Style:roman +\TypeFace:ComputerSans \PointSize:8 \Style:roman +\def\\{,\Spaces:1 } + +% The page is four columns, no footers etc +% +\DefinePageGrid:ThePage width:page=6.5in height:page=5in + textband:start text white:10pt text white:10pt + text white:10pt text textband:stop Stop + +% The main macro is the text block \Entity, representing one item +% in the address book. +% +\DefineTextBlock:Entity HasTitle:short + whitebefore:{6pt plus 6pt minus 3pt} whiteafter:whitebefore + line:start rule:v={height 7pt width7pt depth0pt} Spaces:2 + Style:italic title line:stop Stop + +% Data in an entity is formatted as a number of headings. +% We declare all headings to be embedded, ie, they form a paragraph. +% The 'nomarks' option is to prevent memory overflow. +% +\OptionsMacro:embed=embedded:yes nomarks + whitebefore:0pt whiteafter:0pt Stop +\DefineHeading:phone HasTitle:short macro:embed + literal:phone : Spaces:1.5 title , Spaces:2 Stop +\DefineHeading:fax HasTitle:short macro:embed + literal:fax : Spaces:1.5 title , Spaces:2 Stop +\DefineHeading:Address HasTitle:short macro:embed + title , Spaces:2 Stop +\DefineHeading:Note HasTitle:short macro:embed + ( title ) Spaces:2 Stop + +% Here's an example of non-standard handling of the title: +% email addresses are set in \tt, and can be broken differently +% +\def\breakemail{\hyphenchar\font=`. } +\DefineHeading:email HasTitle:short macro:embed + begingroup tt breakemail title endgroup , Spaces:2 Stop + +% This is invisible information; maybe later we'll do something +% with it. +\DefineHeading:Route HasTitle:short Stop + +% Here is the first really cute application. +% If a person is declared to be \At a certain company, then +% that fact is written out to an external file, which can be loaded +% later. +% +\DefineExternalFile:companies=ats +\def\WorksAt{Works at: } +\DefineHeading:At macro:embed + HasTitle:short WorksAt title Spaces:2 + external:companies title unhskip title:Entity unhskip external:stop Stop +% When the 'companies' file gets loaded the title only gets +% parsed by the macro \CompNam, and nothing else happens. +% The title is split into company and person; #1 becomes the name +% of a list to which #2 is added. +% +\def\CompNam#1\unhskip#2\unhskip{ + \if\UndefinedCS{#1}\NewList:{#1} \fi + \AppendToList:#1={#2\unhskip, } } +\DefineExternalItem:At file:companies + expandafter CompNam title Stop +% The company lists are later simply loaded; see below. + +% Even more complicated: birthdays. +% All birthdays are written to an external file. +% +\DefineExternalFile:births=brt +\DefineHeading:birthday HasTitle:short macro:embed + literal:Born : title Spaces:2 + external:births title unhskip title:Entity unhskip external:stop Stop +% Later every month becomes something like an entity; +% here is how we generate a token list for each month. +% +\def\month#1{\ifcase#1\or jan\or feb\or mar\or apr\or may\or jun\or + jul\or aug\or sep\or oct\or nov\or dec\fi} +\tempcounta=1 \loop\ifnum\tempcounta<13 + \xp\NewList\xp:\xp{\month\tempcounta} + \advance\tempcounta1 \repeat +% Formatting the caboodle means: +% -- loading the 'births' file +% -- formatting each month separately by \OneMonth +% which is essentially a call to the text block \Month +% +\def\AllBirths{\LoadExternalFile:births + \tempcounta=1 \loop\ifnum\tempcounta<13 + \OneMonth \advance\tempcounta1 \repeat} +\def\OneMonth{\xp\Month\month\tempcounta\par + \TheList:{\month\tempcounta} \>} +% Month is much like \Entity, just a bit different visually. +% +\DefineTextBlock:Month + whitebefore:{6pt plus 6pt minus 3pt} whiteafter:whitebefore + line:start rule:v={height 7pt width7pt depth0pt} Spaces:2 + Style:italic title Spaces:2 + fillup rule:v={height 7pt width7pt depth0pt} line:stop + Stop +% When the external file is loaded, every birthday is processed +% by \BirNam which splits it into #1 year #2 month #3 day and +% #4 person's name. This is then written to the list for the +% appropriate month. +% +\def\BirNam#1 #2 #3\unhskip #4\unhskip + {\tempcounta#2\relax + \AppendToList:{\month\tempcounta}={\JollyFellow #3 #4 (#1)\par} + } +\DefineExternalItem:birthday file:births + expandafter BirNam title Stop +\DefineHeading:JollyFellow title nomarks Stop + +% Phooeew! Now we can get down to business! + +\WriteExtern:yes +\Start +\LoadExternalFile:companies + +\Entity Adam Aardvark +\Address Page~1, English Language Dictionary +\> + +\Entity Barbara Beeton +\At Tugbt +\Note Editor in chief +\> + +\Entity Jane Doe +\email doe@re.mi.sol +\> + +\Entity John Doe +\phone +1 212 555 4141 +\> + +\Entity Victor Eijkhout +\Address Department of Computer Science, University of Tennessee +\phone +1 615 974 8298 +\At Tugbt +\Note merely associate editor +\email eijkhout@cs.utk.edu +\birthday 1959 11 29 +\> + +\Entity Elvis Presley +\birthday 1938(?) 01 08 +\> + +\Entity Tugboat +\TheList:Tugbt +\> + +\AllBirths + +\Stop + diff --git a/Master/texmf-dist/doc/otherformats/lollipop/manual/appendix.tex b/Master/texmf-dist/doc/otherformats/lollipop/manual/appendix.tex new file mode 100644 index 00000000000..80a998443fd --- /dev/null +++ b/Master/texmf-dist/doc/otherformats/lollipop/manual/appendix.tex @@ -0,0 +1,69 @@ +% appendix.tex copyright1992 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 <http://www.gnu.org/licenses/>. +% +% +\Chapter Example styles + +To show you the strength of \Lollipop, this chapter collects a few +example style definitions. The first one is that of this manual. + +\Section The style definition for this book + +In case you were wondering how this book was typeset, here is the +full style definition. By the standards of what Lollipop can do it is +pretty pedestrian. + +One thing that may have provide intellectual titilation is the +definition of \cs{Example} and \cs{OutExample}. +It allowed me to keep the examples in sync with their output. + +Of course that +doesn't really rely on \Lollipop. It does illustrate the fact that +\Lollipop\ is interfaceable to arbitrary macros. (But don't try +loading \Lollipop\ on top of \LaTeX! On second thought, do. It +disables most of \LaTeX. Just kidding.) + +\begingroup \PointSize:8 \tt +\verbatimfile{mandefs.tex}\endgroup + +\Section[sec:address] Address book + +The following macros generate an address book. Several noteworthy +features: +\Itemize\item Most titles are short, that is, delimited by the line +end. + \item Since a page will now have several dozens of headings, the +number of marks placed will become a problem, therefore the option +\opt{nomarks} is included everywhere. Without this you would easily +have memory overflows. + \item The \cs{At} heading writes its information to an external +file. This is then parsed by the macro \cs{CompNam}. A~slight amount +of knowledge of Lollipop internals is used here for parameter parsing, +but not more than can be gleaned from simply looking at the external +file.\par + Then a token list is created for each company, and these lists are +printed somewhere down the file. This is a bit of \TeX\ programming +that is not quite elementary, but still \Lollipop saves you a lot of +work. + \> +If you want to see the output, run \TeX\ with Lollipop twice on the +\file{address.tex} file. + + \begingroup \PointSize:8 \tt +\verbatimfile{address.tex}\endgroup + +\endinput
\ No newline at end of file diff --git a/Master/texmf-dist/doc/otherformats/lollipop/manual/btxmac.tex b/Master/texmf-dist/doc/otherformats/lollipop/manual/btxmac.tex new file mode 100644 index 00000000000..3093ed1a833 --- /dev/null +++ b/Master/texmf-dist/doc/otherformats/lollipop/manual/btxmac.tex @@ -0,0 +1,812 @@ +%% @texfile{ +%% author = "Karl Berry and Oren Patashnik", +%% version = "0.99h", +%% date = "24 Apr 1991", +%% filename = "btxmac.tex", +%% address = "Please use electronic mail", +%% checksum = "812 4053 30557", +%% email = "opbibtex@neon.stanford.edu", +%% codetable = "ISO/ASCII", +%% supported = "yes", +%% docstring = "Defines macros that make BibTeX work with plain TeX", +%% } +% BibTeX-for-TeX macros, version 0.99h, for BibTeX 0.99c, TeX 3.0 or later. +% Copyright (C) 1990--91 by Karl Berry and Oren Patashnik; all rights reserved. +% You may copy this file provided: that it's accompanied by the +% "BibTeXing" document, whose text is contained in the file `btxdoc.tex'; +% that any documentation you write for these macros also gives a +% reference for "BibTeXing"; and that either you make absolutely no +% changes to your copy, or if you do make changes, (1) you name the file +% something other than `btxmac.tex' and you remove all occurrences of +% `btxmac.tex' from the file, (2) you put, somewhere in the first twenty +% lines of the file, your name, along with an electronic address at which +% others who might use the file may reach you, and (3) you remove each +% occurrence of Oren's name and electronic address from this file. These +% restrictions help ensure that all standard versions of these macros are +% identical, and that Oren doesn't get deluged with inappropriate e-mail. +% +% This file, btxmac.tex, contains TeX macros that allow BibTeX, a +% bibliography program that was originally designed for use with LaTeX, +% to work with plain TeX. Please report any bugs (outright goofs, +% improvable macros, misfeatures, or unclear documentation) to Oren +% Patashnik (opbibtex@neon.stanford.edu). These macros will become +% frozen shortly after BibTeX version 1.00 is released. +% +% To use these macros you should be familiar with how BibTeX interacts +% with LaTeX, since BibTeX's interaction with TeX is very similar; that +% interaction is explained in the LaTeX manual. It also helps to +% have read "BibTeXing", the documentation that accompanies BibTeX. +% Then, if you want, you should redefine any of the macros that begin +% with `\bbl' or `\biblabel' or `\print' that you need to get formatting +% different from the default (the default settings are designed to +% accompany a bibliography style like BibTeX's standard style `plain'). +% The macros you might want to change are described briefly a few +% paragraphs hence. Finally, as long as you follow the guidelines given +% by the LaTeX manual and "BibTeXing", you simply \input btxmac. +% [Remember the general scheme: Running (La)TeX writes information on +% the .aux (auxiliary) file; then running BibTeX reads information from +% the .aux, .bst (style), and .bib (database) files, and writes +% information (the bibliography) on a .bbl file; then running (La)TeX +% incorporates the bibliography; then running (La)TeX once more fixes +% the remaining forward references into the bibliography. Thus, to get +% everything incorporated into your output, you'll have to run (La)TeX, +% BibTeX, (La)TeX, (La)TeX. (Standup, sitdown, fight, fight, fight.)] +% +% These macros can stand alone or they can be \input into macro packages +% like Eplain. If you want to try out these macros on the 0.99 version +% of the xampl.bib file that's distributed with BibTeX (that version of +% the file has no self-identification), you'll need to define \mbox, +% which is a LaTeX command, to be \hbox. +% +% +% HISTORY +% +% Karl Berry wrote the original version of these macros in 1989 and +% 1990, for use in his `Eplain' package. Oren Patashnik modified them +% slightly in July 1990, as part of the official BibTeX distribution. +% +% 1-Aug-90 Version 0.99a, not released to the general public. +% 14-Aug-90 0.99b, first general release. +% 26-Aug-90 0.99c, made \@undefinedmessage work with other macro packages. +% 6-Sep-90 0.99d, allowed for general formatting of bibliography labels, +% for general formatting of (in-text) citations, and for +% changing certain catcodes while reading the .aux file. +% 14-Nov-90 0.99e, changed the way \@setletters works, made some \new...'s +% non-outer, and changed the way Eplain reads this file. +% 12-Dec-90 0.99f, made \@resetnumerals change the `,' and `.' catcodes; and +% added \biblabelextrahang, \@getoptionalarg, and \bblsc. +% 11-Mar-91 0.99g, made a few minor changes required by the way Eplain reads +% this file, but no functional changes. +% 24-Apr-91 0.99h, inhibited the reading and writing of the .aux file if it +% isn't used or if the \noauxfile macro is defined, and +% removed some .aux-file-opening detritus; printed the +% cite-key of undefined citations in \tt font; changed the +% catcode of `_' inside \cite; and called \@resetnumerals +% from inside a group. +% +% +% The LaTeX-related commands defined in this file include (a) the four +% commands that a user types (\bibliography, \bibliographystyle, \cite, +% and \nocite); (b) the three commands that BibTeX looks for in the .aux +% file (\bibdata, \bibstyle, and \citation---there is a fourth command +% that BibTeX looks for, but that command is related to LaTeX's \include +% facility, so these macros ignore that command); and (c) a LaTeX +% command (\newcommand) that's written by one of the four standard +% bibliography styles (alpha). The definitions here are not exactly the +% same as the corresponding LaTeX definitions (those eight LaTeX +% definitions depend on a significant fraction of LaTeX itself). But +% the only substantial differences are with \newcommand, which here, +% without complaining, lets you redefine a preexisting control sequence +% (in LaTeX, \newcommand won't let you redefine a preexisting command), +% and which here doesn't make the control sequences it defines \long (in +% LaTeX, that happens automatically); there may also be other minor +% differences. To summarize: Unless you know what you're doing, you +% shouldn't define any control sequences with these eight names: +% +% \bibdata +% \bibliography +% \bibliographystyle +% \bibstyle +% \citation +% \cite +% \newcommand +% \nocite +% +% There are three other commands written by one or more of the four +% standard (plain, abbrv, alpha, unsrt) or four semistandard (acm, +% apalike, ieeetr, siam) bibliography styles; they take effect only +% within the bibliography, and are redefinable, as explained later: +% +% \em +% \newblock +% \sc +% +% There's one control sequence you might want to use (but not redefine) +% in redefining \biblabelprint: +% +% \biblabelwidth +% +% There are twelve other control sequences (explained later in more detail) +% that the macros of this file will use if you define them---you should +% define them after the \input btxmac command but before the \bibliography +% command. The first five begin with `\bbl' and affect fonts, spacing, +% and perhaps other characteristics of the bibliography; the next three +% begin with `\biblabel' and determine how labels are formatted in the +% bibliography; and the last four begin with `\print' and determine how +% the in-text citations are formatted: +% +% \bblem +% \bblhook +% \bblnewblock +% \bblrm +% \bblsc +% \biblabelcontents +% \biblabelextrahang +% \biblabelprint +% \printbetweencitations +% \printcitefinish +% \printcitenote +% \printcitestart +% +% If it's defined before the \input btxmac command, the control sequence +% below inhibits the reading and writing of the .aux file(s), and the +% issuing of related warning messages. Any definition will do. This +% feature might help when you're working on draft stages of a document: +% +% \noauxfile +% +% Here's another control sequence (it's described later), with an `@' +% in its name, that you probably won't want to redefine unless you are +% writing another macro package; if you do redefine it, however, do it +% before the \input btxmac command: +% +% \@undefinedmessage +% +% And here are still more control sequences that, should you already have +% them defined, might conflict with the way the btxmac.tex macros use them +% (but since each of these has an `@' in its name, it's unlikely that such +% conflicts will arise unless you intend them): +% +% \@auxfile \@auxfiledonefalse \@auxfiledonetrue +% \@bracketcheck \@citation \@cite +% \@citedef \@citelabel \@citewarningfalse +% \@citewarningtrue \@commandname \@continuenewcommand +% \@emptymarkA \@emptymarkB \@fileexistsfalse +% \@fileexiststrue \@finishcitedef \@finishtestfileexistence +% \@for \@forloop \@fornoop +% \@fortmp \@getoptionalarg \@@getoptionalarg +% \@gobble \@if@auxfiledone \if@citewarning +% \@ifempty \@@ifempty \if@fileexists +% \if@notfirstcitation \@iforloop \@innerdef +% \@innernewcount \@innernewdimen \@innernewif +% \@innernewwrite \@itemnum \@letter +% \@linenumber \@newcommandwithargs \@newcommand +% \@next \@nextwhile \@nil +% \@nnil \@notfirstcitationfalse \@notfirstcitationtrue +% \@numparams \@oldatcatcode \@onecitation +% \@optionalarg \@other \@paramdef +% \@readauxfile \@readbblfile \@resetnumerals +% \@scfont \@setletters \@spacesub +% \@startdef \@testfileexistence \@tokstostring +% \@ttsA \@ttsB \@ttsmarkA +% \@ttsmarkB \@undefined \@writeaux +% +% +% So to start things off we turn `@' into a letter (category code 11), +% keeping track of the old category code for future restoration. +% (Simply resetting it to 12 when we leave these macros is +% insufficient.) The use of `\cite' as a temporary control sequence is +% a kludge, but it's a reasonably simple way to accomplish what we need +% without possibly overwriting something (without an `@' in its name) +% that might already be defined. +% +\edef\cite{\the\catcode`@}% +\catcode`@ = 11 +\let\@oldatcatcode = \cite +\chardef\@letter = 11 +\chardef\@other = 12 +% +% +% Next come some things that will be useful later. +% +% Make an outer definition into an inner one (due to Chris Thompson). +% The arguments should be the control sequence to be defined, and the +% new of the \outer control sequence, as characters; the control +% sequence #1 is defined to be just the same as \csname#2\endcsname, but +% not \outer. For example, \@innerdef\innernewcount{newcount} would +% define \innernewcount to be a non-outer version of \newcount. +% +\def\@innerdef#1#2{\edef#1{\expandafter\noexpand\csname #2\endcsname}}% +% +% We use \@innerdef to make some of our allocations local, because +% Eplain includes our code inside a conditional. We put @'s in the +% names to minimize the (already small) chance of conflicts. +% +\@innerdef\@innernewcount{newcount}% +\@innerdef\@innernewdimen{newdimen}% +\@innerdef\@innernewif{newif}% +\@innerdef\@innernewwrite{newwrite}% +% +% +% Swallow one parameter. +% +\def\@gobble#1{}% +% +% +% Use TeX 3.0's \inputlineno to get the line number, for better error +% messages, but if we're using an old version of TeX, don't do anything. +% +\ifx\inputlineno\@undefined + \let\@linenumber = \empty % Pre-3.0. +\else + \def\@linenumber{\the\inputlineno:\space}% +\fi +% +% +% \@getoptionalarg\CS gets an optional argument from the input, enclosed +% in brackets, then expands \CS. We set \@optionalarg to \empty if we +% don't find one, otherwise to the text of the argument. This assumes +% the brackets don't have a funny category code. +% +\def\@getoptionalarg#1{\let\temp = #1\futurelet\next\@bracketcheck}% +\def\@bracketcheck{\begingroup + \if [\next + \aftergroup\@@getoptionalarg + \else + \global\let\@optionalarg = \empty + % + % We can't do the \aftergroup\temp after the \fi, because then the + % \temp gets in the way of reading the optional argument from the + % input, if we do have one. + \aftergroup\temp + \fi +\endgroup}% +% +\def\@@getoptionalarg[#1]{% + \def\@optionalarg{#1}% + \temp +}% +% +% +% \@tokstostring converts its argument into a list of character tokens. +% It uses no commands that are executed in the stomach, only expansions +% handled in the gullet. (This is necessary for use with \edef). +% +% Control sequences in the argument are not expanded. Blanks become a +% \spacesub. The argument shouldn't contain other special characters. +% +\def\@tokstostring#1{\@ttsA#1 \@ttsmarkA}% +% +% \@ttsA partitions a sequence of tokens into portions delimited by blanks. +% +\def\@ttsA#1 #2\@ttsmarkA{% + \@ifempty{#1}\else + \@ttsB #1\@ttsmarkB + % + \@ifempty{#2}\else + \@spacesub\@ttsA#2\@ttsmarkA + \fi + \fi +}% +% +% \@ttsB processes a sequence of tokens with no contained blanks. +% +\def\@ttsB#1{% + \ifx #1\@ttsmarkB\else + \string #1% + \expandafter\@ttsB + \fi +}% +% +% This is just so \ifx won't complain about an undefined control sequence. +% +\def\@ttsmarkB{\@ttsmarkB}% should never be expanded +% +% The expansion of this macro replaces spaces. +% +\def\@spacesub{+}% +% +% +% \@ifempty tests if it is given an argument. +% +\def\@ifempty#1{\@@ifempty #1\@emptymarkA\@emptymarkB}% +\def\@@ifempty#1#2\@emptymarkB{\ifx #1\@emptymarkA}% +% +\def\@emptymarkA{\@emptymarkA}% Again, so \ifx won't complain. +% +% +% From LaTeX. +% +\def\@nnil{\@nil}% +\def\@fornoop#1\@@#2#3{}% +% +\def\@for#1:=#2\do#3{% + \edef\@fortmp{#2}% + \ifx\@fortmp\empty \else + \expandafter\@forloop#2,\@nil,\@nil\@@#1{#3}% + \fi +}% +% +\def\@forloop#1,#2,#3\@@#4#5{\def#4{#1}\ifx #4\@nnil \else + #5\def#4{#2}\ifx #4\@nnil \else#5\@iforloop #3\@@#4{#5}\fi\fi +}% +% +\def\@iforloop#1,#2\@@#3#4{\def#3{#1}\ifx #3\@nnil + \let\@nextwhile=\@fornoop \else + #4\relax\let\@nextwhile=\@iforloop\fi\@nextwhile#2\@@#3{#4}% +}% +% +% +% This macro tests if a file \jobname.#1 exists, and sets +% \if@fileexists appropriately. If an optional argument is given, it is +% used as the root part of the filename instead of \jobname. +% +\@innernewif\if@fileexists +% +\def\@testfileexistence{\@getoptionalarg\@finishtestfileexistence}% +\def\@finishtestfileexistence#1{% + \begingroup + \def\extension{#1}% + \immediate\openin0 = + \ifx\@optionalarg\empty\jobname\else\@optionalarg\fi + \ifx\extension\empty \else .#1\fi + \space + \ifeof 0 + \global\@fileexistsfalse + \else + \global\@fileexiststrue + \fi + \immediate\closein0 + \endgroup +}% +% +% +%% [[[start of BibTeX-specific stuff]]] +% +% Now come the four main LaTeX commands and their associated .aux +% commands. Just as in LaTeX, \bibliographystyle defines the BibTeX +% style name (.bst file, that is), and \bibliography defines the +% database (.bib) file(s). The corresponding .aux-file commands are +% \bibstyle and \bibdata, which are there only for BibTeX's (but not +% LaTeX's) use. +% +\def\bibliographystyle#1{% + \@readauxfile + \@writeaux{\string\bibstyle{#1}}% +}% +\let\bibstyle = \@gobble +% +% As well as writing the \bibdata command to tell BibTeX +% which .bib files to read, we read the .bbl file that +% BibTeX (or a person, conceivably) has produced. +% +\def\bibliography#1{% + \@readauxfile + \@writeaux{\string\bibdata{#1}}% + \@testfileexistence{bbl}% + \if@fileexists + \@readbblfile + \fi +}% +\let\bibdata = \@gobble +% +% The \nocite{label,label,...} command writes its argument to \@auxfile, +% unless instructed not to, but produces no text in the document. Both +% the \nocite and \cite commands produce \citation commands in the .aux file. +% +\def\nocite#1{% + \@readauxfile + \@writeaux{\string\citation{#1}}% +}% +% +\@innernewif\if@notfirstcitation +% +% \cite[note]{label,label,...} produces the citations for the labels as +% well. If the optional argument `note' is present, it's added after +% the labels. Since \cite calls \nocite before doing any writing, it +% doesn't need to call \@readauxfile. We change the category code of +% `_' so that the dummy definition given to the citation label doesn't +% include a subcript character; that would cause TeX to complain. +% +\def\cite{\begingroup\catcode`_ = \@letter \@getoptionalarg\@cite}% +% +% Typeset the citations for the labels in #1, followed by the note, if +% it exists. To change the citation's format in the text, redefine one +% or more `\print...' macros, whose defaults appear later in this file. +% +\def\@cite#1{% + \nocite{#1}% + % Start printing the text, beginning with a left bracket by default. + % + \printcitestart + \@notfirstcitationfalse + \@for \@citation :=#1\do + {% + \expandafter\@onecitation\@citation\@@ + }% + \ifx\empty\@optionalarg\else + \printcitenote{\@optionalarg}% + \fi + \printcitefinish + \endgroup +}% +% +\def\@onecitation#1\@@{% + \if@notfirstcitation + \printbetweencitations + \fi + % + \expandafter \ifx \csname\@citelabel{#1}\endcsname \relax + \if@citewarning + \message{\@linenumber Undefined citation `#1'.}% + \fi + % Give it a dummy definition: + \expandafter\gdef\csname\@citelabel{#1}\endcsname{% + {\tt \nobreak\hskip0pt#1\nobreak\hskip0pt}}% + \fi + % Now produce the text, whether it was undefined or not. + \csname\@citelabel{#1}\endcsname + \@notfirstcitationtrue +}% +% +% Given a label `foo', the macro `\b@foo' is supposed to +% hold the text that should be produced. +% +\def\@citelabel#1{\@tokstostring{b@#1}}% +% +% So, how does a citation label get defined? When we read the .bbl file +% (below), a \bibitem writes out a \@citedef command. And when we read +% the \@citedef, we define \@citelabel{#1}, where #1 is the user's +% label. But we have to be careful when reading the \@citedef, because +% the second argument might have accents or other commands with numbers +% as arguments. We have given the numerals category code 11 for reading +% the .aux file, and that prevents them from being recognized as TeX +% <number>s. Similarly for the other characters that can be part of a +% <number>. So we have to reset the category codes before reading the +% second argument. We also have to reset them back to letters when we +% finish reading the \@citedef's, because there might be more labels +% with numerals in them defined afterwards in the .aux file, put there +% by Eplain or whatever. +% +\def\@citedef#1{% + \begingroup + \@resetnumerals + \@finishcitedef{#1}% +}% +\def\@finishcitedef#1#2{% + \expandafter\gdef\csname\@citelabel{#1}\endcsname{#2}% + \endgroup +}% +\def\@resetnumerals{% + \catcode`0 = \@other \catcode`1 = \@other \catcode`2 = \@other + \catcode`3 = \@other \catcode`4 = \@other \catcode`5 = \@other + \catcode`6 = \@other \catcode`7 = \@other \catcode`8 = \@other + \catcode`9 = \@other \catcode`" = \@other \catcode`' = \@other + \catcode`` = \@other \catcode`, = \@other \catcode`. = \@other +}% +% +% +% Reading the .bbl file also produces the typeset bibliography. Please +% notice, however, that we do not produce the title for the references +% (e.g., `References'), as LaTeX does. The formatting and spacing of +% that title, whether it should go into the headline, and so on, are all +% things determined by your format. We cannot know those things in +% advance. If you wish, you can define \bblhook to produce the title. +% Or just do it before the \bibliography command. +% +\def\@readbblfile{% + % Define a counter to tell us which item number we are on. + \@innernewcount\@itemnum + % + \begingroup + \def\begin##1##2{% + % ##1 is just `thebibliography'. + % ##2 is the widest label. + % We set (new dimen) \biblabelwidth based on the widest label + \setbox0 = \hbox{\biblabelcontents{##2}}% + \biblabelwidth = \wd0 + }% + \def\end##1{}% ##1 is `thebibliography' again. + % + % Here we have two possibilities: + % \bibitem[typesetlabel]{citationlabel} + % \bibitem{citationlabel} + % If we have the second of these, the citations are numbered, starting + % from one; we use our own count register \@itemnum for this. + % + \@itemnum = 0 + \def\bibitem{\futurelet\next\@bibitem}% + \def\@bibitem{% + \begingroup \if [\next + \aftergroup\@alphabibitem + \else + \aftergroup\@numberedbibitem + \fi \endgroup + }% + \def\@alphabibitem[##1]##2{% + % Need \xdef here for various reasons. + \expandafter \xdef\csname\@citelabel{##2}\endcsname {##1}% + \@finishbibitem{##2}% + }% + % + \def\@numberedbibitem##1{% + \advance\@itemnum by 1 + \expandafter \xdef\csname\@citelabel{##1}\endcsname{\number\@itemnum}% + \@finishbibitem{##1}% + }% + % + \def\@finishbibitem##1{% + \biblabelprint{\csname\@citelabel{##1}\endcsname}% + \@writeaux{\string\@citedef{##1}{\csname\@citelabel{##1}\endcsname}}% + \ignorespaces + }% + % + % Do the printing (we're producing the bibliography, remember). + % + \let\em = \bblem + \let\newblock = \bblnewblock + \let\sc = \bblsc + % Punctuation won't affect spacing; + \frenchspacing + % the penalties below are from LaTeX's [article,book,report].sty; + \clubpenalty = 4000 \widowpenalty = 4000 + % the next two values come from LaTeX's \sloppy command; + \tolerance = 10000 \hfuzz = .5pt + \everypar = {\hangindent = \biblabelwidth + \advance\hangindent by \biblabelextrahang}% + \bblrm + % the \parskip is a guess at what looks good; + \parskip = 1.5ex plus .5ex minus .5ex + % and the .5em matches the \enspace of \biblabelprint below. + \biblabelextrahang = .5em + \bblhook + % + \input \jobname.bbl + \endgroup +}% +% +% The widest label's width is useful for redefining \biblabelprint; you +% redefine \biblabelwidth, in effect, by redefining the +% \biblabelcontents macro that appears below. And \biblabelextrahang, +% which is redefinable inside \bblhook, is added to \biblabelwidth to +% determine the amount of hanging indentation. +% +\@innernewdimen\biblabelwidth +\@innernewdimen\biblabelextrahang +% +% Now come the main macros that are related to the printing of the +% bibliography. Since you might want to redefine them, they are given +% default definitions outside of \@readbblfile. +% +% The first one controls the printing of a bibliography entry's label. +% If you change it, make sure that it starts with something like +% \noindent or \indent that puts TeX into horizontal mode (even if the +% label itself is empty); otherwise, the hanging indentation will get +% messed up in certain circumstances. +% +\def\biblabelprint#1{% + \noindent\hbox to \biblabelwidth{\biblabelcontents{#1}\hss}\enspace}% +% +% By default the labels are typeset in \bblrm, and enclosed in brackets. +% +\def\biblabelcontents#1{\bblrm [#1]}% +% +% The main text, too, is typeset using \bblrm, which is \rm by default. +% +\def\bblrm{\rm}% +% +% Emphasis for producing, e.g., titles, is done with \it by default. +% +\def\bblem{\it}% +% +% Some styles use a caps-and-small-caps font for author names. LaTeX +% defines an \sc command but plain TeX doesn't, so we need one here. +% The definition below doesn't load the font unless it's needed, but it +% tries to load only the 10pt version, because it might not exist at +% other point sizes. +% +\def\bblsc{\ifx\@scfont\@undefined + \font\@scfont = cmcsc10 + \fi + \@scfont +}% +% +% The major parts of an entry are separated with \bblnewblock. The +% numbers below are taken from LaTeX's `article' style. +% +\def\bblnewblock{\hskip .11em plus .33em minus .07em}% +% +% Here's where you stick any other bibliography-formatting goodies, or +% redefine the values above. +% +\let\bblhook = \empty +% +% +% Here are the four default definitions for formatting the in-text +% citations. These are what you redefine (after your \input btxmac but +% before your \bibliography) to get parens instead of brackets, or +% superscripts, or footnotes, or whatever. +% +\def\printcitestart{[}% left bracket +\def\printcitefinish{]}% right bracket +\def\printbetweencitations{, }% comma, space +\def\printcitenote#1{, #1}% comma, space, note (if it exists) +% +% That scheme is pretty flexible. For example you could use +% \def\printcitestart{$^\bgroup} +% \def\printcitefinish{\egroup$} +% \def\printbetweencitations{,} +% \def\printcitenote#1{\hbox{\sevenrm\space (#1)}} +% to get superscripted in-text citations. To get something radically +% different, however, you'll have to define your own \cite command. +% +% When we read this from the .aux file, \citation means nothing. +% +\let\citation = \@gobble +% +% +% Now comes the stuff for dealing with LaTeX's \newcommand. As +% mentioned earlier, this \newcommand will redefine a preexisting +% command; that's different from how LaTeX's \newcommand behaves. +% +\@innernewcount\@numparams +% +% \newcommand{\foo}[n]{text} defines the control sequence \foo to have +% n parameters, and replacement text `text'. +% +\def\newcommand#1{% + \def\@commandname{#1}% + \futurelet\@next\@continuenewcommand +}% +% +% Figure out if this definition has parameters. +% +\def\@continuenewcommand{\begingroup + \if [\@next + \aftergroup\@newcommandwithargs + \else + \global\@numparams = 0 + \aftergroup\@newcommand + \fi +\endgroup}% +% +\def\@newcommandwithargs[#1]{% + \global\@numparams = #1 + \@newcommand +}% +% +% \@numparams is how many arguments this command has. The name of the +% command is \@commandname. The replacement text for the new macro is #1. +% +\def\@newcommand#1{% + \def\@startdef{\expandafter\edef\@commandname}% + \ifnum\@numparams=0 + \let\@paramdef = \empty + \else + \ifnum\@numparams>9 + \errmessage{\the\@numparams\space is too many parameters}% + \else + \ifnum\@numparams<0 + \errmessage{\the\@numparams\space is too few parameters}% + \else + \edef\@paramdef{% + % This is disgusting, but \loop doesn't work inside \edef, + % because \body isn't defined. + % + \ifcase\@numparams + \empty No arguments. + \or ####1% + \or ####1####2% + \or ####1####2####3% + \or ####1####2####3####4% + \or ####1####2####3####4####5% + \or ####1####2####3####4####5####6% + \or ####1####2####3####4####5####6####7% + \or ####1####2####3####4####5####6####7####8% + \or ####1####2####3####4####5####6####7####8####9% + \fi + }% + \fi + \fi + \fi + \expandafter\@startdef\@paramdef{#1}% +}% +% +%% [[[end of BibTeX-specific stuff]]] +% +% +% Names of references (arguments given in the \cite and \nocite +% commands) and file names (arguments given in the \bibliography and +% \bibliographystyle commands) are recorded in \jobname.aux, called the +% \@auxfile in these macros. Here's how they get read in. +% +\def\@readauxfile{% + \if@auxfiledone \else % remember: \@auxfiledonetrue if \noauxfile is defined + \global\@auxfiledonetrue + \@testfileexistence{aux}% + \if@fileexists + \begingroup + % Because we might be in horizontal mode when \@readauxfile + % is called (if it's in response to a \cite or \nocite), we + % want to ignore all the would-be spaces at the ends of + % lines in the aux file. Fortunately, there are never any + % (non-pathological) cases where an end-of-line might + % actually be desired. If you really need to do something + % strange, you can redefine \@setletters to do something + % besides what it does now (this is intentionally left as + % being somewhat painful to do). + \endlinechar = -1 + \@setletters + \input \jobname.aux + \endgroup + \else + \message{\@undefinedmessage}% + \global\@citewarningfalse + \fi + \immediate\openout\@auxfile = \jobname.aux + \fi +}% +% +% The \@readauxfile macro does all that work the first time it's called. +% Since it's called once for every \cite, \nocite, \bibliography, and +% \bibliographystyle command that the user issues, we need to remember +% whether the work's been done. It's considered done if we're not to do +% it---that is, if \noauxfile is defined. +% +\newif\if@auxfiledone +\ifx\noauxfile\@undefined \else \@auxfiledonetrue\fi +% +% Since lots of characters are allowable inside reference names, and +% since a reference name can get converted into a control sequence, +% \@readauxfile must treat many characters as letters. It does that by +% calling \@setletters, which changes the category code of all \@other +% characters to \@letter. The 128/256 business arises because character +% codes go up to 256 starting with TeX 3.0, but up to only 128 with +% earlier versions. +% +\def\@setletters{% + \count255 = 0 + \edef\temp{\ifx\inputlineno\@undefined 128\else 256\fi}% + \loop + \ifnum\catcode\count255 = \@other + \catcode\count255 = \@letter + \fi + \advance\count255 by 1 + \ifnum\count255<\temp + \repeat + % The Eplain package uses underscores to construct the label names. + \catcode`\_ = \@letter +}% +% +% It's conceivable you'd want to change how other characters are read; +% to do that, change their category code before doing \input btxmac. +% +% +% After reading the .aux file, \@readauxfile opens it for writing. +% The \@writeaux macro does the actual writing (as long as +% \noauxfile is undefined). +% +\@innernewwrite\@auxfile +\def\@writeaux#1{\ifx\noauxfile\@undefined \write\@auxfile{#1}\fi}% +% +% +% A macro package that uses btxmac.tex might define +% \@undefinedmessage (before doing an \input btxmac). +% +\ifx\@undefinedmessage\@undefined + \def\@undefinedmessage{No .aux file; I won't give you warnings about + undefined citations.}% +\fi +% +% Even if citations are undefined, we want to complain only if +% \@citewarningtrue. The default is to set \@citewarningtrue unless +% \noauxfile is defined. Again, a macro package that uses +% btxmac.tex might want to redefine this. +% +\@innernewif\if@citewarning +\ifx\noauxfile\@undefined \@citewarningtrue\fi +% +% +% Finally, before leaving we restore @'s old category code. +% +\catcode`@ = \@oldatcatcode diff --git a/Master/texmf-dist/doc/otherformats/lollipop/manual/comm.tex b/Master/texmf-dist/doc/otherformats/lollipop/manual/comm.tex new file mode 100644 index 00000000000..5fba81be50d --- /dev/null +++ b/Master/texmf-dist/doc/otherformats/lollipop/manual/comm.tex @@ -0,0 +1,642 @@ +% comm.tex copyright 1992 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 <http://www.gnu.org/licenses/>. +% +% +\Chapter Commands + +\Section[sec:counters] Counters + +Counters can be declared explicitly by the user, but more often they +are defined automatically in some generic construct: + +The \cs{Foo} defined by +\Ver>\DefineBar:Foo ... + counter:i ... + Stop<Rev + +will have a counter that counts in roman lowercase, and which is +accessible as \refcs{FooCounter}. Everytime \cs{Foo} is used, this +counter is increased by one. + +The use of the \opt{counter} option is described +in~\ref[sec:opt:counter]. +Here are the commands for explicit manipulation of counters. + +\SubSection[sec:counter:repr] Allocation and representation + +A counter is created by for instance +\Ver>\NewCounter:Things<Rev +This will create control sequence \cs{ThingsCounter} that will print +the value of the counter. +The counter will usually be printed as an Arabic numeral, but other +counter representations can be specified by +\refcs{CounterRepresentation}. Here are their codes: \Description +\item 1 +numeric +\item a +lowercase character +\item A +uppercase character +\item i +lowercase roman +\item I +lowercase roman +\> +for instance +\Ver>\CounterRepresentation:Things=i<Rev +will cause \cs{ThingsCounter} to print a lowercase Roman numeral. + +However, a call such as +\Ver>\CounterRepresentation:Theorem=Lemma<Rev +will make the \cs{TheoremCounter} a synonym of an earlier created +\cs{LemmaCounter} + +\SubSection Counter manipulation + +The following commands can be used to manipulate counters, both when +they are created by hand using \refcs{NewCounter} and when they were +generated automatically in some generic construct: + +With \refcs{StartCounter} reset the counter to one: + \Ver>\StartCounter:things<Rev + +With \refcs{StepCounter} increase the counter by one: + \Ver>\StepCounter:things<Rev + +With \refcs{BackStepCounter} decrease the counter by one: + \Ver>\BackStepCounter:things<Rev + +With \refcs{SetCounter} set the counter to some specified value: + \Ver>\SetCounter:things=5<Rev + +With \refcs{AddToCounter} increase the counter by some +specified value: + \Ver>\AddToCounter:things=7<Rev + +The last two commands accept names of numerical parameters, for +instance the value of a counter: + \Ver>\NewCounter:Favourite +\AddToCounter:things=FavouriteValue<Rev +More about this `value' thing in the next section. + +\SubSection What do you get when you define a counter? + +After you define a counter as \Ver>\NewCounter:MyThings<Rev there are +two commands that it is important to distinguish between. First of +all, \cs{MyThingsCounter} gives the {\it printed\/} value of the +counter. This is the command that you will use mostly. It uses +whatever representation you have specified for the counter, or plain +Arabic numerals if haven't specified anything. + +Secondly, \cs{MyThingsValue} gives the value of the counter. You can +not use this command on its own: you will get a `number expected' +error. + +\SubSection Counter hierarchies + +Often counters are related to each other. For instance, when a new +section begins, the subsection counter has to be reset. The same may +be true for equation counters. In Lollipop such a relation is +indicated by a call to \refcs{GoverningCounter}, for instance + +\Ver>\GoverningCounter:SubSection=Section<Rev + +All of the counter manipulation commands applied to a governing +counter will cause all governed counters to be reset. Such a reset +also occurs if the counter was created in some generic construct. + +For examples, see section~\ref[sec:head:examples]. + +\SubSection Referencing counters + +All counters that are declared as part of a generic construct, or +explicitly through \refcs{NewCounter} automatically become the current +reference when they are altered. Thus \ver>\label[bar]> will make +\ver>\ref[bar]> refer to the value of the counter most recently +changed. The way the counter is referenced can be altered by the +\opt{label} option in generic constructs; see +section~\ref[sec:opt:label]. + +For generic constructs with a counter no explicit \refcs{label} commands +need to be given; such commands take an optional argument with the +label key: +\Ver>\Section[sec:examples] Examples<Rev + +\SubSection Adaptive counters + +It may happen that you want to compute a value during one run of +\TeX, and use it in the next. An example is the fact that this manual +states the total number of pages on the title page. For this you can +use \refcs{AdaptiveCounter} + \Ver>\AdaptiveCounter:LastPage<Rev +which is like \cs{NewCounter}, except that the value of this counter +gets written to the \file{.aux} file. + +There are two ways of setting an adaptive counter: you can simply use +it in some construct (for instance through a counter synonym; +section~ref[sec:counter:repr]), or you can set it explicitly, for +instance as + \Ver>\SetCounter:LastPage=PageValue<Rev +See how this manual does it. + +\SubSection Examples of counter usage + +Items start at the value of one, so if a starting value of zero is +necessary, the following will work +\Ver> +\Enumerate \SetCounter:item=-1 +\item ...<Rev + + +\Section[sec:font] Font selection + +In \Lollipop, choosing a font is done through three parameters: +\Description\item Typeface +A collection of related styles and sizes. The typeface is set by the +command \refcs{Typeface}. +\item Style +Italic, bold, roman, typewriter. You know. The style is set by the +command \refcs{Style}. +\item PointSize +The size of a font in typographical points ($72.27$ per inch). +The pointsize is set by the command \refcs{PointSize}. +\> + +The most common change of font is a change in style. Therefore, +issuing a command such as \Ver>\Style:bold<Rev immediately changes +the font to the bold of the current typeface in the current pointsize. + +However, issuing a command such as \Ver>\Typeface:GoudyOldStyle<Rev +or \Ver>\PointSize:28<Rev will not change the font, since such +changes are usually accompanied by a change in style. In case that an +immediate switch is necessary, the command +\refcs{SetFont} can be given. +This evaluates the current value of the typeface, style, and +pointsize commands, and sets the font accordingly. + +A number of typeface names have been predefined in \Lollipop, +however, in order to print them your printer (software) must have them +available. + +\Example +\SerifFace \PointSize:12 +\Style:roman This \Style:italic sentence \PointSize:10 has +\SetFont way \SansFace \Style:roman too \SetFont many +\PointSize:12 \SetFont font \Style:bold changes. +\ExampleStop + +(The commands \cs{SerifFace} and \cs{SansFace} are defined in +the master file of this manual, and serve to make this manual +formattable on any system.) + +\SubSection Relative size changes + +Apart from setting the pointsize explicitly, it is also possibly to +make size changes relative to the current size. For instance, +\refcs{PointSizeLarger} and \refcs{PointSizeSmaller} with an optional +argument indicating the size of the change can be used. These +commands are not cumulative. + +\Example +\SerifFace +\PointSize:9 \SetFont Every once in a while,\SaveFont +\PointSizeLarger[2] shouting \PointSizeLarger helps. +\PointSizeSmaller[2]But most of the times it doesn't. +\RestoreFont Unfortunately. +\ExampleStop + +Similar to the changes in mathematics mode to script and scriptscript +size, the same relative changes are available in text mode through +the control sequences \refcs{script} and \refcs{scriptscript}. +The control +sequence \refcs{normal} can be used to restore the default size. + +Here is one application of such relative changes: +\Ver> +L\kern -.3em\raise .35ex\hbox {\script A}\kern -.1em\TeX<Rev +which gives definition of the \LaTeX\ logo that is independent +of typeface, size and style. + +The relative sizes of script and scriptscript fonts are by default at +$70\%$ and $50\%$, but they can be set explicitly by +\Ver>\PointSizeScriptSizes:10=10,7,5<Rev +This also gives the possibility to have the \cs{normal} size to be +different from the surrounding pointsize. + +\SubSection Typeface definition + +Defining a typeface means telling \Lollipop\ how the external font +name, that is, the name of the \n{tfm} file, is to be constructed from +the internal parameters. The command \refcs{DefineTypeface} takes four +parameters and an optional fifth. The parameters are in sequence +\Enumerate\item The internal name of the typeface: the name that is +given to the \cs{Typeface} command. +\item The root of the external file name. It is assumed that all +font names of different styles and sizes are constructed by appending +characters to this base. +\item Suffixes corresponding to the styles that are available. +\item Suffixes corresponding to the sizes that are available. +\> + +Here is the definition of the Computer Modern typeface: + +\Ver> +\DefineTypeface{ComputerModern}{cm} + {roman:r; slant:sl; italic:ti; mitalic:mi; bold:bx; typewriter:tt; + default:r;} + {<6:5; <7:6; <8:7; <9:8; <10:9; <11:10; + <12:10 \scaled\magstephalf; + <14:10 \scaled\magstep1; <16:10 \scaled\magstep2; + <20:10 \scaled\magstep3; >19:10 \scaled\magstep4; + default:10;}<Rev + +Actually, not all combinations of styles and sizes are available. +That's where the optional argument comes in. This argument can be +used to specify with \TeX\ conditionals exceptional style/size +combinations. Here some trickery is needed: internally the size is +stored in \cs{Fsize}, and in order to use this parameter we need to +make the at-sign a letter temporarily. + +\Ver>\makeatletter +\DefineTypeface{Compu ... + ... + default:10;} + [\ifStyle:italic \ifnum\Fsize<7 ti7\fi\fi + \ifStyle:typewriter \ifnum\Fsize<8 tt8\fi\fi]<Rev + +You may have noticed that this scheme is not all-powerful. Thus +I~found it easier to move all Computer Modern sans serif fonts into a +new typeface: \n{ComputerSans}. + +For other typefaces specifying the size suffix may be much easier +than for Computer Modern. For instance, here is the definition of the +PostScript Helvetica typeface. + +\Ver>\makeatletter +\DefineTypeface{psHelvetica}{helv} + {roman:; italic:i; mitalic:i; bold:b; default:;} + {default: at \Fsize pt;} +\makeatother<Rev + + +\SubSection Math fonts + +Switching styles in math mode should be possible: +$${\Style:bold x\Style:roman y}z$$ + +\SubSection Other font matters + +The combination \refcs{SaveFont} with a subsequent +\refcs{RestoreFont} can +be used to save and restore the current font. + +An abbreviation for a font can be defined by +\Ver>\DefineFont:name=face,size,style<Rev +This has the same effect as +\Ver>\def\name{\TypeFace:face \PointSize:size \Style:style }<Rev +but it takes considerable less processing inside \TeX. + +Even if you don't use Computer Modern as your main typeface, the +typewriter style is not bad, so a control sequence +\Ver> +\def\tt{\Typeface:ComputerModern \Style:typewriter }<Rev +has been given that makes \refcs{tt} always refer to the +\n{cmtt} fonts. You're at liberty to change this, of course. + +\Section Baselineskip + +Corresponding to a font size usually the baseline skip has to change. +By default a fixed ratio of~$1.2$ for this is taken, for instance +using a 12~point baseline skip for 10~point fonts. Changing the ratio +can be done by +\Ver>\BaselineSkipPointSizeRatio:1.3<Rev + +If only for some specific size the baseline skip has to deviate from +the default ratio, then this can be set by +\Ver>\SetPointSizeBaselineSkip:9=12<Rev + +\Section[sec:indent:control] Indentation Control + +\SubSection To indent or not to indent + +In most documents there is a general rule that all paragraphs indent +unless a certain condition, or that they do not indent unless certain +special conditions hold. For \Lollipop\ documents this is determined +by the command \refcs{AlwaysIndent}, with values \n{yes}/\n{no}. + +To override this default setting a command \refcs{Indent} +(with values \n{yes}/\n{no}) exists, but that is mostly useful as an +option in generic constructs, and even there it will not be used much. +See section~\ref[sec:opt:indent] for options relating to indentation. + +Important: never set \cs{parindent} to zero. Preventing indentation +globally should be done through \ver>\AlwaysIndent:no>. + +\SubSection[sec:basic-indent] Basic indent + +There is a quantity \refcs{basicindent} that is used on the first +indentation level (see the next section for an explanation of these +levels). At the start of a document it is set to the then current +value of \cs{parindent}. You can override that by +\refcs{BasicIndentIsSet}: give +\Ver>\BasicIndentIsSet:no<Rev before the \cs{Start} command. + +This way, setting \cs{parindent} in the style definition controls the +indentation in the whole document. + +\SubSection Indentation levels; indentation size + +When \Lollipop\ decides that text should be indented, it refers to a +list of indentations for the exact amount. This list contains +indentation amounts for each `level' of indentation: initially the +level is one, and if you nest constructs that indent (for instance +using a list inside a list) the level goes up one step per nested +construct. + +By +default the indentation on different levels is a fraction of the +\cs{basicindent}. Thus you can regulate the indentation on +all levels simultaneously by resetting the \cs{basicindent}. + +\Example +\Distance:basicindent=15pt +\DefineList:TestList item:left itemCounter item:stop Stop +\TestList\item Level one \TestList\item Level two +\TestList\item Level three\>] +\Distance:basicindent=25pt +\TestList\item Level one \TestList\item Level two +\TestList\item Level three\>] +\ExampleStop + +The amount of +indentation on a certain level can be set explicitly with +\refcs{LevelIndent}. + +\Example +\Distance:basicindent=15pt +\LevelIndent:2=20pt +\DefineList:TestList item:left itemCounter item:stop Stop +\TestList\item Level one \TestList\item Level two +\TestList\item Level three\>] +\ExampleStop + +In fact, sometimes you may want to know the name of the indentation +on a certain level. This is a control sequence such as +\refcs{levelindentii} for the second level. You get the idea. + +\SubSection Manipulating the indentation level + +Every once in a while it can be useful to move to a next indentation +level, or to return to a previous level. For this +the two commands \refcs{PushIndentLevel} and \refcs{PopIndentLevel} are +available. One application is for `interrupted lists': + +\Example +\Itemize\item One +{\par\PopIndentLevel Interrupted text!\par} +\item Two\> +\ExampleStop + +See chapter~\ref[chap:external-files] for examples of the use of +\cs{PushIndentLevel} + +\Section Margins + +By default, \Lollipop\ tries to keep straight margins. You can change +its mind about that by \refcs{FlushRight} and \refcs{FlushLeft} +which are tests: +\Ver>\FlushRight:no \FlushLeft:no<Rev +If the margins are not flush, the stretchable white space used +is \refcs{rightmarginstretch} and \refcs{leftmarginstretch}, +which can be set by \cs{Distance}. + +You have to set the amount of stretch {\it before} specifying that +the margins will not be flush. The \cs{FlushRight/Left} commands take +the current value whenever they are called. + +\Section White Space + +White space can be indicated by \refcs{hwhite} and \refcs{vwhite}. +They are often useful in style definitions. Use: +\Ver>\vwhite:15pt<Rev +or \Ver>\hwhite:{15pt minus 3pt}<Rev +for stretch and shrink. The command \refcs{white} is independent +of the mode, and it expands to \cs{hwhite} or \cs{vwhite} +depending on the prevailing mode of \TeX. + +The command \refcs{fillup} is mostly useful in style definitions: +it tries to fill up as much white space as is possible. +For instance +\Ver> line:start litteral:foo fillup litteral:bar line:stop<Rev +will push \n{foo} and \n{bar} as far apart as is possibly +within the margins. + +\ImpNote +All three control sequences \cs{white}, \cs{hwhite}, \cs{vwhite} +have internal equivalents, for instance +\Ver>\def\white:#1 {\@white{#1}}<Rev +\ImpNoteStop + +\Section[sec:com:distance] Distances + +The command \refcs{Distance} can be used +to declare a name for a certain +distance, or in more correct \TeX nical lingo, for a certain piece of +glue. For instance, declaring that + \Ver>\Distance:oneline=15pt<Rev +means that you can specify in some constructs +\Ver>\DefineFoo:Bar whitebefore:oneline whiteafter:oneline<Rev +If you change your mind later about the value of \n{oneline} you only +need to change one line in the style definition. + +Since the second parameter of \cs{Distance} is bounded by a space (or +the line end, whatever comes first), you can specify stretchable +distances by enclosing \n{plus} and \n{minus} parts in braces: +\Ver>\Distance:oneline={15pt plus 2pt minus 3pt}<Rev + +The effect of \cs{Distance} is global. Let me know if you don't +like it. + +\SubSection Distance synonyms + +Another use of \cs{Distance} is to define one distance as a synonym +of another. This may come in handy if you use some basic distance, +such as \n{oneline} for several purposes. Example: if you specify +\Ver>\Distance:whitebefore=oneline<Rev +than the whitespace before a construct will be taken to be +\n{oneline} if you don't use the \opt{whitebefore} option explicitly. + +\SubSection[sec:adapt-distance] Adaptive distances + +Suppose you want to declare a section heading as + \Ver>\DefineHeading:Section ... + block:start [...] fillupto:widelabel title<Rev +where \cs{widelabel} is the width of the widest label that +occurs in your document. This requires just a tad of \TeX\ +programming. Just copy the details from the example below, which is +the definition of \cs{Section} in this manual. + +By declaring something a \refcs{AdaptiveDistance} instead of just +\cs{Distance} its value gets written to the \file{.aux} file at the +end of the run, and restored in the next run. The second argument is +simply the default value, in case you don't have an auxiliary file +yet. + +\Ver>\AdaptiveDistance:WidestLabel=15pt +\def\MeasureLabel{\ifdim\BlockWidth>\WidestLabel + \global\WidestLabel\BlockWidth\fi} +\DefineHeading:Section + whitebefore:{20pt plus 2pt} whiteafter:14pt + line:start PointSize:14 Style:italic + block:start block:start ChapterCounter . SectionCounter + Spaces:1 block:stop MeasureLabel + fillupto:WidestLabel + title line:stop + external:contents title external:stop + label:start ChapterCounter . SectionCounter label:stop + Stop<Rev + +Note how two nested blocks are used: the first is to measure the +label, and the width is written to the adaptive distance by means of +a small macro; the second block is to fill out the white space. + +If you want the paragraph indentation to depend on this adaptive +width, you can give + \Ver>\StartCommand{\Distance:parindent=WidestLabel }<Rev +to set \cs{parindent} at the start of the document. +See section~\ref[sec:doc-start-stop] and~\ref[sec:basic-indent]. + +\Section[sec:InputFile] Input Files + +Parts of a document can be loaded by +\Ver>\InputFile:parta +\InputFile:partb<Rev +et cetera. A~document part loaded by \refcs{InputFile} always starts +on a new page. In section~\ref[sec:ref-local] it was already +explained how local references for such files can be created. + +Perhaps most importantly, loading files this way provides a form of +error checking; \Lollipop\ checks at the end of such a file whether all +used constructs are balanced properly. + + +\Section[sec:tests] Tests + +Users can define tests: +\Ver>\DefineTest:SomethingTheMatter<Rev +which are set like any other test: +\Ver>\SomethingTheMatter:yes<Rev +or \Ver>\SomethingTheMatter:no<Rev + +Tests can be used as \Ver>\ifSomethingTheMatter ... \else ... \fi<Rev +Like any other conditional, test can be used inside constructs. +\Ver>\DefineFoo:Bar [...] + ifSomethingTheMatter [...] fi + [...] Stop<Rev + +\Section Goodies + +\SubSection List commands + +Lollipop does a lot of list processing internally, and a few +of the commands have been made available to the user. + +\Description\item \refcs{NewList} +creates a list, and sets it to empty: + \Ver>\NewList:mylist<Rev + \item \refcs{EmptyList} +just empty a list. + \item \refcs{TheList} +inserts the list. This will typeset the contents of it. + \Ver>\TheList:mylist<Rev + \item \refcs{AppendToList} +adds data to a list. \Ver>\AppendToList:mylist={my data}<Rev +The data are terminated by a space or line end, hence the braces. +\> + +\SubSection Programming Tools + +A few commands are useful for the Lollipop style designer who wants +to write more sophisticated macros (see for instance the address book +macros in the last chapter). + +\Description\item \refcs{UndefinedCS} +is a test on control sequences. + \Ver>\if\UndefinedCS{testcs} ... \else ... \fi<Rev + \item \refcs{EqualString} +tests equality of strings. + \Ver>\if\EqualString{one}{two} ... \else ... \fi<Rev + \item \refcs{EqualStringX} +tests equality of strings, using only expansion. + \Ver>\if\EqualStringX{one}{two} ... \else ... \fi<Rev + \item \refcs{StringBefore} +tests lexicographic ordering of strings. The string are not supposed +to contain characters with char codes~0, 127,~255. + \Ver>\if\StringBefore{one}{two} ... \else ... \fi<Rev + \item \refcs{NextChar} +chooses between two actions, based on the next character. + \Ver>\if\NextChar[{\macro}{\macro[default]} ...<Rev + \item \refcs{IsEmptyList} +can test whether an argument is empty. + \Ver>\if\IsEmptyList{#1} ...<Rev +is true for calls such as \ver>\macro{}>. + \item\refcs{loop} +can be used for repeated execution of statements. (Users of plaing +\TeX\ may recognize this macro; it is slightly extended here +to include the \cs{else} case.) It is +used as: + \Ver>\loop ... \if ... \repeat<Rev +of \Ver>\loop ... \if ... \else ... \repeat<Rev + + + \> + +\SubSection[sec:everypar] \cs{everypar} + +The \TeX\ primitive \cs{everypar} should not be used any more. +Instead use the command \refcs{EveryParagraph} as if you are setting +a token list: + \Ver>\EveryParagraph{ ... }<Rev + +\SubSection[sec:everymath] \cs{everymath} + +The \TeX\ primitive \cs{everymath} should not be used any more. +Instead use the command \refcs{EveryMath} as if you are setting +a token list: + \Ver>\EveryMath{ ... }<Rev + +\SubSection[sec:everydisplay] \cs{everydisplay} + +The \TeX\ primitive \cs{everydisplay} should not be used any more. +Instead use the command \refcs{EveryDisplay} as if you are setting +a token list: + \Ver>\EveryDisplay{ ... }<Rev + +\SubSection Allocation + +The commands \refcs{SaveAlloc} and subsequent \refcs{RestoreAlloc} save and +reset the internal \TeX\ allocation counters. + +\endinput + +% 2014/04/13 Added some notes about \EveryMath, and +% \EveryDisplay. Also the wrong spelling of `note' changed +% to `not' in `sec:everypar'. +% 2014/04/11 Changed \n{tty} style to \n{typewriter} style +% 92/11/18 Adaptive distances explained +% 92/11/20 Adaptive counters explained +% 93/05/13 changes in font macros diff --git a/Master/texmf-dist/doc/otherformats/lollipop/manual/comment.tex b/Master/texmf-dist/doc/otherformats/lollipop/manual/comment.tex new file mode 100644 index 00000000000..fb7047c4259 --- /dev/null +++ b/Master/texmf-dist/doc/otherformats/lollipop/manual/comment.tex @@ -0,0 +1,129 @@ +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +% comment.sty version 3.0, 3 September 1992 +% selectively in/exclude pieces of text: the user can define new +% comment versions, and each is controlled separately. +% Special comments can be defined where the user specifies the +% action that is to be taken with each comment line. +% +% This style can be used with plain TeX or LaTeX, and probably +% most other packages too. +% +% Author +% Victor Eijkhout and Vafa Khalighi +% persian-tex@tug.org +% +% Usage: all text included in between +% \comment ... \endcomment +% or \begin{comment} ... \end{comment} +% is discarded. The closing command should appear on a line +% of its own. No starting spaces, nothing after it. +% This environment should work with arbitrary amounts +% of comment. +% +% Other 'comment' environments are defined by +% and are selected/deselected with +% \includecomment{versiona} +% \excludecoment{versionb} +% +% These environments are used as +% \versiona ... \endversiona +% or \begin{versiona} ... \end{versiona} +% with the closing command again on a line of its own. +% +% Special comments are defined as +% \specialcomment{name}{before commands}{after commands} +% where the second and third arguments are executed before +% and after each comment. By defining a control sequence +% \Thiscomment#1{...} in the before commands the user can +% specify what is to be done which each comment line. +% +% Basic approach: +% to comment something out, scoop up every line in verbatim mode +% as macro argument, then throw it away. +% For inclusions, both the opening and closing comands +% are defined as noop +% +% This file copyright Victor Eijkhout and 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/>. +% +% + +\def\makeinnocent#1{\catcode`#1=12 } +\def\csarg#1#2{\expandafter#1\csname#2\endcsname} + +\def\TreatAsComment#1{\begingroup + \def\CurrentComment{#1}% + \let\do\makeinnocent \dospecials + \makeinnocent\^^L% and whatever other special cases + \endlinechar`\^^M \catcode`\^^M=12 \xComment} +{\catcode`\^^M=12 \endlinechar=-1 % + \gdef\xComment#1^^M{\def\test{#1} + \csarg\ifx{PlainEnd\CurrentComment Test}\test + \def\next{\endgroup\AfterComment}% + \else \csarg\ifx{LolliEnd\CurrentComment Test}\test + \def\next{\endgroup\AfterComment}% + \else \csarg\ifx{LaLaEnd\CurrentComment Test}\test + \edef\next{\endgroup\noexpand\AfterComment + \noexpand\end{\CurrentComment}} + \else \ThisComment{#1}\let\next\xComment + \fi \fi \fi \next} +} + +\def\includecomment + #1{\message{Including comment '#1'}% + \expandafter\def\csname#1\endcsname{}% + \expandafter\def\csname end#1\endcsname{}} +\def\excludecomment + #1{\message{Excluding comment '#1'}% + \csarg\def{#1}{\let\AfterComment\relax + \def\ThisComment####1{}\TreatAsComment{#1}}% + {\escapechar=-1\relax + \csarg\xdef{PlainEnd#1Test}{\string\\end#1}% + \csarg\xdef{LolliEnd#1Test}{\string\\#1Stop}% + \csarg\xdef{LaLaEnd#1Test}{\string\\end\string\{#1\string\}}% + }} +\long\def\specialcomment + #1#2#3{\message{Special comment '#1'}% + \csarg\def{#1}{\def\ThisComment{}\def\AfterComment{#3}#2% + \TreatAsComment{#1}}% + {\escapechar=-1\relax + \csarg\xdef{PlainEnd#1Test}{\string\\end#1}% + \csarg\xdef{LolliEnd#1Test}{\string\\#1Stop}% + \csarg\xdef{LaLaEnd#1Test}{\string\\end\string\{#1\string\}}% + }} +\excludecomment{comment} + +\endinput + +% a test of the special comments +\newcount\comlines +\specialcomment{countedcomment} + {\comlines=-1\relax %note that the rest of the first line is also comment + \def\ThisComment{\global\advance\comlines1\relax}} + {\endgraf **Comment: \number\comlines\ line(s) removed**\endgraf} + +This is a line of text +\countedcomment +Oneline +\endcountedcomment +another line of text +\countedcomment +One line +Two line +Three line +\endcountedcomment +last line of text +\end diff --git a/Master/texmf-dist/doc/otherformats/lollipop/manual/example.tex b/Master/texmf-dist/doc/otherformats/lollipop/manual/example.tex new file mode 100644 index 00000000000..5b38d8eefb5 --- /dev/null +++ b/Master/texmf-dist/doc/otherformats/lollipop/manual/example.tex @@ -0,0 +1,4 @@ + +\Itemize\item One +{\par\PopIndentLevel Interrupted text!\par} +\item Two\> diff --git a/Master/texmf-dist/doc/otherformats/lollipop/manual/extern.tex b/Master/texmf-dist/doc/otherformats/lollipop/manual/extern.tex new file mode 100644 index 00000000000..e9a3c5937bd --- /dev/null +++ b/Master/texmf-dist/doc/otherformats/lollipop/manual/extern.tex @@ -0,0 +1,428 @@ +% extern.tex copyright 1992 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 <http://www.gnu.org/licenses/>. +% +% +\Chapter[chap:referencing] +Referencing + +In manuals and scientific documents you often want to write something +like `see Chapter~4'. But what if you shuffle the chapters a bit? It +would be nice if the number would be updated automatically. With +\Lollipop, as with many other \TeX\ macro packages, this is easily +done. + +Here is an example to set the mood for the rest of this chapter. +The sort of thing that is referred to most is a heading. So suppose +you want to refer to a section number. + +\Example +\DefineHeading:TestSection + line:start Style:italic TestSectionCounter Spaces:2 title + line:stop Stop +\TestSection[one:section?] First section\par +After this section will come section~\ref[other:section!]. + +\TestSection[other:section!] Another section\par +This is the section that came after section~\ref[one:section?]. +\ExampleStop + +\Section What and how do you reference? + +You can reference not only headings but everything that has a +counter. Thus all generic constructs can be referenced, and in +addition you can reference item numbers in a list (there are examples +of this latter possibility in section~\ref[sec:bib]). The simplest way +of referencing something is to put the key in square brackets behind +it: + +\Ver>\Section[this:section] The title of This Section<Rev +You can then reference the key by \refcs{ref}, or the page +where it appeared by~\refcs{pgref}: +\Ver>Section \ref[this:section] on page \pgref[this:section]<Rev + +As you may have guessed from the above examples, keys can contain all +sorts of characters. Only brackets, braces, and the hash sign are +excepted. You get an error message if you try to use the same key +twice. + +Another way of declaring a key is to use the command \refcs{label} +carrying the key +\Ver>\label[the:key]<Rev +This can be useful if you want to declare two keys for a single +reference. Make sure that the \cs{label} command is not part of the +title. Unexplained phenomena occur if you do that. Instead put the +label after the construct you want to reference: +\Ver>\Section Precautions and remedies + +\label[sec:precautions]\label[sec:remedies] +In this section ...<Rev + +\Section[sec:shape:reference] The shape of the reference + +By default, a reference consists of just the number of the thing you +reference. There are two ways in which you can change this, one +systematic, and one on-the-fly. + +\SubSection Defining the shape of the reference + +You can customize the way an object is +referenced by using the option \refopt{label} in its definition. For +instance, often you want things like parentheses around references. +Putting this information in the label definition saves you a lot of +work in case you change your mind later. + +\Example +\DefineHeading:TestSection + line:start Style:italic TestSectionCounter Spaces:2 title line:stop + label:start ( TestSectionCounter ) label:stop Stop +\TestSection[one:section?2] First section\par +After this section will come section~\ref[other:section!2]. + +\TestSection[other:section!2] Another section\par +This is the section that came after section~\ref[one:section?2]. +\ExampleStop + +Another use of customized labels is including other counters in the +reference: + +\Example +\DefineHeading:TestChapter + line:start Style:bold TestChapterCounter / title line:stop Stop +\DefineHeading:TestSection + line:start Style:italic TestSectionCounter Spaces:2 title line:stop + label:start TestChapterCounter . + TestSectionCounter label:stop Stop +\TestChapter First chapter\par +Pretty short chapter +\TestChapter Second chapter\par +\TestSection[one:section?3] First section\par +After this section will come section~\ref[other:section!3]. + +\TestSection[other:section!3] Another section\par +This is the section that came after section~\ref[one:section?3]. +\ExampleStop + +A more surprising application of explicit definition of labels is +inclusion of the title in the reference. +\Example +\DefineHeading:TestSection + line:start Style:italic TestSectionCounter Spaces:2 title line:stop + label:start TestSectionCounter literal: Spaces:1 + Style:italic title label:stop Stop +\TestSection[one:section?4] First section\par +After this section will come section~\ref[other:section!4]. + +\TestSection[other:section!4] Another section\par +This is the section that came after section~\ref[one:section?4]. +\ExampleStop + +\SubSection[sec:exp-ref] Explicit specification of the reference + +For every specific object referenced you can specify the reference by +using an optional argument before the label key. Have a look at the +next example. + +\Example +\DefineHeading:TestSection counter:A + line:start Style:bold TestSectionCounter . Spaces:2 title line:stop + Stop +\TestSection[ref:one] Lalala\par +This is before section \ref[ref:two]. +\TestSection<`the Didi section'>[ref:two] Dididi\par +This is after section \ref[ref:one]. +\ExampleStop + +This mechanism is also used in lists, where it's mostly useful for +bibliographies generated by Bib\TeX; see section~\ref[sec:BibTeX]. + +\Section[sec:ref-local] Local references + +Some documents are +collated out of parts that were documents in themselves. +The \Lollipop\ command \cs{InputFile} facilitates in a number +of ways working with such a segmented file (see +section~\ref[sec:InputFile]). One of the problems with input files is +that in such a case it may happen that the same reference key is used +in more than one part of the document. This phenomenon is +not at all unknown in multiple authored documents. Ordinarily this +would result in incorrect references. + +To prevent such collisions \Lollipop\ can use local +references: the command \refcs{LocalReferences} has default \n{no}, +and specifying +\Ver>LocalReferences:yes<Rev +creates local \file{aux} files for each input file. + +\Section[sec:bib] Bibliography citations + +\Lollipop\ has an interface to Bib\TeX. However, since a bibliography +is just a list, referencing items in it is quite easy, even if you +don't use Bib\TeX. + +\SubSection Bibliographies without Bib\TeX + +This section doesn't tell you anything that cannot be found elsewhere +in this manual. The following two examples define a bibliography as +just a list, and by giving labels to the items you can refer to them. + +\Example +\DefineList:BibList item:left [ itemCounter ] item:stop + label:start [ itemCounter ] label:stop Stop +In this example we shall have occasion to refer to +\ref[Abee80] and~\ref[Ceede79].\par +\Indent:no Bibliography +\BibList \item[Ace55] C.D. Ace, Inscrutible title. +\item[Abee80] E.F. Abee, Worthless drivel. +\item[Ceede79] G.H. Ceede, Contractual obligation. +\> +\ExampleStop + +Here is a way to customize the label (if you need to refresh your +memory about description lists, see +section~\ref[sec:description:list]). + +\Example +\DefineList:BibList item:left [ itemCounter ] item:stop + label:start ( description ) label:stop Stop +In this example we shall have occasion to refer to +\ref[Abe80] and~\ref[Ceedee79].\par +\Indent:no Bibliography +\BibList \item[Aace55] Aace55 +C.D. Aace, Inscrutible title. +\item[Abe80] Abe80 +E.F. Abe, Worthless drivel. +\item[Ceedee79] Ceedee79 +G.H. Ceedee, Contractual obligation. +\> +\ExampleStop + +\SubSection[sec:BibTeX] Bibliographies with Bib\TeX + +\Lollipop has an interface to the popular Bib\TeX\ +bibliography database program, based on the `BtxMac' macros +by Karl Berry and Oren Patashnik. \Lollipop\ is set up for them, you +only have to \cs{input} the file \file{btxmac.tex}. (The version +of btxmac used to test this is \n{0.99h}.) You can find global +information about Bib\TeX\ in the \LaTeX\ book~{%\tracingmacros=2 +%\tracingcommands\tracingmacros +\bibref[La:book]}, +since Bib\TeX\ was +originally written for \LaTeX. + +Since there is some redefining going on between btxmac and \Lollipop\ +you have to load the btxmac file before the \cs{Start} command (see +section~\ref[sec:doc-start-stop]). + +Since the btxmac file already has a default way of formatting the +bibliography you can get away with just putting the lines + \Ver>\bibliography{ <bfile> } +\bibliographystyle{ <bstyle> }<Rev + in your file wherever you want the bibliography. + +If you want to define your own bibliography, you have to use +\refcs{DefineBBL} which is practically a synonym for +\ver>\DefineList:BBL>, so you can see in the `lists' chapter of this +manual what options apply. + +For example: + \Ver>\DefineBBL line:start Style:italic literal:Literature line:stop + item:left [ begingroup Style:bold itemCounter + endgroup ] item:stop + Stop<Rev + +You refer to a bibliography item by \refcs{bibref}, as in +\ver>\bibref[Knuth80]>. This command has a very simple definition + \Ver>\def\bibref[#1]{[\ref[#1]]\nocite{#1}}<Rev +so you can easily redefine it. For instance + \Ver>\def\supref[#1]{$^{\rm \ref[#1]}$\nocite{#1}}<Rev + will make your references into superscripts. +Make sure that +the call to \cs{nocite} appears, because that generates the request for +Bib\TeX. + +The \Lollipop\ command \ver>\WriteExtern:no> (see +section~\ref[sec:write-extern]) defines \cs{noauxfile} to prevent +regeneration of the bib entries in the \file{.aux} file. +You don't have to do that anymore. + +\Section Obscure details + +For the sake of efficiency, not all macros in Lollipop automatically +accept labels for referencing, only the ones that use the \n{label} +option, or that have a counter (remember, the default form of the +reference is just the counter). If you want a macro that has no +counter and no label specification to accept a label, use the option +\refopt{haslabel}. One reason for doing this is that you have access to +the label itself through the control sequence \refcs{RefLabel}. + +\Chapter[chap:external-files] External Files + +Some document require information to be collected during a run. Such +information typically is a table of contents or index, and it is +gathered in an external file. (The reason for gathering such +information in a file at all is that often some external manipulation, +for instance sorting of an index, is needed.) Since there are many +possibilities for external files (mathematical monographs may have a +list of definitions, or a list of notations) \Lollipop\ does not +predefine such files, but supplies all of the tools for creating them. + +External files involve four actions: +\Enumerate\item The file should be declared. +\item It should be specified what information is to be written to the +file. +\item The formatting of the contents of the file has to be specified. +\item The file has to be loaded. +\> + +You can have at most 15 external files per document. + +\Section[sec:write-extern] Declaring and loading an external file + +The first act, declaring the existence of the external file is very +easy with the command \refcs{DefineExternalFile}: + an internal name and a three-character file name extension have +to be given as parameters. +\Ver>\DefineExternalFile:contents=toc<Rev +With this definition, if the document is called \file{book.tex} then +the `contents' will be gathered in a file called \file{book.toc}. +(The declaration of an external file has to come before any calls +to \cs{ExternalItem} or any options \n{external} that write +to this file.) + +For each external file \n{Foo} there is a command to determine whether +that file will be regenerated in the next run of \TeX: +\refcs{WriteFoo} with values \n{yes}/\n{no} will allow or prevent the +file being regenerated. The value \opt{yes} is default. The +command \refcs{WriteExtern} (values \n{yes}/\n{no}) +can be used to prevent writing out any external files (including the +\file{.aux} file that keeps track of references). + +The final act, loading an external file, is as easy as declaring it: +use \refcs{LoadExternalFile} as in +\Ver>\LoadExternalFile:contents<Rev +This does not cause any page breaks or headings to be set over the +loaded material, so you have to do that explicitly. + +\Section[sec:ext-option] Generating external files + +Next, macros that write to the table of contents have to declare this +information. The \refopt{external} option is used for this. +Any counter that the construct has will be written out +automatically, and the style designer usually has to specify only +that the title will be written out. +\Ver>\DefineHeading:Section + [...] + external:contents title external:stop<Rev + +There is no objection to a construct writing information to more than +one external file. + +If you write more than just \n{title} to an external file, know that +any control sequence you specify is automatically protected from +expansion. See section~\ref[opt:csname] for an exception to this. + +Other titles can be included by specifying \opt{title:OtherThing}. +Using \opt{OtherThingTitle} would not work, because of the protection +of control sequences mentioned above. + +You can write arbitrary information to an external file, if you see a +reason to do so, by \refcs{ToExternalFile}, which takes a file name +and an text argument. The example below has an instance of this +command. In order to format this information you have to define an +external construct of type \cs{anon}. + +\Section[sec:ext-item] Formatting an external file + +The hardest part is declaring the formatting of an external file. For +this a separate generic construct exists: the `external item' with +defining command \refcs{DefineExternalItem}. For example, if +\cs{Section} writes to \n{contents}, than an external item \n{Section} +corresponding to this file has to be declared. The option +\refopt{file} is use to declare to which file the external item +belongs. This way the same name can be reused for more than one file. + +\Ver>\DefineExternalItem:Section file:contents + [...] Stop<Rev + +An external item is basically a list with just one item. Thus, the +option \refopt{item} is available. The elements of an external item are +the label (the counter value), the page number where the information +was generated, and the title. +For the label (say for a construct \cs{Foo}) +an option \refopt{FooLabel} is created. +Thus the typical formating looks like +\Ver>\DefineExternalItem:Chapter file:contents + item:left ChapterLabel item:stop + title begingroup Spaces:2 Style:italic Page endgroup + Stop<Rev +In fact, a control sequence \refcs{FooLabel} is created, which +can be used in other external items. + +Since an external item is a list in itself, you have to pull a +certain trick to get items for subsections to indent further than +those for sections. This is what the command \cs{PushIndentLevel} was +designed for. + +A typical indented item looks like: +\Ver>\DefineExternalItem:SubSection file:contents + PushIndentLevel PushIndentLevel + item:left SectionLabel . SubSectionLabel item:stop + title begingroup Spaces:2 Style:italic Page endgroup + Stop<Rev + +\Section Example + +The following example is for a typical table of contents that +records sections and subsections. In good old-fashioned style, the +subsections are indented with respect to the sections. +\endinput +\Example +\DefineExternalFile:TheContents=tct +\DefineHeading:TestChapter Style:bold + line:start TestChapterCounter Spaces:2 title line:stop + external:TheContents title external:stop Stop +\DefineExternalItem:TestChapter file:TheContents + item:left Style:bold TestChapterLabel item:stop title white:5pt + Page par Stop +\DefineHeading:TestSection Style:italic + line:start TestChapterCounter . TestSectionCounter + Spaces:2 title line:stop + external:TheContents title external:stop Stop +\GoverningCounter:TestSection=TestChapter +\DefineExternalItem:TestSection file:TheContents PushIndentLevel + item:left Style:bold TestChapterLabel . TestSectionLabel item:stop + title white:5pt Page par Stop +\DefineExternalItem:anon file:TheContents begingroup + Style:italic title white:5pt Page par Stop + +\LoadExternalFile:TheContents +\TestChapter First heading\par +\TestSection First subheading\par +Some text might be nice. +\TestSection Second subheading\par +Some more text. +\ToExternalFile:TheContents={Enclosed Graphics} +\TestChapter Second heading\par +\TestSection Third subheading\par +Yet more text. +\TestSection Fourth subheading\par +And again: text. +\ExampleStop + +\endinput + +% 92/11/26 BibTeX section diff --git a/Master/texmf-dist/doc/otherformats/lollipop/manual/head.tex b/Master/texmf-dist/doc/otherformats/lollipop/manual/head.tex new file mode 100644 index 00000000000..cceb07930cf --- /dev/null +++ b/Master/texmf-dist/doc/otherformats/lollipop/manual/head.tex @@ -0,0 +1,118 @@ +% head.tex copyright 1992 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 <http://www.gnu.org/licenses/>. +% +% +\Chapter Headings + +Headings for sections, chapters, and such, are an essential part of +any \TeX\ macro package. In Lollipop they are maybe a bit less +special: all options for headings are general options, meaning that +they also apply to text blocks and lists. There are only two things +that distinguish headings: + +\Enumerate +\item there will be no page break after a heading; +\item there is no closing command for a heading. +\> + +\Section[sec:head:examples] Examples + +Headings are defined by \refcs{DefineHeading}. +The most obvious element in a heading is the title, marked by the +option \refopt{title}. The title is anything that follows the heading +command, upto the first empty line. + +\Ver>\SomeHeading Some title + +And some text following it.<Rev + +\ImpNote +Titles can also be terminated by \cs{par}, but knowledge of this is +not encouraged. See further~\ref[imp:title:delimiting]. +\ImpNoteStop + +The title has to be +included in a line or a textcolumn for proper handling (see +also section~\ref[sec:opt:traps]). For titles that do not exceed one +line, the \opt{line} option suffices (section~\ref[sec:opt:line]); if a +title is possibly more than one line long, the \opt{textcolumn} option +has to be used (section~\ref[sec:opt:textcolumn]. + +\Example +\DefineHeading:TestSection Style:bold + line:start TestSectionCounter Spaces:2 title line:stop + Stop +\TestSection The Title + +The text after the heading. +\ExampleStop + +By default, the text after a heading is indented. Overriding this +default behaviour is done with the option \refopt{indentafter}. + +\Example +\AlwaysIndent:no % as a default, don't indent paragraphs +\DefineHeading:TestSection Style:bold + line:start TestSectionCounter Spaces:2 title line:stop + indentafter:yes Stop +\TestSection The Title + +The text after the heading.\par +The second paragraph after the heading +\ExampleStop + +Usually headings come in a hierarchy, where the counter of one type, +for instance a subsection, is reset everytime the counter of a higer +level is stepped. In \Lollipop, this subordinating of headings is +done by declaring one counter to be governed by another (counters +are explained in full detail in section~\ref[sec:counters]). + +\Example +\DefineHeading:TestChapter Style:bold + line:start TestChapterCounter Spaces:1 title line:stop + Stop +\DefineHeading:TestSection Style:italic + line:start TestChapterCounter : TestSectionCounter . Spaces:1 + title line:stop Stop +\GoverningCounter:TestSection=TestChapter + +\TestChapter Level One Heading\par +\TestSection Level Two Heading\par +Some text. +\TestSection Level Two again\par +More text. +\TestChapter Level One is Stepped\par +\TestSection Level Two\par +Again text. +\ExampleStop + +Headings will often wind up in a table of contents. For this, the +table of contents will have to be declared: +\Ver>\DefineExternalFile:contents=toc<Rev +and its formatting will have to be specified, but also every +construct that writes to this file has to be declared as such. + +\Ver>\DefineHeading:TestSection + [...] + external:contents title external:stop + Stop<Rev + +Usually, the title is all that has to be written out (the counter +value is written by default), but the possibility exists for writing +out other information as well. See section~\ref[sec:ext-option]. + +\endinput
\ No newline at end of file diff --git a/Master/texmf-dist/doc/otherformats/lollipop/manual/list.tex b/Master/texmf-dist/doc/otherformats/lollipop/manual/list.tex new file mode 100644 index 00000000000..87396cbc1f2 --- /dev/null +++ b/Master/texmf-dist/doc/otherformats/lollipop/manual/list.tex @@ -0,0 +1,442 @@ +% list.tex copyright 1992 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 <http://www.gnu.org/licenses/>. +% +% +\Chapter Lists + +Lists in Lollipop are defined by \refcs{DefineList}: + +\Ver>\DefineList:Foo [...] + item:start [...] item:stop + [...] Stop<Rev +and the resulting list is used as +\Ver>\Foo +\item [ ..text.. ] +\item [ ... ] +\FooStop<Rev +where the closing command can be abbreviated as~\cs{>}. + +\Section Label alignment + +In general there is a default position for labels; +either aligning with the +left or the right side of the margin over which the list is indented. +The two ways are indicated with the option \refopt{item}: +\Ver> item:left [...] item:stop<Rev +and \Ver> item:right [...] item:stop<Rev respectively. +Specifying \opt{item:start} gives the default left aligning position. + +\Example +\DefineList:enumerate + item:start itemCounter ) item:stop Stop +\DefineList:enumerateright + item:right ( itemCounter ) Spaces:1 item:stop Stop +\enumerate\item Some item +\item And another +\enumerateright\item First nested item +\item Next nested item\> +\item And back to the original list.\> +\ExampleStop + +\Section List indentation + +The amount over which the text of a list (excluding the item labels) +is indented is controled by a list of indentations. This is explained +in section~\ref[sec:indent:control]. The indentation amount is most of +the time also equal to the value of the paragraph indentation outside +that list. + +In the rare case where the indentation of a list has to be controlled +explicitly, there is an option \refopt{indentation} with one value. +\Ver>\DefineList:SomeList indentation=30pt [...] Stop<Rev + + +\Section Label style + +Every list that uses the \refopt{itemsign} option is an `itemize' list, +no matter what it's name, and there is a counter in Lollipop that +keeps track of how deep you are in itemize lists. Similarly, every +list that uses \refopt{itemCounter} is an `enumerate' lists, and these +are counted too. + +On every next level a new style of item sign or counter is used. For +item signs this is in sequence: $\bullet$, $\circ$, --, and $\cdot$ +for all higher levels. The style of sign can be changed by +\refcs{SetItemSign}: \Ver>\SetItemSign:6=m<Rev where the letter +indicating the sign is interpreted as: \n b~$\bullet$ (bullet), \n +c~$\circ$ (circle), \n d~$\diamond$ (diamond), \n m~--- (em-dash), \n +n~-- (en-dash), \n .~$\cdot$. + +Similarly, the counter style can be set by +\refcs{SetItemCounterRepresentation}: +\Ver>\SetItemCounterRepresentation:2=i<Rev where the letter +representing the style is interpreted as: 1~Arabic, I~uppercase roman, +i~lowercase roman, A~uppercase characters, a~lowercase characters. + +\Section Label width + +The default width for a label is at most the width of the margin over +which the list is indented. Using \opt{item:left} or \opt{item:right} +will have the label pushed to the left or right side of this margin +respectively. Now what if the label material is wider than this +margin? Usually you want the label then to expand to the right, and +that is indeed what happens, unless you specify +\refopt{labeloverflow} with value \n{left}, in which case the right +boundary of the label will not budge, and the label will start +protruding into the outer margin. + +\Section[sec:description:list] Description lists + +A common type of list is the type where each item label consists of a +piece of text. Such a list is called a `description' list in +\Lollipop, and it recognized by the occurrence of the option +\refopt{description} in its definition. A~description list can also use +the item sign or the item counter, of course. + +Using a description list, the description text is everything that +follows the command \cs{item}, up to the end of the line. + +\Example +\DefineList:TestList + item:left Style:bold itemCounter . Spaces:1 description + Spaces:2 item:stop Stop +\TestList\item Do +A deer, a female deer.\item Re +According to mr. Fowler only a legal term. +\item Mimi Jett +The owner/founder of ETP\> +\ExampleStop + +As you can see, the problem of label overflow can easily occur with +description lists. Thus it is a good idea to end the item material +with some white space, as in the above example. + + Exceptional situation: +if you use an empty description text, you should write \ver>\item{}>. + +\Section Suspended lists + +Occasionally the is a need to resume an enumerate list, that is, +after a piece of text that is not part of the list an enumerate list +should start counting from the previous value on. In \Lollipop\ this +phenomenon can be realized by never ending the enumerate list, and +simply moving the text one indentation level back with +\refcs{PopIndentLevel}. + +\Example +\DefineList:enumerate item:left itemCounter item:stop Stop +\enumerate\item First some item\par +{\PopIndentLevel \Indent:no +This text seems to be outside the list. Don't you believe it.\par} +\item And another item\> +\ExampleStop + +Note that the `popped' text has to be in a group (otherwise the +subsequent items will also be popped back), and it has to be +separated from the preceding and following text by \cs{par}; the +trailing \cs{par} has to be in the group. + +\Section Item counter manipulation + +The item counter can be manipulated explicitly. This is necessary for +instance for starting a list at another value than one. What you need +to realize here is that the command \cs{item} starts by incrementing +the counter. Furthermore, the only way to access the item counter is +through the commands for counters; see section~\ref[sec:counters]. + +\Example +\DefineList:enumerate item:left itemCounter item:stop Stop +\enumerate \SetCounter:item=-1 +\item Escape: usually the backslash. +\item Begin Group.\> +\ExampleStop + +\Section List titles and list tails + +Lists can have titles. The title follows the command that invokes the +list, in the usual manner. Material to follow the list can also be +specified: anything following the option \refopt{text} is considered to +be trailing material. + +\Example +\DefineList:TestList hrule line:start Style:bold title line:stop + item:left Style:italic itemCounter item:stop + text vwhite:3pt hrule Stop +\TestList In the last fiscal year, have you:\par +\item Eaten peanuts? \item Walked the dog? +\item Bought a Frank Zappa record?\> +\ExampleStop + +In case you wonder what happens with textual material after +\opt{item:stop} and before any \opt{text}, well, that is taken to be +inserted immediately after each item label. + +\Section Between the items + +There are special list options controlling what happens in between +items. \Lollipop\ has an option \refopt{breakbetween}, analogous to +\opt{breakbefore} and \opt{breakafter}; see +section~\ref[sec:opt:penalties]. This item be default has a +value of~\n{$-50$}, implying that breaks in between items +should be preferred slightly over breaks in between the +lines of an item. + +Similarly, there is an option \refopt{whitebetween} +controlling the amount of white space in between items that is +analogous to \opt{whitebefore} and \opt{whiteafter}. Like these two +options, it can also be set by the \cs{Distance} command +(section~\ref[sec:com:distance]). + +\Section Indentation in lists + +An item can be considered to be consisting of at least one paragraph. +That paragraph is never indented. For the behaviour of any next +paragraph within the same item, the option \refopt{indentinside} can be +used. This option has values yes/no. In case paragraphs inside an +item indent, the indentation amount is level-controlled; see +section~\ref[sec:indent:control]. + +\Chapter[chap:text:block] Text Blocks + +The `text block' is a way of treating a moderate sized chunk of text +in a different way from the surrounding text. Text blocks are +created by \refcs{DefineTextBlock}. Here is a small example. + +\Example +\DefineTextBlock:Quote + PushIndentLevel PointSize:9 SetFont text Stop +\Indent:no In some context it has been written that +\Quote No man is an island.\QuoteStop +In another: +\Quote Run don't walk to the nearest island.\> +Sometimes one would wish women weren't so logical. +\ExampleStop + +Note that the text block has an explicit closing command, +consisting of the name of the block followed by \opt{Stop}, +and that implicit closing by \cs{>} is possible. + +\Section The \opt{text} option + +Text blocks have only one specific option: \refopt{text}. This option +is used to separate material heading the block from material trailing +the block. Example: + +\Example +\DefineTextBlock:DisplayEq + whitebefore:abovedisplayskip whiteafter:belowdisplayskip + line:start white:parindent $ displaystyle text $ line:stop Stop +The formula +\DisplayEq e^{\pi i}+1=0\> +contains nature's five most interesting constants. +\ExampleStop + +Here one dollar comes before the text, and one after, so the first is +inserted by \cs{DisplayEq} and the second by the corresponding +closing command. + +Material before and after the text should usually not be broken. +Hence \cs{nobreak} is automatically inserted. See the \cs{Example} +macro for this manual: pages should not be broken after rules, or +around the text `example~xyz'. + +\Section More examples + +A text block can encompass more than one paragraph, so the options +\opt{indentinside} and \opt{indentfirst} are particularly useful here. + +\Example +\AlwaysIndent:no +\DefineTextBlock:TestBlock PushIndentLevel + indentafter:yes indentfirst:no indentinside:yes + text unskip hfill $ bullet $ par Stop +One paragraph.\par The next paragraph +\TestBlock Inside the block one paragraph.\par +Inside the block the next paragraph.\> +Outside the following paragraph.\par And the last paragraph. +\ExampleStop + +\ImpNote +\iSection[imp:gen:open:close] The environment in generic constructs + +The text block is just about the purest use of the \Lollipop\ +environment mechanism. Here is how a text block is defined: +\Ver> +\def\@DefineTextBlock{ + \csarg\edef{\@name}{\@gen@open + \the\before@coms + } + \@DefineStopCommand{\the\after@coms \@gen@close} + }<Rev + +The \cs{before@coms} and \cs{after@coms} are two token lists with +the heading and trailing commands. + +It is important to note that the definition of the control sequence +of the block is defined by \cs{edef}. This first of all unwraps the +token lists, but it also has an important effect on +\cs{@gen@open/close}. These control sequences contain a lot of +conditionals which, in combination with the \cs{edef} give a really +dynamic definition of generic constructs in \Lollipop. + +First of all, the opening and closing commands induce a group +so that various quantities can be set locally. +\Ver> +\def\@gen@open{\outer@start@commands + \begingroup \inner@start@commands} +\def\@gen@close{\inner@end@commands + \endgroup \outer@end@commands}<Rev + +The outer start commands concern global actions such as backspacing +previous skips, incrementing counters and setting references. +\Ver> +\def\outer@start@commands{% + \iftext@construct + \ifleft@embedded@construct + \nxp\bsp@hack + \else \nxp\leavehmode \nxp\bvwit{\the\@whitebefore}\fi<Rev +The `embedded construct' tests are only true if the construct +can be embedded in a paragraph. A~rare occurence most of the time. +\Ver> + % backspace previous white space while it's visible + \nxp\if@headed\nxp\else + \ifforced@break@before\@beforepenalty + \else\nxp\ifnum\lastpenalty=\z@ + \@beforepenalty\nxp\fi + \fi + \nxp\fi<Rev +A subtle point: a preceding heading will have placed \cs{nobreak} +followed by a skip. It is dangerous to place any sort of penalty +after this because it might induce a page break. + +Now the counter, title, and stuff connected to that. +\Ver> + \fi + \ifhas@counter \nxp\StepCounter:\expandafter\@name\@space + % This sets the \current@label by default<Rev +Since this is used inside an \cs{edef} we can use some trickery +to get the space token after the argument to \cs{StepCounter}. +\Ver> + \ifhas@marks \edef\nxp\cs@e + {\nxp\nxp\nxp\refresh@mark@item + {\@name Counter}{\CSname{\@name Counter}}}% + \nxp\cs@e + \fi + \fi + \iflabel@defined + \global\current@label={\the\@labelcoms}\fi + \ifhas@title \install@title@code<Rev +This title business is explained in~\ref[imp:install:title]. +This piece of code also refreshes the title in the mark structure. +This has to be done after any page break for the benefit +of headers/footers. +\Ver> + \fi + \ifhas@marks\nxp\ifnin{\nxp\place@mark}\fi + %otherwise IniTeX'ing Lollipop will output a page + \nxp\xx@label\the\extern@toks\penalty\@M + % also subtle: if this white space would be higher, it would + % be invisible because of marks et cetera. + % insert nobreak after marks/writes to prevent page breaks. + \iftext@construct + \ifleft@embedded@construct + \else \nxp\@vwhite{\the\@whitebefore}\fi + \fi + }<Rev + +Inner start commands are concerned with setting local values. +\Ver> +\def\inner@start@commands{% + \nxp\Open@Group\CSname{\@class}\CSname{\@name}%<Rev +The \cs{Open@Group} call makes it possible to track down groups +that have inadvertendly been left open. Since we now know the +name we can give helpful error msgs. +\Ver> + \install@stop<Rev +Install the right implicit closing, see~\ref[sec:implicit:close] +and~\ref[imp:implicit:close]. +\Ver> + \ifleft@embedded@construct + \else \nxp\hold@parskip + \nxp\@defaulteverypar + \ifwhiteleft@defined \advance\leftskip \the\@whiteleft \relax \fi + \ifwhiteright@defined \advance\rightskip \the\@whiteright \relax \fi + \nxp\let\nxp\par=\nxp\@par %explain to me again why this is necessary... + \inside@indent \first@indent + \fi + \advance\nest@depth\@ne<Rev +The nest depth is used for determining indentation levels. +\Ver> + }<Rev + +End commands set up some conditions, most of which will be tested +by the start of any next construct. +\Ver> +\def\inner@end@commands{% + \nxp\Close@Group\CSname{\@class}\CSname{\@name}% + \ifright@embedded@construct \else \nxp\leavehmode \fi + \@afterpenalty + \ifright@embedded@construct \else \nxp\@vwhite{\the\@whiteafter}\fi + } +\def\outer@end@commands{% + \the\after@toks + \ifright@embedded@construct + \nxp\@headedno \nxp\esp@hack + \else + \after@indent \nxp\dono@parskip + \fi}<Rev + +\iSection[imp:implicit:close] Implicit closing + +Constructs with an explicit closing command, lists and text blocks, +can be closed by~\cs{>}, which simply closes the current +construct. A~more drastic version, \cs{>]}, closes all currently +open constructs. +\Ver> +\def\outer@stop@command{\Emessage{Vacuous group closing}} +\let\default@stop@command\outer@stop@command +\def\>{\default@stop@command%[fool the editor + \ifNextChar]{% + \ifx\default@stop@command\outer@stop@command + \xp\take@one + \else \xp\>\fi}{}}<Rev +The \cs{outer@stop@command} is meant to give an error msg if the +user attempts to close a group while none is open. + +The current meaning of~\cs{>} is installed in +\cs{inner@start@commands}: +\Ver> +\def\install@stop{\if@implicitclose + \def\nxp\default@stop@command + {\CSname{\stop@command}}% + \else \let\nxp\default@stop@command + \nxp\outer@stop@command + \fi}<Rev + +By default, constructs can be closed implicitly, but there is an +option \refopt{noimplicitclose} to disable this. +\Ver> +\newif\if@implicitclose +\add@generic@default{\@implicitcloseyes} +\@GenericOption{noimplicitclose}{\@implicitcloseno}<Rev +This option is for instance used in the examples in this manual. +Otherwise closing a construct in the example would also close the +example itself. + +\ImpNoteStop + +\endinput
\ No newline at end of file diff --git a/Master/texmf-dist/doc/otherformats/lollipop/manual/lollipop-manual.bib b/Master/texmf-dist/doc/otherformats/lollipop/manual/lollipop-manual.bib new file mode 100644 index 00000000000..d7429919159 --- /dev/null +++ b/Master/texmf-dist/doc/otherformats/lollipop/manual/lollipop-manual.bib @@ -0,0 +1,59 @@ +@article{EL:Cork, +author = {Victor Eijkhout and Andries Lenstra}, +title = {The document style designer as a separate entity}, +journal = {TUGboat}, +volume = {12}, +issue = {1}, +year = {1991}, +pages = {31--34} +} + +@misc{E:book, +author = {Victor Eijkhout}, +title = {{\TeX} by Topic}, +publisher = {Addison-Wesley}, +howpublished = {{\tt http://eijkhout.net/texbytopic/texbytopic.html}}, +year = {1992} +} + +@article{E:Portland, +author = {Victor Eijkhout}, +title = {Just give me a Lollipop (it makes my heart go giddy-up)}, +journal = {TUGboat}, +volume = {13}, +issue = {3}, +year = {1992}, +pages = {341--346} +} + +@book{Kn:book, +author = {Donald E. Knuth}, +title = {The {\TeX} Book}, +publisher = {Addison-Wesley}, +year = {1984, reprinted with corrections 1989} +} + +@book{La:book, +author = {Leslie Lamport}, +title = {{\LaTeX} A Document Preparation System}, +publisher = {Addison-Wesley}, +year = {1986} +} + +@article{Pe:epigrams, +author = {Alan Perlis}, +title = {Epigrams on programming}, +journal = {ACM Sigplan Notices}, +volume = {17}, +issue = {9}, +year = {1982}, +pages = {7--13} +} + +@book{SeLe:book, +author = {Raymond Seroul and Silvio Levy}, +title = {A Beginner's Book of \TeX}, +publisher = {Springer Verlag}, +year = {1990} +} + diff --git a/Master/texmf-dist/doc/otherformats/lollipop/manual/lollipop-manual.pdf b/Master/texmf-dist/doc/otherformats/lollipop/manual/lollipop-manual.pdf Binary files differnew file mode 100644 index 00000000000..a91065dc19a --- /dev/null +++ b/Master/texmf-dist/doc/otherformats/lollipop/manual/lollipop-manual.pdf diff --git a/Master/texmf-dist/doc/otherformats/lollipop/manual/lollipop-manual.tex b/Master/texmf-dist/doc/otherformats/lollipop/manual/lollipop-manual.tex new file mode 100644 index 00000000000..9ad2d7b743a --- /dev/null +++ b/Master/texmf-dist/doc/otherformats/lollipop/manual/lollipop-manual.tex @@ -0,0 +1,99 @@ +% lollipop-manual.tex master file for the Lollipop TeX manual. +% this file and all input files for it copyright 1992 Victor Eijkhout, +% copyright 2014 Vafa Khalighi, +% except where indicated otherwise. +% +% +% 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/>. +% +% +\tracingstats=1 +\makeatletter +\makeatother +\showboxdepth=-1 + +\input comment +% By shuffling the \comment line you can load different fonts. +% This is machine dependent, so by default you get the CM font, +% which should work everywhere. +% +\def\SerifFace{\TypeFace:ComputerModern } +\def\SansFace{\TypeFace:ComputerSans } +\comment +% Macintosh Times & Helvetica +\def\SerifFace{\TypeFace:macTimes } +\def\SansFace{\TypeFace:macHelvetica } +% Unix Postscript has different names +\def\SerifFace{\TypeFace:unixTimes } +\def\SansFace{\TypeFace:unixHelvetica } +\endcomment + +% Now load the style definition. This takes some time. +\input mandefs + +% Prevent regeneration of external files; change 'yes' into 'no' +% if you are changing page dimensions or so. +\WriteExtern:yes + +% BibTeX interface by Berry and Patashnik +\input btxmac + +% Start formating +\Start + +% Include the next line if you are formatting the second half +% of this manual: +%\comment + +\CounterRepresentation:Page=i \RightPage +\InputFile:titlepag + +\InputFile:prelim +\SetCounter:LastInPage=PageValue +\BackStepCounter:LastInPage + +\ToRecto\RightPage +\CounterRepresentation:Page=1 \SetCounter:Page=1 + +\InputFile:struct + +\InputFile:head + +\InputFile:list + +% For the first half include the following line: +%\Stop +% For second half include the following lines: +%\endcomment +%\RightPage \SetCounter:Page=11 + +\InputFile:out + +\InputFile:extern + +\InputFile:opt + +\InputFile:comm + +\InputFile:trace + +\InputFile:appendix + +\SetCounter:LastRegPage=PageValue +\BackStepCounter:LastRegPage +\Stop + +% 2014/04/11 Updated the manual +% 92/11/20 Total pages counter +% 93/01/08 \comment and such for two part processing diff --git a/Master/texmf-dist/doc/otherformats/lollipop/manual/mandefs.tex b/Master/texmf-dist/doc/otherformats/lollipop/manual/mandefs.tex new file mode 100644 index 00000000000..e952bea1ebb --- /dev/null +++ b/Master/texmf-dist/doc/otherformats/lollipop/manual/mandefs.tex @@ -0,0 +1,225 @@ +% mandefs.tex style definition for the Lollipop manual +% 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 <http://www.gnu.org/licenses/>. +% +% +\def\con#1{{\tt#1}} +\def\n#1{{\tt#1}} +\def\file#1{{\tt#1}} + +\def\Lollipop{Lollipop} + +\Distance:rightmarginstretch={0cm plus 2.54cm} +\Distance:whitebefore={6pt plus 3pt minus 2pt} +\Distance:whiteafter=whitebefore +\FlushRight:no + +\DefineExternalFile:contents=toc + +\DefineHeading:Chapter + breakbefore:yes whiteafter:20pt + line:start PointSize:14 Style:bold literal:Chapter + Spaces:1 ChapterCounter line:stop + vwhite:15pt + line:start PointSize:16 Style:bold title line:stop + external:contents title external:stop + Stop + +\AdaptiveDistance:WidestLabel=15pt +\def\MeasureLabel{\ifdim\BlockWidth>\WidestLabel + \global\WidestLabel\BlockWidth\fi} +\StartCommand{\Distance:parindent=WidestLabel } +\DefineHeading:Section + whitebefore:{20pt plus 2pt} whiteafter:14pt + line:start PointSize:14 Style:italic + block:start block:start ChapterCounter . SectionCounter + Spaces:1 block:stop MeasureLabel + fillupto:WidestLabel + title line:stop + external:contents title external:stop + label:start ChapterCounter . SectionCounter label:stop + Stop +\GoverningCounter:Section=Chapter + +\DefineHeading:SubSection + whitebefore:{14pt plus 2pt} whiteafter:8pt + line:start PointSize:10 Style:italic + ChapterCounter . SectionCounter . SubSectionCounter + Spaces:1 title line:stop + label:start ChapterCounter . Spaces:.2 SectionCounter + . Spaces:.2 SubSectionCounter label:stop + Stop +\GoverningCounter:SubSection=Section + +\DefineExternalFile:impnotes=imp +\DefineHeading:iSection + whitebefore:{10pt plus 1pt} whiteafter:8pt + line:start PointSize:12 Style:bold I - + Style:italic iSectionCounter + Spaces:1 title line:stop + label:start I - iSectionCounter label:stop + external:impnotes title external:stop + Stop +%\GoverningCounter:iSection=Chapter +\DefineExternalItem:iSection file:impnotes PushIndentLevel + item:left I - Style:italic iSectionLabel item:stop + title begingroup Spaces:2 Style:italic Page endgroup + Stop + +\DefineExternalItem:Chapter file:contents + item:left ChapterLabel item:stop + title begingroup Spaces:2 Style:italic Page endgroup + Stop +\DefineExternalItem:Section file:contents PushIndentLevel + item:left ChapterLabel . SectionLabel item:stop + title begingroup Spaces:2 Style:italic Page endgroup + Stop + +\def\impnotetxt{Implementor's Note} +\DefineTextBlock:ImpNote PushIndentLevel + whitebefore:12pt whiteafter:11pt + line:start PointSize:12 Style:italic impnotetxt line:stop + SansFace PointSize:9 SetFont text + Stop +\excludecomment{ImpNote} + +\DefineTextBlock:WizNote + PushIndentLevel PointSize:9 SetFont text + Stop + +\DefineList:Description + item:left description Spaces:2 item:stop whitebetween:6pt + Stop + +\DefineList:cDescription + item:left tt char busje description Spaces:2 item:stop + whitebetween:6pt + Stop + +\DefineList:Enumerate + item:left itemCounter item:stop + Stop + +\DefineList:Itemize + item:left itemsign item:stop + Stop + +\DefineBBL + item:left [ - itemCounter - ] item:stop + Stop + +\SerifFace \SetFont + +\newwrite\exfile +\def\HereAndOut#1{\immediate\write\exfile{#1}} +\specialcomment{Example} + {\EExample + \immediate\openout\exfile=example.tex\relax + \let\ThisComment\HereAndOut} + {\immediate\closeout\exfile + \begingroup \tt \SetFont + \verbatimfile{example.tex}\endgroup + \SaveAlloc \input example.tex\relax \RestoreAlloc + \EExampleStop} +\DefineTextBlock:EExample whiteafter:{6pt plus 5pt} + noimplicitclose rule:h vwhite:3pt + line:start literal:Example Spaces:1.5 + ChapterCounter . EExampleCounter + line:stop + vwhite:3pt rule:h vwhite:3pt text vwhite:3pt rule:h + Stop +\GoverningCounter:EExample=Chapter + +\specialcomment{OutExample} + {\EExample + \immediate\openout\exfile=example.tex\relax + \let\ThisComment\HereAndOut} + {\immediate\closeout\exfile + \begingroup \tt \SetFont + \verbatimfile{example.tex}\endgroup + \par\penalty0\relax + \SaveAlloc \SuspendOutput \begingroup \CountSheetsno + \global\setbox\PageRow\hbox{}% + \let\CurrentShipout\ToPageRow + \xInputFile:example + \endgroup + \ResumeOutput \RestoreAlloc + \noindent\unhbox\PageRow\hbox{}\par + \EExampleStop} +\newbox\PageRow\newbox\RowPage +\def\ToPageRow{\setbox\RowPage\box\WholePage \xToPageRow} +\def\xToPageRow{\global\setbox\PageRow + \hbox{\unhbox\PageRow\box\RowPage\hfill}} + +\def\opt#1{{\tt#1}} +\DefineExternalFile:optindex=oix +\def\refopt#1{\OptToIdx #1\par} +\DefineHeading:OptToIdx embedded:yes + block:start tt title block:stop + external:optindex title external:stop + nomarks Stop +\DefineExternalItem:OptToIdx file:optindex + embedded:yes + begingroup tt title endgroup + nobreak Spaces:1.5 Page Spaces:2.5 Stop + +\DefineExternalFile:csindex=cix +\def\refcs#1{\CsToIdx #1\par} +\DefineHeading:CsToIdx embedded:yes + block:start tt char busje title block:stop + external:csindex title external:stop + nomarks Stop +\DefineExternalItem:CsToIdx file:csindex + embedded:yes + begingroup tt char busje title endgroup + nobreak Spaces:1.5 Page Spaces:2.5 Stop + +\topskip20pt +\OptionsMacro:PageDims=width:page=15cm height:page=23cm Stop +\DefinePageGrid:LeftPage macro:PageDims + band:start block:start PointSize:9 Style:italic + FirstPlaced:ChapterCounter Spaces:2 stickout:left + FirstPlaced:ChapterTitle band:stop + textband:start text textband:stop + band:invisible block:start PointSize:9 Style:bold + PageCounter Spaces:2 stickout:left band:stop + NextPageGrid:RightPage Stop +\DefinePageGrid:RightPage macro:PageDims + band:start fillup PointSize:9 Style:italic + LastPlaced:SectionTitle + block:start Spaces:2 LastPlaced:ChapterCounter . + LastPlaced:SectionCounter stickout:right + band:stop + textband:start text textband:stop + band:invisible fillup + block:start PointSize:9 Style:bold Spaces:2 + PageCounter stickout:right band:stop + NextPageGrid:LeftPage Stop +\DefinePageGrid:EmptyPage macro:PageDims + textband:start text textband:stop + NextPageGrid:LeftPage Stop + +\AdaptiveCounter:LastInPage \CounterRepresentation:LastInPage=i +\AdaptiveCounter:LastRegPage \CounterRepresentation:LastRegPage=1 +%\SetCounter:LastInPage=PageValue -- at the end of prelim.tex +%\SetCounter:LastRegPage=PageValue -- at the end of manual.tex + +\endinput + +% 92/11/05 stretch added +% 92/11/18 adaptive label width +% 92/11/19 adaptive last page
\ No newline at end of file diff --git a/Master/texmf-dist/doc/otherformats/lollipop/manual/opt.tex b/Master/texmf-dist/doc/otherformats/lollipop/manual/opt.tex new file mode 100644 index 00000000000..041842ff8da --- /dev/null +++ b/Master/texmf-dist/doc/otherformats/lollipop/manual/opt.tex @@ -0,0 +1,408 @@ +% opt.tex copyright 1992 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 <http://www.gnu.org/licenses/>. +% +% +\Chapter Options + +This chapter discusses the various options that are common to all +\Lollipop\ constructs. + +\Section Titles + +Any construct can have a title, although of course it is most useful +for headings. +A construct has a title if the option \refopt{title} appears. +Example: +\Ver> +\DefineHeading:Section [...] + Style:bold title + [...] Stop<Rev + +will define a \cs{Section} macro that has a title. +The macro is then used as +\Ver> +\Section The title of this section + +Some text in this section.<Rev +that is, the title is delimited by an empty line. + +The title is actually available as a macro \refcs{FooTitle}, so that you +can write a macro, for instance +\Ver> +\def\ComplicatedTitle{ .. \hrule ... + \vrule ... \vbox \bgroup ... + \FooTitle ... + }<Rev +and use this macro instead of the \opt{title} option +\Ver>\DefineBar:Foo ... + ComplicatedTitle + ... Stop<Rev +However, since the option \opt{title} now doesn't appear anymore, it +becomes necessary to specify explicitly that there is a title. +This can be done with the \refopt{HasTitle} option. For instance, +you define +\Ver>\DefineBar:Foo ... + HasTitle + ComplicatedTitle + ... Stop<Rev +where \cs{ComplicatedTitle} is a macro that formats the title. + +\SubSection Short titles + +The option \opt{HasTitle} can have a parameter \n{short}, denoting that +the title is not delimited by an empty line (or \cs{par}) but by the +line end. For an example see section~\ref[sec:address]. + +\Section[sec:opt:counter] Counters + +There are three ways for Lollipop to figure out that a generic +construct has a counter. First of all, in +\Ver>\DefineFoo:Bar [...] + BarCounter [...]<Rev +the \cs{BarCounter} will be defined automatically. + +Additionally there is the option \refopt{counter}, which can be used +to declare the representation of the option, for instance +\opt{counter:i} allocated a counter that is printed in lowercase roman +numerals. For the available representations, +see~\ref[sec:counter:repr]. + +Finally, if the counter is only used in a macro, the +option \refopt{HasCounter} will cause the counter to be created anyhow. +This is analogous to the \opt{HasTitle} option. + +\SubSection Counter synonyms + +Every once in a while you may want different constructs to use the same +counter. For instance, if your book has definitions, theorems, lemmas, +corollaries and notations, it may confuse the reader if they all have +their own counter. The numbering would seem to jump all over the place. + +A `counter synonym' can be declared in \Lollipop\ by a slight abuse of +the \opt{counter} option. +\Example +\DefineTextBlock:Theorem counter:1 begingroup Style:bold + literal:Theorem Spaces:1 TheoremCounter Spaces:2 endgroup + text Stop +\DefineTextBlock:Corollary counter:Theorem begingroup Style:italic + literal:Corollary Spaces:1 CorollaryCounter Spaces:2 endgroup + text Stop +\DefineTextBlock:Definition counter:Theorem begingroup Style:roman + literal:Definition Spaces:1 DefinitionCounter Spaces:2 endgroup + text Stop +\Definition We define a {\it Foo} to be an arbitrary object\> +\Theorem Foos have arbitrary properties\> +\Corollary Foos are extremely valuable\> +\Corollary Foos are extremely worthless\> +\Theorem Foos don't exist\> +\ExampleStop + +You can only declare a counter to be synonym for something that has +already been created. In the above example you cannot define the +\cs{Theorem} after the \cs{Corollary}. + +\ImpNote +At the start of defining the construct, \cs{BarCounter} is defined to +be an option: +\Ver>\add@generic@default{\has@counterno + \def\counter@repr{1} + \csarg\def{\gen@option@name{\@name Counter}}{% + \@add@toks{\@name Counter}\global\has@counteryes}}<Rev + +Then, +\Ver>\add@generic@stop@default{\ifhas@counter + \xp\expandafter\xp\install@counter + \xp\counter@repr\@space\fi}<Rev + + +The counter is stepped, and the new value is stored in a mark item, +in \cs{outer@start@commands}: + +\Ver> + \ifhas@counter + \nxp\StepCounter:\expandafter\@name\@space + % This sets the \current@label by default + \ifhas@marks \edef\nxp\cs@e + {\nxp\nxp\nxp\refresh@mark@item + {\@name Counter}{\CSname{\@name Counter}}}% + \nxp\cs@e + \fi + \fi<Rev +\ImpNoteStop + +\Section Chunks of text + +Especially in headings, short chunks of text may need a special +treatment. For instance, the number may have to be filled to a certain +width, or a line may have to be drawn of the exact length of the +title. Lollipop have various general options (so they can also be used +in other contexts than headings) for handling pieces of text. + +\SubSection[sec:opt:block] The \opt{block} option\label[opt:block] + +The \refopt{block} option takes up a piece of text and fits it on one +line. It can measure the text, or set the size. Also there are a number +of ways of placing a block. + +Basic usage: +\Ver> block:start [...] block:stop<Rev +This takes the enclosed text, and reproduces it. This is mostly +interesting in combination with \opt{textcolumn}, +see~\ref[sec:opt:textcolumn]. +\Ver> block:hang [...] block:stop<Rev +The resulting block is dropped until its top touches the baseline. +For uniformity of appearance, the resulting width of the block can be +specified: +\Ver> block:start [...] fillupto:20pt<Rev +The name of a \cs{Distance} parameter can be used here. + +\Example +\DefineHeading:TestHeading + line:start block:hang PointSize:8 SetFont + TestHeadingCounter fillupto:20pt + block:hang PointSize:14 SetFont title block:stop + line:stop Stop +\TestHeading Top Aligning the Title + +\endExample + +The block is usually in between the margins of the text, but it can be +made to stick out into the margin, by closing it with the option +\refopt{stickout}. For the left margin this done as + \Ver> block:start [...] stickout:left<Rev +and for the right margin + \Ver> block:start [...] stickout:right<Rev +The size of the box can be specified, for instance as + \Ver> block:start [...] stickout:left=20pt<Rev +For a left box the material in it is pushed to the left edge, for a +right sticking box it is shifted to the right. + +\SubSection[sec:blockwidth] Block Measuring + +All blocks are immediately measured when they are placed. This makes it +possible for instance to underline a title exactly. After a block has +been placed, its width is available as \refcs{BlockWidth}. + \Example +\def\rulespecs{height 1pt width \BlockWidth\relax} +\DefineHeading:TestHeading Style:bold + line:start block:start TestHeadingCounter . Spaces:2 stickout:left + block:start title block:stop line:stop + vwhite:2pt hrule rulespecs vwhite:10pt Stop +\TestHeading The Title Is Underlined + +The text follows. +\ExampleStop +Observe how a control sequence \cs{rulespecs} is used to sneak the +height and width of the rule into the definition. This is necessary +because control sequences are not allowed in a construct definition. + +\SubSection[sec:opt:line] The \opt{line} option + +The option \refopt{line} is used to create a single strip of text that +fits exactly in between the margins of the page. Most of the time, titles +will be in a line. + +\Example +\DefineHeading:TestHeading + line:start block:start TestHeadingCounter Spaces:1.5 stickout:left + title line:stop Stop +\TestHeading A Title + +\endExample + +Another example was above. Here is another use of a line: + +\Example +\DefineHeading:TestHeading + line:start TestHeadingCounter fillup title line:stop Stop +\TestHeading The title + +\endExample + +\SubSection[sec:opt:textcolumn] The \opt{textcolumn} option + +In the examples above all titles fit on one line comfortably. If this +is not the case, the title can be put in a \refopt{textcolumn} which can +span several lines. + +\Example +\DefineHeading:TestHeading + line:start block:start TestHeadingCounter Spaces:2 block:stop + textcolumn:topline title textcolumn:stop + line:stop Stop +\TestHeading A very very very very very very very very very very very +very very very very very very very very very very very very very +very very very very very very very very long title + +\endExample + +This option is mostly interesting in combination with others such as +\opt{block} and \opt{line}. As is apparent from the above example: a +block placed in the same line as a text column will detract from the +latter's width. + +(In fact it is the other way around: \Lollipop\ sets +the line with a text column of width zero to determine the remaining +space. Then the line is set again. This may give problems if you +manipulate parameters inside the line, because the line is in effect +typeset twice. Also make sure not to have other \cs{vbox}-es in the +line than the text column.) + +\SubSection[sec:opt:traps] Traps + +It is a bad idea to have material in headings and such that is not +inside a block, textcolumn, or line. For instance: + +\Example +\DefineHeading:TestHeading + block:start TestHeadingCounter Spaces:2 block:stop + title Stop +\TestHeading Where does the title go? + +\endExample + +\Section[sec:opt:label] Labels + +References to any counter will always be correct, no matter if that +counter has changed after retypesetting the document, if symbolic +references are used. Referencing is explained in detail in +chapter~\ref[chap:referencing]. + +The way a symbolic reference is formatted can be altered from the +default (just give the counter) by using the \refopt{label} option. +\Ver>\DefineHeading:TestSection + line:start Style:italic TestSectionCounter Spaces:2 title line:stop + label:start ( TestSectionCounter ) label:stop Stop<Rev +See further section~\ref[sec:shape:reference]. + + +\Section[sec:opt:penalties] Break before / after + +The options \refopt{breakbefore} and \refopt{breakafter} control how +eager \TeX\ will be to break the page before or after a construct. These +options take one value, a so-called `penalty' value, meaning that the +higher the value you specify, the higher the penalty is, and +therefore the less likely it is that the page will be broken there. + +Numerical values are typically in the tens or hundreds; any value +of \n{10$\,$000} or more means that there will never be a break at +that point; a value of \n{-10$\,$000} or less means a guaranteed +break. If you don't want to remember these rules, values of \n{yes} +and \n{no} mean a guaranteed break, and no break respectively. + +\WizNote +A further exceptional value is \n{breakbefore/after:0}, this will +cause no penalty to be placed. The reason for this is highly \TeX +nical. +\> + +\Section[sec:opt:indent] Indentation + +The option \refopt{indentafter} controls the behaviour of the first +paragraph after a generic construct., \refopt{indentinside}, +\refopt{indentfirst}. + +\Section Rules + +There is an option \refopt{hrule}. You should not write +\Ver>\def\rulemacro{\hrule height [...] } +\DefineHeading [...] rulemacro [...] Stop<Rev +because then \Lollipop\ cannot prevent page breaks around the rule. +Instead write +\Ver>\def\rulespecs{ height [...] } +\DefineHeading [...] hrule rulespecs [...] Stop<Rev +so that the option \opt{hrule} is used. See +section~\ref[sec:blockwidth] for an example. + +\Section Embedded constructs + +Most generic constructs will be vertically separated from the +surrounding text. However, in rare cases (and for unusual applications) +it be desired to have a construct that is part of a paragraph. For this +the option \refopt{embedded} exists. + +This option has the following values. +\Ver> embedded:no<Rev +This is the default. +\Ver> embedded:left<Rev +The construct continues an already started paragraph, but after the +construct a vertical break follows. +\Ver> embedded:right<Rev +After the construct a paragraph can continue, but the construct is +separated vertically from preceding text. +\Ver> embedded:yes<Rev +The construct is both left and right embedded. + +Embedding a construct has an interesting application to generating +indexes. (See chapter~\ref[chap:external-files] for general information +about external files.) This can be done by having embedded headings +that write their title to the index file. + +\Example +\DefineExternalFile:tIndex=tix +\DefineHeading:NewWord embedded:yes + block:start Style:bold title block:stop + external:tIndex title external:stop Stop +\def\introword#1{\NewWord #1\par} +In this sentence two \introword{flubrious} words are +\introword{stinselsed}. +\ExampleStop + +Cute, ain't it? + +A word of warning though. Headings and such generate \TeX\ `marks' +which take up main memory. You only need these if you are going +to be referring to that object with \cs{LastPlaced} or such; see +section~\ref[sec:head/foot]. Embedded headings used as above +usually don't need these marks, so you can prevent \TeX\ overflow by +putting the option \opt{nomarks} in their definition. + +\Section Obscure options + +\SubSection Arguments + +In case you want to interface to other macro packages, you may want to +let a construct generate a call to the other package. For this, the +\Lollipop\ macro should be able to produce sequences such as +\ver>\begin{itemize}>. The problem here is the braces. The option +\refcs{arg} produces a braced expression. + +For instance +\Ver>\DefineTextBlock:LaTeXlist begin arg:{itemize} text + end arg:{itemize} Stop<Rev +makes it possible to use call \LaTeX\ macros from \Lollipop. + +\SubSection[sec:implicit:close] Implicit closing + +The control sequence \refcs{>} closes the current group, and \refcs{>]} +closes all currently open groups. Every once in a while this is too +drastic. Hence there is an option \refopt{noimplicitclose} that can be +used to prevent a construct from being closed implicitly. Using \cs{>]} +inside such a construct will close all enclosed constructs. + +See the definition of \cs{EExample} in this manual for an example. + +\Section[sec:opt:test] Testing + +There is an option \opt{test}. + +\endinput + +% 92/11/10 \BlockWidth discussed in 'block' section +% 92/11/15 counter:othercounter discussed +% 92/11/21 option 'arg' + diff --git a/Master/texmf-dist/doc/otherformats/lollipop/manual/out.tex b/Master/texmf-dist/doc/otherformats/lollipop/manual/out.tex new file mode 100644 index 00000000000..9ed6cc00022 --- /dev/null +++ b/Master/texmf-dist/doc/otherformats/lollipop/manual/out.tex @@ -0,0 +1,349 @@ +% 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 <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 diff --git a/Master/texmf-dist/doc/otherformats/lollipop/manual/prelim.tex b/Master/texmf-dist/doc/otherformats/lollipop/manual/prelim.tex new file mode 100644 index 00000000000..c124feb91db --- /dev/null +++ b/Master/texmf-dist/doc/otherformats/lollipop/manual/prelim.tex @@ -0,0 +1,361 @@ +% prelim.tex copyright 1992 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 <http://www.gnu.org/licenses/>. +% +% +\Chapter[chap:prelim] Preliminaries + +\Section What is Lollipop? + +Lollipop is `\TeX\ made easy'. Lollipop is a macro package +that functions as a toolbox for writing \TeX\ macros. It was my +intention to make macro writing so easy that implementing a fully new +layout in \TeX\ would become a matter of less than an hour for an +average document, and that it would be a task that could be +accomplished by someone with only a very basic training in \TeX\ +programming. + +Lollipop is an attempt to make structured text formatting available +for environments where previously only wysiwyg packages could be used +because adapting the layout is so much more easy with them than with +traditional \TeX\ macro packages. + +\Section But is it compatible? + +Lollipop, like \LaTeX, is not compatible with plain \TeX. I~don't +consider this a real problem. Most plain \TeX\ commands will work in +\Lollipop\ with the exception of anything output routine related. +(See also below.) + +\Lollipop\ is also not compatible with \LaTeX, although it has a lot +of the same functionality. There are two reasons why \Lollipop\ still +has a reason for existing, even though \LaTeX\ is used pretty much +all over the scientific world. + +For one, Lollipop is targeted in part +to different users than the typical plain \TeX\ or +\LaTeX\ user. For another, I~have a vain hope that I~can capture some +of the \LaTeX\ market share. Since developing styles in \Lollipop\ is +so much more easier than in \LaTeX, I~may stand a fighting chance. + +\SubSection \Lollipop\ and plain \TeX + +Having said the above, I'll conceded that \Lollipop\ is more +compatible with plain \TeX\ than with \LaTeX. You can use quite some +plain \TeX\ commands in \Lollipop. However, stay away from the +following:\Description\item \cs{everypar} +This one is heavily used by \Lollipop. You may use \cs{EveryParagraph} +instead, which functions pretty much like \cs{everypar}; see +section~\ref[sec:everypar].\item \cs{everymath} +This one is heavily used by \Lollipop. You may use \cs{EveryMath} +instead, which functions pretty much like \cs{everymath}; see +section~\ref[sec:everymath].\item \cs{everydisplay} +This one is heavily used by \Lollipop. You may use \cs{EveryDisplay} +instead, which functions pretty much like \cs{everydisplay}; see +section~\ref[sec:everydisplay].\item \cs{output} +Page output is done so very differently from plain \TeX\ that all +commands pertaining to page numbers and head/footlines have been +eradicated. (Well, \cs{pageno} still gives the page number.) See +chapter~\ref[chap:output]. + \> + +The current version of \Lollipop\ is based on the plain \TeX\ file +that comes with \TeX\ version~3.141592653. + +\SubSection \Lollipop\ and \TeX\ programming + +The tools in \Lollipop\ allow you to program in a simple manner quite +complicated macros. Still you may want to have some knowledge of +ordinary \TeX\ macro programming. If you are just starting in \TeX\ +you can pick up the basics from the book by Seroul and +Levy~\bibref[SeLe:book], +and after that there is the book by +the original author of \TeX~\bibref[Kn:book] and my own \TeX\ +reference guide~\bibref[E:book]. + + \Section How to Use \Lollipop + +The following files comprise the Lollipop format: +\Ver> + lollipop-define.tex lollipop-document.tex + lollipop-float.tex lollipop-fontdefs.tex + lollipop-fonts.tex lollipop-heading.tex + lollipop-lists.tex lollipop-output.tex + lollipop-plain.tex lollipop-text.tex + lollipop-tools.tex lollipop.tex<Rev + + +Lollipop comes in the following five formats: +\Itemize +\item \n{lollipop} uses Pdf\TeX{} engine and produces pdf output. +\item \n{dvilollipop} uses Pdf\TeX{} engine and produces dvi output. +\item \n{lualollipop} uses Lua\TeX{} engine and produces pdf output. +\item \n{dvilualollipop} uses Lua\TeX{} engine and produces dvi output. +\item \n{xelollipop} uses Xe\TeX{} engine and produces pdf output. +\> + + +To process a file, say \file{test.tex}, with +Lollipop you then type: + +\Ver> +> lollipop test.tex <Rev + +or + +\Ver> +> dvilollipop test.tex <Rev + +or + +\Ver> +> lualollipop test.tex <Rev + +or + +\Ver> +> dvilualollipop test.tex <Rev + +or + +\Ver> +> xelollipop test.tex <Rev + +depending on which of the five formats you want to use. + + +\Section[sec:style-dump] Processing a Lollipop file + +Files that you make to be processed with Lollipop contain of course +the input text, but they also have to contain the design macros that +determine the layout. There are two possibilities for these design +macros: + +\Itemize +\item You can simply put them in the same file, either in the +beginning or wherever they are first needed, or +\item You can put the layout definition in a separate file and call this +definition file in your main file. For instance, you can put the layout definition of a +book in a file \file{bookstyle.tex}, and then call this definition file in your +main Lollipop file by putting + +\Ver> +\InputLollipop:bookstyle.tex <Rev + +somewhere in your main Lollipop file. + + + +If you have used \TeX\ before, you will notice that the page numbers +get reported slightly differently from the usual way. See +section~\ref[sec:page-counter] for the explanation. + +\Section The errors of \Lollipop / known bugs + +Since \Lollipop\ is an order of magnitude more powerful +(and hence complicated) than formats such as \LaTeX, its error +messages can also be an order of magnitude more cryptic (see +section~\ref[sec:error-msg] for the possible origin of some of the +more obscure error messages). + +Fortunately, \Lollipop\ is also quite a +bit better than existing formats at catching potential errors. Typos +in a style definition will usually lead to warning messages, and also +during run time \Lollipop\ is able to track down ommisions. + +In addition, you can switch on various trace modes to get more +detailed information about \Lollipop's thought processes. See +chapter~\ref[chap:tracing]. + +These are the known bugs in \Lollipop\ at the moment. + +\Enumerate\item Local references have been insufficiently tested, +and the code definitely is buggy. +\item The `firstpage' test in the page grids does not work. +\item The table of contents example is slightly wrong. +\item Titles get written to the aux file with double spaces. +This shouldn't cause any problem, but it has to be fixed. +\item Rules in page grids get white space around them. +\item External items shouldn't declare \cs{FooTitle} or +\cs{FooCounter}. +\item \cs{ToExternalFile} doesn't work. +\> + +There are also other known bugs on the sourceforge tickets of Lollipop: +\n{http://sourceforge.net/p/lollipop-project/tickets/?source=navbar}. + + +If you find any other bugs, or if you have any fixes/workarounds + for any existing bugs, then please open a ticket on the tickets. + +\Section About this manual + +This manual consists of a main file \file{lollipop-manual.tex}, and the +following input files: +\Ver> +titlepag.tex prelim.tex struct.tex head.tex list.tex +out.tex extern.tex opt.tex comm.tex trace.tex appendix.tex<Rev +and the style definition file \file{mandefs.tex}. + +In addition, you need \file{comment.tex} which is used to format this +manual, and \file{btxmac.tex} for the Bib\TeX\ interface, but these +are not really a part of \Lollipop. + +If you format this manual (which you'll have to do three times +to get the page numbering and the table of contents straight) you'll +notice something strange. The file \file{example.tex} is read in +many, many times. This is because this manual formats its examples +along the way, first writing them out, and then reading them in to +show both their code and their output. This way it is guaranteed that +the examples in the manual will always work. + +As a result of formatting this manual you will wind up with, apart +from the usual \file{pdf} and \file{log} file, with \file{lollipop-manual} files +with extensions \file{aux}, \file{toc}, and \file{imp}; +\file{oix} and \file{cix} for indexes of options and commands, +and +\file{tct}, file{tix} which are for the examples. For the +bibliography there are the Bib\TeX\ input file \file{lollipop-manual.bib} and +output file \file{lollipop-manual.bbl}. + +This manual needs quite some resources: here's what pdf\TeX\ told me +it needed. +\Ver>Here is how much of TeX's memory you used: + 1193 strings out of 495844 + 16191 string characters out of 6190699 + 74602 words of memory out of 5000000 + 3494 multiletter control sequences out of 15000+600000 + 10941 words of font info for 39 fonts, out of 8000000 for 9000 + 19 hyphenation exceptions out of 8191 + 27i,4n,24p,187b,448s stack positions out of + 5000i,500n,10000p,200000b,80000s<Rev + + +Because of all the examples this manual takes quite some time to +process. A~factor of four over the time for a regular document of +similar length should be expected. Ordinary Lollipop documents will +proceed far faster. + +\Section The most boring section in this manual + +There are a few things about \Lollipop\ that I~want to be clear about. + +\SubSection I am going to hurt you and I am not sorry + +In the secret handbook for the software industry it says that the +final test phase of a product consists of putting it in stores and +having innocent suckers pay good money for it. (You guessed it, this +is the disclaimer section.) So let me just say that +\Lollipop\ is probably good for nothing, at least, I~don't claim it +is. And if you hurt yourself by using it, don't blame me. I~warned +you. + +\SubSection Get a \Lollipop, give one away + +\Lollipop\ 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. + +The easiest way to get the current copy of \Lollipop\ is to use +a more recent \TeX{} distribution (\TeX Live or Mik\TeX). + +\SubSection The status of \Lollipop + +\Lollipop\ is still under development. Although I~will try not to +make any drastic changes in the user interface (this says nothing +about the internals!) I~really cannot guarantee anything. +However, I~do listen to complaints and suggestions. + +If you have suggestions or complaints about the +useability of \Lollipop\ or the implementation, feel free to contact +me at \n{persian-tex@tug.org} on the Internet. + +\SubSection[sec:wish:list] The wish list + +\Lollipop\ is not quite perfect. Here's a list of things that I~am +going to be adding in the near future. If you want to add items to +this list, just open a ticket on the tickets. + +\Enumerate\item Raggedbottom should really, really be added. Soon! + +\item Capitalization and initial capping of titles. If a +title appears in mixed case, it should be possible to have it in all +uppercase in running heads. Some code has been disabled now. + +\item A better multi-column mode. + +\item Interface to Bib\TeX\ seems to largely in place; what happens +if you don't load btxmac? + +\item Inserts, in particular footnotes. At the moment floating +figures are entirely lacking. (As a matter of fact, the plain \TeX\ +macros are availble, but I'm not telling that.) + +\item A `nomarks' option to prevent wasting two token lists. +Maybe other recourse saving optio for the expert designer? + +\item More sophisticated white space right before and after +page breaks. (Use at least so and so much.) + +\item Dynamic topskip. + +\item Support for RTL languages (such as Persian). + + +{\PopIndentLevel\Indent:no The following points are debatable: +maybe I~should just steal a few components from \LaTeX. Maybe this +sort of stuff does not belong in \Lollipop.\par} + +\item A tabular mode. Personally I~always felt \cs{halign} to be more +than sufficient, but some people seem to think otherwise. + +\item Maths constructs. Some things in the \cs{eqalign} vein would be +nice. + +\> + +\SubSection A bit of history + +The \Lollipop\ format was begun in late 1989 to typeset Victor Eijkhout's Ph.D. +thesis, `{\Style:italic Vectorizable and Parallelizable +Preconditioners for the Conjugate Gradient Method}'. At that time +Victor~was using \TeX\ on an Atari 1040ST. +Loading the style definition for the thesis took about two minutes. +\Lollipop\ was heavily augmented in late 1991 to typeset his book +`{\Style:italic \TeX\ by Topic}', for which he~used Sun~3 and Sun~4 +computers. Writing this manual brought \Lollipop\ to its version 0.96; the first public release (version~0.9) was announced on the +internet in October 1992. + +Between 1992 and 2014, Lollipop was unmaintained and Vafa Khalighi took over the +development of Lollipop in April 2014. + +The name `\n{Lollipop}' refers to a quote by Alan +Perlis~\bibref[Pe:epigrams], quoted on page 365 of the \TeX +book~\bibref[Kn:book]. In a way it's rather pretentious. The philosophy +of the \n{Lollipop} format is described~\bibref[EL:Cork,E:Portland]. + +\endinput + +% 2014/04/13 Added some notes about \EveryMath, +% and \EveryDisplay. Also \EveryPar changed to +% \EveryParagraph +% 2014/04/12 Added note about xelollipop format +% 2014/04/11 Updated the manual +% 92/10/22 historical remark about name added +% 92/11/03 section 'Lollipop and plain TeX' added; +% remarks about IniTeX in Textures +% 92/11/26 uses bibrefs diff --git a/Master/texmf-dist/doc/otherformats/lollipop/manual/struct.tex b/Master/texmf-dist/doc/otherformats/lollipop/manual/struct.tex new file mode 100644 index 00000000000..b390cff88d5 --- /dev/null +++ b/Master/texmf-dist/doc/otherformats/lollipop/manual/struct.tex @@ -0,0 +1,264 @@ +% struct.tex copyright 1992 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 <http://www.gnu.org/licenses/>. +% +% +\Chapter The structure of Lollipop + +Lollipop provides tools for realizing the style or layout of a +document. Some of these tools are macros ready to be used by the end +user; they concern for instance selection of fonts. +Others, the `generic constructs', are for the style designer so that +she can use them to program the macros for the user. + +\Section[sec:doc-start-stop] Lollipop Files + +Any Lollipop document has to have a \cs{Start} and \cs{Stop} command. +Before the \cs{Start} there can be style definition commands, but no +text. For a number of reasons it is advisable to put as much of the +style definition before the \cs{Start} command as possible. You can +do that easily by loading the style as an input file, or by first +dumping it as a format (see section~\ref[sec:style-dump]). + +\ImpNote +Before the \cs{Start} command, \cs{everypar} contains an error +message. The start command installs the default value for +\cs{everypar}. +\ImpNoteStop + +Both the start and the stop file load the \file{.aux} auxiliary file. +None of this should concern you, really. Expert users who want to +have certain actions performed at the start of the document may want +to use \refcs{StartCommand} to specify what they wish done. See +section~\ref[sec:adapt-distance] for an example. + +\Section Generic Constructs + +\label[generic:construct]\label[option:macro] +There are five `generic constructs': headings, lists, text blocks, page +grids, and external items. For each construct type there is a defining +command, for instance \cs{DefineHeading} +which is followed a list of `options', terminated by the word `Stop'. + +Options (possibly with values) have to be separated by a +space or a line end; the keyword \opt{Stop} has to be followed by a +space or a line end. +Options may have zero, one or two values; if there are values, then +the first one is separated from the option by a colon, the second is +separated from the first by an equals sign. + +\Ver>\DefineFoo:Bar optiona optionb optionc:value + optiond:valuea=valueb optione + optionf Stop<Rev + + As a result of this definition, a command +\cs{Bar} is created. If the \con{Foo} construct was a \con{List} or +\con{TextBlock}, an additional command \cs{BarStop} is created. + +This command can then be used in the ordinary way, for instance +after \ver>\DefineHeading:Foo> you can type +\Ver>\Foo The title<Rev and after \ver>\DefineList:Foo> you can type +\Ver>\Foo +\item One item +\item And another +\FooStop<Rev + +\ImpNote +Actually, this `Stop' business can be customized for other languages. +The file \file{tools} has the following lines: +\Ver> +\def\stop@command@suffix{Stop} +\def\stop@command{\@command\stop@command@suffix}<Rev +\ImpNoteStop + +\Section Options + +Options are mostly used to specify how a construct will look. Some +options, for instance \opt{title}, indicate material that will appear +on the page. Other options are interpreted as commands, for instance +\opt{IndentAfter:yes} in the definition of a heading indicates that +the first paragrah after such a heading will indent. + +In addition to keywords that only exist as options, commands can +be used as options. Also, single characters are accepted as options. +For instance a definition of a subsection heading can contain: + +\Ver>\DefineHeading:SubSection + [...] + SectionCounter . SubSectionCounter + [...] Stop<Rev +(Here and later the \n{[...]} will denote arbitrary omitted text.) +This definition contains the commands \cs{SectionCounter} and +\cs{SubSectionCounter} and the \n{.} character. + +If a number of options appears together in a number of constructs it +is convenient to have an abbreviation for them. This can be done with the command +\refcs{OptionsMacro} as follows. The options that appear together are +given a common name + \Ver>\OptionsMacro:baz=optiona optionb:value optionc + Stop<Rev +(be sure to leave +no spaces around the equals sign) and this name is then used as + \Ver> macro:baz<Rev +in the option list wherever the options are needed. + +This is for +instance a good way of specifying identical white space around all +sorts of constructs without duplicating the typing each time. +However, it is only for your convenience: it doesn't save any \TeX\ +resources or processing time. + +\Section[sec:error-msg] Popular error messages. Not! + +Lollipop is a macro package on top of an existing program, \TeX. +Therefore it is inevitable that you will get \TeX\ error messages +every once in a while. Some of these may confuse you. + +Here are a few of the errors that I~keep making. + +\SubSection Missing \cs{endcsname} inserted + +If you forget the second parameter in a \cs{Distance} or +\cs{SetCounter} command, writing for instance + \Ver>\Distance:TheWidth<Rev +instead of \Ver>\Distance:TheWidth=15pt<Rev + \TeX\ will scan +forward, and it can easily bump into something that is highly +unexpected given the context. If this is a \cs{def} or \cs{Define...} +command, a `missing \cs{endcsname}' results. If a blank line follows +the incomplete declaration, the following section applies. + +\SubSection Paragraph ended before something was complete + +\TeX\ has found a blank line (or a~\cs{par} command) where this was +not expected. See for instance the previous section. + +\SubSection Missing number + +You have used something that you thought was the name of a control +sequence, but it wasn't. Example: +\Ver>\Distance:parskip=parundent<Rev +Since \cs{parundent} is undefined, \Lollipop\ thought you were +writing something like + \Ver>\Distance:parskip=5pt<Rev + +And yes, the message refers to `number' even though what is missing +is a distance. + +\ImpNote +\iSection Defining Generic Constructs + +The \cs{Define...} commands are not defined explicitly, instead they +are generated by a call such as +\Ver> \@GenericConstruct{Heading}<Rev +Full definition: +\Ver>\def\@GenericConstruct#1{<Rev +to be used as \ver>\@GenericConstruct{Foo}>; +\Ver> \append@to@list{@gencons}{\\#1;}<Rev +book keeping of existing generic constructs; +\Ver> \csarg\newtoks{#1@defaults} + \csn #1@defaults\ecs{}<Rev +default commands to be executed whenever +an instance of this construct +is defined; +\Ver> \csarg\def{add@#1@default}##1% + {\append@to@list{#1@defaults}{##1}}<Rev +the command \cs{add@Foo@default} +to add defaults for this construct; +\Ver> \Install@Noops{#1}<Rev +possibility to generate error msgs for the use of an option that is +not allowed for this type of construct; +\Ver> \csarg\def{Define#1}:##1 {<Rev +instances of this construct will be defined +by a statement like \ver>\DefineFoo:Bar>; +\Ver> \def\@name{##1}\def\@class{#1} + \Tmessage[def]{Defining a #1: ##1}<Rev +\ver>DefineFoo:Bar> leads to \cs{@name} begin \n{Bar}, +\cs{@class} being \n{Foo}; +\Ver> \the\generic@defaults + \csarg\the{#1@defaults}<Rev +unpack token lists of generic and specific default actions; +\Ver> \Get@Items}<Rev +start recursive processing of list of options. This ends the +definition of \cs{DefineFoo}; the definition of +\cs{@GenericConstruct} ends with +\Ver> \csarg\def{@#1Option}##1% + {\csarg\def{#1@##1}####1####2}<Rev +which defines the \cs{@FooOption} macro; see~\ref[imp:option]. +\Ver> }<Rev + +\iSection Items Processing + +Processing the list of items is recursive; at the end some concluding +actions have to be taken, mostly the actual definition of the +construct. + +First we have to filter out empty arguments, which can be caused by +the use of option macros (\ref[option:macro], \ref[imp:option:macro]). + +\Ver>\def\Get@Items#1 {\if\EmptyList{#1}\let\get@next@item\Get@Items + \else\def\get@next@item{\@Get@Items#1 }\fi + \get@next@item}<Rev + +Next, check if the argument is \opt{Stop} (defined by +\ver>\NewDummy{Stop}>, \ref[imp:new:dummy]), in which case you +have reached the end of a generic definition, and can start performing +the final rites. Otherwise, dissect this option item +and go on with the rest +of the options. +\Ver> +\def\@Get@Items#1 {\let\get@next@item=\Get@Items + \csarg\ifx{#1}\Stop + \the\generic@stop@defaults + \let\get@next@item=\relax + \else \Item@or@Macro#1::. \fi \get@next@item}<Rev + +The \n{::.} concluding \cs{Item@or@Macro} accomodates one, +possibly empty, argument. + +\iSection Options\label[imp:option]\label[imp:option:macro] + +Options can either be specific, defined as +\Ver>\@FooOption{Bar}{ [...] }<Rev +in which case the option \opt{Bar} can only be used inside +a call to \cs{DefineFoo}, +or they can be generic, defined as +\Ver>\@GenericOption{Bar}{ [...] }<Rev +For both definitions, the definition text can use up to two parameters. +Parameters are given to the options as +\Ver> optiona:par1 optionb:par1=par2<Rev + +Specific options are defined by the line +\Ver> + \csarg\def{@#1Option}##1% + {\csarg\def{#1@##1}####1####2}<Rev +in \cs{@DefineGenericConstruct}; a call +\Ver>\@FooOption{Bar}{ ... }<Rev +expands to +\Ver>\def\Foo@Bar#1#2{ ... }<Rev +Generic options are defined by the +following command: +\Ver>\def\@GenericOption#1{ + \append@to@list{@GenericOptions}{\\#1;} + \csarg\def{Option@#1}##1##2}<Rev +A call +\Ver>\@GenericOption{Bar}{ ... }<Rev +expands to +\Ver>\def\Option@Bar#1#2{ ... }<Rev + +\ImpNoteStop + +\endinput diff --git a/Master/texmf-dist/doc/otherformats/lollipop/manual/titlepag.tex b/Master/texmf-dist/doc/otherformats/lollipop/manual/titlepag.tex new file mode 100644 index 00000000000..a3415bfc2b9 --- /dev/null +++ b/Master/texmf-dist/doc/otherformats/lollipop/manual/titlepag.tex @@ -0,0 +1,84 @@ +% titlepag.tex copyright 1992 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 <http://www.gnu.org/licenses/>. +% +% +\EmptyPage +\begingroup\AlwaysIndent:no +\PointSize:25 \Style:bold Lollipop Unwrapped + +{\tt http://lollipop-project.sourceforge.net} + +\white:30pt + +\PointSize:20 \SetFont Victor Eijkhout {\rm(Original author)} + +\white:10pt + +Vafa Khalighi {\rm(Current developer)} + +\white:50pt + +\PointSize:15 \Style:roman +A manual for the Lollipop \TeX\ format,\par +last updated 19 April 2014\par +Pages: \LastInPageCounter+\LastRegPageCounter +% so far we could have done this with labels, however +\AddToCounter:LastRegPage=LastInPageValue +=\LastRegPageCounter. + +\EjectPage +\endgroup + +\Chapter Contents + +\Section Regular sections + +\LoadExternalFile:contents + +%\Section Implementer's notes + +%\LoadExternalFile:impnotes + +\Section All of the options + +(You know, this section and the next look much better if you sort the +\file{manual.oix} and \file{manual.cix} files before you format the +document the last time. Do put lines + \Ver>\Writeopindex:no +\Writecsindex:no<Rev somewhere in +the top of the \file{manual.tex} file in order to prevent +overwriting of these files +after you've sorted them.) + +\Indent:no \rightskip=0pt plus 5cm +\LoadExternalFile:optindex + +\Section All of the commands + +\Indent:no +\LoadExternalFile:csindex + +\Section Bibliography + +\bibliographystyle{plain} +\bibliography{lollipop-manual} + +\endinput + +% 2014/04/11 Updated the manual +% 92/11/19 Page total included +% 92/11/26 Bibliography diff --git a/Master/texmf-dist/doc/otherformats/lollipop/manual/trace.tex b/Master/texmf-dist/doc/otherformats/lollipop/manual/trace.tex new file mode 100644 index 00000000000..b66cf31e070 --- /dev/null +++ b/Master/texmf-dist/doc/otherformats/lollipop/manual/trace.tex @@ -0,0 +1,61 @@ +% trace.tex copyright 1992 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 <http://www.gnu.org/licenses/>. +% +% +\Chapter[chap:tracing] Tracing + +\Section Do you really want to see this? + +You can get glimpses of Lollipop's internal workings by enabling some +of the internal traces. The extreme positions +\Ver> \Trace:yes<Rev +and +\Ver> \Trace:no<Rev +cause all trace information and no trace at all respectively to be +generated. You may find this trace interesting, or it may dumbfound you. +Of course, if your name is Victor you find it pretty useful. + +The following traces are available: +\Ver> \NewTrace:def % definition of user constructs + \NewTrace:ref % cross references + \NewTrace:ext % external files + \NewTrace:doc % document structure + \NewTrace:font % font loading + \NewTrace:out % output routine + \NewTrace:indent % indentation control + \NewTrace:gen % general tools<Rev + +\ImpNote +Trace messages are generated by calls to +\Ver> \Tmessage[type]{text}<Rev +Setting +\Ver> \Trace:no<Rev +defines \cs{Tmessage} to discard its arguments. This is the most +efficient way of generating no trace information. + +Tracing is controlled by a global parameter \cs{trace@all}. +A value of~$-1$ +disables all tracing; $+1$~corresponds to all tracing on; $0$~gives +selective tracing. In the third case a call +\Ver> \Trace:xyz<Rev +set \ver>\trace:xyz> positive so that only +\ver>\Tmessage[xyz]{...}> calls will +produce output. Enabling a selective trace sets \cs{trace@all} to zero, in +case it was~$-1$. +\ImpNoteStop + +\endinput diff --git a/Master/texmf-dist/doc/otherformats/lollipop/tex-inde.xen b/Master/texmf-dist/doc/otherformats/lollipop/tex-inde.xen new file mode 100644 index 00000000000..60b25a42b57 --- /dev/null +++ b/Master/texmf-dist/doc/otherformats/lollipop/tex-inde.xen @@ -0,0 +1,259 @@ +TeX-index entries + +%% the Lollipop format + +The Lollipop format is designed to make implementation of +new style definitions easy, even for people who can barely +program TeX macros. It is not compatible with either plain +TeX or LaTeX, although a lot of plain TeX constructs are +available. There is a manual with many elaborate examples; +see below. + + + +Name: lollipop-define.tex +Description: cross referencing macros for + the lollipop package +Keywords: lollipop, macro package, style definitions +Author: Victor Eijkhout and Vafa Khalighi +Supported: yes +Latest version: v1.03, 19 April 2014 +Archives: https://github.com/vafa/lollipop +Note: part of the lollipop package, see lollipop.tex. + +Name: lollipop-document.tex +Description: document handling macros for the + lollipop package +Keywords: lollipop, macro package, style definitions +Author: Victor Eijkhout and Vafa Khalighi +Supported: yes +Latest version: v1.03, 19 April 2014 +Archives: https://github.com/vafa/lollipop +Note: part of the lollipop package, see lollipop.tex. + +Name: lollipop-float.tex +Description: floating insertion macros + for the lollipop package +Keywords: lollipop, macro package, style definitions +Author: Victor Eijkhout and Vafa Khalighi +Supported: yes +Latest version: v1.03, 19 April 2014 +Archives: https://github.com/vafa/lollipop +Note: part of the lollipop package, see lollipop.tex. + +Name: lollipop-fontdefs.tex +Description: fontdefinitions for the lollipop package +Keywords: lollipop, macro package, style definitions +Author: Victor Eijkhout and Vafa Khalighi +Supported: yes +Latest version: v1.03, 19 April 2014 +Archives: https://github.com/vafa/lollipop +Note: part of the lollipop package, see lollipop.tex. + +Name: lollipop-fonts.tex +Description: font handling macros + for the lollipop package +Keywords: lollipop, macro package, style definitions +Author: Victor Eijkhout and Vafa Khalighi +Supported: yes +Latest version: v1.03, 19 April 2014 +Archives: https://github.com/vafa/lollipop +Note: part of the lollipop package, see lollipop.tex. + +Name: lollipop-heading.tex +Description: heading macros for the lollipop package +Keywords: lollipop, macro package, style definitions +Author: Victor Eijkhout and Vafa Khalighi +Supported: yes +Latest version: v1.03, 19 April 2014 +Archives: https://github.com/vafa/lollipop +Note: part of the lollipop package, see lollipop.tex. + +Name: lollipop-lists.tex +Description: list definition macros + for the lollipop package +Keywords: lollipop, macro package, style definitions +Author: Victor Eijkhout and Vafa Khalighi +Supported: yes +Latest version: v1.03, 19 April 2014 +Archives: https://github.com/vafa/lollipop +Note: part of the lollipop package, see lollipop.tex. + +Name: lollipop.tex +Description: main file for the lollipop package +Keywords: lollipop, macro package, style definitions +Author: Victor Eijkhout and Vafa Khalighi +Supported: yes +Latest version: v1.03, 19 April 2014 +Archives: https://github.com/vafa/lollipop +Note: requires define.tex, document.tex float.tex, + fontdefs.tex, fonts.tex, heading.tex, lists,tex, + lolplain.tex, output.tex, text.tex, tools.tex. + +Name: lollipop-plain.tex +Description: version of plain.tex customized + for the lollipop package +Keywords: lollipop, macro package, style definitions +Author: Victor Eijkhout and Vafa Khalighi +Supported: yes +Latest version: v1.03, 19 April 2014 +Archives: https://github.com/vafa/lollipop +Note: part of the lollipop package, see lollipop.tex. + +Name: lollipop-output.tex +Description: output routine macros + for the lollipop package +Keywords: lollipop, macro package, style definitions +Author: Victor Eijkhout and Vafa Khalighi +Supported: yes +Latest version: v1.03, 19 April 2014 +Archives: https://github.com/vafa/lollipop +Note: part of the lollipop package, see lollipop.tex. + +Name: lollipop-text.tex +Description: text environment definitions + for the lollipop package +Keywords: lollipop, macro package, style definitions +Author: Victor Eijkhout and Vafa Khalighi +Supported: yes +Latest version: v1.03, 19 April 2014 +Archives: https://github.com/vafa/lollipop +Note: part of the lollipop package, see lollipop.tex. + +Name: lollipop-tools.tex +Description: utility macros for the lollipop package +Keywords: lollipop, macro package, style definitions +Author: Victor Eijkhout and Vafa Khalighi +Supported: yes +Latest version: v1.03, 19 April 2014 +Archives: https://github.com/vafa/lollipop +Note: part of the lollipop package, see lollipop.tex. + +%% lollipop manual + +Name: comment.tex +Description: comment environment for plain TeX, + LaTeX, and lollipop TeX. +Keywords: lollipop, macro package, style definitions +Author: Victor Eijkhout and Vafa Khalighi +Supported: yes +Latest version: v1.03, 19 April 2014 +Archives: https://github.com/vafa/lollipop +Note: part of the manual of the lollipop package, + see lollipop.tex. + +Name: extern.tex +Description: description of external file handling + in lollipop TeX. +Keywords: lollipop, macro package, style definitions +Author: Victor Eijkhout and Vafa Khalighi +Supported: yes +Latest version: v1.03, 19 April 2014 +Archives: https://github.com/vafa/lollipop +Note: part of the manual of the lollipop package, + see lollipop.tex. + +Name: head.tex +Description: description of headings in lollipop TeX. +Keywords: lollipop, macro package, style definitions +Author: Victor Eijkhout and Vafa Khalighi +Supported: yes +Latest version: v1.03, 19 April 2014 +Archives: https://github.com/vafa/lollipop +Note: part of the manual of the lollipop package, + see lollipop.tex. + +Name: list.tex +Description: description of lists in lollipop TeX. +Keywords: lollipop, macro package, style definitions +Author: Victor Eijkhout and Vafa Khalighi +Supported: yes +Latest version: v1.03, 19 April 2014 +Archives: https://github.com/vafa/lollipop +Note: part of the manual of the lollipop package, + see lollipop.tex. + +Name: mandefs.tex +Description: style definition for the lollipop TeX manual. +Keywords: lollipop, macro package, style definitions +Author: Victor Eijkhout and Vafa Khalighi +Supported: yes +Latest version: v1.03, 19 April 2014 +Archives: https://github.com/vafa/lollipop +Note: part of the manual of the lollipop package, + see lollipop.tex. + +Name: lollipop-manual.tex +Description: master file for the lollipop TeX manual +Keywords: lollipop, macro package, style definitions +Author: Victor Eijkhout and Vafa Khalighi +Supported: yes +Latest version: v1.03, 19 April 2014 +Archives: https://github.com/vafa/lollipop +Note: requires comment.tex, extern.tex, head.tex, list.tex + mandefs.tex, lollipop-manual.bbl, opt.tex, out.tex, prelim.tex, + struct.tex, titlepag.tex, trace.tex. + +Name: opt.tex +Description: description of construct options + in lollipop TeX +Keywords: lollipop, macro package, style definitions +Author: Victor Eijkhout and Vafa Khalighi +Supported: yes +Latest version: v1.03, 19 April 2014 +Archives: https://github.com/vafa/lollipop +Note: part of the manual of the lollipop package, + see lollipop.tex. + +Name: out.tex +Description: description of output handling + in lollipop TeX. +Keywords: lollipop, macro package, style definitions +Author: Victor Eijkhout and Vafa Khalighi +Supported: yes +Latest version: v1.03, 19 April 2014 +Archives: https://github.com/vafa/lollipop +Note: part of the manual of the lollipop package, + see lollipop.tex. + +Name: prelim.tex +Description: introductory chapter of lollipop manual. +Keywords: lollipop, macro package, style definitions +Author: Victor Eijkhout and Vafa Khalighi +Supported: yes +Latest version: v1.03, 19 April 2014 +Archives: https://github.com/vafa/lollipop +Note: part of the manual of the lollipop package, + see lollipop.tex. + +Name: struct.tex +Description: description of the overall structure of + lollipop TeX files +Keywords: lollipop, macro package, style definitions +Author: Victor Eijkhout and Vafa Khalighi +Supported: yes +Latest version: v1.03, 19 April 2014 +Archives: https://github.com/vafa/lollipop +Note: part of the manual of the lollipop package, + see lollipop.tex. + +Name: titlepag.tex +Description: titlepage of the lollipop manual +Keywords: lollipop, macro package, style definitions +Author: Victor Eijkhout and Vafa Khalighi +Supported: yes +Latest version: v1.03, 19 April 2014 +Archives: https://github.com/vafa/lollipop +Note: part of the manual of the lollipop package, + see lollipop.tex. + +Name: trace.tex +Description: description of trace modes in lollipop TeX +Keywords: lollipop, macro package, style definitions +Author: Victor Eijkhout and Vafa Khalighi +Supported: yes +Latest version: v1.03, 19 April 2014 +Archives: https://github.com/vafa/lollipop +Note: part of the manual of the lollipop package, + see lollipop.tex. + |