by Jim Briggs
at Department of Computer Science, University of York
Troff2html is a translator for converting troff documents written using the ms macros (or extensions thereof) into HTML, for display on the World Wide Web.
It works by using nroff to produce a textual form of the normally typeset output of troff that includes HTML elements necessary to the format. Since it uses nroff, it is possible for the user to extend the set of macros that are implemented and to use pre-processors such as tbl and refer.
The following macros are implemented by troff2html:
.TL .AU .AI .AB .AE
.TL denotes the title of the HTML document. The text following it is also used as a <H1> heading at the start of the document.
.LP .PP .IE .IP .QP
.IP and .QP are implemented by the HTML <DL> construct. The others map on to the HTML <P> construct.
.B .I .BI .R
.B and .I should produce the desired effect, using HTML's <B> and <I> elements. .BI maps on to <STRONG> and therefore (depending on the browser) may appear the same as .B. The implementation of .R attempts to restore the normal font but may fail in cases of complicated nesting of these calls.
.UL .SM .LG
.UL maps onto <U>. .SM and .LG have no discernible effect in HTML - their argument will appear in normal style.
.SH .NH
.SH maps on to HTML's <H3> heading. .NH n maps on to <Hn+1> since <H1> is used for titles. Section numbering for .NH is done by the troff2html macros.
.RS .RE
Nesting is achieved by means of the <DL> construct which appears nested on most browsers.
.QS .QE
This feature is implemented using HTML's <BLOCKQUOTE>.
.TS .TE .EQ .EN .PS .PE .DS .DE
These are all implemented using the HTML <PRE> construct, therefore the nroff output is displayed without any further formatting. The argument to .DS that indicates the desired indentation is ignored by troff2html but will be interpreted by nroff. Remember to use neqn rather than eqn as your equation pre-processor.
.B1 .B2 .BX
A horizontal rule (<HR>) precedes and follows the text enclosed by .B1 and .B2, but the box has no sides. The argument to .BX is enclosed between [ and ].
.FS .FE
The text of footnotes is included inline between [ and ] brackets.
.UX .US
These macros produce the traditional words in the current text style.
.[ .]
These map on to their text equivalent.
.PM .PZ .BM
These are implemented by linking to the named file. Whether this is effective or not depends on whether the browser can interpret the contents of that file.
.RT
This must be called in the same way that it is used in -ms by any paragraph macro that the user defines, and also by the end macro .EM.
troff2html supports three additional macros for defining locations and linking to other documents and images:
.UD target_location_name
Defines a name for the current target location. If using it to define a name for a section of a document, put .UL before the section heading macro.
.UR URL text
The .UR macro is used to specify links from your document to other documents (or target locations within the current document). The first argument is the URL; the second argument is the text that will appear highlighted in your document.
.UI URL [alignment]
The .UI macro is used to specify image files for inclusion in a document. The first argument is the URL of the file; the second (optional) argument specifies the alignment of the image.
troff2html does not support the following features of the -ms macros:
troff2html takes a document in troff input format (either on the standard input or in files named as arguments) and produces HTML format text on the standard output.