PSGML needs to know about the DTD you are using for many of its commands.
If you do not have a `DOCTYPE' declaration in your file,
PSGML will try assume that there is one of the form
<!DOCTYPE name SYSTEM>
where name is the value of sgml-default-doctype-name, if
the value is non-nil, else the GI of the first tag will be used.
PSGML will try to parse the document type declaration the first time
you do something that needs to parse the document or immediately if the
variable sgml-auto-activate-dtd is t. You can also
initiate the parsing of the document type declaration with the command
sgml-parse-prolog. Big DTDs take some time to parse.
When the DTD has been parsed or loaded the name of the document element
will be displayed in the mode line inside brackets. If there was an
error parsing the DTD or there is no DTD, the mode line will display
`[ANY]' (*** this is not really correct! a DTD will be established
even if there are missing entities, it may even be empty).
If parsing the DTD takes too long time you can arrange to have PSGML
cache an internal complied version of the DTD. Caching can be done of
DTD fragments in favourable situations. It is possible to have an
external DTD subset cached but still have an internal DTD subset as long
as the internal subset does not define parameter entities that affect
the parsing of the external subset (*** what is the exact conditions?,
probably you can't use the cached external subset if the internal subset
defines parameter entities that are also defined in the external subset
with another value).
To enable caching you have to create special catalog files, hereafter
called ECAT files due to (temporary) lack of imagination. These catalogs
have similar syntax to the entity catalogs and there are two variables
containing lists of catalogs to search: sgml-ecat-files and
sgml-local-ecat-files. The ECAT files can contain the following
types of entries:
`file dtdfileentitydefcfile'
The dtdfile is the name of a file containing a DTD subset that
should be cached in cfile. The entitydef is optional and if
given have the following syntax:
[ name1literal1name2literal2 ... ]
Using entitydef will modify the DTD subset by defining the
parameter entity with name name1 to be literal1, .... The
cached version of the subset will be created with those entity
definitions, and when PSGML search for a matching cached subset will check
that the parameter entities in entitydef has been defined with
those values before trying to use `cfile'.
`public pubidentitydefcfile'
Cache the DTD subset with public identifier pubid in file
cfile.
User Option:sgml-recompile-out-of-date-cdtd
If non-nil, out of date compiled DTDs will be automatically
recompiled. If the value is ask, PSGML will ask before
recompiling. A nil value will cause PSGML to silently load an out
of date compiled DTD. A DTD that refers to undefined external entities
is always out of date, thus in such case it can be useful to set this
variable to nil.
Previous versions of PSGML have had another way of speeding up DTD
parsing. This code remains in this version of PSGML, but is not actively
maintained and may disappear in the future.
You can save the parsed DTD in a file using the command M-x
sgml-save-dtd. Next time PSGML can load that file instead of parsing
the DTD. For PSGML to find the saved DTD you must either save the DTD
using the default name or do a M-x sgml-save-options after saving
the DTD. To directly use an already parsed and saved DTD, load the file
containing the saved DTD with the command M-x sgml-load-dtd.
User Option:sgml-default-dtd-file
This is the default file name for saved DTD. This is set by
sgml-mode to the buffer file name less extension plus the
extension .ced, if that file exists. Can be changed in the Local
variables section of the file.
is a string, the name of the file containing the
document entity.
context-element
is a string, that is the name of an element type.
It can occur 0 or more times and is used to set up
exceptions and short reference map. Good candidates
for these elements are the elements open when the
entity pointing to the current file is used.
top-element
is a string that is the name of the element type
of the top level element in the current file. The file
should contain one instance of this element, unless
the last (lisp) element of sgml-parent-document is a
list. If it is a list, the top level of the file
should follow the content model of top-element.
has-seen-element
is a string that is the name of an element type. This
element is satisfied in the content model of top-element.
*** Describe the DTD menu in general. Describe customized entries for
special DTDs. Mention C-c C-u C-d for inserting a DOCTYPE from
keyboard.
If you change the doctype you must execute sgml-parse-prolog,
changes in the doctype are not automatically recognized.
User Option:sgml-custom-dtd
Menu entries to be added to the DTD menu. The value should be a list of
entries to be added to the DTD menu.
Every entry should be a list. The first element of the entry is a string
used as the menu entry. The second element is a string containing a
doctype declaration (this can be nil if no doctype). The rest of the
list should be a list of variables and values. For backward
compatibility a single string instead of a variable is assigned to
sgml-default-dtd-file. All variables are made buffer local and
are also added to the buffers local variables list.
When an entry is selected from the DTD menu, the doctype declaration will
be inserted, the variables will be set to the values in the entry and a
local variables list will be created in the buffer.