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


Commands

The commands listed are divided into three catagories:

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

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

Earl Hood
ehood@medusa.acs.uci.edu
Copyright © 1997