Subversion Repositories planix.SVN

Rev

Rev 2 | Details | Compare with Previous | Last modification | View Log | RSS feed

Rev Author Line No. Line
2 - 1 
.TH HTMLROFF 6
2 
.SH NAME
3 
htmlroff \- HTML formatting and typesetting
4 
.SH DESCRIPTION
5 
.IR 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 
.LR < ,
123 
.LR > ,
124 
and
125 
.L &
126 
are treated as normal characters, not HTML markers,
127 
and are translated to
128 
.LR &lt; ,
129 
.LR &gt; ,
130 
and
131 
.L &amp;
132 
on output.
133 
To embed the raw HTML markers, use
134 
.LR \e< ,
135 
.LR \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 
.IR 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 Traps
288 
.I Htmlroff
289 
implements traps at vertical position 0,
290 
which run when the first character is about
291 
to be printed.
292 
Other position traps are ignored.
293 
Input traps are implemented.
294 
.SS Input pipes
295 
.PP
296 
.I Htmlroff
297 
adds a new request
298 
.B .inputpipe
299 
.I stop
300 
.I cmd
301 
that redirects
302 
.IR htmlroff 's
303 
input into a pipe to
304 
.IR cmd .
305 
The redirection stops on encountering the line
306 
.IR stop ,
307 
optionally followed by white space and extra text.
308 
This is a dangerous and clumsy request, as
309 
.I htmlroff
310 
stops interpreting its input during the redirection, so
311 
.I stop
312 
must be found in the input itself, not in a macro that
313 
the input might appear to call.
314 
Although clumsy,
315 
.B .inputpipe
316 
allows input files to invoke
317 
.I troff
318 
to handle complicated input.
319 
For example,
320 
.B tmac.html
321 
redefines the
322 
.B PS
323 
macro that marks the beginning of a
324 
.IR pic (1)
325 
picture:
326 
.IP
327 
.EX
328 
\&.nr png -1 1
329 
\&.de PS
330 
\&.ds pngbase "\e\e*[basename]
331 
\&.if '\e\e*[pngbase]'' .ds pngbase \e\en(.B
332 
\&.ds pngfile \e\e*[pngbase]\e\en+[png].png
333 
\&.html - <center><img src="\e\e*[pngfile]"></center>
334 
\&.inputpipe .PE troff2png >\e\e*[pngfile]
335 
\&..
336 
.EE
337 
.LP
338 
This macro invokes the shell script
339 
.I troff2png
340 
to run troff and convert the Postscript
341 
output to a PNG image file.
342 
Before starting the program, the macro creates
343 
a new file name for the image and prints
344 
HTML referring to it.
345 
The
346 
.B .B
347 
register holds the final path element
348 
(the base name) of the current input file.
349 
.SS Unimplemented
350 
Tabs are set every eight spaces and cannot be changed.
351 
.PP
352 
Some requests, such as
353 
.BR .tl ,
354 
are unimplemented for lack of a good implementation.
355 
Workarounds can be defined as necessary in input files.
356 
.SH SEE ALSO
357 
.IR htmlroff (1),
358 
.IR mhtml (6)