Savannah Git Hosting - enscript.git/blob

1 This is enscript.info, produced by makeinfo version 4.0 from

2 enscript.texi.

4 INFO-DIR-SECTION Utilities

5 START-INFO-DIR-ENTRY

6 * Enscript: (enscript). GNU Enscript

7 END-INFO-DIR-ENTRY

9 This file documents GNU enscript 1.6.4

13 Permission is granted to make and distribute verbatim copies of this

14 manual provided the copyright notice and this permission notice are

15 preserved on all copies.

17 Permission is granted to copy and distribute modified versions of

18 this manual under the conditions for verbatim copying, provided that

19 the entire resulting derived work is distributed under the terms of a

20 permission notice identical to this one.

22 Permission is granted to copy and distribute translations of this

23 manual into another language, under the above conditions for modified

24 versions, except that this permission notice may be stated in a

25 translation approved by the Foundation.

27 \1f

28 File: enscript.info, Node: Top, Next: Introduction, Prev: (dir), Up: (dir)

30 GNU enscript

31 ************

33 This file documents the GNU enscript program. This edition documents

34 version 1.6.4.

36 * Menu:

38 * Introduction::

39 * Invoking Enscript::

40 * Basic Printing::

41 * Advanced Usage::

42 * Configuration Files::

43 * Customization::

44 * The states Program::

45 * Writing New Highlighting Definitions::

46 * Index::

48 \1f

49 File: enscript.info, Node: Introduction, Next: Invoking Enscript, Prev: Top, Up: Top

51 Introduction

52 ************

54 * overall

56 * design

58 \1f

59 File: enscript.info, Node: Invoking Enscript, Next: Basic Printing, Prev: Introduction, Up: Top

61 Invoking Enscript

62 *****************

64 \1f

65 File: enscript.info, Node: Basic Printing, Next: Advanced Usage, Prev: Invoking Enscript, Up: Top

67 Basic Printing

68 **************

70 * Menu:

72 * Input Encodings::

73 * Selecting Fonts::

74 * Page Headers::

75 * Page Handling::

76 * Highlighting::

78 \1f

79 File: enscript.info, Node: Input Encodings, Next: Selecting Fonts, Prev: Basic Printing, Up: Basic Printing

81 Input Encodings

82 ===============

84 \1f

85 File: enscript.info, Node: Selecting Fonts, Next: Page Headers, Prev: Input Encodings, Up: Basic Printing

87 Selecting Fonts

88 ===============

90 \1f

91 File: enscript.info, Node: Page Headers, Next: Page Handling, Prev: Selecting Fonts, Up: Basic Printing

93 Page Headers

94 ============

96 \1f

97 File: enscript.info, Node: Page Handling, Next: Highlighting, Prev: Page Headers, Up: Basic Printing

99 Page Handling

100 =============

101

102 * Menu:

103

104 * Page Orientation::

105 * N-up Printing::

106 * Fitting Text to Page::

107

108 \1f

109 File: enscript.info, Node: Page Orientation, Next: N-up Printing, Prev: Page Handling, Up: Page Handling

110

111 Page Orientation

112 ----------------

113

114 \1f

115 File: enscript.info, Node: N-up Printing, Next: Fitting Text to Page, Prev: Page Orientation, Up: Page Handling

116

117 N-up Printing

118 -------------

119

120 \1f

121 File: enscript.info, Node: Fitting Text to Page, Prev: N-up Printing, Up: Page Handling

122

123 Fitting Text to Page

124 --------------------

125

126 \1f

127 File: enscript.info, Node: Highlighting, Prev: Page Handling, Up: Basic Printing

128

129 Highlighting

130 ============

131

132 * Menu:

133

134 * Different Output Languages::

135

136 \1f

137 File: enscript.info, Node: Different Output Languages, Prev: Highlighting, Up: Highlighting

138

139 Different Output Languages

140 --------------------------

141

142 \1f

143 File: enscript.info, Node: Advanced Usage, Next: Configuration Files, Prev: Basic Printing, Up: Top

144

145 Advanced Usage

146 **************

147

148 * Menu:

149

150 * Selecting Pages::

151 * Escape Sequences::

152 * Input Filters::

153 * Slice Printing::

154 * PostScript Printer Controlling::

155 * Pass-Through Mode::

156

157 \1f

158 File: enscript.info, Node: Selecting Pages, Next: Escape Sequences, Prev: Advanced Usage, Up: Advanced Usage

159

160 Selecting Pages

161 ===============

162

163 \1f

