OOo Off the Wall: Master Documents

If you are an MS Word user, and we all have secret shames in our pasts,
you may have fallen into the habit of avoiding master documents--and
for good reason. Master documents in MS Word can crash and corrupt
sub-documents unless they are used so carefully that there is hardly
any reason to use them at all.

But if you have this habit of avoiding master documents, you can change
it when you use OpenOffice.org Writer. Master documents in Writer are
much more stable. They are not immune to crashes, but unless a master
document's size exceeds the available RAM on your computer, you may never
see one. This stability frees master documents in Writer to be what they
were meant to be: a way to organize and write long documents more efficiently.
What Are Master Documents?
Master documents are documents that manage and organize other Writer
documents. They consist of a series of links to individual sub-documents
that can be opened only when needed. They offer a savings in overhead that is
noticeable even on today's high-RAM machines.

When a master document is opened, sub-documents are added to it
as sections. As each sub-document is opened, it is reformatted and
repaginated using the master document's styles and other settings. In
particular, any numbering sequences become continuous. For instance, if a
paragraph style is numbered 4 in one sub-document and the next occurrence
of the style is in the next sub-document, then the next occurrence is
numbered 5 in the master document. This occurs even if that paragraph
style originally was numbered 1. The sub-documents then can be printed
or exported as a single document.

What makes master documents useful is these changes apply only
within the master document. If you save the sub-documents as part of a
master document and then open them again as separate documents, they
revert to their original formats and page numberings.
When to Use Master Documents
Master documents are useful in several circumstances:

• If your computer's memory is limited: Experiment to find the maximum
  document size that your computer can handle without grinding. Sub-divide
  your document into files equal to or smaller than the maximum size. Only
  assemble your documents into a master document when you are ready
  to print.
• When material has to be used in different places: A file
  can be used in any number of master documents, so you can re-use it as needed. However,
  because the master document formatting takes precedence over sub-document
  formatting, either try to ensure that all the master documents using the
  same sub-document have the same formatting, or be careful not to save a file
  while more than one master document is open.
• When a document is divided into chapters: You then can use the special
  master document view in Navigator to help move around and work with
  the shorter sub-documents instead of the long document. In other words,
  the master document becomes a floating window that stores the documents
  to which you are most likely to refer.
• You want two or more documents that are similar except in some parts:
  You can add all the files for all the documents and then hide or un-hide
  individual sub-documents before printing or exporting.

Understanding Master Document Contents
Master documents are built from three sources:

• Separate files, or sub-documents: Sub-documents are treated as sections
  of the master document and have the same options as sections within a
  normal document. Within the navigator, sub-documents are listed by their
  file names.
• Text: Areas before, between or after the sections for
  sub-documents. Although anything can be added to text areas in a master
  document, putting a lot in them defeats the purpose of using a master
  document in the first place. In a well-planned document, you should
  generally not need to use extra text. Here's another reason to avoid
  them: text areas are listed in the master document view in the Navigator with
  the unhelpful title of "Text". The main use for text areas is
  spacers between separate files for pagination.
• Indexes and tables: Inserted into text areas of the master document,
  indexes and tables such as Tables of Contents and Alphabetical Indexes
  can provide references to the contents of
  sub-documents.

Planning Master Documents
Master documents simplify the management of long documents. However,
using them to their full advantage still requires some organization. Here are
some suggestions for working with master documents and getting the most
from them:

• To minimize the chances of formatting problems, use the same template to
  create the master document and all its sub-documents. If some documents
  are used in more than one master document, try to make sure that all of the
  master documents use the same template, too. If using the same template
  is not possible for some reason, consider adding the sub-document as
  an OLE Object instead, using Insert > Object > OLE Object to preserve
  its formatting.
• Whenever possible, place each master document and all of its sub-documents in
  the same directory. A convenient strategy is to place the sub-documents
  in a sub-directory of the folder that holds the master document. Use another
  sub-directory for graphics. If some documents are used in
  more than one master document, create a sub-directory only for
  them.
• Ordinarily, you probably want each part of a master document to start
  on a separate page. You can set up this format automatically by using the
  Breaks section on the Text Flow tab to start a new page
  after:
• The Heading paragraph style for each index and table, for example,
  Contents Heading for a Table of Contents.

  The first paragraph style used in each sub-document, probably Title,
  Heading 1 or possibly a created style called something like Chapter
  Number.

• The convention is to start each new part of a long document on a
  right, odd-numbered page. Open a book, and you will see why: most
  readers' eyes fall on the right page first. Because the start of a new
  part is one of the main guides for finding information, you want it to
  be as prominent as possible. To ensure that the parts start on a right page,
  start at the beginning and go through the master document, adding manual
  page breaks in the Text areas wherever they are needed. Starting each
  part on a new page also minimizes reformatting.
