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

Text File | 1993-06-19 | 82.5 KB | 2,166 lines

Newsgroups: comp.sources.misc
From: [e-mail] (Jeff Kingston)
Subject: v37i122:  lout - Lout document formatting system, v2, Part24/30
Message-ID: <[e-mail]>
X-Md4-Signature: 135715d89c295cb429cebe77ed816289
Sender: [e-mail] (Kent Landfield)
Organization: Sterling Software
Date: Wed, 2 Jun 1993 03:05:01 GMT
Approved: [e-mail]

Submitted-by: [e-mail] (Jeff Kingston)
Posting-number: Volume 37, Issue 122
Archive-name: lout/part24
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/s14 lout/doc/tr.fig/s5
#   lout/doc/tr.impl/s3.2 lout/doc/tr.lout/ch1.02
#   lout/doc/tr.lout/ch2.06 lout/doc/tr.lout/ch4.03 lout/makefile
#   lout/z30.c lout/z31.c
# Wrapped by kent@sparky on Sun May 30 19:44:01 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 24 (of 30)."'
if test -f 'lout/doc/tr.begin/s14' -a "${1}" != "-c" ; then
  echo shar: Will not clobber existing file \"'lout/doc/tr.begin/s14'\"
else
  echo shar: Extracting \"'lout/doc/tr.begin/s14'\" \(9025 characters\)
  sed "s/^X//" >'lout/doc/tr.begin/s14' <<'END_OF_FILE'
X@Section
X   @Tag { booklayout }
X   @Title { Books }
X@Begin
X@PP
XThe DocumentLayout package may also be used to produce books.  Type
X@Code "-ibook" in the Unix command instead of {@Code "-idoc"} to use the
Xpackage in this way.
X@PP
XA book begins with a @Code "@Book" symbol:
X@ID @Code {
X"@Book"
X"    @Title {}"
X"    @Author {}"
X"    @Edition {}"
X"    @Publisher {}"
X"    @InitialFont { Times Roman 12p }"
X"    @InitialBreak { adjust 1.2fx }"
X"    @Hyphenate { Yes }"
X"//"
X}
XThe first four options are printed on the title page, the first three
Xusing {@Code "clines @Break"} (see page {@PageOf clines}).  There are no
X{@Code "@Columns"}, {@Code "@PageNumbers"}, or {@Code "@FirstPageNumber"}
Xoptions.  The last three options are as for @Code "@Document" and
X{@Code "@Report"}.  Disaster will ensue if the @Code "//" is omitted.
X@PP
XNext comes an optional preface:
X@ID @Code {
X"@Preface"
X"    @Tag { preface }"
X"    @Title { About this book }"
X"@Begin"
X"@PP"
X"..."
X"@End @Preface"
X}
XSince the title of most prefaces is simply Preface, this is the default
Xvalue of the @Code "@Title" option.  After the preface, BookLayout will
Xproduce a table of contents listing the introduction, chapters,
Xsections, subsections, appendices, biblio&-graphy, and index as
Xappropriate.
X@PP
XThe pages up to this point will be numbered in lower case Roman
Xnumerals; subsequent pages will be numbered in Arabic starting from 1.
X@PP
XNext comes an optional introduction, in exactly the same style as the
Xpreface except that @Code "@Introduction" replaces @Code "@Preface" and
Xthe default title is Introduction.  After that comes a sequence of chapters
Xin the usual style:
X@ID @Code {
X"@Chapter"
X"    @Title { Principles }"
X"    @Tag { principles }"
X"@Begin"
X"@PP"
X"..."
X"@End @Chapter"
X}
XNo @Code "@BeginChapters" or @Code "@EndChapters" symbols are
Xneeded.  Within a chapter, there may be a sequence of sections,
Xeach introduced by @Code "@Section" in the usual way, all bracketed
Xby @Code "@BeginSections" and {@Code "@EndSections"}.  Within each
Xsection there may be subsections, each introduced by {@Code "@SubSection"},
Xand the sequence as a whole bracketed by @Code "@BeginSubSections" and
X{@Code "@EndSubSections"}.  The first subsection of the first section of the
Xfirst chapter will be numbered 1.1.1, and so on.  There are no sub-subsections.
X@PP
XFinally there is opportunity for a sequence of appendices, each
Xintroduced by @Code "@Appendix" in the usual way.  No
X@Code "@BeginAppendices" or @Code "@EndAppendices" symbols are
Xneeded.  The appendices are numbered A, B, C, etc., and there
Xare sub-appendices, obtained in the usual way.
X@PP
XEach symbol with a @Code "@Title" option also has a @Code "@RunningTitle"
Xoption.  The more important parts of the book (preface, introduction,
Xchapters, and appendices) have their @Code "@RunningTitle" printed at
Xthe top of each even-numbered page; if omitted, the @Code "@Title" option
Xis used instead.
X@PP
XWith Basser Lout, a long document is best broken into a sequence of files,
Xeach containing one section, from @Code "@Section" to @Code "@End @Section"
Xinclusive.  Other files are needed for the beginning of each chapter,
Xfrom @Code "@Chapter" to {@Code "@BeginSections"}, and for the end of
Xeach chapter, that is the final @Code "@EndSections" and
X{@Code "@End @Chapter"}.  On the Unix operating system a good scheme for
Xnaming these files is
X@ID lines @Break {
X@Code ch0.00     @Code "@Book" ... @Code "//"
X@Code ch0.01     Preface
X@Code ch0.02     Introduction
X@Code ch1.00     Beginning of Chapter 1
X@Code ch1.01     Section 1.1
X@Code ch1.02     Section 1.2
X. . .
X@Code ch1.99     End of Chapter 1
X@Code ch2.00     Beginning of Chapter 2
X@Code ch2.01     Section 2.1
X@Code ch2.02     Section 2.2
X. . .
X@Code ch2.99     End of Chapter 2
X}
Xand so on.  Then the Unix command
X@ID @Code "lout -ibook ch0.00 ch3.??"
Xwill format Chapter 3 only; and
X@ID @Code "lout -ibook ch?.??"
Xwill format the entire book.  The whole book must be formatted by one
Xcommand to get the page numbers right, but there is no need to do
Xthis until everything is perfect.
X@PP
XThe symbols described in Sections 1--7 above are all available as
Xusual.  The numbering of figures and tables includes a chapter or
Xappendix number:  the first figure of Appendix A will be numbered A.1,
Xand so on.  Figures and tables within the preface and introduction are
Xnumbered 1, 2, 3, etc.  When figures and tables appear near the end of
Xa chapter, the following page on which they appear may also be the first
Xpage of the next chapter, which looks very poor.  The solution is to move
Xthe figure or table to an earlier point in the chapter.
X@PP
XFigures and tables work in a slightly different way to previously, owing
Xto the need to attach a chapter or appendix number to each one.  The
Xfirst figure of each chapter or appendix must be preceded by
X{@Code "@BeginFigures"}, and the last figure of each chapter or appendix
Xmust be followed by {@Code "@EndFigures"}.  These symbols must also bracket
Xfigures in the preface and introduction.  The symbols are not required
Xwhen there are no figures.  Similarly, {@Code "@BeginTables"} and
X{@Code "@EndTables"} must bracket tables.
X@PP
XCross referencing works as described in Section {@NumberOf cross};
X@Code "@Tag" options may be given to the preface, introduction,
Xchapters, sections, subsections, appendices, and sub-appendices.
X@PP
XReferences work as described in Section {@NumberOf refs}, except
Xthat @Code "@ReferenceSection" is added automatically as needed.  A variant of
Xthe @Code "@Ref" symbol called @Code "@ChapRef" is provided, which
Xcauses the reference to appear at the end of the current preface,
Xintroduction, chapter, or appendix, rather than at the end of the book.
X@PP
XAlso available are symbols for making an index.  To
Xadd an entry to the index, place
X@ID @Code "packages @Index { Packages }"
Xfor example at the relevant point.  The result will be something like
X@ID { Packages, 27 }
Xappearing in the index in the alphabetical position determined by the
Xleft parameter, which should be a juxtaposition of simple words composed,
Xby convention, of lower-case letters and periods only.
X@PP
XA variant called @Code "@SubIndex" provides a small indent, as is
Xconventional for sub-entries in indexes.  For example,
X@ID @Code {
X"package  @Index  { Packages }"
X"package.r @SubIndex {ReportLayout}"
X"package.b @SubIndex {BookLayout}"
X}
Xscattered through a document will produce something like
X@ID lines @Break {
XPackages, 27
X   BookLayout, 45
X   ReportLayout, 40
X}
XNote how the left parameters have been carefully chosen to produce the
Xcorrect ordering.  There is also a @Code "@SubSubIndex" symbol with a
Xdouble indent.
X@PP
XThese symbols attach one page number to each entry.  Although the best
Xauthorities recommend exactly this, many authors choose to have entries
Xlike
X@ID { Fourier Transform, 576, 583--593 }
Xdespite the inconvenience to their readers.  {@Code "@RawIndex"},
X{@Code "@RawSubIndex"}, and {@Code "@RawSubSubIndex"}
Xsymbols are provided which do not add page numbers to the entry, leaving
Xthis to the user.  For example, one systematic way to get page number
Xranges is to place
X@ID @Code {
X"packages @RawIndex {"
X"    Packages, {@PageOf packages}"
X"    -- {@PageOf packages.end}"
X"}"
X}
Xat the start of the range, and
X@ID @Code {
X"{@PageMark packages.end}"
X}
Xat the end of the range.  This works because all six index symbols
Xinclude a @Code "@PageMark" operation.  Incidentally, this means that
Xindex tags should be different from chapter and other tags.
X@PP
XAnother use for @Code "@RawIndex" is to get blank lines into the index
Xbetween the letters of the alphabet, by inserting phantom entries:
X@ID @Code {
X"b @RawIndex {}"
X"c @RawIndex {}"
X"..."
X"z @RawIndex {}"
X}
XIn fact there is a symbol called @Code "@IndexBlanks" which creates
Xexactly these 25 entries.  Unfortunately, these blanks will occasionally
Xappear at the top of a column, and if there are no entries beginning with
Xx, for example, there will be two blank lines between the w and y
Xentries.  The careful user can start off with @Code "@IndexBlanks" and
Xreplace it later by the appropriate subset.
X@FootNote {
XFor Lout to solve this problem automatically, it would need to be told
Xwhich letter each index entry belongs under, perhaps by symbols
X{@Code "@AIndex"}, {@Code "@BIndex"}, etc.  The author
Xfelt that this would have been too tedious.
X}
X@PP
XOwing to problems behind the scenes, the Index heading will be printed,
Xand an entry will be made in the table of contents, even if there are no
Xentries in the index.  To prevent this, you will need to change the
X@Code "@MakeIndex" option in the @Code book setup file to {@Code "No"},
Xusing the method described in the following section.
X@PP
XAlthough the page numbers in index entries will be kept up to date
Xautomatically as the document changes, as all cross references are,
Xthe user is recommended to refrain from inserting index entries until
Xthe book is complete and an overall plan of the structure of the index
Xcan be made.
X@End @Section
END_OF_FILE
  if test 9025 -ne `wc -c <'lout/doc/tr.begin/s14'`; then
    echo shar: \"'lout/doc/tr.begin/s14'\" unpacked with wrong size!
  fi
  # end of 'lout/doc/tr.begin/s14'
