enscript.texi - enscript - GNU Enscript
(HTM) git clone git://thinkerwim.org/enscript.git
(DIR) Log
(DIR) Files
(DIR) Refs
(DIR) README
(DIR) LICENSE
---
enscript.texi (11523B)
---
1 \input texinfo @c -*-texinfo-*-
2 @c %**start of header
3 @setfilename enscript.info
4 @settitle enscript
5 @setchapternewpage on
6 @c %**end of header
7
8 @include version.texi
9
10 @dircategory Utilities
11 @direntry
12 * Enscript: (enscript). GNU Enscript
13 @end direntry
14
15 @c Combine function and variable indexes to the Concept index.
16 @synindex fn cp
17 @synindex vr cp
18
19 @ifinfo
20 This file documents GNU enscript @value{VERSION}
21
22 Copyright (C) 1995, 1998, 1999, 2007, 2009 Free Software Foundation, Inc.
23
24 Permission is granted to copy, distribute and/or modify this document
25 under the terms of the GNU Free Documentation License, Version 1.3 or
26 any later version published by the Free Software Foundation; with no
27 Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A
28 copy of the license is included in the section entitled ``GNU Free
29 Documentation License''.
30 @end ifinfo
31
32
33 @titlepage
34 @title GNU enscript
35 @subtitle For version @value{VERSION}, @value{UPDATED}
36 @author Markku Rossi
37
38 @page
39 @vskip 0pt plus 1filll
40 Copyright @copyright{} 1995-1998 Markku Rossi.
41 @sp 2
42 This is the first edition of the GNU enscript documentation,@*
43 and is consistent with GNU enscript @value{VERSION}.@*
44
45 Permission is granted to make and distribute verbatim copies of
46 this manual provided the copyright notice and this permission notice
47 are preserved on all copies.
48
49 Permission is granted to copy and distribute modified versions of this
50 manual under the conditions for verbatim copying, provided that the entire
51 resulting derived work is distributed under the terms of a permission
52 notice identical to this one.
53
54 Permission is granted to copy and distribute translations of this manual
55 into another language, under the above conditions for modified versions,
56 except that this permission notice may be stated in a translation
57 approved by the Free Software Foundation.
58 @end titlepage
59
60 @ifinfo
61 @node Top, Introduction, (dir), (dir)
62 @comment node-name, next, previous, up
63 @top GNU enscript
64
65 This file documents the GNU enscript program. This edition documents
66 version @value{VERSION}.
67
68 @menu
69 * Introduction::
70 * Invoking Enscript::
71 * Basic Printing::
72 * Advanced Usage::
73 * Configuration Files::
74 * Customization::
75 * The states Program::
76 * Writing New Highlighting Definitions::
77 * Index::
78 * Documentation License::
79 @end menu
80
81 @end ifinfo
82
83 @c ----------------------------------------------------------------------
84 @node Introduction, Invoking Enscript, Top, Top
85 @chapter Introduction
86
87 @itemize @bullet
88 @item overall
89 @item design
90 @end itemize
91
92 @c ----------------------------------------------------------------------
93 @node Invoking Enscript, Basic Printing, Introduction, Top
94 @chapter Invoking Enscript
95
96 @c ----------------------------------------------------------------------
97 @node Basic Printing, Advanced Usage, Invoking Enscript, Top
98 @chapter Basic Printing
99
100 @menu
101 * Input Encodings::
102 * Selecting Fonts::
103 * Page Headers::
104 * Page Handling::
105 * Highlighting::
106 @end menu
107
108 @node Input Encodings, Selecting Fonts, Basic Printing, Basic Printing
109 @section Input Encodings
110
111 @node Selecting Fonts, Page Headers, Input Encodings, Basic Printing
112 @section Selecting Fonts
113
114 @node Page Headers, Page Handling, Selecting Fonts, Basic Printing
115 @section Page Headers
116
117 @node Page Handling, Highlighting, Page Headers, Basic Printing
118 @section Page Handling
119
120 @menu
121 * Page Orientation::
122 * N-up Printing::
123 * Fitting Text to Page::
124 @end menu
125
126 @node Page Orientation, N-up Printing, Page Handling, Page Handling
127 @subsection Page Orientation
128
129 @node N-up Printing, Fitting Text to Page, Page Orientation, Page Handling
130 @subsection N-up Printing
131
132 @node Fitting Text to Page, , N-up Printing, Page Handling
133 @subsection Fitting Text to Page
134
135 @node Highlighting, , Page Handling, Basic Printing
136 @section Highlighting
137
138 @menu
139 * Different Output Languages::
140 @end menu
141
142 @node Different Output Languages, , Highlighting, Highlighting
143 @subsection Different Output Languages
144
145 @c ----------------------------------------------------------------------
146 @node Advanced Usage, Configuration Files, Basic Printing, Top
147 @chapter Advanced Usage
148
149 @menu
150 * Selecting Pages::
151 * Escape Sequences::
152 * Input Filters::
153 * Slice Printing::
154 * PostScript Printer Controlling::
155 * Pass-Through Mode::
156 @end menu
157
158 @node Selecting Pages, Escape Sequences, Advanced Usage, Advanced Usage
159 @section Selecting Pages
160
161 @node Escape Sequences, Input Filters, Selecting Pages, Advanced Usage
162 @section Escape Sequences
163
164 @node Input Filters, Slice Printing, Escape Sequences, Advanced Usage
165 @section Input Filters
166
167 @node Slice Printing, PostScript Printer Controlling, Input Filters, Advanced Usage
168 @section Slice Printing
169
170 @node PostScript Printer Controlling, Pass-Through Mode, Slice Printing, Advanced Usage
171 @section PostScript Printer Controlling
172
173 @node Pass-Through Mode, , PostScript Printer Controlling, Advanced Usage
174 @section Pass-Through Mode
175
176 @c ----------------------------------------------------------------------
177 @node Configuration Files, Customization, Advanced Usage, Top
178 @chapter Configuration Files
179
180 @c ----------------------------------------------------------------------
181 @node Customization, The states Program, Configuration Files, Top
182 @chapter Customization
183
184 @menu
185 * Output Media::
186 * User-Defined Fancy Headers::
187 @end menu
188
189 @node Output Media, User-Defined Fancy Headers, Customization, Customization
190 @section Output Media
191
192 @node User-Defined Fancy Headers, , Output Media, Customization
193 @section User-Defined Fancy Headers
194
195
196 @c ----------------------------------------------------------------------
197 @node The states Program, Writing New Highlighting Definitions, Customization, Top
198 @chapter The @samp{states} Program
199
200 @c ----------------------------------------------------------------------
201 @node Writing New Highlighting Definitions, Index, The states Program, Top
202 @chapter Writing New Highlighting Definitions
203
204 The highlighting works in three separate phases. First, the
205 @dfn{highlighing rules} process the input stream and parse it into
206 logical components. The components are called @dfn{faces}. A face
207 presents one logical component of the input language, for example, a
208 keyword, a comment, etc.. The enscript's highlighting model defines the
209 following faces:
210
211 @table @b
212 @item bold
213 @itemx italic
214 @itemx bold_italic
215 Hard-coded faces for the bold, italic, and bold-italice text types.
216 These faces define the exact presentation of the face font, so the style
217 files have very little power in customizing their outlook. These faces
218 should be avoided as much as possible.
219
220 @item comment
221 A comment, normally in a programming language.
222
223 @item function_name
224 A function name. The function names are normally recognized from
225 function definitions, not from an use of the function.
226
227 @item variable_name
228 A variable name. The variable names are normally recognized from
229 function, type, and variable definitions.
230
231 @item keyword
232 A reserved keyword. Normally, all occurrences of the keywords are
233 recognized.
234
235 @item reference
236 A reference to another location in a file or to another file or
237 resource. For example, in the C-language, the goto targets are
238 references.
239
240 @item string
241 A string literal.
242
243 @item builtin
244 A builtin function or property. Normally, all occurrences of the
245 builtins are recognized.
246
247 @item type
248 A type specifier. The types are normally recognized from function,
249 type, and variable definitions.
250
251 @end table
252
253 As the second step, the @dfn{output style} specifies how the faces are
254 presented in the generated output. Each face has the following
255 properties:
256
257 @table @b
258 @item fontname
259 The PostScript font name of the the font that is used for the face.
260 This property is used only for the PostScript outputs.
261
262 @item boldp
263 A boolean flag which tells whether the face should be printed in bold
264 font. This property is used for all output languages except for the
265 PostScript which uses the fontname property.
266
267 @item italicp
268 A boolean flag which tells whether the face shuold be printed with
269 italic font. This property is used for all output languages except for
270 the PostScript which uses the fontname property.
271
272 @item fg_color
273 The foreground color of the face.
274
275 @item bg_color
276 The background color of the face. This property is not implemented on
277 all output languages.
278 @end table
279
280 Finally, the @dfn{output language} describes how the faces and other
281 text are presented in the output language. The output language defines
282 a set of functions which are called to generate the output.
283
284 @menu
285 * Highlighting Rules::
286 * Styles::
287 * Output Languages::
288 @end menu
289
290 @node Highlighting Rules, Styles, Writing New Highlighting Definitions, Writing New Highlighting Definitions
291 @section Highlighting Rules
292
293
294 @node Styles, Output Languages, Highlighting Rules, Writing New Highlighting Definitions
295 @section Styles
296
297 @node Output Languages, , Styles, Writing New Highlighting Definitions
298 @section Output Languages
299
300 @deffn Function map_color (r, g, b)
301 @end deffn
302
303 @deffn Function language_print (string)
304 @end deffn
305
306 @deffn Function language_symbol (symbol)
307 @end deffn
308
309 @deffn Function header ()
310 @end deffn
311
312 @deffn Function trailer ()
313 @end deffn
314
315 @deffn Function face_on (face)
316 @end deffn
317
318 @deffn Function face_off (face)
319 @end deffn
320
321 @defvr Variable LANGUAGE_SPECIALS
322 @end defvr
323
324 The following example creates a new output language @code{simple_html}
325 that creates simple HTML outputs. The output language is defined in a
326 file called @file{lang_simple_html.st}. The file must define a state
327 called @code{lang_simple_html}. The file can be located in any
328 directory that is in the load path of the states program.
329
330 The output language definitions are defined in the @code{BEGIN} block of
331 the @code{lang_simple_html} state. Please, note that the @code{BEGIN}
332 block is ended with a @code{return}-statement. This statement will
333 return the control to the calling state that is the start state of the
334 enscript highlight program. If the @code{return}-statement was omitted,
335 the states would start processing the input with the
336 @code{lang_simple_html} state which is obviously a wrong choice.
337
338 @example
339 state lang_simple_html
340 @{
341 BEGIN @{
342 sub map_color (r, g, b)
343 @{
344 return sprintf ("#%02X%02X%02X", r, g, b);
345 @}
346
347 sub language_print (str)
348 @{
349 str = regsuball (str, /\&/, "&");
350 str = regsuball (str, /</, "<");
351 str = regsuball (str, />/, ">");
352 str = regsuball (str, /\"/, """);
353 print (str);
354 @}
355
356 sub language_symbol (symbol)
357 @{
358 return false;
359 @}
360
361 sub header ()
362 @{
363 print ("<html>\n<head>\n<title>Simple HTML Output</title>\n");
364 print ("</head>\n<body>\n");
365 @}
366
367 sub trailer ()
368 @{
369 print ("</body>\n</html>\n");
370 @}
371
372 sub fase_on (face)
373 @{
374 if (face(boldp])
375 print ("<B>");
376 if (face(italicp])
377 print ("<I>");
378 if (face[fg_color])
379 print ("<FONT COLOR=\", face[fg_color], "\">");
380 @}
381
382 sub face_off (face)
383 @{
384 if (face[fg_color])
385 print ("</FONT>");
386 if (face[italicp])
387 print ("</I>");
388 if (face[boldp])
389 print ("</B>");
390 @}
391
392 LANGUAGE_SPECIALS = /[<>\&\"]/;
393
394 return;
395 @}
396 @}
397 @end example
398
399 @c ----------------------------------------------------------------------
400 @page
401 @node Index, Documentation License, Writing New Highlighting Definitions, Top
402 @unnumbered Index
403
404 @printindex cp
405
406 @c ----------------------------------------------------------------------
407
408 @node Documentation License, , Index, Top
409 @appendix Documentation License
410
411 @include fdl-1.3.texi
412
413 @contents
414 @bye