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