NAME

SYNOPSIS

DESCRIPTION

When its input is just a plain text file in the ASCII or ISO 8859-1 character sets, a major part of the conversion of text to grammatically-correct HTML can be done automatically, especially if the -convert-paragraph-breaks option is used. Section headings, verbatim, and tabular material will, however, require manual editing.

HTML (HyperText Markup Language) is the language used to specify formatting instructions in text files intended for viewing with World-Wide Web (WWW) client programs (browsers), such as amaya(1), arena(1), chimera(1), grail(1), hotjava(1), jde(1), lynx(1), netscape(1), panorama(1), and xmosaic(1).

The WWW idea began in late 1992, and because viewer programs support display of text, line drawings, color raster images, hypertext links, and uniform access to several Internet services, including file transfer, in the first two years, the number of WWW servers grew from zero to several hundred thousand, and some of the more popular sites receive up to twenty-five million accesses a day from all over the Internet. Consequently, many Internet computer users are beginning to write HTML documents for their own home pages, and html-pretty is written for them.

The goal of a prettyprinter is to recognize all legal inputs, and produce output that is indented to reflect the structure, and in which line lengths have been restricted for improved readability. Irregularities in coding practice, and outright errors, are more likely to be detected in the prettyprinted output, than in the input.

SGML (Standard General Markup Language, ISO 8879), and its particular document type definition instance, HTML, follow a rigorous grammar for text markup that makes it possible to clearly identify document parts, such as headings, sections, subsections, paragraphs, figures, tables, equations, and so on, and files with such standardized markup are particularly good candidates for prettyprinting.

The definition of HTML is still evolving. Version 2.0 (Fall 1994) is implemented by almost all browsers. Version 3.0, informally called HTML Plus, was introduced in March, 1995, and the arena(1) browser was developed at the World-Wide Web Consortium, W3C, to serve as a testbed for it.

Although Version 3.0 is a superset of version 2.0, it proved too difficult for browser implementors to incorporate support for it in a reasonable time, and it was withdrawn in Fall, 1996. Version 3.2 was released on 14 January 1997, but despite its higher version number, it lacks many of the new features introduced in version 3.0, notably for mathematical markup, but importantly, it does include support for figures and tables. As with version 3.0, there is also a testbed browser, this time called amaya(1), and augmented with the ability to edit HTML files, providing a (simple-minded) WYSIWYG editor interface that some users may find convenient for creating and maintaining HTML files.

At the time of writing in Fall, 1997, only the amaya(1) and netscape(1) browsers appear to have implemented all, or most, of HTML 3.2.

Further information about HTML versions 3.0 and 3.2 can be found on the World-Wide Web at the Uniform Resource Locators (URLs)

http://www.w3.org/MarkUp/Wilbur/
http://www.w3.org/TR/REC-html32.html

The next version of HTML, code-named Cougar, is under development, and will become version 4.0 when it is finally released. The first draft public release was on 8 July 1997, and a second proposed recommendation followed on 7 November 1997. For details, visit URLs

http://www.w3.org/MarkUp/Cougar/
http://www.w3.org/TR/WD-html40/
http://www.w3.org/TR/PR-html40/

Interestingly, translations of the version 4.0 specification to at least 18 other human languages are in progress: see URLs

http://www.w3.org/TR/WD-html40/translations.html
http://www.w3.org/TR/PR-html40-971107/translations.html

html-pretty recognizes all HTML tags in the grammars of versions 1.0, 2.0, 3.0, 3.2, and proposed 4.0, plus a few vendor-specific extensions.

One significant difference between the grammar versions is that the HTML tag <P> is a paragraph separator in version 2.0, while it is a paragraph begin in later versions, and consequently expects to have a matching </P> paragraph end tag that is not required in 2.0. html-pretty will supply missing </P> tags, and delete empty <P> ... </P> environments. Since HTML translators ignore unknown tags, this is transparent to HTML version 2.0 implementations, and causes no problems.

html-pretty expects that its input is reasonably well-formed. Usually it is sufficient that the file can be displayed by one or more WWW browsers, producing the expected form. However, it would be unwise to write a large amount of program code without a compiler to check it, and it is similarly unwise to write documentation in HTML or SGML without at least a validating parser to ensure that the text is syntactically correct.

Fortunately, at least two such programs are publicly available (thanks to the generosity of their author, James Clark), nsgmls(1) and sgmls(1), together with UNIX shell scripts, html-check(1) and html-ncheck(1), to facilitate their use with HTML files. In addition, the nsgmls(1) distribution is accompanied by two SGML tag normalizers, sgmlnorm(1) and spam(1), and there is a UNIX shell script, html-spam(1), for one of them. You may therefore find it useful to apply html-spam(1), and either html-check(1) or html-ncheck(1), to your HTML files, and fix all of the errors that they detect, before filtering the files with html-pretty.

HTML strictly requires a certain amount of boiler-plate to be wrapped around the text, and there is ample evidence that most HTML files omit these wrappers, because WWW browsers are written to be tolerant of grammatical deviations. html-pretty will supply the wrappers if they are omitted; indeed, if given an empty input file, html-pretty produces output similar to this:

