A newly created sgml widget does not contain SGML or XML data. In order to display or modify SGML data in an sgml widget, an existing SGML or XML document must be loaded into the sgml widget or the sgml widget must be instructed to create a new document.
pathName load ?-encoding encoding?
?-type type? systemId ...
The only required argument for the load command is a system
identifier from which to read the SGML document. The system identifier
can have any of the forms described in section ![[*]](crossref.png)
.
| .s load example1.sgml |
The load command parses the file to be loaded by the SGML parser built into the sgml widget and returns a list of errors and warnings created by the parser. The number of messages returned can be limited by setting the -maxmessages configuration option to the desired value.
Once a document has been loaded into the sgml widget, the contents of the document are displayed in the widget's window.
If more than one system identifier is passed to the load widget command, the contents of the system identifiers are concatenated to form the document. This can be useful e. g. for loading documents where the prolog and the document instance are kept in different files. The sgml widget will treat the content of the system identifiers as if it were contained in a single data source.
The -encoding option can be used to inform the sgml widget
about the encoding of the document. The value for this option can be
one of the encodings that can be used as the value of the
encoding attribute of formal system identifers. The usable
encodings are restricted by same restrictions that apply to the
encodings that are used in formal system identifier attributes.
Please refer to section for a description of the
available encodings and their limitations.
If no encoding is specified with the -encoding option, the standard encoding ISO-8859-1 is assumed for SGML documents while UTF-8 is used for XML documents in the absence of a byte order mark in the document.
The -type option allows to specify whether the document in question should be treated as an XML or as an SGML document. The value of the -type option must be either xml or sgml. If this option is not provided, a document that starts with an XML declaration is treated as an XML document. If the document does not start with an XML declaration, it is assumed to be an SGML document.
During the load process, the widget performs the following operations on the document content:
The document can be saved with the save command. The general form of the save command is:
pathName save ?-noprolog? systemId
The save command requires at least one argument: a system identifier for storing the document. The system identifier for storing the document can be either a simple system identifier which is interpreted as a file name or a formal system identifier that specifies the storage manager for saving the document.
Not all types of storage managers that are described in
section can be used in the save widget command; only
CHANNEL, TCL, OSFILE, and OSFD storage
managers are available for storing a document. User-written storage
managers may be used, depending on the implementation of the storage
manager. See section .
If a system identifier without an explicit storage manager specification (i.e. a simple system identifier) is passed to the save command, the OSFILE storage manager is assumed and the system identifier will be treated as a file name.
The -noprolog option can be used to save the document without the document prolog. When the -noprolog option is specified, everything preceeding the start tag of the document element is stripped from the document when saving the widget content.
 |
Using the -noprolog option discards vital information about a document and may prevent successful processing by other applications. This option should be used with care, e.g. for saving a document as a text entity. |
Although it is in theory possible to use the URL storage manager, no properly configured HTTP server would accept an unsolicited document without some kind of user authentication. For this reason, the URL storage manager is not supported in the save command. Users that want to save SGML documents to a HTTP server are encouraged to utilize the Tcl http packet or to use socket operations together with Tcl channels to achieve the desired results.
The sgml widget supports the creation of new SGML or XML documents with the new widget command. The command has the general form:
pathName new ?-encoding encoding?
?-type type? prolog
The new command instructs the sgml widget to discard the current document (if any) and start a new document. The necessary information about the structure of the new document is passed to the sgml widget as the prolog argument. This argument must contain the document prolog for the new SGML or XML document.
| .s new {<!DOCTYPE BOOK SYSTEM "docbook.dtd">} |
The prolog in the example above has been enclosed in braces to stop Tcl from parsing the prolog argument (which would lead to problems with the string delimiters used in the system identifier). Alternatively, the prolog could have been enclosed in quotation marks while prefixing the quotation marks around the system identifier with a backslash.
Depending on the setup of your catalog files, you may be able to use a simplified approach by providing only the name of the document element in the prolog:
| .s new <BOOK> |
This approach is only possible if your catalog files contain a DOCTYPE entry that tells the underlying SGML parser which DTD to use
for documents with a top-level element of <BOOK>, e.g. an
entry of the form:
DOCTYPE BOOK "docbook.dtd"
Although possible (and supported for interoperability with other SGML
software), we discourage the catalog-based approach for determining
the document type since it results in an empty document prolog which
would prevent the sgml widget from storing user-defined entities in
the prolog (cf. section ). Consequently, the
pcrmentity declare command (cf. section ) is
disabled for documents that do not contain a proper prolog and rely on
a DOCTYPE statement in the catalog. Please refer to
section for more details on catalog entries.
Things can be made easier if you already have a document of the same type as the new document you want to create.
To create a new document of the same type as a document that has already been loaded into the sgml widget, we can ask the widget for the prolog of the loaded document and then use this value as the prolog for a new document:
| set prolog [ .s document prolog ] | |
| .s new $prolog |
The first command retrieves the prolog from the sgml widget and stores it in the Tcl variable prolog. The second command tells the sgml widget to create a new document with the value of this variable as the prolog for the new document.
Note that this approach works only for SGML and valid XML documents since the prolog of DTDless XML documents is missing a doctype statement and does not contain enough information to construct a new document.
When the sgml widget creates a new document, it automatically inserts the document element. It is, of course, up to the user to fill the document with the required content.
Valid XML documents (i.e. XML documents that contain a DOCTYPE
statement and a DTD) are created just like SGML documents (see
section for details).
Because XML documents that are only well-formed do not contain a DOCTYPE statement, the sgml widget does not know about the type of the document element to create. To create such a document, the prolog that is passed to the pcrmnew command must contain the document element for the new document. The following example shows how to create a new DTDless XML document where the document element is labeled X:
| .s new -type xml -encoding XML {<?xml version="1.0"?><X>} |
The document element that is passed in the prolog does not need
to be terminated by an end tag; it is only used to determine the name
of the top level element for the new document. Enclosing the document
element name in tag delimiters (< and >) is mandatory to
distinguish it from other markup that could occur in the prolog.
The occurrence of the XML declaration is recommended, but not mandatory unless the encoding in use requires the presence of an XML declaration.