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-1999 Markku Rossi.
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.
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
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.
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
49 @subtitle For version @value{VERSION}, @value{UPDATED}
53 @vskip 0pt plus 1filll
54 Copyright @copyright{} 1995-1998 Markku Rossi.
56 This is the first edition of the GNU enscript documentation,@*
57 and is consistent with GNU enscript @value{VERSION}.@*
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.
63 Permission is granted to copy and distribute modified versions of this
64 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.
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.
75 @node Top, Introduction, (dir), (dir)
76 @comment node-name, next, previous, up
79 This file documents the GNU enscript program. This edition documents
80 version @value{VERSION}.
87 * Configuration Files::
89 * The states Program::
90 * Writing New Highlighting Definitions::
96 @c ----------------------------------------------------------------------
97 @node Introduction, Invoking Enscript, Top, Top
105 @c ----------------------------------------------------------------------
106 @node Invoking Enscript, Basic Printing, Introduction, Top
107 @chapter Invoking Enscript
109 @c ----------------------------------------------------------------------
110 @node Basic Printing, Advanced Usage, Invoking Enscript, Top
111 @chapter Basic Printing
121 @node Input Encodings, Selecting Fonts, Basic Printing, Basic Printing
122 @section Input Encodings
124 @node Selecting Fonts, Page Headers, Input Encodings, Basic Printing
125 @section Selecting Fonts
127 @node Page Headers, Page Handling, Selecting Fonts, Basic Printing
128 @section Page Headers
130 @node Page Handling, Highlighting, Page Headers, Basic Printing
131 @section Page Handling
136 * Fitting Text to Page::
139 @node Page Orientation, N-up Printing, Page Handling, Page Handling
140 @subsection Page Orientation
142 @node N-up Printing, Fitting Text to Page, Page Orientation, Page Handling
143 @subsection N-up Printing
145 @node Fitting Text to Page, , N-up Printing, Page Handling
146 @subsection Fitting Text to Page
148 @node Highlighting, , Page Handling, Basic Printing
149 @section Highlighting
152 * Different Output Languages::
155 @node Different Output Languages, , Highlighting, Highlighting
156 @subsection Different Output Languages
158 @c ----------------------------------------------------------------------
159 @node Advanced Usage, Configuration Files, Basic Printing, Top
160 @chapter Advanced Usage
167 * PostScript Printer Controlling::
168 * Pass-Through Mode::
171 @node Selecting Pages, Escape Sequences, Advanced Usage, Advanced Usage
172 @section Selecting Pages
174 @node Escape Sequences, Input Filters, Selecting Pages, Advanced Usage
175 @section Escape Sequences
177 @node Input Filters, Slice Printing, Escape Sequences, Advanced Usage
178 @section Input Filters
180 @node Slice Printing, PostScript Printer Controlling, Input Filters, Advanced Usage
181 @section Slice Printing
183 @node PostScript Printer Controlling, Pass-Through Mode, Slice Printing, Advanced Usage
184 @section PostScript Printer Controlling
186 @node Pass-Through Mode, , PostScript Printer Controlling, Advanced Usage
187 @section Pass-Through Mode
189 @c ----------------------------------------------------------------------
190 @node Configuration Files, Customization, Advanced Usage, Top
191 @chapter Configuration Files
193 @c ----------------------------------------------------------------------
194 @node Customization, The states Program, Configuration Files, Top
195 @chapter Customization
199 * User-Defined Fancy Headers::
202 @node Output Media, User-Defined Fancy Headers, Customization, Customization
203 @section Output Media
205 @node User-Defined Fancy Headers, , Output Media, Customization
206 @section User-Defined Fancy Headers
209 @c ----------------------------------------------------------------------
210 @node The states Program, Writing New Highlighting Definitions, Customization, Top
211 @chapter The @samp{states} Program
213 @c ----------------------------------------------------------------------
214 @node Writing New Highlighting Definitions, Index, The states Program, Top
215 @chapter Writing New Highlighting Definitions
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
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.
234 A comment, normally in a programming language.
237 A function name. The function names are normally recognized from
238 function definitions, not from an use of the function.
241 A variable name. The variable names are normally recognized from
242 function, type, and variable definitions.
245 A reserved keyword. Normally, all occurrences of the keywords are
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
257 A builtin function or property. Normally, all occurrences of the
258 builtins are recognized.
261 A type specifier. The types are normally recognized from function,
262 type, and variable definitions.
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
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.
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.
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.
286 The foreground color of the face.
289 The background color of the face. This property is not implemented on
290 all output languages.
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 a set of functions which are called to generate the output.
298 * Highlighting Rules::
303 @node Highlighting Rules, Styles, Writing New Highlighting Definitions, Writing New Highlighting Definitions
304 @section Highlighting Rules
307 @node Styles, Output Languages, Highlighting Rules, Writing New Highlighting Definitions
310 @node Output Languages, , Styles, Writing New Highlighting Definitions
311 @section Output Languages
313 @deffn Function map_color (r, g, b)
316 @deffn Function language_print (string)
319 @deffn Function language_symbol (symbol)
322 @deffn Function header ()
325 @deffn Function trailer ()
328 @deffn Function face_on (face)
331 @deffn Function face_off (face)
334 @defvr Variable LANGUAGE_SPECIALS
337 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.
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.
352 state lang_simple_html
355 sub map_color (r, g, b)
357 return sprintf ("#%02X%02X%02X", r, g, b);
360 sub language_print (str)
362 str = regsuball (str, /\&/, "&");
363 str = regsuball (str, /</, "<");
364 str = regsuball (str, />/, ">");
365 str = regsuball (str, /\"/, """);
369 sub language_symbol (symbol)
376 print ("<html>\n<head>\n<title>Simple HTML Output</title>\n");
377 print ("</head>\n<body>\n");
382 print ("</body>\n</html>\n");
392 print ("<FONT COLOR=\", face[fg_color], "\">");
405 LANGUAGE_SPECIALS = /[<>\&\"]/;
412 @c ----------------------------------------------------------------------
414 @node Index, , Writing New Highlighting Definitions, Top