aboutsummaryrefslogtreecommitdiffstats
path: root/man/lout.1
blob: 3bfc2c9a0a6f93b0c1281acf10103199dd864e96 (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
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
.\" Use default p.i., so commented out here and in .TP
.\" .nr oi 16 \" Prevailing indentation for options' .TP request
.\" .de Sp
.\" .if n .sp
.\" .if t .sp 0.4
.\" ..
.TH LOUT 1
.SH NAME
lout - prepare Lout document for printing
.SH SYNOPSIS
\fBlout\fR [ \fIoptions\fR ] \fIfile\fR...
.SH DESCRIPTION
Invoke the Basser Lout interpreter on the concatenation of the named
files, producing a PostScript file on standard output suitable for
printing on PostScript printers using
.IR lpr (1).
If no files are named, stdin is used instead.  The special file name
.RB ` \|\-\| '
may be used to denote standard input.  White space between flags
and their associated option values is optional.
.LP
An optional
.B .lt
suffix may be used for Lout source and include files.  When invoking
files ending in this suffix the suffix may be omitted.
.SH OPTIONS
.SS Output
.TP \" \n(oi
.BI \-o " filename"
Direct output to
.I filename
instead of to stdout.
.TP
.BI \-e " filename"
Direct error messages to
.I filename
instead of to stderr.
.TP
.B \-a
Use "\c
.IR filename :\c
.IR linenum :\c
.IR colnum :\c
.I message\c
\&" alternative error message format (useful with Emacs compilation
mode and other tools).
.SS Output format
.TP \" \n(oi
.B \-EPS
Produce output in the form of an EPS (Encapsulated PostScript) file,
suitable for inclusion in another document.  Useful with stand-alone
illustrations.
.TP
.B \-p
Produce plain text output instead of PostScript.
.TP
.B \-P
Like
.BR \-p ,
but with a form-feed character between pages.
.TP
.B \-Z
Produce Adobe Portable Document Format (PDF) output.  This includes
links, but the more advanced graphics packages of Lout are not supported.
.TP
.B \-PDF
Synonym for
.BR \-Z.
.TP
.B \-t
Ignore texture-changing options; everything that would otherwise have
been printed using a texture will be printed in solid colour.
.SS Cross-reference database
.TP \" \n(oi
.B \-s
Suppress all reading and writing of the cross reference database;
other databases are not affected.  Useful when many simple documents
that don't do any cross referencing are stored in one directory.
.TP
.B \-l
Use ASCII order when sorting index entries etc.; the default depends on
the COLLATE compilation option (use
.B \-V
option to find out your default value).
.TP
.B \-L
Use your locale's order when sorting index entries etc.; the default
depends on the COLLATE compilation option (use
.B \-V
option to find out your default value).
.SS Execution of filters
.TP \" \n(oi
.B \-S
Safe execution: disable all calls to
.IR system (3),
instead echoing the commands that would have been executed.  Although
this makes the Lout run certainly safe, the PostScript output file may
not be.
.TP
.B \-U
Unsafe execution: allow calls to
.IR system (3).
This is usually the default behavior, but it is possible to make safe
execution the default during installation (use
.B \-V
option to find out whether this was done or not), hence the need for
this flag.
.SS Changing document setup options
.TP \" \n(oi
.BI \-\- option { value }
Set setup file
.I option
to
.IR value ,
overriding any value assigned to
.I option
in the setup file.  For example,
.B \-\-@PageType{Letter}
will set the
.B @PageType
setup file option to
.BR  Letter .
The value may be a sequence of words but not an arbitrary Lout object.
If there are spaces you must ensure that it is passed to Lout as a
single option; the usual way to do this is to enclose it in quotes.
.SS Searching for files
.TP \" \n(oi
.BI \-i " filename"
Search the directories of the include file path (see below) for
.I filename
or
.IR filename .lt
and include it.  There may be multiple
.B \-i
options.
.TP
.BI \-I " dirname"
Add
.I dirname
to the list of directories searched for
.B @Include
files and
.B \-i
option files.
There may be multiple
.B \-I
options.
.B @Include
first searches the current directory, then searches the
.B \-I
directories in the order given, and finally searches the default
include file directory (see below).
.B @SysInclude
and the
.B \-i
option omit the search of the current directory.
.TP
.BI \-C " dirname"
Add
.I dirname
to the list of directories searched for Lout character mapping (\c
.BR .LCM )
files.
There may be multiple
.B \-C
options; the directories are searched in the order given, and finally
the default character mappings directory is searched (see below).
.TP
.BI -F " dirname"
Add
.I dirname
to the list of directories searched for font metrics (formerly
.BR .AFM )
files.  There may be multiple
.B \-F
options; the directories are searched in the order given, and finally
the default font metrics directory is searched (see below).
.TP
.BI \-H " dirname"
Add
.I dirname
to the list of directories searched for hyphenation patterns files,
both unpacked
.RB ( .lh )
and packed
.RB ( .lp ).
There may be multiple
.B \-H
options; the directories are searched in the order given, and finally
the default hyphenation directory is searched (see below).
.TP
.BI -D " dirname"
Add
.I dirname
to the list of directories searched for Lout database files.  There
may be multiple
.B \-D
options.
.B @Database
searches the current directory, then the
.B \-D
directories in the order given, and finally searches the default
databases directory (see below).
.B @SysDatabase
omits the search of the current directory.
.SS Miscellaneous options
.TP \" \n(oi
.B \-r num
Run Lout num times, producing output only on the last run.  Useful for
bringing cross references up to date quickly.
.TP
.B \-x
Initializing run, not for ordinary use: read and check all font files
mentioned in font definitions, read and check all hyphenation files
mentioned in language definitions and build compressed versions, read
and check all database files mentioned in database clauses and build
index files.
.TP
.B \-u
Print usage information on stderr and exit.
.TP
.B \-V
Print version information on stderr and exit.
.TP
.B \-M
Use less memory and run more slowly (the cross reference database index
will be kept in a file rather than in memory).
.TP
.B \-w
Show the total number of non-empty words printed in the output file.
This includes words and numbers in page headers and footers; section
numbers and other numbers; every punctuation character in a font
different from its adjacent word; and every little fragment of every
equation; so it will always somewhat overestimate the true number.
.SH FILES AND ENVIRONMENT VARIABLE
.LP
.\" NB: be careful with tabs in the table below
.nf
.ta \w'Default character mappings dir.:  'u
\&Default include file directory:	\fILOUTLIB\fP/include
\&Default databases directory:	\fILOUTLIB\fP/data
\&Default font metrics directory:	\fILOUTLIB\fP/font
\&Default hyphenation directory:	\fILOUTLIB\fP/hyph
\&Default character mappings dir.:	\fILOUTLIB\fP/maps
\&Default locales directory:	\fILOUTLIB\fP/locale
.fi
.LP
The default library directory, usually
.BR /usr/local/lib/lout ,
can be changed by setting environment variable
.SB LOUTLIB
to an alternative directory name.
.SH SEE ALSO
.LP
.BR prg2lout (1),
.BR lpr (1),
.BR ghostview (1)
.SH REFERENCES
.LP
Jeffrey H. Kingston,
.I 
\(lq\&A User's Guide to the Lout Document Formatting System\(rq\c
\&, and
.I
\(lq\&An Expert's Guide to the Lout Document Formatting System\(rq\c
\&.
.SH AUTHOR
.LP
Jeffrey H. Kingston