HTMLROFF(6)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 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> ]\fL
.ihtml id [ <ihtml> ]\fL
.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
<,
>,
and
&
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=\"font-size=\\n(.spt\">
.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
Traps
Htmlroff
implements traps at vertical position 0,
which run when the first character is about
to be printed.
Other position traps are ignored.
Input traps are implemented.
Input pipes
Htmlroff
adds a new request
.inputpipe
stop
cmd
that redirects
htmlroff’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 itself, not in a macro that
the input might appear to call.
Although clumsy,
.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
.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 implementation.
Workarounds can be defined as necessary in input files.
SEE
htmlroff(1),
mhtml(6)