<!-- -*-html-*- -->
<!-- Prettyprinted by html-pretty flex version 1.00 [11-Nov-1997] -->
<!-- on Tue Nov 11 16:23:39 1997 -->
<!-- for Nelson H. F. Beebe (beebe@plot79.math.utah.edu) -->
<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
<HTML>
    <HEAD>
        <TITLE>
            <!-- Please supply a descriptive title here -->
        </TITLE>
        <!-- Please supply a correct e-mail address here -->
        <LINK REV="made" HREF="mailto:beebe@plot79.math.utah.edu">
    </HEAD>
    <BODY>
    </BODY>
</HTML>

This example, minus the comments <!-- ... -->, shows the minimal markup that should be expected in an HTML file, although the grammar permits the HTML, HEAD and BODY environments to be implicitly assumed if they are omitted. While most WWW browsers ignore the DOCTYPE declaration, it is essential for SGML parsers, since it identifies the grammar rules that apply to what follows. Two recent WWW browsers, amaya(1) and panorama(1), are SGML-grammar based, and may require a valid DOCTYPE declaration.

OPTIONS

Any argument that begins with a hyphen is expected to be an option, and will raise an error if it is not recognized. If a filename begins with a hyphen, you therefore need to disguise it by supplying a leading directory path. For example, ./-foo represents the file named -foo in the current directory in UNIX.

GNU- and POSIX-style options of the form --name are also recognized: they begin with two option prefix characters.

For every option -xxx that sets a Boolean flag to be acted upon later, there is a corresponding -no-xxx option to override it. The negative forms are normally not required, but are necessary to counteract options set in a style file.

-author

Show author information on stderr and quit after processing any remaining command-line options that precede the next command-line HTML file.

-blank-line-warning

Unlike most word processing and typesetting systems, and ordinary typewritten text, in HTML and SGML, blank lines do not imply a paragraph break, except in verbatim environments. You can select this option to get warnings about such blank lines. They will be reduced to a single blank line, leaving space for later manual insertion of a <P> tag, if that was indeed what was intended [default: -no-blank-line-warning].

If you specify the -convert-paragraph-breaks option, then this option will have no effect.

-brief

Brief mode: exclude the standard boiler-plate wrapper of !DOCTYPE, HTML, HEAD, and BODY tags [default: -no-brief].

This option, in conjunction with -no-comment-banner, is convenient for prettyprinting small fragments of text, such as from inside a text editor. It can also be used for portions of larger documents (e.g., chapters of a book) that are not in themselves complete HTML files.

This option can be abbreviated to -b.

-catalogfile filename

Specify an alternate catalog file to override the default one. See the CATALOG DIRECTORY section for more details.

This option can be abbreviated to -c.

-check-tag-nesting

Use built-in tables, or tables from style files, of tag-is-contained-in and tag-cannot-contain relations to check that tags are properly nested. The rules that govern this are very complex, and depend on the grammar level chosen. The precise relations are tabulated in the HTML GRAMMAR CONSTRAINTS section, and the way they are provided to html-pretty is described in the STYLE FILES section.

Because this option can lead to a large number of warning messages when optional end tags are omitted, the default is -no-check-tag-nesting.

Nevertheless, when a proper SGML parser, such as html-check(1) or html-ncheck(1), is not available, this option can be very helpful in diagnosing errors of tag usage.

-comment-banner

Generate a leading comment banner containing the prettyprinter version number and date, the current date and time, and the personal name and email address of the user who ran the prettyprinter [default: -comment-banner].

-convert-paragraph-breaks

Convert paragraph breaks (sequences of one or more blank or empty lines) to HTML <P> tags [default: -no-convert-paragraph-breaks].

This option is intended for converting text files to HTML; it should not be used when the input file is already HTML, unless the intent really is to insert explicit paragraph tags.

This option has no effect on blank lines inside verbatim environments.

-copyright

-copyleft

Show copyright information on stderr and quit after processing any remaining command-line options that precede the next command-line HTML file.

-email-address user@hostname

Supply an alternate electronic mail address to be used in the comment banner and the LINK tag. Otherwise, a default address is constructed from the current user name and host name, when that information is available from the operating system.

This option may also be spelled -e-mail-address, since both e-mail and email are about equally common abbreviations on the World-Wide Web.

-extend-style 'style: TAG TAG ...'

-extend-style 'TAG: TAG TAG ...'

These options, whose name can be abbreviated to just -e, provide a quick command-line alternative to the style file feature of the -stylefile option. They permit you to augment the list of tags associated with a particular formatting style class, or to add a list of tags to the same class as an existing tag (to avoid the need to know the style class names), but only for the duration of the current process.

Since a tag can belong to only a single style class at one time, specification of existing tags with these options effectively removes their old style class association.

html-pretty distinguishes between the two cases by looking up the first name in its tag table. If it is entirely in uppercase, then it might be found there. Otherwise, it is a style class name.

If the style class is not recognized, an error message is issued with a list of the recognized class names, and execution is terminated after processing any remaining command-line options that precede the next command-line HTML file. Thus, an option -extend-style foo:bar' or -extend-style help=me' with obviously incorrect class and tag names can be used to coax a list of the valid ones from html-pretty; it will respond with something like this:

