# Chapter 6 - 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.

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 | See Below
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 | See Below
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.
`<!-- 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`
  Inserts the current date.
`$HEADING`
  Inserts the current heading.
`$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`
  Inserts the current time.
`$TITLE`
  Inserts the document title.

## 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
Helvetica | Helvetica
Monospace | Courier
Sans-Serif | Helvetica
Serif | Times
Symbol | Symbol
Times | Times

All other unrecognized typefaces are silently ignored.

## Headings

Currently HTMLDOC supports a maximum of 10000 headings and 100 chapters. These limits can be increased by changing the constants 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 H6). Each chapter starts a new page or the next odd-numbered page if duplexing is selected.

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 BMP, GIF, JPEG, and PNG image files. EPS and other types of image files are not supported at this time.

## Links

Currently HTMLDOC supports a maximum of 20000 links within a document. This limit can be increased by changing the constant in the config.h file included with the source code.

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="KEYWORDS" CONTENT="..."`
  Specifies document search keywords.

## Page Breaks

HTMLDOC supports four new page comments to specify page breaks. In addition, the older `BREAK` attribute is still supported by the `HR` element:

    <HR BREAK>

Support for the `BREAK` attribute is deprecated and will be removed in a future release of HTMLDOC.

## 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 supports HTML 3.0 tables with the following exceptions:

- The `CAPTION` element is always shown at the top of the table.

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