164 File: enscript.info, Node: Escape Sequences, Next: Input Filters, Prev: Selecting Pages, Up: Advanced Usage

165

166 Escape Sequences

167 ================

168

169 \1f

170 File: enscript.info, Node: Input Filters, Next: Slice Printing, Prev: Escape Sequences, Up: Advanced Usage

171

172 Input Filters

173 =============

174

175 \1f

176 File: enscript.info, Node: Slice Printing, Next: PostScript Printer Controlling, Prev: Input Filters, Up: Advanced Usage

177

178 Slice Printing

179 ==============

180

181 \1f

182 File: enscript.info, Node: PostScript Printer Controlling, Next: Pass-Through Mode, Prev: Slice Printing, Up: Advanced Usage

183

184 PostScript Printer Controlling

185 ==============================

186

187 \1f

188 File: enscript.info, Node: Pass-Through Mode, Prev: PostScript Printer Controlling, Up: Advanced Usage

189

190 Pass-Through Mode

191 =================

192

193 \1f

194 File: enscript.info, Node: Configuration Files, Next: Customization, Prev: Advanced Usage, Up: Top

195

196 Configuration Files

197 *******************

198

199 \1f

200 File: enscript.info, Node: Customization, Next: The states Program, Prev: Configuration Files, Up: Top

201

202 Customization

203 *************

204

205 * Menu:

206

207 * Output Media::

208 * User-Defined Fancy Headers::

209

210 \1f

211 File: enscript.info, Node: Output Media, Next: User-Defined Fancy Headers, Prev: Customization, Up: Customization

212

213 Output Media

214 ============

215

216 \1f

217 File: enscript.info, Node: User-Defined Fancy Headers, Prev: Output Media, Up: Customization

218

219 User-Defined Fancy Headers

220 ==========================

221

222 \1f

223 File: enscript.info, Node: The states Program, Next: Writing New Highlighting Definitions, Prev: Customization, Up: Top

224

225 The `states' Program

226 ********************

227

228 \1f

229 File: enscript.info, Node: Writing New Highlighting Definitions, Next: Index, Prev: The states Program, Up: Top

230

231 Writing New Highlighting Definitions

232 ************************************

233

234 The highlighting works in three separate phases. First, the

235 "highlighing rules" process the input stream and parse it into logical

236 components. The components are called "faces". A face presents one

237 logical component of the input language, for example, a keyword, a

238 comment, etc.. The enscript's highlighting model defines the following

239 faces:

240

241 bold

242 italic

243 bold_italic

244 Hard-coded faces for the bold, italic, and bold-italice text types.

245 These faces define the exact presentation of the face font, so the

246 style files have very little power in customizing their outlook.

247 These faces should be avoided as much as possible.

248

249 comment

250 A comment, normally in a programming language.

251

252 function_name

253 A function name. The function names are normally recognized from

254 function definitions, not from an use of the function.

255

256 variable_name

257 A variable name. The variable names are normally recognized from

258 function, type, and variable definitions.

259

260 keyword

261 A reserved keyword. Normally, all occurrences of the keywords are

262 recognized.

263

264 reference

265 A reference to another location in a file or to another file or

266 resource. For example, in the C-language, the goto targets are

267 references.

268

269 string

270 A string literal.

271

272 builtin

273 A builtin function or property. Normally, all occurrences of the

274 builtins are recognized.

275

276 type

277 A type specifier. The types are normally recognized from function,

278 type, and variable definitions.

279

280 As the second step, the "output style" specifies how the faces are

281 presented in the generated output. Each face has the following

282 properties:

283

284 fontname

285 The PostScript font name of the the font that is used for the face.

286 This property is used only for the PostScript outputs.

287

288 boldp

289 A boolean flag which tells whether the face should be printed in

290 bold font. This property is used for all output languages except

291 for the PostScript which uses the fontname property.

292

293 italicp

294 A boolean flag which tells whether the face shuold be printed with

295 italic font. This property is used for all output languages

296 except for the PostScript which uses the fontname property.

297

298 fg_color

299 The foreground color of the face.

300

301 bg_color

302 The background color of the face. This property is not

303 implemented on all output languages.

304

305 Finally, the "output language" describes how the faces and other

306 text are presented in the output language. The output language defines

307 a set of functions which are called to generate the output.

308

309 * Menu:

310

311 * Highlighting Rules::

312 * Styles::

313 * Output Languages::

314

315 \1f

316 File: enscript.info, Node: Highlighting Rules, Next: Styles, Prev: Writing New Highlighting Definitions, Up: Writing New Highlighting Definitions

317

318 Highlighting Rules

319 ==================

320

321 \1f

322 File: enscript.info, Node: Styles, Next: Output Languages, Prev: Highlighting Rules, Up: Writing New Highlighting Definitions

323

324 Styles

325 ======

326

327 \1f

328 File: enscript.info, Node: Output Languages, Prev: Styles, Up: Writing New Highlighting Definitions

329

330 Output Languages

331 ================

332

333 - Function: map_color (r, g, b)

334

335 - Function: language_print (string)

336

337 - Function: language_symbol (symbol)

338

339 - Function: header ()

340

341 - Function: trailer ()

342

343 - Function: face_on (face)

344

345 - Function: face_off (face)

346

347 - Variable: LANGUAGE_SPECIALS

348

349 The following example creates a new output language `simple_html'

