SGMLFMT(1)

NAME
sgmlfmt - Formats SGML files tagged according to the linuxdoc DTD.

SYNOPSIS
sgmlfmt -f format [-links] [-ssi] [-i name ...] file

DESCRIPTION
The sgmlfmt command reads SGML files tagged according to the linuxdoc DTD, validates them using the 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:

    <!DOCTYPE linuxdoc PUBLIC "-//FreeBSD//DTD linuxdoc//EN">

sgmlfmt include the following:

-f format
    Determines the output format which can be one of the following:

    html
        Generates a set of linked HTML files suitable for use with an HTML browser. A top level file, file.html, contains the title, author, date, abstract and brief table of contents for the document. A file file_toc.html contains a complete table of contents. A series of files named file1.html, file2.html ... filen.html contain the actual text of the document.

    latex
        Generates a single output file with the extension .tex suitable for processing with LaTeX. Note that the LaTeX style file /usr/share/sgml/FreeBSD/lib/linuxdoc.sty must be accessible to LaTeX for correct processing.

    ascii
        Generates a single output file with the extension .ascii suitable for viewing on an ASCII terminal.

    nroff
        Generates a single output file with the extension .nroff suitable processing with nroff(1) or groff(1). This is actually an intermediate conversion used by the -f ascii format option.

-i name
    Pretend that
        <!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 -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
        <!ENTITY % name IGNORE >
    and will use %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.

-links
    When used with the -f html option, for each <label id="foo"> in the document source sgmlfmt generates a symbolic link foo.html pointing to the numbered .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 (_).

-ssi
    When used with the -f 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 file.hdr and file.ftr for the header and footer of the file.html. Other pages include file are named file.ftr1, file.ftr2 ... file.ftrn where the number corresponds to the depth of the file from file.html.

If the input file name ends with .sgml, the extension may be omitted on the command line. In all cases, the output files are created in the current working directory.

FILES
/usr/share/sgml/FreeBSD/dtd/linuxdoc - the linuxdoc DTD.

/usr/share/sgml/FreeBSD/rep/ - directory containing replacement files for sgmlsasp(1).

/usr/share/sgml/FreeBSD/lib/linuxdoc.sty - the LaTeX style used in documents produced with the -latex format option.

SEE ALSO
sgmls(1), sgmlsasp(1), groff(1)

HISTORY
The sgmlfmt command appeared in Version 2.0.5 FreeBSD UNIX.

AUTHORS
The sgmlfmt command was written by John Fieber <jfieber@FreeBSD.org>. The linuxdoc DTD was written by Matt Welsh <mdw@cs.cornell.edu> and based on the Qwertz DTD written by Tom Gordon <thomas.gordon@gmd.de>.

BUGS
The ASCII output has many, many bugs including no meaningful cross references, and numerous formatting problems.

A line in the SGML source file beginning with a period (.) will confuse groff(1) which is used to generate ASCII output.

The division of the sources file into separate HTML files is currently fixed.

Although legal according to the DTD, it the ascii formatting gets botched if the <heading> ... </heading> tags are omitted following a sectioning tag such as <sect>.

Beginning and ending tags for the <tag> element must occur on the same line for correct formatting with the -ascii option.