:1:unknown style [foo] command [BAR] at line 0
in style source [command-line]
The recognized style classes are:
        body doctype font head html
        line-break link list list-header
        list-item markup-declaration math
        math-pair pair paragraph plaintext
        public section short standalone
        standalone-nocheck title verbatim

The output line width in this list is governed by the -width option.

You can assign tags to the special style class name default to make them unknown (and also, warned about, if you supply the -unknown-tag-warning option), e.g., default:blink.

Because some operating systems do not allow embedded spaces in command-line arguments, you can separate the tags in the value string with a comma instead of whitespace. Also, you can use an equals sign instead of a colon after the first word. For example, the value strings

font:A,MEDIUM
font=A,MEDIUM
'font   =   A    MEDIUM'
'font :     A,,,,MEDIUM'

all assign tags A and MEDIUM to the font style class. Incidentally, some people prefer A (anchor) tag pairs to be treated this way, rather than their default of being placed on separate lines, even though long hypertext references in <A HREF="..."> make this style hard to read.

For more information on this topic, see the STYLE FILES section below.

-file filename

Supply an alternate input filename for use in the output comment banner. This overrides the actual filename(s), and provides a way to name the output, even when no named input file is available, because standard input is redirected, or comes from a pipe.

-grammar-level grammar

Select a grammar level that in turn will select a suitable style file. See the CATALOG DIRECTORY and STYLE FILES sections for more details.

Lettercase is not significant in grammar-level names.

You can use this option, together with the -unknown-tag-warning option, to help detect use of HTML tags that are not part of the grammar. However, a better, and grammatically rigorous, way to do this is to use a validating SGML parser, such as those accessible via the html-check(1) and html-ncheck(1) scripts.

The built-in default grammar level is a union of the HTML grammar levels 1.0, 2.0, 3.0, 3.2, and proposed 4.0, plus selected browser-vendor extensions.

A properly-installed html-pretty always supports at least grammar levels 1.0, 2.0, 3.0, 3.2, 4.0, plus one named all which contains a union of all of the grammar styles in the catalog directory. This will be similar to the built-in default style, but may differ from it in minor details, since it is easier to augment the style file than it is to rebuild and reinstall the software.

There is also a `grammar level' named dtd; it augments the normal style rules with additional ones for extra declarations and tags found in SGML and HTML Document Type Definition (DTD) files.

If you specify an incorrect grammar level, html-pretty will display a message showing the available levels, and then quit:

html-pretty -g foo
:1:could not find grammar level [foo] in
catalog file [/usr/local/share/lib/html-pretty/catalog]:
    levels available:  all dtd 2 2.0 3 3.0 3.2 4 4.0

If the style file has a public style class entry, the output DOCTYPE declaration will use its value, instead of a built-in default; see the STYLE FILES section below for details.

Tip: if you want to find out the differences in the sets of HTML tags accepted by two different grammar versions, use this option with the -print-stylefile and -width options like this:

html-pretty -w 0 -g 3.2 -p >foo.3.2
html-pretty -w 0 -g 4.0 -p >foo.4.0
diff foo.3.2 foo.4.0

The difference listing will show just those style classes where the tag lists differ, since each class will be complete on one (possibly long) line.

-help or -?

Display brief usage information on stderr and quit after processing any remaining command-line options that precede the next command-line HTML file.

-indent nnn

Set the number of spaces for each indentation level [default: 4].

-keep-format

Treat the input stream as verbatim text whose visual format is to be exactly preserved. It will be converted to the body of a preformatted HTML environment, <PRE> ... </PRE>, and all characters will be output unchanged, except for the four characters `<', `>', `&', and `"', which will be translated to SGML entities `&lt;', `&gt;', `&amp;', and either `&quot;' or `&34;' (depending on the grammar level), respectively.

This option is useful for converting non-HTML text to HTML when the linebreaking and indentation are already decided, such as preformatted tables, samples of computer program input and output, and programming language fragments.

Horizontal tab characters are treated like spaces in HTML, but most Web browsers will display text containing tabs as if each tab caused blank fill up to, and including, the next column which is a multiple of eight, which is the conventional behavior on many systems. The visual appearance is correct if the text is displayed with a fixed-width font, but is usually wrong with a proportionally-spaced font.

However, when asked to save the file as plain text, some browsers will save text with tabs, and others will save text with tabs expanded to spaces, thereby preserving the original appearance. When the same text is cut with the mouse and pasted into another window, some browsers preserve tabs, and others convert it to spaces. And even more confusingly, a browser that converts tabs to spaces in a saved file may leave tabs intact in cut-and-pasted text!

In most cases, tabs are not significant, but they are for UNIX Makefiles, so if your text has significant tabs, you should incorporate a warning that they will likely be destroyed by the Web browser, and will need to be restored manually, or with a pass through a filter such as unexpand(1).

html-pretty always treats tabs as ordinary characters, but if you want to be sure of correct display of tabs according to the conventional blank-fill rule, you should filter the input to html-pretty using a tab expander such as expand(1).

For Fortran code containing tab characters, the meaning of tabs is context sensitive, and you need to use a Fortran-tab aware converter. There is no standard UNIX utility to do this, although a local emacs(1) editor function M-x detab-fortran will do the job.

-logfile filename

