# Chapter 4 - HTML Reference

This chapter defines all of the HTML elements and attributes that are recognized and supported by HTMLDOC.

## General Usage

There are two types of HTML files - structured documents using headings (H1, H2, etc.) which HTMLDOC calls "books", and unstructured documents that do not use headings which HTMLDOC calls "web pages".

A very common mistake is to try converting a web page using:

    htmldoc -f filename.pdf filename.html

which will likely produce a PDF file with no pages. To convert web page files you must use the `--webpage` option at the command-line or choose Web Page in the input tab of the GUI.

> Note: HTMLDOC does not support HTML 4.0 elements, attributes, stylesheets, or scripting.

## Elements

The following HTML elements are recognized by HTMLDOC:

Element | Version | Supported? | Notes
--- | --- | --- | ---
!DOCTYPE | 3.0 | Yes | DTD is ignored
A | 1.0 | Yes | See Below
ACRONYM | 2.0 | Yes | No font change
ADDRESS | 2.0 | Yes |
AREA | 2.0 | No |
B | 1.0 | Yes |
BASE | 2.0 | No |
BASEFONT | 1.0 | No |
BIG | 2.0 | Yes |
BLINK | 2.0 | No |
BLOCKQUOTE | 2.0 | Yes |
BODY | 1.0 | Yes |
BR | 2.0 | Yes |
CAPTION | 2.0 | Yes |
CENTER | 2.0 | Yes |
CITE | 2.0 | Yes | Italic/Oblique
CODE | 2.0 | Yes | Courier
DD | 2.0 | Yes |
DEL | 2.0 | Yes | Strikethrough
DFN | 2.0 | Yes | Helvetica
DIR | 2.0 | Yes |
DIV | 3.2 | Yes |
DL | 2.0 | Yes |
DT | 2.0 | Yes | Italic/Oblique
EM | 2.0 | Yes | Italic/Oblique
EMBED | 2.0 | Yes | HTML Only
FONT | 2.0 | Yes | See Below
FORM | 2.0 | No |
FRAME | 3.2 | No |
FRAMESET | 3.2 | No |
H1 | 1.0 | Yes | Boldface, See Below
H2 | 1.0 | Yes | Boldface, See Below
H3 | 1.0 | Yes | Boldface, See Below
H4 | 1.0 | Yes | Boldface, See Below
H5 | 1.0 | Yes | Boldface, See Below
H6 | 1.0 | Yes | Boldface, See Below
HEAD | 1.0 | Yes |
HR | 1.0 | Yes |
HTML | 1.0 | Yes |
I | 1.0 | Yes |
IMG | 1.0 | Yes | See Below
INPUT | 2.0 | No |
INS | 2.0 | Yes | Underline
ISINDEX | 2.0 | No |
KBD | 2.0 | Yes | Courier Bold
LI | 2.0 | Yes |
LINK | 2.0 | No |
MAP | 2.0 | No |
MENU | 2.0 | Yes |
META | 2.0 | Yes | See Below
MULTICOL | N3.0 | No |
NOBR | 1.0 | No |
NOFRAMES | 3.2 | No |
OL | 2.0 | Yes |
OPTION | 2.0 | No |
P | 1.0 | Yes |
PRE | 1.0 | Yes |
S | 2.0 | Yes | Strikethrough
SAMP | 2.0 | Yes | Courier
SCRIPT | 2.0 | No |
SELECT | 2.0 | No |
SMALL | 2.0 | Yes |
SPACER | N3.0 | Yes |
STRIKE | 2.0 | Yes |
STRONG | 2.0 | Yes | Boldface Italic/Oblique
SUB | 2.0 | Yes | Reduced Fontsize
SUP | 2.0 | Yes | Reduced Fontsize
TABLE | 2.0 | Yes | See Below
TD | 2.0 | Yes |
TEXTAREA | 2.0 | No |
TH | 2.0 | Yes | Boldface Center
TITLE | 2.0 | Yes |
TR | 2.0 | Yes |
TT | 2.0 | Yes | Courier
U | 1.0 | Yes |
UL | 2.0 | Yes |
VAR | 2.0 | Yes | Helvetica Oblique
WBR | 1.0 | No |

