Source Code 1994 March/Source_Code_CD-ROM_Walnut_Creek_March_1994.iso/compsrcs/misc/volume37/lout/part27

Text File | 1993-06-19 | 82.7 KB | 2,086 lines

Newsgroups: comp.sources.misc
From: [e-mail] (Jeff Kingston)
Subject: v37i125:  lout - Lout document formatting system, v2, Part27/30
Message-ID: <[e-mail]>
X-Md4-Signature: 858bc2b505e948c5f76112d2a6373592
Sender: [e-mail] (Kent Landfield)
Organization: Sterling Software
Date: Wed, 2 Jun 1993 03:06:02 GMT
Approved: [e-mail]

Submitted-by: [e-mail] (Jeff Kingston)
Posting-number: Volume 37, Issue 125
Archive-name: lout/part27
Environment: UNIX

#! /bin/sh
# This is a shell archive.  Remove anything before this line, then feed it
# into a shell via "sh file" or similar.  To overwrite existing files,
# type "sh file -c".
# Contents:  lout/doc/tr.begin/s01 lout/doc/tr.begin/s07
#   lout/doc/tr.begin/s10 lout/doc/tr.eq/s4 lout/doc/tr.fig/s2
#   lout/doc/tr.fig/s6 lout/doc/tr.impl/s2.5 lout/doc/tr.impl/s4.0
#   lout/doc/tr.impl/s5.3 lout/doc/tr.impl/s5.4 lout/doc/tr.impl/s5.5
#   lout/doc/tr.impl/s6.2 lout/doc/tr.over/s4 lout/doc/tr.over/s5
#   lout/doc/tr.tab/s6 lout/include/book lout/include/report
# Wrapped by kent@sparky on Sun May 30 19:44:02 1993
PATH=/bin:/usr/bin:/usr/ucb:/usr/local/bin:/usr/lbin ; export PATH
echo If this archive is complete, you will see the following message:
echo '          "shar: End of archive 27 (of 30)."'
if test -f 'lout/doc/tr.begin/s01' -a "${1}" != "-c" ; then
  echo shar: Will not clobber existing file \"'lout/doc/tr.begin/s01'\"
else
  echo shar: Extracting \"'lout/doc/tr.begin/s01'\" \(4181 characters\)
  sed "s/^X//" >'lout/doc/tr.begin/s01' <<'END_OF_FILE'
