html2psrc(5)

📦
version 1.0b7 · 2 versions
  • 1.0b7 · debian bookworm, debian trixie, epel 9, fedora 43, fedora 44, ubuntu jammy, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking (latest)
  • 1.0b5 · opensuse-leap 16.0
, in debian bookworm, debian trixie, epel 9, fedora 43, fedora 44, ubuntu jammy, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

💖 html2psrc — the configuration file format for html2ps(1) 💖

okay bestie, sit down, grab a boba, because this is the manual page for html2psrc(5) and it's lowkey a whole vibe. this is the tea on how you configure html2ps. let's get into it 🫶

✨ NAME ✨

html2psrc — configuration file format for html2ps(1)

🌸 DESCRIPTION 🌸

so basically, config files are where you control layout, resource info, all that good stuff. and normally? there should always be a global config file chillin' somewhere. in this file you typically say things like: which image conversion packages are available on your system, what the default paper size is, the default text fonts and sizes, etc. the whole setup, you know? 💅

on Unix and Windows systems, the installation script install can be used to automatically build a global config file with all the necessary definitions, and install all the files. and get this — the files that get replaced by the installation are saved. so if you're for some reason not satisfied with the new version (no judgement), just execute the script backout to reinstall your earlier version. iconic, honestly. 🙈

on other systems, you're gonna have to manually create a global config file, and insert the name of this file into the html2ps script (close to the beginning, the line starting with "$globrc="). the config file should contain a package block, and perhaps paper and hyphenation blocks, described below. ✨

each user can then have a personal config file (by default $HOME/.html2psrc) that complements/overrides the definitions made in the global file. it's also possible to specify alternative files on the command line, using the -f option. slay. 👑

🎀 FILE FORMAT 🎀

a config file can include other config files. this is done with:

@import "filename";

the rest of the config file consists of zero or more blocks. a block is given by a block name, followed by the block definition, like:

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. (yes, it's giving optional. main character energy. 😌)

several blocks can share the same definition. the block names are then separated by commas, like:

H2, H4, H6 { font-style: italic }

a comment in a config file starts with the characters "/*" and ends with "*/":

@html2ps {
  seq-number: 1;  /* Automatic numbering of headings */
}

📝 Notations 📝

here are some definitions of terms used below, bestie:

  • Flag: a value of either 0 (absence, inactive etc) or 1 (presence, active etc).
  • 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.
  • 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'.
  • Whitespace: any one of the characters: space, tab, newline, or carriage return.

🌈 CSS2 blocks 🌈

all blocks, except one — the @html2ps block — coincide 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:

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;
}

DIV.noprint { display: none }

DEL { text-decoration: line-through }

A:link, HR { color: black }

@page {
  margin-left: 2.5cm;
  margin-right: 2.5cm;
  margin-top: 3cm;
  margin-bottom: 3cm;
}

💫 The program specific block @html2ps 💫

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, and these are described in this section. okay let's go 🧚

📦 The package block 📦

this block is used to specify which program packages are installed on the system. typically, this is done in the global config file.

  • PerlMagick — a flag specifying whether the Perl module PerlMagick is installed or not. the default is 0.
  • ImageMagick — a flag specifying whether the ImageMagick package is installed or not. the default is 0.
  • pbmplus — a flag specifying whether the pbmplus package is installed or not. the default is 0.
  • netpbm — a flag specifying whether the netpbm package is installed or not. the default is 0.
  • djpeg — a flag specifying whether djpeg is installed or not. the default is 0.
  • Ghostscript — a flag specifying whether Ghostscript is installed or not. the default is 0.
  • TeX — a flag specifying whether the TeX package is installed or not. the default is 0.
  • dvips — a flag specifying whether dvips is installed or not. the default is 0.
  • libwww-perl — a flag specifying whether the Perl module library libwww-perl is installed or not. the default is 0.
  • 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".
  • check — the name of a program used for syntax checking HTML documents. no default, a good choice is weblint.
  • 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.

📄 The paper block 📄

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.

  • 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.
  • height — an absolute size specifying the paper height.
  • width — an absolute size specifying the paper width.

