Extract unroff-1.0.tar.gz
This commit is contained in:
commit
d8bfced2b7
|
|
@ -0,0 +1,26 @@
|
|||
Copyright 1995 Oliver Laumann. All rights reserved.
|
||||
|
||||
Not derived from licensed software.
|
||||
|
||||
Permission is granted to use, copy, perform, display, modify, and
|
||||
redistribute this software (including derivative works based on it) in
|
||||
any form, subject to the following restrictions:
|
||||
|
||||
i) Source distributions must be accompanied by this entire copyright
|
||||
notice.
|
||||
ii) Binary distributions must include the acknowledgement ``This
|
||||
product includes software developed by Oliver Laumann'' in the
|
||||
documentation or other materials provided with the distribution.
|
||||
iii) The origin of this software must not be misrepresented, either
|
||||
by explicit claim or by omission.
|
||||
iv) Altered versions must be plainly marked as such in the source
|
||||
and documentation and must not be misrepresented as being the
|
||||
original software.
|
||||
v) The author is not deemed to have made any representations as to
|
||||
the suitability of this software for any purpose nor is held
|
||||
responsible for any defects of this software.
|
||||
THERE IS ABSOLUTELY NO WARRANTY FOR THIS SOFTWARE.
|
||||
|
||||
Berlin, March 23, 1995
|
||||
|
||||
Oliver Laumann <net@cs.tu-berlin.de> # $Revision: 1.2 $
|
||||
|
|
@ -0,0 +1,96 @@
|
|||
Installation Guide for the `unroff' Source Distribution
|
||||
-------------------------------------------------------
|
||||
|
||||
Requirements: you need Elk 2.2 or Elk 3.0 and an ANSI C compiler
|
||||
to install unroff from the source distribution. If you don't have
|
||||
Elk and don't want to install it, you may want to obtain the binary
|
||||
unroff distribution instead.
|
||||
|
||||
You can obtain Elk 3.0 in the World Wide Web at
|
||||
|
||||
http://www.informatik.uni-bremen.de/~net/elk
|
||||
|
||||
and from a number of FTP servers including these:
|
||||
|
||||
ftp://ftp.x.org/contrib/devel_tools/elk-3.0.tar.gz
|
||||
ftp://ftp.uni-bremen.de/pub/programming/languages/scheme/elk/elk-3.0.tar.gz
|
||||
|
||||
|
||||
|
||||
o If you are still using Elk 2.2, you may have to apply a small patch to
|
||||
your Elk installation. The patch is in the file src/elk-2.2-patch.
|
||||
Assuming you have unpacked unroff under /usr/local/src/unroff-1.0,
|
||||
change to the directory where the Elk "src" directory is located and call:
|
||||
|
||||
patch < /usr/local/src/unroff-1.0/src/elk-2.2-patch
|
||||
|
||||
If the patch program detects a `Reverse patch', the patch is not
|
||||
required and you are done. If the patch succeeded, recompile the
|
||||
interpreter by calling "make" and "make install" in the directory "src".
|
||||
|
||||
o Go to the sub-directory "src" below the directory where you unpacked
|
||||
unroff:
|
||||
|
||||
cd /usr/local/src/unroff-1.0/src
|
||||
|
||||
and edit the Makefile. Check the site and compiler dependencies at the
|
||||
beginning of the Makefile and modify them if necessary.
|
||||
|
||||
(Don't worry about DIR= if you just want to test unroff; you can
|
||||
override the directory later by setting the environment variable
|
||||
UNROFF_DIR before calling unroff.)
|
||||
|
||||
o Call "make depend" and then "make".
|
||||
|
||||
o You may want to remove the minimal Elk runtime environment contained
|
||||
in the directory "elk" and replace it by a symbolic link to your
|
||||
site's Elk runtime directory (i.e. the directory with sub-directories
|
||||
"scm" and "obj").
|
||||
|
||||
|
||||
o Test unroff and the HTML back-end included in the distribution.
|
||||
|
||||
For example, change to the directory "doc" and run "make" to convert
|
||||
the manual pages and the Programmer's Manual to HTML. Then view the
|
||||
resulting .html files with your favorite WWW browser.
|
||||
|
||||
Test the supplementary -ms features by calling (still in "doc"):
|
||||
|
||||
unroff -ms document=test split=1 hyper.scm manual.ms
|
||||
|
||||
This creates several files beginning with "test". Load test.html
|
||||
into your WWW browser; observe the automatically generated table of
|
||||
contents and the hypertext links embedded in the document. When
|
||||
finished, you may want to "rm test*".
|
||||
|
||||
You can proceed by using unroff with a few troff documents of your
|
||||
own. For example, try to convert a large manual page:
|
||||
|
||||
unroff -man /usr/man/man1/csh.1
|
||||
|
||||
Don't worry if this displays numerous warning messages. unroff
|
||||
usually produces good results even if many low-level troff requests
|
||||
are ignored. Check csh.1.html with your WWW browser.
|
||||
|
||||
o Read the documentation located in the directory "doc", in particular
|
||||
the manual pages.
|
||||
|
||||
You can convert the troff files to HTML and view them with your
|
||||
WWW browser (as explained in the previous step), or typeset them
|
||||
using your local troff and send the output to the printer, or read
|
||||
them online using nroff or man.
|
||||
|
||||
o You may want to place a number of default settings into an initialization
|
||||
file ".unroff" in your home directory. There is a sample init file
|
||||
"sample.unroff" in the directory "misc". If you decide to use this
|
||||
file, replace the string "net@cs.tu-berlin.de" by your e-mail address.
|
||||
|
||||
o If you find unroff useful, you may want to install it in a central
|
||||
directory at your site. If so, install the executable, the contents
|
||||
of the directory "scm", and the manual pages.
|
||||
|
||||
|
||||
If you have any questions, problems, or suggestions send a message to
|
||||
net@cs.tu-berlin.de.
|
||||
|
||||
# $Revision: 1.6 $
|
||||
|
|
@ -0,0 +1 @@
|
|||
2
|
||||
|
|
@ -0,0 +1,133 @@
|
|||
This is version 1.0 of unroff.
|
||||
|
||||
Unroff is a Scheme-based, programmable, extensible troff translator
|
||||
with a back-end for the Hypertext Markup Language. Unroff is free
|
||||
software and is distributed both as source and as precompiled binaries.
|
||||
|
||||
|
||||
* Overview
|
||||
|
||||
Unroff reads and parses UNIX troff documents and translates the embedded
|
||||
markup into a different format. Neither the actual output format nor
|
||||
any knowledge about particular troff macro sets (-man, -ms, etc.) are
|
||||
hard-wired into unroff. Instead, the translation process is controlled
|
||||
by a set of user-supplied procedures written in the Scheme programming
|
||||
language.
|
||||
|
||||
Translation rules for new output formats and troff macro packages can
|
||||
be added easily by providing a corresponding set of Scheme procedures
|
||||
(a `back-end'). Version 1.0 of unroff includes back-ends for translating
|
||||
documents using the `man' and `ms' macros into the Hypertext Markup
|
||||
Language (HTML) version 2.0. Additional requests facilitate use of
|
||||
arbitrary hypertext links in troff documents.
|
||||
|
||||
|
||||
* unroff and troff
|
||||
|
||||
In contrast to conventional troff `converters' (usually Perl scripts
|
||||
some of which process nroff output) unroff includes a full troff parser
|
||||
and closely mimics the troff processing engine.
|
||||
|
||||
This enables unroff to handle user-defined macros, strings, and
|
||||
number registers, nested if-else requests, arbitrary fonts and font
|
||||
positions, low-level formatting requests such as \l, \c, and \h, and
|
||||
idiosyncrasies such as troff `copy mode' and the subtle differences
|
||||
between request and macro invocations.
|
||||
|
||||
Unroff has adopted a number of groff extensions, among them long names
|
||||
for macros, strings, number registers, and special characters, and the
|
||||
escape sequences \$@ and \$*.
|
||||
|
||||
|
||||
* unroff and Scheme
|
||||
|
||||
Unroff uses Elk, the Scheme-based Extension Language Kit, to achieve
|
||||
programmability. It includes a full Scheme language implementation
|
||||
with the usual amenities such as garbage collection, interactive
|
||||
programming and testing, and dynamic loading. Standard Scheme has
|
||||
been augmented by a set of new Scheme data types and primitives that
|
||||
aid in writing new unroff back-ends.
|
||||
|
||||
A new troff request and an extension to the `.ig' request allow for
|
||||
Scheme code to be embedded in troff documents; the code is then
|
||||
evaluated on the fly as the documents are processed by unroff.
|
||||
|
||||
Unroff may be viewed as a prototype for hybrid applications that use
|
||||
Scheme (in particular Elk) as their extension language. Approximately
|
||||
half of its source consists of portable ANSI C code, and the other
|
||||
half is written in Scheme and can be configured and tailored easily
|
||||
without the need to recompile unroff. Authors of Elk-based applications
|
||||
are encouraged to look into the source code or reuse parts of it for
|
||||
their own projects.
|
||||
|
||||
As the time-critical Scheme primitives provided of unroff have been
|
||||
coded in (efficient) C, its performance comes close to that of nroff
|
||||
processing the same troff input.
|
||||
|
||||
|
||||
* unroff and hypertext
|
||||
|
||||
troff documents that were originally written without intentions to
|
||||
make them available in the World Wide Web (such as UNIX manual pages)
|
||||
can easily be translated to the Hypertext Markup Language using the
|
||||
predefined HTML back-ends.
|
||||
|
||||
As unroff closely simulates ordinary troff, even large or complex
|
||||
documents (like technical reports or theses with many user-defined
|
||||
macros) can be translated to HTML automatically without having to
|
||||
add any structural cues to the documents.
|
||||
|
||||
The `-man' support has been tested with several hundred vendor- and
|
||||
user-supplied manual pages and has produced good results in all but
|
||||
less than a dozen cases (a few manual pages were found to make excessive
|
||||
use of low-level troff constructs or to include tbl output verbatim).
|
||||
|
||||
|
||||
* Managing hypertext documents with troff
|
||||
|
||||
Authors can benefit from unroff not only as a converter for existing
|
||||
documents, but also when writing new documents that must exist both
|
||||
in high-quality paper form and in the World Wide Web as hypertext.
|
||||
|
||||
Rather than writing hypertext documents directly in HTML (which is
|
||||
cumbersome for long or complex texts), authors can continue using
|
||||
ordinary troff together with the usual preprocessors and macro packages.
|
||||
Unroff is then employed to produce the WWW form, while troff is used
|
||||
in the normal way to typeset the same text, producing the printed
|
||||
version (or, using nroff, an ASCII version if desired).
|
||||
|
||||
In this way authors of hypertext documents can take full advantage of
|
||||
the usual troff facilities such as user-defined macros, conditional text,
|
||||
tables, equations, and drawings, automatic table of contents generation,
|
||||
footnotes/endnotes, indexes, etc., none of which are available when
|
||||
composing documents directly in plain HTML.
|
||||
|
||||
Two new troff requests for embedding hypertext links in troff documents
|
||||
are provided by the unroff HTML back-end. Arbitrary forward and backward
|
||||
references using symbolic labels (rather than actual file names) among
|
||||
groups of troff source files are supported. Another new request and
|
||||
another extension to `.ig' allow for HTML code to be embedded directly
|
||||
in troff documents. The hypertext capabilities are demonstrated by
|
||||
the troff source of the Programmer's Manual that is part of the unroff
|
||||
distribution.
|
||||
|
||||
|
||||
* Availability
|
||||
|
||||
The source distribution of unroff 1.0 as well as binary distributions
|
||||
(with full Scheme source code and documentation) are available under:
|
||||
|
||||
http://www.informatik.uni-bremen.de/~net/unroff/unroff.html#dist
|
||||
|
||||
You can obtain Elk 3.0 from the same WWW server at:
|
||||
|
||||
http://www.informatik.uni-bremen.de/~net/elk
|
||||
|
||||
Elk 3.0 is also available from a number of FTP servers including these:
|
||||
|
||||
ftp://ftp.x.org/contrib/devel_tools/elk-3.0.tar.gz
|
||||
ftp://ftp.uni-bremen.de/pub/programming/languages/scheme/elk/elk-3.0.tar.gz
|
||||
|
||||
|
||||
--
|
||||
Oliver Laumann <net@cs.tu-berlin.de> # $Revision: 1.4 $
|
||||
|
|
@ -0,0 +1,34 @@
|
|||
# $Revision: 1.7 $
|
||||
|
||||
SHELL = /bin/sh
|
||||
UNROFF = unroff
|
||||
|
||||
TROFF = \
|
||||
unroff.1\
|
||||
unroff-html.1\
|
||||
unroff-html-man.1\
|
||||
unroff-html-ms.1\
|
||||
manual.ms
|
||||
|
||||
HTML = \
|
||||
unroff.1.html\
|
||||
unroff-html.1.html\
|
||||
unroff-html-man.1.html\
|
||||
unroff-html-ms.1.html\
|
||||
manual.html
|
||||
|
||||
|
||||
ALL = $(HTML)
|
||||
|
||||
all: $(ALL)
|
||||
|
||||
.SUFFIXES: .1 .1.html
|
||||
|
||||
.1.1.html:
|
||||
$(UNROFF) -man $<
|
||||
|
||||
manual.html: manual.ms
|
||||
$(UNROFF) -ms document=manual hyper.scm $?
|
||||
|
||||
clean:
|
||||
rm -f $(ALL)
|
||||
File diff suppressed because it is too large
Load Diff
|
|
@ -0,0 +1,19 @@
|
|||
.\" tmac.hyper: These macros implement hypertext links in troff, that is,
|
||||
.\" they basically do nothing. See scm/misc/hyper.scm for the macros as
|
||||
.\" implemented by unroff.
|
||||
.
|
||||
.ds pk tmac.hyper
|
||||
.
|
||||
.de Er
|
||||
.tm \\*(pk: \\$1 \\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9
|
||||
..
|
||||
.
|
||||
.de Ha
|
||||
.if !\\n(.$=2 .Er too few arguments for .Ha
|
||||
\\$2\c
|
||||
..
|
||||
.
|
||||
.de Hr
|
||||
.if \\n(.$<1 .Er too few arguments for .Hr
|
||||
.if !'\\$1'-symbolic' .if !'\\$1'-url' \\$1
|
||||
..
|
||||
|
|
@ -0,0 +1,218 @@
|
|||
.\" $Revision: 1.6 $
|
||||
.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-man 1 "\*(Dt"
|
||||
.SH NAME
|
||||
unroff-html-man \- back-end to translate manual pages to HTML 2.0
|
||||
.SH SYNOPSIS
|
||||
.B unroff
|
||||
[
|
||||
.B \-fhtml
|
||||
] [
|
||||
.B \-man
|
||||
] [
|
||||
.IR file " | " option...\&
|
||||
]
|
||||
.SH OVERVIEW
|
||||
When called with the
|
||||
.B \-fhtml
|
||||
and
|
||||
.B \-man
|
||||
options, the troff translator
|
||||
.I unroff
|
||||
loads the back-end for converting UNIX manual pages 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 \-man
|
||||
extension provides one new keyword/value option in addition to
|
||||
those listed in
|
||||
.BR unroff (1)
|
||||
and
|
||||
.BR unroff-html (1):
|
||||
.TP
|
||||
.BR do-signature " (boolean)"
|
||||
If set to 1, a signature is appended to each output file.
|
||||
The signature is composed of a horizontal rule and a one-line
|
||||
message consisting of version information and date and time.
|
||||
The default value of this option is 1.
|
||||
.SH DESCRIPTION
|
||||
.I unroff
|
||||
reads and parses its input files (each containing a UNIX manual
|
||||
page); the HTML output is written to a separate output file
|
||||
for each input file.
|
||||
The name of an output file is obtained by appending the
|
||||
suffix \*(lq.html\*(rq to the name of the corresponding input
|
||||
file.
|
||||
Any
|
||||
.B document
|
||||
option is ignored if input files are named in the command line.
|
||||
As usual, the special file name
|
||||
.RB ` \- '
|
||||
can be used to interpolate standard input.
|
||||
.LP
|
||||
If no file name is given in the command line, a manual page
|
||||
is read from standard input and sent to standard output,
|
||||
unless the
|
||||
.B document
|
||||
option is given, in which case the HTML output is written
|
||||
to the specified file (with \*(lq.html\*(rq appended).
|
||||
Example:
|
||||
this call to
|
||||
.I unroff
|
||||
translates two manual pages and creates two corresponding output files,
|
||||
.B cc.1.html
|
||||
and
|
||||
.BR send.2.html :
|
||||
.Ex
|
||||
unroff \-fhtml \-man /usr/man/man1/cc.1 /usr/man/man2/send.2
|
||||
.Ee
|
||||
.LP
|
||||
The following
|
||||
.B \-man
|
||||
macros are recognized and translated (in addition to any user-defined macros):
|
||||
.LP
|
||||
.nf
|
||||
.if !\n(.U .ta 8n 16n 24n 32n 40n 48n 56n
|
||||
.TH .SH .SS .I .B .SB .SM
|
||||
.BI .BR .IB .IR .RB .RI .TP
|
||||
.IP .HP .RS .RE .LP .PP .P
|
||||
.fi
|
||||
.LP
|
||||
In addition, the following Sun-specific macros are silently
|
||||
ignored (.TX generates an informational message containing
|
||||
its argument):
|
||||
.LP
|
||||
.nf
|
||||
.TX .IX .DT .PD .UC
|
||||
.fi
|
||||
.LP
|
||||
The following predefined troff strings are recognized
|
||||
(\e*S expands to the empty string):
|
||||
.LP
|
||||
.nf
|
||||
\e*R \e*S \e*(lq \e*(rq
|
||||
.fi
|
||||
.LP
|
||||
The title of each HTML document generated is obtained by calling
|
||||
the primitive
|
||||
.I substitute
|
||||
(as explained in the Programmer's Manual) with the value of the option
|
||||
.B title
|
||||
and the first and second arguments passed to the initial call to
|
||||
.BR .TH .
|
||||
Thus, the specifiers \*(lq%1%\*(rq and \*(lq%2%\*(rq can be used
|
||||
in the option to interpolate the command (or whatever is documented
|
||||
in the manual page) and the section number.
|
||||
If
|
||||
.B title
|
||||
has not been specified, the string \*(lqManual page for %1%(%2%)\*(rq
|
||||
is taken.
|
||||
As generating the HTML title element is deferred until the call to
|
||||
.BR .TH ,
|
||||
any macros or other troff requests that produce output must not be
|
||||
used before the initial
|
||||
.BR .TH .
|
||||
.LP
|
||||
HTML header elements <h2> and <h3> are created for
|
||||
.B .SH
|
||||
and
|
||||
.B .SS
|
||||
requests.
|
||||
The markup created for the initial NAME section differs in that the
|
||||
contents of the section (usually a single line) is itself placed
|
||||
inside a header element.
|
||||
.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.
|
||||
As HTML is lacking the concept of text size, the macro
|
||||
.B .SB
|
||||
is just an alias for
|
||||
.BR .B ,
|
||||
and
|
||||
.B .SM
|
||||
simply echoes its arguments.
|
||||
.LP
|
||||
The translation rules for
|
||||
.B .TP
|
||||
and
|
||||
.B .IP
|
||||
employ a heuristic to determine whether to generate a definition
|
||||
list or an unordered list:
|
||||
if the first in a sequence of tagged/indented paragraph macros is
|
||||
called with a tag consisting of the special character \e(bu, a
|
||||
definition list is begun, otherwise an unordered list.
|
||||
Subsequent invocations cause the list style to change if appropriate.
|
||||
Use of tagged paragraphs inside non-filled (pre-formatted) text
|
||||
violates the HTML definition and should be avoided.
|
||||
A warning message is printed in this and other questionable situations.
|
||||
.LP
|
||||
As hanging tags cannot be realized with HTML 2.0,
|
||||
a kludge is used for the
|
||||
.B .HP
|
||||
(hanging paragraph) macro:
|
||||
the macro starts a definition list (as does the ordinary
|
||||
.BR .TP
|
||||
macro), and everything up to the next request that causes a break
|
||||
is placed inside the definition tag.
|
||||
This method obviously fails if no break occurs in subsequent lines,
|
||||
but it works for the common, idiomatic use of hanging paragraphs
|
||||
in manual pages.
|
||||
.SH "SEE ALSO"
|
||||
.BR unroff (1),
|
||||
.BR unroff-html (1),
|
||||
.BR troff (1),
|
||||
.BR man "(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.
|
||||
|
|
@ -0,0 +1,324 @@
|
|||
.\" $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.
|
||||
|
|
@ -0,0 +1,671 @@
|
|||
.\" $Revision: 1.12 $
|
||||
.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 1 "\*(Dt"
|
||||
.SH NAME
|
||||
unroff-html \- HTML 2.0 back-end for the programmable troff translator
|
||||
.SH SYNOPSIS
|
||||
.B unroff
|
||||
[
|
||||
.B \-fhtml
|
||||
] [
|
||||
.BI \-m package
|
||||
] [
|
||||
.IR file " | " option...\&
|
||||
]
|
||||
.SH OVERVIEW
|
||||
When called with the
|
||||
.B \-fhtml
|
||||
option,
|
||||
.I unroff
|
||||
loads the back-end for the Hypertext Markup Language (HTML) version 2.0.
|
||||
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 .
|
||||
For information about extending and programming
|
||||
.I unroff
|
||||
also refer to the
|
||||
.IR "Unroff Programmer's Manual" .
|
||||
.LP
|
||||
.I unroff
|
||||
is usually invoked with an additional
|
||||
.BI \-m package
|
||||
option (such as
|
||||
.B \-ms
|
||||
or
|
||||
.BR \-man )
|
||||
to load the translation rules for the troff macros and other elements
|
||||
defined by the macro package that is used to typeset the document.
|
||||
If no
|
||||
.B \-m
|
||||
option is supplied, only the standard troff requests, special characters,
|
||||
escape sequences, etc. are recognized and translated to HTML by
|
||||
.I unroff
|
||||
as described in this manual.
|
||||
.SH OPTIONS
|
||||
The following HTML-specific options can be specified in the command
|
||||
line after the generic options.
|
||||
See
|
||||
.BR unroff (1)
|
||||
for a general description of keyword/value options and their types
|
||||
and for a list of options that are not specific to the target language.
|
||||
.TP
|
||||
.BR title " (string)"
|
||||
The value to be used for the <title> element in HTML output files.
|
||||
This option may be ignored by the code implementing a specific
|
||||
macro set, e.\|g. when special rules are employed to derive the title
|
||||
from the contents of the troff input files.
|
||||
Whether or not this option is required also depends on the specific
|
||||
.B \-m
|
||||
option used, but it may be omitted if no
|
||||
.B \-m
|
||||
option is given.
|
||||
.TP
|
||||
.BR document " (string)"
|
||||
The prefix used for the names of all output files.
|
||||
May be ignored depending on the macro package that has been selected.
|
||||
.TP
|
||||
.BR mail-address " (string)"
|
||||
The caller's mail address; may be used for \*(lqmailto:\*(rq URLs,
|
||||
in particular for the \*(lqhref\*(rq attribute of the <link>
|
||||
element that is usually generated.
|
||||
.TP
|
||||
.BR tt-preformat " (boolean)"
|
||||
If 1, font changes to a font that is mapped to the <tt> element
|
||||
are honored inside non-filled text (as described below).
|
||||
The default is 0, i.\|e. the font changes will be recorded, but no
|
||||
corresponding HTML tags will be emitted for them.
|
||||
.TP
|
||||
.BR handle-eqn " (string)"
|
||||
.TP
|
||||
.BR handle-tbl " (string)"
|
||||
.TP
|
||||
.BR handle-pic " (string)"
|
||||
These options specify how equations, tables, and pictures encountered
|
||||
in the troff input are processed.
|
||||
Possible values are \*(lqcopy\*(rq to include the raw eqn, tbl, or
|
||||
pic commands as pre-formatted text, \*(lqtext\*(rq to run the
|
||||
respective troff preprocessor (eqn, tbl, or pic) and include its output
|
||||
as pre-formatted text, or \*(lqgif\*(rq to convert the preprocessor
|
||||
output to a GIF image and include it in the HTML document as
|
||||
an inline image.
|
||||
The default is \*(lqtext\*(rq for
|
||||
.BR handle-tbl ,
|
||||
\*(lqgif\*(rq for the other options.
|
||||
See DESCRIPTION below for more information.
|
||||
.TP
|
||||
.BR eqn " (string)"
|
||||
.TP
|
||||
.BR tbl " (string)"
|
||||
.TP
|
||||
.BR pic " (string)"
|
||||
These options specify the programs to invoke as the eqn, tbl,
|
||||
and pic preprocessors.
|
||||
The defaults are site-dependent.
|
||||
.TP
|
||||
.BR troff-to-text " (string)"
|
||||
.TP
|
||||
.BR troff-to-gif " (string)"
|
||||
The programs to invoke for converting the output of a troff preprocessor
|
||||
to plain text or to a GIF image.
|
||||
The default values are site-dependent.
|
||||
See DESCRIPTION below for more information on these options.
|
||||
.SH FILES
|
||||
If no
|
||||
.B \-m
|
||||
option is supplied,
|
||||
.I unroff
|
||||
reads the specified input files and sends the HTML document to
|
||||
standard output, unless the
|
||||
.B document
|
||||
option is given, in which case its value together
|
||||
with the suffix \*(lq.html\*(rq is used as the name of an
|
||||
output file.
|
||||
If no input files are specified, input is taken from standard input.
|
||||
The output is enclosed by the usual HTML boiler-plate (<html>, <head>,
|
||||
and <body> elements), a <title> element with the specified title
|
||||
(or the value of
|
||||
.B document
|
||||
if no title has been given, or a default title if both are omitted),
|
||||
a <link> element with rev= and href= attributes if
|
||||
.B mail-address
|
||||
has been set, and any pending end tags are generated on end of input.
|
||||
.LP
|
||||
Note that this is the default action that is performed in the
|
||||
rare case when no macro package name has been specified, i.\|e. when
|
||||
processing \*(lqbare\*(rq troff input.
|
||||
Somewhat different rules may apply when processing, for
|
||||
example, a group of UNIX manual pages
|
||||
.RB ( \-man ).
|
||||
.LP
|
||||
See
|
||||
.BR unroff (1)
|
||||
for a list of Scheme files that are loaded on startup.
|
||||
.SH DESCRIPTION
|
||||
.SS "OUTPUT TRANSLATIONS"
|
||||
The characters `<', `>', and `&' are replaced by the entities
|
||||
`<', `>', and `&' on output.
|
||||
In addition, the quote character is mapped to `"' where
|
||||
appropriate.
|
||||
New mappings can be added by means of the
|
||||
.I defchar
|
||||
Scheme primitive as explained in the Programmer's Manual.
|
||||
.SS COMMENTS
|
||||
each troff comment is translated to a corresponding HTML tag
|
||||
followed by a newline; empty comments are ignored.
|
||||
Comments are also ignored when appearing inside a macro body.
|
||||
.SS "ESCAPE SEQUENCES"
|
||||
The following is a list of troff escape sequences that are recognized
|
||||
and the HTML output generated for them.
|
||||
Any escape sequence that does not appear in the list
|
||||
expands to the character after the escape character, and
|
||||
a warning is printed in this case.
|
||||
New definitions can be added and the predefined mappings can
|
||||
be replaced by calling the
|
||||
.I defescape
|
||||
Scheme primitive in the user's initialization file, in a user-supplied
|
||||
Scheme file, in a document, or on a site-wide basis by modifying
|
||||
the file
|
||||
.B scm/html/common.scm
|
||||
in the installation directory.
|
||||
.LP
|
||||
.nf
|
||||
.if !\n(.U .ta 8n 16n 24n 32n 40n 48n 56n
|
||||
\e& nothing
|
||||
\e- -
|
||||
\e| nothing
|
||||
\e^ nothing
|
||||
\e\e \e
|
||||
\e' '
|
||||
\e` `
|
||||
\e" rest of line as HTML comment tag
|
||||
\e% nothing
|
||||
\e{ conditional input begin
|
||||
\e} conditional input end
|
||||
\e* contents of string
|
||||
\espace space
|
||||
\e0 space
|
||||
\ec nothing; eats following newline
|
||||
\ee \e
|
||||
\es nothing
|
||||
\eu nothing, prints warning
|
||||
\ed nothing, prints warning
|
||||
\ev nothing, prints warning
|
||||
\eo its argument, prints warning
|
||||
\ez its argument, prints warning
|
||||
\ek sets specified register to zero
|
||||
\eh appropriate number of spaces for positive argument
|
||||
\ew length of argument in units
|
||||
\el repeats specified character, or <hr>
|
||||
\en contents of number register
|
||||
\ef see description of fonts below
|
||||
.fi
|
||||
.SS "SPECIAL CHARACTERS"
|
||||
The following special characters are mapped to their equivalent
|
||||
ISO-Latin 1 entities:
|
||||
.LP
|
||||
.nf
|
||||
\e(12 \e(14 \e(34 \e(*b \e(*m \e(+- \e(:A
|
||||
\e(:O \e(:U \e(:a \e(:o \e(:u \e(A: \e(Cs
|
||||
\e(O: \e(Po \e(S1 \e(S2 \e(S3 \e(U: \e(Ye
|
||||
\e(a: \e(bb \e(cd \e(co \e(ct \e(de \e(di
|
||||
\e(es \e(hy \e(mu \e(no \e(o: \e(r! \e(r?
|
||||
\e(rg \e(sc \e(ss \e(tm \e(u:
|
||||
.fi
|
||||
.LP
|
||||
Heuristics have to be used for the following special characters:
|
||||
.LP
|
||||
.nf
|
||||
\e(** *
|
||||
\e(-> ->
|
||||
\e(<- <-
|
||||
\e(<= <=
|
||||
\e(== ==
|
||||
\e(>= >=
|
||||
\e(Fi ffi
|
||||
\e(Fl ffl
|
||||
\e(aa '
|
||||
\e(ap ~
|
||||
\e(br |
|
||||
\e(bu + (prints a warning)
|
||||
\e(bv |
|
||||
\e(ci O
|
||||
\e(dd *** (prints a warning)
|
||||
\e(dg ** (prints a warning)
|
||||
\e(em --
|
||||
\e(en -
|
||||
\e(eq =
|
||||
\e(ff ff
|
||||
\e(fi fi
|
||||
\e(fl fl
|
||||
\e(fm '
|
||||
\e(ga `
|
||||
\e(lh <=
|
||||
\e(lq ``
|
||||
\e(mi -
|
||||
\e(or |
|
||||
\e(pl +
|
||||
\e(rh =>
|
||||
\e(rq ''
|
||||
\e(ru _
|
||||
\e(sl /
|
||||
\e(sq o (prints a warning)
|
||||
\e(ul _
|
||||
\e(~= ~
|
||||
.fi
|
||||
.LP
|
||||
A warning is printed to standard error output for any special
|
||||
character not mentioned in this section.
|
||||
To add new definitions, and to customize existing ones, the
|
||||
.I defspecial
|
||||
Scheme primitive can be used.
|
||||
.SS "NON-FILLED TEXT"
|
||||
The
|
||||
.B .nf
|
||||
and
|
||||
.B .fi
|
||||
troff requests generate pairs of <pre> and </pre> tags.
|
||||
Nested requests are treated correctly, and currently
|
||||
active character formatting elements such as <i> (resulting
|
||||
from troff font changes) are temporarily disabled while
|
||||
the <pre> or </pre> is emitted.
|
||||
A warning is printed if a \*(lqtab\*(rq character is encountered
|
||||
within filled text.
|
||||
.SS FONTS
|
||||
The `\ef' escape sequence and the requests
|
||||
.B .ft
|
||||
(change current font) and
|
||||
.B .fp
|
||||
(mount font at font position) are supported in the usual way,
|
||||
both with numeric font positions as well as font names and
|
||||
the special name `P' to denote the previous font.
|
||||
The font position of the currently active font is available
|
||||
through the read-only number register `.f'.
|
||||
Initially, the font `R' is mounted on font positions 1 and 4,
|
||||
font `I' on font position 2, and font `B' on position 3.
|
||||
.LP
|
||||
To map troff font names to HTML character formatting elements,
|
||||
the \f2define-font\fP Scheme procedure is called with the name
|
||||
of a troff font to be used in documents, and
|
||||
HTML start and end tags to be emitted when changing to this font,
|
||||
or when changing
|
||||
.I from
|
||||
this font to another font, respectively.
|
||||
Whether <tt> and </tt> is generated inside non-filled (pre-formatted)
|
||||
text for fixed-width fonts is controlled by the option
|
||||
.BR tt-preformat .
|
||||
The following calls to
|
||||
.I define-font
|
||||
are evaluated on startup:
|
||||
.LP
|
||||
.nf
|
||||
.if !\n(.U \{\
|
||||
. ft C
|
||||
. ps -1
|
||||
. vs -1 \}
|
||||
(define-font "R" "" "")
|
||||
(define-font "I" '<i> '</i>)
|
||||
(define-font "B" '<b> '</b>)
|
||||
(define-font "C" '<tt> '</tt>)
|
||||
(define-font "CW" '<tt> '</tt>)
|
||||
(define-font "CO" '<i> '</i>) ; kludge for Courier-Oblique
|
||||
.if !\n(.U \{\
|
||||
. ft
|
||||
. ps
|
||||
. vs \}
|
||||
.fi
|
||||
.LP
|
||||
Site administrators may add definitions here for fonts used
|
||||
at their site.
|
||||
Users can define mappings for new fonts by placing corresponding
|
||||
definitions in their documents or document-specific Scheme files.
|
||||
.SS "OTHER TROFF REQUESTS"
|
||||
The
|
||||
.B .br
|
||||
request generates a <br> tag.
|
||||
.LP
|
||||
.B .sp
|
||||
requires a positive argument and is mapped to the appropriate number
|
||||
of <p> tags (or newline characters inside non-filled/pre-formatted
|
||||
text).
|
||||
Likewise, the request
|
||||
.BR .ti ,
|
||||
when called with a positive indent, produces a <br> followed by the
|
||||
appropriate number of non-breakable spaces.
|
||||
.LP
|
||||
The
|
||||
.B .tl
|
||||
requests justs emits the title parts delimited by spaces.
|
||||
It is impossible to preserve the meaning of this request
|
||||
in HTML 2.0.
|
||||
.LP
|
||||
The horizontal line drawing escape sequence `\el' just repeats
|
||||
the specified character (or underline as default) to draw
|
||||
a line.
|
||||
If the given length looks like it could be the line length
|
||||
(that is, if it exceeds a certain value), a <hr> tag
|
||||
is produced instead.
|
||||
Example:
|
||||
.LP
|
||||
.nf
|
||||
\el'5c\e&-'
|
||||
\el'60'
|
||||
.fi
|
||||
.LP
|
||||
The first of these two requests
|
||||
would produce a line of 20 dashes, while the second
|
||||
request would generate a <hr> tag (the '\e&' is required
|
||||
because the dash could be interpreted as a continuation of
|
||||
the numeric expression).
|
||||
.LP
|
||||
Centering
|
||||
.RB ( .ce )
|
||||
is simulated by producing a <br> at the end of each line, as
|
||||
this functionality is not supported by HTML 2.0.
|
||||
.LP
|
||||
The following requests are silently ignored; as the corresponding
|
||||
functions cannot be expressed in HTML 2.0 or are controlled by
|
||||
the client.
|
||||
Ignoring these requests most likely does no harm.
|
||||
.LP
|
||||
.nf
|
||||
.ad .bp .ch .fl .hw .hy .lg
|
||||
.na .ne .nh .ns .pl .ps .rs
|
||||
.vs .wh
|
||||
.fi
|
||||
.LP
|
||||
All troff requests not mentioned in this section by default
|
||||
cause a warning message to be printed to standard error output,
|
||||
except for these basic requests which have their usual
|
||||
semantics:
|
||||
.LP
|
||||
.nf
|
||||
.am .as .de .ds .ec .el .ie
|
||||
.if .ig .nr .rm .rr .so .tm
|
||||
.fi
|
||||
.LP
|
||||
The
|
||||
.I defrequest
|
||||
Scheme primitive is used to associate an event handling procedure
|
||||
with a request as documented in the Programmer's Manual.
|
||||
.SS "END OF SENTENCE"
|
||||
The sequence \*(lq<tt>space</tt>\*(rq is produced at the end of
|
||||
each sentence to provide additional space, except inside non-filled text.
|
||||
A sentence is defined a sequence of characters followed by
|
||||
a period, a question mark, or an exclamation mark, followed
|
||||
by a newline.
|
||||
The usual convention to suppress end-of-sentence recognition
|
||||
by adding the escape sequence `\e&' is correctly implemented by
|
||||
.IR unroff .
|
||||
To change the end-of-sentence function, the
|
||||
.I sentence-event
|
||||
can be redefined from within Scheme code as described in
|
||||
the Programmer's Manual.
|
||||
.SS "SCALE INDICATORS"
|
||||
As the notions of vertical spacing, character width, device
|
||||
resolution, etc. do not exist in HTML, the scaling for the
|
||||
usual troff scale indicators is defined once on startup and
|
||||
then remains constant.
|
||||
For simplicity, the scaling usually employed by
|
||||
.BR nroff (1)
|
||||
is taken.
|
||||
.SS "EQUATIONS, TABLES, PICTURES"
|
||||
Interpretation of embedded eqn, tbl, and pic preprocessor input
|
||||
is controlled by the options
|
||||
.BR handle-eqn ,
|
||||
.BR handle-tbl ,
|
||||
and
|
||||
.B handle-pic
|
||||
(see OPTIONS above).
|
||||
These options affect the input lines from a starting
|
||||
.BR .EQ ,
|
||||
.BR .TS ,
|
||||
or
|
||||
.B .PS
|
||||
request up to and including the matching
|
||||
.BR .EN ,
|
||||
.BR .TE ,
|
||||
or
|
||||
.B .PE
|
||||
request, as well as text surrounded by the current eqn
|
||||
inline equation delimiters.
|
||||
Each of the options can have one the following values:
|
||||
.TP
|
||||
.B copy
|
||||
The preprocessor input (including the enclosing requests) is
|
||||
placed inside <pre> and </pre>.
|
||||
If assigned to the option
|
||||
.BR handle-eqn ,
|
||||
inline equations are rendered in the font currently mounted
|
||||
on font position 2.
|
||||
.TP
|
||||
.B text
|
||||
The input is sent to the respective preprocessor (as specified
|
||||
by the options
|
||||
.BR eqn ,
|
||||
.BR tbl ,
|
||||
or
|
||||
.BR pic ),
|
||||
and its result is piped to the shell command referred to by the
|
||||
option
|
||||
.BR troff-to-text ,
|
||||
which typically involves a call to
|
||||
.BR nroff (1)
|
||||
or an equivalent command.
|
||||
As with \*(lqcopy\*(rq, the result is then placed inside
|
||||
<pre> and </pre>, unless the source is an inline equation.
|
||||
.IP
|
||||
The value of
|
||||
.B troff-to-text
|
||||
is filtered through a call to the
|
||||
.I substitute
|
||||
Scheme primitive with the name of an output file as its argument;
|
||||
this file name can be referenced from within the option's value
|
||||
by the substitute specifier \*(lq%1%\*(rq (see the Programmer's
|
||||
Manual for a description of
|
||||
.I substitute
|
||||
and a list of substitute specifiers).
|
||||
Here is a typical value for the
|
||||
.B troff-to-text
|
||||
option:
|
||||
.Ex
|
||||
"groff \-Tascii | col \-b | sed '/^[ \et]*$/d' > %1%"
|
||||
.Ee
|
||||
.TP
|
||||
.B gif
|
||||
Input lines are preprocessed as described under \*(lqtext\*(rq, and
|
||||
the result is piped to the shell command named by the option
|
||||
.BR troff-to-gif .
|
||||
The latter is subject to a call to
|
||||
.I substitute
|
||||
with the name of a temporary file (which may be used to store intermediate
|
||||
PostScript output) and the name of the output file where the resulting
|
||||
GIF image must be stored.
|
||||
The entire preprocessor input is replaced by an <img> element with
|
||||
a reference to the GIF file and a suitable \*(lqalt=\*(rq attribute.
|
||||
Unless processing an inline equation, the <img> element is
|
||||
surrounded by <p> tags.
|
||||
.IP
|
||||
The names of the files containing the GIF images are generated
|
||||
from the value of the
|
||||
.B document
|
||||
option, a sequence number, and the suffix \*(lq.gif\*(rq.
|
||||
Therefore, the
|
||||
.B document
|
||||
option must have been set when using the \*(lqgif\*(rq method,
|
||||
otherwise a warning is printed and the preprocessor input
|
||||
is skipped.
|
||||
.LP
|
||||
In any case, the output of a call to eqn is ignored if the
|
||||
input consists of calls to \*(lqdelim\*(rq or \*(lqdefine\*(rq
|
||||
and empty lines exclusively.
|
||||
When processing eqn input, calls to \*(lqdelim\*(rq are intercepted by
|
||||
.I unroff
|
||||
to record changes of the inline equation delimiters.
|
||||
.SS "HYPERTEXT LINKS"
|
||||
The facilities for embedding arbitrary hypertext links in troff
|
||||
documents are still experimental in this version of
|
||||
.I unroff
|
||||
and thus are likely to change in future releases.
|
||||
To use them, mention the file name \*(lqhyper.scm\*(rq in the
|
||||
command line before any troff source files.
|
||||
At the beginning of the first troff file, source the file
|
||||
\*(lqtmac.hyper\*(rq from the directory \*(lqdoc\*(rq like this:
|
||||
.LP
|
||||
.nf
|
||||
.if !\en(.U .so tmac.hyper
|
||||
.fi
|
||||
.LP
|
||||
The request
|
||||
.B .Hr
|
||||
can then be used to create a hypertext link.
|
||||
Its usage is:
|
||||
.LP
|
||||
.nf
|
||||
.Hr -url URL anchor-text [suffix]
|
||||
.Hr -symbolic label anchor-text [suffix]
|
||||
.Hr troff-text
|
||||
.fi
|
||||
.LP
|
||||
The first two forms are recognized by
|
||||
.I unroff
|
||||
and the third form is recognized by troff.
|
||||
The first form is used for links pointing to external resources,
|
||||
and the second one is used for forward or backward links referencing
|
||||
anchors defined in a file belonging to the same document.
|
||||
An anchor is placed in the document by calling the request
|
||||
.BR .Ha :
|
||||
.LP
|
||||
.nf
|
||||
.Ha label anchor-text
|
||||
.fi
|
||||
.LP
|
||||
The label specified in a call to
|
||||
.B .Ha
|
||||
can then be used in calls to
|
||||
.BR ".Hr -symbolic" .
|
||||
All symbolic references must have been resolved at the end of the document.
|
||||
The \*(lqanchor-text\*(rq is placed between the tags <a> and </a>;
|
||||
\*(lqsuffix\*(rq is appended to the closing </a> if present.
|
||||
\*(lqtroff-text\*(rq is just formatted in the normal way.
|
||||
Quotes must be used if any of the arguments contains spaces.
|
||||
.LP
|
||||
Use of the hypertext facilities is demonstrated by the troff source
|
||||
of the Programmer's Manual that is included in the
|
||||
.I unroff
|
||||
distribution.
|
||||
.SH "SCHEME PROCEDURES"
|
||||
The following Scheme procedures, macros, and variables are defined
|
||||
by the HTML 2.0 back-end and can be used from within user-supplied
|
||||
Scheme code:
|
||||
.TP
|
||||
(\f2define-font name start-tag end-tag\fP)
|
||||
Associates a HTML start tag and end tag (symbols) with a troff
|
||||
font name (string) as explained under FONTS above.
|
||||
The font name can then be used in
|
||||
.BR .fp ,
|
||||
.BR .ft ,
|
||||
and `\ef' requests.
|
||||
.TP
|
||||
(\f2reset-font\fP)
|
||||
Resets both the current and previous font to the font mounted
|
||||
on position 1.
|
||||
.TP
|
||||
\f2current-font\fP
|
||||
.TP
|
||||
\f2previous-font\fP
|
||||
These variables hold the current and previous font as
|
||||
(integer) font positions.
|
||||
.TP
|
||||
(\f2with-font-preserved\fP . \f2body\fP)
|
||||
This macro can be used to temporarily change to font \*(lqR\*(rq,
|
||||
evaluate \f2body\fP, and revert to the font that has been
|
||||
active when the form was entered.
|
||||
The macro returns a string that can be output using the
|
||||
primitive \f2emit\fP or returned from an event procedure.
|
||||
.TP
|
||||
(\f2preform enable?\fP)
|
||||
If the argument is #t, pre-formatted text is enabled, otherwise disabled.
|
||||
.TP
|
||||
\f2preform?\fP
|
||||
This boolean variable holds #t if pre-formatted text is enabled,
|
||||
#f otherwise.
|
||||
.TP
|
||||
(\f2with-preform-preserved\fP . \f2body\fP)
|
||||
A macro that can be used to temporarily disable pre-formatted
|
||||
text, evaluate \f2body\fP, and then re-enable it if appropriate.
|
||||
The macro expands to a string that must be output or returned from
|
||||
an event procedure.
|
||||
.TP
|
||||
(\f2parse-unquote string\fP)
|
||||
Temporarily establishes an output translation to map the quote
|
||||
character to \*(lq"\*(rq, applies \f2parse\fP (explained
|
||||
in the Programmer's Manual) to its argument, and returns the result.
|
||||
.TP
|
||||
(\f2center n\fP)
|
||||
Centers the next \f2n\fP input lines (see description of
|
||||
.B .ce
|
||||
under TROFF REQUESTS above).
|
||||
If \f2n\fP is zero, centering is stopped.
|
||||
.TP
|
||||
\f2nbsp\fP
|
||||
A Scheme variable that holds a string interpreted as a non-breaking
|
||||
space by HTML clients.
|
||||
.SH "SEE ALSO"
|
||||
.BR unroff (1),
|
||||
.BR unroff-html-man (1),
|
||||
.BR unroff-html-ms (1);
|
||||
.br
|
||||
.BR troff (1),
|
||||
.BR nroff (1),
|
||||
.BR groff (1),
|
||||
.BR eqn (1),
|
||||
.BR tbl (1),
|
||||
.BR pic (1).
|
||||
.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 `\espace' escape sequence should be mapped to the   entity
|
||||
(non-breaking space), but this entity is not supported by a number
|
||||
of HTML clients.
|
||||
.LP
|
||||
Only the font positions 1 to 9 can currently be used.
|
||||
There should be no limit.
|
||||
.LP
|
||||
The extra space generated for end of sentence should be configurable.
|
||||
.LP
|
||||
Underlining should be supported.
|
||||
|
|
@ -0,0 +1,682 @@
|
|||
.\" $Revision: 1.16 $
|
||||
.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 1 "\*(Dt"
|
||||
.SH NAME
|
||||
unroff \- programmable, extensible troff translator
|
||||
.SH SYNOPSIS
|
||||
.B unroff
|
||||
[
|
||||
.BI \-f format
|
||||
] [
|
||||
.BI \-m package
|
||||
] [
|
||||
.BI \-h heapsize
|
||||
] [
|
||||
.B \-C
|
||||
]
|
||||
.if n .ti +0.5i
|
||||
[
|
||||
.B \-t
|
||||
] [
|
||||
.IR file " | " option...\&
|
||||
]
|
||||
.SH OVERVIEW
|
||||
.I unroff
|
||||
reads and parses documents with embedded troff markup
|
||||
and translates them to a different format\(emtypically
|
||||
to a different markup language such as SGML.
|
||||
The actual output format is not hard-wired into
|
||||
.IR unroff ;
|
||||
instead, the translation is performed by a set of user-supplied rules
|
||||
and functions written in the
|
||||
.I Scheme
|
||||
programming language.
|
||||
.I unroff
|
||||
employs the Extension Language Kit
|
||||
.I Elk
|
||||
to achieve programmability based on the Scheme language:
|
||||
a fully-functional Scheme interpreter is embedded in the translator.
|
||||
.LP
|
||||
The documents that can be processed by
|
||||
.I unroff
|
||||
are not restricted to a specific troff macro set.
|
||||
Translation rules for a new macro package can be added by supplying
|
||||
a set of corresponding Scheme procedures (a \*(lqback-end\*(rq).
|
||||
Predefined sets of such procedures exist for a number of combinations
|
||||
of target language and troff macro package:
|
||||
.I unroff
|
||||
\*(Ve supports translation to the \*(lqHypertext Markup Language\*(rq
|
||||
(HTML) version 2.0 for the
|
||||
.B \-man
|
||||
and
|
||||
.B \-ms
|
||||
macro packages as well as \*(lqbare\*(rq troff (see
|
||||
.BR unroff-html (1),
|
||||
.BR unroff-html-man (1),
|
||||
and
|
||||
.BR unroff-html-ms (1)
|
||||
for a description).
|
||||
.LP
|
||||
Unlike conventional troff conversion tools,
|
||||
.I unroff
|
||||
includes a full troff parser and can therefore handle user-defined
|
||||
macros, strings, and number registers, nested if-else requests
|
||||
(with text blocks enclosed by `\e{' and `\e}' escape sequences), arbitrary
|
||||
fonts and font positions, troff \*(lqcopy mode\*(rq, low-level formatting
|
||||
requests such as `\el' and '\eh', and the subtle
|
||||
differences between request and macro invocations that are inherent
|
||||
in the troff processing model.
|
||||
.I unroff
|
||||
has adopted a number of troff extensions introduced by
|
||||
.IR groff ,
|
||||
among them long names for macros, strings, number registers, and
|
||||
special characters, and the `\e$@' and `\e$*' escape sequences.
|
||||
.LP
|
||||
.I unroff
|
||||
interprets its input stream as a sequence of \*(lqevents\*(rq.
|
||||
Events include the invocation of a troff request or macro, the use of a
|
||||
troff escape sequence or special character, a troff string
|
||||
or number register reference, end of sentence, start
|
||||
of a new input file, and so on.
|
||||
For each event encountered
|
||||
.I unroff
|
||||
invokes a Scheme procedure associated with that event.
|
||||
Some types of events require a procedure that returns a string (or an
|
||||
object that can be coerced into a string),
|
||||
which is then interpolated into the input or output stream;
|
||||
for other types of events, the event procedures are just called
|
||||
for their side-effects.
|
||||
.LP
|
||||
The set of Scheme procedures to be used by
|
||||
.I unroff
|
||||
is determined by the output format and the name of the troff
|
||||
macro package.
|
||||
In addition, users can supply event procedures for their own macro
|
||||
definitions (or replace existing ones) in form of a simple Scheme
|
||||
program passed to
|
||||
.I unroff
|
||||
along with the troff input files; Scheme code can even be directly
|
||||
embedded in the troff input as described below.
|
||||
.LP
|
||||
The full capabilities of
|
||||
.IR unroff
|
||||
and the Scheme primitives required to write extensions or support
|
||||
for new output formats are described in the
|
||||
.IR "Unroff Programmer's Manual" .
|
||||
.SH "GENERIC OPTIONS"
|
||||
.TP
|
||||
.BI \-f format
|
||||
Specifies the output format into which the troff input files are
|
||||
translated.
|
||||
If no
|
||||
.B \-f
|
||||
option is given, a default output format is used (for
|
||||
.I unroff
|
||||
version \*(Ve the default is
|
||||
.B \-f\c
|
||||
.IR html ).
|
||||
This default can be overridden by setting the
|
||||
.SB UNROFF_FORMAT
|
||||
environment variable.
|
||||
.TP
|
||||
.BI \-m name
|
||||
Specifies the name of the macro package that would be used by ordinary
|
||||
troff to typeset the document.
|
||||
In contrast to troff
|
||||
.I unroff
|
||||
does not actually load the macro package.
|
||||
Instead, the specified name\-in combination with the specified output
|
||||
format\-selects a set of Scheme files providing the procedure definitions
|
||||
that control the translation process (see
|
||||
.B FILES
|
||||
below).
|
||||
Therefore a corresponding
|
||||
.B tmac
|
||||
file need not exist for a given
|
||||
.B \-m
|
||||
option.
|
||||
.TP
|
||||
.BI \-h heapsize
|
||||
This option can be used to specify a non-standard heap size (in Kbytes)
|
||||
for the Scheme interpreter included in
|
||||
.IR unroff ;
|
||||
see
|
||||
.BR elk (1).
|
||||
.TP
|
||||
.B \-C
|
||||
Enables troff compatibility mode.
|
||||
In compatibility mode certain
|
||||
.I groff
|
||||
extensions such as long names are not recognized.
|
||||
.TP
|
||||
.B \-t
|
||||
Enables test mode.
|
||||
Instead of processing troff input files,
|
||||
.I unroff
|
||||
enters an interactive Scheme top-level.
|
||||
This can be useful to interactively experiment with the Scheme
|
||||
primitives defined by
|
||||
.I unroff
|
||||
or to test or debug user-defined Scheme procedures.
|
||||
.SH "KEYWORD/VALUE OPTIONS"
|
||||
In addition to the generic options, a set of output-format-specific
|
||||
options can be set from the command line and from within troff and
|
||||
Scheme input files.
|
||||
When specified on the command line, these options have the form
|
||||
.Ex
|
||||
\f2option\fP=\f2value\fP
|
||||
.Ee
|
||||
where the format of
|
||||
.I value
|
||||
depends on the
|
||||
.I type
|
||||
of the option.
|
||||
For example, most output formats defines an option
|
||||
.B document
|
||||
whose value is used as a prefix for all output files created during
|
||||
the translation.
|
||||
The option is assigned a value by specifying a token such as
|
||||
.Ex
|
||||
document=thesis
|
||||
.Ee
|
||||
on the command line.
|
||||
This option's value is interpreted as a plain string, i.\|e.\&
|
||||
its type is
|
||||
.BR string .
|
||||
.LP
|
||||
The Scheme back-ends and user-supplied extensions can define their
|
||||
own option types, but at least the following types are recognized:
|
||||
.TP 10n
|
||||
.B integer
|
||||
the option value is composed of an optional sign and an (arbitrary)
|
||||
string of digits
|
||||
.TP 10n
|
||||
.B boolean
|
||||
the option value must either be the character 1 (true) or the
|
||||
character 0 (false)
|
||||
.TP 10n
|
||||
.B character
|
||||
a single character must be specified as the option value
|
||||
.TP 10n
|
||||
.B string
|
||||
an arbitrary string of characters can be specified
|
||||
.TP 10n
|
||||
.B dynstring
|
||||
\*(lqdynamic string\*(rq; the option value is either
|
||||
.RS
| ||||