dc3fa61ed3
creating a symbolic link from foo.html (from <label name="foo">) to the numbered file, a shell script is built that can be used to make the links at a later time (read: after installation in the target directory).
179 lines
5.0 KiB
Groff
179 lines
5.0 KiB
Groff
.Dd September 9, 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 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 latex
|
|
Generates a single output file with the extension
|
|
.Pa .latex
|
|
suitable for processing with LaTeX. Note that the LaTeX style
|
|
file
|
|
.Pa /usr/share/sgml/FreeBSD/linuxdoc.sty
|
|
must be accessible to LaTeX for correct processing.
|
|
.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 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/linuxdoc.dtd
|
|
- the linuxdoc DTD.
|
|
.Pp
|
|
.Pa /usr/share/sgml/transpec
|
|
- directory containing translation specification files for
|
|
.Xr instant 1 .
|
|
.Pp
|
|
.Pa /usr/share/sgml/FreeBSD/linuxdoc.sty
|
|
- the LaTeX style used in documents produced with the
|
|
.Fl f Ar latex
|
|
format option.
|
|
.Sh SEE ALSO
|
|
.Xr sgmls 1 ,
|
|
.Xr instant 1 ,
|
|
.Xr transpec 5 ,
|
|
.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 .
|