sys/man/6/htmlroff

   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)