## Comments

HTMLDOC supports many special HTML comments to initiate page breaks, set the header and footer text, and control the current media options:

`<!-- FOOTER LEFT "foo" -->`
  Sets the left footer text; the test is applied to the current page if empty, or the next page otherwise.
`<!-- FOOTER CENTER "foo" -->`
  Sets the center footer text; the test is applied to the current page if empty, or the next page otherwise.
`<!-- FOOTER RIGHT "foo" -->`
  Sets the right footer text; the test is applied to the current page if empty, or the next page otherwise.
`<!-- HALF PAGE -->`
  Break to the next half page.
`<!-- HEADER LEFT "foo" -->`
  Sets the left header text; the test is applied to the current page if empty, or the next page otherwise.
`<!-- HEADER CENTER "foo" -->`
  Sets the center header text; the test is applied to the current page if empty, or the next page otherwise.
`<!-- HEADER RIGHT "foo" -->`
  Sets the right header text; the test is applied to the current page if empty, or the next page otherwise.
`<!-- MEDIA BOTTOM nnn -->`
  Sets the bottom margin of the page. The "nnn" string can be any standard measurement value, e.g. 0.5in, 36, 12mm, etc. Breaks to a new page if the current page is already marked.
`<!-- MEDIA COLOR "foo" -->`
  Sets the media color attribute for the page. The "foo" string is any color name that is supported by the printer, e.g. "Blue", "White", etc. Breaks to a new page or sheet if the current page is already marked.
`<!-- MEDIA DUPLEX NO -->`
  Chooses single-sided printing for the page; breaks to a new page or sheet if the current page is already marked.
`<!-- MEDIA DUPLEX YES -->`
  Chooses double-sided printing for the page; breaks to a new sheet if the current page is already marked.
`<!-- MEDIA LANDSCAPE NO -->`
  Chooses portrait orientation for the page; breaks to a new page if the current page is already marked.
`<!-- MEDIA LANDSCAPE YES -->`
  Chooses landscape orientation for the page; breaks to a new page if the current page is already marked.
`<!-- MEDIA LEFT nnn -->`
  Sets the left margin of the page. The "nnn" string can be any standard measurement value, e.g. 0.5in, 36, 12mm, etc. Breaks to a new page if the current page is already marked.
`<!-- MEDIA POSITION nnn -->`
  Sets the media position attribute (input tray) for the page. The "nnn" string is an integer that usually specifies the tray number. Breaks to a new page or sheet if the current page is already marked.
`<!-- MEDIA RIGHT nnn -->`
  Sets the right margin of the page. The "nnn" string can be any standard measurement value, e.g. 0.5in, 36, 12mm, etc. Breaks to a new page if the current page is already marked.
`<!-- MEDIA SIZE foo -->`
  Sets the media size to the specified size. The "foo" string can be "Letter", "Legal", "Universal", or "A4" for standard sizes or "WIDTHxHEIGHTunits" for custom sizes, e.g. "8.5x11in"; breaks to a new page or sheet if the current page is already marked.
`<!-- MEDIA TOP nnn -->`
  Sets the top margin of the page. The "nnn" string can be any standard measurement value, e.g. 0.5in, 36, 12mm, etc. Breaks to a new page if the current page is already marked.
`<!-- MEDIA TYPE "foo" -->`
  Sets the media type attribute for the page. The "foo" string is any type name that is supported by the printer, e.g. "Plain", "Glossy", etc. Breaks to a new page or sheet if the current page is already marked.
`<!-- NEED length -->`
  Break if there is less than `length` units left on the current page. The `length` value defaults to lines of text but can be suffixed by `in`, `mm`, or `cm` to convert from the corresponding units.
`<!-- NEW PAGE -->`
  Break to the next page.
`<!-- NEW SHEET -->`
  Break to the next sheet.
`<!-- NUMBER-UP nn -->`
  Sets the number of pages that are placed on each output page. Valid values are 1, 2, 4, 6, 9, and 16.