fi
if test -f 'lout/doc/tr.fig/s5' -a "${1}" != "-c" ; then
  echo shar: Will not clobber existing file \"'lout/doc/tr.fig/s5'\"
else
  echo shar: Extracting \"'lout/doc/tr.fig/s5'\" \(9154 characters\)
  sed "s/^X//" >'lout/doc/tr.fig/s5' <<'END_OF_FILE'
X@Section
X   @Title { Lengths, angles, and points }
X@Begin
X@PP
XWe already know that two lengths placed side by side define a point.  This is
Xonly the simplest of a number of such geometrical combinations.
X@PP
XThe symbol @Code "@Distance" returns the length of the line joining two
Xpoints:
X@ID @Code "{0 0} @Distance {3 cm  4 cm}"
Xis equivalent to the length {@Code "5 cm"}.  The result of @Code "@Distance"
Xis never negative.  Notice that braces must enclose the two points.  The
Xsymbol @Code "@XDistance" returns the distance in the @Eq { x } direction
Xfrom one point to another:
X@ID {
X@Code "{" & @Eq { x sub 1 ``` y sub 1 } & @Code "}  @XDistance  {"
X& @Eq { x sub 2 ``` y sub 2 } & @Code "}"
X}
Xhas for its result the length @Eq { x sub 2 - x sub 1 }, and so may be
Xnegative.  There is an analogous @Code "@YDistance" symbol.
X@PP
XThe symbol @Code "@Angle" returns the angle @Eq {theta} from one point to
Xanother:
X@ID {
X@Code "{" & @Eq { x sub 1 ``` y sub 1 } & @Code "}  @Angle  {"
X& @Eq { x sub 2 ``` y sub 2 } & @Code "}"
X||7ct
X@Fig {
X@Figure
X   arrow { forward }
X   shape { 4 cm 0 0 0 4 cm 3 cm }
X{ 4c @Wide 3c @High }
X// {4 cm 3 cm} ** 0.4 ++ { 0.5 cm 0 } @MarkOf @Eq { (x sub 1 & , y sub 1 & ) }
X// {4 cm 3 cm} ** 0.4 @BaseOf @Circle margin { 0.05c } paint { black } {}
X// {4 cm 3 cm} ** 0.8 ++ { 0.5 cm 0 } @MarkOf @Eq { (x sub 2 & , y sub 2 & ) }
X// {4 cm 3 cm} ** 0.8 @BaseOf @Circle margin { 0.05c } paint { black } {}
X// { 1 cm 0.2 cm } ** 0.7 @BaseOf @Eq { theta }
X}
X}
XThe result will be 0 if the two points are equal.  The symbol @Code "<<"
Xreturns the point at a given distance and angle from @Eq { (0, 0) }:
X@ID {
X@Code "{" & @Eq { length }  @Code "<<"  @Eq { theta } & @Code "}"
X||7ct
X@Fig {
X@Figure
X   arrow { forward }
X   shape { 4 cm 0 0 0 4 cm 3 cm }
X{ 4c @Wide 3c @High }
X// {4 cm 3 cm} ** 0.5 -- {1.5 cm 0} @BaseOf @I length
X// {4 cm 3 cm} ** 0.8 @BaseOf @Circle margin { 0.05c } paint { black } {}
X// { 1 cm 0.2 cm } ** 0.7 @BaseOf @Eq { theta }
X}
X}
XFor example, @Code "{ 5 cm << 45 dg }" is the point 5 cm
Xfrom @Eq { (0, 0) } at 45 degrees.
X@PP
XPoints may be added, subtracted, and multiplied by a number:
X@ID @Tab
X     vmargin { 0.5vx }
X     @Fmta { @Col A ! @Col is ! @Col B }
X{
X@Rowa
X   A { @Code "{" & @Eq {x sub 1 ``` y sub 1} & @Code "}  ++  {" &
X@Eq {x sub 2 ``` y sub 2} & @Code "}" }
X   B { @Eq { (x sub 1 + x sub 2 & , y sub 1 + y sub 2 & ) } }
X@Rowa
X   A { @Code "{" & @Eq {x sub 1 ``` y sub 1} & @Code "}  --  {" &
X@Eq {x sub 2 ``` y sub 2} & @Code "}" }
X   B { @Eq { (x sub 1 - x sub 2 & , y sub 1 - y sub 2 & ) } }
X@Rowa
X   A { @Code "{" & @Eq {x sub 1 ``` y sub 1} & @Code "}  **  " & @Eq {k} }
X   B { @Eq { (x sub 1 & k, y sub 1 & k) } }
X}
XFor example,
X@ID {
X@Code "{" & @Eq {x sub 1 ``` y sub 1} & @Code "} ** 0.2  ++  " &
X@Code "{" & @Eq {x sub 2 ``` y sub 2} & @Code "} ** 0.8"
X}
Xis the point eight tenths of the way from
X@Eq { (x sub 1 & , y sub 1 & ) } to
X@Eq { (x sub 2 & , y sub 2 & ) } on the line joining them:
X@LP
X@ID @Fig {
X@Figure
X   shape {
X      {xsize 0} ** 0.3 ++ {0 ysize} @Label P1
X      {xsize 0} ++ {0 ysize} ** 0.4 @Label P2
X      P1 ** 0.2 @Label FP1
X      P2 ** 0.8 @Label FP2
X      0 0 P1 P2 0 0 [] FP1 FP1 ++ FP2 FP2
X   }
X{ 6c @High 9c @Wide }
X// P1 ++ {0.3 cm 0} @BaseOf @Eq { (x sub 1 & , y sub 1 & ) }
X// P2 ++ {0.3 cm 0} @BaseOf @Eq { (x sub 2 & , y sub 2 & ) }
X// FP1 ++ FP2 ++ {0.3 cm 0} @BaseOf
X@Eq { (0.2x sub 1 & + 0.8x sub 2 & , 0.2y sub 1 & + 0.8y sub 2 & ) }
X}
XWhen using {@Code "**"}, the point must be on the left and the number on
Xthe right.  It would be more convenient to name these symbols
X{@Code "+"}, {@Code "-"}, and {@Code "*"}, but these names
Xare often taken by equation formatters, and @Code "-" appears in
Xlengths, so we don't.  There are @Code "@Max" and @Code "@Min" symbols:
X@ID @Tab
X     vmargin { 0.5vx }
X     @Fmta { @Col A ! @Col is ! @Col B }
X{
X@Rowa
X  A { @Code "{" & @Eq {x sub 1 ``` y sub 1} & @Code "}  @Max  {" &
X@Eq {x sub 2 ``` y sub 2} & @Code "}" }
X  B { @Eq { (max(x sub 1 & , x sub 2 & ), max(y sub 1 & , y sub 2 & )) } }
X@Rowa
X  A { @Code "{" & @Eq {x sub 1 ``` y sub 1} & @Code "}  @Min  {" &
X@Eq {x sub 2 ``` y sub 2} & @Code "}" }
X  B { @Eq { (min(x sub 1 & , x sub 2 & ), min(y sub 1 & , y sub 2 & )) } }
X}
XNote carefully that these apply to points, not to numbers.
X@PP
XThe result of adding two points together depends on where the origin is
Xat the time, as well as on the points themselves.  This can lead to
Xunexpected results, as the author has found to his cost more than
Xonce.  Within the @Code shape option of {@Code "@Figure"}, the origin is
Xthe lower left corner of the result of the {@Code "@Figure"}.  In cases
Xlike the example on page {@PageOf sumpoints}, where points are added
Xoutside of any {@Code "@Figure"} symbol, the origin is usually at the
Xbottom left corner of the figure as a whole.  A label always denotes a
Xparticular point on the printed page, regardless of where the origin
Xhappens to be.
X@PP
XThe symbol @Code "@Prev" within the @Code "shape" option of @Code
X"@Figure" denotes the previous point of the shape, ignoring points within
X{@Code {"[" &0.5s "]"}}.  This makes it easy to specify each point
Xrelative to the previous one:
X@ID {
X@Code {
X"   shape {"
X"      0 0"
X"      { 2 cm << 30 }"
X"      @Prev ++ { 2 cm << 90 }"
X"      @Prev ++ { 2 cm << 150 }"
X"      @Prev ++ { 2 cm << 210 }"
X"      @Prev ++ { 2 cm << 270 }"
X"      0 0"
X"   }"
X}
X||7ct
X@Fig { ||2.5c
X@Figure
X   shape {
X      0 0
X      { 2 cm << 30 }
X      @Prev ++ { 2 cm << 90 }
X      @Prev ++ { 2 cm << 150 }
X      @Prev ++ { 2 cm << 210 }
X      @Prev ++ { 2 cm << 270 }
X      0 0
X   }
X{ 4c @Wide 4c @High }
X}
X}
X@PP
XFig provides a @Code "@Label" symbol for attaching a label to a point in
Xa shape, like this:
X@ID @Code "{xsize ysize} ** 0.5 @Label CTR"
XThe point may then be referred to more concisely by its label,
X{@Code CTR}.  For example, the large arrow appearing in Section 2 was
Xbuilt like this:
X@ID {
X@Code {
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"{ 6c @Wide 2c @High }"
X}
X||7ct
X@Fig {
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{ 6c @Wide 2c @High }
X// @ShowLabels
X}
X}
XIncidentally, the labels of a figure can be displayed as above by putting
Xthe symbol @Code "@ShowLabels" at the end of the figure.  Labels can
Xsave a lot of effort.  They should contain only digits, upper-case
Xletters and {@Code "@"}, because Fig and Lout use labels of their own
Xmade from lower-case letters.
X@PP
XThe standard shapes have standard labels; for example, the labels
Xof @Code "@Ellipse" are
X@LP
X@ID {
X@Code {
X"@Ellipse"
X"{ 3c @Wide 2c @High }"
X}
X||7ct
X@Fig {
X@Ellipse { 3c @Wide 2c @High }
X// @ShowLabels
X}
X}
XThere is a symbol, {@Code "::"}, for @I relabelling an object.
XEach label in the right parameter is relabelled in the following way:
X@LP
X@ID {
X@Code {
X"E1:: @Ellipse"
X"{ 3c @Wide 2c @High }"
X}
X||7ct
X@Fig {
XE1:: @Ellipse { 3c @Wide 2c @High }
X// @ShowLabels
X}
X}
XWithin the right parameter of @Code "::" the original names hold sway;
Xbut afterwards the names are changed by prefixing the label
Xand @Code "@" to them.  These composite labels may be used exactly like
Xother labels.  Relabelling can be nested to arbitrary depth:
X@LP
X@ID {
X5c @Wide @Code {
X"A::"
X"{   1:: @Ellipse"
X"    { 3c @Wide 2c @High }"
X"    //1c"
X"    2:: @Box"
X"    { 3c @Wide 2c @High }"
X"}"
X}
X||7ct
X@Fig {
XA::
X{   1:: @Ellipse { 3c @Wide 2c @High }
X    //1c
X    2:: @Box { 3c @Wide 2c @High }
X}
X// @ShowLabels
X}
X}
XThe right parameter of @Code "::" may be any object.
X@PP
XThe six standard shapes ({@Code "@Box"}, {@Code "@Square"},
X{@Code "@Diamond"}, {@Code "@Polygon"}, {@Code "@Ellipse"}, and
X{@Code "@Circle"}) have a special @Code CIRCUM label, not displayed by
X{@Code "@ShowLabels"}.  The expression
X@ID {
X@Eq { "angle" } @Code CIRCUM
X}
Xyields the point on the boundary of the shape at the given angle from
Xthe centre, in a coord&-inate system with the centre for origin.  Thus,
Xgiven a labelled standard shape such as
X@ID @Code "A :: @Ellipse ..."
Xthe point on its boundary at an angle of 45 degrees from the centre is
X@ID @Code "A@CTR ++ {45 A@CIRCUM}"
XThe braces must be present.  Regrettably, there is no way to produce a
X@Code CIRCUM label for shapes defined by the user in any reasonable time.
X@PP
XIf the same label is used twice, as is inevitable with unlabelled standard
Xshapes, only the most recent value is remembered.  There is a limit on the
Xmaximum number of distinct labels in any one figure, which
Xcan be changed by means of an option to the @Code "@Fig" symbol:
X@ID @Code {
X"@Fig"
X"   maxlabels { 500 }"
X"{ ... }"
X}
XThe default value is 200.  Large values could cause the printing device
Xto run out of memory.  Memory is reclaimed at the end of each figure.
X@End @Section
END_OF_FILE
  if test 9154 -ne `wc -c <'lout/doc/tr.fig/s5'`; then
    echo shar: \"'lout/doc/tr.fig/s5'\" unpacked with wrong size!
  fi
  # end of 'lout/doc/tr.fig/s5'
fi
if test -f 'lout/doc/tr.impl/s3.2' -a "${1}" != "-c" ; then
  echo shar: Will not clobber existing file \"'lout/doc/tr.impl/s3.2'\"
else
  echo shar: Extracting \"'lout/doc/tr.impl/s3.2'\" \(3408 characters\)
  sed "s/^X//" >'lout/doc/tr.impl/s3.2' <<'END_OF_FILE'
X@SubSection
X    @Tag { recursion }
X    @Title { Recursion and page layout }
X@Begin
X@PP
XDesign and implementation should proceed together in exploratory projects,
Xsince otherwise the design too easily becomes unrealistic.  Sometimes the
Ximplementation does more than its designer intended.  The author wrote the
Xfollowing purely as a testing scaffold:
X@ID @Code {
X"def @Page right x"
X"{"
X"    8i @Wide 11i @High"
X"    {"
X"        //1i  ||1i  x  ||1i"
X"        //1i"
X"    }"
X"}"
X}
XOnly afterwards did he realize its significance:  the concept of a page
Xhad been defined outside the implementation, removing the need for
Xcommands for setting page width and height, margins, and so on.
X@PP
XDefining a sequence of pages is harder, since their number is not known
Xin advance.  A simple version of this same problem is afforded by the
Xleaders found in tables of contents:
X@ID {
X4i @Wide { Chapter 7  @Leaders  53 }
X}
XThis seemed to require recursion, specifically the definition
X@ID @Code {
X"def @Leaders { ..   @Leaders }"
X}
XNote that both @Code ".." and @Code "@Leaders" are objects, so the two
Xspaces separating them are significant.  No base case is given, and indeed
Xwe have no boolean or conditional operators with which to express it;
Xbut we can adopt the implicit base `if space is not sufficient, delete
X{@Code "@Leaders"} and any preceding space'.  Then the expression
X@ID @Code "4i @Wide { Chapter 7  @Leaders  53 }"
Xwill produce the object shown above.  It is hard to see how this base
Xcould be made explicit, without violating the general principle of
Xkeeping all size information internal.  In the implementation,
X@Code "@Leaders" remains unexpanded while sizes are being
Xcalculated; then it is treated similarly to a receptive symbol, with
Xits body as an incoming galley (Section {@NumberOf flushing}).
X@PP
XWith this settled, it is now clear how to define a document which is a
Xnumbered sequence of pages.  Let @Code "@Next" be a prefix operator
Xwhich returns its parameter plus one.  Then
X@ID @Code {
X"def @PageList"
X"    right @PageNum"
X"{"
X"    @Page {"
X"          |0.5rt - @PageNum -"
X"          //1v   @TextPlace"
X"          //1rt  @FootSect"
X"    }"
X"    //"
X"    @PageList @Next @PageNum"
X"}"
X}
Xwhen invoked in the expression {@Code "@PageList 1"}, has for its result
Xthe potentially infinite 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}
XSimilarly, we may define @Code "@FootSect" like this:
X@ID @Code {
X"def @FootSect"
X"{"
X"    def @FootList"
X"        right @Num"
X"    {"
X"        @FootPlace"
X"        //1v"
X"        @FootList @Next @Num"
X"    }"
X""
X"    1i @Wide @HLine"
X"    //1v"
X"    @FootList 1"
X"}"
X}
Xso that an invocation of @Code "@FootSect" produces
X@ID @Code {
X1i @Wide @HLine
X"@FootPlace"
X"@FootPlace"
X"@FootPlace"
X"..."
X}
XThe expansion process is very similar to a BNF derivation, and would be
Xattempted only on demand.
X@PP
XClearly, deciding which expansions to take and replacing @Code "@TextPlace"
Xand {@Code "@FootPlace"} by the appropriate actual text will not be easy;
Xthis is the subject of Section {@NumberOf galleys}.  The important point
Xfor now is that we have here a very simple and flexible method of specifying
Xthe layout of pages, which requires no specialized language features.
X@End @SubSection
END_OF_FILE
  if test 3408 -ne `wc -c <'lout/doc/tr.impl/s3.2'`; then
    echo shar: \"'lout/doc/tr.impl/s3.2'\" unpacked with wrong size!
  fi
  # end of 'lout/doc/tr.impl/s3.2'
fi
if test -f 'lout/doc/tr.lout/ch1.02' -a "${1}" != "-c" ; then
  echo shar: Will not clobber existing file \"'lout/doc/tr.lout/ch1.02'\"
else
  echo shar: Extracting \"'lout/doc/tr.lout/ch1.02'\" \(8755 characters\)
  sed "s/^X//" >'lout/doc/tr.lout/ch1.02' <<'END_OF_FILE'
X@Section
X   @Title { Definitions }
X   @Tag { definitions }
X@Begin
X@PP
XThe features of Lout are very general.  They do not assume that documents
Xare composed of pages, nor that there are such things as margins and
Xfootnotes, for example.  @I Definitions
Xdefinitions. @Index { Definitions }
Xbridge the gap between Lout's general features and the
Xspecial features -- footnotes, equations, pages -- that particular
Xdocuments require.  They hold the instr&-uct&-ions for producing these
Xspecial features, conveniently packaged ready for use.
X@PP
XFor example, consider the challenge posed by `@TeX', which is the name of
Xone of Lout's most illustrious rivals [{@Ref knuth84}].  Lout solves it
Xeasily enough, like this:
X@ID @Code {
X"T{ /0.2fo E }X"
X}
Xbut to type this every time @TeX is mentioned would be tedious and
Xerror-prone.  So we place a definition at the beginning of the document:
X@ID @Code {
X"def  @TeX  {  T{ /0.2fo E }X  }"
X}
XNow @Code "@TeX" stands for the object following it between
Xbraces, and we may write
X@ID @Code {
Xconsider the challenge posed by "`@TeX'", ...
X}
Xas the author did earlier in this paragraph.
X@PP
XA @I symbol
Xsymbol. @Index Symbol
Xis a name, like {@Code "@TeX"}, which stands for
Xsomething other than itself.  The initial @Code "@" is not compulsory,
Xbut it does make the name stand out clearly.  A @I definition of a symbol
Xdeclares a name to be a symbol, and says what the symbol stands for.  The
X@I body of a definition
Xbody.of @Index { Body of a definition }
Xis the part following the name, between the braces.  To @I invoke
Xinvocation @Index { Invocation of a symbol }
Xa symbol is to make use of it.
X@PP
XAnother expression ripe for packaging in a definition is
X@ID @Code {
X"@OneRow {  |  -2p @Font n  ^/0.5fk  2  }"
X}
Xwhich produces @OneRow { | -2p @Font n ^/0.5sk 2 } as the reader
Xfamiliar with Chapter {@NumberOf details}
Xcan verify.  But this time we would like to be able to write
X@ID {
X@I object  @Code "@Super"  @I object
X}
Xso that @Code { a "@Super" 2 } would come out as {a @Super 2}, and so
Xon, for in this way the usefulness of the definition is greatly
Xincreased.  Here is how it is done:
X@ID @Code {
X"def @Super"
X"   left x"
X"   right y"
X"{ @OneRow {  |  -2p @Font y  ^/0.5fk  x  }"
X"}"
X}
XThis definition says that @Code "@Super" has two {@I parameters},
Xparameter @Index Parameter
X@Code x and {@Code y}.  When @Code "@Super" is invoked, all occurrences
Xof @Code x in the body will be replaced by the object just to the left
Xof {@Code "@Super"}, and all occurrences of @Code y will be replaced by
Xthe object just to the right.  So, for example, the expression
X@ID @Code {
X"2  @Super  { Slope @Font n }"
X}
Xis equal to
X@ID @Code {
X"@OneRow {  |  -2p @Font { Slope @Font n }  ^/0.5fk  2  }"
X}
Xand so comes out as {2 @Super {Slope @Font n}}.
X@PP
XLout permits definitions to invoke themselves, a peculiarly circular
Xthing to do which goes by the name of
Xrecursion @Index Recursion
X@I recursion.  Here is an example
Xof a recursive definition:
X@ID @Code {
X"def  @Leaders  {  ..   @Leaders  }"
X}
XThe usual rule is that the value of an invocation of a symbol is a copy of
Xthe body of the symbol's definition, so the value of @Code "@Leaders" must be
X@ID @Code {
X"..   @Leaders"
X}
XBut now this rule applies to this new invocation of {@Code "@Leaders"};
Xsubstituting its body gives
X@ID @Code {
X"..   ..   @Leaders"
X}
Xand so on forever.  In order to make this useful,
Xan invocation of a recursive symbol is replaced by its body only if
Xsufficient space is available.  So, for example,
X@ID @Code {
X"4i @Wide { Chapter 7  @Leaders   62 }"
X}
Xhas for its result the object
X@ID {
X4i @Wide { Chapter 7  @Leaders   62 }
X}
Xwith Lout checking before each replacement of @Code "@Leaders" by
X@OneCol @Code { ".."   "@Leaders" } that the total length afterwards,
Xincluding the other words, would not exceed four inches.
X@PP
XThe remaining issue is what happens when Lout decides that it is time to
Xstop.  The obvious thing to do is to replace the last invocation by an
Xempty object:
X@ID @Code {
X"..    ..    ..    ..    ..    ..    ..    ..    {}"
X}
XAs the example shows, this would leave a small trailing space, which in
Xpractice turns out to be a major headache.  Lout solves this problem
Xby replacing the last invocation with a different kind of empty object,
Xcalled @@Null, whose effect is to make an adjacent concatenation symbol
Xdisappear, preferably one preceding the @@Null.  Thus, when Lout
Xreplaces @Code "@Leaders" by @@Null in the expression
X@ID @Code {
X"..    ..    ..    ..    ..    ..    ..    ..    @Leaders"
X}
Xthe trailing space, which is really a horizontal concatenation symbol,
Xdisappears as well.  This is carefully taken into account when deciding
Xwhether there is room to replace @Code "@Leaders" by its body at each
Xstage.
X@PP
XThe remainder of this section is devoted to showing how definitions may
Xbe used to specify the @I {page layout}
Xpage.layout @RawIndex { Page layout }
Xpage.layout.basic @SubIndex { principles of }
Xof a document.  To begin with,
Xwe can define a page like this:
X@ID @Code {
X"def @Page"
X"{"
X"    //1i  ||1i"
X"    6i @Wide 9.5i @High"
X"    { @TextPlace  //1rt  @FootSect }"
X"    ||1i  //1i"
X"}"
X}
XNow @Code "@Page" is an eight by
Xeleven and a half inch object, with one inch margins, a place at the top for
Xtext, and a section at the bottom for footnotes (since @Code "//1rt" leaves
Xsufficient space to bottom-justify the following object).  It will be
Xconvenient for us to show the effect of invoking @Code "@Page" like this:
X@ID @Code
X{ { //0.5ix 8p @Font "@Page" &2m => } &2m
X@LittlePage { "@TextPlace" //1rt "@FootSect" }
X}
Xwith the invoked symbol appearing to the left of the arrow, and its body to
Xthe right.
X@PP
XThe definition of a vertical list of pages should come as no surprise:
X@ID @Code {
X"def @PageList"
X"{"
X"    @Page"
X"    //"
X"    @PageList"
X"}"
X}
XThis allows invocations like the following:
X@ID @Code @HExpand @HScale {
X{ //0.5ix 8p @Font "@PageList" }
X||1m { //0.5ix => } ||1m
X{        @LittlePage { "@TextPlace" //1rt "@FootSect" }
X  //0.2c 8p @Font "@PageList"
X}
X||1m { //0.5ix => } ||1m
X{        @LittlePage { "@TextPlace" //1rt "@FootSect" }
X  //     @LittlePage { "@TextPlace" //1rt "@FootSect" }
X  //0.2c 8p @Font "@PageList"
X}
X||1m { //0.5ix => } ||1m
X{        @LittlePage { "@TextPlace" //1rt "@FootSect" }
X  //     @LittlePage { "@TextPlace" //1rt "@FootSect" }
X}
X}
Xsetting  @Code "@PageList" to @Code @@Null on the last step.  An
Xarbitrary number of pages can be generated in this way.
X@PP
XA definition for @Code "@TextPlace" is beyond us at present, since
X@Code "@TextPlace" must be replaced by different parts of the text
Xof the document on different pages.  We can,
Xhowever, define @Code "@FootSect" to be a small space followed by a
Xhorizontal line followed by a list of places where footnotes are to go:
X@ID @Code {
X"def @FootList         "
X"{                     "
X"   @FootPlace         "
X"   //0.3v             "
X"   @FootList          "
X"}                     "
X"                      "
X"def @FootSect"
X"{                        "
X"   //0.3v 1i @Wide @HLine"
X"   //0.3v @FootList      "
X"}                        "
X}
Xassuming that @Code "@HLine" will produce a horizontal line of the
Xindicated width.  With this definition we can generate pages like this:
X@ID @Code {
X@LittlePage { "@TextPlace"
X               //1rt
X               "@FootSect"
X             }
X||2m { //0.5ix => } ||2m
X@LittlePage { "@TextPlace"
X               //1rt
X               @OneRow { 1c @Wide @HLine
X                         //0.1c
X                         "@FootList"
X                       }
X             }
X||2m { //0.5ix => } ||2m
X@LittlePage { "@TextPlace"
X               //1rt
X               @OneRow { 1c @Wide @HLine
X                         //0.1c
X                         "@FootPlace"
X                         //0.1c
X                         "@FootList"
X                       }
X             }
X}
Xand so on for arbitrarily many footnotes.
X@PP
XWe will see in the next section how invocations of @Code "@PageList",
X@Code "@FootSect" and @Code "@FootList" are replaced by their bodies only
Xwhen the need to insert text and footnotes obliges Lout to do so;
Xotherwise the invocations are replaced by @@Null.  In this way, the
Xright number of pages is made, the small line appears only on pages that
Xhave at least one footnote, and unnecessary concatenation symbols
Xdisappear.
X@PP
XThis approach to page layout is the most original contribution Lout has
Xmade to document formatting.  It is extraordinarily flexible.  Two-column
Xpages?  Use
X@ID @Code {
X"{2.8i @Wide @TextPlace}  ||0.4i  {2.8i @Wide @TextPlace}"
X}
Xinstead of {@Code "@TextPlace"}.  Footnotes in smaller type?  Use
X@Code { -2p "@Font" "@FootPlace" } instead of {@Code "@FootPlace"}.  And
Xon and on.
X@End @Section
END_OF_FILE
  if test 8755 -ne `wc -c <'lout/doc/tr.lout/ch1.02'`; then
    echo shar: \"'lout/doc/tr.lout/ch1.02'\" unpacked with wrong size!
  fi
  # end of 'lout/doc/tr.lout/ch1.02'
fi
if test -f 'lout/doc/tr.lout/ch2.06' -a "${1}" != "-c" ; then
  echo shar: Will not clobber existing file \"'lout/doc/tr.lout/ch2.06'\"
else
  echo shar: Extracting \"'lout/doc/tr.lout/ch2.06'\" \(9965 characters\)
  sed "s/^X//" >'lout/doc/tr.lout/ch2.06' <<'END_OF_FILE'
X@Section
X   @Title { Galleys and targets }
X   @Tag { targets }
X@Begin
X@PP
XThe behaviour of galleys and their targets, as described in Section
Xgalley.feature.in.detail @SubIndex { in detail }
Xtargets.in.detail @SubIndex { in detail }
X{@NumberOf galleys}, can be summarized in three laws:
X@DP
X{@I {First Law}}:  The first target is the closest invocation of the
Xtarget symbol, either preceding or following the invocation point of the
Xgalley as required, which has sufficient space to receive the first
Xcomponent;
X@DP
X{@I {Second Law}}:  Each subsequent target is the closest invocation of
Xthe target symbol, following the previous target and lying within the same
Xgalley, which has sufficient space to receive the first remaining component;
X@DP
X{@I {Third Law}}:  A receptive symbol that does not receive at least one
Xcomponent of any galley is replaced by @@Null.
X@DP
XThe terms `closest,' `preceding,' and `following' refer to position in
Xthe final printed document.  This section explains the operation of
Xthese laws in Basser Lout.
X@PP
XWhen a galley cannot be fitted into just one target, Lout must find
Xpoints in the galley where it can be split in two.  The object lying
Xbetween two neighbouring potential split points is called a @I component
Xcomponent @Index { Components of a galley }
Xof the galley.  By definition, a component cannot be split.
X@PP
XTo determine the components of a galley, expand all symbols other than
Xrecursive and receptive ones, discard all @@Font, @@Break, and @@Space
Xsymbols, perform paragraph breaking as required, and discard all
Xredundant braces.  Then view the galley as a sequence of one or more
Xobjects separated by vertical concatenation symbols; these are the
Xcomponents and split points.  For example, given the definition
X@ID @Code {
X"def @Section into { @SectionPlace&&preceding }"
X"    named @Title {}"
X"    right @Body"
X"{"
X"    15p @Font { @Title //0.7f }"
X"    //"
X"    @Body"
X"}"
X}
Xthe galley
X@ID @Code {
X"@Section"
X"    @Title { Introduction }"
X"{ This is a subject that really"
X"needs no introduction. }"
X}
Xbecomes
X@ID @Code {
X"Introduction"
X"//0.7f"
X"{}"
X"//"
X"This is a subject that really needs"
X"//1vx"
X"no introduction."
X}
Xwith four components.  If @Code "@Body" was preceded by @Code "|1.0c" in
Xthe definition, the result would be
X@ID @Code {
X"Introduction"
X"//0.7f"
X"{}"
X"//"
X"|1.0c { This is a subject that really needs //1vx no introduction. }"
X}
Xand now @Code "//1vx" is buried within one component and is not a
Xpotential split point.  In fact, in this case the broken paragraph as
Xa whole is enclosed in @@OneRow.  This highlights a deficiency of
XBasser Lout:  an indented paragraph cannot be split.
X@PP
XThe lines of a paragraph become separate components if the paragraph
Xoccupies an entire component before breaking; otherwise they are
Xenclosed in a @@OneRow symbol within one component.  The same is true of
Xincoming components of other galleys.  If a @@Galley symbol occupies an
Xentire component by the rules above, then the incoming components that
Xreplace it become components of their new home:
X@ID @Tab
X  @Fmta { @Col @Code A ! @Col lines @Break B ! @Col @Code C }
X{
X@Rowa
X   A {
X"An example"
X"//0.5c"
X"@Galley"
X"//0.5c"
X"@SomethingList"
X}
X  B {
X""
X@Eq { ==> }
X}
X   C {
X"An example"
X"//0.5c"
X"Incoming components"
X"//0.2c"
X"from some other galley"
X"//0.5c"
X"@SomethingList"
X}
X}
XOtherwise the incoming components are grouped within a @@OneRow symbol
Xand lie within one component.
X@PP
XThis distinction has a marked effect on the vertical concatenation
Xb.unit.use @SubIndex { use in @Code "//1.1b" }
Xsymbol {@Code "//1.1b"}, which calls for more space than is available
X(Section {@NumberOf concatenation}).  There is no room for this symbol
Xwithin any component, so it will force a split and be discarded in that
Xcase.  But it can be promoted to between two components.
X@PP
XComponents may be separated by @Code "/" as well as by {@Code "//"},
Xgiving rise to column mark alignment between adjacent components:
X@ID @ShowVMark {
X@HContract @GreyBox { 1c @Wide ^| 1c @Wide 0.6c @High }
X/0.3c
X@HContract @GreyBox { 2c @Wide 0.6c @High }
X/0.3c
X@HContract @GreyBox { 0.5c @Wide ^| 0.8c @Wide 0.6c @High }
X}
XWhen aligned components are promoted into different targets, the meaning
Xof alignment becomes very doubtful.  For example, what if the targets
Xmark.alignment.in.detail @SubIndex { in detail }
Xare in different columns of one page, or what if one lies within
X{@Code "90d @Rotate"}?
X@PP
XThe truth is that @Code "/" causes all the objects that share a mark to
Xhave equal width:
X@ID @ShowVMark {
X@Box @HContract @GreyBox { 1c @Wide ^| 1c @Wide 0.6c @High }
X/0.3c
X@Box @HContract @GreyBox { 2c @Wide 0.6c @High }
X/0.3c
X@Box @HContract @GreyBox { 0.5c @Wide ^| 0.8c @Wide 0.6c @High }
X}
XThis is a consequence of the `as wide as possible' rule (Section
X{@NumberOf size}).  Mark alignment occurs {@I incidentally}, whenever
Xthe fragments are placed into similar contexts.
X@PP
XIn this connection we must also consider the special case of a @@Galley
Xsymbol which shares its column mark with some other object:
X@ID @Code {
X"@Galley"
X"/0.2c"
X"@SomethingList"
X}
X(The @@Galley may or may not occupy an entire component; that doesn't
Xmatter here.)  If incoming components are separated by @Code "//" rather
Xthan by {@Code "/"}, the meaning is so doubtful that this is forbidden.  In
Xfact, a galley whose components replace such a @@Galley must have a
Xsingle column mark running its full length; that is, its components must
Xall share a single column mark.  This mark will be merged with the
Xcolumn mark passing through each @@Galley that these components replace;
Xall the objects on the resulting merged mark will have equal width.
X@PP
XThe root galley, where everything collects immediately prior to output,
Xroot.galley.in.detail @SubIndex { in detail }
Xis created automatically, not by a definition.  Its target is the output
Xfile, and its object is the entire input, which typically looks like this:
X@ID @Code {
X"@PageList"
X"//"
X"@Text {"
X"  Body text of the document ..."
X"}"
X}
Xwhere @Code "@PageList" expands to a sequence of pages containing
X@Code "@TextPlace" symbols (see Section {@NumberOf definitions}), and
X@Code "@Text" is a galley:
X@ID @Code {
X"def @TextPlace { @Galley }"
X""
X"def @Text into { @TextPlace&&preceding }"
X"    right x"
X"{"
X"    x"
X"}"
X}
XThe spot vacated by a galley -- its invocation point -- becomes a @@Null
Xobject, so this root galley is effectively @Code "@PageList" alone, as
Xrequired.  The @Code "@Text" galley will find its first target preceding
Xits invocation point, within {@Code "@PageList"}.
X@PP
XPrinting {@PageMark rootg} the root galley on the output file is somewhat problematical,
Xroot.galley.printing @SubIndex { printing of }
Xbecause Lout has no way of knowing how large the paper is.  Basser Lout
Xsimply prints one root galley component per page (except it skips
Xcomponents of height zero), and the user is responsible for ensuring
Xthat each component is page-sized.
X@PP
XBasser Lout will promote a component only after any receptive symbols
Xcomponents.promotion @SubIndex { promotion of }
Xpromotion @Index { Promotion of components }
Xwithin it have been replaced, either by galleys or by @@Null, since
Xuntil then the component is not complete.  A component which shares a
Xmark with following components is held up until they are all complete,
Xsince until then their width is uncertain.
X@PP
XConsider a page with @Code "@TextPlace" and @Code "@FootSect" receptive
Xsymbols.  The rule just given will prevent the page from being printed
Xuntil @Code "@TextPlace" is replaced by body text, quite rightly; but
X@Code "@FootSect" will also prevent its printing, even when there are no
Xfootnotes.
X@PP
XBasser Lout is keen to write out pages as soon as possible, to save memory,
Xand it cannot afford to wait forever for non-existent footnotes.  A variant
Xof the galley concept, called a {@I {forcing galley}},
Xforcing.galley @Index { Forcing galley } {@PageMark forcing}
Xis introduced to solve this problem.  A forcing galley is defined like this:
X@ID @Code {
X"def @Text force into { @TextPlace&&preceding }"
X"   ..."
X}
Xand so on.  When such a galley replaces a @@Galley symbol, Lout replaces
Xevery receptive symbol preceding the @@Galley by @@Null, thus ensuring that
Xas soon as text enters a page, for example, everything up to and including
Xthe preceding page can be printed.  This does not take care of the very last
Xpage, but Basser Lout replaces all receptive symbols by @@Null when it realizes
Xthat its input has all been read, thus allowing the last page to print.
X@PP
XA forcing galley causes the Third Law to be applied earlier than
Xexpected, and this creates two problems.  First, the replacement by
X@@Null may be premature:  a galley may turn up later wanting one of the
Xdefunct targets.  Such galleys (entries in tables of contents are
Xtypical examples) are copied into the cross reference database and read
Xin during the next run just before their targets are closed, and so they
Xfind their targets in the end.  Care must be taken to ensure that
Xlarge galleys such as chapters and sections do not have defunct targets,
Xsince the cost of copying them to and from the database is unacceptably high.
X@PP
XA @Code "following" galley may fail to find a first target lying in a
Xfollowing component of the same galley as its invocation point.  This is
Xa deficiency of Basser Lout, which occurs if the target has not been
Xread from input at the time the galley tries to find it.  A workaround
Xis to use a @Code "preceding" galley instead, defined like this:
X@ID @Code {
X"def @AGalley into { @AGalleyPlace&&preceding }"
X"    right @Body"
X"{"
X"    //1.1b"
X"    @Body"
X"}"
X}
Xand invoked like this:
X@ID @Code {
X"@AGalleyPlace | @AGalley { content of galley }"
X"//"
X"..."
X"@AGalleyPlace"
X}
XThe first @Code "@AGalleyPlace" receives only the initial empty object,
Xsince the @Code "//1.1b" forces a split; and the Second Law puts Basser
XLout on the right track thereafter.
X@End @Section
END_OF_FILE
  if test 9965 -ne `wc -c <'lout/doc/tr.lout/ch2.06'`; then
    echo shar: \"'lout/doc/tr.lout/ch2.06'\" unpacked with wrong size!
  fi
  # end of 'lout/doc/tr.lout/ch2.06'
fi
if test -f 'lout/doc/tr.lout/ch4.03' -a "${1}" != "-c" ; then
  echo shar: Will not clobber existing file \"'lout/doc/tr.lout/ch4.03'\"
else
  echo shar: Extracting \"'lout/doc/tr.lout/ch4.03'\" \(9416 characters\)
  sed "s/^X//" >'lout/doc/tr.lout/ch4.03' <<'END_OF_FILE'
X@Section
X   @Title { Page layout }
X   @Tag { pagelayout }
X@Begin
X@PP
XThe page layout
Xpage.layout.inpractice @SubIndex { in practice }
Xdocument.layout.page.layout. @SubIndex { page layout }
Xdefinitions given in Section {@NumberOf definitions},
Xalthough correct, are very basic.  In this section we present the
Xdefinitions used by the DocumentLayout package for laying out the pages
Xof books, including running page headers and footers, different formats
Xfor odd and even pages, and so on.  The present document is produced with
Xthese definitions.
X@PP
XWe begin with a few definitions which permit the user to create cross
Xreferences of the `see page 27' variety which will be kept up to date
Xautomatically.  The user marks the target page by placing
X@Code {"@PageMark intro"}, for example, at the point of interest, and
Xrefers to the marked page as @Code "@PageOf intro" elsewhere:
Xpageof.example @Index { @Code "@PageOf" example }
X@IndentedList
X@LI @Code {
X"export @Tag"
X"def @PageMarker right @Tag { @Null }"
X}
X@LI @Code {
X"def @PageMark right x"
X"{"
X"    @PageMarker&&preceding @Tagged x"
X"}"
X}
X@LI @Code {
X"def @PageOf right x"
X"{"
X"    @PageMarker&&x @Open { @Tag }"
X"}"
X}
X@EndList
XWe will see below that an invocation of @Code "@PageMarker" appears before
Xeach page, with @Code "@Tag" parameter equal to the
Xpage number.  Suppose that {@Code "@PageMark intro"}, which expands to
X@ID @Code "@PageMarker&&preceding @Tagged intro"
Xhappens to fall on page 27 of the final printed document (of course, its
Xvalue is @@Null which makes it invisible).  Then the effect of @@Tagged
Xis to attach @Code "intro" as an extra tag to the first invocation of
X{@Code "@PageMarker"} preceding that final point, and this must be
X{@Code "@PageMarker 27"}.  Therefore the expression
X@ID @Code "@PageMarker&&intro @Open { @Tag }"
Xwill open the invocation {@Code "@PageMarker 27"} and yield the value of
Xits @Code "@Tag" parameter, 27.  Thus, {@Code "@PageOf intro"} appearing
Xanywhere in the document yields 27.
X@PP
XNext we have some little definitions for various parts of the
Xpage.  {@Code "@FullPlace"} will be the target of full-width body text:
X@ID @Code {
X"def @FullPlace { @Galley }"
X}
X{@Code "@ColPlace"} will be the target of body text within one column:
X@ID @Code {
X"def @ColPlace { @Galley }"
X}
X{@Code "@TopList"} will be the target of figures and tables:
X@ID @Code {
X"export @Tag"
X"def @TopList right @Tag"
X"{"
X"    @Galley"
X"    //@TopGap @TopList @Next @Tag"
X"}"
X}
XWe have taken a shortcut here, avoiding an unnecessary @Code "@TopPlace"
Xsymbol.  @Code "@FootList" and {@Code "@FootSect"} define a sequence of
Xfull-width targets at the foot of the page for footnotes,
Xpreceded by a short horizontal line:
Xfootsect.example @Index { @Code "@FootSect" example }
X@IndentedList
X@LI @Code {
X"export @Tag"
X"def @FootList right @Tag"
X"{"
X"    @Galley"
X"    //@FootGap  @FootList @Next @Tag"
X"}"
X}
X@LI @Code {
X"def @FootSect"
X"{"
X"    @FootLen @Wide @HLine"
X"    //@FootGap  @FootList 1  ||@FootLen"
X"}"
X}
X@EndList
XSimilarly, @Code "@ColFootList" and @Code "@ColFootSect" provide a
Xsequence of targets for footnotes within one column:
X@ID @Code {
X"export @Tag"
X"def @ColFootList right @Tag"
X"{"
X"    @Galley"
X"    //@FootGap  @ColFootList @Next @Tag"
X"}"
X""
X"def @ColFootSect"
X"{"
X"    @ColFootLen @Wide @HLine"
X"    //@FootGap  @ColFootList 1  ||@ColFootLen"
X"}"
X}
XThe next definition provides a horizontal sequence of one or more columns:
Xcollist.example @Index { @Code "@ColList" example }
X@ID @Code {
X"def @ColList right col"
X"{"
X"    def @Column"
X"    {  @VExpand { @ColPlace //1rt @OneRow { //@MidGap @ColFootSect } }  }"
X""
X"    col @Case {"
X"        Single @Yield @Column"
X"        Double @Yield { @DoubleColWidth @Wide @Column  ||@ColGap  @ColList col }"
X"        Multi  @Yield { @MultiColWidth @Wide @Column  ||@ColGap  @ColList col }"
X"    }"
X"}"
X}
XEach column consists of a @Code "@ColPlace" at the top and a
X@Code "@FootSect" at the foot.  The @@VExpand symbol ensures that
Xwhenever a column comes into existence, it will expand vertically so
Xthat the bottom-justification @Code "//1rt" has as much space as
Xpossible to work within.  The @Code "col" parameter determines whether
Xthe result has a single column, double columns, or multiple columns.
X@PP
XThe {@Code "@Page"} symbol places its parameter in a page of fixed width,
Xheight, and margins:
Xpage.example @Index { @Code "@Page" example }
X@ID @Code {
X"def @Page right x"
X"{"
X"    @PageWidth @Wide @PageHeight @High {"
X"        //@PageMargin  ||@PageMargin"
X"        @HExpand @VExpand x"
X"        ||@PageMargin  //@PageMargin"
X"    }"
X"}"
X}
X@@HExpand and @@VExpand ensure that the right parameter occupies all the
Xavailable space; this is important when the right parameter is unusually
Xsmall.  The @@High symbol gives the page a single row mark, ensuring that
Xit will be printed on a single sheet of paper (page {@PageOf rootg}).
X@PP
XNext we have {@Code "@OnePage"}, defining a typical page of a book or
Xother document:
Xonepage.example @Index { @Code "@OnePage" example }
X@ID @Code {
X"def @OnePage"
X"    named @Columns {}"
X"    named @PageTop {}"
X"    named @PageFoot {}"
X"{"
X"    @Page {"
X"        @PageTop"
X"        //@MidGap  @TopList"
X"        //@MidGap  @FullPlace"
X"        //@MidGap  @ColList @Columns"
X"        // //1rt   @OneRow { //@MidGap @FootSect //@MidGap @PageFoot }"
X"    }"
X"}"
X}
XThe page top and page foot, and the number of columns, are parameters
Xthat will be given later when @Code "@OnePage" is invoked.  The body of
Xthe page is a straightforward combination of previous definitions.  The
X@Code "//" symbol protects the following @Code "//1rt" from deletion in
Xthe unlikely event that all the preceding symbols are replaced by
X@@Null.  The following object is enclosed in @@OneRow to ensure that
Xall of it is bottom-justified, not just its first component.
X@PP
XBefore presenting the definition of a sequence of pages, we must detour
Xto describe how running page headers and footers (like those in the
Xpresent document) are produced.  These are based on the
X@Code "@Runner" symbol:
Xrunner.example @Index { @Code "@Runner" example }
X@ID @Code {
X"export @TopOdd @TopEven @FootOdd @FootEven"
X"def @Runner"
X"    named @TopOdd right @PageNum { @Null }"
X"    named @TopEven right @PageNum { @Null }"
X"    named @FootOdd right @PageNum { @Null }"
X"    named @FootEven right @PageNum { @Null }"
X"    named @Tag {}"
X"{ @Null }"
X}
XThe four parameters control the format of running headers and footers on
Xodd and even pages respectively.  Invocations of {@Code "@Runner"}, for
Xexample
X@ID @Code {
X"@Runner"
X"    @TopEven { @B @PageNum |1rt @I { Chapter 4 } }"
X"    @TopOdd  { @I { Examples }   |1rt @B @PageNum }"
X}
Xwill be embedded in the body text of the document, and, as we will see
Xin a moment, are accessed by @Code "@Runner&&following" cross references
Xon the pages.  Notice how the @Code "@PageNum" parameter of each
Xparameter allows the format of the running header to be specified while
Xleaving the page number to be substituted later.
X@PP
XWe may now define {@Code "@OddPageList"}, whose result is a sequence of
Xpages beginning with an odd-numbered page:
Xoddpagelist.example @Index { @Code "@OddPageList" example }
X@ID @Code {
X"def @OddPageList"
X"    named @Columns {}"
X"    right @PageNum"
X"{"
X"    def @EvenPageList ..."
X""
X"        @PageMarker @PageNum"
X"    //  @Runner&&following @Open {"
X"            @OnePage"
X"                @Columns { @Columns }"
X"                @PageTop { @TopOdd @PageNum }"
X"                @PageFoot { @FootOdd @PageNum }"
X"        }"
X"    //  @EvenPageList"
X"            @Columns { @Columns }"
X"            @Next @PageNum"
X"}"
X}
XIgnoring @Code "@EvenPageList" for the moment, notice first that the
Xinvocation of @Code "@OnePage" is enclosed in
X{@Code "@Runner&&following @Open"}.  Since {@Code "@Runner&&following"}
Xrefers to the first invocation of @Code "@Runner" appearing after itself
Xin the final printed document, the symbols @Code "@TopOdd" and
X@Code "@FootOdd" will take their value from the first invocation of
X@Code "@Runner" following the top of the page, even though @Code "@FootOdd"
Xappears at the foot of the page.  Their @Code "@PageNum" parameters are
Xreplaced by {@Code "@PageNum"}, the actual page number parameter of
X{@Code "@OddPageList"}.
X@PP
XAfter producing the odd-numbered page, @Code "@OddPageList" invokes
X{@Code "@EvenPageList"}:
Xevenpagelist.example @Index { @Code "@EvenPageList" example }
X@ID @Code {
X"def @EvenPageList"
X"    named @Columns {}"
X"    right @PageNum"
X"{"
X"        @PageMarker @PageNum"
X"    //  @Runner&&following @Open {"
X"            @OnePage"
X"                @Columns { @Columns }"
X"                @PageTop { @TopEven @PageNum }"
X"                @PageFoot { @FootEven @PageNum }"
X"        }"
X"    //  @OddPageList"
X"            @Columns { @Columns }"
X"            @Next @PageNum"
X"}"
X}
XThis produces an even-numbered page, then passes the ball back to
X@Code "@OddPageList" -- a delightful example of what computer
Xscientists call mutual recursion.  The two page types differ only in
Xtheir running headers and footers, but other changes could easily be made.
X@PP
XIt was foreshadowed earlier that an invocation of @Code "@PageMarker"
Xwould precede each page, and this has been done.  Although this @Code
X"@PageMarker" is a component of the root galley, it will not cause a
Xpage to be printed, because Basser Lout skips components of height zero.
X@End @Section
END_OF_FILE
  if test 9416 -ne `wc -c <'lout/doc/tr.lout/ch4.03'`; then
    echo shar: \"'lout/doc/tr.lout/ch4.03'\" unpacked with wrong size!
  fi
  # end of 'lout/doc/tr.lout/ch4.03'
fi
if test -f 'lout/makefile' -a "${1}" != "-c" ; then
  echo shar: Will not clobber existing file \"'lout/makefile'\"
else
  echo shar: Extracting \"'lout/makefile'\" \(8738 characters\)
  sed "s/^X//" >'lout/makefile' <<'END_OF_FILE'
X
X###################################################################
X#                                                                 #
X#  Make file for installing Lout Version 2.03                     #
X#                                                                 #
X#  Jeffrey H. Kingston                                            #
X#  23 April 1993                                                  #
X#                                                                 #
X#     make lout        Compile the Lout source                    #
X#     make install     Install the Lout binary and libraries and  #
X#                      perform a compulsory initial run           #
X#     make installman  Install the Lout manual entry              #
X#     make installdoc  Install the Lout documentation             #
X#     make clean       Remove compilation temporaries             #
X#     make clobber     Undo the effect of `make lout'             #
X#     make uninstall   Undo the effect of `make install',         #
X#                      `make installman', and `make installdoc'   #
X#                                                                 #
X#  Most installations of Lout should require no more than the     #
X#  following steps.                                               #
X#                                                                 #
X#  (1) Set the following five macros defined below to appropriate #
X#      values.  The macros are                                    #
X#                                                                 #
X#         LATIN        Set this to 1 if the ISO-LATIN-1 character #
X#                      set is to be used (i.e. for non-English    #
X#                      languages), or 0 for ASCII (i.e. English). #
X#                      This has two effects: it changes the       #
X#                      lexical analyser in the lout binary so     #
X#                      as to recognize ISO-LATIN-1 characters,    #
X#                      and it changes the directory that the Lout #
X#                      font files are copied from during install  #
X#                      so that Latin .AFM files are used.  It     #
X#                      has no effect on hyphenation.              #
X#                                                                 #
X#                      At the time of writing the Latin font      #
X#                      directory is empty and the changes to the  #
X#                      lexical analyser are not implemented; but  #
X#                      someday someone will fill in these gaps.   #
X#                                                                 #
X#         BINDIR       The directory where the Lout binary goes   #
X#                      (this directory is assumed to exist)       #
X#                                                                 #
X#         LIBDIR       Directory where the Lout libraries go      #
X#                      (this directory will be created)           #
X#                                                                 #
X#         DOCDIR       Directory where the Lout documents go;     #
X#                      they are tech. reports written in Lout     #
X#                      describing various parts of the system     #
X#                      (this directory will be created)           #
X#                                                                 #
X#         MANDIR       Directory where Lout manual entry goes;    #
X#                      it has the form of input to nroff -man     #
X#                      (this directory is assumed to exist)       #
X#                                                                 #
X#  (2) Execute "make lout".  This will compile the Lout source    #
X#      code and leave the binary in this directory.  No changes   #
X#      will be made in any other directories.                     #
X#                                                                 #
X#  (3) Execute "make install".  This will (a) copy the Lout       #
X#      binary into directory BINDIR; (b) create LIBDIR and copy   #
X#      all the library files into it; and finally (c) perform a   #
X#      test run on the document stored in ./doc/tr.eq.  This test #
X#      is compulsory because it has side effects: the database    #
X#      index files loutrefs.li, refstyles.li, and standard.li     #
X#      are created in directory $(LIBDIR)/data, and the packed    #
X#      hyphenation pattern file lout.hyph.packed is created in    #
X#      directory $(LIBDIR)/include.  The test run will produce    #
X#      quite a few warning messages about unresolved cross        #
X#      references, but there should be no fatal errors.  (These   #
X#      warning messages gradually go away on subsequent runs.)    #
X#                                                                 #
X#  (4) Execute "make installman".  This installs the manual       #
X#      entry in directory $(MANDIR).                              #
X#                                                                 #
X#  (5) Execute "make installdoc".  This creates $(DOCDIR) and     #
X#      copies the tech. reports into it.                          #
X#                                                                 #
X#  (6) Execute "make clobber".  This undoes "make lout".          #
X#                                                                 #
X#  You probably also want to change the default values of the     #
X#  @PageWidth and @PageHeight parameters of the DocumentLayout    #
X#  package, if you are using something other than A4 paper.       #
X#  These are found on lines 154-5 of file $(LIBDIR)/include/dl.   #
X#  Set them to the physical width and height of your paper; for   #
X#  example, 29.70c is 29.7 centimetres, the A4 height.            #
X#                                                                 #
X#  Mail [e-mail] if you have any problems.                #
X#                                                                 #
X###################################################################
X
XLATIN    = 0
XBINDIR    = /usr/local/bin
XLIBDIR    = /usr/local/lib/lout
XDOCDIR    = /usr/local/lib/lout.doc
XMANDIR    = /usr/local/man/man1
X
XCFLAGS    = -DFONT_DIR=\"$(LIBDIR)/font$(LATIN)\"            \
X      -DINCL_DIR=\"$(LIBDIR)/include\"            \
X      -DDATA_DIR=\"$(LIBDIR)/data\"                \
X      -DLATIN=$(LATIN)                    \
X      -DDEBUG_ON=0                        \
X      -DASSERT_ON=1
X
XOBJS    = z01.o z02.o z03.o z04.o z05.o z06.o z07.o        \
X      z08.o z09.o z10.o z11.o z12.o z13.o z14.o        \
X      z15.o z16.o z17.o z18.o z19.o z20.o z21.o        \
X      z22.o z23.o z24.o z25.o z26.o z27.o z28.o        \
X      z29.o z30.o z31.o z32.o z33.o z34.o z35.o z36.o
X
Xlout:    $(OBJS)
X    $(CC) -o lout $(OBJS) -lm
X    chmod a+x lout
X
X$(OBJS): externs
X
Xexterns:
X
Xinstall: lout
X    @echo ""
X    @echo "Copying Lout binary to BINDIR"
X    cp lout $(BINDIR)/lout
X    chmod a+x-w $(BINDIR)/lout
X    @echo ""
X    @echo "Creating LIBDIR and copying library files"
X    mkdir $(LIBDIR)
X    chmod 775 $(LIBDIR)
X    mkdir $(LIBDIR)/include
X    chmod 775 $(LIBDIR)/include
X    mkdir $(LIBDIR)/data
X    chmod 775 $(LIBDIR)/data
X    mkdir $(LIBDIR)/font$(LATIN)
X    chmod 775 $(LIBDIR)/font$(LATIN)
X    cp include/* $(LIBDIR)/include
X    chmod a+r-wx $(LIBDIR)/include/*
X    cp data/* $(LIBDIR)/data
X    chmod a+r-wx $(LIBDIR)/data/*
X    cp font$(LATIN)/* $(LIBDIR)/font$(LATIN)
X    chmod a+r-wx $(LIBDIR)/font$(LATIN)/*
X    @echo ""
X    @echo "Compulsory test run on doc/tr.eq (expect many non-fatal error messages)"
X    ./lout ./doc/tr.eq/setup ./doc/tr.eq/s? > ./doc/tr.eq/op
X    rm ./doc/tr.eq/op ./doc/tr.eq/s?.ld lout.li
X
Xinstallman:
X    sed -e "s@<BINDIR>@$(BINDIR)@" -e "s@<LIBDIR>@$(LIBDIR)@"    \
X        -e "s@<DOCDIR>@$(DOCDIR)@" -e "s@<MANDIR>@$(MANDIR)@"    \
X    man/lout.1 > $(MANDIR)/lout.1
X    chmod a+r $(MANDIR)/lout.1
X
Xinstalldoc:
X    mkdir $(DOCDIR)
X    chmod 775 $(DOCDIR)
X    mkdir $(DOCDIR)/tr.lout
X    chmod 775 $(DOCDIR)/tr.lout
X    cp doc/tr.lout/* $(DOCDIR)/tr.lout
X    chmod a+r-wx $(DOCDIR)/tr.lout/*
X    mkdir $(DOCDIR)/tr.impl
X    chmod 775 $(DOCDIR)/tr.impl
X    cp doc/tr.impl/* $(DOCDIR)/tr.impl
X    chmod a+r-wx $(DOCDIR)/tr.impl/*
X    mkdir $(DOCDIR)/tr.over
X    chmod 775 $(DOCDIR)/tr.over
X    cp doc/tr.over/* $(DOCDIR)/tr.over
X    chmod a+r-wx $(DOCDIR)/tr.over/*
X    mkdir $(DOCDIR)/tr.begin
X    chmod 775 $(DOCDIR)/tr.begin
X    cp doc/tr.begin/* $(DOCDIR)/tr.begin
X    chmod a+r-wx $(DOCDIR)/tr.begin/*
X    mkdir $(DOCDIR)/tr.eq
X    chmod 775 $(DOCDIR)/tr.eq
X    cp doc/tr.eq/*   $(DOCDIR)/tr.eq
X    chmod a+r-wx $(DOCDIR)/tr.eq/*
X    mkdir $(DOCDIR)/tr.fig
X    chmod 775 $(DOCDIR)/tr.fig
X    cp doc/tr.fig/*  $(DOCDIR)/tr.fig
X    chmod a+r-wx $(DOCDIR)/tr.fig/*
X    mkdir $(DOCDIR)/tr.tab
X    chmod 775 $(DOCDIR)/tr.tab
X    cp doc/tr.tab/*  $(DOCDIR)/tr.tab
X    chmod a+r-wx $(DOCDIR)/tr.tab/*
X
Xuninstall:
X    -rm -f  $(BINDIR)/lout
X    -rm -fr $(LIBDIR)
X    -rm -fr $(DOCDIR)
X    -rm -f  $(MANDIR)/lout.1
X
Xclean:
X    rm -f *.o
X
Xclobber: clean
X    rm -f lout
END_OF_FILE
  if test 8738 -ne `wc -c <'lout/makefile'`; then
    echo shar: \"'lout/makefile'\" unpacked with wrong size!
  fi
  # end of 'lout/makefile'
fi
if test -f 'lout/z30.c' -a "${1}" != "-c" ; then
  echo shar: Will not clobber existing file \"'lout/z30.c'\"
else
  echo shar: Extracting \"'lout/z30.c'\" \(8790 characters\)
  sed "s/^X//" >'lout/z30.c' <<'END_OF_FILE'
X/*@z30.c:Symbol uses:InsertUses(), FlattenUses(), SearchUses()@***************/
X/*                                                                           */
X/*  LOUT: A HIGH-LEVEL LANGUAGE FOR DOCUMENT FORMATTING (VERSION 2.03)       */
X/*  COPYRIGHT (C) 1993 Jeffrey H. Kingston                                   */
X/*                                                                           */
X/*  Jeffrey H. Kingston ([e-mail])                                   */
X/*  Basser Department of Computer Science                                    */
X/*  The University of Sydney 2006                                            */
X/*  AUSTRALIA                                                                */
X/*                                                                           */
X/*  This program is free software; you can redistribute it and/or modify     */
X/*  it under the terms of the GNU General Public License as published by     */
X/*  the Free Software Foundation; either version 1, or (at your option)      */
X/*  any later version.                                                       */
X/*                                                                           */
X/*  This program is distributed in the hope that it will be useful,          */
X/*  but WITHOUT ANY WARRANTY; without even the implied warranty of           */
X/*  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the            */
X/*  GNU General Public License for more details.                             */
X/*                                                                           */
X/*  You should have received a copy of the GNU General Public License        */
X/*  along with this program; if not, write to the Free Software              */
X/*  Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.                */
X/*                                                                           */
X/*  FILE:         z30.c                                                      */
X/*  MODULE:       Symbol Uses                                                */
X/*  EXTERNS:      InsertUses(), FlattenUses(), SearchUses(), TargetUsedBy()  */
X/*                                                                           */
X/*****************************************************************************/
X#include "externs"
X
X
X/*****************************************************************************/
X/*                                                                           */
X/*  InsertUses(x, y)                                                         */
X/*                                                                           */
X/*  Record the fact that symbol x uses symbol y, by linking them.            */
X/*  Increment count of the number of times y is used, if y is a parameter.   */
X/*                                                                           */
X/*****************************************************************************/
X
XInsertUses(x, y)
XOBJECT x, y;
X{ OBJECT tmp;
X  debug2(DSU, D, "InsertUses( %s, %s )", SymName(x), SymName(y));
X  if( type(x) == LOCAL && type(y) == LOCAL && !predefined(y) )
X  { tmp = GetMem(USES_SIZE, no_fpos);  item(tmp) = y;
X    if( base_uses(x) == nil )  next(tmp) = tmp;
X    else next(tmp) = next(base_uses(x)), next(base_uses(x)) = tmp;
X    base_uses(x) = tmp;
X  }
X  if( is_par(type(y)) )
X  { uses_count(y) += (enclosing(y) == x ? 1 : 2);
X    if( dirty(y) || uses_count(y) > 1 )  dirty(enclosing(y)) = TRUE;
X  }
X  else if( sym_body(y) == nil || dirty(y) )  dirty(x) = TRUE;
X  debug5(DSU, D, "InsertUses returning ( %s %s; %s %s, count = %d )",
X    SymName(x), (dirty(x) ? "dirty" : "clean"),
X    SymName(y), (dirty(y) ? "dirty" : "clean"), uses_count(y));
X} /* end InsertUses */
X
X
X/*****************************************************************************/
X/*                                                                           */
X/*  static gather_uses(x, sym)                                               */
X/*  static gather_all_uses(x)                                                */
X/*                                                                           */
X/*  gather_uses adds all the unmarked descendants of x to the uses relation  */
X/*  of sym;  gather_all_uses applies gather_uses to all descendants of x.    */
X/*                                                                           */
X/*****************************************************************************/
X
Xstatic gather_uses(x, sym)
XOBJECT x, sym;
X{ OBJECT link, y, tmp;
X  if( base_uses(x) != nil )
X  { link = next(base_uses(x));
X    do
X    { y = item(link);
X      if( marker(y) != sym )
X      {    if( y != sym )
X    { marker(y) = sym;
X      tmp = GetMem(USES_SIZE, no_fpos);  item(tmp) = y;
X      if( uses(sym) == nil )  next(tmp) = tmp;
X      else next(tmp) = next(uses(sym)), next(uses(sym)) = tmp;
X      uses(sym) = tmp;
X      if( indefinite(y) )  indefinite(sym) = TRUE;
X      if( uses_extern_target(y) )  uses_extern_target(sym) = TRUE;
X      gather_uses(y, sym);
X    }
X    else recursive(sym) = TRUE;
X      }
X      link = next(link);
X    } while( link != next(base_uses(x)) );
X  }
X} /* end gather_uses */
X
X
Xstatic gather_all_uses(x)
XOBJECT x;
X{ OBJECT link, y;
X  for( link = Down(x);  link != x;  link = NextDown(link) )
X  { Child(y, link);
X    if( type(y) == LOCAL )  gather_uses(y, y);
X    gather_all_uses(y);
X  }
X} /* end gather_all_uses */
X
X
X/*@@**************************************************************************/
X/*                                                                           */
X/*  FlattenUses()                                                            */
X/*                                                                           */
X/*  Traverse the directed graph assembled by InsertUses, finding its         */
X/*  transitive closure and storing this explicitly in uses(x) for all x.     */
X/*                                                                           */
X/*****************************************************************************/
X
XFlattenUses()
X{ gather_all_uses(StartSym);
X} /* end FlattenUses */
X
X
X/*****************************************************************************/
X/*                                                                           */
X/*  BOOLEAN SearchUses(x, y)                                                 */
X/*                                                                           */
X/*  Determine whether symbol x uses symbol y by searching x's uses list.     */
X/*                                                                           */
X/*****************************************************************************/
X
XBOOLEAN SearchUses(x, y)
XOBJECT x, y;
X{ OBJECT p;
X  debug3(DSU, DD, "SearchUses(%s, %s) uses: %d", SymName(x),SymName(y),uses(x));
X  if( x == y )  return TRUE;
X  if( uses(x) != nil )
X  { p = next(uses(x));
X    do
X    { debug1(DSU, DDD, "  checking %s", SymName(item(p)));
X      if( item(p) == y )  return TRUE;
X      p = next(p);
X    } while( p != next(uses(x)) );
X  }
X  return FALSE;
X} /* end SearchUses */
X
X
X/*****************************************************************************/
X/*                                                                           */
X/*  OBJECT FirstExternTarget(sym, cont)                                      */
X/*  OBJECT NextExternTarget(sym, cont)                                       */
X/*                                                                           */
X/*  Together these two procedures return all symbols which are both used by  */
X/*  sym and a target for at least one external galley.  Return nil at end.   */
X/*                                                                           */
X/*****************************************************************************/
X
XOBJECT FirstExternTarget(sym, cont)
XOBJECT sym, *cont;
X{ OBJECT res;
X  debug1(DSU, D, "FirstExternTarget( %s )", SymName(sym));
X  res = nil;  *cont = nil;
X  if( is_extern_target(sym) )  res = sym;
X  else if( uses(sym) != nil )
X  { *cont = next(uses(sym));
X    do
X    { if( is_extern_target(item(*cont)) )
X      {    res = item(*cont);
X    break;
X      }
X      *cont = next(*cont);
X    } while( *cont != next(uses(sym)) );
X  }
X  debug1(DSU, D, "FirstExternTarget returning %s", SymName(res));
X  return res;
X} /* end FirstExternTarget */
X
XOBJECT NextExternTarget(sym, cont)
XOBJECT sym, *cont;
X{ OBJECT res;
X  debug1(DSU, D, "NextExternTarget( %s )", SymName(sym));
X  res = nil;
X  if( *cont != nil )
X  { *cont = next(*cont);
X    while( *cont != next(uses(sym)) )
X    { if( is_extern_target(item(*cont)) )
X      {    res = item(*cont);
X    break;
X      }
X      *cont = next(*cont);
X    }
X  }
X  debug1(DSU, D, "NextExternTarget returning %s", SymName(res));
X  return res;
X} /* end NextExternTarget */
END_OF_FILE
  if test 8790 -ne `wc -c <'lout/z30.c'`; then
    echo shar: \"'lout/z30.c'\" unpacked with wrong size!
  fi
  # end of 'lout/z30.c'
fi
if test -f 'lout/z31.c' -a "${1}" != "-c" ; then
  echo shar: Will not clobber existing file \"'lout/z31.c'\"
else
  echo shar: Extracting \"'lout/z31.c'\" \(9723 characters\)
  sed "s/^X//" >'lout/z31.c' <<'END_OF_FILE'
X/*@z31.c:Memory Allocator:zz_free[], GetMemory() etc.@************************/
X/*                                                                           */
X/*  LOUT: A HIGH-LEVEL LANGUAGE FOR DOCUMENT FORMATTING (VERSION 2.03)       */
X/*  COPYRIGHT (C) 1993 Jeffrey H. Kingston                                   */
X/*                                                                           */
X/*  Jeffrey H. Kingston ([e-mail])                                   */
X/*  Basser Department of Computer Science                                    */
X/*  The University of Sydney 2006                                            */
X/*  AUSTRALIA                                                                */
X/*                                                                           */
X/*  This program is free software; you can redistribute it and/or modify     */
X/*  it under the terms of the GNU General Public License as published by     */
X/*  the Free Software Foundation; either version 1, or (at your option)      */
X/*  any later version.                                                       */
X/*                                                                           */
X/*  This program is distributed in the hope that it will be useful,          */
X/*  but WITHOUT ANY WARRANTY; without even the implied warranty of           */
X/*  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the            */
X/*  GNU General Public License for more details.                             */
X/*                                                                           */
X/*  You should have received a copy of the GNU General Public License        */
X/*  along with this program; if not, write to the Free Software              */
X/*  Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.                */
X/*                                                                           */
X/*  FILE:         z31.c                                                      */
X/*  MODULE:       Memory Allocator                                           */
X/*  EXTERNS:      zz_free[], GetMemory(), DebugMemory()                      */
X/*                                                                           */
X/*****************************************************************************/
X#include "externs"
X
X#define    MEM_CHUNK    1020        /* how many ALIGNs to get from sys   */
X
X
X#if DEBUG_ON
Xstatic    int    no_of_calls    = 0;    /* number of calls to calloc()       */
X    int    zz_newcount    = 0;    /* number of calls to New()          */
X    int    zz_disposecount    = 0;    /* number of calls to Dispose()      */
X
X/*****************************************************************************/
X/*                                                                           */
X/*  DebugMemory()                                                            */
X/*                                                                           */
X/*  Print memory usage.                                                      */
X/*                                                                           */
X/*****************************************************************************/
X
XDebugMemory()
X{ int i, j;  OBJECT p;
X  debug2(DMA, D, "calloc called %d times (%d bytes total)",
X    no_of_calls, no_of_calls * MEM_CHUNK * sizeof(ALIGN));
X  debug2(DMA, D, "New() called %d times;  Dispose() called %d times",
X    zz_newcount, zz_disposecount);
X  for( i = 0;  i < MAX_OBJECT_REC;  i++ )
X  { if( zz_free[i] != nil )
X    { j = 0;
X      for( p = zz_free[i];  p != nil;  p = pred(p, CHILD) )  j++;
X      debug2(DMA, DD, "zz_free[%2d]: %3d", i, j);
X    }
X  }
X} /* end DebugMemory */
X#endif
X
X
X/*****************************************************************************/
X/*                                                                           */
X/*  OBJECT         zz_free[], zz_hold, zz_tmp, zz_res                        */
X/*  int            zz_size                                                   */
X/*  unsigned char  zz_lengths[]                                              */
X/*                                                                           */
X/*  zz_free[i]:    free records of size i*sizeof(ALIGN).                     */
X/*  zz_lengths[i]: the number of ALIGNs in a record of type i.               */
X/*  These variables are used only within the New() and Dispose() macros,     */
X/*  and the list handling macros.                                            */
X/*                                                                           */
X/*****************************************************************************/
X
XOBJECT        zz_free[MAX_OBJECT_REC], zz_hold, zz_tmp, zz_res;
Xint        zz_size;
Xunsigned char    zz_lengths[DISPOSED];        /* DISPOSED is 1 + max type */
XOBJECT         xx_link, xx_tmp, xx_res, xx_hold;
X
X
X/*@@**************************************************************************/
X/*                                                                           */
X/*  MemInit()                                                                */
X/*                                                                           */
X/*  Initialise memory allocator.                                             */
X/*                                                                           */
X/*****************************************************************************/
X
XMemInit()
X{
X  zz_lengths[ WORD        ] = 0;
X  zz_lengths[ LINK        ] = ceiling( sizeof(struct link_type), sizeof(ALIGN));
X
X  /* object types, except closure NB have actual() field in token phase! */
X  zz_lengths[ SPLIT       ] =
X  zz_lengths[ HEAD        ] =
X  zz_lengths[ PAR         ] =
X  zz_lengths[ ROW_THR     ] =
X  zz_lengths[ COL_THR     ] =
X  zz_lengths[ CLOSURE     ] =
X  zz_lengths[ NULL_CLOS   ] =
X  zz_lengths[ CROSS       ] =
X  zz_lengths[ ONE_COL     ] =
X  zz_lengths[ ONE_ROW     ] =
X  zz_lengths[ WIDE        ] =
X  zz_lengths[ HIGH        ] =
X  zz_lengths[ HSCALE      ] =
X  zz_lengths[ VSCALE      ] =
X  zz_lengths[ HCONTRACT   ] =
X  zz_lengths[ VCONTRACT   ] =
X  zz_lengths[ HEXPAND     ] =
X  zz_lengths[ VEXPAND     ] =
X  zz_lengths[ PADJUST     ] =
X  zz_lengths[ HADJUST     ] =
X  zz_lengths[ VADJUST     ] =
X  zz_lengths[ ROTATE      ] =
X  zz_lengths[ SCALE       ] =
X  zz_lengths[ CASE        ] =
X  zz_lengths[ YIELD       ] =
X  zz_lengths[ FONT        ] =
X  zz_lengths[ SPACE       ] =
X  zz_lengths[ BREAK       ] =
X  zz_lengths[ NEXT        ] =
X  zz_lengths[ ENV         ] =
X  zz_lengths[ CLOS        ] =
X  zz_lengths[ LVIS        ] =
X  zz_lengths[ OPEN        ] =
X  zz_lengths[ TAGGED      ] =
X  zz_lengths[ INCGRAPHIC  ] =
X  zz_lengths[ SINCGRAPHIC ] =
X  zz_lengths[ GRAPHIC     ] =
X  zz_lengths[ ACAT        ] =
X  zz_lengths[ HCAT        ] =
X  zz_lengths[ VCAT        ] =
X  zz_lengths[ LBR         ] =
X  zz_lengths[ RBR         ] =
X  zz_lengths[ BEGIN       ] =
X  zz_lengths[ END         ] =
X  zz_lengths[ USE         ] =
X  zz_lengths[ DATABASE    ] =
X  zz_lengths[ SYS_DATABASE] =
X  zz_lengths[ GSTUB_NONE  ] =
X  zz_lengths[ GSTUB_INT   ] =
X  zz_lengths[ GSTUB_EXT   ] =
X  zz_lengths[ DEAD        ] =
X  zz_lengths[ UNATTACHED  ] =
X  zz_lengths[ RECEPTIVE   ] =
X  zz_lengths[ RECEIVING   ] =
X  zz_lengths[ RECURSIVE   ] =
X  zz_lengths[ PRECEDES    ] =
X  zz_lengths[ FOLLOWS     ] =
X  zz_lengths[ CROSS_FOLL  ] =
X  zz_lengths[ GALL_FOLL   ] =
X  zz_lengths[ CROSS_TARG  ] =
X  zz_lengths[ GALL_TARG   ] =
X  zz_lengths[ GALL_PREC   ] =
X  zz_lengths[ CROSS_PREC  ] =
X  zz_lengths[ EXPAND_IND  ] =
X  zz_lengths[ THREAD      ] =
X  zz_lengths[ CR_LIST     ] =
X    ceiling(sizeof(struct closure_type), sizeof(ALIGN));
X
X  /* symbol types */
X  zz_lengths[ MACRO       ] =
X  zz_lengths[ LOCAL       ] =
X  zz_lengths[ LPAR        ] =
X  zz_lengths[ RPAR        ] =
X  zz_lengths[ NPAR        ] =
X    ceiling(sizeof(struct symbol_type), sizeof(ALIGN));
X
X  /* gap objects */
X  zz_lengths[ TSPACE      ] =
X  zz_lengths[ TJUXTA      ] =
X  zz_lengths[ GAP_OBJ     ] =
X    ceiling(sizeof(struct gapobj_type), sizeof(ALIGN));
X
X  /* cross-reference and data base types */
X  zz_lengths[ CROSS_SYM   ] =
X  zz_lengths[ CR_ROOT     ] = ceiling(sizeof(struct cr_type) , sizeof(ALIGN));
X
X  /* external galley record */
X  zz_lengths[ EXT_GALL  ] = ceiling(sizeof(struct ext_gall_type),sizeof(ALIGN));
X
X} /* end MemInit() */
X
X
X/*@@**************************************************************************/
X/*                                                                           */
X/*  OBJECT GetMemory(siz, pos)                                               */
X/*                                                                           */
X/*  Return a pointer to siz ALIGNs of memory (0 < siz < MAX_OBJECT_REC).     */
X/*                                                                           */
X/*****************************************************************************/
X
XOBJECT GetMemory(siz, pos)
Xint siz;  FILE_POS *pos;
X{ static ALIGN *next_free = (ALIGN *) nil;
X  static ALIGN *top_free  = (ALIGN *) nil;
X  OBJECT res;
X  char *calloc();
X
X  debug1(DMA, DDD, "GetMemory( %d )", siz);
X
X  /* get memory from operating system, if not enough left here */
X  if( &next_free[siz] > top_free )
X  { next_free = (ALIGN *) calloc(MEM_CHUNK, sizeof(ALIGN));
X    ifdebug(DMA, D, no_of_calls++; )
X    if( next_free == NULL ) Error(FATAL,pos,"run out of memory - exiting now");
X    top_free = &next_free[MEM_CHUNK];
X    debug2(DMA, D, "GetMemory: calloc returned %d - %d",
X      (int) next_free, (int) top_free);
X  }
X
X  res = (OBJECT) next_free;
X  next_free = &next_free[siz];
X  debug3(DMA, DDD, "GetMemory returning @%d (next_free = @%d, top_free = @%d",
X    (int) res, (int) next_free, (int) top_free);
X  return res;
X} /* end GetMemory */
END_OF_FILE
  if test 9723 -ne `wc -c <'lout/z31.c'`; then
    echo shar: \"'lout/z31.c'\" unpacked with wrong size!
  fi
  # end of 'lout/z31.c'
fi
echo shar: End of archive 24 \(of 30\).
cp /dev/null ark24isdone
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...