DOCBOOK: Split documents using psgml

["Jens M. Felderhoff" <jmfelder at baan dot com>]

I have a large document which is split into several files. The
structure of the master file master.sgml is:

    ...
    <!ENTITY sect1-file SYSTEM "sect1.sgml"
    ...
    <sect1>
    <title>This is Section 1</title>

    &sect1-file;
    </sect1>
    ...

In sect1.sgml:

    <para>Mary had a little lamb...</para>

    <sect2>
    <title>Gobbledygook</title>

    <para>...</para>
    </sect2>

Now when I want to create another <sect2> using PSGML's C-c C-e
command, the only valid completions PSGML will accept are "sect1" and
"section".

In sext1.sgml I have set the Emacs file-local variable
"sgml-parent-document" to the value

    ("master.sgml" "sect1" "sect1" ("title"))

Neither does it work with the value

    ("master.sgml" "sect1" "para")

The documentation of the "sgml-parent-document" variable is somewhat
confusing and I'd like to get some insight in the meaning of the
components of the variable. From the documentation:


          (PARENT-FILE CONTEXT-ELEMENT* TOP-ELEMENT (HAS-SEEN-ELEMENT*)?)

[...]

    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.

Is that "sect1" because it is open in master.sgml?

    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.

The current file (sect1.sgml) has *two* top level elements (para and
sect2). Is that permissible at all or must the whole contents of
sect1.sgml be wrapped in exactly one element? In my case I assume
that the unless-part of TOP-ELEMENT's description holds, so I set
sgml-parent-document to

    ("master.sgml" "sect1" "sect1" ("title"))

What is the proper way to do it?

Cheers

Jens