⚙️ The option block ⚙️

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.

  • twoup — two column (2-up) output. the default is one column per page.
  • base — use URL 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 URL should then be the URL of the original document.
  • check — check the syntax of the HTML file (using an external syntax checker). the default is to not make a syntax check.
  • 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':
    • b — the ToC will be printed first. this requires that Ghostscript is installed.
    • f — the ToC will be generated from the links in the converted document.
    • 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!
    • t — the ToC will be generated from links having the attribute rev=TOC in the converted document.
  • debug — generate debugging information. you should always use this option when reporting problems with html2ps.
  • 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.
  • 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.
  • 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.)
  • frame — draws a frame around the text on every page 🖼️. The default is not to draw a frame, so you're opting in, bestie.
  • grayscale — converts colour images into grayscale ones. Heads up though: your PostScript file gets smaller when images go grayscale, which is lowkey a glow-up and a diet at the same time. The default is to generate colour images 🌈.
  • help — shows usage information. It's giving "ask the manual, she knows" 💅.
  • hyphenate — hyphenates the text. This one requires TeX hyphenation pattern files, so it's not just vibes, it needs actual files 🎀.
  • scaleimage — scales in-line images by a factor num. The default is 1.
  • cookie — enables cookie support, using a netscape formatted cookie file (requires libwww-perl) 🍪.
  • language — specifies the language of the document (it 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) 🌍.
  • landscape — generates code for printing in landscape mode. The default is portrait mode, so this is you choosing to lay it all the way out 📐.
  • scalemath — scales mathematical formulas by a factor num. The default is 1 ➗.
  • mainchapter — specifies the start number for automatic numbering of headings (by setting the seq-number parameter). The default is 1 🔢.
  • number — inserts page numbers. The default is to not number the pages, so flip the switch if you want them counted.
  • startno — specifies the starting page number. The default is 1.
  • output — writes the PostScript code to file. The default is to write to standard output 💾.
  • original — uses 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 used instead ✨. This only works 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:
<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 — 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 📂.
  • xref — inserts cross references at every link to within the set of converted documents 🔗.
  • scaledoc — scales the entire document by a factor num. The default is 1.
  • style — this option complements/overrides definitions made in the configuration files. The string must follow the configuration file syntax. (Note: this is only supposed to be used on the command line, not in a configuration file.) 👑
  • titlepage — generates a title page. The default is to not generate one.
  • text — text mode, ignore images. The default is to include the images 🚫🖼️.
  • underline — underlines text that constitutes a hypertext link. The default is to not underline.
  • colour — produces colour output for text and background, when specified. The default is black text on white background (mnemonic: coloUr ;-) 🎨.
  • version — prints information about the current version of html2ps ⭐.
  • web — processes a web of documents by recursively retrieving and converting 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:
    • a — follow all links.
    • b — follow only links to within the same directory, or below, as the start document.
    • l — follow only links specified with "<LINK rel=NEXT>" in the document.
    • p — prompt for each remote document. This mode will automatically be entered after the first 50 documents.
    • r — follow only relative links.
    • s — follow only links to within the same server as the start document.
    • 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.
    • # — a positive integer giving the number of recursive levels. The default is 4 (when the option is present).
  • duplex — generates postscript code for single or double sided printing. No default, valid values are:
    • 0 — single sided.
    • 1 — double sided.
    • 2 — double sided, opposite page reversed (tumble mode).

🌸 The margin block 🌸

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. (Yes bestie, they moved. We don't make the rules 💀.)

  • middle — an absolute size for the distance between the columns when printing two columns per page, default is 2cm.

💫 The xref block 💫

At every hyperlink (to within the set of converted documents) it is possible to have a cross reference inserted. The xref block is used to control this function.

  • text — this defines the cross reference text to be inserted; the symbol $N will expand to the page number, default is "[p $N]".
  • 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.

🎀 The quote block 🎀

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ål), Finnish, Spanish, French, German and Italian). It is possible to define different quotation marks for quotes within quotes.

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. (Iconic messy era tbh 🙈.)

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 — the quote opening character(s).
  • close — the quote closing character(s). If undefined, it will equal open.
  • open2 — the quote opening character(s) for quotes within quotes. If undefined, it will equal open.
  • close2 — the quote closing character(s) for quotes within quotes. If undefined, it will equal close.

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:

quote {
  en {
    open: "&ldquo;";
    close: "&rdquo;";
    open2: "`";
    close2: "'";
  }
  es: en;
}

📖 The toc block 📖

