<?xml version="1.0"?>
<!-- vim: sw=2 sta et
-->

<!DOCTYPE refentry
  PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
         "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [

  <!ENTITY nsgmls1 "
    <citerefentry>
      <refentrytitle><command>nsgmls</command></refentrytitle>
      <manvolnum>1</manvolnum>
    </citerefentry>">
]>

<refentry>
  <refentryinfo>
    <date>25 July 2004</date>
  </refentryinfo>
  
  <refmeta>
    <refentrytitle>sgmlnorm</refentrytitle>
    <manvolnum>1</manvolnum>
    
    <refmiscinfo>SP</refmiscinfo>
  </refmeta>
  
  <refnamediv>
    <refname>sgmlnorm</refname>
    <refpurpose>normalize SGML documents</refpurpose>
    <refclass>
      An SGML System Conforming to International Standard ISO 8879 &mdash;
      Standard Generalized Markup Language
    </refclass>
  </refnamediv>
    
  <refsynopsisdiv>
    <cmdsynopsis>
      <command>sgmlnorm</command>
      <arg choice="opt" rep="norepeat"><option>-Cdemnv</option></arg>
      <arg choice="opt" rep="norepeat"><option>-b<replaceable>bctf</replaceable></option></arg>
      <arg choice="opt" rep="norepeat"><option>-c<replaceable>catalog</replaceable></option></arg>
      <arg choice="opt" rep="norepeat"><option>-D<replaceable>dir</replaceable></option></arg>
      <arg choice="opt" rep="norepeat"><option>-i<replaceable>name</replaceable></option></arg>
      <arg choice="opt" rep="norepeat"><option>-w<replaceable>warning</replaceable></option></arg>
      <arg choice="req" rep="repeat"><replaceable>sysid</replaceable></arg>
    </cmdsynopsis>
  </refsynopsisdiv>
    
  <refsect1>
    <title>Description</title>
    
    <para>
      <command>sgmlnorm</command> prints on the standard output a
      <emphasis>normalized</emphasis> document instance for the SGML document
      contained in the concatenation of the entities with system identifiers
      <replaceable>sysid...</replaceable>
    </para>
    
    <para>
      When the normalized instance is prefixed with the original SGML
      declaration and prolog, it will have the same ESIS as the original
      SGML document, with the following exceptions:

      <itemizedlist>
        <listitem>
          <para>
            The output of sgmlnorm does not protect against the recognition
            of short reference delimiters, so any <sgmltag>USEMAP</sgmltag>
            declarations must be removed from the DTD.
          </para>
        </listitem>
        
        <listitem>
          <para>
            The normalized instance will use the reference delimiters, even
            if the original instance did not.
          </para>
        </listitem>
        
        <listitem>
          <para>
            If marked sections are included in the output using the 
            <option>-m</option> option, the reference reserved names will be
            used for the status keywords even if the original instance did not.
          </para>
        </listitem>
        
        <listitem>
          <para>
            Any ESIS information relating to the SGML LINK feature will be 
            lost.  
          </para>
        </listitem>
      </itemizedlist>
    </para>
    
    <para>
      The normalized instance will not use any markup minimization
      features except that:

      <itemizedlist>
        <listitem>
          <para>
            Any attributes that were not specified in the original instance
            will not be included in the normalized instance.
            (Current attributes will be included.)
          </para>
        </listitem>
        
        <listitem>
          <para>
            If the declared value of an attribute was a name token group, and
            a value was specified that was the same as the name of the 
            attribute, then the attribute name and value indicator will be 
            omitted. For example, with HTML <command>sgmlnorm</command> would
            output <literal>&lt;DL COMPACT&gt;</literal> rather than 
            <literal>&lt;DL COMPACT="COMPACT"&gt;</literal>.
          </para>
        </listitem>
      </itemizedlist>
    </para>
  </refsect1>
  
  <refsect1>
    <title>Options</title>
    
    <variablelist>
      <varlistentry>
        <term><option>-b</option><replaceable>bctf</replaceable></term>
        <listitem>
          <para>
            Use the BCTF name <replaceable>bctf</replaceable> for output.  
            See &nsgmls1; for more information about this option.
          </para>
        </listitem>
      </varlistentry>
    
      <varlistentry>
        <term><option>-c</option><replaceable>file</replaceable></term>
        <listitem>
          <para>
            Use the catalog entry file <replaceable>file</replaceable>.  
          </para>
        </listitem>
      </varlistentry>
      
      <varlistentry>
        <term><option>-C</option></term>
        <listitem>
          <para>
            The <replaceable>filename...</replaceable> arguments specify 
            catalog files rather than the document entity. The document entity
            is specified by the first <sgmltag>DOCUMENT</sgmltag> entry in the
            catalog files.
          </para>
        </listitem>
      </varlistentry>
      
      <varlistentry>
        <term><option>-d</option></term>
        <listitem>
          <para>
            Output a document type declaration with the same external
            identifier as the input document, and with no internal
            declaration subset.  No check is performed that the document
            instance is valid with respect to this DTD.
          </para>
        </listitem>
      </varlistentry>
    
      <varlistentry>
        <term><option>-D</option><replaceable>directory</replaceable></term>
        <listitem>
          <para>
            Search <replaceable>directory</replaceable> for files specified in
            system identifiers.  Multiple <option>-D</option> options are 
            allowed.  See &nsgmls1; for more information about this option.
          </para>
        </listitem>
      </varlistentry>
    
      <varlistentry>
        <term><option>-e</option></term>
  
        <listitem>
          <para>Describe open entities in error messages.</para>
        </listitem>
      </varlistentry>
    
      <varlistentry>
        <term><option>-i</option><replaceable>name</replaceable></term>
        <listitem>
          <para>
            Pretend that <literal>&lt;!ENTITY % name "INCLUDE"&gt;</literal>
            occurs at the start of the document type declaration subset in the
            SGML 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 <option>-i</option> options are allowed. If the SGML 
            declaration replaces the reserved name <sgmltag>INCLUDE</sgmltag> 
            then the new reserved name will be the replacement text of the 
            entity.  Typically the document type declaration will contain
            <literal>&lt;!ENTITY % name "IGNORE"&gt;</literal> and will use 
            <sgmltag>%name;</sgmltag> 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.
          </para>
        </listitem>
      </varlistentry>
    
      <varlistentry>
        <term><option>-m</option></term>
        <listitem>
          <para>
            Output any marked sections that were in the input document 
            instance.
          </para>
        </listitem>
      </varlistentry>
    
      <varlistentry>
        <term><option>-n</option></term>
        <listitem>
          <para>
            Output any comments that were in the input document instance.
          </para>
        </listitem>
      </varlistentry>
    
      <varlistentry>
        <term><option>-r</option></term>
        <listitem>
          <para>
            Raw output. Don't perform any conversion on RSs and REs when 
            printing the entity. The entity would typically have the storage 
            manager attribute <sgmltag>records=asis</sgmltag>.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>-v</option></term>
        <listitem>
          <para>Print the version number.</para>
        </listitem>
      </varlistentry>
    
      <varlistentry>
        <term><option>-w</option><replaceable>type</replaceable></term>
        <listitem>
          <para>
            Control warnings and errors according to 
            <replaceable>type</replaceable>.  See &nsgmls1;
            for the allowed values of type.
          </para>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsect1>

  <refsect1>
    <title>Author</title>
    <simpara>James Clark <email>jjc@jclark.com</email></simpara>
  </refsect1>
  
  <refsect1>
    <title>See Also</title>
    
    <simplelist type="vert">
      <member>&nsgmls1;</member>
      <member><filename>/usr/share/doc/sp/sgmlnorm.htm</filename></member>
    </simplelist>
  </refsect1>
</refentry>