18. Document related commands

Document related commands

validate
	Validates the document and returns a list of error messages.
document element
	Returns a handle for the document element.
document base
	Returns a system identifier for the base document.
document prolog
	Returns the prolog of the current document.
document alterprolog
	Returns a boolean value indicating whether the prolog of the current document can be modified or not.
document statistics
	Returns statistical information about the current document.

18.1 Validating the document

In addition to the checks that are performed while the contents of the sgml widget are changed by Tcl commands, the complete content of the widget can be checked using the pcrmvalidate command. This command performs an in-depth validation of the widget contents by recreating the external SGML representation and parsing the resulting document.

If no errors are found in the widget contents, the validate command returns an empty string.

If any problems were found in the sgml document, the pcrmvalidate command signals an Tcl-error and returns a list of error descriptions that can be examined to obtain further information.

Each element in the list of error descriptions consists of seven fields that are separated by colons (:). A description of these fields is given below:

1	Index	This is the location in the sgml widget where the error occurred.
2	File	If the error occurred in an external file, then this field contains the name of the file. This field is empty if the error occurred within the document instance itself.
3	Line	This field contains the number of the line in an external file where the error occurred. The field is empty if the error occurred in the document instance.
4	Column	This field contains the number of the column in an external file where the error occurred. The field is empty if the error occurred in the document instance.
5	Error number	This is a number for identifying the type of the error.
6	Error type	This is a one-character identifier that specifies the class of errors.
7	Description	This is a textual description of the error.

The validate command returns a list of error messages describing the problems that occurred when the document was validated. If serious errors occurred during the validation, an error is created and the validation error messages are returned as the error description.

Serious errors are errors that would make it impossible reload the document or to process the document by other sgml applications. Of course, the amount of ``error tolerance'' depends on the individual sgml application and it is normally required to provide error-free sgml documents. Although the sgml widget does its best to prevent any errors, some errors can occur because of circumstances outside of the reach of the sgml widget, such as erroneous contents of external sgml entities.

18.2 Document element

The document element (i.e. the top level element that encloses the complete contents of the document) can be retrieved with the document element command.

pathname document element

The document element command returns a handle for the document element that can be used like any other element handle (with the exception that it can not be split, deleted, or removed). The command generates an error if no document has been loaded.

Like any other commands that retrieve element handles, the document element command returns a string that has no interpretation other than functioning as a handle for a specific element:

	.s document element
$\Rightarrow$	E8641e80

The only use for the element handle returned by the document element command is to function as a parameter for other widget commands that expect element handles. For example, the following sequence of commands retrieves a handle for the document element and stores it into the variable ref. In the next step, it uses the value of this variable to return the name of the document element:

	set ref [ .s document element ]
$\Rightarrow$	E8641e80
	.s element name $ref
$\Rightarrow$	HTML

18.3 Document prolog

To retrieve the document prolog, the command document prolog can be used.

pathname document prolog

The command returns a string representing the document prolog. By using this command in combination with the get widget command, a complete copy of the document instance can be created with the following procedure:

Some commands (e.g. pcrmentity declare) must alter the prolog of a document to make changes permanent. In some cases, no modifiable document prolog is available, e.g. if DTDless XML documents are manipulated or if the DTD of an SGML document has been implied by a catalog lookup (see section  for details). In these cases, the sgml widget will refuse to perform the requested modifcations.

To find out if the prolog of a document can be modified, the pcrm document alterprolog command can be used. The command has the general form

pathname document alterprolog

and returns a boolean value indicating whether the document prolog may be altered or not. Like all other widget commands, the pcrm document alterprolog command can be abbreviated, e.g. by doc alter als long as the abbreviation is unique and does not conflict with the name of any other widget command.

Note that it is not possible to change the status of the document prolog by passing an additional parameter to the document alterprolog command: It depends on the general setup of the document (i.e. the DOCTYPE statement or the presence of an internal DTD subset) whether the prolog is alterable or not.

18.4 Statistics

The document statistics widget command can be used to retrieve statistical information about the current document.

pathname document statistics

The result of the document statistics command is a Tcl list with three elements:

• The number of elements in the document.
• The number of entity references in the document.
• The maximum depth of the hierarchy of nested elements.