home *** CD-ROM | disk | FTP | other *** search
/ Fresh Fish 10 / Fresh_Fish_10_2352.bin / new / dev / lang / sgmls / doc / sgmls.txt < prev    next >
Text File  |  1994-07-10  |  27KB  |  727 lines
  1.  
  2.  
  3.  
  4. SGMLS(1)                                                 SGMLS(1)
  5.  
  6.  
  7. NAME
  8.        sgmls - a validating SGML parser
  9.  
  10.        An SGML System Conforming to
  11.        International Standard ISO 8879 --
  12.        Standard Generalized Markup Language
  13.  
  14. SYNOPSIS
  15.        sgmls  [  -deglprsuv  ] [ -cfile ] [ -iname ] [ -mfile ] [
  16.        filename...  ]
  17.  
  18. DESCRIPTION
  19.        Sgmls parses and validates the  SGML  document  entity  in
  20.        filename...   and  prints  on the standard output a simple
  21.        ASCII representation of its Element Structure  Information
  22.        Set.   (This  is  the  information  set which a structure-
  23.        controlled conforming SGML application should  act  upon.)
  24.        Note  that  the document entity may be spread amongst sev-
  25.        eral files; for example, the  SGML  declaration,  document
  26.        type  declaration  and document instance set could each be
  27.        in a separate file.  If no filenames are  specified,  then
  28.        sgmls  will  read  the  document  entity from the standard
  29.        input.  A filename of - can also be used to refer  to  the
  30.        standard input.
  31.  
  32.        The following options are available:
  33.  
  34.        -cfile Report  any  capacity  limits that are exceeded and
  35.               write a report of  capacity  usage  to  file.   The
  36.               report  is in the format of a RACT result.  RACT is
  37.               the  Reference  Application  for  Capacity  Testing
  38.               defined  in the Proposed American National Standard
  39.               Conformance Testing for Standard Generalized Markup
  40.               Language  (SGL)  Systems  (X3.190-199X), Draft July
  41.               1991.
  42.  
  43.        -d     Warn about duplicate entity declarations.
  44.  
  45.        -e     Describe open entities in  error  messages.   Error
  46.               messages  always  include  the position of the most
  47.               recently opened external entity.
  48.  
  49.        -g     Show the GIs of open elements in error messages.
  50.  
  51.        -iname Pretend that
  52.  
  53.                      <!ENTITY % name "INCLUDE">
  54.  
  55.               occurs at the start of the document  type  declara-
  56.               tion  subset  in  the  SGML document entity.  Since
  57.               repeated definitions of an entity are ignored, this
  58.               definition will take precedence over any other def-
  59.               initions of this entity in the document type decla-
  60.               ration.   Multiple  -i options are allowed.  If the
  61.  
  62.  
  63.  
  64.                                                                 1
  65.  
  66.  
  67.  
  68.  
  69.  
  70. SGMLS(1)                                                 SGMLS(1)
  71.  
  72.  
  73.               SGML declaration replaces the reserved name INCLUDE
  74.               then  the new reserved name will be the replacement
  75.               text of the entity.  Typically  the  document  type
  76.               declaration will contain
  77.  
  78.                      <!ENTITY % name "IGNORE">
  79.  
  80.               and  will use %name; in the status keyword specifi-
  81.               cation of a marked section  declaration.   In  this
  82.               case  the effect of the option will be to cause the
  83.               marked section not to be ignored.
  84.  
  85.        -l     Output L commands giving the  current  line  number
  86.               and filename.
  87.  
  88.        -mfile Map  public  identifiers and entity names to system
  89.               identifiers using  the  catalog  entry  file  file.
  90.               Multiple  -m  options  are  allowed.  Catalog entry
  91.               files specified with the -m option will be searched
  92.               before the defaults.
  93.  
  94.        -p     Parse only the prolog.  Sgmls will exit after pars-
  95.               ing the document type declaration.  Implies -s.
  96.  
  97.        -r     Warn about defaulted references.
  98.  
  99.        -s     Suppress output.   Error  messages  will  still  be
  100.               printed.
  101.  
  102.        -u     Warn about undefined elements: elements used in the
  103.               DTD but not defined.
  104.  
  105.        -v     Print the version number.
  106.  
  107.    Entity Manager
  108.        An external entity resides in  one  or  more  files.   The
  109.        entity manager component of sgmls maps a sequence of files
  110.        into an entity in three sequential stages:
  111.  
  112.        1.     each carriage return character  is  turned  into  a
  113.               non-SGML character;
  114.  
  115.        2.     each  newline character is turned into a record end
  116.               character, and at the  same  time  a  record  start
  117.               character  is  inserted  at  the  beginning of each
  118.               line;
  119.  
  120.        3.     the files are concatenated.
  121.  
  122.        A system identifier is interpreted as a list of  filenames
  123.        separated by colons.  A filename of - can be used to refer
  124.        to the standard input.
  125.  
  126.        If a system identifier is not specified, then  the  entity
  127.  
  128.  
  129.  
  130.                                                                 2
  131.  
  132.  
  133.  
  134.  
  135.  
  136. SGMLS(1)                                                 SGMLS(1)
  137.  
  138.  
  139.        manager  can generate one using catalog entry files in the
  140.        format defined in the SGML Open Draft Technical Resolution
  141.        on  Entity  Management.   A  catalog entry file contains a
  142.        sequence of entries in one of the following four forms:
  143.  
  144.        PUBLIC pubid sysid
  145.               This specifies that sysid should  be  used  as  the
  146.               system  identifier  if the the public identifier is
  147.               pubid.  Sysid is a system identifier as defined  in
  148.               ISO  8879  and  pubid  is  a  public  identifier as
  149.               defined in ISO 8879.
  150.  
  151.        ENTITY name sysid
  152.               This specifies that sysid should  be  used  as  the
  153.               system identifier if the entity is a general entity
  154.               whose name is name.
  155.  
  156.        ENTITY %name sysid
  157.               This specifies that sysid should  be  used  as  the
  158.               system  identifier  if  the  entity  is a parameter
  159.               entity whose name is name.  Note that there  is  no
  160.               space between the % and the name.
  161.  
  162.        DOCTYPE name sysid
  163.               This  specifies  that  sysid  should be used as the
  164.               system  identifier  if  the  entity  is  an  entity
  165.               declared in a document type declaration whose docu-
  166.               ment type name is name.
  167.  
  168.        The last two forms are extensions to the SGML Open format.
  169.        The  delimiters  can be omitted from the sysid provided it
  170.        does not contain any white space.   Comments  are  allowed
  171.        between  parameters delimited by -- as in SGML.  The envi-
  172.        ronment  variable  SGML_CATALOG_FILES  contains  a  colon-
  173.        separated  list  of  catalog  entry  files.  These will be
  174.        searched after any catalog entry files specified using the
  175.        -m  option.  If this environment variable is not set, then
  176.        a system dependent list of catalog  entry  files  will  be
  177.        used.   A match in a catalog entry file for a PUBLIC entry
  178.        will take precedence over a match in the same file for  an
  179.        ENTITY  or  DOCTYPE entry.  A filename in a system identi-
  180.        fier in a catalog entry file is  interpreted  relative  to
  181.        the directory containing the catalog entry file.
  182.  
  183.        If no match can be found in a catalog entry file, then the
  184.        entity manager will attempt to generate a  filename  using
  185.        the public identifier (if there is one) and other informa-
  186.        tion available to it.  Notation identifiers are  not  sub-
  187.        ject to this treatment.  This process is controlled by the
  188.        environment variable SGML_PATH;  this  contains  a  colon-
  189.        separated list of filename templates.  A filename template
  190.        is a filename that may contain substitution fields; a sub-
  191.        stitution field is a % character followed by a single let-
  192.        ter that indicates the value  of  the  substitution.   The
  193.  
  194.  
  195.  
  196.                                                                 3
  197.  
  198.  
  199.  
  200.  
  201.  
  202. SGMLS(1)                                                 SGMLS(1)
  203.  
  204.  
  205.        value  of  a substitution can either be a string or it can
  206.        be null.  The entity manager transforms the list of  file-
  207.        name  templates  into  a list of filenames by substituting
  208.        for each substitution field and  discarding  any  template
  209.        that  contained a substitution field whose value was null.
  210.        It th