htmlroff 6.5 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358
  1. .TH HTMLROFF 6
  2. .SH NAME
  3. htmlroff \- HTML formatting and typesetting
  4. .SH DESCRIPTION
  5. .I 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. .EX
  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)