Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
HTMLROFF(7)	       Miscellaneous Information Manual		   HTMLROFF(7)

       htmlroff	- HTML formatting and typesetting

       accepts troff input with	a few extensions and changes.  This manual de-
       scribes the changes to the input	language, assuming a working knowledge
       of troff	itself.

   Name	lengths
       Request,	 macro,	 string,  and number names can be longer than two let-
       ters, as	in:

	      .html c <center>
	      .de footnote
	      Footnote here.
	      .ds string "hello
	      .nr number 1

   HTML	output
       Two new requests:

	      .html id [ _html_	]
	      .ihtml id	[ _ihtml_ ]

       .html and .ihtml	insert HTML into the output.  The  requests  are  only
       for opening new HTML tags.  To close previously-opened tags, repeat the
       request with the	same id.  For example, the input:

	      .html t <table><tr>
	      .html td <td>Cell	1
	      .html td <td>Cell	2
	      .html td
	      .html t

       produces	this output:

	      <table><tr><td>Cell 1</td><td>Cell 2</td></tr></table>

       The .html request is intended for block-level  HTML  constructs	(those
       that  can  contain <p>) and maintains the HTML tag stack	automatically.
       Intermediate tags need not be explicitly	 closed:  removing  the	 final
       .html  t	 line in the example above would produce the same output.  The
       special id closes the HTML tags immediately after printing them.

       The .ihtml request is similar to	.html but is intended for inline  HTML
       constructs such as <b> or <i> (those that can be	contained within <p>).
       Unlike .html, .ihtml treats the open HTML tags as a set rather  than  a
       stack:  each must be explicitly closed.	Although it treats the tags as
       a set, .ihtml treats nesting properly in	the output,  closing  and  re-
       opening tags as necessary.  For example,	the input:

	      .ihtml style <b>
	      .ihtml link <a href="link.html">
	      .ihtml style <i>
	      and italic, still	linked.
	      .ihtml link <a>
	      .ihtml style

       produces	this output:

	      <b><a href="link.html">Bold</a></b>
	      <i><a href="link.html">and italic, still linked.</i></a>

       Outside of .html	and .ihtml requests, the characters and	are treated as
       normal characters, not HTML markers, and	are translated to and on  out-
       put.  To	embed the raw HTML markers, use	and [sic].

   Font	changes
       Htmlroff	 interprets  the usual \f, .ft,	\s, and	.ps requests to	change
       the font	and point size.	 After applying	each such change to its	inter-
       nal  registers,	htmlroff invokes the .font macro to emit corresponding
       HTML.  The default definition of	.font is:

	      .de font
	      .ihtml f1
	      .ihtml f
	      .ihtml f <span style=
	      .if \n(.f==2 .ihtml f1 <i>
	      .if \n(.f==3 .ihtml f1 <b>
	      .if \n(.f==4 .ihtml f1 <b><i>
	      .if \n(.f==5 .ihtml f1 <tt>
	      .if \n(.f==6 .ihtml f1 <tt><i>

       Input files can redefine	.font like any other request or	macro.

       Htmlroff	implements line	height,	text adjustment, and margins by	 wrap-
       ping  all  output  text	in <p style="..."> tags.  This behavior	can be
       disabled	by setting the .paragraph number register  to  zero.   Setting
       the .margin register to zero eliminates only the	margin annotations.

   Subscripts and superscripts
       Htmlroff	interprets the \u, \d, and \v requests to move vertically dur-
       ing output.  It emits output vertically offset up the page inside <sup>
       tags  and  output  vertically  offset  down the page inside <sub> tags.
       This heuristic handles simple equations formatted by

   Conditional input
       To make it easier to write input	files that can be  formatted  by  both
       troff  and  htmlroff,  htmlroff	adds a new condition h which evaluates
       true in .if and .ie requests.  The t condition  continues  to  evaluate
       true, to	accomodate input files trying to distinguish between troff and
       nroff.  To write	a conditional matching troff alone, use	 `.if  !h  .if

       Htmlroff	 's  handling  of conditional input does not match troff's ex-
       actly.  For example,

	      .if 0 \{\
	      .de xx

       redefines the xx	macro in troff but not	in  htmlroff.	Do  not	 write
       files  depending	 on this behavior, as this bug may be fixed in the fu-
       ture.  Htmlroff also mishandles \} in some cases.  To work around them,
       use .\} on a line by itself, as in the last example.

       Diversions  in  htmlroff	use the	alignment in effect at the time	of the
       diversion when output.  In particular,

	      .di xx
	      Line here.

       produces	a centered line	in troff but not in htmlroff.  The solution is
       to center inside	the diversion, as in

	      .di xx
	      .if h .ce	999
	      Line here

   Input pipes
       Htmlroff	adds a new request .inputpipe stop cmd that redirects htmlroff
       's input	into a pipe to the given cmd .	The redirection	stops  on  en-
       countering  the line stop, optionally followed by white space and extra
       text.  This is a	dangerous and clusmy request, as htmlroff stops	inter-
       preting	its input during the redirection, so stop must be found	in the
       input itself, not in a macro that the input might appear	to call.   Al-
       though  clusmy, .inputpipe allows input files to	invoke troff to	handle
       complicated input.  For example,	tmac.html redefines the	PS macro  that
       marks the beginning of a	picture:

	      .nr png -1 1
	      .de PS
	      .ds pngbase "\\*[basename]
	      .if '\\*[pngbase]'' .ds pngbase \\n(.B
	      .ds pngfile \\*[pngbase]\\n+[png].png
	      .html - <center><img src="\\*[pngfile]"></center>
	      .inputpipe .PE troff2png >\\*[pngfile]

       This  macro invokes the shell script troff2png to run troff and convert
       the Postscript output to	a PNG image file.  Before  starting  the  pro-
       gram,  the  macro creates a new file name for the image and prints HTML
       referring to it.	 The new .B register holds the final path element (the
       base name) of the current input file.



Want to link to this manual page? Use this URL:

home | help