When a table of contents (ToC) is generated from document headings and titles, the appearance is controlled by this block.

  • heading — a string with HTML code specifying a heading used on the first ToC page.
  • level — the maximum heading level used for building the ToC. The default is 6, which means that all headings will generate ToC entries.
  • indent — the ToC entries are indented proportional to the corresponding heading level. This value specifies the size of the indentation. The default is 1em.

👑 The titlepage block 👑

When a title page is generated, its appearance is controlled by this block.

  • content — a string with HTML code specifying a heading used on the title page. The default is "<DIV align=center> <H1><BIG>$T</BIG></H1> <H2>$[author]</H2></DIV>".
  • margin-top — the size of the top margin on the title page. The default is 4cm.

🦋 The font block 🦋

Currently, html2ps recognizes the fonts: Times, New-Century-Schoolbook, Helvetica, Helvetica-Narrow, Palatino, Avantgarde, Bookman, and Courier. To add a new font (family), choose a name (consisting of letters, digits, hyphens, and underscores) for the font. Then define a sub-block to the font block, with the same name as the chosen font name. This block can contain two key-value pairs:

  • names — bestie, this is a string of four PostScript font names, separated by whitespace, matching the font styles normal, italic, bold, and bold-italic. If you give fewer than four names, the first one is used for the missing ones. 💅 And no cap: PostScript font names are case sensitive, so don't play.
  • files — a string of four file names, separated by whitespace, for files containing font definitions for those four font styles as specified above. 📁

Example time, bestie! Say a font 'myfont' has its four font styles defined in local files. To use this font in all tables in the converted documents, one can use something like:

TABLE { font-family: myfont }

@html2ps {
  font {
    myfont {
      names: "MyFont-Roman MyFont-Italic MyFont-Bold MyFont-
      BoldItalic";
      files: "/x/y/myfr.pfa /x/y/myfi.pfa /x/y/myfb.pfa
      /x/y/myfbi.pfa";
    }
  }
}

✨ The hyphenation block ✨

Hyphenation pattern files for different languages are specified in sub-blocks within this block. The blocks names should equal the language code as defined in ISO 639. These language blocks can contain the following two key-values:

  • file — a hyphenation pattern file in TeX format for this language. 📄
  • extfile — a file containing a list of hyphenation exceptions for this language. The exception file should contain words, separated by whitespaces, with hyphens inserted where hyphenation is allowed, as in: "in-fra-struc-ture white-space". 🦋

For example, for English (with language code 'en') one can have a block like:

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 — a positive integer defining the minimum number of letters a word must contain to make it a candidate for hyphenation. The default is 8. 🔢
  • start — a positive integer defining the minimum number of letters that must precede the hyphen when a word is hyphenated. The default is 4. ✨
  • end — a positive integer defining the minimum number of letters that must follow the hyphen when a word is hyphenated. The default is 3. 💜

✨ The header block ✨

This block is used to specify page headers. It is possible to define left, center, and right headers. Different headers for odd and even pages can be specified. Some symbols can be used that will expand to document title, author, date etc. See below.

  • left — a left aligned header. If the alternate flag in this block is set to 1, this will be the right header on even pages. ⬅️
  • center — a centered header. ⚖️
  • right — a right aligned header. If the alternate flag in this block is set to 1, this will be the left header on even pages. ➡️
  • odd-left — a left aligned header on odd pages. 1️⃣
  • odd-center — a centered header on odd pages. 1️⃣
  • odd-right — a right aligned header on odd pages. 1️⃣
  • even-left — a left aligned header on even pages. 2️⃣
  • even-center — a centered header on even pages. 2️⃣
  • even-right — a right aligned header on even pages. 2️⃣
  • font-family — the font used for the header, default is Helvetica. 🖋️
  • font-size — the font size for the header, default is 8pt. 📏
  • font-style — the default is "normal". ✨
  • font-weight — the default is "normal". ✨
  • color — the header color, default is black. 🖤
  • alternate — a flag indicating whether the headers given by the left and right keys should change place on even pages. Typically used for double sided printing. The default is 1. 🔄

