unroff-website/www/doc/unroff-html-ms.1.html

<html>
<head>
<!-- This file has been generated by unroff 1.0, 03/21/96 19:29:27. -->
<!-- Do not edit! -->
<link rev="made" href="mailto:net@informatik.uni-bremen.de">
<!--  $Revision: 1.8 $ -->
<title>Manual page for unroff-html-ms(1)</title>
</head>
<body>
<h2>
unroff-html-ms - back-end to translate `ms' documents to HTML 2.0
<hr></h2>
<h2>SYNOPSIS</h2>
<b>unroff
</b>[
<b>-fhtml
</b>] [
<b>-ms
</b>] [
<i>file</i> | <i>option...
</i>]
<h2>OVERVIEW</h2>
When called with the
<b>-fhtml
</b>and
<b>-ms
</b>options, the troff translator
<i>unroff
</i>loads the back-end for converting ``ms'' documents to the Hypertext
Markup Language (HTML) version 2.0.<tt> </tt>
<p>
Please read
<b>unroff</b>(1)
first for an overview of the Scheme-based, programmable troff translator
and for a description of the generic options that exist in
addition to
<b>-f
</b>and
<b>-m</b>.<tt> </tt>
The translation of basic troff requests, special characters,
escape sequences, etc. as well as the HTML-specific options
are described in
<b>unroff-html</b>(1).<tt> </tt>
For information about extending and programming
<i>unroff
</i>also refer to the
<i>Unroff Programmer's Manual</i>.<tt> </tt>
<h2>OPTIONS</h2>
The
<b>-ms
</b>extension provides a number of keyword/value options in addition to
those listed in
<b>unroff</b>(1)
and
<b>unroff-html</b>(1):
<dl>
<dt><b>signature</b> (string)
<dd>
If non-empty, the value of this option together with a &lt;hr&gt; tag is
appended to each HTML output file created.<tt> </tt>
The
<i>substitute
</i>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.<tt> </tt>
<dt><b>split</b> (integer)
<dd>
This option specifies whether to split the output document into
individual files for each major section.<tt> </tt>
If a positive integer
<i>level
</i>is assigned to the option, a new output file is opened for each
numbered header
(<b>.NH
</b>request) with a level equal to or numerically less than
<i>level</i>.<tt> </tt>
Use of this feature requires that the
<b>document
</b>option has bee set, as otherwise the HTML document is sent
to standard output.<tt> </tt>
The default value is 0, i.e. all sections will be written to
a single file.<tt> </tt>
<dt><b>toc</b> (boolean)
<dd>
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.<tt> </tt>
Use of this feature requires a non-zero value for the
<b>split
</b>option.<tt> </tt>
The default is to produce a table of contents if
<b>split
</b>is non-zero.<tt> </tt>
<dt><b>toc-header</b> (string)
<dd>
This option defines the contents of the &lt;h2&gt; header element prepended to
an automatically generated table of contents.<tt> </tt>
Its value is subject to a call to
<i>substitute</i>.<tt> </tt>
The default is the string ``Table of Contents''.<tt> </tt>
<dt><b>pp-indent</b> (integer)
<dd>
The number of non-breakable spaces (as specified by the predefined
Scheme variable
<i>nbsp</i>)
to generate for a paragraph created by the
<b>.PP
</b>macro.<tt> </tt>
The default is 3.<tt> </tt>
This option, as well as
<b>signature</b>,
is typically set in the user-preferences file
<b>~/.unroff</b>,
or in a document-specific Scheme file or at the beginning of
the document proper.<tt> </tt>
<dt><b>footnotes-header</b> (string)
<dd>
The contents of the &lt;h2&gt; 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.<tt> </tt>
As with all string option listed in this section, the
<i>substitute
</i>primitive is applied to the option's value.<tt> </tt>
The default is the string ``Footnotes''.<tt> </tt>
<dt><b>footnote-reference</b> (string)
<dd>
This option controls the text generated by each use of the variable
`\**', which produces a footnote (hypertext) reference.<tt> </tt>
Its value is passed to a call to
<i>substitute
</i>with the current footnote number as another argument, so that the
specifier ``%1%'' can be used to interpolate the footnote
number.<tt> </tt>
The default is the string ``[note %1%]''.<tt> </tt>
<dt><b>footnote-anchor</b> (string)
<dd>
This options specifies the footnote reference that appears at the
beginning of each footnote proper if
<b>.FS
</b>was called without an argument.<tt> </tt>
The option's value is passed to a call to
<i>substitute
</i>with the footnote number generated by the last use of `\**' as
another argument.<tt> </tt>
The default is ``[%1%]''.<tt> </tt>
</dl>
<h2>FILES</h2>
<i>unroff
</i>reads and parses an ''ms`` document composed of one ore more
input files.<tt> </tt>
As usual, the special file name
`<b>-</b>'
can be used to interpolate standard input.<tt> </tt>
If no file name is given in the command line,
<i>unroff
</i>reads from standard input.<tt> </tt>
<p>
The resulting HTML document is sent to standard output, unless a
file name prefix is assigned to the
<b>document
</b>option.<tt> </tt>
In the latter case, the
<b>split
</b>option controls splitting of the output into separate files at
section boundaries as described under OPTIONS above.<tt> </tt>
A number of other features, such as footnotes, also require
that the
<b>document
</b>option is supplied, as separate output files are created for them
(regardless of the value of
<b>split</b>).<tt> </tt>
In any case, the name of each output file consists of the value of
<b>document</b>,
followed by an optional suffix, followed by the extension ``.html''.<tt> </tt>
<h2>EXAMPLE</h2>
To translate an ``ms'' document composed of several
input files,
<i>unroff
</i>could be invoked like this:
<dl><dt><dd>
<pre>
unroff -fhtml -ms document=thesis split=2 intro.ms 1.ms 2.ms 3.ms app.ms
</pre>
</dl>
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.<tt> </tt>
<h2>DESCRIPTION</h2>
The following 
<b>-ms
</b>macros are translated (in addition to any user-defined macros):
<p>
<pre>
	.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
	.XE	.XS