Redirect warning and error messages from stderr to the indicated filename. This option is provided for user convenience on poorly-designed operating systems (e.g., IBM PC DOS) that fail to provide for redirection of stderr to a specified file.

This option can also be used for discarding messages, with, e.g., on UNIX systems, -logfile /dev/null.

If the file cannot be opened for output, html-pretty will terminate silently with a non-zero exit code, because the internal attempted redirection required the closure of stderr, making it unavailable for printing further error messages.

-no-blank-line-warning

Override an earlier -blank-line-warning option. Unlike most word processing and typesetting systems, and ordinary typewritten text, in HTML and SGML, blank lines do not imply a paragraph break, except in verbatim environments. html-pretty will therefore normally silently reduce such blank lines to a single space [default: -no-blank-line-warning].

If you specify the -convert-paragraph-breaks option, then this option will have no effect.

-no-brief

Override an earlier -brief option, so that the standard wrapper !DOCTYPE, HTML, HEAD, and BODY tags are generated [default: -no-brief].

-no-check-tag-nesting

Suppress checks for correct tag nesting [default: -no-check-tag-nesting].

-no-comment-banner

Suppress generation of the default leading comment banner.

This option can be abbreviated to -n, since it may be used frequently [default: -comment-banner].

-no-convert-paragraph-breaks

Do not convert paragraph breaks (sequences of one or more blank or empty lines) to HTML <P> tags [default: -no-convert-paragraph-breaks]. Instead, unless the -blank-line-warning option has been given, the empty lines will be reduced to a single space.

-no-keep-format

Override an earlier -keep-format option, and thus permit reformatting of the input stream [default: -no-keep-format ].

-no-print-stylefile

Override an earlier -print-stylefile option, and therefore, do not terminate execution before processing style files [default: -no-print-stylefile].

-no-quiet

Override an earlier -quiet option, to restore output of warning messages on stderr [default: -no-quiet].

-no-read-stylefiles

Suppress reading of the three default style files (see the STYLE FILES section below) [default: -read-stylefiles].

Style files implicitly specified with -grammar-level options, or explicitly specified with -stylefile options, will still be processed.

-no-trace-opens

Override an earlier -trace-opens option, so that file opening attempts are not traced on stderr [default: -no-trace-opens].

-no-unknown-tag-warning

Override an earlier -unknown-tag-warning option, so that unknown HTML tags will not elicit a warning message [default: -no-unknown-tag-warning].

-no-warnings-in-comments

Override an earlier -warnings-in-comments option, so that warning and error messages are written only to stderr (which might have been redirected with the -logfile option) [default: -no-warnings-in-comments].

-outfile filename

Redirect output from stdout to the indicated filename. This option is provided for user convenience on operating systems that fail to provide for redirection of stdout to a specified file.

-personal-name name

Supply an alternate personal name string to be used in the comment banner. Normally, the personal name is determined via the current user name, when that information is available from the operating system.

-print-stylefile

Print a style file on stdout and quit after processing any remaining command-line options that precede the next command-line HTML file.

This option can be abbreviated to -p.

The output line width in the style file is governed by the -width option described later.

Startup option files, and any preceding -extend-style, -grammar-level, and -stylefile options will already have been processed, and their changes will be reflected in the output produced by this option.

Use this option to find out how each recognized tag is processed, and also to get a template style file that you can customize. The style class names and tag lists are ordered alphabetically for improved readability. For more details, see the STYLE FILES section below.

-quiet

Suppress output of warning messages on stderr. Error messages will, however, not be suppressed.

If you really want to discard error messages too, then use the -logfile /dev/null option instead.

-read-stylefiles

Override an earlier -no-read-stylefiles option, so that the three standard style files (see the STYLE FILES section below) are read [default: -read-stylefiles].

-stylefile filename

Name a style file (see the STYLE FILES section below) to augment html-pretty's built-in knowledge of HTML tags. This option may be given more than once, if multiple initialization files are needed.

-trace-opens

Trace all file-opening attempts, with a one-line message on stderr for each [default: -no-trace-opens].

This option can be helpful in analyzing file access failures, and in uncovering the location of default style files and the catalog directory.

-unknown-tag-warning

Unknown HTML tags are always treated as ordinary text, but with this option, you can request that a warning be raised for each of them [default: -no-unknown-tag-warning].

While this option is not a substitute for a validating HTML parser, such as html-check(1) or html-ncheck(1), it does provide a simple way to catch use of non-standard tags. See the -extend-style option for a way to catch specific tags.

-version

Show version information on stderr and quit after processing any remaining command-line options that precede the next command-line HTML file.

-warnings-in-comments

Write warning and error messages as easily-identifiable single-line HTML comments on stdout [default: -no-warnings-in-comments]. This may facilitate correction of problems in the output file, since the messages can be located by context, rather than by line number in the input file.

Messages are always written to stderr as well (which might have been redirected with the -logfile option, or suppressed with the -quiet option).

-width nnn

Set the maximum output line width [default: 72]. This limit may be exceeded if an excessively long string without embedded spaces is encountered, and it is ignored completely inside preformatted or verbatim text.

