Grouping documents in XML projects

Large Documents

Let's consider the case of documenting a large project. It is likely to be several people involved. The resulting document can be few megabytes in size. How to deal with this amount of data in such a way the work parallelism would not be affected ?

Fortunately, XML provides a solution for this. It can be created a master document, with references to the other document parts, containing the document sections. The users can edit individually the sections, then apply FOP or XSLT over the master and obtain the result files, let say PDF or HTML.

Two conditions must be fulfilled:

  • The master should declare the DTD to be used and the external entities - the sections. A sample document is:

    <?xml version="1.0" encoding="UTF-8"?> 
    <!DOCTYPE book SYSTEM "../xml/docbookx.dtd" [ 
    <!ENTITY testing SYSTEM "testing.xml" > ]
    > 
    <book> 
    <chapter> ...                
    

    At a certain point in the master document there can be inserted the section "testing.xml" entity:

    ... &testing; ...

  • The document containing the section must not define again the DTD.

    <section> ... here comes the section content ... </section>

    Note

    The indicated DTD and the element names ( "section", "chapter" ) are used here only for illustrating the inclusion mechanism. You can use any DTD and element names you need.

When splitting a large document and including the separate parts in the master file using external entities, only the master file will contain the Document Type Definition (the DTD) or other type of schema. The included sections can't define again the schema because the main document will not be valid. If you want to validate the parts separately you have to use XInclude for assembling the parts together with the master file.

Creating an included part

Open a new document of type XML, with no associated schema.

You can type in the edited document the root element of your section. For example, if you are using DocBook it can be "<chapter></chapter>" or "<section></section>". Now if you are moving the cursor between the tags and press "<", you will see the list of element names that can be inserted.

Figure 4.27. Content Completion list over a document with no schema

Content Completion list over a document with no schema

Note

The validation will work on an included file that has no DTD set only if you associate the file with a validation scenario that specifies the master file as the start point of validation. Without a validation scenario you can only check the included file to be well-formed.