aboutsummaryrefslogtreecommitdiffstats
path: root/doc/user/fmt_setu
blob: 991e1f4f82c36b78e67596f64f94f01ae79f7ffe (plain) (blame)
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
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
@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.files. @Index { setup files }
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, and each specialized package (for equations, tables, and
so on) has a setup file too.
@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 { langdefs }"
"@SysInclude { bsf }"
"@SysInclude { dsf }"
"@SysInclude { docf }"
}
We already know that @Code "@SysInclude" causes Lout to read a file from
the Lout system include directory.  File @Code langdefs
langdefs.file @Index { @Code "langdefs" file }
tells Lout what languages there are, and files @Code "bsf" and
@Code "dsf" contain
bsf.file @Index { @Code "bsf" file }
dsf.file @Index { @Code "dsf" file }
the definitions of the BasicSetup and DocumentSetup packages, in which
all the symbols of the first two 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 line
will be different in the setup files for those other types.
@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
material rather than two.
@PP
Next we come to the BasicSetup @Code "@Use" clause.  It looks like this:
use. @Index @Code "@Use"
@ID @OneRow @Code @Verbatim {
@Use { @BasicSetup
  # @InitialFont { Times Base 12p }
  # @InitialBreak { {adjust 1.20fx hyphen} @OrIfPlain {ragged 1fx nohyphen} }
  # @InitialSpace { lout }
  # @InitialLanguage { English }
  # @InitialColour { black }
  # @OptimizePages { No }
  # @HeadingFont { Bold }
  # @ParaGap { 1.3vx @OrIfPlain 1f }
  # @ParaIndent { 2.00f @OrIfPlain 5s }
}
}
@Code "@BasicSetup" is a symbol, and @Code { "@InitialFont" },
basic.layout @Index @Code "@BasicSetup"
@Code { "@InitialBreak" }, etc. are its options.  There are more options
than we've shown; the display above just shows the first
few.  You change the overall format of your document by changing
these options.
@PP
A @Code "#" causes Lout to ignore that character and the rest of the
line (such ignored parts are called {@I comments} and @Code "#" is
the @I { comment character }).  As it stands, then, the options are
all hidden within comments, so their default values (shown within braces
in the comments) 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
Next comes a similar @Code "@Use" clause, for the DocumentSetup package:
@ID @OneRow @Code @Verbatim {
@Use { @DocumentSetup
  # @PageType { A4 @OrIfPlain Other }
  # @PageWidth { 80s }
  # @PageHeight { 66f }
  # @PageOrientation { Portrait }
  # @PageBackground {}
  # @TopMargin { 2.5c @OrIfPlain 6f }
}
}
This one has many options, starting with options for page
layout as shown, then going on to figures and tables, tables of
contents, etc.
@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 third @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 (once again we show just some of the options):
@ID @OneRow @Code @Verbatim {
@Use { @OrdinarySetup
  # @IndexWord { index }
  # @AppendixWord { appendix }
  # @SectionNumbers { Arabic }
  # @AppendixNumbers { UCAlpha }
  # @SectionHeadingFont { Bold }
}
}
In the @Code slides setup file for overhead transparencies, we find this:
@ID @OneRow @Code @Verbatim {
@Use { @OverheadSetup
  # @DateLine { No }
  # @ContentsWord { contents }
  # @FirstOverheadNumber { 1 }
  # @OverheadNumbers { Arabic }
  # @TitlePageFont { Helvetica Base 1.5f }
  # @OverheadHeadingFont { Bold }
  # @OverheadInContents { No }
}
}
In general this third @Code "@Use" clause assigns values to options
specific to the document type we are using, whereas the first and
second @Code "@Use" clauses assign values to options that are relevant to many
or all document types.
@PP
The setup file ends with a comment identifying a spot where database
declarations may
database.dec @Index { database declarations, where to put }
be put, and two such declarations, one for fonts and the other for
reference printing styles.
@PP
The setup files used with other packages, such as C and C++ program printing,
diagrams, and graphs, are similar to the @Code { doc } setup file we
have just gone through.  They contain a @@SysInclude line analogous to
@Code "@SysInclude { dsf }" for reading the package's definition, followed
by a @@Use clause for setting the package's options.  The same procedure
is followed for changing these options.  For example, to change the
options of the @Code "diag" package, copy file @Code "diag" from the
Lout system include directory to your directory, replace the
@ID @Code "@SysInclude { diag }"
line at the top of your document by {@Code "@Include { mydiag }"}, then
edit @Code "mydiag" and change the options as you wish.
@PP
If you are using several packages and you would like a single setup file,
that is quite easy to arrange.  For example, suppose you have
@ID @Code {
"@Include { mydoc }"
"@Include { mydiag }"
"@Include { mycprint }"
}
To create a single setup file, just concatenate these three files into
one file (call it @Code { mysetup }, say), and replace the three lines by
@ID @Code {
"@Include { mysetup }"
}
As explained earlier, you can even replace the @Code "@Include { mydefs }"
line within the setup file by the actual definitions, giving just one
file of setup material for the entire document.
@End @Section