</pre>
<p>
These predefined strings and number registers are recognized:
<p>
<pre>
	\*-	\*(DY	\*(MO	\*Q	\*U	\n(PN
</pre>
<p>
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
structure:
<p>
<pre>
	.AM	.BT	.CM	.CT	.DA	.EF	.EH
	.HD	.KE	.KF	.KS	.ND	.NL	.OF
	.OH	.P1	.PT	.TM	.MC	.1C	.2C
</pre>
<p>
The font switching macros are based on changes to the fonts `R',
`I', and `B', as explained under FONTS in
<b>unroff-html</b>(1).<tt> </tt>
Of course, this fails if the fonts (which are mounted on startup)
are unmounted by explicit
<b>.fp
</b>requests.<tt> </tt>
<p>
Upper or lower case letters are accepted as section numbers by
<b>.NH
</b>when the argument ``S'' is used to set new section numbers.<tt> </tt>
This is useful for appendices and similar constructs.<tt> </tt>
<p>
The translation rule for
<b>.IP
</b>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.<tt> </tt>
Since
exdented[<i>sic</i>]
paragraphs cannot be expressed in HTML 2.0, a warning
message is printed when a call to the macro
<b>.XP
</b>is encountered.<tt> </tt>
<p>
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.<tt> </tt>
Use of the string `\**' generates a hypertext link to the beginning
of the footnote created by the next call to
<b>.FS
</b>and
<b>.FE</b>.<tt> </tt>
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.<tt> </tt>
A warning message is printed on termination if `\**' has been
used but a corresponding footnote was not seen.<tt> </tt>
As an alternative to `\**', the new request
<b>.FA
</b>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
<b>.FA</b>).<tt> </tt>
<p>
Likewise, a hypertext reference is created for each use of the
table of contents macros
<b>.XS
</b>and
<b>.XE
</b>(optionally accompanied by calls to
<b>.XA</b>).<tt> </tt>
<h2>SEE ALSO</h2>
<b>unroff</b>(1),
<b>unroff-html</b>(1),
<b>troff</b>(1),
<b>ms</b>(5 or 7).<tt> </tt>
<p>
Unroff Programmer's Manual.<tt> </tt>
<p>
http://www.informatik.uni-bremen.de/~net/unroff
<p>
Berners-Lee, Connolly, et al.,
HyperText Markup Language Specification--2.0,
Internet Draft, Internet Engineering Task Force.<tt> </tt>
<h2>BUGS</h2>
The macro
<b>.UL
</b>is currently mapped to a call to
<b>.I</b>,
as underlining is not supported by the HTML back-end of
<i>unroff
</i>1.0.<tt> </tt>
<p>
Footnote references and requests such as
<b>.sp
</b>that cause non-character-level markup to be generated must not
be used inside a numbered header.<tt> </tt>
<p>
When creating a hypertext anchor for
<b>.XS
</b>and
<b>.XE</b>,
there is nothing to put inside the &lt;a&gt; element;
therefore a non-breaking space is used.<tt> </tt>
<p>
Changing the number register format of `NH' to get roman or alphabetic
section numbers does not work, obviously.<tt> </tt>
<p><hr>
Markup created by <em>unroff</em> 1.0,&#160;<tt> </tt>&#160;<tt> </tt>March 21, 1996.
</body>
</html>