If you set the line width to 0, it will be treated as `infinite' (i.e., the largest representable integer). If you set it to a very small value, e.g., 1, then the output will have one word per line, which might actually be useful on occasion!

This option can be abbreviated to -w.

FORMATTING CONVENTIONS

The subsections which follow catalog the origins of the recognized tags, and then describe the available style classes in alphabetical order, listing their default tag members, and briefly sketching how the tags are formatted.

Tags that are not explicitly named in these subsections, or in style files that are read at run time, are treated as normal text, and have no effect on the indentation or line breaking, other than their contribution toward the line length limit.

Tags in the style classes doctype, line-break, math, plaintext, short, standalone, and standalone-nocheck make up the set of HTML tags with SGML content EMPTY, which means that end tags for them are forbidden. html-pretty will issue warnings about such end tags, but will leave their deletion to a human.

<!ENTITY % font " TT | B | I ">
<!ENTITY % phrase "EM | STRONG | CODE | SAMP | KBD | VAR | CITE ">
<!ELEMENT (%font;|%phrase) - - (%text)+>
<!ELEMENT XMP - -  %literal>

STYLE FILES

The default name of the first three style files is system dependent: .html-prettyrc (UNIX), htmlpty.ini (IBM PC DOS), and html-pretty.ini (DEC VMS and OpenVMS). The exact names depend on the name of the executable program, which is used to construct the style file names. If you renamed it to sgmlpretty.exe, the names would be .sgmlprettyrc on UNIX, and sgmlpretty.ini on other systems.

More precisely, the program name passed to the prettyprinter as its zeroth argument is filtered by discarding any trailing version number and extension, then keeping the last consecutive string of characters that are letters, digits, hyphens, or underscores. If the zeroth argument is empty, implying that the program name is unknown, then the name htmlpty is used; it is short enough to be acceptable to any reasonable file system.

Automatic association of the style file names with the program name makes it easy to support multiple versions, e.g., html-pretty-2-0, html-pretty-3-0, html-pretty-3-2, and html-pretty-4-0 could select different HTML grammar versions, and on UNIX, and a few other operating systems, those programs could all be links to the same physical file, avoiding wasteful duplication of disk space.

In the current implementation of html-pretty, all of the standard HTML tags defined in HTML grammar levels up to the proposed 4.0, plus a few browser vendor extensions, are hard-coded into the program as members of over twenty formatting-style classes, so that no external style files need exist for the program to run. However, the -extend-style, -grammar-level, and -stylefile options allow the built-in rules to be completely replaced, if desired.

The -print-stylefile command displays the built-in style rules as a set of style class names, each followed by a colon and a list of HTML tags in that style class. Its output may be used without further modification as a style file, and looks something like this:

%% html-pretty version 1.00 date [29-Nov-1997]
%% User-modifiable style file generated on Wed Dec  3 08:34:39 1997
%% Uncomment the next line to clear all existing rules,
%% or leave it as a comment to preserve them:
% default :
body :                    BODY
doctype :                 !DOCTYPE
font :                    ACRONYM B BIG BLINK BT CODE \
                          DFN EM I KBD Q REV S SAMP \
                          SMALL STRIKE STRONG T TT U \
                          VAR
head :                    HEAD
html :                    HTML
inline :
line-break :              BR
link :                    LINK
list :                    DIR DL MENU OL UL
list-header :             LH
list-item :               DD DT LI
markup-declaration :      !ATTLIST !ELEMENT !ENTITY \
                          !NOTATION !SGML !SHORTREF \
                          !USEMAP
math :                    ATOP CHOOSE LEFT OF OVER \
                          RIGHT TAB
math-pair :               ABOVE BAR BELOW BOX DDOT \
                          DOT HAT ROOT ROW SQRT SUB \
                          SUP TILDE VEC
pair :                    A ABBREV ABSTRACT ADDED \
                          ADDRESS APPLET ARG AROW \
                          ARRAY AU BDO BLOCKQUOTE BQ \
                          BUTTON CAPTION CENTER CITE \
                          CMD COLGROUP CREDIT DEL DIV \
                          DIV1 DIV2 DIV3 DIV4 DIV5 \
                          DIV6 FIELDSET FIG FN FONT \
                          FOOTNOTE FORM FRAMESET HIDE \
                          IFRAME INS LABEL LANG MAP \
                          MARGIN MATH MESSAGE \
                          NOFRAMES NOSCRIPT NOTE \
                          OBJECT OPTION PERSON QUOTE \
                          REMOVED SELECT SPAN TABLE \
                          TBODY TD TEXTAREA TFOOT TH \
                          THEAD TR
paragraph :               P
plaintext :               PLAINTEXT
public :                  "-//IETF//DTD HTML//EN"
section :                 H1 H2 H3 H4 H5 H6
short :                   ITEM
standalone :              CHANGED HR IMG INPUT RENDER \
                          STYLES WBR
standalone-nocheck :      AREA BASE BASEFONT COL \
                          FRAME ISINDEX META NEXTID \
                          OVERLAY PARAM
title :                   TITLE
verbatim :                LISTING NOBR PRE XMP
verbatim-nocheck :        SCRIPT STYLE

There will be additional data at the end of this output, in the form of the tag relationships discussed below, but we omit it here because of its length.

Notice that long lines can be continued on multiple physical lines, for improved readability, by terminating them with a backslash immediately before the newline. The output line width in this file is governed by the -width option.

As with the command-line -extend-style option, you can replace the colon with an equal sign, and the spaces between tags with commas, if you prefer.

In addition to the style classes listed above, the special style class default can be used to force an HTML tag to revert to the default rule for unknown tags: just treat it as ordinary text, although if the -unknown-tag-warning option was specified, a warning will be issued for this now unknown tag. You can use this to override earlier style file settings, and most of the built-in ones.

The special style class public is associated with the SGML DOCTYPE identifier string, rather than with a list of HTML tags. That string determines which grammar file is to be used for the document, and the value above corresponds to the most generic grammar level (2.0) recognized by almost all browsers, even though the style file includes tags from higher grammar levels. The public style class is the only class whose value is a quoted string.

If the tag list to the right of the colon (or equals sign) is empty, then all existing tags for that class are forgotten. If an empty tag list is used with the default style class, then all tags for all classes are forgotten. These two uses allow you to eliminate all built-in rules, or just certain style classes, so that your style file can start from a known rule base.

Style class names are case sensitive, and all of the ones recognized by html-pretty must be spelled with lowercase letters.

The style file is expected to contain lines of the forms:

style-class : TAG1 TAG2 ...

TAG : TAG1 TAG2 ...

relationship[TAG] : TAG1 TAG2 ...

-option
-option -option ...
-option value
-option value -option value  ...

In the second form, the style class of the first tag is looked up and assigned to the remaining tags. That first tag must be entirely UPPERCASE in order to distinguish it from a style class. The remaining tag names can be in either lettercase, or in mixed case; they will be converted to uppercase internally.

The third form specifies a relationship between a tag, and one or more other tags. The two currently-recognized relationships are ContainedIn and CannotContain; any others that are specified will simply be ignored, although they will take up memory space. For example, the lines

CannotContain[TITLE]      : LINK META SCRIPT STYLE
ContainedIn[LH]           : DL OL UL

mean that a TITLE environment cannot contain LINK, META, SCRIPT, or STYLE tags, and that an LH tag can only be contained in a DL, OL, or UL environment. Unlike style class definitions, relationships are not cumulative; only the last one of each relationship type encountered for a particular tag will be used.

Because of the complexity of SGML grammars, tag relationships cannot be reliably determined manually. Instead, relationship tables are derived from the grammar files by software developed especially for, and included with, the html-pretty distribution, and then inserted into the standard style files. Thus, it is not anticipated that users will provide tag relationship data in their personal style files, although they are free to do so.

The built-in relationship tables are derived from a merger of the major grammar levels, so that they match tags in the built-in style classes, which are also derived from that merger.

Tag relationships are only checked when the -check-tag-nesting option is specified, and since that is not a default option, omitting tag relationships will normally not have a visible effect on the output of html-pretty.

In the remaining forms, command-line options appear, and any of the documented options may be used this way. You can use this facility to collect preferred option settings in one place, such as in directory- or user-specific initialization files. Observe that a -stylefile option here can be used to chain temporarily to another file, and this can go on recursively to a depth which is limited only by the run-time stack depth and the maximum number of simultaneously open files.

Blank lines, leading and trailing whitespace, and text from a percent (%) comment character to end of line, are ignored. To get a literal percent or quotation mark into a value, prefix it with a backslash; the backslash will be removed when the value is collected.

Whitespace separates items, and can be omitted around the colon. There is no significance to the order of items on a line, or lines in the file, except that later settings can override earlier ones. The same style class name may occur on multiple lines, and the tag lists will be accumulated, discarding duplicates.

The line length limit in style files is system-dependent, but guaranteed to be at least 2048 characters.

Here is an example of a small style file to add the new tags introduced in the HTML proposed 4.0 grammar (even though they are actually already present in the built-in rules):

% HTML proposed 4.0 additions
font : Acronym s
pair : BdO Button col colgroup Fieldset FrameSet IFrame \
       laBel NoFrames NoScript Object span TBody TFoot thEAD
public : "-//W3C//DTD HTML 4.0 Transitional//EN"

The last style class attached to command or environment name is the one that is used, so specifications in command-line -extend-style, -grammar-level, or -stylefile options can override those in the current directory style file, those in turn override settings from the home directory style file, and those override system-wide style file settings.

CATALOG DIRECTORY

However, it may be useful to offer a simpler interface that only requires the user to specify the desired grammar level with the -grammar-level grammar option, and have html-pretty automatically find the style files. Thus, when the -grammar-level option is used, html-pretty looks for a catalog directory that contains a file named catalog, and one or more style files.

The catalog directory is searched for in the same path as the executable file, but in a path starting one level higher. On UNIX, it is usually called share/lib/<programname>, so if the executable program was /usr/local/bin/html-pretty, the catalog directory is /usr/local/share/lib/html-pretty. [Conventionally, on UNIX systems, directories in the share directory tree are shared across multiple O/S releases and vendor architectures.]

On other operating systems, the share portion of the path may be omitted. However, the quickest way to find out where the catalog directory resides on your system is to run html-pretty with the -grammar-level and -trace-opens options, to trace the file-opening attempts.

The catalog file has a simple format: each non-empty line contains a grammar level, and a corresponding filename in that directory. As with style files, comments run from percent (%) to end-of-line, but there is no support for line continuation, since the lines are all very short. To get a literal percent or quotation mark into a value, prefix it with a backslash; the backslash will be removed when the value is collected.

This indirect mapping of grammar level to style file means that end users need not know the style file names, and thus, that the names can be changed to meet local requirements.

SGML parsers and other SGML software use a similar catalog file to map DTD descriptor strings to local filenames.

Lettercase is not significant in grammar-level names, although it may be for filenames. The standard style files are all named in a single lettercase, so that the catalog entries work on all file systems.

If you are developing a new set of styles, you probably do not want them put in the system-wide catalog directory until they have been completed and debugged. In such a case, you can use the -catalogfile option to specify an alternate catalog file location. Once they are ready for wider release, you (or your system manager) can merge your catalog file with the system one, and copy your style files into the system catalog directory.

COMMENTS IN HTML AND SGML

SGML has a command called markup declaration open, or mdo for short, which defaults to the two-character sequence <!, and is matched by a markup declaration close, or mdc, which defaults to the one-character sequence >. The mdo must be immediately followed either by a keyword, such as ATTLIST, DOCTYPE, ELEMENT, ENTITY, NOTATION, SGML, SHORTREF, or USEMAP, or else by a comment start, which is the two-character sequence --. In the latter case, there must later be a second -- pair to signal a comment end. Anything after that second pair is non-comment text to be parsed. However, additional comments can appear, provided that they are surrounded by -- pairs. Eventually, the markup declaration is ended by an mdc command, although whitespace may follow the last comment. Thus,

<!--one-- --two-- --three-->
<!-- one -- -- two -- -- three -- >
<!-- one --
  -- two --
  -- three --
>

are all legal markup declarations, each of which consists of three comments. However, these are in error:

<! --one-- --two-- --three-- >
<!-- one -- two -- three -- >
<!--
         one --
      -- two --
      - - three - -
>

The first has an illegal space after the mdo, the second has the word two outside a comment, and the third has the text - - three - - outside the comment.

Given these rules, can SGML comments be nested? It might appear that they can, since

<!-- <!-- --> -->
<!-- <!-- --> <!-- --> -->

are both accepted by an SGML parser. However, the nesting is illusory, since the first has two comments, containing the text <! and >, and the third has three comments: <! and > <! and >. As soon as we put words between the hyphen pairs, such as

<!-- one <!-- two --> three -->
<!-- one <!-- two --> <!-- three --> four -->

the word two lies outside the comment in the first, and two and three are outside the comment in the second. Therefore, SGML and HTML comments cannot in general be nested.

Finally, because of the special significance of -- as both a comment start and a comment end inside a markup declaration, you must be careful about using adjacent hyphens in the comment text. In particular, if you use a line of hyphens to set off one block of text from another, the number of hyphens must be a multiple of 4, such as this 60-hyphen example:

<!------------------------------------------------------------>

Having 57, 58, 59, 61, 62, or 63 hyphens won't do!

html-pretty does not distinguish markup declarations, beginning with <!, from tags, beginning with <, except for comments, which have to be parsed separately anyway to handle the pairs-of-pairs-of-hyphens balance requirement. Thus, it considers !DOCTYPE to be a tag name, when strictly speaking, the ! is part of the markup declaration open. However, since the closing character > can always be represented by an SGML entity, &lt;, html-pretty can safely assume that anything between angle brackets is a `tag'. That is why the style files have a rule

