| HTMLROFF(7) | HTMLROFF(7)

NAME

| htmlroff – HTML formatting and typesetting

DESCRIPTION

Htmlroff (1) accepts troff input with a few extensions and changes. This manual describes the changes to the input language, assuming a working knowledge of troff itself.

Name lengths

Request, macro, string, and number names can be longer than two letters, as in:

| `.html c <center> .de footnote Footnote here. .. .footnote .ds string "hello \*[string] .nr number 1 \n[number]`

HTML output

Two new requests:

`.html` id [ <html> ]
`.ihtml` id [ <ihtml> ]

`.html` and `.ihtml` insert HTML into the output. The requests are only for opening new HTML tags. To close previously-opened tags, repeat the request with the same id. For example, the input:

`.html t <table><tr>
.html td <td>Cell 1
.html td <td>Cell 2
.html td
.html t

`

produces this output:

`<table><tr><td>Cell 1</td><td>Cell 2</td></tr></table>

`

The `.html` request is intended for block-level HTML constructs (those that can contain `<p>`) and maintains the HTML tag stack automatically. Intermediate tags need not be explicitly closed: removing the final `.html t` line in the example above would produce the same output. The special id `−` closes the HTML tags immediately after printing them.

The `.ihtml` request is similar to `.html` but is intended for inline HTML constructs such as `<b>` or `<i>` (those that can be contained within `<p>`). Unlike `.html`, `.ihtml` treats the open HTML tags as a set rather than a stack: each must be explicitly closed. Although it treats the tags as a set, `.ihtml` treats nesting properly in the output, closing and reopening tags as necessary. For example, the input:

`.ihtml style <b>
.ihtml link <a href="link.html">
Bold
.ihtml style <i>
and italic, still linked.
.ihtml link <a>
Unlinked.
.ihtml style

`

produces this output:

`<b><a href="link.html">Bold</a></b>
<i><a href="link.html">and italic, still linked.</i></a>
<i>Unlinked.</i>

`

Outside of `.html` and `.ihtml` requests, the characters `< , > ,` and `&` are treated as normal characters, not HTML markers, and are translated to `&lt; , &gt; ,` and `&amp;` on output. To embed the raw HTML markers, use `\< , \> ,` and `\@` [sic].

Font changes

Htmlroff interprets the usual `\f`, `.ft`, `\s`, and `.ps` requests to change the font and point size. After applying each such change to its internal registers, htmlroff invokes the `.font` macro to emit corresponding HTML. The default definition of `.font` is:

`.de font
.ihtml f1
.ihtml f
.ihtml f <span style=
.if \n(.f==2 .ihtml f1 <i>
.if \n(.f==3 .ihtml f1 <b>
.if \n(.f==4 .ihtml f1 <b><i>
.if \n(.f==5 .ihtml f1 <tt>
.if \n(.f==6 .ihtml f1 <tt><i>
..

`

Input files can redefine `.font` like any other request or macro.

Paragraphs
Htmlroff implements line height, text adjustment, and margins by wrapping all output text in `<p style="...">` tags. This behavior can be disabled by setting the `.paragraph` number register to zero. Setting the `.margin` register to zero eliminates only the margin annotations.

Subscripts and superscripts

Htmlroff interprets the `\u`, `\d`, and `\v` requests to move vertically during output. It emits output vertically offset up the page inside `<sup>` tags and output vertically offset down the page inside `<sub>` tags. This heuristic handles simple equations formatted by eqn(1).

Conditional input

To make it easier to write input files that can be formatted by both troff and htmlroff, htmlroff adds a new condition `h` which evaluates true in `.if` and `.ie` requests. The `t` condition continues to evaluate true, to accomodate input files trying to distinguish between troff and nroff. To write a conditional matching troff alone, use ‘`.if !h .if t`’.

Htmlroff ’s handling of conditional input does not match troff’s exactly. For example,

`.if 0 \{\
.de xx
..
.\}

`

redefines the `xx` macro in troff but not in htmlroff. Do not write files depending on this behavior, as this bug may be fixed in the future. Htmlroff also mishandles `\}` in some cases. To work around them, use `.\}` on a line by itself, as in the last example.

Diversions

Diversions in htmlroff use the alignment in effect at the time of the diversion when output. In particular,

`.di xx
Line here.
.di
.nf
.ce
.xx

`

produces a centered line in troff but not in htmlroff. The solution is to center inside the diversion, as in

| `.di xx .if h .ce 999 Line here .di`

Input pipes

Htmlroff adds a new request `.inputpipe` stop cmd that redirects htmlroff ’s input into a pipe to the given cmd . The redirection stops on encountering the line stop, optionally followed by white space and extra text. This is a dangerous and clusmy request, as htmlroff stops interpreting its input during the redirection, so stop must be found in the input itself, not in a macro that the input might appear to call. Although clusmy, `.inputpipe` allows input files to invoke troff to handle complicated input. For example, `tmac.html` redefines the `PS` macro that marks the beginning of a pic(1) picture:

`.nr png −1 1
.de PS
.ds pngbase "\\*[basename]
.if '\\*[pngbase]'' .ds pngbase \\n(.B
.ds pngfile \\*[pngbase]\\n+[png].png
.html − <center><img src="\\*[pngfile]"></center>
.inputpipe .PE troff2png >\\*[pngfile]
..

`

This macro invokes the shell script troff2png to run troff and convert the Postscript output to a PNG image file. Before starting the program, the macro creates a new file name for the image and prints HTML referring to it. The new `.B` register holds the final path element (the base name) of the current input file.