rtsi.com/2014.01.www.rtsi.com.tar/www.rtsi.com/OS9/OSK/APPS/lout2.lzh/LOUT2/DOC/TR.BEGIN/s14

Text File | 1994-01-25 | 9KB | 221 lines

@Section
   @Tag { booklayout }
   @Title { Books }
@Begin
@PP
The DocumentLayout package may also be used to produce books.  Type
@Code "-ibook" in the Unix command instead of {@Code "-idoc"} to use the
package in this way.
@PP
A book begins with a @Code "@Book" symbol:
@ID @Code {
"@Book"
"    @Title {}"
"    @Author {}"
"    @Edition {}"
"    @Publisher {}"
"    @InitialFont { Times Roman 12p }"
"    @InitialBreak { adjust 1.2fx }"
"    @Hyphenate { Yes }"
"//"
}
The first four options are printed on the title page, the first three
using {@Code "clines @Break"} (see page {@PageOf clines}).  There are no
{@Code "@Columns"}, {@Code "@PageNumbers"}, or {@Code "@FirstPageNumber"}
options.  The last three options are as for @Code "@Document" and
{@Code "@Report"}.  Disaster will ensue if the @Code "//" is omitted.
@PP
Next comes an optional preface:
@ID @Code {
"@Preface"
"    @Tag { preface }"
"    @Title { About this book }"
"@Begin"
"@PP"
"..."
"@End @Preface"
}
Since the title of most prefaces is simply Preface, this is the default
value of the @Code "@Title" option.  After the preface, BookLayout will
produce a table of contents listing the introduction, chapters,
sections, subsections, appendices, biblio&-graphy, and index as
appropriate.
@PP
The pages up to this point will be numbered in lower case Roman
numerals; subsequent pages will be numbered in Arabic starting from 1.
@PP
Next comes an optional introduction, in exactly the same style as the
preface except that @Code "@Introduction" replaces @Code "@Preface" and
the default title is Introduction.  After that comes a sequence of chapters
in the usual style:
@ID @Code {
"@Chapter"
"    @Title { Principles }"
"    @Tag { principles }"
"@Begin"
"@PP"
"..."
"@End @Chapter"
}
No @Code "@BeginChapters" or @Code "@EndChapters" symbols are
needed.  Within a chapter, there may be a sequence of sections,
each introduced by @Code "@Section" in the usual way, all bracketed
by @Code "@BeginSections" and {@Code "@EndSections"}.  Within each
section there may be subsections, each introduced by {@Code "@SubSection"},
and the sequence as a whole bracketed by @Code "@BeginSubSections" and
{@Code "@EndSubSections"}.  The first subsection of the first section of the
first chapter will be numbered 1.1.1, and so on.  There are no sub-subsections.
@PP
Finally there is opportunity for a sequence of appendices, each
introduced by @Code "@Appendix" in the usual way.  No
@Code "@BeginAppendices" or @Code "@EndAppendices" symbols are
needed.  The appendices are numbered A, B, C, etc., and there
are sub-appendices, obtained in the usual way.
@PP
Each symbol with a @Code "@Title" option also has a @Code "@RunningTitle"
option.  The more important parts of the book (preface, introduction,
chapters, and appendices) have their @Code "@RunningTitle" printed at
the top of each even-numbered page; if omitted, the @Code "@Title" option
is used instead.
@PP
With Basser Lout, a long document is best broken into a sequence of files,
each containing one section, from @Code "@Section" to @Code "@End @Section"
inclusive.  Other files are needed for the beginning of each chapter,
from @Code "@Chapter" to {@Code "@BeginSections"}, and for the end of
each chapter, that is the final @Code "@EndSections" and
{@Code "@End @Chapter"}.  On the Unix operating system a good scheme for
naming these files is
@ID lines @Break {
@Code ch0.00     @Code "@Book" ... @Code "//"
@Code ch0.01     Preface
@Code ch0.02     Introduction
@Code ch1.00     Beginning of Chapter 1
@Code ch1.01     Section 1.1
@Code ch1.02     Section 1.2
. . .
@Code ch1.99     End of Chapter 1
@Code ch2.00     Beginning of Chapter 2
@Code ch2.01     Section 2.1
@Code ch2.02     Section 2.2
. . .
@Code ch2.99     End of Chapter 2
}
and so on.  Then the Unix command
@ID @Code "lout -ibook ch0.00 ch3.??"
will format Chapter 3 only; and
@ID @Code "lout -ibook ch?.??"
will format the entire book.  The whole book must be formatted by one
command to get the page numbers right, but there is no need to do
this until everything is perfect.
@PP
The symbols described in Sections 1--7 above are all available as
usual.  The numbering of figures and tables includes a chapter or
appendix number:  the first figure of Appendix A will be numbered A.1,
and so on.  Figures and tables within the preface and introduction are
numbered 1, 2, 3, etc.  When figures and tables appear near the end of
a chapter, the following page on which they appear may also be the first
page of the next chapter, which looks very poor.  The solution is to move
the figure or table to an earlier point in the chapter.
@PP
Figures and tables work in a slightly different way to previously, owing
to the need to attach a chapter or appendix number to each one.  The
first figure of each chapter or appendix must be preceded by
{@Code "@BeginFigures"}, and the last figure of each chapter or appendix
must be followed by {@Code "@EndFigures"}.  These symbols must also bracket
figures in the preface and introduction.  The symbols are not required
when there are no figures.  Similarly, {@Code "@BeginTables"} and
{@Code "@EndTables"} must bracket tables.
@PP
Cross referencing works as described in Section {@NumberOf cross};
@Code "@Tag" options may be given to the preface, introduction,
chapters, sections, subsections, appendices, and sub-appendices.
@PP
References work as described in Section {@NumberOf refs}, except
that @Code "@ReferenceSection" is added automatically as needed.  A variant of
the @Code "@Ref" symbol called @Code "@ChapRef" is provided, which
causes the reference to appear at the end of the current preface,
introduction, chapter, or appendix, rather than at the end of the book.
@PP
Also available are symbols for making an index.  To
add an entry to the index, place
@ID @Code "packages @Index { Packages }"
for example at the relevant point.  The result will be something like
@ID { Packages, 27 }
appearing in the index in the alphabetical position determined by the
left parameter, which should be a juxtaposition of simple words composed,
by convention, of lower-case letters and periods only.
@PP
A variant called @Code "@SubIndex" provides a small indent, as is
conventional for sub-entries in indexes.  For example,
@ID @Code {
"package  @Index  { Packages }"
"package.r @SubIndex {ReportLayout}"
"package.b @SubIndex {BookLayout}"
}
scattered through a document will produce something like
@ID lines @Break {
Packages, 27
   BookLayout, 45
   ReportLayout, 40
}
Note how the left parameters have been carefully chosen to produce the
correct ordering.  There is also a @Code "@SubSubIndex" symbol with a
double indent.
@PP
These symbols attach one page number to each entry.  Although the best
authorities recommend exactly this, many authors choose to have entries
like
@ID { Fourier Transform, 576, 583--593 }
despite the inconvenience to their readers.  {@Code "@RawIndex"},
{@Code "@RawSubIndex"}, and {@Code "@RawSubSubIndex"}
symbols are provided which do not add page numbers to the entry, leaving
this to the user.  For example, one systematic way to get page number
ranges is to place
@ID @Code {
"packages @RawIndex {"
"    Packages, {@PageOf packages}"
"    -- {@PageOf packages.end}"
"}"
}
at the start of the range, and
@ID @Code {
"{@PageMark packages.end}"
}
at the end of the range.  This works because all six index symbols
include a @Code "@PageMark" operation.  Incidentally, this means that
index tags should be different from chapter and other tags.
@PP
Another use for @Code "@RawIndex" is to get blank lines into the index
between the letters of the alphabet, by inserting phantom entries:
@ID @Code {
"b @RawIndex {}"
"c @RawIndex {}"
"..."
"z @RawIndex {}"
}
In fact there is a symbol called @Code "@IndexBlanks" which creates
exactly these 25 entries.  Unfortunately, these blanks will occasionally
appear at the top of a column, and if there are no entries beginning with
x, for example, there will be two blank lines between the w and y
entries.  The careful user can start off with @Code "@IndexBlanks" and
replace it later by the appropriate subset.
@FootNote {
For Lout to solve this problem automatically, it would need to be told
which letter each index entry belongs under, perhaps by symbols
{@Code "@AIndex"}, {@Code "@BIndex"}, etc.  The author
felt that this would have been too tedious.
}
@PP
Owing to problems behind the scenes, the Index heading will be printed,
and an entry will be made in the table of contents, even if there are no
entries in the index.  To prevent this, you will need to change the
@Code "@MakeIndex" option in the @Code book setup file to {@Code "No"},
using the method described in the following section.
@PP
Although the page numbers in index entries will be kept up to date
automatically as the document changes, as all cross references are,
the user is recommended to refrain from inserting index entries until
the book is complete and an overall plan of the structure of the index
can be made.
@End @Section