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