htmlroff(7) - Plan 9 from User Space

| 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.