htmlroff.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.