unroff/doc/unroff-html-ms.1

325 lines
8.9 KiB
Groff
Raw Normal View History

2023-02-13 08:45:50 -05:00
.\" $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.