1 \input texinfo @c -*-texinfo-*-
3 @setfilename enscript.info
10 @dircategory Utilities
12 * Enscript: (enscript). GNU Enscript
15 @c Combine function and variable indexes to the Concept index.
20 This file documents GNU enscript @value{VERSION}
22 Copyright (C) 1995, 1998, 1999, 2007, 2009 Free Software Foundation, Inc.
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''.
35 @subtitle For version @value{VERSION}, @value{UPDATED}
39 @vskip 0pt plus 1filll
40 Copyright @copyright{} 1995-1998 Markku Rossi.
42 This is the first edition of the GNU enscript documentation,@*
43 and is consistent with GNU enscript @value{VERSION}.@*
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.
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.
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.
61 @node Top, Introduction, (dir), (dir)
62 @comment node-name, next, previous, up
65 This file documents the GNU enscript program. This edition documents
66 version @value{VERSION}.
73 * Configuration Files::
75 * The states Program::
76 * Writing New Highlighting Definitions::
78 * Documentation License::
83 @c ----------------------------------------------------------------------
84 @node Introduction, Invoking Enscript, Top, Top
92 @c ----------------------------------------------------------------------
93 @node Invoking Enscript, Basic Printing, Introduction, Top
94 @chapter Invoking Enscript
96 @c ----------------------------------------------------------------------
97 @node Basic Printing, Advanced Usage, Invoking Enscript, Top
98 @chapter Basic Printing
108 @node Input Encodings, Selecting Fonts, Basic Printing, Basic Printing
109 @section Input Encodings
111 @node Selecting Fonts, Page Headers, Input Encodings, Basic Printing
112 @section Selecting Fonts
114 @node Page Headers, Page Handling, Selecting Fonts, Basic Printing
115 @section Page Headers
117 @node Page Handling, Highlighting, Page Headers, Basic Printing
118 @section Page Handling
123 * Fitting Text to Page::
126 @node Page Orientation, N-up Printing, Page Handling, Page Handling
127 @subsection Page Orientation
129 @node N-up Printing, Fitting Text to Page, Page Orientation, Page Handling
130 @subsection N-up Printing
132 @node Fitting Text to Page, , N-up Printing, Page Handling
133 @subsection Fitting Text to Page
135 @node Highlighting, , Page Handling, Basic Printing
136 @section Highlighting
139 * Different Output Languages::
142 @node Different Output Languages, , Highlighting, Highlighting
143 @subsection Different Output Languages
145 @c ----------------------------------------------------------------------
146 @node Advanced Usage, Configuration Files, Basic Printing, Top
147 @chapter Advanced Usage
154 * PostScript Printer Controlling::
155 * Pass-Through Mode::
158 @node Selecting Pages, Escape Sequences, Advanced Usage, Advanced Usage
159 @section Selecting Pages
161 @node Escape Sequences, Input Filters, Selecting Pages, Advanced Usage
162 @section Escape Sequences
164 @node Input Filters, Slice Printing, Escape Sequences, Advanced Usage
165 @section Input Filters
167 @node Slice Printing, PostScript Printer Controlling, Input Filters, Advanced Usage
168 @section Slice Printing
170 @node PostScript Printer Controlling, Pass-Through Mode, Slice Printing, Advanced Usage
171 @section PostScript Printer Controlling
173 @node Pass-Through Mode, , PostScript Printer Controlling, Advanced Usage
174 @section Pass-Through Mode
176 @c ----------------------------------------------------------------------
177 @node Configuration Files, Customization, Advanced Usage, Top
178 @chapter Configuration Files
180 @c ----------------------------------------------------------------------
181 @node Customization, The states Program, Configuration Files, Top
182 @chapter Customization
186 * User-Defined Fancy Headers::
189 @node Output Media, User-Defined Fancy Headers, Customization, Customization
190 @section Output Media
192 @node User-Defined Fancy Headers, , Output Media, Customization
193 @section User-Defined Fancy Headers
196 @c ----------------------------------------------------------------------
197 @node The states Program, Writing New Highlighting Definitions, Customization, Top
198 @chapter The @samp{states} Program
200 @c ----------------------------------------------------------------------
201 @node Writing New Highlighting Definitions, Index, The states Program, Top
202 @chapter Writing New Highlighting Definitions
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
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.
221 A comment, normally in a programming language.
224 A function name. The function names are normally recognized from
225 function definitions, not from an use of the function.
228 A variable name. The variable names are normally recognized from
229 function, type, and variable definitions.
232 A reserved keyword. Normally, all occurrences of the keywords are
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
244 A builtin function or property. Normally, all occurrences of the
245 builtins are recognized.
248 A type specifier. The types are normally recognized from function,
249 type, and variable definitions.
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
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.
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.
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.
273 The foreground color of the face.
276 The background color of the face. This property is not implemented on
277 all output languages.
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.
285 * Highlighting Rules::
290 @node Highlighting Rules, Styles, Writing New Highlighting Definitions, Writing New Highlighting Definitions
291 @section Highlighting Rules
294 @node Styles, Output Languages, Highlighting Rules, Writing New Highlighting Definitions
297 @node Output Languages, , Styles, Writing New Highlighting Definitions
298 @section Output Languages
300 @deffn Function map_color (r, g, b)
303 @deffn Function language_print (string)
306 @deffn Function language_symbol (symbol)
309 @deffn Function header ()
312 @deffn Function trailer ()
315 @deffn Function face_on (face)
318 @deffn Function face_off (face)
321 @defvr Variable LANGUAGE_SPECIALS
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.
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.
339 state lang_simple_html
342 sub map_color (r, g, b)
344 return sprintf ("#%02X%02X%02X", r, g, b);
347 sub language_print (str)
349 str = regsuball (str, /\&/, "&");
350 str = regsuball (str, /</, "<");
351 str = regsuball (str, />/, ">");
352 str = regsuball (str, /\"/, """);
356 sub language_symbol (symbol)
363 print ("<html>\n<head>\n<title>Simple HTML Output</title>\n");
364 print ("</head>\n<body>\n");
369 print ("</body>\n</html>\n");
379 print ("<FONT COLOR=\", face[fg_color], "\">");
392 LANGUAGE_SPECIALS = /[<>\&\"]/;
399 @c ----------------------------------------------------------------------
401 @node Index, Documentation License, Writing New Highlighting Definitions, Top
406 @c ----------------------------------------------------------------------
408 @node Documentation License, , Index, Top
409 @appendix Documentation License
411 @include fdl-1.3.texi