X@Section
X   @Tag { intro }
X   @Title { Introduction }
X@Begin
X@PP
XThe Lout document formatting system has been designed with the
Xneeds of the ordinary user very much in mind.  Although the features of Lout
Xare virtually endless, and include mathematical equations, diagrams made
Xfrom lines and shapes, bibliographic databases, and so on, the system is
Xvery simple to use.
X@PP
XDocument formatting with Lout begins with the creation of a file like
Xthe following:
X@ID @Code {
X"@Doc @Text @Begin"
X"@Heading { Introduction }"
X"@PP"
X"For Virginia Woolf, @I Middlemarch"
X"was `the magnificent book which"
X"for all its imperfections is one"
X"of the few English novels written"
X"for grown-up people.'"
X"@End @Text"
X}
XOrdinary words are mixed with symbols of special meaning, such as
X{@Code "@Doc"}, {@Code "@Text"}, {@Code "@Heading"}, and
X{@Code "@I"}.  Most symbols begin with {@Code "@"}, but some, like
X{@Code "{"} and {@Code "}"}, do not.  It doesn't matter where the lines
Xend:  the end of a line is treated the same as a single space.
X@PP
XThis file is then processed by the Basser Lout interpreter, for example
Xby typing
X@ID @Code "lout -idoc simple > simple.ps"
Xon the Unix
X@FootNote { Unix is a trademark of "AT&T" Bell Laboratories. &0io }
Xoperating system, assuming that the file's name is
X{@Code "simple"}.  The @Code "-idoc" part instructs Lout to include a
Xspecial @I {setup file} called {@Code doc}, in which the symbols are
Xdefined.  The output is the PostScript
X@FootNote { PostScript is a trademark of Adobe Systems, Inc. &0io }
Xfile {@Code "simple.ps"}, which is suitable for printing on most laser
Xprinters and many other devices.  When printed, it will appear like this:
X@ID {
X@Heading { Introduction }
X@PP
XFor Virginia Woolf, @I Middlemarch was `the magnificent book which
Xfor all its imperfections is one of the few English novels written
Xfor grown-up people.'
X}
XThe meaning of each symbol is now clear.  @Code "@Doc @Text @Begin" and
X@Code "@End @Text" have no visible effect, but they always bracket the
Xdocument as a whole.  @Code "@Heading" makes the following thing into
Xa heading; there is also @Code "@MajorHeading" for producing a large
Xheading, and @Code "@MinorHeading" for a subheading.  The @Code "@PP"
Xsymbol starts a paragraph whose first line is indented; also available
Xare {@Code "@LP"} which omits the indent, {@Code "@DP"} which leaves the
Xamount of vertical space used for displays, and {@Code "@NP"}, which
Xstarts a new page or column (rarely used, since Lout does this
Xautomatically when the old one fills).  Finally, @Code "@I" changes the
Xfont of the following thing to {@I Italic}.
X@PP
XBraces are used to group parts of the document together so that nearby
Xsymbols will affect the whole part.  For example,
X@ID @Code "@I { Scenes of Clerical Life }"
Xproduces {@I { Scenes of Clerical Life }}.  The braces around
X@Code "Introduction" in the example above are not strictly necessary,
Xsince a single word does not need to be grouped; but a longer heading
Xwould require them.  Braces also help when a symbol must be immediately
Xadjacent to another symbol or to a word:
X@ID @Code "QuikWipe{@TradeMark}"
Xhas result QuikWipe{@TradeMark}.  Without them Lout would confuse the
Xtwo.  In a similar way, @Code "{@I Middlemarch}," produces
X{@I Middlemarch}, with the comma not set in Italic.
X@PP
XCharacters like "{", which normally are symbols, will be
Xtreated as ordinary words when enclosed in double quotes.  For example,
X@Code "\"{\"" produces "{".  The characters
X@ID @Code "/    |    &    {    }    #    @    ^"
Xshould always be so enclosed, since otherwise they will have special
Xeffects.
X@PP
XThe symbols described above form part of the {@I DocumentLayout @I package},
Xa collection of symbols designed to make day-to-day document formatting
Xeasy.  This package also provides symbols for producing displays and
Xlists, numbered sections, subsections, and appendices, footnotes,
Xfigures, tables, references, and cross references.  These are described
Xin later sections of this report.  This same package may also be used to
Xproduce technical reports and books, as described in Sections
X@NumberOf reportlayout and {@NumberOf booklayout}.
X@End @Section
END_OF_FILE
  if test 4181 -ne `wc -c <'lout/doc/tr.begin/s01'`; then
    echo shar: \"'lout/doc/tr.begin/s01'\" unpacked with wrong size!
  fi
  # end of 'lout/doc/tr.begin/s01'
fi
if test -f 'lout/doc/tr.begin/s07' -a "${1}" != "-c" ; then
  echo shar: Will not clobber existing file \"'lout/doc/tr.begin/s07'\"
else
  echo shar: Extracting \"'lout/doc/tr.begin/s07'\" \(1777 characters\)
  sed "s/^X//" >'lout/doc/tr.begin/s07' <<'END_OF_FILE'
X@Section
X   @Tag { sections }
X   @Title { Sections }
X@Begin
X@PP
XThe DocumentLayout package provides sections, like this:
X@ID @Code {
X"some introductory text."
X"@BeginSections"
X"@Section"
X"    @Title { Introduction }"
X"@Begin"
X"@PP"
X"..."
X"..."
X"@End @Section"
X"@Section"
X"    @Title { Displays and lists }"
X"@Begin"
X"@PP"
X"..."
X"..."
X"@End @Section"
X"@EndSections"
X}
X@Code "@BeginSections" and @Code "@EndSections" symbols must
Xbracket the sections, and paragraph symbols are needed at the
Xbeginning of each section but not before or after the whole group.  The
X@Code "@Title" option of @Code "@Section" is made into a numbered heading,
Xlike those in the present document, preceded by a conditional new page
Xsymbol (Section {@NumberOf cnp}).  The body of each section is enclosed in
X@Code "@Begin" and {@Code "@End @Section"}, although @Code "{" and @Code "}"
Xare sufficient if preferred.  The former are more long-winded but less
Xprone to error.
X@PP
XWithin sections one may choose to have a sequence of subsections.  These
Xare introduced by @Code "@BeginSubSections" and concluded by
X{@Code "@EndSubSections"}:
X@ID @Code {
X"in the following subsections."
X"@BeginSubSections"
X"@SubSection"
X"    @Title { ... }"
X"@Begin"
X"@PP"
X"..."
X"@End @SubSection"
X"@SubSection"
X"    @Title { ... }"
X"@Begin"
X"@PP"
X"..."
X"@End @SubSection"
X"@EndSubSections"
X}
XThe first subsection of the first section will be numbered 1.1, and so
Xon.  There are no sub-subsections.  DocumentLayout also provides appendices
Xin an exactly analogous way, using the symbols {@Code "@BeginAppendices"},
X{@Code "@Appendix"}, and {@Code "@EndAppendices"}, and subappendices
Xwithin any appendix using the symbols {@Code "@BeginSubAppendices"},
X{@Code "@SubAppendix"}, and {@Code "@EndSubAppendices"}.
X@End @Section
END_OF_FILE
  if test 1777 -ne `wc -c <'lout/doc/tr.begin/s07'`; then
    echo shar: \"'lout/doc/tr.begin/s07'\" unpacked with wrong size!
  fi
  # end of 'lout/doc/tr.begin/s07'
fi
if test -f 'lout/doc/tr.begin/s10' -a "${1}" != "-c" ; then
  echo shar: Will not clobber existing file \"'lout/doc/tr.begin/s10'\"
else
  echo shar: Extracting \"'lout/doc/tr.begin/s10'\" \(4136 characters\)
  sed "s/^X//" >'lout/doc/tr.begin/s10' <<'END_OF_FILE'
X@Section
X   @Tag { refs }
X   @Title { References }
X@Begin
X@PP
XThe method of handling references described in this section is rather
Xelaborate, but it has many advantages.  The first step is to create a
Xseparate @I {database file} containing @Code "@Reference" symbols.  Each
Xis enclosed in braces, and has options chosen from
X{@Code "@Tag"}, {@Code "@Type"}, {@Code "@Author"}, {@Code "@Title"},
X{@Code "@Institution"}, {@Code "@Number"}, {@Code "@Publisher"},
X{@Code "@Year"}, {@Code "@Proceedings"}, {@Code "@Journal"},
X{@Code "@Volume"}, {@Code "@Pages"}, and {@Code "@Comment"}:
X@IndentedList
X@ListItem @Code {
X"{ @Reference"
X"     @Tag { strunk79 }"
X"     @Type { Book }"
X"     @Author { Strunk and White }"
X"     @Title { The Elements of Style }"
X"     @Publisher { MacMillan }"
X"     @Year { 1979 }"
X"}"
X}
X@ListItem @Code {
X"{ @Reference"
X"     @Tag { kingston92 }"
X"     @Type { TechReport }"
X"     @Author { Kingston, Jeffrey H. }"
X"     @Title { Document Formatting"
X"with Lout }"
X"     @Number { 449 }"
X"     @Institution { Basser Department"
X"of Computer Science F09, University"
X"of Sydney 2006, Australia }"
X"     @Year { 1992 }"
X"}"
X}
X@EndList
XThe {@Code "@Tag"} and {@Code "@Type"} options are in fact compulsory; the
Xfirst serves to name the reference, the second gives its type, which may
Xbe {@Code "TechReport"}, {@Code "ConferencePaper"}, {@Code "JournalArticle"},
X{@Code "PhD"}, or {@Code "Book"}, although a Lout expert will be able to add
Xother types.  The type determines which other options must be present, as
Xshown above, and how they will be printed.
X@PP
XSuppose this file is given the name @Code "myrefs.ld" (Basser Lout
Xdatabase file names must end in {@Code ".ld"}).  To tell Lout to refer
Xto this file as needed,
X@ID @Code {
X"@Database @Reference { myrefs }"
X}
Xis placed at the beginning of the document, before {@Code "@Doc"},
X{@Code "@Report"}, or {@Code "@Book"}.
X@PP
XNow, with everything prepared,
X@ID @Code {
X"{@Ref kingston92}"
X}
Xfor example at any point in the document will cause the reference whose
Xtag is @Code "kingston92" to be added to the nearest following
Xreference list, indicated by the symbol {@Code "@ReferenceSection"}, unless
Xit is already there.  Typically one would write
X@ID @Code {
X"... which ends our study."
X"@DP"
X"@ReferenceSection"
X}
Xat the very end of the document (although one could equally well have several
X@Code "@ReferenceSection" symbols scattered through the document if desired);
Xtechnical reports and books add @Code "@ReferenceSection" automatically
Xwhen needed.  The references will appear in alphabetical order by tag, and
Xthe @Code "@Ref" symbol will be replaced by the number of the reference,
Xin this case {@Ref "kingston92"}.  @Code "@ReferenceSection" has a
X@Code "@Title" option like {@Code "@Section"}, and it also has {@Code style},
X{@Code indent}, {@Code gap} and {@Code start} options for contolling the
Xappearance of the reference list, like {@Code "@RawIndentList"}.
X@PP
XIf a separate database file is not convenient for some reason, perhaps
Xbecause it is desirable for the entire document to reside in one file,
Xthe @Code "@Reference" symbols may be incorporated into the document
Xitself, anywhere after {@Code "@Text @Begin"}.  Nothing will appear
Xwhere they are typed in, but Lout will
Xnotice them and treat them exactly as if they had come from a database
Xfile.  In this case no @Code "@Database" symbol is needed.
X@PP
XA way to print references at any point in the document is provided by
X{@Code "@RefPrint"}:
X@ID @Code "{@RefPrint kingston92}"
Xmight have result
X@ID {@RefPrint kingston92}
Xdepending on what references exist.
X@PP
XTo get section numbers, footnote numbers, cross references, and references
Xright, Basser Lout has to process the document more than once (three times
Xfor numbered references), and create special files whose names end
Xin `.li' and `.ld'.  It will print warning messages on runs when this
Xprocess is incomplete, and substitute question marks for the unknown
Xvalues.  There should be only one document containing these features per
XUnix directory, otherwise Basser Lout will confuse their special files.
X@End @Section
END_OF_FILE
  if test 4136 -ne `wc -c <'lout/doc/tr.begin/s10'`; then
    echo shar: \"'lout/doc/tr.begin/s10'\" unpacked with wrong size!
  fi
  # end of 'lout/doc/tr.begin/s10'
fi
if test -f 'lout/doc/tr.eq/s4' -a "${1}" != "-c" ; then
  echo shar: Will not clobber existing file \"'lout/doc/tr.eq/s4'\"
else
  echo shar: Extracting \"'lout/doc/tr.eq/s4'\" \(4293 characters\)
  sed "s/^X//" >'lout/doc/tr.eq/s4' <<'END_OF_FILE'
X@Section
X   @Title { Features from Standard Lout }
X@Begin
X@PP
XIn this section we summarize those features of standard Lout of most
Xrelevance to equation formatting.  All are freely available within
Xequations.  Full details may be found in the Lout reference manual
X[{@Ref kingston92}].
X@PP
XStandard Lout uses the symbols {@Code "#"}, {@Code "{"}, {@Code "}"},
X{@Code "&"}, {@Code "|"}, and @Code "/" for special purposes (the braces
Xare used for grouping, for example).  To get these characters into
Xequations without using their full names, enclose them in double quotes:
X{@Code "\"{\""}, {@Code "\"}\""}, etc.  Any sequence of characters
Xincluding spaces but not newlines may be so enclosed, and the effect is
Xto turn off any special meaning that the symbols within it might have.
X@PP
XEq sets letters in Slope (Lout's name for Italic), digits in Base (i.e.
XRoman), and other symbols in various fonts, mostly the Symbol font.  To
Xchange fonts, use the @Code "@Font" symbol:
X@ID {
X@Code "Slope @Font \"2\""
X|7ct
X@Eq { Slope @Font "2" }
X}
XIn Eq it will often be necessary to enclose the right parameter in
Xdouble quotes, because the symbol 2 includes a built-in change back to
XBase font.  Changing fonts makes white space between objects in the
Xright parameter appear in the result.  The @Code "@Font" operator also
Xdoes size changes:
X@IL
X@LI {
X@Code "sum"
X|7ct
X@Eq { sum }
X}
X@LI {
X@Code "\"+2p\" @Font sum"
X|7ct
X@Eq { "+2p" @Font sum }
X}
X@LI {
X@Code "2.0f @Font sum"
X|7ct
X@Eq { 2.0f @Font sum }
X}
X@EL
XHere @Code "\"+2p\" @Font" sets its right parameter in a font two points
Xlarger than it would otherwise have been; @Code "2.0f @Font" sets its
Xright parameter in a font twice the original size.  Sizes should always
Xbe specified relative to the enclosing size as we have done here, since
Xthen they don't need to be changed if a decision is made to set the entire
Xdocument in a different size.  It is necessary to enclose @Code "+2p" in
Xdouble quotes within Eq, because otherwise the @Code "+" will be taken as
Xthe Eq symbol for {@Eq { + }}.  The right parameter may be any object.
X@PP
XWhenever similar equations or parts of equations are being typed
Xrepeatedly, @I definitions should be used to save time.  Suppose for
Xexample that @OneCol @Eq { p sub i ` log sub 2 ` p sub i } occurs
Xfrequently.  Then
X@ID @Code "def epi { p sub i ` log sub 2 ` p sub i }"
Xmakes the symbol @Code "epi" stand for the object between the braces:
X@ID {
X@Code "big sum from i=1 to n ` epi"
X|7ct
X@Eq { big sum from i=1 to n ` epi }
X}
XSymbols may be given parameters:
X@ID @Code {
X"def ep"
X"   right x"
X"{ p sub x ` log sub 2 ` p sub x"
X"}"
X}
XThe parameter @Code x will be replaced by the object just to the right
Xof {@Code "ep"}:
X@ID {
X@Code {
X"big sum from j=1 to k ` ep i +"
X"big sum from j=k+1 to n ep j"
X}
X||7ct
X@Eq {
Xbig sum from j=1 to k ` ep i +
Xbig sum from j=k+1 to n ep j
X}
X}
XThe precedence of such symbols will be 100 by default.
X@PP
XTo make the symbols of Eq available within such definitions, each must be
Xpreceded by {@Code "import @Eq"}.  The best place to keep them is in the
Xsetup file, which might then look like this:
X@ID @Code {
X"@SysInclude { ft  }"
X"@SysInclude { dl  }"
X"@SysInclude { eq  }"
X""
X"import @Eq"
X"def epi { p sub i ` log sub 2 ` p sub i }"
X""
X"import @Eq"
X"def ep right x { p sub x ` log sub 2 ` p sub x }"
X""
X"@Use { @DocumentLayout }"
X}
XUse of @Code "epi" and @Code "ep" outside equations will cause an error.
X@PP
XEquations can appear within a paragraph of text, or they can be
Xdisplayed.  Eq's job is to produce a Lout object containing the
Xequation; it neither knows nor cares where this equation goes.  To get
Xan equation within a paragraph, simply place @Code "@Eq { ... }" at the
Xdesired point.  To prevent it spreading over two lines, use
X{@Code "@OneCol @Eq { ... }"}.  To display an equation, use a display
Xsymbol from some other Lout package.  For example, the DocumentLayout package
X[{@Ref kingston92begin}] has @Code "@IndentedDisplay" or @Code "@ID" for an
Xindented display, and @Code "@CentredDisplay" or @Code "@CD" for a centred
Xdisplay, so
X@ID @Code "@CD @Eq { int supp pi on 0 sin ` x = 0 }"
Xproduces
X@CD @Eq { int supp pi on 0 sin ` x = 0 }
XDocumentLayout also provides display symbols that make it easy to
Xproduce aligned and numbered equations.
X@End @Section
END_OF_FILE
  if test 4293 -ne `wc -c <'lout/doc/tr.eq/s4'`; then
    echo shar: \"'lout/doc/tr.eq/s4'\" unpacked with wrong size!
  fi
  # end of 'lout/doc/tr.eq/s4'
fi
if test -f 'lout/doc/tr.fig/s2' -a "${1}" != "-c" ; then
  echo shar: Will not clobber existing file \"'lout/doc/tr.fig/s2'\"
else
  echo shar: Extracting \"'lout/doc/tr.fig/s2'\" \(4595 characters\)
  sed "s/^X//" >'lout/doc/tr.fig/s2' <<'END_OF_FILE'
X@Section
X   @Title { Basic Shapes }
X@Begin
X@PP
XFig has a repertoire of basic shapes, whose size varies depending on
Xwhat they enclose:
X@IL
X@LI {
X@Code "@Ellipse { hello, world }"
X||7ct
X@Fig {
X@Ellipse { hello, world }
X}
X}
X@LI {
X@Code "@Box { 2c @High }"
X||7ct
X@Fig {
X@Box { 2c @High }
X}
X}
X@EL
XThere are six such shapes: {@Code "@Box"}, {@Code "@Square"},
X{@Code "@Diamond"}, {@Code "@Polygon"}, {@Code "@Ellipse"}, and
X{@Code "@Circle"}; the result in each case is the right parameter,
Xenclosed in a small margin, with the shape around it.
X@PP
XThere are options for changing the appearance of these shapes.  The
Xboundary line's style may be {@Code solid}, {@Code dashed},
X{@Code cdashed}, {@Code dotted}, or {@Code noline} (that is, no line is
Xdrawn), and the length of the dashes may be changed:
X@ID {
X@Code {
X"@Circle"
X"   linestyle { cdashed }"
X"   dashlength { 0.2 cm }"
X"@Eq { X sub 2 }"
X}
X||7ct
X@Fig {
X@Circle
X   linestyle { cdashed }
X   dashlength { 0.2 cm }
X@Eq { X sub 2 }
X}
X}
XIf the line style is not mentioned, it becomes @Code solid by default.  The
X@Code dashed option makes all dashes the same length; @Code cdashed
Xhalves the length of the first and last dash on each segment, which
Xlooks better in some cases.  The distance between dashes or dots will be
Xat most {@Code dashlength}, reduced to make the dashes or dots fit evenly.
X@PP
XShapes may be painted {@Code black}, {@Code dark}, {@Code grey} or
X{@Code gray}, {@Code light}, {@Code white}, or {@Code nopaint} (the default):
X@ID {
X@Code {
X"@Box"
X"   margin { 0c }"
X"   paint { grey }"
X"@Diamond"
X"   linestyle { noline }"
X"   paint { white }"
X"{ hello, world }"
X}
X||7ct
X@Fig {
X@Box
X   margin { 0c }
X   paint { grey }
X@Diamond
X   linestyle { noline }
X   paint { white }
X{ hello, world }
X}
X}
XHere, the right parameter of @Code "@Box" is a diamond containing
X{@Code "hello, world"}.  There is no limit to the amount of this sort of
Xnesting; the right parameter may be any Lout object.
X@PP
XWhen painting it is important to know what order things are done in,
Xbecause anything put down earlier will disappear under the paint.  This
Xis why @Code nopaint and @Code white are different.  Painting is done
Xfirst, then boundaries, and finally the right parameter.
X@PP
XThe @Code "@Polygon" shape has a @Code sides option for specifying the number
Xof sides, and an @Code angle option for specifying what angle anticlockwise
Xfrom vertically beneath the centre the first corner will appear at:
X@IL
X@LI {
X@Code {
X"@Polygon"
X"   sides { 5 }"
X"{}"
X}
X||7ct
X@Fig {
X//0.5c
X@Polygon
X   sides { 5 }
X{}
X}
X}
X
X@LI {
X@Code {
X"@Polygon"
X"   sides { 5 }"
X"   angle { 0 dg }"
X"{}"
X}
X||7ct
X@Fig {
X//0.5c
X@Polygon
X   sides { 5 }
X   angle { 0 dg }
X{}
X}
X}
X@EL
XThe defaults are 3 sides and the angle that gives the polygon
Xa horizontal base (i.e. 180 degrees divided by the number of sides).
XThus the two cases with symmetry about a vertical axis are obtained
Xby the default angle and @Code "0 dg" respectively, which is convenient.
X@PP
XAlthough lines and arrows do not enclose things in the way that boxes
Xand circles do, Fig treats them as it does the other shapes.  The line
Xor arrow is drawn along the mark of the right parameter, either
Xhorizontally or vertically:
X@IL
X@LI {
X@Code "@HLine { //0.2c hello, world }"
X||7ct
X@Fig {
X@HLine { //0.2c hello, world }
X}
X}
X@LI {
X@Code "@VArrow { 2c @High X ^|0.2c }"
X||7ct
X@Fig {
X@VArrow { 2c @High X ^|0.2c }
X}
X}
X@EL
XThe usual line style options are available; the default margin is
X{@Code "0c"}.  Arrows can be
X{@Code forward} (the default), {@Code back}, {@Code both}, or
X{@Code noarrow} (which just draws a line); the style of the arrowhead
Xcan be {@Code open} (the default), {@Code halfopen}, or {@Code closed}:
X@ID {
X@Code {
X"@HArrow"
X"   arrow { both }"
X"   headstyle { closed }"
X"{ 3c @Wide }"
X}
X||7ct
X@Fig {
X@HArrow
X   arrow { both }
X   headstyle { closed }
X{ 3c @Wide }
X}
X}
XIt is also possible to change the shape of the arrowhead, using the
X@Code headwidth and @Code headlength options:
X@ID @Fig {
X{
X@Figure
X   shape {
X      {0 ysize} ** 0.4 @Label SB
X      {0 ysize} ** 0.6 @Label ST
X      {xsize 0} ** 0.7 @Label HB
X      SB
X      SB ++ HB
X      HB
X      {xsize 0} ++ {0 ysize} ** 0.5
X      HB ++ {0 ysize}
X      HB ++ ST
X      ST
X      SB
X   }
X   paint { grey }
X{ 10c @Wide 3c @High }
X//0.3c
X7c @Wide {} & @HArrow headstyle { closed } arrow {both }
X3c @Wide { //0.2c |0.5rt @I -2p @Font headlength }
X} |0.3c @VArrow headstyle { closed } arrow {both }
X1.5c @High { /0.5rt |0.2c @I -2p @Font headwidth |0io }
X}
XTheir default values are @Code "0.05 cm" and @Code "0.15 cm"
Xrespectively.
X@End @Section
END_OF_FILE
  if test 4595 -ne `wc -c <'lout/doc/tr.fig/s2'`; then
    echo shar: \"'lout/doc/tr.fig/s2'\" unpacked with wrong size!
  fi
  # end of 'lout/doc/tr.fig/s2'
fi
if test -f 'lout/doc/tr.fig/s6' -a "${1}" != "-c" ; then
  echo shar: Will not clobber existing file \"'lout/doc/tr.fig/s6'\"
else
  echo shar: Extracting \"'lout/doc/tr.fig/s6'\" \(5044 characters\)
  sed "s/^X//" >'lout/doc/tr.fig/s6' <<'END_OF_FILE'
X@Section
X   @Title { Putting it all together }
X@Begin
X@PP
XIn this section we consider the problem of linking individual shapes
Xtogether to form complex diagrams like this one:
X@ID @Fig {
X@Frame { 10c @Wide 6c @High }
X// X**0.1 ++ Y**0.4 @BaseOf A:: @Square { @I A }
X// X**0.4 ++ Y**0.7 @BaseOf B:: @Square { @I B }
X// X**0.6 ++ Y**0.1 @BaseOf C:: @Square { @I C }
X// X**0.8 ++ Y**0.6 @BaseOf D:: @Square { @I D }
X// A @JoinFigures arrow { forward } B
X// A @JoinFigures arrow { forward } C
X// B @JoinFigures arrow { forward } C
X// B @JoinFigures arrow { forward } D
X// C @JoinFigures arrow { forward } D
X}
XWe already have several aids to hand:  the standard Lout symbols,
Xespecially horizontal and vertical concatenation, rotation and scaling;
Xthe ability to nest text, equations, and other figures (in fact
Xarbitrary Lout objects) within our shapes; and the standard Lout
Xdefinition mechanism.
X@PP
XThe default values of the various options -- @Code "solid" for
X{@Code linestyle}, @Code noarrow for {@Code arrow}, and so on -- may be
Xchanged by giving options to the @Code "@Fig" symbol:
X@ID {
X@Code {
X"@Fig"
X"   linestyle { noline }"
X"   paint { black }"
X"{"
X"   @Circle |1c @Square"
X"   /1c @Diamond | @Polygon"
X"}"
X}
X||7ct
X@Fig
X   linestyle { noline }
X   paint { black }
X{
X    @Circle |1c @Square
X   /1c
X   @Diamond | @Polygon
X}
X}
XA complete list of options is given in the next section.
X@PP
XFig provides an additional aid: the symbols {@Code "@BaseOf"} and
X{@Code "@MarkOf"}.  The right parameter of {@Code "@BaseOf"} is an
Xarbitrary object, and its left parameter is a point.  As far as Lout
Xis concerned, the result of @Code "@BaseOf" is always an empty object;
Xbut the right parameter will appear on the page with the bottom left-hand
Xcorner of its base at the point denoted by the left parameter.  We stress
Xthat Lout has no idea that this is happening, and so cannot prevent the
Xshifted object from writing over other objects or even going off the edge
Xof the page.  Of course, this lack of discipline is just what is needed
Xvery often in diagrams.
X@PP
XThe @Code "@MarkOf" symbol works in a similar way, except that the point
Xwhere the object's marks cross (rather than its bottom left-hand corner)
Xwill appear on the page at the point denoted by the left parameter.
X@PP
XWe can set up a coordinate system for a figure:
X@ID @Code {
X"@Figure shape { xsize 0 @Label X  0 ysize @Label Y }"
X"{ 10c @Wide 6c @High }"
X}
XIn fact, Fig contains this shape under the name {@Code "@Frame"}, so we
Xneed only write
X@ID @Code "@Frame { 10c @Wide 6c @High }"
XOf course, the right parameter may contain an arbitrary Lout object.
X@PP
XOnce the frame is set up, we can specify points by their @Code X and
X@Code Y coordinates, as fractions of the total width and height:
X@ID @Code "X ** 0.5  ++  Y ** 0.8"
XTo place the squares in the diagram above, we can use
X@ID @Code {
X"//  X**0.1 ++ Y**0.4  @BaseOf  A:: @Square { @I A }"
X"//  X**0.4 ++ Y**0.7  @BaseOf  B:: @Square { @I B }"
X"//  X**0.6 ++ Y**0.1  @BaseOf  C:: @Square { @I C }"
X"//  X**0.8 ++ Y**0.6  @BaseOf  D:: @Square { @I D }"
X}
XThe symbols' precedences are chosen so that this very common situation
Xrequires no braces.  The result of this is
X@ID @Fig {
X@Box margin { 0c } @Frame { 10c @Wide 6c @High }
X// X**0.1 ++ Y**0.4 @BaseOf A:: @Square { @I A }
X// X**0.4 ++ Y**0.7 @BaseOf B:: @Square { @I B }
X// X**0.6 ++ Y**0.1 @BaseOf C:: @Square { @I C }
X// X**0.8 ++ Y**0.6 @BaseOf D:: @Square { @I D }
X}
X{@PageMark sumpoints} where we have drawn a box with margin 0 around the
Xframe to make its extent clear.
X@PP
XNow the arrow from @I A to @I B starts on the boundary of @I A at the
Xangle of a line drawn between the centres of @I A and {@I B}:
X@ID @Code "A@CTR ++ { {A@CTR @Angle B@CTR} A@CIRCUM }"
Xand a similar expression will yield the endpoint of the arrow.  Such
Xexpressions should be placed into definitions if they are to be used often:
X@ID @Code {
X"import @Fig"
X"def @JoinFigures"
X"   left A"
X"   named linestyle { solid }"
X"   named dashlength { 0.15 cm }"
X"   named arrow { noarrow }"
X"   named linewidth { 0.5 pt }"
X"   right B"
X"{  @Arrow"
X"      from { A\"@CTR\" ++ {{A\"@CTR\" @Angle B\"@CTR\"} A\"@CIRCUM\"} }"
X"      to   { B\"@CTR\" ++ {{B\"@CTR\" @Angle A\"@CTR\"} B\"@CIRCUM\"} }"
X"      linestyle { linestyle }"
X"      dashlength { dashlength }"
X"      arrow { arrow }"
X"      linewidth { linewidth }"
X"   {}"
X"}"
X}
XDefinitions preceded by @Code "import @Fig" may use the symbols of
XFig within them; they may themselves be used only within
X@Code "@Fig { ... }".  Now, to the figure above we can add
X@ID @Code {
X"// A @JoinFigures arrow { forward } B"
X"// A @JoinFigures arrow { forward } C"
X"// B @JoinFigures arrow { forward } C"
X"// B @JoinFigures arrow { forward } D"
X"// C @JoinFigures arrow { forward } D"
X}
Xto obtain the diagram as it appears at the beginning of this
Xsection.  Definitions are the best means of managing complexity in
Xdiagrams, and serious users maintain a file of definitions which is
Xincluded automatically by an @Code "@Include" command.
X@End @Section
END_OF_FILE
  if test 5044 -ne `wc -c <'lout/doc/tr.fig/s6'`; then
    echo shar: \"'lout/doc/tr.fig/s6'\" unpacked with wrong size!
  fi
  # end of 'lout/doc/tr.fig/s6'
fi
if test -f 'lout/doc/tr.impl/s2.5' -a "${1}" != "-c" ; then
  echo shar: Will not clobber existing file \"'lout/doc/tr.impl/s2.5'\"
else
  echo shar: Extracting \"'lout/doc/tr.impl/s2.5'\" \(4418 characters\)
  sed "s/^X//" >'lout/doc/tr.impl/s2.5' <<'END_OF_FILE'
X@SubSection
X    @Tag { style }
X    @Title { Context-sensitive attributes of objects }
X@Begin
X@PP
XAlthough we are free to place any object in any context, the context
Xmust influence the appearance of the object, since otherwise
X@ID @Code "A short paragraph of text."
Xcould not appear in a variety of fonts, column widths, etc.  This
Xinfluence cannot take the purely static form that block-structured
Xlanguages use to associate values with identifiers, for then an operator
Xcould not influence the appearance of its parameters; and a state
Xvariable solution is not compatible with the overall functional design.
X@PP
XThe information needed from the context seems quite limited, comprising
Xthe font family, face, and size to use, the style of paragraph breaking
Xrequired, how much space to substitute between the words of paragraphs,
Xand how much horizontal and vertical space is available to receive the
Xobject.  These four items constitute the so-called `style information'
Xof Lout.  As graphics rendering hardware improves, the style information
Xwill probably grow to include colour and texture information.
X@PP
XThe way to deal with fonts at least is very clear:
X@ID @Code "{ Times Slope 12p } @Font { Hello, world }"
Xshould have result
X@ID { { Times Slope 12p } @Font { Hello, world } }
XLout also provides @Code "@Break" and @Code "@Space" symbols for
Xcontrolling the paragraph breaking and space styles mentioned
Xabove.  These work in the same way, returning their right
Xparameters in the style of their left.  The implementation is very
Xsimple:  one merely broadcasts the style information down into the parse
Xtree of the right parameter.  A font, for example, is converted to an
X8-bit internal name and stored in each leaf, while a breaking style is
Xstored in the root node of each paragraph.
X@PP
XThe same language design can be used for available width and height,
Xonly here the implementation is much more demanding:
X@ID @Code {
X"2i @Wide {"
X"(1)  |0.1i  An example"
X"containing a small"
X"paragraph of filled text."
X"}"
X}
Xis guaranteed to be two inches wide:
X@ID {
X2i @Wide {
X(1)  |0.1i  An example
Xcontaining a small
Xparagraph of filled text.
X}
X}
XOne must calculate that 1.9 inches minus the width of @Code "(1)" is
Xavailable
Xto the paragraph, and break it accordingly; Basser Lout does this in two
Xstages.  In the first, upward-moving stage, widths are calculated using the
Xformulae of Section {@NumberOf objects}, which assume that available
Xspace is infinite.  If the upward movement reaches a @Eq { WIDE }
Xnode, corresponding to a @Code "@Wide" operator, and
Xthe calculated width exceeds that allowed, a second, downward-moving stage
Xis initiated which attempts to reduce the width by finding and breaking
Xparagraphs.  This second stage is quite routine except at @Code "|" nodes,
Xwhose children are the columns of a table.  It is necessary to apportion
Xthe available width (minus inter-column gaps) among the columns.  Basser
XLout leaves narrow columns unbroken and breaks the remaining columns to
Xequal width, using up all of the available space.
X@PP
XThe size of an object is not clearly determined when the upward-moving
Xsize is less than the downward-moving available space, and the object
Xcontains constructs that depend on available space (e.g. right
Xjustification).  For example, in
X@ID @Code "2i @Wide { Heading // a |1rt b }"
Xit seems natural to assign a width of two inches to the subobject
X@Code "a |1rt b" because of the right justification, but it would be
Xequally plausible if the width of @Code Heading was assigned to the
Xsubobject instead.  The author is conscious of having failed to resolve
Xthis matter properly; an extra operator for controlling available space
Xis probably necessary.
X@PP
XThe actual paragraph breaking is just a simple transformation on the
Xparse tree; the real issue is how to describe the various styles:  ragged
Xright, adjusted, outdented, and so on.  Their diversity suggests that
Xthey should somehow be defined using more basic features; but then there
Xare algorithms for high-quality paragraph breaking, which presumably
Xmust be built-in.  This dilemma was not clearly grasped by the author in
X1985, and he included a built-in paragraph breaker, with the @Code
X"@Break" operator selecting from a fixed set of styles.  A much better
Xsolution based on galleys will be given in Section {@NumberOf horizontal},
Xbut, regrettably, it is not implemented.
X@End @SubSection
END_OF_FILE
  if test 4418 -ne `wc -c <'lout/doc/tr.impl/s2.5'`; then
    echo shar: \"'lout/doc/tr.impl/s2.5'\" unpacked with wrong size!
  fi
  # end of 'lout/doc/tr.impl/s2.5'
fi
if test -f 'lout/doc/tr.impl/s4.0' -a "${1}" != "-c" ; then
  echo shar: Will not clobber existing file \"'lout/doc/tr.impl/s4.0'\"
else
  echo shar: Extracting \"'lout/doc/tr.impl/s4.0'\" \(4101 characters\)
  sed "s/^X//" >'lout/doc/tr.impl/s4.0' <<'END_OF_FILE'
X@Section
X    @Tag { functional }
X    @Title { Implementation of the functional subset }
X@Begin
X@PP
XThe objects and definitions of Lout are very similar to those found in
Xother functional languages, and they form a natural subset of the
Xlanguage.  So we pause here and present an overview of the Basser Lout
Xobject evaluation algorithm.
X@PP
XThe problem is to take an unsized object (pure parse tree), its
Xenvironment (Section {@NumberOf defs.impl}), and its style
X(Section {@NumberOf style}), and to produce a PostScript file for
Xrendering the object on an output device.  This file is essentially a
Xsequence of instructions to print a given string of characters in a
Xgiven font at a given point.
X@PP
XBefore the algorithm begins, the parse tree must be obtained, either by
Xparsing input or by copying from the symbol table.  Afterwards the data
Xstructure must be disposed.  The algorithm proper consists of five
Xpasses, each a recursive traversal of the structure from the root down
Xto the leaves and back.
X@DP
X@I {1.  Evaluation of unsized objects.}  On the way down, calculate
Xenvironments and replace non-recursive, non-receptive symbols by their
Xbodies (Section {@NumberOf defs.impl}); broadcast fonts to the leaves,
Xand paragraph breaking and spacing styles to the paragraph nodes.  On the
Xway back up, delete @Eq { FONT }, @Eq { BREAK }, and @Eq { SPACE } nodes,
Xand insert @Eq { SPLIT }, @Eq { COL }, and @Eq { ROW } nodes
X(Section {@NumberOf objects}).
X@DP
X@I {2.  Width calculations and breaking.}  Calculate the width of every
Xsubobject from the bottom up.  As described in Section {@NumberOf objects},
X@Eq { WIDE } nodes may trigger object breaking sub-traversals during this pass.
X@DP
X@I {3.  Height calculations.}  Calculate the height of every subobject,
Xfrom the bottom up.
X@DP
X@I {4.  Horizontal coordinates.}  Calculate the horizontal coordinate of
Xeach subobject from the top down, and store each leaf's coordinate in
Xthe leaf.
X@DP
X@I {5.  Vertical coordinates and PostScript generation.}  Calculate the
Xvertical coordinate of every subobject from the top down, and at each
Xleaf, retrieve the character string, font, and horizontal coordinate,
Xand print the PostScript instruction for rendering that leaf.
X@DP
XFigure {@NumberOf components} gives the amount of code required for each
X
X@Figure
X    @Tag { components }
X    @Caption { Major components of the Basser Lout interpreter, showing
Xthe approximate number of lines of C code.  }
X@Begin
X@Tab
X   vmargin { 0.5vx }
X   @Fmta { @Col @RR A ! @Col B ! @Col @RR C }
X   @Fmtb { @Col @RR A ! @Col B ! @Col     C }
X{
X   @Rowa A { 1. } B { Initialization } C { 200 }
X   @Rowa A { 2. } B { Memory allocation, ordered dag operations } C { 400 }
X   @Rowa A { 3. } B { Lexical analysis, macros, file handling } C { 1,350 }
X   @Rowa A { 4. } B { Parsing of objects and definitions } C { 1,150 }
X   @Rowa A { 5. } B { Symbol table and call graph } C { 600 }
X   @Rowa A { 6. } B { Evaluation of pure parse trees } C { 1,650 }
X   @Rowa A { 7. } B { Reading, storing, and scaling of fonts } C { 600 }
X   @Rowa A { 8. } B { Cross references and databases } C { 1,000 }
X   @Rowa A { 9. } B { Width and height calculations, and breaking } C { 700 }
X   @Rowa A { 10. } B { @I Constrained and @I AdjustSize } C { 700 }
X   @Rowa A { 11. } B { Transfer of sized objects into galley tree } C { 450 }
X   @Rowa A { 12. } B { Galley flushing algorithm } C { 1,500 }
X   @Rowa A { 13. } B { Coordinate calculations and PostScript output } C { 700 }
X   @Rowa A { 14. } B { Debugging and error handling } C { 1,200 }
X   @Rowb vmargin { 0.1c } C { @Line }
X   @Rowa C { 12,200 }
X}
X@End @Figure
X
Xpass.  Symmetry between horizontal and vertical is exploited throughout
XBasser Lout, and passes 2 and 3, as well as 4 and 5, are executed on
Xshared code.
X@PP
XThe author can see no simple way to reduce the number of passes.  The
Xintroduction of horizontal galleys (Section {@NumberOf horizontal})
Xwould remove the need for the object breaking transformations within this
Xalgorithm that are the principal obstacles in the way of the merging of
Xpasses 2 and 3.
X@End @Section
END_OF_FILE
  if test 4101 -ne `wc -c <'lout/doc/tr.impl/s4.0'`; then
    echo shar: \"'lout/doc/tr.impl/s4.0'\" unpacked with wrong size!
  fi
  # end of 'lout/doc/tr.impl/s4.0'
fi
if test -f 'lout/doc/tr.impl/s5.3' -a "${1}" != "-c" ; then
  echo shar: Will not clobber existing file \"'lout/doc/tr.impl/s5.3'\"
else
  echo shar: Extracting \"'lout/doc/tr.impl/s5.3'\" \(4681 characters\)
  sed "s/^X//" >'lout/doc/tr.impl/s5.3' <<'END_OF_FILE'
X@SubSection
X    @Tag { constraints }
X    @Title { Size constraints and size adjustments }
X@Begin
X@PP
XThe galley flushing algorithm needs to know the available width and
Xheight at each receptive symbol.  These symbols may lie within
Xarbitrarily complex objects, and they may compete with each other for
Xavailable space (as body text and footnote targets do), so this
Xinformation must be extracted from the tree structure when required.
X@PP
XFor example, consider the object
X@ID @Code "5i  @Wide  {  a  /  b  }"
Xand suppose that the width of @Code { a } is @Eq { 1i, 2i } (@Eq {1i} to
Xthe left of the mark, @Eq { 2i } to the right).  What then is the
Xavailable width at {@Code { b }}?  If we let the width of @Code b be
X@Eq {l,r}, we must have
X@ID @Eq { (1i up l) + (2i up r) <= 5i }
Xwith the @Eq {non up } (i.e. max) operations arising from mark
Xalignment.  Eliminating them gives
X@ID @Eq {
Xmatrix {
X    { 1i + 2i ^<= 5i }
Xmabove    { l  + 2i ^<= 5i }
Xmabove    { 1i + r  ^<= 5i }
Xmabove    { l  + r  ^<= 5i }
X}
X}
Xand since we assume that @Code a fits into the available space, the
Xfirst inequality may be dropped, leaving
X@ID @Eq {
Xmatrix {
X    { l     ^<= 3i }
Xmabove    { l + r ^<= 5i }
Xmabove    { r     ^<= 4i }
X}
X}
XObject @Code b may have width @Eq {l, r} for any @Eq { l } and
X@Eq { r } satisfying these inequalities, and no others.
X@PP
XHere is another example:
X@ID @Code "5i  @High  {  a  /2ix  b  }"
XAssuming that @Code a has height @Eq {1i,1i}, the height @Eq {l, r} of
X@Code b must satisfy
X@ID @Eq { 1i + ((1i + l) up 2i) + r <= 5i }
XThis time the @Eq { non up } operation arises from the mark-to-mark gap
Xmode, which will widen the @Eq { 2i } gap if necessary to prevent
X@Code a and @Code b from overlapping.  This inequality can be rewritten as
X@ID @Eq {
Xmatrix {
X    { l     ^<= infinity }
Xmabove    { l + r ^<= 3i       }
Xmabove    { r     ^<= 2i       }
X}
X}
XIn general, Lout is designed so that the available width or height at
Xany point can be expressed by three inequalities of the form
X@ID @Eq {
Xmatrix {
X    { l     ^<= x }
Xmabove    { l + r ^<= y }
Xmabove    { r     ^<= z }
X}
X}
Xwhere @Eq {x }, @Eq {y} and @Eq {z} may be @Eq { infinity }.  We
Xabbreviate these three inequalities to @Eq { l, r <= x, y, z }, and we
Xcall @Eq {x, y, z} a {@I{size constraint}}.
X@PP
XThe two examples above showed how to propagate the size constraint
X@Eq { infinity, 5i, infinity } for
X@Code "a / b" down one level to the child {@Code b}.  Basser Lout
Xcontains a complete set of general rules for all node types, too
Xcomplicated to give here.  Instead, we give just one example of how
Xthese rules are derived, using the object
X@ID {
X@Eq {x sub 1}  @Code "/"  @Eq {x sub 2}  @Code "/"  @Eq {ldots}  @Code
X"/"  @Eq {x sub n}
X}
Xwhere @Eq { x sub j } has width @Eq { l sub j , r sub j } for all @Eq {j}.
X@PP
XSuppose the whole object has width constraint @OneCol @Eq {X,Y,Z}, and we
Xrequire the width constraint of {@Eq { x sub i }}.  Let
X@Eq { L = max sub j ` l sub j } and @Eq { R = max sub j ` r sub j },
Xso that @OneCol @Eq {L, R} is the width of the whole object.  We assume
X@Eq {L, R <= X,Y,Z}.  Then @Eq { x sub i } can be enlarged to any size
X@Eq { l sub i ` , r sub i } satisfying
X@ID @Eq { ( l sub i up L), ( r sub i up R) <= X, Y, Z }
Xwhich expands to eight inequalities:
X@ID @Eq {
Xmatrix {
X         { l sub i           ^<= X }
Xmabove   { L                 ^<= X }
Xmabove   { l sub i + r sub i ^<= Y }
Xmabove   { l sub i + R       ^<= Y }
Xmabove   { L + r sub i       ^<= Y }
Xmabove   { L + R             ^<= Y }
Xmabove   { r sub i           ^<= Z }
Xmabove   { R                 ^<= Z }
X}
X}
XThree are already known, and slightly rearranging the others gives
X@ID @Eq {
Xmatrix {
X         { l sub i           ^<= X     }
Xmabove   { l sub i           ^<= Y - R }
Xmabove   { l sub i + r sub i ^<= Y     }
Xmabove   { r sub i           ^<= Z     }
Xmabove   { r sub i           ^<= Y - L }
X}
X}
XTherefore the width constraint of @Eq { x sub i } is
X@ID @Eq { min(X, Y-R), Y, min(Z, Y-L) }
XThe size constraint of any node can be found by climbing the tree to a
X@I WIDE or @I HIGH node where the constraint is trivial, then propagating
Xit back down to the node, and this is the function of procedure
X{@I Constrained} in Basser Lout.
X@PP
XAfter some components have been promoted into a target, the sizes stored
Xin its parent and higher ancestors must be adjusted to reflect the
Xincreased size.  This is done by yet another set of recursive rules,
Xupward-moving this time, which cease as soon as some ancestor's size
Xdoes not change.  These rules are embodied in procedure @I AdjustSize
Xof Basser Lout.  The adjustment must be done before relinquishing
Xcontrol to any other galley, but not after every component.
X@End @SubSection
END_OF_FILE
  if test 4681 -ne `wc -c <'lout/doc/tr.impl/s5.3'`; then
    echo shar: \"'lout/doc/tr.impl/s5.3'\" unpacked with wrong size!
  fi
  # end of 'lout/doc/tr.impl/s5.3'
fi
if test -f 'lout/doc/tr.impl/s5.4' -a "${1}" != "-c" ; then
  echo shar: Will not clobber existing file \"'lout/doc/tr.impl/s5.4'\"
else
  echo shar: Extracting \"'lout/doc/tr.impl/s5.4'\" \(4726 characters\)
  sed "s/^X//" >'lout/doc/tr.impl/s5.4' <<'END_OF_FILE'
X@SubSection
X    @Tag { lookahead }
X    @Title { The limited lookahead problem }
X@Begin
X@PP
XBasser Lout assumes that there will be enough internal memory to hold
Xthe symbol table plus a few pages, but not an entire document.  This
Xsection describes the consequent problems and how they were solved.
XOther interpreters, notably interactive editors running on virtual
Xmemory systems, would not necessarily need this assumption.
X@PP
XAlthough Basser Lout can read and format any legal input, its memory
Xconsumption will be optimized when the bulk of the document resides in
Xgalleys whose targets can be identified at the moment they are
Xencountered.  Let us take the typical example of a root galley which
Xis a list of pages, a @Code "@BodyText" galley targeted into the
Xpages, @Code "@Chapter" galleys targeted into {@Code "@BodyText"},
Xand @Code "@Section" galleys targeted into the @Code "@Chapter"
Xgalleys:
X@ID @Code {
X"@PageList"
X"//"
X"@BodyText"
X"//"
X"@Chapter {"
X"    @Section { ... }"
X"    @Section { ... }"
X"    ..."
X"    @Section { ... }"
X"}"
X"@Chapter {"
X"    ..."
X"}"
X}
XBasser Lout is able to read and process such galleys one paragraph at
Xa time (strictly, from one @Code "//" at the outer level of a galley
Xto the next), as we now describe.
X@PP
XWhen the parser encounters the beginning of a galley, like @Code "@Chapter"
Xor {@Code "@Section"}, it initiates a new galley process.  The special
Xreceptive symbol @Code "@Input" is substituted for the as yet
Xunread right parameter of the galley.  As each paragraph of the right
Xparameter is read, it is deleted from the parse tree and injected into
Xthe galley's {@Code "@Input"}.  The galley is then resumed.  The parser
Xthus acts as an extra
Xconcurrent process; it has low priority, so that input is read only when
Xthere is nothing else to do.  Since galleys may be nested, a stack of
X@Code "@Input" symbols is needed, each with its own environment and
Xstyle.  If a galley is encountered for which a target is not immediately
Xidentifiable (a footnote, for example), it is read in its entirety and
Xhung in pure parse tree form from an @I UNATTACHED index in the usual way,
Xwith an environment but without a style.  It will be flushed later
Xwhen its component is promoted.
X@PP
XIn addition to producing a steady flow of components from input, we must
Xalso ensure that receptive symbols do not unduly block their
Xpromotion.  The @Code "@FootSect" symbol at the foot of each page is a
Xtypical example:  until it is deleted the page cannot be printed.
X@PP
XReceptive symbols are expanded only on demand, so @Code "@FootSect" can
Xbe deleted as soon as we can prove that it is not wanted.  The symbol
Xtable can tell us that only @Code "@FootNote" galleys (with
X@Code "@FootPlace&&following" targets) want it, so it might be possible
Xto deduce that @Code "@FootSect" may be deleted as soon as body text
Xenters the following page.
X@PP
XThe author was unable to make this work, so Basser Lout requires the
Xuser to identify those galleys which will carry the bulk of the document
X({@Code "@Chapter"}, {@Code "@Section"}, {@Code "@BodyText"}) as
X{@I {forcing galleys}}, by writing @Code "force into" instead of
X@Code "into" in their definitions.  As described in the previous
Xsection, when a forcing galley attaches to a target, all receptive
Xsymbols preceding the target in its galley are deleted, removing all
Ximpediments to flushing.  For example, when a forcing body text galley
Xenters a new page, the @Code "@FootSect" symbol on the preceding page
Xwill be deleted.  It seems likely that a system which could afford to
Xwait until all input was read before deleting any receptive symbols
Xwould not need forcing galleys.
X@PP
XGalleys whose targets are a long way from their invocation points can be
Xa problem.  If the direction is {@Code "following"}, such galleys are
Xheld in internal memory for a long time, unless they are to be
Xsorted.  If the direction is
X{@Code "preceding"}, then either the entire intervening document must be
Xheld in memory (prevented by the target from flushing), or else some
Xforcing galley prematurely deletes the target, leaving the galley bereft.
X@PP
XThe typical example of the latter case occurs when the galley is an
Xentry in the table of contents, launched backwards from the beginning of
Xa chapter or section.  Its target in the table of contents will have
Xbeen deleted long before, to permit the rest of the document to print,
Xso the galley ultimately emerges as an unattached galley promoted out of
Xthe root galley.  All such galleys are written to an auxiliary file,
Xindexed by the missing target.  On the next run, just before that target
Xis deleted, the auxiliary file is checked and any galleys for it are
Xread in and flushed.
X@End @SubSection
END_OF_FILE
  if test 4726 -ne `wc -c <'lout/doc/tr.impl/s5.4'`; then
    echo shar: \"'lout/doc/tr.impl/s5.4'\" unpacked with wrong size!
  fi
  # end of 'lout/doc/tr.impl/s5.4'
fi
if test -f 'lout/doc/tr.impl/s5.5' -a "${1}" != "-c" ; then
  echo shar: Will not clobber existing file \"'lout/doc/tr.impl/s5.5'\"
else
  echo shar: Extracting \"'lout/doc/tr.impl/s5.5'\" \(4791 characters\)
  sed "s/^X//" >'lout/doc/tr.impl/s5.5' <<'END_OF_FILE'
X@SubSection
X    @Tag { horizontal }
X    @Title { Horizontal galleys }
X@Begin
X@PP
XThere is a strong analogy between breaking a column of text into
Xpage-sized pieces, and breaking a paragraph into line-sized pieces.  In
Xfact, the two differ only in direction:  vertical for body text,
Xhorizontal for paragraphs.  In this section we define {@I{horizontal
Xgalleys}}, and show how they provide an unlimited number of paragraph
Xbreaking styles, as well as solve some other problems.  Regrettably,
Xlack of time has prevented their incorporation into the Basser Lout
Xinterpreter.
X@PP
XImagine a galley whose components are separated by horizontal
Xconcatenation operators instead of vertical ones, perhaps indicated by a
X@Code { horizontally into } clause.  Then all object breaking, including
Xparagraph breaking, could be replaced by galley component promotion like
Xthis:
X@ID @Code {
X"def @Paragraph right x"
X"{"
X"    def @LinePlace { @Galley }"
X""
X"    def @LineList"
X"    {"
X"        @HExpand @LinePlace"
X"        //1vx  @LineList"
X"    }"
X""
X"    def @Par horizontally into { @LinePlace&&preceding }"
X"        right x"
X"    { x }"
X""
X"    @LineList  //  @Par { 0.2i @Wide {}  &0i  x  &1rt }"
X"}"
X}
XThe @Code "@HExpand" operator, which is a primitive of Basser Lout,
Xhorizontally expands the gaps in its right parameter until the result
Xfills the available space, thus implementing line adjustment, except
Xwhen the parameter contains tabulation gaps like {@Code "&1rt"}, which
Xcause the parameter to be already expanded.  The result of
X@ID @Code "@Paragraph { A short paragraph of text. }"
Xwould then be something like
X@ID 1.5i @Wide {
X0.2i @Wide {} & A short paragraph of text.
X}
Xdepending on the available horizontal space.  An unlimited range of
Xparagraph breaking styles could be defined, including ragged right, ragged
Xleft, break-and-center, and so on.
X@PP
XIn Basser Lout, indented paragraphs are produced by preceding them with
Xa horizontal concatenation operator, for example {@Code "|0.5i"}.  This
Xhas the unfortunate effect of making an indented paragraph into a single
Xcomponent of the enclosing galley, so that it will always be kept
Xtogether on one page.  Horizontal galleys solve this problem with a
Xsimple change to {@Code "@LineList"}:
X@ID @Code {
X"def @LineList"
X"{"
X"    |0.5i  @HExpand @LinePlace"
X"    //1vx  @LineList"
X"}"
X}
Xshowing the flexibility that comes from bringing the full power of the
XLout language to bear on paragraph layout.  It is easy to make provision
Xfor a tag on the first line.
X@PP
XAlthough Basser Lout permits receptive symbols within paragraphs, they
Xare of little use, because their available width is calculated after
Xparagraph breaking, and the incoming galley cannot spread over more than
Xone line.  With horizontal galleys, such symbols would have infinite
Xavailable width, and we could easily produce a filled paragraph of
Xfootnotes like this:
X@ID 3.5i @Wide {
X@OneRow { -2p @Font 1 ^/0.3vo } & See Jones and Saunders (1982). &2m
X@OneRow { -2p @Font 2 ^/0.3vo } & Or so Jacobsen (1973) asserts. &2m
X@OneRow { -2p @Font 3 ^/0.3vo } & {@I ibid}, p. 327.
X}
Xbased on an infinite horizontal sequence of @Code "@FootPlace" symbols
Xinside a horizontal galley.
X@PP
XWhen body text is placed on pages, the length of each column varies
Xdepending on the available vertical space.  Horizontal galleys could
Xanalogously produce lines of varying length, and so could fill
Xnon-rectangular shapes.
X@PP
XAn important theoretical benefit of horizontal galleys is that they
Xwould permit horizontal and vertical to be treated in a perfectly
Xsymmetrical way, whereas at present paragraph breaking is horizontal
Xonly, and galley breaking is vertical only.  This must simplify the
Xtreatment of non-European languages which fill in unusual directions,
Xalthough it is not itself sufficient to implement them.
X@PP
XThere are a few minor problems with horizontal galleys.  First, the
Xsyntactic overhead of enclosing each paragraph in @Code "@Paragraph { ... }"
Xor whatever is unacceptable.  Permitting user-defined operators to have lower
Xprecedence than the white space between two words might help here.  Second,
Xthe built-in paragraph breaker includes hyphenation, and it permits line
Xbreaks in the input to determine line breaks in the output, if
Xdesired.  These features must somehow be preserved.  Finally, we have
Xexplained how the Basser Lout interpreter assigns equal width to the
Xwider columns of tables (Section {@NumberOf style}).  The equivalent
Xsituation in vertical galleys occurs when two receptive symbols compete
Xfor vertical space (e.g. @Code "@TextPlace" and {@Code "@FootSect"}),
Xand there it is conventional to grant as much as required to the first
Xarrival.  It is not clear to the author how these different approaches
Xcan be reconciled.
X@End @SubSection
END_OF_FILE
  if test 4791 -ne `wc -c <'lout/doc/tr.impl/s5.5'`; then
    echo shar: \"'lout/doc/tr.impl/s5.5'\" unpacked with wrong size!
  fi
  # end of 'lout/doc/tr.impl/s5.5'
fi
if test -f 'lout/doc/tr.impl/s6.2' -a "${1}" != "-c" ; then
  echo shar: Will not clobber existing file \"'lout/doc/tr.impl/s6.2'\"
else
  echo shar: Extracting \"'lout/doc/tr.impl/s6.2'\" \(4579 characters\)
  sed "s/^X//" >'lout/doc/tr.impl/s6.2' <<'END_OF_FILE'
X@SubSection
X    @Tag { cross.impl }
X    @Title { Implementation of cross references }
X@Begin
X@PP
XBefore an object can be sized and printed, the values of any cross
Xreferences within it must be known.  If they refer to invocations that
Xhave not yet been read, there is a problem.  Scribe [7]
Xsolves it by capitalizing on the fact that documents are formatted
Xrepeatedly during the drafting process.  All tagged invocations are
Xcopied to an auxiliary file during the first run, and indexed for quick
Xretrieval on the second.  A new auxiliary file is written during the second
Xrun, for retrieval on the third, and so on.  Cross references always lag
Xone run behind the rest of the document; a perfect copy may be produced
Xby formatting the same version twice, except in a few pathological cases
Xthat fail to converge.
X@PP
XCross referencing in Lout is implemented on top of a simple database
Xsystem.  Each database is either writable or readable but not both at
Xonce, and holds a set of key-value entries:  the keys are @S ASCII
Xstrings, and the values are Lout objects, possibly with environments,
Xwritten in Lout source.  Operations are provided for writing an entry,
Xconverting from writable to readable, retrieval by key, and sequential
Xretrieval in key order.
X@PP
XThe implementation, which is quite unsophisticated, employs one or more
X@S ASCII {@I{ database files}}, containing the values, and one @S ASCII
X{@I{ index file}} per database, containing the keys.  To write an entry,
Xthe value is first appended to a database file, then a line like
X@ID @Code "@Chapter&&intro  ch1.ld  57"
Xis appended to the index file, giving the file and offset where the value
Xis stored.  To convert from writable to readable, the index file is
Xsorted.  Then retrieval by key requires a binary search of the index
Xfile and one seek into a database file, and sequential retrieval by key
Xis trivial.
X@PP
XThis database system is used in several ways.  For an external database,
Xsay of bibliographic references, the user creates the database file of
Xvalues (without environments), Lout creates the index file whenever it
Xcannot find one, and retrievals by key proceed as usual.  Cross
Xreferences with tags other than @Code preceding and @Code following are
Xtreated as described above, by writing all tagged invocations (with
Xenvironments) to a single database, which is converted to readable at
Xthe end of the run for retrievals on the next run.  Sorted galleys, such
Xas index entries, are written out indexed by target and key and retrieved
Xsequentially on the next run.  Unsorted galleys with preceding targets
Xwhich pop off the top of the root galley without finding a target, such
Xas entries in tables of contents, are treated similarly, except that they
Xare indexed by target and a sequence number that preserves their relative
Xorder during the sort.
X@PP
XWhen Lout processes a multi-file document, one cross reference database
Xfile is written for each input file, but they share a common index
Xfile.  At end of run, the new index file is sorted and merged with the
Xold one in such a way as to preserve entries relating to files not read
Xon the current run.  This provides some support for piecemeal
Xformatting, but eventually the files must all be formatted together.
X@PP
XWhen a @Code preceding or @Code following cross reference is found,
Xit is attached to a galley index of type @Eq { CROSS_PREC } or
X{@Eq { CROSS_FOLL }}, together with an automatically generated tag composed
Xof the current file name and a sequence number.  When a tagged
Xinvocation is found, it is attached to a @Eq { CROSS_TARG } index.  These
Xgalley indexes are carried along through the dynamic tree, and
Xeventually pop off the top of the root galley, at which point it is easy
Xto determine which cross references refer to which invocations, since
Xthe indexes are now in final printed document order.  Each referenced
Xinvocation is then written to the cross reference database, multiply indexed
Xby the generated tags of the associated cross references.  On the next
Xrun, when the same @Code preceding and @Code following cross references
Xare found, chances are good that the same tags will be generated, and
Xthe appropriate values can be retrieved from the database immediately.
X@PP
XThis approach was the genesis of the @Code "@Tagged" operator, whose
Ximplementation is now immediate: for each @Code "@Tagged" operator we
Xproduce one @Eq { CROSS_PREC } or @Eq { CROSS_FOLL } galley index,
Xreplacing the generated tag with the right parameter of the @Code "@Tagged"
Xoperator.  Nothing more is required.
X@End @SubSection
END_OF_FILE
  if test 4579 -ne `wc -c <'lout/doc/tr.impl/s6.2'`; then
    echo shar: \"'lout/doc/tr.impl/s6.2'\" unpacked with wrong size!
  fi
  # end of 'lout/doc/tr.impl/s6.2'
fi
if test -f 'lout/doc/tr.over/s4' -a "${1}" != "-c" ; then
  echo shar: Will not clobber existing file \"'lout/doc/tr.over/s4'\"
else
  echo shar: Extracting \"'lout/doc/tr.over/s4'\" \(5064 characters\)
  sed "s/^X//" >'lout/doc/tr.over/s4' <<'END_OF_FILE'
X@Section
X   @Title { Definitions }
X@Begin
X@PP
XLout permits the user to define operators which take objects as
Xparameters and return objects as results.  This feature, unremarkable
Xin itself, has some surprising applications, most notably to a problem
Xwhich is the litmus test of flexibility in document formatting:  the
Xspecification of page layout.
X@PP
XThe use of operators in document formatting seems to have been pioneered
Xby the eqn equation formatting language of Kernighan and Cherry
X[{@Ref kernighan75}].  In eqn, the mathematical formula
X@ID @Eq { { x sup 2 + 1 } over 4 }
Xfor example is expressed as
X@ID @Code "{ x sup 2 + 1 } over 4"
XThis identical expression is also used in Lout, but in Lout the operators
X({@Code "sup"}, {@Code over} and so on) have visible definitions which
Xare easy to modify and extend.
X@PP
XFor example, here is the definition of the @Code over operator as it
Xappears in the Eq equation formatting package [{@Ref kingston92eq}]:
X@ID @Code {
X"def over"
X"    precedence 54"
X"    associativity left"
X"    left x"
X"    right y"
X"{"
X"    @OneRow @OneCol"
X"    {"
X"        |0.5rt  x"
X"        ^//0.2f  @HLine"
X"        //0.2f  |0.5rt  y"
X"    }"
X"}"
X}
XInvokations of @Code over return the object between the braces, with the
Xformal parameters @Code x and @Code y replaced by actual parameters
Xwhich are objects found to the left and right of the @Code over symbol.
X@PP
XThe body of @Code over makes a good demonstration of the way in which
XLout's operators combine together.  All are Lout primitives except
X{@Code "@HLine"}, which calls upon Lout's graphics primitives to draw a
Xhorizontal line.  The @Code "//" and @Code "^//" operators are variants
Xof vertical concatenation which omit mark alignment; the separation
Xis 0.2 times the current font size.  The two @Code "|0.5rt" operators
Xcenter each parameter in the column.  Finally, the @Code "@OneRow" and
X@Code "^//" operators work together to ensure that only one horizontal
Xmark protrudes, rather than three; the result has the structure
X@ID @ShowMarks @Eq { { x sup 2 + 1 } over 4 }
Xand so will be aligned correctly with adjacent parts of the equation.
X@PP
XAs is usual in functional languages, sequences are obtained by recursive
Xdefinitions.  For example, the `leaders' often seen in tables of
Xcontents can be generated by the definition
X@ID @Code {
X"def @Leaders"
X"{"
X"    ..   @Leaders"
X"}"
X}
XWhite space after @Code "{" and before @Code "}" is not
Xsignificant.  The recursion stops when space runs out, so
X@ID @Code {
X"1.5i @Wide {"
X"Chapter 1  @Leaders  5"
X"}"
X}
Xhas result
X@ID {
X1.5i @Wide {
XChapter 1  @Leaders  5
X}
X}
XThe final invokation of @Code "@Leaders" is deleted along with any
Xpreceding concatenation operator (or white space in this case).
X@PP
XThe specification of page layout is a major problem for many document
Xformatters, because the model of a document as a sequence of pages is
Xbuilt-in, and an armada of tedious commands is required to communicate
Xwith this model:  commands for setting page width and height, margins,
Xcolumns, page header and footer lines, and so on.  Even with all these
Xcommands, the formatter will be unable to do such a simple thing as draw
Xa box around each page, if there is no command for it.
X@PP
XLout has no built-in model and no such commands.  Instead, a page is an
Xobject like any other:
X@ID @Code {
X"def @Page"
X"    right x"
X"{"
X"    8i @Wide 11i @High"
X"    {"
X"        //1i ||1i x ||1i"
X"        //1i"
X"    }"
X"}"
X}
XThe result of @Code "@Page" is an eight by eleven inch object containing
Xthe right parameter within one inch margins.  A document is a vertical
Xconcatenation of numbered pages:
X@ID @Code {
X"def @PageList"
X"    right @PageNum"
X"{"
X"    @Page"
X"    {"
X"        |0.5rt  - @PageNum -"
X"        //0.2i  @TextPlace"
X"        //1rt   @FootSect"
X"    }"
X"    //0i"
X"    @PageList"
X"        @Next @PageNum"
X"}"
X}
XThe @Code "@Next" operator is a Lout primitive that returns its right
Xparameter plus one; all automatic numbering is effected by combining
Xthis operator with recursion.  The result of @Code "@PageList 1" is
Xthe object
X@ID {
X@LittlePage {
X|0.5rt - 1 -
X//1.2vx @Code "@TextPlace"
X//1rt @Code "@FootSect"
X}
X//
X@LittlePage {
X|0.5rt - 2 -
X//1.2vx @Code "@TextPlace"
X//1rt @Code "@FootSect"
X}
X//0.2c
X8p @Font @Code "@PageList 3"
X}
Xwhich has the potential to expand to infinitely many pages.
X@PP
XWe conclude this example by defining @Code "@FootSect" to be a small
Xhoriz&-ontal line above a list of @Code "@FootPlace" symbols:
X@IL
X@LI @Code {
X"def @FootList"
X"{"
X"    @FootPlace"
X"    //0.1i @FootList"
X"}"
X}
X@LI @Code {
X"def @FootSect"
X"{"
X"    1i @Wide @HLine"
X"    //0.1i @FootList"
X"}"
X}
X@EL
XThis method of specifying page layout is infinitely more flexible than
Xthe other, since the full resources of the language may be brought to
Xbear.  Of course, the {@Code "@PageList"}, {@Code "@FootSect"}, and
X{@Code "@FootList"} symbols must be expanded only on demand, and we have
Xyet to see how the {@Code "@TextPlace"} and {@Code "@FootPlace"} symbols
Xcan be replaced by actual text and footnotes.
X@End @Section
END_OF_FILE
  if test 5064 -ne `wc -c <'lout/doc/tr.over/s4'`; then
    echo shar: \"'lout/doc/tr.over/s4'\" unpacked with wrong size!
  fi
  # end of 'lout/doc/tr.over/s4'
fi
if test -f 'lout/doc/tr.over/s5' -a "${1}" != "-c" ; then
  echo shar: Will not clobber existing file \"'lout/doc/tr.over/s5'\"
else
  echo shar: Extracting \"'lout/doc/tr.over/s5'\" \(4210 characters\)
  sed "s/^X//" >'lout/doc/tr.over/s5' <<'END_OF_FILE'
X@Section
X   @Title { Galleys }
X@Begin
X@PP
XThe fundamental problem with inserting text, footnotes, and floating
Xfigures into pages is that the process seems impossible to describe in
Xfunctional terms.  A footnote is entered within a paragraph of text, but
Xit appears somewhere else:  at the foot of a page.  Some new abstraction
Xis needed to explain this.
X@PP
XThe landscape of features that previous document formatting systems have
Xintro&-duced at this point can best be described metaphorically, as an
Xantediluvian swamp populated by dinosaurs and demons, whose air is
Xfilled with the piteous cries of docu&-ment format designers in torment.
X@PP
XLout's solution to this problem is a feature called the @I galley, after
Xthe metal trays used in manual typesetting.  A galley consists of an
Xobject plus an indication that the object is to appear somewhere other
Xthan its invokation point.  For example,
X@ID {
X@LittlePageList 1
X// @LittleEndRunPlace
X//
X@LittleText {
X@Heading { Galleys }
X@PP
XThe fundamental problem with inserting text, footnotes, and floating
Xfigures into pages is that the process seems impossible to describe in
Xfunctional terms.  A footnote is entered within a para&-graph of text, but
Xit appears somewhere else:  at the foot of a page.  Some new abstraction
Xis needed to explain this.
X}
X//
X@LittleEndRun
X}
Xis the result of the expression
X@ID @Code {
X"@PageList 1"
X"//"
X"@Text {"
X"@Heading { Galleys }"
X"@PP"
X"The fundamental ..."
X"... to explain this."
X"}"
X}
XThe only new definitions required are these:
X@ID @Code {
X"def @TextPlace { @Galley }"
X""
X"def @Text"
X"    into { @TextPlace&&preceding }"
X"    right x"
X"{ x }"
X}
XThey say that @Code "@TextPlace" (which the reader will recall as lying
Xwithin the pages of {@Code "@PageList"}) is a placeholder for an
Xincoming galley, and that @Code "@Text" is a galley whose result is to
Xappear, not where @Code "@Text" is invoked, but rather at some
X@Code "@TextPlace" preceding that point of invokation in the final
Xprinted document.
X@PP
XAlthough the abstraction can be understood in a static way, it is
Xhelpful to trace what happens when the Basser Lout batch formatter reads
Xthe expression above.
X@PP
XSince @Code "@PageList 1" indirectly con&-tains the special @Code "@Galley"
Xsymbol, it will be expanded only upon demand.  The discovery of the
X@Code "@Text" galley initiates a search for a {@Code "@TextPlace"},
Xwhich is found within {@Code "@PageList 1"} and so forces one such
Xexpansion.  The available width at this @Code "@TextPlace" is six
Xinches, so the @Code "@Text" galley is broken into six-inch components
Xwhich are promoted one by one until the available height (nine inches)
Xis exhausted.  Since the @Code "@Text" galley is not entirely consumed,
Xa forward search of the docu&-ment is made, another @Code "@TextPlace" is
Xfound within the as yet unexpanded {@Code "@PageList 2"}, and the
Xprocess is repeated.
X@PP
XThe treatment of footnotes is the same, except that
X@ID @Code {
X"def @FootNote"
X"    into { @FootPlace&&following }"
X}
Xis used to make the footnote appear later in the finished document than its
Xinvokation point.  Basser Lout suspends the promotion of text into pages
Xjust after the component containing the footnote's invokation point is
Xpromoted, switches to the placement of the footnote galley, then resumes
Xthe body text.
X@PP
XA collection of galleys all targeted to the same place may optionally
Xappear sorted on a designated key, thus implementing sorted reference
Xlists and indexes.  The author was obliged to make the sorting option a
Xprimitive feature, since it otherwise seems to require boolean operators
Xwhich he preferred to exclude.
X@PP
XThe @Code "@PageList" object which receives the @Code "@Text" galley
Xcan itself be viewed as a galley whose components are pages, and this
Xleads to a dynamic view of Lout document assembly as a tree of galleys, each
Xpromoting into its parent, with the root galley promoting into the
Xoutput file.  For example, the BookLayout package [{@Ref kingston92begin}]
Xhas @Code "@Section" galleys promoting into @Code "@Chapter" galleys
Xpromoting into a single @Code "@PageList" galley, which promotes into
Xthe output; no limit is imposed on the height of the tree.
X@End @Section
END_OF_FILE
  if test 4210 -ne `wc -c <'lout/doc/tr.over/s5'`; then
    echo shar: \"'lout/doc/tr.over/s5'\" unpacked with wrong size!
  fi
  # end of 'lout/doc/tr.over/s5'
fi
if test -f 'lout/doc/tr.tab/s6' -a "${1}" != "-c" ; then
  echo shar: Will not clobber existing file \"'lout/doc/tr.tab/s6'\"
else
  echo shar: Extracting \"'lout/doc/tr.tab/s6'\" \(4698 characters\)
  sed "s/^X//" >'lout/doc/tr.tab/s6' <<'END_OF_FILE'
X@Section
X   @Title { Rules, boxes, multi-page tables, etc. }
X@Begin
X@PP
XTab draws four kinds of rules.  @I {Above rules} go across the table
Xabove a specified row; @I {below rules} go across the table below a
Xrow.  @I {Between rules} go down the table between any two columns, but
Xnot before the first or after the last; and @I { side rules } go down
Xthe two sides:
X@ID @Code {
X"@Tab"
X"    above { no }"
X"    below { yes }"
X"    between { single }"
X"    side { double }"
X"    @Fmta { ... }"
X"..."
X}
XEach option may have the value @Code no (no rules), @Code yes or
X@Code single (draw single rules), or @Code double (draw double
Xrules).  Omitting an option is equivalent to giving it the value
X{@Code no}.  A rule below one row exactly overstrikes a rule above the
Xnext, unless a page break intervenes.
X@PP
XThese options to @Code "@Tab" will draw all possible rules of the given
Xtype.  If only some are wanted, there are {@Code above} and
X{@Code below} options (but no {@Code side} option) for each row symbol:
X@ID @Code {
X"@Rowf"
X"    above { yes }"
X"    below { double }"
X"    A { ... }"
X"    ..."
X}
Xand there is a @Code between option for the @Code "!" symbol that
Xseparates columns in the format options:
X@ID @Code "@Col A  ! between { double }  @Col B"
XThe symbols @Code "!!" and @Code "!!!" are abbreviations for
X@Code "! between { single }" and {@Code "! between { double }"}.  All
Xthese options override the corresponding @Code "@Tab" options when they
Xare present; when they are absent, the @Code "@Tab" options hold sway.
X@PP
XIt is not hard to assemble a single box around a table, using side
Xrules, a rule above the first row, and a rule below the last:
X@ID @Code {
X"@Tab"
X"    side { single }"
X"{"
X"    @Rowa above { single } ..."
X"    ..."
X"    @Rowj below { single } ..."
X"}"
X}
XDouble boxes around a table should be assembled using the following recipe:
X@ID @Code {
X"@Tab"
X"    side { double }"
X"{"
X"    @Rowa above { doubleboxabove } ..."
X"    ..."
X"    @Rowj below { doubleboxbelow } ..."
X"}"
X}
XThis is a little tedious, but the result is good.
X@PP
XThe symbols @Code "@Line" and @Code "@DoubleLine" produce horizontal
Xsingle and double lines of the width of the column.  Two other symbols,
X@Code "@Rule" and {@Code "@DoubleRule"}, produce lines which extend into
Xthe adjacent margins as well.  For example,
X@CD {
X@Tab
X    @Fmta { @Col A }
X{
X    @Rowa A { 5^.46 }
X    @Rowa A { 128^.2 }
X    @Rowa A { 3^.4159 }
X    @Rowa A { 5772^ }
X    @Rowa A { @Line } vmargin { 0i }
X    @Rowa A { 5909^.0759 }
X}
X}
Xis produced by
X@ID @Code {
X"@Tab"
X"    @Fmta { @Col A }"
X"{"
X"    @Rowa A { 5^.46 }"
X"    @Rowa A { 128^.2 }"
X"    @Rowa A { 3^.4159 }"
X"    @Rowa A { 5772^ }"
X"    @Rowa A { @Line } vmargin { 0i }"
X"    @Rowa A { 5909^.0759 }"
X"}"
X}
XOwing to problems behind the scenes, @Code "@Rule" and @Code "@DoubleRule"
Xfail in aligned columns.
X@PP
XThe @Code "@Tab" symbol has a @Code "linewidth" option which determines
Xthe thickness of all the lines:
X@ID @Code {
X"@Tab"
X"    linewidth { 0.5 pt }"
X}
Xshows the default value, 0.5 points.  This cannot be overridden within
Xthe table.  Double rules are drawn with their centres three line widths
Xapart.  Tab thinks that rules and double rules occupy no space, so thick
Xrules may require larger margins.
X@PP
XThe tables produced by Tab permit page breaks between any two rows.  The
Xchoice of page breaks can either be left to Lout, or it can be forced by
Xplacing the new page symbol @Code "@NP" between two rows.  To
Xensure that each part of a multi-page table is boxed, the rows preceding
Xthe page breaks must have @Code below rules, and the rows following them
Xmust have @Code above rules.  The @Code "@IndentedDisplay" and
X@Code "@CentredDisplay" symbols of the DocumentLayout package prevent
Xpage breaks in the thing displayed, so they cannot be used to display
Xmulti-page tables; a multi-page table should be displayed at the left
Xmargin by preceding and following it with {@Code "@DP"}.  To prevent
Xpage breaks within a small table, either use one of the
Xdisplay symbols just mentioned or else use @Code "@OneRow @Tab ...".
X@PP
XThe @Code "@HAdjust" symbol from standard Lout can be used to widen a
Xtable's columns until it occupies the full column width.  The
Xrecommended arrangement is
X@ID @Code {
X"@DP"
X"@HAdjust @Tab"
X"   ..."
X"@DP"
X}
Xsince @Code "@HAdjust" is not effective within displays.
X@PP
XExpert users might occasionally find a use for the @Code "@MarkRow"
Xsymbols.  There is one of them for each @Code "@Row" symbol
X({@Code "@MarkRowa"} for {@Code "@Rowa"}, etc.).  A @Code "@MarkRow"
Xsymbol causes the principal mark of the table to pass through that row,
Xpermitting its alignment with horizontally adjacent objects.
X@End @Section
END_OF_FILE
  if test 4698 -ne `wc -c <'lout/doc/tr.tab/s6'`; then
    echo shar: \"'lout/doc/tr.tab/s6'\" unpacked with wrong size!
  fi
  # end of 'lout/doc/tr.tab/s6'
fi
if test -f 'lout/include/book' -a "${1}" != "-c" ; then
  echo shar: Will not clobber existing file \"'lout/include/book'\"
else
  echo shar: Extracting \"'lout/include/book'\" \(4131 characters\)
  sed "s/^X//" >'lout/include/book' <<'END_OF_FILE'
X
X###############################################################################
X#                                                                             #
X#  Setup file for invoking @DocumentLayout for books                          #
X#                                                                             #
X#  Jeffrey H. Kingston                                                        #
X#  22 December 1992                                                           #
X#                                                                             #
X###############################################################################
X
X@SysInclude { ft  }
X@SysInclude { dl  }
X# @SysInclude { eq  }
X# @SysInclude { tab }
X# @SysInclude { pas }
X# @SysInclude { fig }
X
X@Use { @DocumentLayout
X  # @InitialFont       {  Times Base 12p } # initial font
X  # @InitialBreak      {  adjust 1.20fx  } # initial break
X  # @Hyphenate         {  Yes            } # Want hyphenation? Yes or No
X  # @MajorHeadingFont  {  Bold 2.0f      } # font for major headings
X  # @HeadingFont       {  Bold           } # font for ordinary headings
X  # @MinorHeadingFont  {  Bold           } # font for minor headings
X  # @BookCoverFont     {  Helvetica Base } # font for book cover
X
X  # @ParaGap           {  1.30vx         } # gap between paragraphs
X  # @ParaIndent        {  2.00f          } # paragraph first-line indent
X
X  # @DispGap           {  1.00v          } # gap above and below displays
X  # @DispIndent        {  2.00f          } # @IndentedDisplay indent
X  # @DefaultIndent     {  0.5rt          } # @Display indent
X  # @WideIndent        {  4.00f          } # @WideTaggedList indent
X  # @VeryWideIndent    {  8.00f          } # @VeryWideTaggedList indent
X
X  # @PageWidth         { 21.00c          } # width of page
X  # @PageHeight        { 29.70c          } # height of page
X  # @PageMargin        {  2.50c          } # size of all four margins
X  # @Columns           {  Single         } # Single, Double, Multi
X  # @DoubleColWidth    {  7.50c          } # column width used by Double
X  # @MultiColWidth     {  4.67c          } # column width used by Multi
X  # @ColGap            {  1.00c          } # gap between columns
X  # @TopGap            {  0.75c          } # gap between figures
X  # @MidGap            {  0.75c          } # gap above and below body text
X
X  # @FootNoteFont      {  0.80f          } # font for footnotes
X  # @FootNoteBreak     {  1.20fx         } # break for footnotes
X  # @FootLen           {  2.00c          } # footnote line and indent size
X  # @ColFootLen        {  1.20c          } # @FootLen when Double, Multi
X  # @FootGap           {  0.20c          } # gap between footnotes
X
X    @MakeIndex         {  Yes            } # Want index? Yes or No
X  # @IndexColumns      {  Double         } # Single, Double, Multi
X
X    @TableOfContents   {  Yes            } # Want contents? Yes or No
X  # @MajorContentsGap  {  1.30v          } # gap above major entry
X  # @ContentsGap       {  1.00v          } # gap above ordinary entry
X
X  # @ChapterNumbers    {  Yes            } # Yes or No
X  # @SectionNumbers    {  Yes            } # Yes or No
X  # @SubSectionNumbers {  Yes            } # Yes or No
X  # @AppendixNumbers   {  Yes            } # Yes or No
X  # @SubAppendixNumbers{  Yes            } # Yes or No
X  # @ChapterGap        {  1.10b          } # gap before each chapter
X  # @SectionGap        {  2.00v          } # gap before each section
X  # @SubSectionGap     {  1.50v          } # gap before each subsection
X    @AppendixGap       {  1.10b          } # gap before each appendix
X  # @SubAppendixGap    {  2.00v          } # gap before each subappendix
X
X  # @PageNumbers       {  Yes            } # Want page numbers? Yes or No
X  # @FirstPageNumber   {  1              } # Number of first page
X  # @PageOneTopFormat  { @Null               }
X  # @PageOneFootFormat { @Null               }
X  # @PageTopFormat     { |0.5rt - @PageNum - }
X  # @PageFootFormat    { @Null               }
X    @BookTitleFormat   { {Bold 2.0f} @Font {//2.0f @Title //0.5f} }
X}
END_OF_FILE
  if test 4131 -ne `wc -c <'lout/include/book'`; then
    echo shar: \"'lout/include/book'\" unpacked with wrong size!
  fi
  # end of 'lout/include/book'
fi
if test -f 'lout/include/report' -a "${1}" != "-c" ; then
  echo shar: Will not clobber existing file \"'lout/include/report'\"
else
  echo shar: Extracting \"'lout/include/report'\" \(4110 characters\)
  sed "s/^X//" >'lout/include/report' <<'END_OF_FILE'
X
X###############################################################################
X#                                                                             #
X#  Setup file for invoking @DocumentLayout for technical reports              #
X#                                                                             #
X#  Jeffrey H. Kingston                                                        #
X#  22 December 1992                                                           #
X#                                                                             #
X###############################################################################
X
X@SysInclude { ft  }
X@SysInclude { dl  }
X# @SysInclude { eq  }
X# @SysInclude { tab }
X# @SysInclude { pas }
X# @SysInclude { fig }
X
X@Use { @DocumentLayout
X  # @InitialFont       {  Times Base 12p } # initial font
X  # @InitialBreak      {  adjust 1.20fx  } # initial break
X  # @Hyphenate         {  Yes            } # Want hyphenation? Yes or No
X  # @MajorHeadingFont  {  Bold 2.0f      } # font for major headings
X  # @HeadingFont       {  Bold           } # font for ordinary headings
X  # @MinorHeadingFont  {  Bold           } # font for minor headings
X  # @BookCoverFont     {  Helvetica Base } # font for book cover
X
X  # @ParaGap           {  1.30vx         } # gap between paragraphs
X  # @ParaIndent        {  2.00f          } # paragraph first-line indent
X
X  # @DispGap           {  1.00v          } # gap above and below displays
X  # @DispIndent        {  2.00f          } # @IndentedDisplay indent
X  # @DefaultIndent     {  0.5rt          } # @Display indent
X  # @WideIndent        {  4.00f          } # @WideTaggedList indent
X  # @VeryWideIndent    {  8.00f          } # @VeryWideTaggedList indent
X
X  # @PageWidth         { 21.00c          } # width of page
X  # @PageHeight        { 29.70c          } # height of page
X  # @PageMargin        {  2.50c          } # size of all four margins
X  # @Columns           {  Single         } # Single, Double, Multi
X  # @DoubleColWidth    {  7.50c          } # column width used by Double
X  # @MultiColWidth     {  4.67c          } # column width used by Multi
X  # @ColGap            {  1.00c          } # gap between columns
X  # @TopGap            {  0.75c          } # gap between figures
X  # @MidGap            {  0.75c          } # gap above and below body text
X
X  # @FootNoteFont      {  0.80f          } # font for footnotes
X  # @FootNoteBreak     {  1.20fx         } # break for footnotes
X  # @FootLen           {  2.00c          } # footnote line and indent size
X  # @ColFootLen        {  1.20c          } # @FootLen when Double, Multi
X  # @FootGap           {  0.20c          } # gap between footnotes
X
X  # @MakeIndex         {  No             } # Want index? Yes or No
X  # @IndexColumns      {  Double         } # Single, Double, Multi
X
X  # @TableOfContents   {  No             } # Want contents? Yes or No
X  # @MajorContentsGap  {  1.30v          } # gap above major entry
X  # @ContentsGap       {  1.00v          } # gap above ordinary entry
X
X  # @ChapterNumbers    {  Yes            } # Yes or No
X  # @SectionNumbers    {  Yes            } # Yes or No
X  # @SubSectionNumbers {  Yes            } # Yes or No
X  # @AppendixNumbers   {  Yes            } # Yes or No
X  # @SubAppendixNumbers{  Yes            } # Yes or No
X  # @ChapterGap        {  1.10b          } # gap before each chapter
X  # @SectionGap        {  2.00v          } # gap before each section
X  # @SubSectionGap     {  1.50v          } # gap before each subsection
X  # @AppendixGap       {  2.00v          } # gap before each appendix
X  # @SubAppendixGap    {  2.00v          } # gap before each subappendix
X
X  # @PageNumbers       {  Yes            } # Want page numbers? Yes or No
X  # @FirstPageNumber   {  1              } # Number of first page
X  # @PageOneTopFormat  { @Null               }
X  # @PageOneFootFormat { @Null               }
X  # @PageTopFormat     { |0.5rt - @PageNum - }
X  # @PageFootFormat    { @Null               }
X  # @BookTitleFormat   { Bold @Font @Title   }
X}
END_OF_FILE
  if test 4110 -ne `wc -c <'lout/include/report'`; then
    echo shar: \"'lout/include/report'\" unpacked with wrong size!
  fi
  # end of 'lout/include/report'
fi
echo shar: End of archive 27 \(of 30\).
cp /dev/null ark27isdone
MISSING=""
for I in 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 ; do
    if test ! -f ark${I}isdone ; then
    MISSING="${MISSING} ${I}"
    fi
done
if test "${MISSING}" = "" ; then
    echo You have unpacked all 30 archives.
    rm -f ark[1-9]isdone ark[1-9][0-9]isdone
else
    echo You still must unpack the following archives:
    echo "        " ${MISSING}
fi
exit 0
exit 0 # Just in case...