« back to all changes in this revision
Viewing changes to html2psrc.5
- browse files at revision 1
- compare with another revision
- download diff
- download tarball
- view history from revision 1
- Committer: Bazaar Package Importer
- Author(s): Matt Zimmerman
- Date: 2002-11-22 19:21:17 UTC
- Revision ID: james.westby@ubuntu.com-20021122192117-gc4bl1um1pvnixh3
Tags: upstream-1.0b3
Import upstream version 1.0b3
- files added:
- contrib
- contrib/xhtml2ps
added
removed
html2psrc.5
1
.\" @(#)html2psrc.5
2
.\"
3
.TH html2psrc 5 "15 Aug 2000" "Autogenerated" "html2ps configuration file format"
4
.SH NAME
5
html2psrc - configuration file format for html2ps(1)
6
.SH DESCRIPTION
7
8
Configuration files are used for layout control, resource information
9
etc. Normally, there should always exist a global configuration file.
10
In this file one typically specify things like: what image conversion
11
packages are available on the system, the default paper size, the default
12
text fonts and sizes, etc.
13
.PP
14
For Unix and Windows systems, the installation script 'install' can be
15
used to automatically build a global configuration file with all necessary
16
definitions, and install all files. The files replaced by the installation
17
are saved. If you for some reason are not satisfied with the new version:
18
execute the script 'backout' to reinstall your earlier version.
19
.PP
20
On other systems, you will have to manually create a global
21
configuration file, and insert the name of this file into the
22
html2ps script (close to the beginning, the line starting with
23
"$globrc="). The configuration file should contain a
24
package block, and perhaps
25
paper and
26
hyphenation blocks, described below.
27
.PP
28
Each user can then have a personal configuration file (by default
29
$HOME/.html2psrc) that complements/overrides the definitions made in the
30
global file. It is also possible to specify alternative files on the
31
command line, using the -f option.
32
.SH FILE FORMAT
33
.PP
34
A configuration file can include other configuration files. This is done with:
35
.RS
36
.PD
37
.PP
38
.PD 0
39
.RE
40
.RS .3i
41
.PP
42
@import "\fIfilename\fP";
43
.RE
44
.PD
45
.PP
46
.PP
47
The rest of the configuration file consists of zero or more blocks.
48
A block is given by a block name, followed by the block definition, as in:
49
.RS
50
.RE
51
.RS .0i
52
.PD
53
.PP
54
.PD 0
55
.RE
56
.RS .3i
57
.PP
58
BODY {
59
.RE
60
.RS .5i
61
.PP
62
font-size: 12pt;
63
.PP
64
font-family: Helvetica;
65
.PP
66
text-align: justify
67
.RE
68
.RS .3i
69
.PP
70
}
71
.RE
72
.PD
73
.PP
74
.PP
75
The block definition, enclosed by curly braces: { }, consists of
76
key-value pairs and/or other blocks. A key-value pair consists of the key
77
name followed by a colon, followed by the value. Blocks and key-value pairs
78
are separated by semicolons. The semicolon may be omitted after a block.
79
.PP
80
Several blocks can share the same definition. The block names are then
81
separated be commas, as in:
82
.RS
83
.RE
84
.RS .0i
85
.PD
86
.PP
87
.PD 0
88
.RE
89
.RS .3i
90
.PP
91
H2, H4, H6 { font-style: italic }
92
.RE
93
.PD
94
.PP
95
.PP
96
A comment in a configuration file starts with the characters
97
"/*" and ends with "*/":
98
.RS
99
.RE
100
.RS .0i
101
.PD
102
.PP
103
.PD 0
104
.RE
105
.RS .3i
106
.PP
107
@html2ps {
108
.RE
109
.RS .5i
110
.PP
111
seq-number: 1; /* Automatic numbering of headings */
112
.RE
113
.RS .3i
114
.PP
115
}
116
.RE
117
.PD
118
.PP
119
Notations
120
.PP
121
.PP
122
Here are some definitions of terms used below:
123
.LP
124
.RS
125
.PD 0
126
.TP
127
.B Flag:
128
A value of either 0 (absence, inactive etc) or 1 (presence, active etc).
129
.TP
130
.B Absolute size:
131
A real number optionally followed by one of the following two-letter
132
unit identifiers: cm (centimeters), mm (millimeters), in (inches),
133
pt (points, 1pt = 1/72 inch), pc (picas, 1pc = 12pt). The default
134
unit is centimeters.
135
.TP
136
.B Relative size:
137
A size relative to current fontsize. The default and currently only
138
recognized unit is em. One em equals the size of the current font.
139
The value should be given as a real number, optionally followed by 'em',
140
as in '0.25em'.
141
.TP
142
.B Whitespace:
143
Any one of the characters: space, tab, newline, or carriage return.
144
.RE
145
.PD
146
.PP
147
CSS2 blocks
148
.PP
149
.PP
150
All blocks, except one: the @html2ps
151
block, coincides with a subset of the
152
Cascading Style Sheets, level 2 CSS2 Specification (http://www.w3.org/TR/REC-CSS2/).
153
The following default settings for html2ps illustrate just about everything
154
that currently can be used from the CSS2 specification:
155
.RS
156
.RE
157
.RS .0i
158
.PD
159
.PP
160
.PD 0
161
.RE
162
.RS .3i
163
.PP
164
BODY {
165
.RE
166
.RS .5i
167
.PP
168
font-family: Times;
169
.PP
170
font-size: 11pt;
171
.PP
172
text-align: left;
173
.PP
174
background: white;
175
.RE
176
.RS .3i
177
.PP
178
}
179
.PD
180
.PP
181
.PD 0
182
.PP
183
H1, H2, H3, H4, H5, H6 {
184
.RE
185
.RS .5i
186
.PP
187
font-weight: bold;
188
.PP
189
margin-top: 0.8em;
190
.PP
191
margin-bottom: 0.5em;
192
.RE
193
.RS .3i
194
.PP
195
}
196
.PP
197
H1 { font-size: 19pt }
198
.PP
199
H2 { font-size: 17pt }
200
.PP
201
H3 { font-size: 15pt }
202
.PP
203
H4 { font-size: 13pt }
204
.PP
205
H5 { font-size: 12pt }
206
.PP
207
H6 { font-size: 11pt }
208
.PD
209
.PP
210
.PD 0
211
.PP
212
P, OL, UL, DL, BLOCKQUOTE, PRE {
213
.RE
214
.RS .5i
215
.PP
216
margin-top: 1em;
217
.PP
218
margin-bottom: 1em;
219
.RE
220
.RS .3i
221
.PP
222
}
223
.PD
224
.PP
225
.PD 0
226
.PP
227
P {
228
.RE
229
.RS .5i
230
.PP
231
line-height: 1.2em;
232
.PP
233
text-indent: 0;
234
.RE
235
.RS .3i
236
.PP
237
}
238
.PD
239
.PP
240
.PD 0
241
.PP
242
OL, UL, DD { margin-left: 2em }
243
.PD
244
.PP
245
.PD 0
246
.PP
247
TT, KBD, PRE { font-family: Courier }
248
.PD
249
.PP
250
.PD 0
251
.PP
252
PRE { font-size: 9pt }
253
.PD
254
.PP
255
.PD 0
256
.PP
257
BLOCKQUOTE {
258
.RE
259
.RS .5i
260
.PP
261
margin-left: 1em;
262
.PP
263
margin-right: 1em;
264
.RE
265
.RS .3i
266
.PP
267
}
268
.PD
269
.PP
270
.PD 0
271
.PP
272
ADDRESS {
273
.RE
274
.RS .5i
275
.PP
276
margin-top: 0.5em;
277
.PP
278
margin-bottom: 0.5em;
279
.RE
280
.RS .3i
281
.PP
282
}
283
.PD
284
.PP
285
.PD 0
286
.PP
287
TABLE {
288
.RE
289
.RS .5i
290
.PP
291
margin-top: 1.3em;
292
.PP
293
margin-bottom: 1em;
294
.RE
295
.RS .3i
296
.PP
297
}
298
.PD
299
.PP
300
.PD 0
301
.PP
302
DIV.noprint { display: none }
303
.PD
304
.PP
305
.PD 0
306
.PP
307
DEL { text-decoration: line-through }
308
.PD
309
.PP
310
.PD 0
311
.PP
312
A:link, HR { color: black }
313
.PD
314
.PP
315
.PD 0
316
.PP
317
@page {
318
.RE
319
.RS .5i
320
.PP
321
margin-left: 2.5cm;
322
.PP
323
margin-right: 2.5cm;
324
.PP
325
margin-top: 3cm;
326
.PP
327
margin-bottom: 3cm;
328
.RE
329
.RS .3i
330
.PP
331
}
332
.RE
333
.PD
334
.PP
335
.PP
336
The program specific block \fI@html2ps\fP:
337
.PP
338
This block is used to specify parameters that are specific to
339
html2ps, and not covered by CSS2. The @html2ps block has
340
several sub-blocks and key-value pairs, these are described in this section.
341
.TP
342
The \fIpackage\fP block
343
.RS .5i
344
This block is used to specify which program
345
packages are installed on the system. Typically, this is done in the
346
global configuration file.
347
.TP
348
.B PerlMagick
349
A flag specifying whether the Perl module PerlMagick is installed
350
or not. The default is 0.
351
.TP
352
.B ImageMagick
353
A flag specifying whether the ImageMagick package is installed
354
or not. The default is 0.
355
.TP
356
.B pbmplus
357
A flag specifying whether the pbmplus package is installed
358
or not. The default is 0.
359
.TP
360
.B netpbm
361
A flag specifying whether the netpbm package is installed
362
or not. The default is 0.
363
.TP
364
.B djpeg
365
A flag specifying whether djpeg is installed or not.
366
The default is 0.
367
.TP
368
.B Ghostscript
369
A flag specifying whether Ghostscript is installed or not.
370
The default is 0.
371
.TP
372
.B TeX
373
A flag specifying whether the TeX package is installed or not.
374
The default is 0.
375
.TP
376
.B dvips
377
A flag specifying whether dvips is installed or not.
378
The default is 0.
379
.TP
380
.B libwww-perl
381
A flag specifying whether the Perl module library libwww-perl
382
is installed or not. The default is 0.
383
.TP
384
.B jfriedl
385
A flag specifying whether the Perl scripts www.pl and network.pl
386
(by Jeffrey Friedl) are installed or not. The default is 0.
387
.TP
388
.B geturl
389
When neither of the Perl packages for retrieving remote documents
390
are available, it is possible to use some other program like lynx or
391
url_get. This value should be set to a command that retrieves a document
392
with a complete MIME header, such as "lynx -source
393
-mime_header" or "url_get -h".
394
.TP
395
.B check
396
The name of a program used for syntax checking HTML documents.
397
No default, a good choice is weblint.
398
.TP
399
.B path
400
A colon separated list of directories where the executables from
401
the program packages are. It is only necessary to include directories
402
that are not in the PATH for a typical user.
403
.RE
404
.TP
405
The \fIpaper\fP block
406
.RS .5i
407
The paper size is defined in this block. The size can either be
408
given as one of the recognized paper types or by giving explicit values for
409
the paper height and width. As of version 1.0 beta2, one can also use the
410
@page block in CSS2
411
for the paper size. The paper block is kept for backwards compatibility.
412
Also, one can only specify explicit dimensions in @page, not any paper
413
types by name.
414
.TP
415
.B type
416
Paper type, possible choices are: A0, A1, A2, A3, A4,...,A10,
417
B0, B1,...,B10, letter, legal, arche, archd, archc, archb, archa,
418
flsa, flse, halfletter, 11x17, and ledger (this set of paper types
419
is taken from Aladdin Ghostscript). The default is A4.
420
.TP
421
.B height
422
An absolute size specifying the paper height.
423
.TP
424
.B width
425
An absolute size specifying the paper width.
426
.RE
427
.TP
428
The \fIoption\fP block
429
.RS .5i
430
This block is used to set default values for the command line
431
options. The key in the key-value pair is the option name, in either its
432
long or short form.
433
.TP
434
.B twoup
435
Two column (2-up) output. The default is one column per page.
436
.TP
437
.B base
438
Use \fIURL\fP as a base to expand relative references for in-line
439
images. This is useful if you have downloaded a document to a local file.
440
The \fIURL\fP should then be the \fIURL\fP of the original document.
441
.TP
442
.B check
443
Check the syntax of the HTML file (using an external syntax
444
checker). The default is to not make a syntax check.
445
.TP
446
.B toc
447
Generate a table of contents (ToC). The value should be a string
448
consisting of one of the letters 'f', 'h', or 't', optionally combined
449
with the letter 'b':
450
.LP
451
.RS
452
.PD 0
453
.TP
454
.B b
455
The ToC will be printed first. This requires that Ghostscript is
456
installed.
457
.TP
458
.B f
459
The ToC will be generated from the links in the converted document.
460
.TP
461
.B h
462
The ToC will be generated from headings and
463
titles in the converted documents. Note that if the document author
464
for some strange reason has chosen to use some other means to represent
465
the headings than the HTML elements H1,...,H6, you are out of luck!
466
.TP
467
.B t
468
The ToC will be generated from links having the attribute
469
rev=TOC in the converted document.
470
.RE
471
.PD
472
.PP
473
.TP
474
.B debug
475
Generate debugging information. You should always use this
476
option when reporting problems with html2ps.
477
.TP
478
.B DSC
479
Generate DSC compliant PostScript. This requires Ghostscript and
480
can take quite some time to do. Note that a PostScript file generated
481
with this option cannot be used as input to html2ps for reformatting
482
later.
483
.TP
484
.B encoding
485
The document encoding. Currently recognized values are ISO-8859-1,
486
EUC-JP, SHIFT-JIS, and ISO-2022-JP (other EUC-xx encodings may also
487
work). The default is ISO-8859-1.
488
.TP
489
.B rcfile
490
A colon separated list of configuration file names to use
491
instead of the default personal configuration file $HOME/.html2psrc.
492
Definitions made in one file override definitions in previous files
493
(the last file in the list has highest precedence). An empty file
494
name (as in ':file', 'file1::file3', or 'file:') will expand to the
495
default personal file. The environment variable HTML2PSPATH is used
496
to specify the directories where to search for these files. (Note:
497
this is only supposed to be used on the command line, not
498
in a configuration file.)
499
.TP
500
.B frame
501
Draw a frame around the text on each page. The default is
502
to not draw a frame.
503
.TP
504
.B grayscale
505
Convert colour images to grayscale images. Note that the
506
PostScript file will be smaller when the images are converted to
507
grayscale. The default is to generate colour images.
508
.TP
509
.B help
510
Show usage information.
511
.TP
512
.B hyphenate
513
Hyphenate the text. This requires TeX
514
hyphenation pattern files.
515
.TP
516
.B scaleimage
517
Scale in-line images with a factor \fInum\fP.
518
The default is 1.
519
.TP
520
.B cookie
521
Enable cookie support, using a netscape formatted cookie
522
\fIfile\fP (requires libwww-perl).
523
.TP
524
.B language
525
Specifies the language of the document
526
(overrides an eventual LANG attribute of the BODY element).
527
The language should be given according to
528
RFC1766 (ftp://ftp.nordu.net/rfc/rfc1766.txt) and
529
ISO 639 (http://www.oasis-open.org/cover/iso639a.html).
530
.TP
531
.B landscape
532
Generate code for printing in landscape mode. The default
533
is portrait mode.
534
.TP
535
.B scalemath
536
Scale mathematical formulas with a factor \fInum\fP.
537
The default is 1.
538
.TP
539
.B number
540
Insert page numbers. The default is to not number the pages.
541
.TP
542
.B startno
543
Specifies the starting page number, the default is 1.
544
.TP
545
.B output
546
Write the PostScript code to \fIfile.\fP The default is
547
to write to standard output.
548
.TP
549
.B original
550
Use PostScript original images if they exist. For example, if a
551
document contains an image figure.gif, and an encapsulated PostScript
552
file named figure.ps exists in the same directory, that file will be
553
use instead. This only work for documents read as local files. Note:
554
if the PostScript file is large or contains bitmap images, this must
555
be combined with the -D option. In HTML 4.0 this can be achieved in a
556
much better way with:
557
.RS
558
.RE
559
.RS .0i
560
.PD
561
.PP
562
.PD 0
563
.RE
564
.RS .3i
565
.PP
566
<OBJECT data="figure.ps" type="application/postscript">
567
.RE
568
.RS .4i
569
.PP
570
<OBJECT data="figure.gif" type="image/gif">
571
.RE
572
.RS .5i
573
.PP
574
<PRE>[Maybe some ASCII art for text browsers]</PRE>
575
.RE
576
.RS .4i
577
.PP
578
</OBJECT>
579
.RE
580
.RS .3i
581
.PP
582
</OBJECT>
583
.RE
584
.PD
585
.PP
586
.TP
587
.B rootdir
588
When a document is read from a local file, this value specifies
589
a base directory for resolving relative links starting with "/".
590
Typically, this should be the directory where your web server's home
591
page resides.
592
.TP
593
.B xref
594
Insert cross references at every link to
595
within the set of converted documents.
596
.TP
597
.B scaledoc
598
Scale the entire document with a factor \fInum\fP.
599
The default is 1.
600
.TP
601
.B style
602
This option complements/overrides definitions made in the
603
configuration files. The \fIstring\fP must follow the configuration
604
file syntax. (Note: this is only supposed to be used on the
605
command line, not in a configuration file.)
606
.TP
607
.B titlepage
608
Generate a title page. The default is to not generate one.
609
.TP
610
.B text
611
Text mode, ignore images. The default is to include the images.
612
.TP
613
.B underline
614
Underline text that constitutes a hypertext link. The default
615
is to not underline.
616
.TP
617
.B colour
618
Produce colour output for text and background, when specified.
619
The default is black text on white background (mnemonic: coloUr ;-).
620
.TP
621
.B version
622
Print information about the current version of html2ps.
623
.TP
624
.B web
625
Process a web of documents by recursively retrieve and convert
626
documents that are referenced with hyperlinks. When dealing with remote
627
documents it will of course be necessary to impose restrictions, to
628
avoid downloading the entire web... The value should be a string
629
consisting of one of the letters 'a', 'b', 'l', 'r', or 's', optionally
630
combined with a combination of the letters 'p', 'L', and a positive
631
integer:
632
.LP
633
.RS
634
.PD 0
635
.TP
636
.B a
637
Follow all links.
638
.TP
639
.B b
640
Follow only links to within the same directory, or below, as the
641
start document.
642
.TP
643
.B l
644
Follow only links specified with
645
"<LINK rel=NEXT>" in the document.
646
.TP
647
.B p
648
Prompt for each remote document. This mode will automatically be
649
entered after the first 50 documents.
650
.TP
651
.B r
652
Follow only relative links.
653
.TP
654
.B s
655
Follow only links to within the same server as the start document.
656
.TP
657
.B L
658
With this option, the order in which the documents are processed will
659
be: first all top level documents, then the documents linked to from
660
these etc. For example, if the document A has links to B and C, and
661
B has a link to D, the order will be A-B-C-D.
662
By default, each document will be followed by the first document
663
it links to etc; so the default order for the example is
664
A-B-D-C.
665
.TP
666
.B #
667
A positive integer giving the number of recursive levels. The
668
default is 4 (when the option is present).
669
.RE
670
.PD
671
.PP
672
.TP
673
.B duplex
674
Generate postscript code for single or double sided printing.
675
No default, valid values are:
676
.LP
677
.RS
678
.PD 0
679
.TP
680
.B 0
681
Single sided.
682
.TP
683
.B 1
684
Double sided.
685
.TP
686
.B 2
687
Double sided, opposite page reversed (tumble mode).
688
.RE
689
.PD
690
.PP
691
.RE
692
.TP
693
The \fImargin\fP block
694
.RS .5i
695
This block is used to specify page margins. The left, right, top
696
and bottom margins, previously defined with this block, should now be
697
defined using the @page
698
construction from CSS2.
699
.TP
700
.B middle
701
An absolute size for the distance between the columns when
702
printing two columns per page, default is 2cm.
703
.RE
704
.TP
705
The \fIxref\fP block
706
.RS .5i
707
At every hyperlink (to within the set of converted documents)
708
it is possible to have a cross reference inserted. The \fIxref\fP
709
block is used to control this function.
710
.TP
711
.B text
712
This defines the cross reference text to be inserted; the symbol
713
$N will expand to the page number, default is "[p $N]".
714
.TP
715
.B passes
716
The number of passes used to insert the cross references.
717
Normally, only one pass is run. But since the insertion of the page
718
numbers may effect the page breaks, it might for large documents with
719
many links be necessary with more than one pass to get the cross
720
references right. The default is 1.
721
.RE
722
.TP
723
The \fIquote\fP block
724
.RS .5i
725
Language specific quotation marks are defined in this block.
726
These quotation marks are used with the HTML 4.01 element Q for short
727
quotations. Quotation marks are predefined for a few languages (English,
728
Swedish, Danish, Norwegian (also Nynorsk and Bokm�l), Finnish, Spanish,
729
French, German and Italian). It is possible to define different quotation
730
marks for quotes within quotes.
731
.PP
732
A quotation mark is defined as a string, using the same encoding as the
733
converted document (normally ISO-8859-1), and/or with character entities.
734
Note that quotation mark characters for several languages are not
735
included in ISO-8859-1, and their corresponding character entities were
736
not been defined prior to HTML 4.0.
737
.PP
738
Quotation marks for a language can be defined explicitly in a sub-block
739
of the quote block. One can also identify the set of quotation
740
marks with another previously defined language, using a key-value pair.
741
The sub-block/key name should equal the language code as defined in
742
ISO 639. The language sub-block can have the following key-values:
743
.LP
744
.RS
745
.PD 0
746
.TP
747
.B open
748
The quote opening character(s).
749
.TP
750
.B close
751
The quote closing character(s). If undefined, it will equal
752
open.
753
.TP
754
.B open2
755
The quote opening character(s) for quotes within quotes. If undefined,
756
it will equal open.
757
.TP
758
.B close2
759
The quote closing character(s) for quotes within quotes. If undefined,
760
it will equal close.
761
.RE
762
.PD
763
.PP
764
.PP
765
Example: English and Spanish use the same set of quotation marks -
766
at least according to my book on typography. These (already known to
767
html2ps) are defined with:
768
.RS
769
.RE
770
.RS .0i
771
.PD
772
.PP
773
.PD 0
774
.RE
775
.RS .3i
776
.PP
777
quote {
778
.RE
779
.RS .5i
780
.PP
781
en {
782
.RE
783
.RS .7i
784
.PP
785
open: "“";
786
.PP
787
close: "”";
788
.PP
789
open2: "`";
790
.PP
791
close2: "'";
792
.RE
793
.RS .5i
794
.PP
795
}
796
.PP
797
es: en;
798
.RE
799
.RS .3i
800
.PP
801
}
802
.RE
803
.PD
804
.PP
805
.RE
806
.TP
807
The \fItoc\fP block
808
.RS .5i
809
When a table of contents (ToC) is generated from document
810
headings and titles, the appearance is controlled by this block.
811
.TP
812
.B heading
813
A string with HTML code specifying a heading used on the first
814
ToC page.
815
.TP
816
.B level
817
The maximum heading level used for building the ToC. The
818
default is 6, which means that all headings will generate
819
ToC entries.
820
.TP
821
.B indent
822
The ToC entries are indented proportional to the corresponding
823
heading level. This value specifies the size of the indentation.
824
The default is 1em.
825
.RE
826
.TP
827
The \fItitlepage\fP block
828
.RS .5i
829
When a title page is generated, its appearance is controlled by
830
this block.
831
.TP
832
.B content
833
A string with HTML code specifying a heading used on the
834
title page, The default is
835
"<DIV align=center>
836
<H1><BIG>$T</BIG></H1>
837
<H2>$[author]</H2></DIV>".
838
.TP
839
.B margin-top
840
The size of the top margin on the title page,
841
The default is 4cm.
842
.RE
843
.TP
844
The \fIfont\fP block
845
.RS .5i
846
Currently, html2ps recognizes the fonts: Times,
847
New-Century-Schoolbook, Helvetica, Helvetica-Narrow, Palatino, Avantgarde,
848
Bookman, and Courier. To add a new font (family), choose a name (consisting
849
of letters, digits, hyphens, and underscores) for the font. Then define a
850
sub-block to the font block, with the same name as the chosen
851
font name. This block can contain two key-value pairs:
852
.LP
853
.RS
854
.PD 0
855
.TP
856
.B names
857
A string containing four PostScript font names, separated by
858
whitespace, corresponding to the font styles normal, italic, bold, and
859
bold-italic. If less than four names are given, the first is used for
860
the missing names. Note that PostScript font names are case sensitive.
861
.TP
862
.B files
863
A string of four file names, separated by whitespace, for files
864
containing font definitions for the four font styles as specified above.
865
.RE
866
.PD
867
.PP
868
.PP
869
Example: A font 'myfont' has its four font styles defined in local files.
870
To use this font in all tables in the converted documents, one can use
871
something like:
872
.RS
873
.RE
874
.RS .0i
875
.PD
876
.PP
877
.PD 0
878
.RE
879
.RS .3i
880
.PP
881
TABLE { font-family: myfont }
882
.PD
883
.PP
884
.PD 0
885
.PP
886
@html2ps {
887
.RE
888
.RS .5i
889
.PP
890
font {
891
.RE
892
.RS .7i
893
.PP
894
myfont {
895
.RE
896
.RS .9i
897
.PP
898
names: "MyFont-Roman MyFont-Italic MyFont-Bold MyFont-BoldItalic";
899
.PP
900
files: "/x/y/myfr.pfa /x/y/myfi.pfa /x/y/myfb.pfa /x/y/myfbi.pfa";
901
.RE
902
.RS .7i
903
.PP
904
}
905
.RE
906
.RS .5i
907
.PP
908
}
909
.RE
910
.RS .3i
911
.PP
912
}
913
.RE
914
.PD
915
.PP
916
.RE
917
.TP
918
The \fIhyphenation\fP block
919
.RS .5i
920
Hyphenation pattern files for different languages are specified
921
in sub-blocks within this block. The blocks names should equal the
922
language code as defined in ISO 639. These language blocks can contain
923
the following two key-values:
924
.LP
925
.RS
926
.PD 0
927
.TP
928
.B file
929
A hyphenation pattern file in TeX format for this language.
930
.TP
931
.B extfile
932
A file containing a list of hyphenation exceptions for this language.
933
The exception file should contain words, separated by whitespaces, with
934
hyphens inserted where hyphenation is allowed, as in:
935
"in-fra-struc-ture white-space".
936
.RE
937
.PD
938
.PP
939
.PP
940
For example, for English (with language code 'en') one can have a block
941
like:
942
.RS
943
.RE
944
.RS .0i
945
.PD
946
.PP
947
.PD 0
948
.RE
949
.RS .7i
950
.PP
951
en {
952
.RE
953
.RS .9i
954
.PP
955
file: "/opt/tex/lib/macros/hyphen.tex";
956
.PP
957
extfile: "/opt/tdb/lib/html2ps/enhyphext";
958
.RE
959
.RS .7i
960
.PP
961
}
962
.RE
963
.PD
964
.PP
965
.PP
966
The hyphenation block itself can furthermore have these
967
key-values:
968
.TP
969
.B min
970
A positive integer defining the minimum number of letters a word
971
must contain to make it a candidate for hyphenation.
972
The default is 8.
973
.TP
974
.B start
975
A positive integer defining the minimum number of letters that
976
must precede the hyphen when a word is hyphenated.
977
The default is 4.
978
.TP
979
.B end
980
A positive integer defining the minimum number of letters that
981
must follow the hyphen when a word is hyphenated.
982
The default is 3.
983
.RE
984
.TP
985
The \fIheader\fP block
986
.RS .5i
987
This block is used to specify page headers. It is possible to
988
define left, center, and right headers. Different headers for odd and even
989
pages can be specified. Some symbols can be used that will expand to
990
document title, author, date etc. See below.
991
.TP
992
.B left
993
A left aligned header. If the alternate flag in this
994
block is set to 1, this will be the right header on even pages.
995
.TP
996
.B center
997
A centered header.
998
.TP
999
.B right
1000
A right aligned header. If the alternate flag in this
1001
block is set to 1, this will be the left header on even pages.
1002
.TP
1003
.B odd-left
1004
A left aligned header on odd pages.
1005
.TP
1006
.B odd-center
1007
A centered header on odd pages.
1008
.TP
1009
.B odd-right
1010
A right aligned header on odd pages.
1011
.TP
1012
.B even-left
1013
A left aligned header on even pages.
1014
.TP
1015
.B even-center
1016
A centered header on even pages.
1017
.TP
1018
.B even-right
1019
A right aligned header on even pages.
1020
.TP
1021
.B font-family
1022
The font used for the header, default is Helvetica.
1023
.TP
1024
.B font-size
1025
The font size for the header, default is 8pt.
1026
.TP
1027
.B font-style
1028
The default is "normal".
1029
.TP
1030
.B font-weight
1031
The default is "normal".
1032
.TP
1033
.B color
1034
The header color, default is black.
1035
.TP
1036
.B alternate
1037
A flag indicating whether the headers given by the
1038
left and right keys should change place on
1039
even pages. Typically used for double sided printing.
1040
The default is 1.
1041
.RE
1042
.TP
1043
The \fIfooter\fP block
1044
.RS .5i
1045
This block is used to specify page footers. It is possible to
1046
define left, center, and right footers. Different footers for odd and even
1047
pages can be specified. Some symbols can be used that will expand to
1048
document title, author, date etc. See below.
1049
.TP
1050
.B left
1051
A left aligned footer. If the alternate flag in
1052
this block is set to 1, this will be the right footer on even pages.
1053
.TP
1054
.B center
1055
A centered footer.
1056
.TP
1057
.B right
1058
A right aligned footer. If the alternate flag in
1059
this block is set to 1, this will be the left footer on even pages.
1060
.TP
1061
.B odd-left
1062
A left aligned footer on odd pages.
1063
.TP
1064
.B odd-center
1065
A centered footer on odd pages.
1066
.TP
1067
.B odd-right
1068
A right aligned footer on odd pages.
1069
.TP
1070
.B even-left
1071
A left aligned footer on even pages.
1072
.TP
1073
.B even-center
1074
A centered footer on even pages.
1075
.TP
1076
.B even-right
1077
A right aligned footer on even pages.
1078
.TP
1079
.B font-family
1080
The font used for the footer, default is Helvetica.
1081
.TP
1082
.B font-size
1083
The font size for the footer, default is 8pt.
1084
.TP
1085
.B font-style
1086
The default is "normal".
1087
.TP
1088
.B font-weight
1089
The default is "normal".
1090
.TP
1091
.B color
1092
The footer color, default is black.
1093
.TP
1094
.B alternate
1095
A flag indicating whether the footers given by the
1096
left and right keys should change place on
1097
even pages. Typically used for double sided printing.
1098
The default is 1.
1099
.RE
1100
.TP
1101
The \fIframe\fP block
1102
.RS .5i
1103
The appearance of the optional frame (drawn on each page) is
1104
controlled by this block.
1105
.TP
1106
.B width
1107
The width of the frame, default is 0.6pt.
1108
.TP
1109
.B margin
1110
The size of the frame margin, default is 0.5cm.
1111
.TP
1112
.B color
1113
The colour of the frame, default is black.
1114
.RE
1115
.TP
1116
The \fIjustify\fP block
1117
.RS .5i
1118
This block specifies the maximum amount of extra space inserted
1119
between words and letters when text justification is in effect.
1120
.TP
1121
.B word
1122
Maximum amount of extra space inserted between words.
1123
The default is 15pt.
1124
.TP
1125
.B letter
1126
Maximum amount of extra space inserted between letters
1127
within words. The default is 0pt.
1128
.RE
1129
.TP
1130
The \fIdraft\fP block
1131
.RS .5i
1132
It is possible to have some text written in a large font diagonally
1133
across each page. Typically this is a word, written in a very light colour,
1134
indicating that the document is a draft.
1135
.TP
1136
.B text
1137
The text to be printed, default is "DRAFT".
1138
.TP
1139
.B print
1140
A flag specifying whether the draft text should be printed or not.
1141
If unspecified, the draft text is printed when the document head contains
1142
<META name="Status" content="Draft">.
1143
.TP
1144
.B dir
1145
Specifies print direction, 0=downwards, 1=upwards.
1146
.TP
1147
.B font-family
1148
The default is Helvetica.
1149
.TP
1150
.B font-style
1151
The default is "normal".
1152
.TP
1153
.B font-weight
1154
The default is "bold".
1155
.TP
1156
.B color
1157
The default is "F0F0F0".
1158
.RE
1159
.TP
1160
The \fIcolour\fP block
1161
.RS .5i
1162
The 16 standard colour names from HTML 4.01 (although their
1163
use in HTML elements are now deprecated) are recognized by html2ps.
1164
Use this block to extend this list of colours. This is done with
1165
key-value pairs, where the key is the colour name, and the value is
1166
the colour given as a hexadecimal RGB value, for example: "brown:
1167
A52A2A;".
1168
.RE
1169
.B Key-value pairs in the @html2ps block
1170
.TP
1171
.B html2psrc
1172
The name of the default personal configuration file.
1173
The default is $HOME/.html2psrc.
1174
.TP
1175
.B imgalt
1176
Specifies which text should be written as a replacement
1177
for in-line images when the IMG element has no ALT attribute.
1178
The default is "[IMAGE]".
1179
.TP
1180
.B datefmt
1181
The symbol $D can be used in page headers and footers to insert the
1182
current date/time; the value of the datefmt key specifies the
1183
format used. The syntax is the same as in the strftime(3) routine. The
1184
default is "%e %b %Y %R", which gives a date
1185
string like "15 Aug 2000 22:32".
1186
.TP
1187
.B locale
1188
The locale (language code) used for formating language dependent
1189
parts of the date/time in datefmt. If unspecified, the value
1190
is taken from environment variables, see setlocale(3). No default.
1191
.TP
1192
.B doc-sep
1193
A string of HTML code that will be inserted between the
1194
documents when more than one are converted. The default is
1195
"<!--NewPage-->", which will cause
1196
a page break. You may use (almost) any HTML code, for example
1197
"<HR><HR>" or
1198
"<IMG src=...>".
1199
.TP
1200
.B ball-radius
1201
The radius, given as a relative size, of the balls used in
1202
unordered lists. The default is 0.25em.
1203
.TP
1204
.B numbstyle
1205
Page numbering style, 0=arabic, 1=roman. The default is 0.
1206
.TP
1207
.B showurl
1208
When this flag is set to 1, the URL for external links are shown
1209
within parentheses after the link. The default is 0.
1210
.TP
1211
.B seq-number
1212
When this flag is set, the headings in the document will be
1213
sequentially numbered: H1 headings will be numbered 1, 2,..., H2 headings
1214
1.1, 1.2, etc. The default is 0.
1215
.TP
1216
.B extrapage
1217
A flag specifying whether an extra (empty) page should be printed,
1218
when necessary, to ensure that the title page, the table of contents, and
1219
the document itself will start on odd pages. This is typically
1220
desirable for double sided printing. The default is 1.
1221
.TP
1222
.B break-table
1223
A flag specifying if a table should be broken across two pages
1224
when it does not fit on the current page, but it does on a page of its own.
1225
The default is 0 (avoid breaking tables when possible).
1226
.TP
1227
.B forms
1228
This flag is used to specify whether FORM elements in the document
1229
should be processed or ignored. Some forms may be suitable for printing out
1230
and be filled out (with a pen), others are not. The default is 1.
1231
.TP
1232
.B textarea-data
1233
When a TEXTAREA element contains prefilled data, the text will be
1234
used as labels if this flag is set, otherwise ignored. The default is
1235
0.
1236
.TP
1237
.B page-break
1238
Set this flag to 0 to suppress the normal behavior of generating
1239
page breaks from the comment <!--NewPage--> etc, as
1240
specified below. The default is 1.
1241
.TP
1242
.B expand-acronyms
1243
A flag specifying whether acronyms, given by the ACRONYM element,
1244
should be expanded or not. The default is 0.
1245
.TP
1246
.B spoof
1247
Some web servers return different documents depending on which user
1248
agent is used to retrieve the document. You can fool the web server that
1249
a certain browser is used, by setting this value to the identification
1250
used by the browser, such as "Mozilla/4.0". This only works if you are
1251
using one of the Perl packages to retrieve remote documents.
1252
.TP
1253
.B ssi
1254
When this flag is set, some Server Side Includes will be processed
1255
when the document is read from a local file. Examples are
1256
<!--#include file=...>,
1257
<!--#echo var="LAST_MODIFIED">,
1258
<!--#config timefmt=...>. The default is 1.
1259
.TP
1260
.B prefilled
1261
This flag controls whether the content of form elements should be
1262
rendered or not. That is, when this flag is set, the content of TEXTAREA
1263
elements, and the value of the value attribute of text INPUT elements will
1264
be shown. Also, checked radio buttons and checkboxes will be marked.
1265
The default is 0.
1266
.RE
1267
.SH SYMBOLS
1268
.PP
1269
The following symbols can be used on the title page, the page headers/footers,
1270
and in the heading for the table of contents:
1271
.PP
1272
Symbols of the form "$[\fIname\fP]"
1273
will expand to the value of the content attribute of
1274
META elements, having either of the attributes
1275
"name=\fIname\fP" or
1276
"http-equiv=\fIname\fP" (case insensitive string matching).
1277
For example, when a document containing:
1278
.RS
1279
.RE
1280
.RS .0i
1281
.PD
1282
.PP
1283
.PD 0
1284
.RE
1285
.RS .3i
1286
.PP
1287
<META name="expires" content="31 Dec 2001">
1288
.RE
1289
.PD
1290
.PP
1291
.PP
1292
is converted, using a configuration file with:
1293
.RS
1294
.RE
1295
.RS .0i
1296
.PD
1297
.PP
1298
.PD 0
1299
.RE
1300
.RS .3i
1301
.PP
1302
footer { left: "Expires: $[expires]" }
1303
.RE
1304
.PD
1305
.PP
1306
.PP
1307
this left footer will be inserted:
1308
.RS
1309
.RE
1310
.RS .0i
1311
.PD
1312
.PP
1313
.PD 0
1314
.RE
1315
.RS .3i
1316
.PP
1317
Expires: 31 Dec 2001
1318
.RE
1319
.PD
1320
.PP
1321
.PP
1322
In addition, these symbols are defined:
1323
.LP
1324
.RS
1325
.PD 0
1326
.TP
1327
.B $T
1328
Current document title.
1329
.TP
1330
.B $A
1331
Author of current document, as specified with <META name="Author"
1332
content="..."> in the document head.
1333
.TP
1334
.B $U
1335
The URL, or file name, of current document.
1336
.TP
1337
.B $N
1338
Page number.
1339
.TP
1340
.B $H
1341
Current document heading (level 1-3).
1342
.TP
1343
.B $D
1344
Current date/time. The format is given by the datefmt key.
1345
.RE
1346
.PD
1347
.PP
1348
.PP
1349
So $A is equivalent to $[author], but kept for
1350
backwards compatibility.
1351
.PP
1352
To avoid symbol expansion, precede the dollar sign with a backslash,
1353
as in "\\$T".
1354
.SH HINTS
1355
.PP
1356
I imagine that a typical use of configuration files can be something
1357
along the following lines.
1358
.PP
1359
System specific definitions (e.g. specification of available program packages)
1360
and global defaults (paper type etc) are defined in the global configuration
1361
file.
1362
.PP
1363
If there is more than one user of the program on the system, each user can
1364
also have a personal configuration file with his/hers own personal preferences.
1365
(On a single user system one can use the global configuration file for this
1366
purpose as well.)
1367
.PP
1368
One may also develop a collection of configuration files for typical
1369
situations. These files are placed in a directory that is searched by html2ps
1370
(the search path is defined with the environment variable HTML2PSPATH).
1371
For example, to print a document as slides - in landscape mode, with
1372
large text in Helvetica, and a thick frame - one can create a
1373
configuration file, called 'slides' say, containing:
1374
.RS
1375
.RE
1376
.RS .0i
1377
.PD
1378
.PP
1379
.PD 0
1380
.RE
1381
.RS .3i
1382
.PP
1383
@html2ps {
1384
.RE
1385
.RS .5i
1386
.PP
1387
option {
1388
.RE
1389
.RS .7i
1390
.PP
1391
landscape: 1;
1392
.PP
1393
frame: 1;
1394
.RE
1395
.RS .5i
1396
.PP
1397
}
1398
.PP
1399
frame { width: 3pt }
1400
.RE
1401
.RS .3i
1402
.PP
1403
}
1404
.PP
1405
BODY {
1406
.RE
1407
.RS .5i
1408
.PP
1409
font-family: Helvetica;
1410
.PP
1411
font-size: 20pt;
1412
.RE
1413
.RS .3i
1414
.PP
1415
}
1416
.PP
1417
H1 { font-size: 35pt }
1418
.PP
1419
H2 { font-size: 32pt }
1420
.PP
1421
H3 { font-size: 29pt }
1422
.PP
1423
H4 { font-size: 26pt }
1424
.PP
1425
H5 { font-size: 23pt }
1426
.PP
1427
H6 { font-size: 20pt }
1428
.PP
1429
PRE { font-size: 18pt }
1430
.RE
1431
.PD
1432
.PP
1433
.PP
1434
Then use the command:
1435
.RS
1436
.RE
1437
.RS .0i
1438
.PD
1439
.PP
1440
.PD 0
1441
.RE
1442
.RS .3i
1443
.PP
1444
html2ps -f slides ...
1445
.RE
1446
.PD
1447
.PP
1448
.PP
1449
to convert the document. Note that with this command the file 'slides' is used
1450
instead of the personal configuration file. If you want both to
1451
be used, giving precedence to definitions made in the file 'slides', use
1452
the command:
1453
.RS
1454
.RE
1455
.RS .0i
1456
.PD
1457
.PP
1458
.PD 0
1459
.RE
1460
.RS .3i
1461
.PP
1462
html2ps -f :slides ...
1463
.RE
1464
.PD
1465
.PP
1466
.PP
1467
(The page breaks between the slides can for example be generated by
1468
adding '<HR class=PAGE-BREAK>' to the HTML document.)
1469
.PP
1470
For features that are frequently turned on and off, and that cannot be
1471
controlled by command line options, it may be a good idea to create small
1472
configuration files as "building blocks". For example a file 'A4' for
1473
printing on A4 paper (if you have some other default paper type):
1474
.RS
1475
.RE
1476
.RS .0i
1477
.PD
1478
.PP
1479
.PD 0
1480
.RE
1481
.RS .3i
1482
.PP
1483
@html2ps { paper { type: A4 } }
1484
.RE
1485
.PD
1486
.PP
1487
.PP
1488
and a file 'hnum' for automatic numbering of headings:
1489
.RS
1490
.RE
1491
.RS .0i
1492
.PD
1493
.PP
1494
.PD 0
1495
.RE
1496
.RS .3i
1497
.PP
1498
@html2ps { seq-number: 1 }
1499
.RE
1500
.PD
1501
.PP
1502
.PP
1503
Combining this with the previous example: to convert a document for printing
1504
on A4 sized slides with all headings numbered, use the command:
1505
.RS
1506
.RE
1507
.RS .0i
1508
.PD
1509
.PP
1510
.PD 0
1511
.RE
1512
.RS .3i
1513
.PP
1514
html2ps -f :slides:A4:hnum ...
1515
.RE
1516
.PD
1517
.PP
1518
1519
.SH SEE ALSO
1520
html2ps(1), setlocale(3), strftime(3)
1521
.SH VERSION
1522
This manpage describes html2ps version 1.0 beta3.
1523
.SH AVAILABILITY
1524
http://www.tdb.uu.se/~jan/html2ps.html
1525
.SH AUTHOR
1526
Jan Karrman (jan@tdb.uu.se)
1527
Loggerhead is a web-based interface for Breezy
Version: 2.0.1