313 lines
9.6 KiB
HTML
313 lines
9.6 KiB
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 <hr> 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 <h2> 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 <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.<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 <a> 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, <tt> </tt> <tt> </tt>March 21, 1996.
|
|
</body>
|
|
</html>
|