Working with a document set

What is a document set?

A document set is simply a set of related XML documents. These documents are related because they all contribute to the content of the same deliverable: PDF file, EPUB file, Web site, etc.

When XMLmind XML Editor knows that some opened documents are members of the same set:

• it will more thoroughly check the links which may exist between these documents,
• it will make it easier creating links between these documents.

Modular documents, for example a DITA map referencing a number of topics or a modular DocBook book including a number of chapters, implicitly specify a document set. When you author such modular documents, it is strongly recommended to first open their document set in XXE.

How to open a document set in XXE?

Use File→Document Set→Open Document Set to let XXE know about a given document set. This menu item displays a dialog box allowing to choose the file specifying the document set.

• If the selected file is a DITA map, then the members of the document set are the topics referenced in this map. See figure below.
• If the selected file is a master DocBook document (for example a modular book including a number of chapters, each chapter being found in its own XML file), then the members of the document set are the DocBook documents included in this master document. See figure below.
• In all other cases, the content of the selected file is not analyzed by XXE. Instead, the selected file specifies a directory and a filename extension. For example, selecting file file:/home/john/site/buy.html specifies the "file:/home/john/site/*.html" glob pattern. In this example, the members of the document set are all the files found in directory file:/home/john/site/ having an "html" extension. See figure below.

A document set specified by a DITA map and 3 topic members opened in XXE

A document set specified by a modular DocBook book and 3 chapter or section members opened in XXE

A document set specified by a glob pattern and 3 XHTML page members opened in XXE

The "Document Set" tool

As you can see it in the 3 above screenshots, a document set is represented by a special tool added to the left of XXE's main window: the "Document Set" tool. Each instance of this tool is given a specific, random, background color. This specific background color is also given to the tabs of all the opened documents which are members of the set.

The "Document Set" tool is a convenient, interactive, navigational tool: you can double-click on an element to open in XXE the member document corresponding to this element; dragging the selected element will drag the corresponding member document inside or outside XXE; etc. More information in XMLmind XML Editor - Online Help, Using the "Document Set" tool.

However the most important part of its job is done behind the scene, because opening a document set in XXE automatically modifies the behavior of the Validity tool and the Attributes tool:

• The diagnostics issued by the Validity tool about cross-reference errors will take into account the fact that the document being checked is a member of a set.
• The target of a link is almost always specified as an attribute value (XHTML example: the href attribute of the a element). That's why the Attributes tool, through its auto-completion feature, will suggest, not only link targets found within the document being edited, but also link targets found in the other members of the set.

A simple use case

Modular book mybook.xml includes 3 chapters. Each chapter is found in its own file: chapterA.xml, chapterB.xml and chapterC.xml.

File chapterA.xml contains:

<chapter id="chapterA">
  <title>Chapter A</title>

  <para>Link to <link linkend="nowhere">nowhere</link>. Link to <link
  linkend="sectionB1">Section B1</link>.</para>

  <section id="sectionA1">
    <title>Section A1</title>

    <para>TODO.</para>
  </section>

  <section id="sectionA2">
    <title>Section A2</title>

    <para>TODO.</para>
  </section>
</chapter>

In the above file, the first link element points to a non-existent target and the second link points to the first section of chapterB.xml.

The user wants to check the links found in chapterA.xml and also to add an xref element pointing to the first section of chapterC.xml. In order to do that, she/he opens chapterA.xml in XXE.

Before opening mybook.xml as a document set:

• The Validity tool reports 2 cross-reference warnings: reference to non-existent ID "nowhere" and reference to non-existent ID "sectionB1".
• When the user inserts an xref element and specifies its linkend attribute, the Attributes tool suggests: chapterA, sectionA1, sectionA2.

After opening mybook.xml as a document set:

• The Validity tool reports 1 cross-reference warning: reference to non-existent ID "nowhere".
• When the user inserts an xref element and specifies its linkend attribute, the Attributes tool suggests: chapterA, sectionA1, sectionA2, chapterB, sectionB1, sectionB2, chapterC, sectionC1, sectionC2.

Watch the screencast

(same but in a new window )

Similar use case, but based on a DITA map rather than on a DocBook modular book

Watch the screencast

(same but in a new window )