SUPPE(1)

NAME
suppe - SGML UnPretty Printer (Experimental)

SYNOPSIS
suppe [- -indent count] [- -linecount offset] [- -maxlinelength count]

DESCRIPTION
Chapter 10 of the “ FreeBSD Documentation Projekt Primer for New Contributors ” defines a set of guidelines for the formatting and indentation of documents written for the FreeBSD Documentation Projekt. It is easy to follow these rules while writing a new document, especially with the “sgml-mode” of emacs(1) and the scripts and settings for vim(1) that can be found in doc/share/examples/vim. Fixing the formatting and indentation of a large existing document, however, is another matter.

The suppe utility was written to reduce the amount of mindless labor involved in this process. It rebuilds the formatting and indentation of an SGML document in accordance with the style guidelines outlined in Chapter 10 of FDP Primer.

The following arguments are supported by suppe:

- -indent count
    Start with indentation set at column count instead of 0. Use this option to format a section of a document (like a single entry for the FAQ).

- -linecount offset
    Start the counter for the number of lines in the output with linecount instead of 0. Use this option while fixing a section of a document to get more useful (i.e. document-relative instead of section-relative) line numbers in the error or warning messages.

- -maxlinelength count
    Maximum length of a line in the output.

The arguments obey the usual rules of the Getopt::Long(3) package:
•   The second dash is optional.
•   Argument names can be abbreviated to uniquess, i.e. (-i, -l, -m).
•   Arguments can specified more than once, the option value of the later argument prevails.

Unformatted input is read from the stdin, the formatted output is written to the stdout, warning and error messages are written to the stderr.

  Basic Concepts
The starting point for the development of suppe was the reformatting of a 300 KByte document that violated almost every formatting and indentation guideline outlined in the FDP primer. The basic concept of suppe was shaped by this starting point: suppe does not attempt to “fix” the formatting and intendation instructions (spaces, tabs, and newlines), suppe removes them completly and reformats the document. There are three exceptions to this rule:

•   The FPI is not modified by suppe

•   Whitespace and or linebreaks are significant inside multi-line SGML comments and several special entities (e.g., <programlisting>). These sections of the input stream (“protblocks” in suppe-speak) will keep the original formatting instructions.

•   A full stop followed by two (or more) spaces or a newline is treated as the end of a sentence. This attribute will be conserved in the output.
The formatting engine in suppe is a combination of a rather braindead lex-like scanner, a minimal state machine, and a line-filling algorithm. Input is parsed into chunks; each chunks contains either a complete SGML tag, a complete SMGL comment, or character data. An SGML tag has two attributes: It is either an opening or a closing tag and it belongs to one of these three classes:
“single”
    A tag that cannot have any kind of content.
“normal”
    A tag for an element that cannot contain character data by itself
“inline”
    A tag for an element that can contain character data
The basis for the classification are three lists of tags that are probably incomplete. An unknown tag causes a fatal error, the remaining unformatted input is sent to stdout and the program aborts. A closing “single” tag is evidence of a false entry within the lists of tags and causes a fatal error.

Every opening “normal” or “inline” tag increases the current indentation level by two and every closing “normal” or “inline” tag decreases the current indentation level by two. “Normal” tags are printed immediately and on a seperate line. “Single” tags, “inline” tags, character data and SGML comments are joined to form complete SGML entities. The entity is passed to the line-filling algorithm when it is complete or if a “normal” tag is encountered. Precious areas outside inline elements are restored and printed immediately. Precious areas inside inline elements are restored and printed by the line-filling algorithm. In both cases, the opening tag is always set at column 0.

DIAGNOSTICS
All error messages are sent to the standard error. You should capture them in a seperate file

  Could not find the opening <tag>
If the document contains something remotly resembling a DOCTYPE declaration, suppe will parse it to get the type of document. If cannot find an opening tag matchting the document type, it will print this message and abort.

  Hey, inline protblock at XXX
This warning message is sent if suppe detects a precious entity inside an inline element. This usual cause is a <programlisting> element inside a <para>. This causes tidy(1) to issue a warning message because it has to insert <Br> tags into the HTML source. And that is the reason why suppe suppe complains about these constructs, too. Suggested course of action: Move the precious entity out of the inline element.

  Whoa, character data outside inline element in XXX

  Whoa, character data before normal tag in XXX
These messages indicate that there is something seriously wrong with the document. In both cases, character data was found outside an inline element. The only difference is the type of tag that follows. The character data will be formatted like a legal inline element, but an in-depth check of the resulting SGML is a good idea.

  Hey, normal tag XXX inside inline element in XXX
This is a variation of the “inline protblock” warning message. The suggestion course of action is to fix the source and close the “inline” element before this tag.

  Hey, XXX closed with </>
It is possible to close the ‘last tag’ by simple using </> instead of </foo>. This is considered bad style and a guideline to that effect will be included in the FDP primer. The safest course of action is to pipe the source through slashexpand(1) before you use suppe on this source. The formatting engine contains a minimal fix for this problem which should result in correct formatting. The stack-based correcting engine of slashexpand(1) WILL fix the problem at the source.

The suppe utility exits 0 on success, and >0 if a unrecoverable error occurs.

COMPATIBILITY
The formatting and indentation should follow guidelines given in Chapter 10 of the FreeBSD Documentation Projekt Primer for New Contributor.

SEE ALSO
emacs(1), perl(1), slashexpand(1), tidy(1), vim(1), Getopt::Long(3)

HISTORY
The first version of the suppe utility was written in July 2000.

AUTHORS
The suppe utility and this manual page were written by Udo Erdelhoff <ue@nathan.ruhr.de>.

BUGS
Complex enough to guarantee the existence of some bugs. The program name contains two of them, this is not a generic SGML formatting tool, but a rather restricted one. And everybody who was subjected to the end result of a “dump” caused by an unknown tag knows why this program has this name. It is neccessary to modify the source code of suppe to add additional tags. This will change in a later version.