186 lines
5.0 KiB
Groff
186 lines
5.0 KiB
Groff
.Dd October 7, 1995
|
|
.Os FreeBSD 2.1
|
|
.Dt SGMLFMT 1
|
|
.Sh NAME
|
|
.Nm sgmlfmt
|
|
.Nd Formats SGML files tagged according to the linuxdoc DTD.
|
|
.Sh SYNOPSIS
|
|
.Nm
|
|
.Fl f Ar format
|
|
.Op Fl links
|
|
.Op Fl ssi
|
|
.Op Fl i Ar name ...
|
|
.Ar file
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm
|
|
command reads SGML files tagged according to the linuxdoc DTD,
|
|
validates them using the
|
|
.Xr sgmls 1
|
|
parser and then converts them to the specified output format.
|
|
The input file 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 f Ar format
|
|
Determines the output format which can be one of the following:
|
|
.Bl -tag -width Ds
|
|
.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 latex
|
|
Generates a single output file with the extension
|
|
.Pa .tex
|
|
suitable for processing with LaTeX. Note that the LaTeX style
|
|
file
|
|
.Pa /usr/share/sgml/FreeBSD/lib/linuxdoc.sty
|
|
must be accessible to LaTeX for correct processing.
|
|
.It Ar ascii
|
|
Generates a single output file with the extension
|
|
.Pa .ascii
|
|
suitable for viewing on an ASCII terminal.
|
|
.It Ar nroff
|
|
Generates a single output file with the extension
|
|
.Pa .nroff
|
|
suitable processing with
|
|
.Xr nroff 1
|
|
or
|
|
.Xr groff 1 .
|
|
This is actually an intermediate conversion used by the
|
|
.Fl f Ar ascii
|
|
format option.
|
|
.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, for each
|
|
.Li <label id="foo">
|
|
in the document source
|
|
.Nm
|
|
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 ssi
|
|
When used with the
|
|
.Fl f Ar html
|
|
option, hooks will be placed to have an http server include a
|
|
custom header and footer on the document using the server side
|
|
include mechanism. This mechanism is supported by the Apache and
|
|
NCSA http servers and possibly others. Included files are named
|
|
.Pa file.hdr
|
|
and
|
|
.Pa file.ftr
|
|
for the header and footer of the
|
|
.Pa file.html .
|
|
Other pages include file are named
|
|
.Pa file.ftr1 ,
|
|
.Pa file.ftr2 ...
|
|
.Pa file.ftrn
|
|
where the number corresponds to the depth of the file from
|
|
.Pa file.html .
|
|
.El
|
|
.Pp
|
|
If the input file name ends with
|
|
.Pa .sgml ,
|
|
the extension may be omitted on the command line.
|
|
In all cases, the output files are created in the current working
|
|
directory.
|
|
.Sh FILES
|
|
.Pa /usr/share/sgml/FreeBSD/dtd/linuxdoc
|
|
- the linuxdoc DTD.
|
|
.Pp
|
|
.Pa /usr/share/sgml/FreeBSD/rep/
|
|
- directory containing replacement files for
|
|
.Xr sgmlsasp 1 .
|
|
.Pp
|
|
.Pa /usr/share/sgml/FreeBSD/lib/linuxdoc.sty
|
|
- the LaTeX style used in documents produced with the
|
|
.Fl latex
|
|
format option.
|
|
.Sh SEE ALSO
|
|
.Xr sgmls 1 ,
|
|
.Xr sgmlsasp 1 ,
|
|
.Xr groff 1
|
|
.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 .
|
|
.Sh BUGS
|
|
The ASCII output has many, many bugs including no meaningful
|
|
cross references, and numerous formatting problems.
|
|
.Pp
|
|
A line in the SGML source file beginning with a period (.) will
|
|
confuse
|
|
.Xr groff 1
|
|
which is used to generate ASCII output.
|
|
.Pp
|
|
The division of the sources file into separate HTML files is
|
|
currently fixed.
|
|
.Pp
|
|
Although legal according to the DTD, it the ascii formatting gets botched if
|
|
the
|
|
.Li <heading>
|
|
.No ...
|
|
.Li </heading>
|
|
tags are omitted following a
|
|
sectioning tag such as
|
|
.Li <sect> .
|
|
.Pp
|
|
Beginning and ending tags for the
|
|
.Li <tag>
|
|
element must occur on the same line for correct formatting with
|
|
the
|
|
.Fl ascii
|
|
option.
|