173 lines
4.7 KiB
Groff
173 lines
4.7 KiB
Groff
.Dd May 9, 1997
|
|
.Os FreeBSD 2.2
|
|
.Dt SGMLFMT 1
|
|
.Sh NAME
|
|
.Nm sgmlfmt
|
|
.Nd Formats linuxdoc and DocBook SGML documents.
|
|
.Sh SYNOPSIS
|
|
.Nm
|
|
.Op Fl d Ar doctype
|
|
.Fl f Ar format
|
|
.Op Fl i Ar name ...
|
|
.Op Fl links
|
|
.Op Fl e Ar encoding
|
|
.Op Fl hdr Ar file
|
|
.Op Fl ftr Ar file
|
|
.Ar file
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm
|
|
command reads SGML files tagged according to the linuxdoc or
|
|
DocBook DTD,
|
|
validates them using the
|
|
.Xr sgmls 1
|
|
parser and then converts them to the specified output format.
|
|
Linuxdoc input files must include the following document type
|
|
declaration before any uncommented text:
|
|
.Bd -literal -offset indent
|
|
<!DOCTYPE linuxdoc PUBLIC "-//FreeBSD//DTD linuxdoc//EN">
|
|
.Ed
|
|
.Pp
|
|
Options for
|
|
.Nm
|
|
include the following:
|
|
.Bl -tag -width Ds
|
|
.It Fl d Ar doctype
|
|
Specifies the SGML document type of the source file. Currently
|
|
supported document types are
|
|
.Ar linuxdoc
|
|
and
|
|
.Ar docbook .
|
|
If no
|
|
.Fl d
|
|
option is specified, the default is
|
|
.Ar linuxdoc .
|
|
.It Fl f Ar format
|
|
Determines the output format which can be one of the following:
|
|
.Bl -tag -width Ds
|
|
.It Ar ascii
|
|
Generates a single output file with the extension
|
|
.Pa .ascii
|
|
suitable for viewing on an ASCII terminal.
|
|
.It Ar html
|
|
Generates a set of linked HTML files suitable for use with an
|
|
HTML browser. A top level file,
|
|
.Pa file.html ,
|
|
contains the title, author, date, abstract and brief table of
|
|
contents for the document. A file
|
|
.Pa file_toc.html
|
|
contains a complete table of contents. A series of files named
|
|
.Pa file1.html ,
|
|
.Pa file2.html ...
|
|
.Pa filen.html
|
|
contain the actual text of the document.
|
|
.It Ar koi8-r
|
|
Generates a single output file with the extension
|
|
.Pa .koi8-r
|
|
suitable for viewing on an terminal supporting the KOI8-R
|
|
character encoding.
|
|
.It Ar latin1
|
|
Generates a single output file with the extension
|
|
.Pa .latin1
|
|
suitable for viewing on an terminal supporting the ISO8859-1
|
|
character encoding.
|
|
.It Ar ps
|
|
Generates a single output file with the extension
|
|
.Pa .ps
|
|
suitable for printing or display on a PostScript compatible device.
|
|
.It Ar roff
|
|
Generates a single output file with the extension
|
|
.Pa .roff
|
|
suitable processing with
|
|
.Xr groff 1 .
|
|
This is actually an intermediate conversion used by the
|
|
.Fl f Ar ascii ,
|
|
.Fl f Ar latin1 ,
|
|
.Fl f Ar koi8-r ,
|
|
and
|
|
.Fl f Ar ps
|
|
format options.
|
|
.El
|
|
.It Fl i Ar name
|
|
Pretend that
|
|
.Dl <!ENTITY % name "INCLUDE">
|
|
occurs at the start of the document type declaration subset in
|
|
the document entity. Since repeated definitions of an entity are
|
|
ignored, this definition will take precedence over any other
|
|
definitions of this entity in the document type declaration.
|
|
Multiple
|
|
.Fl i
|
|
options are allowed. If the declaration replaces the reserved
|
|
name INCLUDE then the new reserved name will be the replacement
|
|
text of the entity. Typically the document type declaration will
|
|
contain
|
|
.Dl <!ENTITY % name "IGNORE">
|
|
and will use
|
|
.Li %name;
|
|
in the status keyword specification of a
|
|
marked section declaration. In this case the effect of the
|
|
option will be to cause the marked section not to be ignored.
|
|
.It Fl links
|
|
When used with the
|
|
.Fl f Ar html
|
|
option, this option generates a shell script named
|
|
.Pa file.ln .
|
|
For each
|
|
.Li <label id="foo">
|
|
in the document source,
|
|
.Pa file.ln
|
|
generates a symbolic link
|
|
.Pa foo.html
|
|
pointing to the numbered
|
|
.Pa .html
|
|
file containing the reference. Since the number of the file
|
|
containing a particular section can change when a document
|
|
is modified, this provides a convenient hook by which separate
|
|
documents can provide links into another document without the
|
|
links becoming invalid when the target document is modified.
|
|
When creating a symbolic link, any occurrence of a slash (/) in label
|
|
is replaced with percent (%), while any occurrence of a space is replaced
|
|
with an underscore (_).
|
|
.It Fl e Ar encoding
|
|
When used with the
|
|
.Fl f Ar html
|
|
option, specifies document encoding to use for the generated
|
|
HTML files. If this option is not specified, iso-8859-1 is used.
|
|
.It Fl hdr Ar file
|
|
When used with the
|
|
.Fl f Ar html
|
|
option, the specified file will be inserted at the beginning of the
|
|
body element of each generated HTML file.
|
|
.It Fl ftr Ar file
|
|
When used with the
|
|
.Fl f Ar html
|
|
option, the specified file will be inserted at the end of the
|
|
body element of each generated HTML file.
|
|
.El
|
|
.Pp
|
|
In all cases, the output files are created in the current working
|
|
directory.
|
|
.Sh FILES
|
|
.Pa /usr/share/sgml/transpec
|
|
- directory containing translation specification files for
|
|
.Xr instant 1 .
|
|
.Pp
|
|
.Sh SEE ALSO
|
|
.Xr groff 1 ,
|
|
.Xr instant 1 ,
|
|
.Xr sgmls 1 ,
|
|
.Xr transpec 5
|
|
.Sh HISTORY
|
|
The
|
|
.Nm
|
|
command appeared in Version 2.0.5 FreeBSD UNIX.
|
|
.Sh AUTHORS
|
|
The
|
|
.Nm
|
|
command was written by John Fieber
|
|
.Aq jfieber@FreeBSD.org .
|
|
The linuxdoc DTD was written by Matt Welsh
|
|
.Aq mdw@cs.cornell.edu
|
|
and based on the Qwertz DTD written by Tom Gordon
|
|
.Aq thomas.gordon@gmd.de .
|