• Aside from tables, indexes and page breaks, minimize the content
  that is added to the master document directly. Add it to the
  sub-documents instead. The more content added directly to the master
  document, the less flexible it becomes.
• Because of the kludges required to add some cross-references
  to a master document, place them in a paragraph of their own to prevent unexpected
  reformatting in the master document.
• Use page styles and/or manual page breaks to use different numbering for
  different parts of the master document. For example, one common format is
  to use lowercase Roman numerals for front matter, such as copyright pages
  and tables of contents, and Arabic numbers for the main text. And often,
  numbering is restarted with the main text.

Making a Master Document
If the sub-documents use the template currently selected as the default,
you can start a master document by selecting File > New > Master
Document. Otherwise, follow these steps:

1. Start a new document based on same template that all
   the sub-documents use.Technically, this step is optional, because you can use any
   template. However, a master document template overrides the
   templates used in sub-documents, so if you ignore it you are likely to
   have reformatting problems. If you save the sub-documents after using
   them in a master document with another template, the document is
   reformatted. If a sub-document is used in more than one master document,
   you quickly can compound the problem.
2. Select File > Send > Create Master Document.The Name and Path of Master Document screen opens. This screen is a
   variant of the Save screen designed for master
   documents.
3. Choose a name for the document and the paragraph style at
   which the current document should be divided into sub-documents.If you are creating the master document from a blank document, the
   paragraph style does not matter. If the source document has contents,
   ordinary Writer documents then are created with the same name as the master
   document. The master document is saved with an .sxg extension.Select the Save button. If the source document had content, a query
   screen opens to update links.
4. Select the Yes or No button to
   continue.
5. If you created the master document from a blank document, open the
   Navigator. Either select Edit > Navigator or press the F5
   key.The Navigator opens in the master view. If you started with a blank
   document or chose a style that was not current, then the only entry is
   Text. If you started with a document that had contents, the Navigator
   lists the new sub-documents.
6. Save the master document. The master document is saved with an .sxg
   extension. This option is available only in a master document.

Navigating Master Documents
Master documents have a special view in the Navigator. You move between
the master view and the normal view by selecting the Toggle button in
the upper left side of the toolbar. In the master document view, you can
add, delete and reposition sub-documents, as well as open them for
editing. In other words, the master document view converts the Navigator
into a floating window for your work, with all of the associated files and
pieces visible.

In the normal view, in case you were wondering, the master document
displays as though it was a single document. No file names or text areas
are listed.
Editing Contents in a Master Document
How you edit contents in a master document depends on the type of content:
Content TypeHow to EditText AreaNavigate to the text area and then place the cursor in the text area.
Text can be edited as in any other document.Index or TablePlace the mouse cursor in the index or table. Then,
select Edit Index/Table from the right-click menu.Sub-DocumentSelect the sub-document from the Navigator. Then, select
Edit from the right-click menu.Sub-Document SectionSelect the sub-document from the Navigator. Then,
select Edit Link from the right-click menu to open the Edit Sections
screen. Changes made to the section apply only within the master document. The
most useful change to make is hiding or un-hiding that section. By
changing this setting, you can use the master document to provide two
different versions of the same document.Updating Master Documents
You may need to update a master document when:

• You have edited a sub-document. Use the Update button in the Navigator's
  master view.
• You open a master document and sub-documents have been
  edited since you last closed the master document. Select Yes at the query window when opening
  the master document. Because you always want to keep the master
  document updated, you should have no reason not to update when
  opening.

Adding Cross-References in Master Documents
Adding cross-references in a master document is similar to adding
cross-references in a standalone document. In both cases, you set
the text to use for the reference and then add the cross-reference. The
difference with master documents is you cannot create a permanent cross-reference in
a master document, even if you turn off the write-protection for a
document's sub-section. In addition, you cannot read a reference in one sub-document
from another sub-document.

The solution is to note the reference's name as you create
it and then enter it for the cross-reference in the second
document. The cross-reference field in the second document is
blank when you are viewing only the second document, but it displays
the reference within the master document. For details, see:
"Fielding Questions,
Part 2: Cross References and User-Defined Fields".
Conclusion
Master documents aren't a feature of Writer that everyone needs. If you never
write documents longer than 30 pages, you probably can ignore them
entirely. However, if you ever write anything longer--especially
a document that shares some parts with other documents--take the
time to learn about them. The chances are, you'll find that master
documents are just what you need to automate your work. And if you've ever used
books in FrameMaker, you'll greet them them with a sigh of relief.
Although the name may bring back memories of corrupted files in MS
Word, Writer master documents are far closer to FrameMaker books in
both functionality and stability.

Bruce Byfield is a computer journalist and course designer. His articles
appear regularly on the Linux Journal and Newsforge Web sites.