@Section
    @Title { Setup files }
    @Tag { setup }
@Begin
@PP
As mentioned briefly in Section {@NumberOf start}, each Lout document
begins with an instruction to include (i.e. to read) a @I { setup file }:
setup.file @Index { setup file }
sysinclude. @Index @Code "@SysInclude"
system.include @Index { system include directory }
doc.file @Index { @Code "doc" file }
@ID @Code "@SysInclude { doc }"
The setup file's name in this example is @Code { doc }, and the @Code Sys
in @Code "@SysInclude" means that @Code doc is stored in the @I { Lout
system include directory }, which is where all the standard setup files
are kept.  Each document type (Chapter {@NumberOf types}) has its own
setup file.
@PP
To change the overall format of a document, you need to create your own
setup file by copying and modifying one of the standard ones.  We will
assume that you are making an ordinary document, with the @Code doc
setup file, but a similar procedure works for any setup file.
@PP
You first need to find out the name of the Lout system include
directory, by typing
@ID @Code "lout  -V"
in Unix.  This causes Lout to print out various facts about itself.  Then,
supposing that this tells you that the Lout system include directory
is @Code { "/usr/lout/include" }, type the Unix command
@ID @Code "cp  /usr/lout/include/doc  mydoc"
to place a copy of the @Code doc setup file in your directory,
mydoc.file @Index { @Code "mydoc" file }
renaming it @Code {mydoc}.  Since @Code "doc" is read-only, you may
also need to change the mode of @Code mydoc to be writable (by
@Code "chmod +w mydoc" in Unix).  Now replace
@ID @Code "@SysInclude { doc }"
at the beginning of your document by
@ID @Code "@Include { mydoc }"
and Lout will read @Code mydoc as the setup file instead of
@Code { doc }.  Since the two files are at present identical, this has
changed nothing so far; but now any changes you make to @Code mydoc
will affect your document.  Notice the use of @Code "@Include"
rather than @Code { "@SysInclude" }; @Code "@Include" will search your
current directory for @Code { mydoc }, whereas @Code "@SysInclude"
searches only the system directory.
@PP
The remainder of this section is a tour through @Code {doc},
explaining the various parts and how to modify them.  The first lines
that actually do anything are these:
@ID @OneRow @Code {
"@SysInclude { fontdefs }"
"@SysInclude { langdefs }"
"@SysInclude { dl }"
"@SysInclude { docf }"
}
We already know that @Code "@SysInclude" causes Lout to read a file from
the Lout system include directory.  Files @Code fontdefs and @Code langdefs
fontdefs.file @Index { @Code "fontdefs" file }
langdefs.file @Index { @Code "langdefs" file }
tell Lout what fonts and languages there are.  File @Code "dl" contains
dl.file @Index { @Code "dl" file }
the definition of the DocumentLayout package, in which all the symbols
of the first four chapters of this guide are defined.  File
@Code "docf" contains extra definitions specific to
docf.file @Index { @Code "docf" file }
ordinary documents (as distinct from technical reports, books, or the
other document types of Chapter {@NumberOf types}).  So this fourth line
will be different in the setup files for those other types.
@PP
Now let's look at the next six lines of {@Code "doc"}:
@ID @OneRow @Code {
"# @SysInclude { tab }"
"# @SysInclude { eq }"
"# @SysInclude { diag }"
"# @SysInclude { graph }"
"# @SysInclude { cprint }"
"# @SysInclude { pas }"
}
These lines, each beginning with {@Code "#"}, are @I { comments }:  when
Lout encounters a @Code "#" character not enclosed in double quotes, it
ignores it and everything following it up to and including the end of
that line.  So these lines do nothing as they stand, but by deleting one
or more @Code "#" characters you can have the @Code "@SysInclude" lines
for these files, which contain the definitions of Lout's specialized
formatting packages, in your setup file, rather than at the beginning
of your document.
@PP
The next line is
@ID @Code {
"@Include { mydefs }"
}
This searches your current directory for a file called @Code { mydefs },
which (as Section {@NumberOf definitions} explains) is intended to hold
your own personal set of definitions of new symbols.  It does no harm
if there is no @Code "mydefs" file in your current directory, because
@Code "@Include" then searches the Lout system include directory for
it, and there is an empty @Code mydefs file there.  When using your own
setup file, you might prefer to delete @Code "@Include { mydefs }" and
put your definitions in its place, so that you have one file of setup-type
material rather than two.
@PP
Next we come to the main thing:  the DocumentLayout @Code "@Use"
use. @Index @Code "@Use"
clause.  It looks like this:
@ID @OneRow @Code {
"@Use { @DocumentLayout"
"  # @InitialFont { Times Base 12p }"
"  # @InitialBreak { {adjust 1.20fx hyphen} @OrIfPlain {ragged 1fx nohyphen} }"
"  # @InitialLanguage { English }"
"  # @InitialColour { black }"
"  # @HeadingFont { Bold }"
"  # @ParaGap { 1.3vx @OrIfPlain 1f }"
"}"
}
@Code "@DocumentLayout" is a symbol, and @Code { "@InitialFont" },
document.layout @Index @Code "@DocumentLayout"
@Code { "@InitialBreak" }, etc. are its options.  There are over one
hundred options altogether; the display above just shows the first
six.  You change the overall format of your document by changing
these options.
@PP
As it stands, the options are all hidden within comments, so the
default values (shown within braces) are in force.  To change an
option, delete the @Code "#" and change the value between
braces.  For example, to set the document in Helvetica 10 point
font, change the @Code { "@InitialFont" } line to
@ID @Code "@InitialFont { Helvetica Base 10p }"
We won't go through all the options now, since they are the subject of
following sections.
@PP
The @Code "@OrIfPlain" symbol that appears within some setup file
options is used to set the value of the option differently when
plain text output (Section {@NumberOf plain}) is being produced.  For
example, the default value of @Code "@InitialBreak" is usually
{@Code "adjust 1.20fx hyphen"}, but when plain text is being produced
it switches to {@Code "ragged 1fx nohyphen"}.  When changing such
options you can leave the @Code "@OrIfPlain" symbol there and change
one or both of the alternative values as you wish.
@PP
The standard setup files are all much the same up to this point; the
main variation is that in some files, some options are already set.  The
@Code "slides" setup file, for example, contains
@ID @Code "@InitialFont { Times Base 20p }"
so that overhead transparencies will have a large font size.  However,
now comes a second @Code "@Use" clause whose symbol and options depend
on the document type.  For ordinary documents (i.e. in the @Code "doc"
setup file) this clause is
@ID @OneRow @Code {
"@Use { @OrdinaryLayout"
"  # @IndexWord { index }"
"  # @AppendixWord { appendix }"
"  # @SectionNumbers { Arabic }"
"  # @AppendixNumbers { UCAlpha }"
"  # @SectionHeadingFont { Bold }"
"}"
}
Once again this is just some of the options.  In the @Code slides
setup file for overhead transparencies, we find this:
@ID @OneRow @Code {
"@Use { @OverheadLayout"
"  # @DateLine { No }"
"  # @ContentsWord { contents }"
"  # @FirstOverheadNumber { 1 }"
"  # @OverheadNumbers { Arabic }"
"  # @TitlePageFont { Helvetica Base 1.5f }"
"  # @OverheadHeadingFont { Bold }"
"  # @OverheadInContents { No }"
"}"
}
In general this second @Code "@Use" clause assigns values to options
specific to the document type we are using, whereas the first
@Code "@Use" clause assigns values to options that are relevant to many
or all document types.
@PP
The setup files used with C and C++ program printing ({@Code "cdoc"},
{@Code "creport"}, etc.) contain a third @Code "@Use" clause, providing
options specific to printing C and C++ programs.  The setup files used
with the @Code "@Diag" symbol also have an extra @Code "@Use" clause
whose options relate to producing diagrams.  If you need C programs and
diagrams, for example, you have to make your own setup file by combining
these two (it will have four {@Code "@Use" clauses}).  The setup file ends
with a comment identifying the spot where database declarations should
database.dec @Index { database declarations, where to put }
be put, and one such declaration, for reference printing styles.
@End @Section