unroff-html-ms - back-end to translate `ms' documents to HTML 2.0
file | option...
When called with the
options, the troff translator
loads the back-end for converting ``ms'' documents to the Hypertext
Markup Language (HTML) version 2.0.
first for an overview of the Scheme-based, programmable troff translator
and for a description of the generic options that exist in
The translation of basic troff requests, special characters,
escape sequences, etc. as well as the HTML-specific options
are described in
For information about extending and programming
also refer to the
Unroff Programmer's Manual.
extension provides a number of keyword/value options in addition to
those listed in
- signature (string)
If non-empty, the value of this option together with a <hr> tag is
appended to each HTML output file created.
Scheme primitive (as described in the Programmer's Manual) is
applied to the value of the option, so that date, time, environment
variables, etc. can be interpolated.
- split (integer)
This option specifies whether to split the output document into
individual files for each major section.
If a positive integer
is assigned to the option, a new output file is opened for each
request) with a level equal to or numerically less than
Use of this feature requires that the
option has bee set, as otherwise the HTML document is sent
to standard output.
The default value is 0, i.e. all sections will be written to
a single file.
- toc (boolean)
If true, a table of contents with a hypertext link for each section
is generated automatically and inserted after the front matter
(title, author information, abstract) and before the first section.
Use of this feature requires a non-zero value for the
The default is to produce a table of contents if
- toc-header (string)
This option defines the contents of the <h2> header element prepended to
an automatically generated table of contents.
Its value is subject to a call to
The default is the string ``Table of Contents''.
- pp-indent (integer)
The number of non-breakable spaces (as specified by the predefined
to generate for a paragraph created by the
The default is 3.
This option, as well as
is typically set in the user-preferences file
or in a document-specific Scheme file or at the beginning of
the document proper.
- footnotes-header (string)
The contents of the <h2> header element prepended to the footnotes
section that is appended to the document if any footnotes were used,
and that also appears in the automatically generated table of contents.
As with all string option listed in this section, the
primitive is applied to the option's value.
The default is the string ``Footnotes''.
- footnote-reference (string)
This option controls the text generated by each use of the variable
`\**', which produces a footnote (hypertext) reference.
Its value is passed to a call to
with the current footnote number as another argument, so that the
specifier ``%1%'' can be used to interpolate the footnote
The default is the string ``[note %1%]''.
- footnote-anchor (string)
This options specifies the footnote reference that appears at the
beginning of each footnote proper if
was called without an argument.
The option's value is passed to a call to
with the footnote number generated by the last use of `\**' as
The default is ``[%1%]''.
reads and parses an ''ms`` document composed of one ore more
As usual, the special file name
can be used to interpolate standard input.
If no file name is given in the command line,
reads from standard input.
The resulting HTML document is sent to standard output, unless a
file name prefix is assigned to the
In the latter case, the
option controls splitting of the output into separate files at
section boundaries as described under OPTIONS above.
A number of other features, such as footnotes, also require
option is supplied, as separate output files are created for them
(regardless of the value of
In any case, the name of each output file consists of the value of
followed by an optional suffix, followed by the extension ``.html''.
To translate an ``ms'' document composed of several
could be invoked like this:
The names of all output files will have the prefix ``thesis'',
and the resulting HTML document will be split into separate files
at each level 1 section or level 2 section.
unroff -fhtml -ms document=thesis split=2 intro.ms 1.ms 2.ms 3.ms app.ms
macros are translated (in addition to any user-defined macros):
.AB .AE .AI .AU .B .B1 .B2
.BD .BX .CD .DE .DS .FA .FE
.FS .I .ID .IP .LD .LG .LP
.NH .PP .PX .QP .R .RE .RS
.RT .SH .SM .TL .UL .UX .XA
These predefined strings and number registers are recognized:
\*- \*(DY \*(MO \*Q \*U \n(PN
In addition, a number of macros are either silently ignored
or cause a warning to be printed, because their function either
cannot be mapped to HTML 2.0 elements or assumes a page
.AM .BT .CM .CT .DA .EF .EH
.HD .KE .KF .KS .ND .NL .OF
.OH .P1 .PT .TM .MC .1C .2C
The font switching macros are based on changes to the fonts `R',
`I', and `B', as explained under FONTS in
Of course, this fails if the fonts (which are mounted on startup)
are unmounted by explicit
Upper or lower case letters are accepted as section numbers by
when the argument ``S'' is used to set new section numbers.
This is useful for appendices and similar constructs.
The translation rule for
employs a heuristic to determine whether to generate a definition
list or an unordered list:
if the first in a sequence of indented paragraph macros is
called with a tag consisting of one of the special character \(bu
or \(sq, a definition list is begun, otherwise an unordered list.
paragraphs cannot be expressed in HTML 2.0, a warning
message is printed when a call to the macro
All footnotes are concatenated and placed in a separate output file,
and a corresponding section (with a user-defined header) holding
the footnotes is appended to the document automatically.
Use of the string `\**' generates a hypertext link to the beginning
of the footnote created by the next call to
The actual text generated by using `\**' as well as the footnote
reference that appears in the footnote proper are controlled by
two options as explained under OPTIONS above.
A warning message is printed on termination if `\**' has been
used but a corresponding footnote was not seen.
As an alternative to `\**', the new request
can be used to produce a footnote anchor together with a hypertext
link; the anchor is the argument to the macro
(however, `\**' itself must not be used in a call to
Likewise, a hypertext reference is created for each use of the
table of contents macros
(optionally accompanied by calls to
ms(5 or 7).
Unroff Programmer's Manual.
Berners-Lee, Connolly, et al.,
HyperText Markup Language Specification--2.0,
Internet Draft, Internet Engineering Task Force.
is currently mapped to a call to
as underlining is not supported by the HTML back-end of
Footnote references and requests such as
that cause non-character-level markup to be generated must not
be used inside a numbered header.
When creating a hypertext anchor for
there is nothing to put inside the <a> element;
therefore a non-breaking space is used.
Changing the number register format of `NH' to get roman or alphabetic
section numbers does not work, obviously.
Markup created by unroff 1.0, March 21, 1996.