325 lines
8.9 KiB
Groff
325 lines
8.9 KiB
Groff
.\" $Revision: 1.8 $
|
|
.ds Ve 1.0
|
|
.\"
|
|
.de Ex
|
|
.RS
|
|
.nf
|
|
.nr sf \\n(.f
|
|
.if !\\n(.U \{\
|
|
. ft B
|
|
. if n .sp
|
|
. if t .sp .5 \}
|
|
..
|
|
.de Ee
|
|
.if !\\n(.U \{\
|
|
. ft \\n(sf
|
|
. if n .sp
|
|
. if t .sp .5 \}
|
|
.fi
|
|
.RE
|
|
..
|
|
.\"
|
|
.de Sd
|
|
.ds Dt \\$2
|
|
..
|
|
.\"
|
|
.Sd $Date: 1995/08/23 12:07:31 $
|
|
.TH unroff-html-ms 1 "\*(Dt"
|
|
.SH NAME
|
|
unroff-html-ms \- back-end to translate `ms' documents to HTML 2.0
|
|
.SH SYNOPSIS
|
|
.B unroff
|
|
[
|
|
.B \-fhtml
|
|
] [
|
|
.B \-ms
|
|
] [
|
|
.IR file " | " option...\&
|
|
]
|
|
.SH OVERVIEW
|
|
When called with the
|
|
.B \-fhtml
|
|
and
|
|
.B \-ms
|
|
options, the troff translator
|
|
.I unroff
|
|
loads the back-end for converting \*(lqms\*(rq documents to the Hypertext
|
|
Markup Language (HTML) version 2.0.
|
|
.LP
|
|
Please read
|
|
.BR unroff (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
|
|
and
|
|
.BR \-m .
|
|
The translation of basic troff requests, special characters,
|
|
escape sequences, etc. as well as the HTML-specific options
|
|
are described in
|
|
.BR unroff-html (1).
|
|
For information about extending and programming
|
|
.I unroff
|
|
also refer to the
|
|
.IR "Unroff Programmer's Manual" .
|
|
.SH OPTIONS
|
|
The
|
|
.B \-ms
|
|
extension provides a number of keyword/value options in addition to
|
|
those listed in
|
|
.BR unroff (1)
|
|
and
|
|
.BR unroff-html (1):
|
|
.TP
|
|
.BR signature " (string)"
|
|
If non-empty, the value of this option together with a <hr> tag is
|
|
appended to each HTML output file created.
|
|
The
|
|
.I substitute
|
|
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.
|
|
.TP
|
|
.BR split " (integer)"
|
|
This option specifies whether to split the output document into
|
|
individual files for each major section.
|
|
If a positive integer
|
|
.I level
|
|
is assigned to the option, a new output file is opened for each
|
|
numbered header
|
|
.RB ( .NH
|
|
request) with a level equal to or numerically less than
|
|
.IR level .
|
|
Use of this feature requires that the
|
|
.B document
|
|
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.
|
|
.TP
|
|
.BR 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
|
|
.B split
|
|
option.
|
|
The default is to produce a table of contents if
|
|
.B split
|
|
is non-zero.
|
|
.TP
|
|
.BR 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
|
|
.IR substitute .
|
|
The default is the string \*(lqTable of Contents\*(rq.
|
|
.TP
|
|
.BR pp-indent " (integer)"
|
|
The number of non-breakable spaces (as specified by the predefined
|
|
Scheme variable
|
|
.IR nbsp )
|
|
to generate for a paragraph created by the
|
|
.B .PP
|
|
macro.
|
|
The default is 3.
|
|
This option, as well as
|
|
.BR signature ,
|
|
is typically set in the user-preferences file
|
|
.BR ~/.unroff ,
|
|
or in a document-specific Scheme file or at the beginning of
|
|
the document proper.
|
|
.TP
|
|
.BR 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
|
|
.I substitute
|
|
primitive is applied to the option's value.
|
|
The default is the string \*(lqFootnotes\*(rq.
|
|
.TP
|
|
.BR footnote-reference " (string)"
|
|
This option controls the text generated by each use of the variable
|
|
\&`\e**', which produces a footnote (hypertext) reference.
|
|
Its value is passed to a call to
|
|
.I substitute
|
|
with the current footnote number as another argument, so that the
|
|
specifier \*(lq%1%\*(rq can be used to interpolate the footnote
|
|
number.
|
|
The default is the string \*(lq[note %1%]\*(rq.
|
|
.TP
|
|
.BR footnote-anchor " (string)"
|
|
This options specifies the footnote reference that appears at the
|
|
beginning of each footnote proper if
|
|
.B .FS
|
|
was called without an argument.
|
|
The option's value is passed to a call to
|
|
.I substitute
|
|
with the footnote number generated by the last use of `\e**' as
|
|
another argument.
|
|
The default is \*(lq[%1%]\*(rq.
|
|
.SH FILES
|
|
.I unroff
|
|
reads and parses an \*(rqms\*(lq document composed of one ore more
|
|
input files.
|
|
As usual, the special file name
|
|
.RB ` \- '
|
|
can be used to interpolate standard input.
|
|
If no file name is given in the command line,
|
|
.I unroff
|
|
reads from standard input.
|
|
.LP
|
|
The resulting HTML document is sent to standard output, unless a
|
|
file name prefix is assigned to the
|
|
.B document
|
|
option.
|
|
In the latter case, the
|
|
.B split
|
|
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
|
|
that the
|
|
.B document
|
|
option is supplied, as separate output files are created for them
|
|
(regardless of the value of
|
|
.BR split ).
|
|
In any case, the name of each output file consists of the value of
|
|
.BR document ,
|
|
followed by an optional suffix, followed by the extension \*(lq.html\*(rq.
|
|
.SH EXAMPLE
|
|
To translate an \*(lqms\*(rq document composed of several
|
|
input files,
|
|
.I unroff
|
|
could be invoked like this:
|
|
.Ex
|
|
.if n \{unroff \-fhtml \-ms document=thesis split=2\e
|
|
intro.ms 1.ms 2.ms 3.ms app.ms\}
|
|
.if !n unroff \-fhtml \-ms document=thesis split=2 intro.ms 1.ms 2.ms 3.ms app.ms
|
|
.Ee
|
|
The names of all output files will have the prefix \*(lqthesis\*(rq,
|
|
and the resulting HTML document will be split into separate files
|
|
at each level 1 section or level 2 section.
|
|
.SH DESCRIPTION
|
|
The following
|
|
.B \-ms
|
|
macros are translated (in addition to any user-defined macros):
|
|
.LP
|
|
.nf
|
|
.if !\n(.U .ta 8n 16n 24n 32n 40n 48n 56n
|
|
.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
|
|
.fi
|
|
.LP
|
|
These predefined strings and number registers are recognized:
|
|
.LP
|
|
.nf
|
|
\e*- \e*(DY \e*(MO \e*Q \e*U \en(PN
|
|
.fi
|
|
.LP
|
|
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:
|
|
.LP
|
|
.nf
|
|
.AM .BT .CM .CT .DA .EF .EH
|
|
.HD .KE .KF .KS .ND .NL .OF
|
|
.OH .P1 .PT .TM .MC .1C .2C
|
|
.fi
|
|
.LP
|
|
The font switching macros are based on changes to the fonts `R',
|
|
`I', and `B', as explained under FONTS in
|
|
.BR unroff-html (1).
|
|
Of course, this fails if the fonts (which are mounted on startup)
|
|
are unmounted by explicit
|
|
.B .fp
|
|
requests.
|
|
.LP
|
|
Upper or lower case letters are accepted as section numbers by
|
|
.B .NH
|
|
when the argument ``S'' is used to set new section numbers.
|
|
This is useful for appendices and similar constructs.
|
|
.LP
|
|
The translation rule for
|
|
.B .IP
|
|
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 \e(bu
|
|
or \e(sq, a definition list is begun, otherwise an unordered list.
|
|
Since
|
|
.RI exdented[ sic ]
|
|
paragraphs cannot be expressed in HTML 2.0, a warning
|
|
message is printed when a call to the macro
|
|
.B .XP
|
|
is encountered.
|
|
.LP
|
|
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 `\e**' generates a hypertext link to the beginning
|
|
of the footnote created by the next call to
|
|
.B .FS
|
|
and
|
|
.BR .FE .
|
|
The actual text generated by using `\e**' 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 `\e**' has been
|
|
used but a corresponding footnote was not seen.
|
|
As an alternative to `\e**', the new request
|
|
.B .FA
|
|
can be used to produce a footnote anchor together with a hypertext
|
|
link; the anchor is the argument to the macro
|
|
(however, `\e**' itself must not be used in a call to
|
|
.BR .FA ).
|
|
.LP
|
|
Likewise, a hypertext reference is created for each use of the
|
|
table of contents macros
|
|
.BR .XS
|
|
and
|
|
.BR .XE
|
|
(optionally accompanied by calls to
|
|
.BR .XA ).
|
|
.SH "SEE ALSO"
|
|
.BR unroff (1),
|
|
.BR unroff-html (1),
|
|
.BR troff (1),
|
|
.BR ms "(5 or 7)."
|
|
.LP
|
|
Unroff Programmer's Manual.
|
|
.LP
|
|
http://www.informatik.uni-bremen.de/~net/unroff
|
|
.LP
|
|
Berners-Lee, Connolly, et al.,
|
|
HyperText Markup Language Specification\(em2.0,
|
|
Internet Draft, Internet Engineering Task Force.
|
|
.SH BUGS
|
|
The macro
|
|
.B .UL
|
|
is currently mapped to a call to
|
|
.BR .I ,
|
|
as underlining is not supported by the HTML back-end of
|
|
.I unroff
|
|
\*(Ve.
|
|
.LP
|
|
Footnote references and requests such as
|
|
.B .sp
|
|
that cause non-character-level markup to be generated must not
|
|
be used inside a numbered header.
|
|
.LP
|
|
When creating a hypertext anchor for
|
|
.B .XS
|
|
and
|
|
.BR .XE ,
|
|
there is nothing to put inside the <a> element;
|
|
therefore a non-breaking space is used.
|
|
.LP
|
|
Changing the number register format of `NH' to get roman or alphabetic
|
|
section numbers does not work, obviously.
|