dtdview 0.5.1

# dtdview

`dtdview` is an interactive 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 Usage on how to invoke `dtdview` from your shell command-line. See Command Syntax on how to invoke `dtdview` commands. See 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 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:

- Data access commands
- Hierarchical path commands
- 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 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 `reset` is done before <filename> is read.

  Once the DTD is loaded, `dtdview` will automatically set the root to the 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 `-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 `-catalog` is read first before any files specified by SGML_CATALOG_FILES.

## Availability

This software is part of the perlSGML package; see (http://www.oac.uci.edu/indiv/ehood/perlSGML.html)

## Author