
     _________________________________________________________________
                                      
                                    dtdview
                                       
   dtdview is an interactive [1]SGML _document type definition_ (DTD)
   querying tool. dtdview provides a command-line interface to access
   element content rules, element attributes, and navigate the structure
   of a DTD.
   
     _________________________________________________________________
                                      
Description

   When dtdview is invoked, it provides a command-line interface to
   access the information defined in a DTD. When dtdview is started
   without an initial DTD to read, the following prompt will appear:
   
(dtdview) ->

   If an initial DTD was specified, the prompt will look like the
   following:
   
(mydtd) ->

   The string in the "()" will contain the name of the DTD.
   
   See [2]Usage on how to invoke dtdview from your shell command-line.
   See [3]Command Syntax on how to invoke dtdview commands. See
   [4]Commands for a list of all dtdview commands available.
   
     _________________________________________________________________
                                      
Usage

   dtdview is invoked from the shell as follows:
   
   % dtdview [<options>] [<filename>]
   
   If <filename> is given, dtdview will automatically load <filename> as
   the initial DTD.
   
   The following are the list of options available:
   
   -catalog filename
          Use filename as the file for mapping public identifiers and
          external entities to system files. If -catalog is not
          specified, "catalog" is used as the default filename. See
          [5]Resolving External Entities for more information.
          
   -help
          Print a brief usage description. No other action is performed.
          
   -verbose
          Print parsing information if a DTD is specified on the
          command-line.
          
  Batch Mode
  
   If standard input is not the terminal, dtdview will run in batch mode.
   dtdview will execute each command from the input without prompting.
   Any line of the input beginning with a '#' will be ignored. dtdview
   will still generate output as normal.
   
   Batch mode operation allows you to create scripts to automate
   repeating tasks. The following example script will generate a full
   listing of all elements' content models and attributes to a file
   called "dtdreport.txt":
   
#       Script to generate a report off all elements of a dtd.
#
# List all elements in a single column and save to a temp file.
#
elements 1 > ,tmpfile
#
# Remove report file if it exists.
#
system /bin/rm dtdreport.txt
#
# Call perl to edit temp file to create legal dtdview commands
#
system perl -p -i -e 's/\s*(\S+)\s*/content $1 >> dtdreport.txt\nattributes $1
>> dtdreport.txt\n/' ,tmpfile
#
# Source temp file
#
source ,tmpfile
#
# Remove temp file
#
system /bin/rm ,tmpfile
#
# End of script

   If the script is called "report.dvs", the following can be used to run
   the script on a DTD:
   
dtdview mydtd.dtd < report.dvs

     _________________________________________________________________
                                      
Command Syntax

   The following notation is used for syntax diagrams:
   
   |
          Or connector. Used to separate a list of choices.
          
   [ ]
          Optional. Anything surrounded by [ ]'s is optional.
          
   < >
          Variable value. Anything in < >'s represents a value that can
          vary.
          
   " "
          Literal text. Anything in " "'s is taken as-is.
          
   The following is the general syntax for all dtdview commands:
   
   <command> [<options>] [ [ [ ">" | ">>" ] <filename> ] | [ "|"
   <program> ] ]
   
   In sum, dtdview commands may have some options to control the behavior
   of the command. Any command may be redirected to a file, or piped into
   another program.
   
   Here's an example of a command that prints the content model of the
   element CHAPTER:
   
(dtdview) -> content chapter

   Here's an example of a command that prints all the elements defined in
   the DTD and redirects the output to a file:

(dtdview) -> elements > element.lst

   If the output is to be appended to a file, use ">>".
   
   Here's an example of a command that prints all the elements defined in
   the DTD at pipes the output to more(1) to allow the output to be paged
   one screenful at a time:

(dtdview) -> elements | more

  Syntax Notes
  
     * An entire command name does not need to be entered to invoke a
       command. As long as the unambiguous prefix is entered, dtdview
       will automatically determine the proper command to invoke.
     * For commands that take element names as arguments, an element can
       be designated by its unambiguous prefix. dtdview will
       automatically determine the proper full element name.
       
     _________________________________________________________________
                                      
