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