diff options
Diffstat (limited to 'macros/lollipop/doc/manual/prelim.tex')
-rw-r--r-- | macros/lollipop/doc/manual/prelim.tex | 327 |
1 files changed, 0 insertions, 327 deletions
diff --git a/macros/lollipop/doc/manual/prelim.tex b/macros/lollipop/doc/manual/prelim.tex deleted file mode 100644 index d0af6d3e02..0000000000 --- a/macros/lollipop/doc/manual/prelim.tex +++ /dev/null @@ -1,327 +0,0 @@ -% prelim.tex copyright 1992 Victor Eijkhout -% copyright 2014--2016 Vafa Khalighi -% -% -% This program is free software: you can redistribute it and/or modify -% it under the terms of the GNU General Public License as published by -% the Free Software Foundation, either version 3 of the License, or -% (at your option) any later version. -% -% This program is distributed in the hope that it will be useful, -% but WITHOUT ANY WARRANTY; without even the implied warranty of -% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -% GNU General Public License for more details. -% -% You should have received a copy of the GNU General Public License -% along with this program. If not, see <http://www.gnu.org/licenses/>. -% -% -\Chapter[chap: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 - - -To process a file, say \file{test.tex}, with -Lollipop you then type: - -\Ver> -> lollipop test.tex <Rev - -to get the dvi output. - - -\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. -\> - - -If you find any other issues, or if you have any fixes/workarounds -for any existing issues, then please post them on GitHub. - -\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 \TeX\ told me -it needed. -\Ver>Here is how much of TeX's memory you used: - 1194 strings out of 496579 - 16173 string characters out of 6202690 - 72655 words of memory out of 5000000 - 3270 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 - 24i,4n,24p,187b,562s 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 |