Commands

   The commands listed are divided into three catagories:
   
     * [6]Data access commands
     * [7]Hierarchical path commands
     * [8]Utility commands
       
  Data access commands
  
   The following commands allow to access the data defined in the DTD.
   
   attributes [<elem>]
          List the attributes of <elem>. If <elem> is not specified, the
          attributes of the last element in the hierarchical path are
          listed.
          
   base [<elem>]
          Output the base content model of <elem>. If <elem> is not
          specified, then the base content model of the last element in
          the hierarchical path is listed.
          
   content [<elem>]
          Output the full content model of <elem>. If <elem>] is not
          specified, then the effective content model (including
          inherited exceptions) of the last element in the hierarchical
          path is listed.
          
   elements [<col> [<width>] ]
          List all elements defined in the DTD. The optional <col>
          argument specifies the number of columns to use in the output.
          The <width> argument specifies the width of the columns. If no
          <col> and <width> arguments are specified, dtdview will
          automatically determine columns and column widths.
          
   exc [<elem>]
          List exclusion defined for <elem>. If <elem> is not specified,
          then the exclusions defined for the last element in the
          hierarchical path are listed.
          
   inc [<elem>]
          List inclusion defined for <elem>. If <elem> is not specified,
          then the inclusions defined for the last element in the
          hierarchical path are listed.
          
   parents [<elem> [<col> [<width>] ] ]
          List all possible parents of <elem>. If <elem> is not
          specified, then the parents for the last element in the
          hierarchical path are listed.
          
          The optional <col> argument specifies the number of columns to
          use in the output. The <width> argument specifies the width of
          the columns. If no <col> and <width> arguments are specified,
          dtdview will automatically determine columns and column widths.
          
   top
          List top-most elements defined in the DTD.
          
   tree <elem> [<depth>]
          Print content tree of <elem> with an optional depth of <depth>.
          Depth level of 2 is the default.
          
  Hierarchical path commands
  
   down <elem>
          down <elem> "," <elem> "," ...
          Move down the hierarchical path to <elem>. A comma separated
          list (with no whitespace) of elements may be specified to go
          down the path represented by the list.
          
   root [<elem>]
          Set the root of the hierarchical path to <elem>. If <elem> is
          not specified, the current root is listed.
          
   up [<#>]
          Move up <#> elements in the hierarchical path. If <#> is not
          specified, 1 is used.
          
   where
          Print the current hierarchical path.
          
  Utility commands
  
   catalog <filename>
          Read catalog <filename>. See [9]Resolving External Entities for
          more information.
          
   cd <path>
          Change the current working directory to <path>. This command is
          a convience function to simplify the interactive loading of
          DTDs and catalogs.
          
   dtd <filename> [ "0" | "1" ]
          Read the DTD specified by <filename>. An optional 0 or 1 may be
          specified to set the verbosity. A 1 will cause output to be
          generated as the DTD is parsed. A [10]reset is done before
          <filename> is read.
          
          Once the DTD is loaded, dtdview will automatically set the
          [11]root to the [12]top element in the DTD. If multiple top
          elements exists, the first one in alphabetical order is chosen.
          
   exit
          Exit the program.
          
   help [<command>]
          Give listing of all commands available. If <command> is
          specified, a brief usage description will be given for
          <command>.
          
   ls
          List files in current working directory. The output is similar
          to the Unix command "ls -ACF". This command is a convience
          function to simplify the interactive loading of DTDs and
          catalogs.
          
   quit
          Quit the program.
          
   reset
          Reset dtdview to start-up state with no DTD loaded.
          
   source <filename>
          Process commands listed in <filename>.
          
   system <shell_command>
          Invoke <shell_command>.
          
   version
          List version information of dtdview.
          
     _________________________________________________________________
                                      
Resolving External Entities

   Defining the mapping between external entities to system files may be
   done via the [13]-catalog command-line option. The _catalog_ provides
   you with the capability of mapping public identifiers to system
   identifiers (files) or to map entity names to system identifiers.
   
   _Catalog Syntax_
   
   The syntax of a catalog is a subset of SGML catalogs (as defined in
   _SGML Open Draft Technical Resolution 9401:1994_).
   
   A catalog contains a sequence of the following types of entries:
   
   PUBLIC public_id system_id
          This maps public_id to system_id.
          
   ENTITY name system_id
          This maps a general entity whose name is name to system_id.
          
   ENTITY %name system_id
          This maps a parameter entity whose name is name to system_id.
          
   _Syntax Notes_
   
     * A system_id string cannot contain any spaces. The system_id is
       treated as pathname of file.
     * Any line in a catalog file that does not follow the previously
       mentioned entries is ignored.
     * In case of duplicate entries, the first entry defined is used.
       
   Example catalog file:
   
        -- ISO public identifiers --
PUBLIC "ISO 8879-1986//ENTITIES General Technical//EN"            iso-tech.ent
PUBLIC "ISO 8879-1986//ENTITIES Publishing//EN"                   iso-pub.ent
PUBLIC "ISO 8879-1986//ENTITIES Numeric and Special Graphic//EN"  iso-num.ent
PUBLIC "ISO 8879-1986//ENTITIES Greek Letters//EN"                iso-grk1.ent
PUBLIC "ISO 8879-1986//ENTITIES Diacritical Marks//EN"            iso-dia.ent
PUBLIC "ISO 8879-1986//ENTITIES Added Latin 1//EN"                iso-lat1.ent
PUBLIC "ISO 8879-1986//ENTITIES Greek Symbols//EN"                iso-grk3.ent
PUBLIC "ISO 8879-1986//ENTITIES Added Latin 2//EN"                ISOlat2
PUBLIC "ISO 8879-1986//ENTITIES Added Math Symbols: Ordinary//EN" ISOamso

        -- HTML public identifiers and entities --
PUBLIC "-//IETF//DTD HTML//EN"                                    html.dtd
PUBLIC "ISO 8879-1986//ENTITIES Added Latin 1//EN//HTML"          ISOlat1.ent
ENTITY "%html-0"                                                  html-0.dtd
ENTITY "%html-1"                                                  html-1.dtd

   _Environment Variables_
   
   The following envariables (ie. environment variables) are supported:
   
   P_SGML_PATH
          This is a colon (semi-colon for MSDOS users) separated list of
          paths for finding catalog files or system identifiers. For
          example, if a system identifier is not an absolute pathname,
          then the paths listed in P_SGML_PATH are used to find the file.
          
   SGML_CATALOG_FILES
          This envariable is a colon (semi-colon for MSDOS users)
          separated list of catalog files to read. If a file in the list
          is not an absolute path, then file is searched in the paths
          listed in the P_SGML_PATH and SGML_SEARCH_PATH.
          
   SGML_SEARCH_PATH
          This is a colon (semi-colon for MSDOS users) separated list of
          paths for finding catalog files or system identifiers. This
          envariable serves the same function as P_SGML_PATH. If both are
          defined, paths listed in P_SGML_PATH are searched first before
          any paths in SGML_SEARCH_PATH.
          
   The use of P_SGML_PATH is for compatibility with earlier versions.
   SGML_CATALOG_FILES and SGML_SEARCH_PATH are supported for
   compatibility with James Clark's nsgmls(1).
   
   _Note_
          When searching for a file via the P_SGML_PATH and/or
          SGML_SEARCH_PATH, if the file is not found in any of the paths,
          then the current working directory is searched.
          
   _Note_
          The file specified by [14]-catalog is read first before any
          files specified by SGML_CATALOG_FILES.
          
     _________________________________________________________________
                                      
Availability

   This program is part of the _perlSGML_ package; see
   <URL:[15]http://www.oac.uci.edu/indiv/ehood/perlSGML.html>
   
     _________________________________________________________________
                                      
Author

   
    [16]Earl Hood <[17]ehood@medusa.acs.uci.edu>
    
     _________________________________________________________________

References

   1. http://www.sil.org/sgml/sgml.html
   2. file://localhost/usr/local/src/perlsgml-1996Oct09/doc/dtdview.html#usage
   3. file://localhost/usr/local/src/perlsgml-1996Oct09/doc/dtdview.html#syntax
   4. file://localhost/usr/local/src/perlsgml-1996Oct09/doc/dtdview.html#commands
   5. file://localhost/usr/local/src/perlsgml-1996Oct09/doc/dtdview.html#resolving
   6. file://localhost/usr/local/src/perlsgml-1996Oct09/doc/dtdview.html#data-access-cmds
   7. file://localhost/usr/local/src/perlsgml-1996Oct09/doc/dtdview.html#path-cmds
   8. file://localhost/usr/local/src/perlsgml-1996Oct09/doc/dtdview.html#util-cmds
   9. file://localhost/usr/local/src/perlsgml-1996Oct09/doc/dtdview.html#resolving
  10. file://localhost/usr/local/src/perlsgml-1996Oct09/doc/dtdview.html#resetcmd
  11. file://localhost/usr/local/src/perlsgml-1996Oct09/doc/dtdview.html#rootcmd
  12. file://localhost/usr/local/src/perlsgml-1996Oct09/doc/dtdview.html#topcmd
  13. file://localhost/usr/local/src/perlsgml-1996Oct09/doc/dtdview.html#-catalog
  14. file://localhost/usr/local/src/perlsgml-1996Oct09/doc/dtdview.html#-catalog
  15. http://www.oac.uci.edu/indiv/ehood/perlSGML.html
  16. http://www.oac.uci.edu/indiv/ehood/
  17. mailto:ehood@medusa.acs.uci.edu