`<!-- PAGE BREAK -->`
  Break to the next page.

### Header/Footer Strings

The `HEADER` and `FOOTER` comments allow you to set an arbitrary string of text for the left, center, and right headers and footers. Each string consists of plain text; special values or strings can be inserted using the dollar sign (`$`):

`$$`
  Inserts a single dollar sign in the header.
`$CHAPTER`
  Inserts the current chapter heading.
`$CHAPTERPAGE`
`$CHAPTERPAGE(format)`
  Inserts the current page number within a chapter or file. When a format is specified, uses that numeric format (1 = decimal, i = lowercase roman numerals, I = uppercase roman numerals, a = lowercase ascii, A = uppercase ascii) for the page numbers.
`$CHAPTERPAGES`
`$CHAPTERPAGES(format)`
  Inserts the total page count within a chapter or file. When a format is specified, uses that numeric format (1 = decimal, i = lowercase roman numerals, I = uppercase roman numerals, a = lowercase ascii, A = uppercase ascii) for the page count.
`$DATE`
`$DATE(format)`
  Inserts the current date. See Date/Time Formats for details on the format string. When no format is supplied, the default date format for the current locale is used.
`$HEADING`
  Inserts the current heading.
`$HFIMAGE1`
`$HFIMAGE2`
`$HFIMAGE3`
`$HFIMAGE4`
`$HFIMAGE5`
`$HFIMAGE6`
`$HFIMAGE7`
`$HFIMAGE8`
`$HFIMAGE9`
`$HFIMAGE10`
  Inserts the specified header/footer image; all other text in the string will be ignored.
`$LETTERHEAD`
  Inserts the logo image as a letterhead with no down-scaling; all other text in the string will be ignored.
`$LOGOIMAGE`
  Inserts the logo image; all other text in the string will be ignored.
`$PAGE`
`$PAGE(format)`
  Inserts the current page number. When a format is specified, uses that numeric format (1 = decimal, i = lowercase roman numerals, I = uppercase roman numerals, a = lowercase ascii, A = uppercase ascii) for the page numbers.
`$PAGES`
`$PAGES(format)`
  Inserts the total page count. When a format is specified, uses that numeric format (1 = decimal, i = lowercase roman numerals, I = uppercase roman numerals, a = lowercase ascii, A = uppercase ascii) for the page count.
`$TIME`
`$TIME(format)`
  Inserts the current time. See Date/Time Formats for details on the format string. When no format is supplied, the default time format for the current locale is used.
`$TITLE`
  Inserts the document title.
`$URL`
  Inserts the document filename or URL.

### Date/Time Formats

The `$DATE` and `$TIME` header/footer strings support an optional format string in parenthesis. Letters represent date/time values while other characters are inserted verbatim. The following letters are supported:

Letter | Description
--- | ---
`A` | Full weekday name
`a` | Abbreviated weekday name
`B` | Full month name
`b` | Abbreviated month name
`C` | Century (CC)
`c` | Default date and time format
`d` | Day of the month ("01" to "31")
`e` | Day of the month (" 1" to "31")
`F` | YYYY-MM-DD
`H` | Hours for 24-hour clock ("00" to "23")
`I` | Hours for 12-hour clock ("01" to "12")
`j` | Day of the year ("001" to "366")
`k` | Hours for 24-hour clock (" 0" to "23")
`l` | Hours for 12-hour clock (" 1" to "12")
`M` | Minutes ("00" to "59")
`m` | Month number ("01" to "12")
`p` | "am" or "pm"
`R` | Hours and minutes ("HH:MM")
`r` | Hours, minutes, seconds, and am/pm ("HH:MM:SS am/pm")
`S` | Seconds ("00" to "60")
`T` | Hours, minutes, and seconds ("HH:MM:SS")
`X` | Default time format
`x` | Default date format
`Y` | Year with century (CCYY)
`y` | Year without century (YY)
`Z` | Time zone name
`z` | Time zone offset from UTC

## FONT Attributes

Limited typeface specification is currently supported to ensure portability across platforms and for older PostScript printers:

