1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
|
.TH HTMLROFF 7
.SH NAME
htmlroff \- HTML formatting and typesetting
.SH DESCRIPTION
.IR Htmlroff (1)
accepts
.I troff
input with a few extensions and changes.
This manual describes the changes to the input language,
assuming a working knowledge of
.I troff
itself.
.SS Name lengths
.PP
Request, macro, string, and number names can be longer
than two letters, as in:
.IP
.EX
\&.html c <center>
\&.de footnote
Footnote here.
\&..
\&.footnote
\&.ds string "hello
\&\e*[string]
\&.nr number 1
\&\en[number]
.EE
.SS HTML output
.PP
Two new requests:
.IP
.EX
\&.html \fIid\fP \fR[ \fI<html>\fP ]\fL
\&.ihtml \fIid\fP \fR[ \fI<ihtml>\fP ]\fL
.EE
.LP
.B .html
and
.B .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
.IR id .
For example, the input:
.IP
.EX
\&.html t <table><tr>
\&.html td <td>Cell 1
\&.html td <td>Cell 2
\&.html td
\&.html t
.EE
.LP
produces this output:
.IP
.EX
<table><tr><td>Cell 1</td><td>Cell 2</td></tr></table>
.EE
.LP
The
.B .html
request is intended for block-level HTML constructs (those that can contain
.BR <p> )
and maintains the HTML tag stack automatically.
Intermediate tags need not be explicitly closed:
removing the final
.B \&.html t
line in the example above would produce the same output.
The special
.I id
.L -
closes the HTML tags immediately after printing them.
.PP
The
.B .ihtml
request is similar to
.B .html
but is intended for inline HTML constructs such as
.B <b>
or
.B <i>
(those that can be contained
within
.BR <p> ).
Unlike
.BR .html ,
.B .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,
.B .ihtml
treats nesting properly in the output,
closing and reopening tags as necessary.
For example, the input:
.IP
.EX
\&.ihtml style <b>
\&.ihtml link <a href="link.html">
Bold
\&.ihtml style <i>
and italic, still linked.
\&.ihtml link <a>
Unlinked.
\&.ihtml style
.EE
.LP
produces this output:
.IP
.EX
<b><a href="link.html">Bold</a></b>
<i><a href="link.html">and italic, still linked.</i></a>
<i>Unlinked.</i>
.EE
.PP
Outside of
.B .html
and
.B .ihtml
requests, the characters
.L < ,
.L > ,
and
.L &
are treated as normal characters, not HTML markers,
and are translated to
.L < ,
.L > ,
and
.L &
on output.
To embed the raw HTML markers, use
.L \e< ,
.L \e> ,
and
.L \e@
.RI [ sic ].
.SS Font changes
.PP
.I Htmlroff
interprets the usual
.BR \ef ,
.BR .ft ,
.BR \es ,
and
.B .ps
requests to change the font and point size.
After applying each such change to its internal registers,
.I htmlroff
invokes the
.B .font
macro to emit corresponding HTML.
The default definition of
.B .font
is:
.IP
.EX
\&.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>
\&..
.EE
.LP
Input files can redefine
.B .font
like any other request or macro.
.SS Paragraphs
.I Htmlroff
implements line height, text adjustment, and margins by
wrapping all output text in
.B <p style="...">
tags.
This behavior can be disabled by setting the
.B .paragraph
number register to zero.
Setting the
.B .margin
register to zero
eliminates only the margin annotations.
.SS Subscripts and superscripts
.PP
.I Htmlroff
interprets the
.BR \eu ,
.BR \ed ,
and
.BR \ev
requests to move vertically during output.
It emits output vertically offset up the page inside
.B <sup>
tags and output vertically offset down the page
inside
.B <sub>
tags.
This heuristic handles simple equations formatted by
.IR eqn (1).
.SS Conditional input
.PP
To make it easier to write input files that can be formatted by both
.I troff
and
.IR htmlroff ,
.I htmlroff
adds a new condition
.B h
which evaluates true in
.B .if
and
.B .ie
requests.
The
.B t
condition continues to evaluate true, to accomodate
input files trying to distinguish between
.I troff
and
.IR nroff .
To write a conditional matching
.I troff
alone, use
.RB ` ".if !h .if t" '.
.PP
.I Htmlroff 's
handling of conditional input does not match
.IR troff 's
exactly.
For example,
.IP
.EX
\&.if 0 \e{\e
\&.de xx
\&..
\&.\e}
.EE
.LP
redefines the
.B xx
macro in
.I troff
but not in
.IR htmlroff .
Do not write files depending on this behavior, as this bug may be fixed
in the future.
.I Htmlroff
also mishandles
.B \e}
in some cases. To work around them, use
.B .\e}
on a line by itself, as in the last example.
.SS Diversions
.PP
Diversions in
.I htmlroff
use the alignment in effect at the time of the
diversion
when output.
In particular,
.IP
.EX
\&.di xx
Line here.
\&.di
\&.nf
\&.ce
\&.xx
.EE
.LP
produces a centered line in
.I troff
but not in
.IR htmlroff .
The solution is to center inside the diversion, as in
.IP
.EX
\&.di xx
\&.if h .ce 999
Line here
\&.di
.EE
.SS Input pipes
.PP
.I Htmlroff
adds a new request
.B .inputpipe
.I stop
.I cmd
that redirects
.I htmlroff 's
input into a pipe to the
given
.I cmd .
The redirection stops on encountering the line
.IR stop ,
optionally followed by white space and extra text.
This is a dangerous and clusmy request, as
.I htmlroff
stops interpreting its input during the redirection, so
.I stop
must be found in the input itself, not in a macro that
the input might appear to call.
Although clusmy,
.B .inputpipe
allows input files to invoke
.I troff
to handle complicated input.
For example,
.B tmac.html
redefines the
.B PS
macro that marks the beginning of a
.IR pic (1)
picture:
.IP
.EX
\&.nr png -1 1
\&.de PS
\&.ds pngbase "\e\e*[basename]
\&.if '\e\e*[pngbase]'' .ds pngbase \e\en(.B
\&.ds pngfile \e\e*[pngbase]\e\en+[png].png
\&.html - <center><img src="\e\e*[pngfile]"></center>
\&.inputpipe .PE troff2png >\e\e*[pngfile]
\&..
.EE
.LP
This macro invokes the shell script
.I 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 .B
register holds the final path element
(the base name) of the current input file.
|