doctype :            !DOCTYPE

with the exclamation mark prefixed to the word DOCTYPE.

HTML GRAMMAR CONSTRAINTS

The grammar rules for some environments explicitly forbid certain tags from appearing in those environments; this is indicated in the lists below by the prefix cannot contain:.

Because the HTML definition is evolving, many tags are defined only in certain grammar files. In such a case, the grammar level is indicated by a suffix with a colon and a sorted list of one or more levels: 2, 3, 3.2, 4C (4-Cougar), 4L (4-loose), and M (Mosaic and Netscape). [The level 4-strict from July and November, 1997, is excluded because the grammar file omits many heavily-used tags, in anticipation that their features will be provided by style sheets.]

Although there are other HTML grammar versions, these are the major ones that are important for current browsers. If no grammar level list is present, then the tag is available in all of the levels listed at the start of this paragraph.

The `tag' #PCDATA means parsed character data, an SGML term for text of zero or more ordinary characters and/or SGML named and numeric entities, such as &quot; and &#34;.

The `tag' ANY is a catch-all that means #PCDATA, or any SGML tag defined in the grammar. It should not be used in SGML grammars, but it is present in the Mosaic/Netscape grammar file, html-mcom.dtd.

The `tag' CDATA means character data, an SGML term for zero or more characters that are not further examined, except for the purposes of scanning for an end tag. This corresponds to verbatim text in typesetting and word-processing systems.

The special `tag' EMPTY means that the environment is empty, and further, that a matching end tag is forbidden.