This block is used to specify page footers. It is possible to define left, center, and right footers. Different footers for odd and even pages can be specified. Some symbols can be used that will expand to document title, author, date etc. See below.

  • left — a left aligned footer. If the alternate flag in this block is set to 1, this will be the right footer on even pages. ⬅️
  • center — a centered footer. ⚖️
  • right — a right aligned footer. If the alternate flag in this block is set to 1, this will be the left footer on even pages. ➡️
  • odd-left — a left aligned footer on odd pages. 1️⃣
  • odd-center — a centered footer on odd pages. 1️⃣
  • odd-right — a right aligned footer on odd pages. 1️⃣
  • even-left — a left aligned footer on even pages. 2️⃣
  • even-center — a centered footer on even pages. 2️⃣
  • even-right — a right aligned footer on even pages. 2️⃣
  • font-family — the font used for the footer, default is Helvetica. 🖋️
  • font-size — the font size for the footer, default is 8pt. 📏
  • font-style — the default is "normal". ✨
  • font-weight — the default is "normal". ✨
  • color — the footer color, default is black. 🖤
  • alternate — a flag indicating whether the footers given by the left and right keys should change place on even pages. Typically used for double sided printing. The default is 1. 🔄

✨ The frame block ✨

The appearance of the optional frame (drawn on each page) is controlled by this block.

  • width — the width of the frame, default is 0.6pt. 📏
  • margin — the size of the frame margin, default is 0.5cm. 📐
  • color — the colour of the frame, default is black. 🖤

✨ The justify block ✨

This block specifies the maximum amount of extra space inserted between words and letters when text justification is in effect.

  • word — maximum amount of extra space inserted between words. The default is 15pt. 📏
  • letter — maximum amount of extra space inserted between letters within words. The default is 0pt. ✨

✨ The draft block ✨

It is possible to have some text written in a large font diagonally across each page. Typically this is a word, written in a very light colour, indicating that the document is a draft.

  • text — the text to be printed, default is "DRAFT". 📝
  • print — a flag specifying whether the draft text should be printed or not. If unspecified, the draft text is printed when the document head contains <META name="Status" content="Draft">. 🖨️
  • dir — specifies print direction, 0=downwards, 1=upwards. ⬇️⬆️
  • font-family — the default is Helvetica. 🖋️
  • font-style — the default is "normal". ✨
  • font-weight — the default is "bold". 💪
  • color — the default is "F0F0F0". 🎨

✨ The colour block ✨

The 16 standard colour names from HTML 4.01 (although their use in HTML elements are now deprecated) are recognized by html2ps. Use this block to extend this list of colours. This is done with key-value pairs, where the key is the colour name, and the value is the colour given as a hexadecimal RGB value, for example: "brown: A52A2A;". 🌈

✨ Key-value pairs in the @html2ps block ✨

  • html2psrc — the name of the default personal configuration file. The default is $HOME/.html2psrc. 🏠
  • imgalt — specifies which text should be written as a replacement for in-line images when the IMG element has no ALT attribute. The default is "[IMAGE]". 🖼️
  • datefmt — the symbol $D can be used in page headers and footers to insert the current date/time; the value of the 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 " 7 May 2010 13:22". 📅
  • locale — the locale (language code) used for formating language dependent parts of the date/time in datefmt. If unspecified, the value is taken from environment variables, see setlocale(3). No default. 🌍
  • doc-sep — a string of HTML code that will be inserted between the documents when more than one are converted. The default is "<!--NewPage-->", which will cause a page break. You may use (almost) any HTML code, for example "<HR><HR>" or "<IMG src=...>". ✂️
  • ball-radius — the radius, given as a relative size, of the balls used in unordered lists. The default is 0.25em. 🔴
  • numbstyle — page numbering style, 0=arabic, 1=roman. The default is 0. 🔢
  • showurl — when this flag is set to 1, the URL for external links are shown within parentheses after the link. The default is 0. 🔗
  • seq-number — when this flag is set, the headings in the document will be sequentially numbered: H1 headings will be numbered 1, 2,..., H2 headings 1.1, 1.2, etc. The starting number for H1 can be changed using the -M (--mainchapter) option. The default is 0. 🔢
  • extrapage — a flag specifying whether an extra (empty) page should be printed, when necessary, to ensure that the title page, the table of contents, and the document itself will start on odd pages. This is typically desirable for double sided printing. The default is 1. 📄
  • break-table — a flag specifying if a table should be broken across two pages when it does not fit on the current page, but it does on a page of its own. The default is 0 (avoid breaking tables when possible). 📊
  • forms — this flag is used to specify whether FORM elements in the document should be processed or ignored. Some forms may be suitable for printing out and be filled out (with a pen), others are not. The default is 1. 📝
  • textarea-data — when a TEXTAREA element contains prefilled data, the text will be used as labels if this flag is set, otherwise ignored. The default is 0. 📝
  • page-break — set this flag to 0 to suppress the normal behavior of generating page breaks from the comment <!--NewPage--> etc, as specified below. The default is 1. 📄
  • expand-acronyms — a lil flag that says whether acronyms (the ones coming from the ACRONYM element) get expanded or not. Default? 0. 🙅♀️
  • spoof — okay so some web servers are messy and hand you a different document depending on which user agent asked for it. If you wanna fool the server into thinking you're some specific browser, set this to that browser's identification, like "Mozilla/4.0". Heads up though: this only works if you're using one of the Perl packages to retrieve remote documents. 💅
  • ssi — when this flag is set, some Server Side Includes get processed while the document is being read from a local file. Examples: <!--#include file=...>, <!--#echo var="LAST_MODIFIED">, <!--#config timefmt=...>. Default is 0. ✨
  • prefilled — this flag decides whether the content of form elements gets rendered or not. So when it's on, the content of TEXTAREA elements and the value of the value attribute of text INPUT elements will be shown, and checked radio buttons and checkboxes get marked too. Default is 0. 🎀

