Working with master documents
What is a master document?
The following documents may be used as master documents: DITA map, DocBook 5.1 assembly, DocBook modular documents (for example, a book including chapters by the means of XInclude).
In order to use a document as a master document, simply open this document and check ToolsUse as Master Document. This is done once for all as this choice is is persistent across editing sessions.
Declaring a document as being a master document creates a document set containing the master document and its module document. This document set is automatically updated when the master document is saved to disk.
Notice in the screenshots below that XXE gives the same distinctive color to the tabs containing the master document and its module documents. This makes it easier for the user to spot the members of a document set.
Why check "Use as Master Document"?
By grouping a master document and its module documents, you inform XMLmind XML Editor (XXE) that all the module documents referenced or included, directly or indirectly, by the master document are related. When XXE knows that some of the opened documents are related:
- it will more thoroughly check the cross-references which may exist between these documents;
- it will make it easier creating cross-references between these documents;
- it will make it easier following cross-references between these documents;
- if a DITA map contains key definitions, then this map acts not only as a cross-reference creation/validation context for its topics, but it also acts as a key space;
- if the "Easy Profiling" add-on has been installed, then the conditional processing profile selected for the master document is automatically shared by all module documents;
- if the document view area is split in two parts, the module documents opened from a master document will appear at the opposite of this master document. This allows to use the view of the master document as a rudimentary navigation pane.
Use case explaining the enhanced cross-reference creation/validation provided by a master document
DITA map
mymap.ditamap references 3 topics: topicA.dita,
topicB.dita and topicC.dita.
File
topicA.dita contains:
<topic id="topicA">
<title>Topic A</title>
<body>
<section id="sectionA1"><title>Section A1</title><p>TODO</p></section>
<section id="sectionA2"><title>Section A2</title><p>TODO</p></section>
</body>
<related-links>
<link href="nowhere.dita">
<linktext>Link to nowhere</linktext>
</link>
<link href="topicB.dita#topicB/sectionB1">
<linktext>Link to Section B1</linktext>
</link>
</related-links>
</topic>In the above file, the first link element
points to a non-existent target and the second link points to
the first section of topicB.dita.
The user wants to check
the links found in topicA.dita and also to add an
xref element pointing to the first section of
topicC.dita. In order to do that, she/he opens
topicA.dita in XXE.
Before using
mymap.ditamap as a master document:
- The Validity tool does not report any error, even for
<link href="nowhere.dita">. - When the user inserts an
xrefelement and specifies itshrefattribute, XXE suggests just:#topicA,#topicA/sectionA1,#topicA/sectionA2.
After using mymap.ditamap as a master
document:
- The Validity tool now reports 1 cross-reference warning:
"nowhere.dita" does not belong to this document set. - When the user inserts an
xrefelement and specifies itshrefattribute, XXE now suggests:#topicA,#topicA/sectionA1,#topicA/sectionA2,topicB.dita,topicB.dita#topicB/sectionB1,topicB.dita#topicB/sectionB2,topicC.dita,topicC.dita#topicC/sectionC1,topicC.dita#topicC/sectionC2.
