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