term% cat index.txt HTMLROFF(6) Games Manual HTMLROFF(6)
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 let‐
ters, 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 re‐
opening 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 and on out‐
put. 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 inter‐
nal 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 wrap‐
ping 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 dur‐
ing 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 ex‐
actly. 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 fu‐
ture. 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
Traps
Htmlroff implements traps at vertical position 0, which run when the
first character is about to be printed. Other position traps are ig‐
nored. Input traps are implemented.
Input pipes
Htmlroff adds a new request .inputpipe stop cmd that redirects html‐
roff's input into a pipe to cmd. The redirection stops on encountering
the line stop, optionally followed by white space and extra text. This
is a dangerous and clumsy request, as htmlroff stops interpreting its
input during the redirection, so stop must be found in the input it‐
self, not in a macro that the input might appear to call. Although
clumsy, .inputpipe allows input files to invoke troff to handle compli‐
cated 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 pro‐
gram, the macro creates a new file name for the image and prints HTML
referring to it. The .B register holds the final path element (the
base name) of the current input file.
Unimplemented
Tabs are set every eight spaces and cannot be changed.
Some requests, such as .tl, are unimplemented for lack of a good imple‐
mentation. Workarounds can be defined as necessary in input files.
SEE ALSO
htmlroff(1), mhtml(6)
HTMLROFF(6)