350 that creates simple HTML outputs. The output language is defined in a

351 file called `lang_simple_html.st'. The file must define a state called

352 `lang_simple_html'. The file can be located in any directory that is

353 in the load path of the states program.

354

355 The output language definitions are defined in the `BEGIN' block of

356 the `lang_simple_html' state. Please, note that the `BEGIN' block is

357 ended with a `return'-statement. This statement will return the

358 control to the calling state that is the start state of the enscript

359 highlight program. If the `return'-statement was omitted, the states

360 would start processing the input with the `lang_simple_html' state

361 which is obviously a wrong choice.

362

363 state lang_simple_html

364 {

365 BEGIN {

366 sub map_color (r, g, b)

367 {

368 return sprintf ("#%02X%02X%02X", r, g, b);

369 }

370

371 sub language_print (str)

372 {

373 str = regsuball (str, /\&/, "&");

374 str = regsuball (str, /</, "<");

375 str = regsuball (str, />/, ">");

376 str = regsuball (str, /\"/, """);

377 print (str);

378 }

379

380 sub language_symbol (symbol)

381 {

382 return false;

383 }

384

385 sub header ()

386 {

387 print ("<html>\n<head>\n<title>Simple HTML Output</title>\n");

388 print ("</head>\n<body>\n");

389 }

390

391 sub trailer ()

392 {

393 print ("</body>\n</html>\n");

394 }

395

396 sub fase_on (face)

397 {

398 if (face(boldp])

399 print ("");

400 if (face(italicp])

401 print ("");

402 if (face[fg_color])

403 print ("");

404 }

405

406 sub face_off (face)

407 {

408 if (face[fg_color])

409 print ("");

410 if (face[italicp])

411 print ("");

412 if (face[boldp])

413 print ("");

414 }

415

416 LANGUAGE_SPECIALS = /[<>\&\"]/;

417

418 return;

419 }

420 }

421

422 \1f

423 File: enscript.info, Node: Index, Prev: Writing New Highlighting Definitions, Up: Top

424

425 Index

426 *****

427

428 * Menu:

429

430 * face_off: Output Languages.

431 * face_on: Output Languages.

432 * header: Output Languages.

433 * language_print: Output Languages.

434 * LANGUAGE_SPECIALS: Output Languages.

435 * language_symbol: Output Languages.

436 * map_color: Output Languages.

437 * trailer: Output Languages.

438

439

440 \1f

441 Tag Table:

442 Node: Top\7f932

443 Node: Introduction\7f1333

444 Node: Invoking Enscript\7f1479

445 Node: Basic Printing\7f1619

446 Node: Input Encodings\7f1857

447 Node: Selecting Fonts\7f2005

448 Node: Page Headers\7f2151

449 Node: Page Handling\7f2289

450 Node: Page Orientation\7f2500

451 Node: N-up Printing\7f2647

452 Node: Fitting Text to Page\7f2795

453 Node: Highlighting\7f2932

454 Node: Different Output Languages\7f3087

455 Node: Advanced Usage\7f3240

456 Node: Selecting Pages\7f3523

457 Node: Escape Sequences\7f3672

458 Node: Input Filters\7f3822

459 Node: Slice Printing\7f3965

460 Node: PostScript Printer Controlling\7f4124

461 Node: Pass-Through Mode\7f4319

462 Node: Configuration Files\7f4465

463 Node: Customization\7f4612

464 Node: Output Media\7f4809

465 Node: User-Defined Fancy Headers\7f4957

466 Node: The states Program\7f5111

467 Node: Writing New Highlighting Definitions\7f5281

468 Node: Highlighting Rules\7f8119

469 Node: Styles\7f8311

470 Node: Output Languages\7f8459

471 Node: Index\7f10994

472 \1f

473 End Tag Table