man(1) Manual page archive


     HTMLROFF(7)                                           HTMLROFF(7)

     NAME
          htmlroff - HTML formatting and typesetting

     DESCRIPTION
          Htmlroff (1) accepts troff input with a few extensions and
          changes.  This manual describes 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 letters, as in:

               .html c <center>
               .de footnote
               Footnote here.
               ..
               .footnote
               .ds string "hello
               \*[string]
               .nr number 1
               \n[number]

        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 exam-
          ple, 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 con-
          structs (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.

     HTMLROFF(7)                                           HTMLROFF(7)

          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 explic-
          itly closed.  Although it treats the tags as a set, .ihtml
          treats nesting properly in the output, closing and reopening
          tags as necessary.  For example, the input:

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

          produces this output:

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

          Outside of .html and .ihtml requests, the characters `< ,'
          `> ,' and `&' are treated as normal characters, not HTML
          markers, and are translated to `&lt; ,' `&gt; ,' and `&amp;'
          on output.  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 internal 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.

        Paragraphs
          Htmlroff implements line height, text adjustment, and

     HTMLROFF(7)                                           HTMLROFF(7)

          margins by wrapping all output text in <p style="..."> tags.
          This behavior can be disabled by setting the .paragraph num-
          ber 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 ver-
          tically during 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 eqn(1).

        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 condi-
          tion 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 t'.

          Htmlroff 's handling of conditional input does not match
          troff's exactly.  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 future.  Htmlroff also mishandles \} in some
          cases.  To work around them, use .\} on a line by itself, as
          in the last example.

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

               .di xx
               Line here.
               .di
               .nf
               .ce
               .xx

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

     HTMLROFF(7)                                           HTMLROFF(7)

        Input pipes
          Htmlroff adds a new request .inputpipe stop cmd that redi-
          rects htmlroff 's input into a pipe to the given cmd . The
          redirection stops on encountering the line stop, optionally
          followed by white space and extra text.  This is a dangerous
          and clusmy request, as htmlroff stops interpreting 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.
          Although 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 pic(1)
          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 program, 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.