If no end tag is shown in the paragraph heading, then it must be omitted in HTML files.

Unless suffixed by optional, all tags listed in the remainder of this section are required. However, if a grammar level list is attached to optional or required, then the tag is defined only in those grammar levels.

Use these lists as a portability guide: if a tag is implemented in only specified grammar levels, then documents which use it are more likely to be displayed improperly by Web browsers.

#PCDATA

NB: The meaning of this tag is aberrant, in that the closing tag is not supposed to be present, even though the grammar says that it is optional: the environment instead terminates at end-of-file. Browsers differ in their handling of the end tag: some display it as ordinary text, and others terminate the environment.

<PRE> ... </PRE>

PRETTYPRINTER LIMITATIONS

In SGML, this is conventionally done in SGML declaration files for syntax definitions, and in DTD files, which are analogous to LaTeX style files. Low-level typesetting commands of the flavor ``select a 14-point Lucida-BoldItalic font'', ``skip down vertically 6 picas'', and ``draw a horizontal rule 3 ems long'' are notably absent. SGML documents are expected to use only high-level markup commands, leaving the visual appearance entirely up to the DTD specification, and the formatting software.

Unlike LaTeX and TeX, SGML is not a typesetting system. It is only a grammar for a standard markup language, and it is left to SGML software implementors to write DTDs, and to provide for translation of SGML documents to specific document formatting, typesetting, or word processing systems. In this respect, SGML is similar to the RTF (Rich Text Format) supported by many popular word processors, in that it can serve as an intermediate language for electronic document exchange; several language translators between SGML and other text representations are mentioned in the SEE ALSO section below. Regrettably, there is wide variation in the capabilities and document models of current text formatting systems, so such translations are usually rough approximations that may require substantial hand patching to make them truly satisfactory.