🔮 SYMBOLS 🔮

These symbols are usable on the title page, the page headers/footers, and in the heading for the table of contents. Slay. 💖

Symbols shaped like "$[name]" expand to the value of the content attribute of META elements that have either of the attributes "name=name" or "http-equiv=name" — and yes, that's case insensitive string matching. So for example, when a document containing:

<META name="expires" content="31 Dec 2011">

gets converted using a configuration file with:

footer { left: "Expires: $[expires]" }

this left footer gets inserted:

Expires: 31 Dec 2011

And on top of that, these symbols are also defined:

  • $T — current document title. 👑
  • $A — author of the current document, as specified with <META name="Author" content="..."> in the document head.
  • $U — the URL, or file name, of the current document.
  • $N — page number.
  • $H — current document heading (level 1-3).
  • $D — current date/time. The format is given by the datefmt key.

So $A is equivalent to $[author], but it's kept around for backwards compatibility. 🫶

Wanna stop a symbol from expanding? Just put a backslash before the dollar sign, like "\$T". Iconic escape behaviour, no cap. 💅

💡 HINTS 💡

Okay so picture this: a typical use of configuration files probably looks something like this. 🌈

System specific definitions (like specifying which program packages are available) and global defaults (paper type, etc.) get defined in the global configuration file.

If more than one person uses the program on the system, each user can also have a personal configuration file with their own personal preferences. (On a single user system, you can just use the global configuration file for this purpose too. 🫶)

You can also build a whole collection of configuration files for typical situations. Those files live in a directory that html2ps searches — and that search path is defined with the environment variable HTML2PSPATH. For example, to print a document as slides — landscape mode, big Helvetica text, thick frame — you could make 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. But watch out bestie — with this command, the file 'slides' is used instead of the personal configuration file. If you want both to be used, giving precedence to the definitions made in the file 'slides', use:

html2ps -f :slides ...

(The page breaks between the slides can, for example, be generated by adding '<HR class=PAGE-BREAK>' to the HTML document. ✨)

Now, for features that get turned on and off a lot — ones that can't be controlled by command line options — it might be a great idea to make lil tiny configuration files as "building blocks". For example a file 'A4' for printing on A4 paper (if you've got 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 — you'd use:

html2ps -f :slides:A4:hnum ...

Compositional config files? We love to see it. 🦋

👀 SEE ALSO 👀

html2ps(1), setlocale(3), strftime(3)

🏷️ VERSION 🏷️

This manpage describes html2ps version 1.0 beta7.

🌐 AVAILABILITY 🌐

http://user.it.uu.se/~jan/html2ps.html

👑 AUTHOR 👑

Jan Karrman (jan@it.uu.se)

That's the whole page, bestie, we ate and left no crumbs. 💅 Shoutout to the autogenerated footer: it says html2psrc(5), dated 7 May 2010. Periodt. 💖✨🎀

📦 where this page comes from