.\" @(#)html2psrc.5 .\" .TH html2psrc 5 " 7 May 2010" "Autogenerated" "html2ps configuration file format" .SH NAME html2psrc - configuration file format for html2ps(1) .SH DESCRIPTION Configuration files are used for layout control, resource information etc. Normally, there should always exist a global configuration file. In this file one typically specify things like: what image conversion packages are available on the system, the default paper size, the default text fonts and sizes, etc. .PP For Unix and Windows systems, the installation script 'install' can be used to automatically build a global configuration file with all necessary definitions, and install all files. The files replaced by the installation are saved. If you for some reason are not satisfied with the new version: execute the script 'backout' to reinstall your earlier version. .PP On other systems, you will have to manually create a global configuration file, and insert the name of this file into the html2ps script (close to the beginning, the line starting with "$globrc="). The configuration file should contain a package block, and perhaps paper and hyphenation blocks, described below. .PP Each user can then have a personal configuration file (by default $HOME/.html2psrc) that complements/overrides the definitions made in the global file. It is also possible to specify alternative files on the command line, using the -f option. .SH FILE FORMAT .PP A configuration file can include other configuration files. This is done with: .RS .PD .PP .PD 0 .RE .RS .3i .PP @import "\fIfilename\fP"; .RE .PD .PP .PP The rest of the configuration file consists of zero or more blocks. A block is given by a block name, followed by the block definition, as in: .RS .RE .RS .0i .PD .PP .PD 0 .RE .RS .3i .PP BODY { .RE .RS .5i .PP font-size: 12pt; .PP font-family: Helvetica; .PP text-align: justify .RE .RS .3i .PP } .RE .PD .PP .PP The block definition, enclosed by curly braces: { }, consists of key-value pairs and/or other blocks. A key-value pair consists of the key name followed by a colon, followed by the value. Blocks and key-value pairs are separated by semicolons. The semicolon may be omitted after a block. .PP Several blocks can share the same definition. The block names are then separated be commas, as in: .RS .RE .RS .0i .PD .PP .PD 0 .RE .RS .3i .PP H2, H4, H6 { font-style: italic } .RE .PD .PP .PP A comment in a configuration file starts with the characters "/*" and ends with "*/": .RS .RE .RS .0i .PD .PP .PD 0 .RE .RS .3i .PP @html2ps { .RE .RS .5i .PP seq-number: 1; /* Automatic numbering of headings */ .RE .RS .3i .PP } .RE .PD .PP Notations .PP .PP Here are some definitions of terms used below: .LP .RS .PD 0 .TP .B Flag: A value of either 0 (absence, inactive etc) or 1 (presence, active etc). .TP .B Absolute size: A real number optionally followed by one of the following two-letter unit identifiers: cm (centimeters), mm (millimeters), in (inches), pt (points, 1pt = 1/72 inch), pc (picas, 1pc = 12pt). The default unit is centimeters. .TP .B Relative size: A size relative to current fontsize. The default and currently only recognized unit is em. One em equals the size of the current font. The value should be given as a real number, optionally followed by 'em', as in '0.25em'. .TP .B Whitespace: Any one of the characters: space, tab, newline, or carriage return. .RE .PD .PP CSS2 blocks .PP .PP All blocks, except one: the @html2ps block, coincides with a subset of the Cascading Style Sheets, level 2 CSS2 Specification (http://www.w3.org/TR/REC-CSS2/). The following default settings for html2ps illustrate just about everything that currently can be used from the CSS2 specification: .RS .RE .RS .0i .PD .PP .PD 0 .RE .RS .3i .PP BODY { .RE .RS .5i .PP font-family: Times; .PP font-size: 11pt; .PP text-align: left; .PP background: white; .RE .RS .3i .PP } .PD .PP .PD 0 .PP H1, H2, H3, H4, H5, H6 { .RE .RS .5i .PP font-weight: bold; .PP margin-top: 0.8em; .PP margin-bottom: 0.5em; .RE .RS .3i .PP } .PP H1 { font-size: 19pt } .PP H2 { font-size: 17pt } .PP H3 { font-size: 15pt } .PP H4 { font-size: 13pt } .PP H5 { font-size: 12pt } .PP H6 { font-size: 11pt } .PD .PP .PD 0 .PP P, OL, UL, DL, BLOCKQUOTE, PRE { .RE .RS .5i .PP margin-top: 1em; .PP margin-bottom: 1em; .RE .RS .3i .PP } .PD .PP .PD 0 .PP P { .RE .RS .5i .PP line-height: 1.2em; .PP text-indent: 0; .RE .RS .3i .PP } .PD .PP .PD 0 .PP OL, UL, DD { margin-left: 2em } .PD .PP .PD 0 .PP TT, KBD, PRE { font-family: Courier } .PD .PP .PD 0 .PP PRE { font-size: 9pt } .PD .PP .PD 0 .PP BLOCKQUOTE { .RE .RS .5i .PP margin-left: 1em; .PP margin-right: 1em; .RE .RS .3i .PP } .PD .PP .PD 0 .PP ADDRESS { .RE .RS .5i .PP margin-top: 0.5em; .PP margin-bottom: 0.5em; .RE .RS .3i .PP } .PD .PP .PD 0 .PP TABLE { .RE .RS .5i .PP margin-top: 1.3em; .PP margin-bottom: 1em; .RE .RS .3i .PP } .PD .PP .PD 0 .PP DIV.noprint { display: none } .PD .PP .PD 0 .PP DEL { text-decoration: line-through } .PD .PP .PD 0 .PP A:link, HR { color: black } .PD .PP .PD 0 .PP @page { .RE .RS .5i .PP margin-left: 2.5cm; .PP margin-right: 2.5cm; .PP margin-top: 3cm; .PP margin-bottom: 3cm; .RE .RS .3i .PP } .RE .PD .PP .PP The program specific block \fI@html2ps\fP: .PP This block is used to specify parameters that are specific to html2ps, and not covered by CSS2. The @html2ps block has several sub-blocks and key-value pairs, these are described in this section. .TP The \fIpackage\fP block .RS .5i This block is used to specify which program packages are installed on the system. Typically, this is done in the global configuration file. .TP .B PerlMagick A flag specifying whether the Perl module PerlMagick is installed or not. The default is 0. .TP .B ImageMagick A flag specifying whether the ImageMagick package is installed or not. The default is 0. .TP .B pbmplus A flag specifying whether the pbmplus package is installed or not. The default is 0. .TP .B netpbm A flag specifying whether the netpbm package is installed or not. The default is 0. .TP .B djpeg A flag specifying whether djpeg is installed or not. The default is 0. .TP .B Ghostscript A flag specifying whether Ghostscript is installed or not. The default is 0. .TP .B TeX A flag specifying whether the TeX package is installed or not. The default is 0. .TP .B dvips A flag specifying whether dvips is installed or not. The default is 0. .TP .B libwww-perl A flag specifying whether the Perl module library libwww-perl is installed or not. The default is 0. .TP .B geturl When neither of the Perl packages for retrieving remote documents are available, it is possible to use some other program like wget or lynx. This value should be set to a command that retrieves a document with a complete MIME header, such as "wget -s -q -O-" or "lynx -source -mime_header". .TP .B check The name of a program used for syntax checking HTML documents. No default, a good choice is weblint. .TP .B path A colon separated list of directories where the executables from the program packages are. It is only necessary to include directories that are not in the PATH for a typical user. .RE .TP The \fIpaper\fP block .RS .5i The paper size is defined in this block. The size can either be given as one of the recognized paper types or by giving explicit values for the paper height and width. As of version 1.0 beta2, one can also use the @page block in CSS2 for the paper size. The paper block is kept for backwards compatibility. Also, one can only specify explicit dimensions in @page, not any paper types by name. .TP .B type Paper type, possible choices are: A0, A1, A2, A3, A4,...,A10, B0, B1,...,B10, letter, legal, arche, archd, archc, archb, archa, flsa, flse, halfletter, 11x17, and ledger (this set of paper types is taken from Aladdin Ghostscript). The default is A4. .TP .B height An absolute size specifying the paper height. .TP .B width An absolute size specifying the paper width. .RE .TP The \fIoption\fP block .RS .5i This block is used to set default values for the command line options. The key in the key-value pair is the option name, in either its long or short form. .TP .B twoup Two column (2-up) output. The default is one column per page. .TP .B base Use \fIURL\fP as a base to expand relative references for in-line images. This is useful if you have downloaded a document to a local file. The \fIURL\fP should then be the \fIURL\fP of the original document. .TP .B check Check the syntax of the HTML file (using an external syntax checker). The default is to not make a syntax check. .TP .B toc Generate a table of contents (ToC). The value should be a string consisting of one of the letters 'f', 'h', or 't', optionally combined with the letter 'b': .LP .RS .PD 0 .TP .B b The ToC will be printed first. This requires that Ghostscript is installed. .TP .B f The ToC will be generated from the links in the converted document. .TP .B h The ToC will be generated from headings and titles in the converted documents. Note that if the document author for some strange reason has chosen to use some other means to represent the headings than the HTML elements H1,...,H6, you are out of luck! .TP .B t The ToC will be generated from links having the attribute rev=TOC in the converted document. .RE .PD .PP .TP .B debug Generate debugging information. You should always use this option when reporting problems with html2ps. .TP .B DSC Generate DSC compliant PostScript. This requires Ghostscript and can take quite some time to do. Note that a PostScript file generated with this option cannot be used as input to html2ps for reformatting later. .TP .B encoding The document encoding. Currently recognized values are ISO-8859-1, EUC-JP, SHIFT-JIS, and ISO-2022-JP (other EUC-xx encodings may also work). The default is ISO-8859-1. .TP .B rcfile A colon separated list of configuration file names to use instead of the default personal configuration file $HOME/.html2psrc. Definitions made in one file override definitions in previous files (the last file in the list has highest precedence). An empty file name (as in ':file', 'file1::file3', or 'file:') will expand to the default personal file. The environment variable HTML2PSPATH is used to specify the directories where to search for these files. (Note: this is only supposed to be used on the command line, not in a configuration file.) .TP .B frame Draw a frame around the text on each page. The default is to not draw a frame. .TP .B grayscale Convert colour images to grayscale images. Note that the PostScript file will be smaller when the images are converted to grayscale. The default is to generate colour images. .TP .B help Show usage information. .TP .B hyphenate Hyphenate the text. This requires TeX hyphenation pattern files. .TP .B scaleimage Scale in-line images with a factor \fInum\fP. The default is 1. .TP .B cookie Enable cookie support, using a netscape formatted cookie \fIfile\fP (requires libwww-perl). .TP .B language Specifies the language of the document (overrides an eventual LANG attribute of the BODY element). The language should be given according to RFC1766 (ftp://ftp.nordu.net/rfc/rfc1766.txt) and ISO 639 (http://www.w3.org/WAI/ER/IG/ert/iso639.htm). .TP .B landscape Generate code for printing in landscape mode. The default is portrait mode. .TP .B scalemath Scale mathematical formulas with a factor \fInum\fP. The default is 1. .TP .B mainchapter Specifies the start number for automatic numbering of headings (by setting the seq-number parameter), the default is 1. .TP .B number Insert page numbers. The default is to not number the pages. .TP .B startno Specifies the starting page number, the default is 1. .TP .B output Write the PostScript code to \fIfile.\fP The default is to write to standard output. .TP .B original Use PostScript original images if they exist. For example, if a document contains an image figure.gif, and an encapsulated PostScript file named figure.ps exists in the same directory, that file will be use instead. This only work for documents read as local files. Note: if the PostScript file is large or contains bitmap images, this must be combined with the -D option. In HTML 4.0 this can be achieved in a much better way with: .RS .RE .RS .0i .PD .PP .PD 0 .RE .RS .3i .PP .RE .PD .PP .TP .B rootdir When a document is read from a local file, this value specifies a base directory for resolving relative links starting with "/". Typically, this should be the directory where your web server's home page resides. .TP .B xref Insert cross references at every link to within the set of converted documents. .TP .B scaledoc Scale the entire document with a factor \fInum\fP. The default is 1. .TP .B style This option complements/overrides definitions made in the configuration files. The \fIstring\fP must follow the configuration file syntax. (Note: this is only supposed to be used on the command line, not in a configuration file.) .TP .B titlepage Generate a title page. The default is to not generate one. .TP .B text Text mode, ignore images. The default is to include the images. .TP .B underline Underline text that constitutes a hypertext link. The default is to not underline. .TP .B colour Produce colour output for text and background, when specified. The default is black text on white background (mnemonic: coloUr ;-). .TP .B version Print information about the current version of html2ps. .TP .B web Process a web of documents by recursively retrieve and convert documents that are referenced with hyperlinks. When dealing with remote documents it will of course be necessary to impose restrictions, to avoid downloading the entire web... The value should be a string consisting of one of the letters 'a', 'b', 'l', 'r', or 's', optionally combined with a combination of the letters 'p', 'L', and a positive integer: .LP .RS .PD 0 .TP .B a Follow all links. .TP .B b Follow only links to within the same directory, or below, as the start document. .TP .B l Follow only links specified with "" in the document. .TP .B p Prompt for each remote document. This mode will automatically be entered after the first 50 documents. .TP .B r Follow only relative links. .TP .B s Follow only links to within the same server as the start document. .TP .B L With this option, the order in which the documents are processed will be: first all top level documents, then the documents linked to from these etc. For example, if the document A has links to B and C, and B has a link to D, the order will be A-B-C-D. By default, each document will be followed by the first document it links to etc; so the default order for the example is A-B-D-C. .TP .B # A positive integer giving the number of recursive levels. The default is 4 (when the option is present). .RE .PD .PP .TP .B duplex Generate postscript code for single or double sided printing. No default, valid values are: .LP .RS .PD 0 .TP .B 0 Single sided. .TP .B 1 Double sided. .TP .B 2 Double sided, opposite page reversed (tumble mode). .RE .PD .PP .RE .TP The \fImargin\fP block .RS .5i This block is used to specify page margins. The left, right, top and bottom margins, previously defined with this block, should now be defined using the @page construction from CSS2. .TP .B middle An absolute size for the distance between the columns when printing two columns per page, default is 2cm. .RE .TP The \fIxref\fP block .RS .5i At every hyperlink (to within the set of converted documents) it is possible to have a cross reference inserted. The \fIxref\fP block is used to control this function. .TP .B text This defines the cross reference text to be inserted; the symbol $N will expand to the page number, default is "[p $N]". .TP .B passes The number of passes used to insert the cross references. Normally, only one pass is run. But since the insertion of the page numbers may effect the page breaks, it might for large documents with many links be necessary with more than one pass to get the cross references right. The default is 1. .RE .TP The \fIquote\fP block .RS .5i Language specific quotation marks are defined in this block. These quotation marks are used with the HTML 4.01 element Q for short quotations. Quotation marks are predefined for a few languages (English, Swedish, Danish, Norwegian (also Nynorsk and Bokm\(oal), Finnish, Spanish, French, German and Italian). It is possible to define different quotation marks for quotes within quotes. .PP A quotation mark is defined as a string, using the same encoding as the converted document (normally ISO-8859-1), and/or with character entities. Note that quotation mark characters for several languages are not included in ISO-8859-1, and their corresponding character entities were not been defined prior to HTML 4.0. .PP Quotation marks for a language can be defined explicitly in a sub-block of the quote block. One can also identify the set of quotation marks with another previously defined language, using a key-value pair. The sub-block/key name should equal the language code as defined in ISO 639. The language sub-block can have the following key-values: .LP .RS .PD 0 .TP .B open The quote opening character(s). .TP .B close The quote closing character(s). If undefined, it will equal open. .TP .B open2 The quote opening character(s) for quotes within quotes. If undefined, it will equal open. .TP .B close2 The quote closing character(s) for quotes within quotes. If undefined, it will equal close. .RE .PD .PP .PP Example: English and Spanish use the same set of quotation marks - at least according to my book on typography. These (already known to html2ps) are defined with: .RS .RE .RS .0i .PD .PP .PD 0 .RE .RS .3i .PP quote { .RE .RS .5i .PP en { .RE .RS .7i .PP open: "“"; .PP close: "”"; .PP open2: "`"; .PP close2: "'"; .RE .RS .5i .PP } .PP es: en; .RE .RS .3i .PP } .RE .PD .PP .RE .TP The \fItoc\fP block .RS .5i When a table of contents (ToC) is generated from document headings and titles, the appearance is controlled by this block. .TP .B heading A string with HTML code specifying a heading used on the first ToC page. .TP .B level The maximum heading level used for building the ToC. The default is 6, which means that all headings will generate ToC entries. .TP .B indent The ToC entries are indented proportional to the corresponding heading level. This value specifies the size of the indentation. The default is 1em. .RE .TP The \fItitlepage\fP block .RS .5i When a title page is generated, its appearance is controlled by this block. .TP .B content A string with HTML code specifying a heading used on the title page, The default is "