1 37052ddc 2006-03-19 devnull .TH HTMLROFF 7
3 37052ddc 2006-03-19 devnull htmlroff \- HTML formatting and typesetting
4 37052ddc 2006-03-19 devnull .SH DESCRIPTION
5 d32deab1 2020-08-16 rsc .MR Htmlroff (1)
8 37052ddc 2006-03-19 devnull input with a few extensions and changes.
9 37052ddc 2006-03-19 devnull This manual describes the changes to the input language,
10 37052ddc 2006-03-19 devnull assuming a working knowledge of
13 37052ddc 2006-03-19 devnull .SS Name lengths
15 37052ddc 2006-03-19 devnull Request, macro, string, and number names can be longer
16 37052ddc 2006-03-19 devnull than two letters, as in:
19 37052ddc 2006-03-19 devnull \&.html c <center>
20 37052ddc 2006-03-19 devnull \&.de footnote
21 37052ddc 2006-03-19 devnull Footnote here.
23 37052ddc 2006-03-19 devnull \&.footnote
24 37052ddc 2006-03-19 devnull \&.ds string "hello
25 37052ddc 2006-03-19 devnull \&\e*[string]
26 37052ddc 2006-03-19 devnull \&.nr number 1
27 37052ddc 2006-03-19 devnull \&\en[number]
29 37052ddc 2006-03-19 devnull .SS HTML output
31 37052ddc 2006-03-19 devnull Two new requests:
34 37052ddc 2006-03-19 devnull \&.html \fIid\fP \fR[ \fI<html>\fP ]\fL
35 37052ddc 2006-03-19 devnull \&.ihtml \fIid\fP \fR[ \fI<ihtml>\fP ]\fL
40 37052ddc 2006-03-19 devnull .B .ihtml
41 37052ddc 2006-03-19 devnull insert HTML into the output.
42 37052ddc 2006-03-19 devnull The requests are only for opening new HTML tags.
43 37052ddc 2006-03-19 devnull To close previously-opened tags, repeat the request
44 37052ddc 2006-03-19 devnull with the same
46 37052ddc 2006-03-19 devnull For example, the input:
49 37052ddc 2006-03-19 devnull \&.html t <table><tr>
50 37052ddc 2006-03-19 devnull \&.html td <td>Cell 1
51 37052ddc 2006-03-19 devnull \&.html td <td>Cell 2
52 37052ddc 2006-03-19 devnull \&.html td
53 37052ddc 2006-03-19 devnull \&.html t
56 37052ddc 2006-03-19 devnull produces this output:
59 37052ddc 2006-03-19 devnull <table><tr><td>Cell 1</td><td>Cell 2</td></tr></table>
64 37052ddc 2006-03-19 devnull request is intended for block-level HTML constructs (those that can contain
65 37052ddc 2006-03-19 devnull .BR <p> )
66 37052ddc 2006-03-19 devnull and maintains the HTML tag stack automatically.
67 37052ddc 2006-03-19 devnull Intermediate tags need not be explicitly closed:
68 37052ddc 2006-03-19 devnull removing the final
69 37052ddc 2006-03-19 devnull .B \&.html t
70 37052ddc 2006-03-19 devnull line in the example above would produce the same output.
71 37052ddc 2006-03-19 devnull The special
74 37052ddc 2006-03-19 devnull closes the HTML tags immediately after printing them.
77 37052ddc 2006-03-19 devnull .B .ihtml
78 37052ddc 2006-03-19 devnull request is similar to
80 37052ddc 2006-03-19 devnull but is intended for inline HTML constructs such as
84 37052ddc 2006-03-19 devnull (those that can be contained
86 37052ddc 2006-03-19 devnull .BR <p> ).
88 37052ddc 2006-03-19 devnull .BR .html ,
89 37052ddc 2006-03-19 devnull .B .ihtml
90 37052ddc 2006-03-19 devnull treats the open HTML tags as a set rather than a stack:
91 37052ddc 2006-03-19 devnull each must be explicitly closed.
92 37052ddc 2006-03-19 devnull Although it treats the tags as a set,
93 37052ddc 2006-03-19 devnull .B .ihtml
94 37052ddc 2006-03-19 devnull treats nesting properly in the output,
95 37052ddc 2006-03-19 devnull closing and reopening tags as necessary.
96 37052ddc 2006-03-19 devnull For example, the input:
99 37052ddc 2006-03-19 devnull \&.ihtml style <b>
100 37052ddc 2006-03-19 devnull \&.ihtml link <a href="link.html">
102 37052ddc 2006-03-19 devnull \&.ihtml style <i>
103 37052ddc 2006-03-19 devnull and italic, still linked.
104 37052ddc 2006-03-19 devnull \&.ihtml link <a>
105 37052ddc 2006-03-19 devnull Unlinked.
106 37052ddc 2006-03-19 devnull \&.ihtml style
109 37052ddc 2006-03-19 devnull produces this output:
112 37052ddc 2006-03-19 devnull <b><a href="link.html">Bold</a></b>
113 37052ddc 2006-03-19 devnull <i><a href="link.html">and italic, still linked.</i></a>
114 37052ddc 2006-03-19 devnull <i>Unlinked.</i>
117 37052ddc 2006-03-19 devnull Outside of
118 37052ddc 2006-03-19 devnull .B .html
120 37052ddc 2006-03-19 devnull .B .ihtml
121 37052ddc 2006-03-19 devnull requests, the characters
126 37052ddc 2006-03-19 devnull are treated as normal characters, not HTML markers,
127 37052ddc 2006-03-19 devnull and are translated to
128 37052ddc 2006-03-19 devnull .L < ,
129 37052ddc 2006-03-19 devnull .L > ,
131 37052ddc 2006-03-19 devnull .L &
132 37052ddc 2006-03-19 devnull on output.
133 37052ddc 2006-03-19 devnull To embed the raw HTML markers, use
134 37052ddc 2006-03-19 devnull .L \e< ,
135 37052ddc 2006-03-19 devnull .L \e> ,
138 37052ddc 2006-03-19 devnull .RI [ sic ].
139 37052ddc 2006-03-19 devnull .SS Font changes
141 37052ddc 2006-03-19 devnull .I Htmlroff
142 37052ddc 2006-03-19 devnull interprets the usual
143 37052ddc 2006-03-19 devnull .BR \ef ,
144 37052ddc 2006-03-19 devnull .BR .ft ,
145 37052ddc 2006-03-19 devnull .BR \es ,
148 37052ddc 2006-03-19 devnull requests to change the font and point size.
149 37052ddc 2006-03-19 devnull After applying each such change to its internal registers,
150 37052ddc 2006-03-19 devnull .I htmlroff
151 37052ddc 2006-03-19 devnull invokes the
152 37052ddc 2006-03-19 devnull .B .font
153 37052ddc 2006-03-19 devnull macro to emit corresponding HTML.
154 37052ddc 2006-03-19 devnull The default definition of
155 37052ddc 2006-03-19 devnull .B .font
159 37052ddc 2006-03-19 devnull \&.de font
160 37052ddc 2006-03-19 devnull \&.ihtml f1
161 37052ddc 2006-03-19 devnull \&.ihtml f
162 37052ddc 2006-03-19 devnull \&.ihtml f <span style=\"font-size=\\n(.spt\">
163 37052ddc 2006-03-19 devnull \&.if \\n(.f==2 .ihtml f1 <i>
164 37052ddc 2006-03-19 devnull \&.if \\n(.f==3 .ihtml f1 <b>
165 37052ddc 2006-03-19 devnull \&.if \\n(.f==4 .ihtml f1 <b><i>
166 37052ddc 2006-03-19 devnull \&.if \\n(.f==5 .ihtml f1 <tt>
167 37052ddc 2006-03-19 devnull \&.if \\n(.f==6 .ihtml f1 <tt><i>
171 37052ddc 2006-03-19 devnull Input files can redefine
172 37052ddc 2006-03-19 devnull .B .font
173 37052ddc 2006-03-19 devnull like any other request or macro.
174 37052ddc 2006-03-19 devnull .SS Paragraphs
175 37052ddc 2006-03-19 devnull .I Htmlroff
176 37052ddc 2006-03-19 devnull implements line height, text adjustment, and margins by
177 37052ddc 2006-03-19 devnull wrapping all output text in
178 37052ddc 2006-03-19 devnull .B <p style="...">
180 37052ddc 2006-03-19 devnull This behavior can be disabled by setting the
181 37052ddc 2006-03-19 devnull .B .paragraph
182 37052ddc 2006-03-19 devnull number register to zero.
183 37052ddc 2006-03-19 devnull Setting the
184 37052ddc 2006-03-19 devnull .B .margin
185 37052ddc 2006-03-19 devnull register to zero
186 37052ddc 2006-03-19 devnull eliminates only the margin annotations.
187 37052ddc 2006-03-19 devnull .SS Subscripts and superscripts
189 37052ddc 2006-03-19 devnull .I Htmlroff
190 37052ddc 2006-03-19 devnull interprets the
191 37052ddc 2006-03-19 devnull .BR \eu ,
192 37052ddc 2006-03-19 devnull .BR \ed ,
195 37052ddc 2006-03-19 devnull requests to move vertically during output.
196 37052ddc 2006-03-19 devnull It emits output vertically offset up the page inside
197 37052ddc 2006-03-19 devnull .B <sup>
198 37052ddc 2006-03-19 devnull tags and output vertically offset down the page
200 37052ddc 2006-03-19 devnull .B <sub>
202 37052ddc 2006-03-19 devnull This heuristic handles simple equations formatted by
203 d32deab1 2020-08-16 rsc .MR eqn (1) .
204 37052ddc 2006-03-19 devnull .SS Conditional input
206 37052ddc 2006-03-19 devnull To make it easier to write input files that can be formatted by both
207 37052ddc 2006-03-19 devnull .I troff
209 37052ddc 2006-03-19 devnull .IR htmlroff ,
210 37052ddc 2006-03-19 devnull .I htmlroff
211 37052ddc 2006-03-19 devnull adds a new condition
213 37052ddc 2006-03-19 devnull which evaluates true in
217 37052ddc 2006-03-19 devnull requests.
220 37052ddc 2006-03-19 devnull condition continues to evaluate true, to accomodate
221 37052ddc 2006-03-19 devnull input files trying to distinguish between
222 37052ddc 2006-03-19 devnull .I troff
224 37052ddc 2006-03-19 devnull .IR nroff .
225 37052ddc 2006-03-19 devnull To write a conditional matching
226 37052ddc 2006-03-19 devnull .I troff
227 37052ddc 2006-03-19 devnull alone, use
228 37052ddc 2006-03-19 devnull .RB ` ".if !h .if t" '.
230 37052ddc 2006-03-19 devnull .I Htmlroff 's
231 37052ddc 2006-03-19 devnull handling of conditional input does not match
232 37052ddc 2006-03-19 devnull .IR troff 's
233 37052ddc 2006-03-19 devnull exactly.
234 37052ddc 2006-03-19 devnull For example,
237 37052ddc 2006-03-19 devnull \&.if 0 \e{\e
238 37052ddc 2006-03-19 devnull \&.de xx
243 37052ddc 2006-03-19 devnull redefines the
245 37052ddc 2006-03-19 devnull macro in
246 37052ddc 2006-03-19 devnull .I troff
247 37052ddc 2006-03-19 devnull but not in
248 37052ddc 2006-03-19 devnull .IR htmlroff .
249 37052ddc 2006-03-19 devnull Do not write files depending on this behavior, as this bug may be fixed
250 37052ddc 2006-03-19 devnull in the future.
251 37052ddc 2006-03-19 devnull .I Htmlroff
252 37052ddc 2006-03-19 devnull also mishandles
254 37052ddc 2006-03-19 devnull in some cases. To work around them, use
256 37052ddc 2006-03-19 devnull on a line by itself, as in the last example.
257 37052ddc 2006-03-19 devnull .SS Diversions
259 37052ddc 2006-03-19 devnull Diversions in
260 37052ddc 2006-03-19 devnull .I htmlroff
261 37052ddc 2006-03-19 devnull use the alignment in effect at the time of the
262 37052ddc 2006-03-19 devnull diversion
263 37052ddc 2006-03-19 devnull when output.
264 37052ddc 2006-03-19 devnull In particular,
267 37052ddc 2006-03-19 devnull \&.di xx
268 37052ddc 2006-03-19 devnull Line here.
275 37052ddc 2006-03-19 devnull produces a centered line in
276 37052ddc 2006-03-19 devnull .I troff
277 37052ddc 2006-03-19 devnull but not in
278 37052ddc 2006-03-19 devnull .IR htmlroff .
279 37052ddc 2006-03-19 devnull The solution is to center inside the diversion, as in
282 37052ddc 2006-03-19 devnull \&.di xx
283 37052ddc 2006-03-19 devnull \&.if h .ce 999
284 37052ddc 2006-03-19 devnull Line here
287 37052ddc 2006-03-19 devnull .SS Input pipes
289 37052ddc 2006-03-19 devnull .I Htmlroff
290 37052ddc 2006-03-19 devnull adds a new request
291 37052ddc 2006-03-19 devnull .B .inputpipe
294 37052ddc 2006-03-19 devnull that redirects
295 37052ddc 2006-03-19 devnull .I htmlroff 's
296 37052ddc 2006-03-19 devnull input into a pipe to the
298 37052ddc 2006-03-19 devnull .I cmd .
299 37052ddc 2006-03-19 devnull The redirection stops on encountering the line
300 37052ddc 2006-03-19 devnull .IR stop ,
301 37052ddc 2006-03-19 devnull optionally followed by white space and extra text.
302 37052ddc 2006-03-19 devnull This is a dangerous and clusmy request, as
303 37052ddc 2006-03-19 devnull .I htmlroff
304 37052ddc 2006-03-19 devnull stops interpreting its input during the redirection, so
306 37052ddc 2006-03-19 devnull must be found in the input itself, not in a macro that
307 37052ddc 2006-03-19 devnull the input might appear to call.
308 37052ddc 2006-03-19 devnull Although clusmy,
309 37052ddc 2006-03-19 devnull .B .inputpipe
310 37052ddc 2006-03-19 devnull allows input files to invoke
311 37052ddc 2006-03-19 devnull .I troff
312 37052ddc 2006-03-19 devnull to handle complicated input.
313 37052ddc 2006-03-19 devnull For example,
314 37052ddc 2006-03-19 devnull .B tmac.html
315 37052ddc 2006-03-19 devnull redefines the
317 37052ddc 2006-03-19 devnull macro that marks the beginning of a
319 37052ddc 2006-03-19 devnull picture:
322 37052ddc 2006-03-19 devnull \&.nr png -1 1
323 37052ddc 2006-03-19 devnull \&.de PS
324 37052ddc 2006-03-19 devnull \&.ds pngbase "\e\e*[basename]
325 37052ddc 2006-03-19 devnull \&.if '\e\e*[pngbase]'' .ds pngbase \e\en(.B
326 37052ddc 2006-03-19 devnull \&.ds pngfile \e\e*[pngbase]\e\en+[png].png
327 37052ddc 2006-03-19 devnull \&.html - <center><img src="\e\e*[pngfile]"></center>
328 37052ddc 2006-03-19 devnull \&.inputpipe .PE troff2png >\e\e*[pngfile]
332 37052ddc 2006-03-19 devnull This macro invokes the shell script
333 37052ddc 2006-03-19 devnull .I troff2png
334 37052ddc 2006-03-19 devnull to run troff and convert the Postscript
335 37052ddc 2006-03-19 devnull output to a PNG image file.
336 37052ddc 2006-03-19 devnull Before starting the program, the macro creates
337 37052ddc 2006-03-19 devnull a new file name for the image and prints
338 37052ddc 2006-03-19 devnull HTML referring to it.
341 37052ddc 2006-03-19 devnull register holds the final path element
342 37052ddc 2006-03-19 devnull (the base name) of the current input file.
