First, do not get intimidated by the size of this document. At least on a Unix system with Perl installed, you should be able to convert a local text-only HTML file directly without doing any preparation at all. Just execute the script with the HTML file as parameter and direct the output to a file or a printer, for example:
html2ps file.html > file.psor perhaps
perl html2ps file.html > file.psThere are several possibilities to control the appearance of the output. Starting with version 1.0 of html2ps, most of this is done via configuration files, and not with command line options only. A sample configuration file 'sample' is included with the html2ps distribution (used by the installation script to convert this document to postscript). You can take a look at this file to see an example of a configuration file.
The command line options, and how to set their defaults using
a configuration file, are described in the
option block below. Due to the new concept of
configuration files, some of the command line options in earlier
versions have been removed. Hopefully, this will not cause too many
problems for old users.
Jean-Philippe Argaud has written a GUI (xhtml2ps) for html2ps. You can find this in the directory 'contrib'. Both html2ps and xhtml2ps comes with the GNU General Public License, see the file 'COPYING' for details.
There is a mailing list for html2ps. If you want to be included on this list, send a mail with the word 'subscribe' on the subject line to html2ps-request@tdb.uu.se.
Since html2ps is written in Perl, you must of course have Perl installed, version 5 or later is required.
If you want to make use of the support for inline images, you must have one of the packages ImageMagick, pbmplus or netpbm installed. If you do not have ImageMagick (or if it is not installed with jpeg support), you can use djpeg from the jpegsrc distribution to handle jpeg images. The recommended image package is ImageMagick together with its Perl module interface PerlMagick.
To be able to convert remote documents directly without downloading them first, you must have have some program installed for this purpose. The best is to either use the Perl module library libwww-perl or www.pl and network.pl, but you can for example also use lynx or url_get for this.
Ghostscript is also required to get full functionality (needed to generate DSC PostScript and cross references).
If you are on a Unix system, and have all necessary software installed, you can now execute the installation script 'install' to build a global configuration file, and install all files. On other platforms you will have to create a global configuration file manually, and insert its name into the html2ps script. This is described in next section.
For Unix 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.
On non-Unix 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.
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.
@import "filename";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:
BODY {
font-size: 12pt;
font-family: Helvetica;
text-align: justify
}
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.
Several blocks can share the same definition. The block names are then separated be commas, as in:
H2, H4, H6 { font-style: italic }
A comment in a configuration file starts with the characters
"/*" and ends with "*/":
@html2ps {
seq-number: 1; /* Automatic numbering of headings */
}
@html2ps
block, coincides with a subset of the
CSS1 – Cascading Style Sheets
level 1 – specification.
(If this link is no longer valid, try looking for style
sheet documentation starting at the
W3C home page.)
The following default settings for html2ps illustrate just about everything that currently can be used from the CSS1 specification:
BODY {
font-family: Times;
font-size: 11pt;
text-align: left;
background: white;
}
H1, H2, H3, H4, H5, H6 {
font-weight: bold;
margin-top: 0.8em;
margin-bottom: 0.5em;
}
H1 { font-size: 19pt }
H2 { font-size: 17pt }
H3 { font-size: 15pt }
H4 { font-size: 13pt }
H5 { font-size: 12pt }
H6 { font-size: 11pt }
P, OL, UL, DL, BLOCKQUOTE, PRE {
margin-top: 1em;
margin-bottom: 1em;
}
P {
line-height: 1.2em;
text-indent: 0;
}
OL, UL, DD { margin-left: 2em }
TT, KBD, PRE { font-family: Courier }
PRE { font-size: 9pt }
BLOCKQUOTE {
margin-left: 1em;
margin-right: 1em;
}
ADDRESS {
margin-top: 0.5em;
margin-bottom: 0.5em;
}
TABLE {
margin-top: 1.3em;
margin-bottom: 1em;
}
DEL { text-decoration: line-through }
A:link, HR { color: black }
@html2ps
@html2ps block has
several sub-blocks and key-value pairs, these are described in this section.
package block
PerlMagick
ImageMagick
pbmplus
netpbm
djpeg
Ghostscript
TeX
dvips
libwww-perl
jfriedl
geturl
lynx -source
-mime_header" or "url_get -h".
check
path
paper block
type
height
width
option block
twoup (on the command line: -2 or --twoup)
base (on the command line: -b URL or --base URL)
check (on the command line: -c or --check)
toc (on the command line: -C string or --toc string)
rev=TOC in the converted document.
debug (on the command line: -d or --debug)
DSC (on the command line: -D or --DSC)
encoding (on the command line: -e encoding or --encoding encoding)
rcfile (on the command line: -f file[:file[:...]] or --rcfile file[:file[:...]])
frame (on the command line: -F or --frame)
grayscale (on the command line: -g or --grayscale)
help (on the command line: -h or --help)
hyphenate (on the command line: -H or --hyphenate)
scaleimage (on the command line: -i num or --scaleimage num)
language (on the command line: -l lang or --language lang)
landscape (on the command line: -L or --landscape)
scalemath (on the command line: -m num or --scalemath num)
number (on the command line: -n or --number)
startno (on the command line: -N num or --startno num)
output (on the command line: -o file or --output file)
original (on the command line: -O or --original)
<OBJECT data="figure.ps" type="application/postscript">
<OBJECT data="figure.gif" type="image/gif">
<PRE>[Maybe some ASCII art for text browsers]</PRE>
</OBJECT>
</OBJECT>
rootdir (on the command line: -r path or --rootdir path)
xref (on the command line: -R or --xref)
scaledoc (on the command line: -s num or --scaledoc num)
style (on the command line: -S string or --style string)
text (on the command line: -T or --text)
underline (on the command line: -u or --underline)
colour (on the command line: -U or --colour)
version (on the command line: -v or --version)
web (on the command line: -W string or --web string)
<LINK rel=NEXT>" in the document.
duplex (on the command line: -x num or --duplex num)
margin block
left
right
top
bottom
middle
xref block
xref
block is used to control this function.
text
passes
quote block
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.
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:
open
close
open.
open2
open.
close2
close.
quote {
en {
open: "“";
close: "”";
open2: "`";
close2: "'";
}
es: en;
}
toc block
heading
level
indent
extrapage
font block
font block, with the same name as the chosen
font name. This block can contain two key-value pairs:
names
files
TABLE { font-family: myfont }
@html2ps {
font {
myfont {
names: "MyFont-Roman MyFont-Italic MyFont-Bold MyFont-BoldItalic";
files: "/x/y/myfr.ps /x/y/myfi.ps /x/y/myfb.ps /x/y/myfbi.ps";
}
}
}
hyphenation block
file
extfile
in-fra-struc-ture white-space".
en {
file: "/opt/tex/lib/macros/hyphen.tex";
extfile: "/opt/tdb/lib/html2ps/enhyphext";
}
The hyphenation block itself can furthermore have these
key-values:
min
start
end
header block
left
alternate flag in this
block is set to 1, this will be the right header on even pages.
center
right
alternate flag in this
block is set to 1, this will be the left header on even pages.
odd-left
odd-center
odd-right
even-left
even-center
even-right
font-family
font-size
font-style
font-weight
color
alternate
left and right keys should change place on
even pages. Typically used for double sided printing.
The default is 1.
footer block
left
alternate flag in
this block is set to 1, this will be the right footer on even pages.
center
right
alternate flag in
this block is set to 1, this will be the left footer on even pages.
odd-left
odd-center
odd-right
even-left
even-center
even-right
font-family
font-size
font-style
font-weight
color
alternate
left and right keys should change place on
even pages. Typically used for double sided printing.
The default is 1.
frame block
width
margin
color
justify block
word
letter
draft block
text
print
<META name="Status" content="Draft">.
dir
font-family
font-style
font-weight
color
colour block
brown: A52A2A;".
@html2ps block
html2psrc
imgalt
"[IMAGE]".
datefmt
datefmt key specifies the
format used. The syntax is the same as in the strftime(3) routine. The
default is "%e %b %Y %R", which gives a date
string like "9 Aug 1997 18:24".
locale
datefmt. If unspecified, the value
is taken from environment variables, see setlocale(3). No default.
doc-sep
"<!--NewPage-->", which will cause
a page break. You may use (almost) any HTML code, for example
"<HR><HR>" or
"<IMG src=...>".
ball-radius
numbstyle
showurl
seq-number
forms
textarea-data
page-break
<!--NewPage--> etc, as
specified below. The default is 1.
expand-acronyms
collapse-br
spoof
<META name="Author"
content="..."> in the document head.
datefmt key.
System specific definitions (e.g. specification of available program packages) and global defaults (paper type etc) are defined in the global configuration file.
If there is more than one user of the program on the system, each user can also have a personal configuration file with his/hers own personal preferences. (On a single user system one can use the global configuration file for this purpose as well.)
One may also develop a collection of configuration files for typical situations. These files are placed in a directory that is searched by html2ps (the search path is defined with the environment variable HTML2PSPATH). For example, to print a document as slides – in landscape mode, with large text in Helvetica, and a thick frame – one can create a configuration file, called 'slides' say, containing:
@html2ps {
option {
landscape: 1;
frame: 1;
}
frame { width: 3pt }
}
BODY {
font-family: Helvetica;
font-size: 20pt;
}
H1 { font-size: 35pt }
H2 { font-size: 32pt }
H3 { font-size: 29pt }
H4 { font-size: 26pt }
H5 { font-size: 23pt }
H6 { font-size: 20pt }
PRE { font-size: 18pt }
Then use the command:
html2ps -f slides ...to convert the document. Note that with this command the file 'slides' is used instead of the personal configuration file. If you want both to be used, giving precedence to definitions made in the file 'slides', use the command:
html2ps -f :slides ...(The page breaks between the slides can for example be generated by adding '
<HR class=PAGE-BREAK>' to the HTML document.)
For features that are frequently turned on and off, and that cannot be controlled by command line options, it may be a good idea to create small configuration files as "building blocks". For example a file 'A4' for printing on A4 paper (if you have some other default paper type):
@html2ps { paper { type: A4 } }
and a file 'hnum' for automatic numbering of headings:
@html2ps { seq-number: 1 }
Combining this with the previous example: to convert a document for printing
on A4 sized slides with all headings numbered, use the command:
html2ps -f :slides:A4:hnum ...
DEL { display: none }
in a configuration file.
@html2ps { expand-acronyms: 1 }
in a configuration file. By default, acronyms are not expanded.
lang attribute (recognized for a
few elements) is used to determine the language of the document, or for
a particular section.
You must of course have access to PostScript fonts for these languages and encodings. For Japanese you can use the free Wadalab fonts and associated tools. These fonts can be used together with Ghostscript to print on a printer that does not have such fonts.
Of the three Japanese encodings, EUC-JP works best with html2ps. The 7-bit encoding ISO-2022-JP, found in several documents on the web, is a bad choice for HTML documents. This is because the encoding uses characters that have a special function in HTML, such as '<'. Often this results in incorrect HTML code, and html2ps as well as browsers will of course have problems rendering these documents.
There is not yet any automatic detection of the encoding, this must be explicitly specified with the option -e, or in a configuration file. If you for example would like to convert a document with EUC-JP encoding, you can use a configuration file like:
BODY { font-family: eucjp }
@html2ps {
option {
encoding: "EUC-JP";
}
font {
eucjp {
names: "Ryumin-Light-EUC-H";
}
}
}
The name Ryumin-Light-EUC-H should be changed into the
PostScript font name for the font to be used, here with EUC-JP encoding.
The name eucjp can be changed to something else, as long
as it is the same in the BODY and font blocks.
You may not (yet) use a font having vertical writing mode.
The support for Japanese has only recently been added, and so far only been tested by me. Unfortunately, I do not know any Japanese, and cannot verify that what comes out is correct. Also, the line breaking is probably not correctly done.
Please let me know if you are aware of any free PostScript fonts for Chinese, Korean, etc.
Here follow a few quotes that illustrate the languages that have their
quotation marks predefined. See the quote
block how to extend the list of quotation marks. Note: since the Q element
is currently not implemented in most browsers, you will probably not see any
quotation marks at all if you are reading this in a browser (this document
is best printed with html2ps ;-).
A horse! a horse! my kingdom for a horse!
–
Richard III by W. Shakespeare.
Blott Sverige svenska krusbär har– Carl Jonas Love Almqvist (Swedish poet).
Der er et yndigt land– National anthem of Denmark.
Seiern er vår!– Almost any Norwegian nowadays...
Sukuvirttä suoltamahan, lajivirttä laulamahan– Kalevala, national epos of Finland.
... y veámonos, como dijo un ciego a otro– Don Quijote de la Mancha by Cervantes.
Je pense donc je suis– René Descartes.
Zum Denken sind wenige Menschen geneigt, obwohl alle zum Rechthaben– Arthur Schopenhauer.
Eppur si muove– Galileo Galilei.
It is also possible to get automatic hyphenation of the text. This requires hyphenation pattern files from the TeX distribution. A hyphenation pattern file for English is included with html2ps. Pattern files for other languages are available from the CTAN archives in, for example
The hyphenation patterns for words containing only ASCII characters should work correctly. But it may be problems with other words, since the authors of these hyphenation pattern files use different (but in TeX equivalent) syntax to represent non-ASCII characters.Please note that although TeX hyphenation patterns are used, the algorithm used is not as sophisticated as in TeX. In fact, you should not expect TeX quality in any part of this program!
Hyphenation patterns for important languages such as Swedish, Icelandic, Danish, Norwegian and Finnish, as well as a few exotic languages such as English, Spanish, German and French have been tested and seem to work correctly :-).
The IMG attributes ALIGN=LEFT and ALIGN=RIGHT are not recognized. This means that text flow around images does not work. Also, the IMG attributes WIDTH and HEIGHT are ignored.
The TYPE attribute in unordered lists UL is not supported.
A few deviations from the TABLE element as specified in HTML 3.2: It is not possible to set the border width of a table. The WIDTH and HEIGHT attributes of the TH and TD elements does not work correctly (in my opinion, these attributes are bugs in the HTML specification itself!). The CELLSPACING attribute is not implemented as described in the specification; instead the value of the CELLPADDING attribute is increased by half the value of CELLSPACING.
Rendering HTML tables well is a non-trivial task. For "real" tables, that is representation of tabular data, html2ps usually generates reasonably good output. When tables are used for layout purposes, the result varies from good to useless. This is because a table cell is never broken across pages. So if a table contains a cell with a lot of content, the entire table may have to be scaled down in size in order to make this cell fit on a single page. Sometimes this may even result in unreadable output.
Page breaks are occasionally done in bad places: for example directly after a (long) heading, and before the last line in a paragraph.
A more realistic project is to implement the parts of HTML 4.0 that are relevant for printing. Much is already implemented, but there remain a lot to do regarding internationalization.
Support for style sheets has also high priority. Currently, a small part of CSS1 is supported, but only in the form of personal style sheets (using configuration files); style information within HTML documents is ignored.
Being a (currently inactive) PhD student in mathematics, I hope to be able to implement the suggested standard for expressing mathematical expressions in HTML documents. However, rendering mathematical formulas well is a very difficult task indeed.
All new features added have made the script quite large, and significantly slower than earlier versions. I will try to find some way to speed it up somewhat.
I am grateful for all suggestions how to improve html2ps. In fact, many of the current features have been implemented after suggestions from other users.
The advantage with the non-DSC code is that it can be 'reused' by html2ps: you can rebuild an already generated PostScript file using new command line options and configuration files. This is done by running html2ps with the new options, and with the old PostScript file as input. This can save a lot of time and bandwidth when converting remote documents.
It is possible to generate DSC compliant PostScript by using the option -D, but this requires that Ghostscript is installed, and it can take quite some time to do. Note: if you are producing PostScript files for others to download and print, it is strongly recommended that you generate DSC compliant code (i.e. convert with the -D option).
A page break can be forced by including any of these in a document:
<HR class=PAGE-BREAK> <?page-break> <!--NewPage-->If you want html2ps to ignore certain parts of a document, use the following construction:
<DIV class=NOPRINT>
This will not be printed...
</DIV>
This can be used to avoid getting navigation bars etc in the printout.
The BANNER, FIG, and MATH elements from the expired HTML 3.0 specification are also supported. Note that the support for MATH is far from complete, and requires that TeX and dvips are installed.
pdfmark operator, that are instructions to a PostScript-to-PDF
converter (such as version 5.0 or later of Aladdin Ghostscript, or Adobe
Acrobat Distiller). These instructions generate hyperlinks in the PDF
document, from the hyperlinks in the original HTML documents. A PDF outline
entry, or bookmark, is also generated from the HTML headings.
By default the links in the PDF document will be represented by a box
with a border. You may instead have the link text coloured, by for example
specifying 'A:link { color: red }' in a configuration file,
and use the option -U when converting.
If possible, also include the HTML document, or a URL – preferably containing a minimal example illustrating the problem.