Requested Font | Actual Font
--- | ---
Arial | Helvetica
Courier | Courier
Dingbats | Dingbats
Helvetica | Helvetica
Monospace | DejaVu Sans Mono
Sans | DejaVu Sans
Serif | DejaVu Serif
Symbol | Symbol
Times | Times

All other unrecognized typefaces are silently ignored.

## Headings

Currently HTMLDOC supports a maximum of 1000 chapters (H1 headings). This limit can be increased by changing the `MAX_CHAPTERS` constant in the config.h file included with the source code.

All chapters start with a top-level heading (H1) markup. Any headings within a chapter must be of a lower level (H2 to H15). Each chapter starts a new page or the next odd-numbered page if duplexing is selected.

> Note: Heading levels 7 to 15 are not standard HTML and will not likely be recognized by most web browsers.

The headings you use within a chapter must start at level 2 (H2). If you skip levels the heading will be shown under the last level that was known. For example, if you use the following hierarchy of headings:

    <H1>Chapter Heading</H1>
    ...
    <H2>Section Heading 1</H2>
    ...
    <H2>Section Heading 2</H2>
    ...
    <H3>Sub-Section Heading 1</H3>
    ...
    <H4>Sub-Sub-Section Heading 1</H4>
    ...
    <H4>Sub-Sub-Section Heading 2</H4>
    ...
    <H3>Sub-Section Heading 2</H3>
    ...
    <H2>Section Heading 3</H2>
    ...
    <H4>Sub-Sub-Section Heading 3</H4>
    ...

the table-of-contents that is generated will show:

- Chapter Heading
  - Section Heading 1
  - Section Heading 2
    - Sub-Section Heading 1
      - Sub-Sub-Section Heading 1
      - Sub-Sub-Section Heading 2
    - Sub-Section Heading 2
      - Sub-Sub-Section Heading 3
  - Section Heading 3

### Numbered Headings

When the numbered headings option is enabled, HTMLDOC recognizes the following additional attributes for all heading elements:

`VALUE="#"`
  Specifies the starting value for this heading level (default is "1" for all new levels).
`TYPE="1"`
  Specifies that decimal numbers should be generated for this heading level.
`TYPE="a"`
  Specifies that lowercase letters should be generated for this heading level.
`TYPE="A"`
  Specifies that uppercase letters should be generated for this heading level.
`TYPE="i"`
  Specifies that lowercase roman numerals should be generated for this heading level.
`TYPE="I"`
  Specifies that uppercase roman numerals should be generated for this heading level.

## Images

HTMLDOC supports loading of GIF, JPEG, and PNG image files. BMP image support is deprecated and will be removed in a future version of HTMLDOC. EPS and other types of image files are not supported at this time.

## Links

External URL and internal (`#target` and `filename.html`) links are fully supported for HTML and PDF output.

When generating PDF files, local PDF file links will be converted to external file links for the PDF viewer instead of URL links. That is, you can directly link to another local PDF file from your HTML document with:

    <A HREF="filename.pdf">...</A>

## META Attributes

HTMLDOC supports the following `META` attributes for the title page and document information:

`<META NAME="AUTHOR" CONTENT="..."`
  Specifies the document author.
`<META NAME="COPYRIGHT" CONTENT="..."`
  Specifies the document copyright.
`<META NAME="DOCNUMBER" CONTENT="..."`
  Specifies the document number.
`<META NAME="GENERATOR" CONTENT="..."`
  Specifies the application that generated the HTML file.
`<META NAME="HTMLDOC.filename" CONTENT="..."`
  Specifies the filename that is reported in CGI mode.
`<META NAME="KEYWORDS" CONTENT="..."`
  Specifies document search keywords.
`<META NAME="SUBJECT" CONTENT="..."`
  Specifies document subject.

## Tables

Currently HTMLDOC supports a maximum of 200 columns within a single table. This limit can be increased by changing the `MAX_COLUMNS` constant in the config.h file included with the source code.

HTMLDOC does not support HTML 4.0 table elements or attributes, such as `TBODY`, `THEAD`, `TFOOT`, or `RULES`.