HTML is a modest subset of SGML, with tag names apparently chosen from SGML, the Free Software Foundation's TeXinfo system (which in turn is modeled on the earlier Scribe document formatting system), and occasionally, also from LaTeX.

html-pretty is written in this spirit: it knows about the meaning and typical use of all standard HTML tags, but nothing about other SGML DTDs. However, the style-file facility makes it possible to prepare formatting rules for any SGML DTD, extending the applicability of html-pretty to the entire world of SGML, provided a tag normalizer such as sgmlnorm(1) or spam(1) is available to supply omitted tags, and expand abbreviated ones. However, since SGML tag names depend on the specific DTD, and DTDs tend to be proprietary, html-pretty is not packaged with pre-written style files for SGML.

Contributions of suitable style files for public SGML DTDs, together with those DTDs, are hereby solicited, and they may be included in future releases of html-pretty.

PRETTYPRINTER IMPLEMENTATION LIMITS

2048 characters in single words, tag names, and filenames (this must be at least as large as the LITLEN limit set in the SGML parser declaration file html.decl);

100 levels of list and environment nesting (this must be at least as large as the TAGLVL limit set in the SGML parser declaration file html.decl);

6 simultaneously open files (stdin, stderr, and stdout, plus the style catalog file, and two style files, allowing at least two levels of style file nesting).

These are ample for any realistic document: they support the longest legal file paths in all major current operating systems, World-Wide Web URLs, and HTML tags named after 58-letter Welsh towns like Llanfairpwllgwyngyllgogerychwyrndrobwllllantysiliogogogoch, yet will still work on the smallest personal computer operating systems.

There is no limit on the size of input or output files and lines, other than that imposed by physical storage limits of the host file system and the computer address space.

SEE ALSO

The ISO 8879 SGML Standard is contained in the book

Charles F. Goldfarb and Yuri Rubinsky
The SGML Handbook
Cambridge University Press
1990
xxiv + 663 pp.
ISBN 0-19-853737-9
LCCN Z286.E43 G64 1990

That book serves as the `scriptures' of SGML; it even has long blue ribbons attached to serve as page marks!

References to nearly 300 books and over 1000 other publications about SGML can be found at these World-Wide Web locations:

ftp://ftp.math.utah.edu/pub/tex/bib/index.html#sgml
http://sgml.sgmlopen.org/
http://www.sil.org/sgml/sgml.html
http://www.falch.no/people/pepper/sgmltool/

SGML software repositories are available at:

http://sgml.sgmlopen.org/
ftp://ftp.math.utah.edu/pub/sgml

The latter has source and binary distributions for several of the SGML tools mentioned at the start of this section, including html-check(1), html-ncheck(1), html-pretty, html-spam(1), man2html(1), nsgmls(1), sgmlnorm(1), sgmls(1), and spam(1).

AUTHOR

Nelson H. F. Beebe, Ph.D.
Center for Scientific Computing
University of Utah
Department of Mathematics, 105 JWB
155 S 1400 E RM 233
Salt Lake City, UT 84112-0090
Tel: +1 801 581 5254
FAX: +1 801 581 4148
Email: beebe@math.utah.edu, beebe@acm.org, beebe@ieee.org (Internet)
WWW URL: http://www.math.utah.edu/~beebe

AVAILABILITY

ftp://ftp.math.utah.edu/pub/sgml/

in the file htmlpty-x.yy.tar.gz where x.yy is the current version. Other distribution formats are usually available in the same location. Several other SGML and HTML tools are available in that same directory.

That site is mirrored to several other Internet archives, so you may also be able to find it elsewhere on the Internet; try searching for the string htmlpty at one or more of the popular Web search sites, such as

http://altavista.digital.com/
http://www.hotbot.com/
http://www.stpt.com/
http://www.yahoo.com/