You are here: Home / OpenOffice.org / English / Userguide3 / Resources for contributors / Creating a User Guide using a Master Document

Creating a User Guide using a Master Document

Summary of steps an editor takes to produce an updated copy of an OOoAuthors user guide.

The user guides being produced by OOoAuthors consist of a set of individual chapter files, plus a master document file that combines the chapter files into a book.

The chapter files have been designed so that the copyright page and the chapter's table of contents pages are in a conditional section which is hidden when the chapter is part of a book.

The master document file contains a copyright page listing all the authors of all the chapters in the book and a table of contents for the full book, a TOC for the entire book, and an index for the entire book.

When you have published several changed chapters in a completed book, you need to regenerate the full book. To do this:

  1. Be sure the *.odt files for the latest version of all chapters are in the Published Chapters folder for the book.
  2. Download all the *.odt (chapter) files and the *.odm (master document) file and place them in a folder on your computer.
  3. If any new names have been added to the Authors section of the copyright page of any chapter, take a note of them.
  4. Open the *.ODM (master doc) file for the book. When asked "Update all links?" click Yes.
  5. Wait while the file loads and paginates; this may take several minutes. To avoid errors, do not do anything with the file until it finishes paginating; do not even scroll through the file.
  6. If any chapter files do not load, you may need to edit the path for those files in the Navigator for the master document. Problem files are shown in red in the Navigator.
  7. When all the files have loaded and the book has finished paginating, regenerate the table of contents and index by right-clicking on each of them and choosing Update from the pop-up menu.
  8. Check that the Authors section of the master document's copyright page includes all the authors for the changed chapters.
  9. Check that the information in File > Properties is correct.
  10. On the copyright page, change the publication date to the current date, change the OOo version information to the version covered by the book, and check that the email address for OOoAuthors and the URL for the published chapters (given in the footer) are correct.
  11. Check that the footers show the correct information: book title on left-hand (even) pages and chapter title on right-hand (odd) pages.
  12. Check that the first item in the first numbered list in each chapter from Chapter 2 on is numbered "1" as it should be; it may continue the numbering from the last list in the preceeding chapter. If necessary, OPEN EACH PROBLEM CHAPTER and explicitly restart at "1" the number of the first list paragraph in the first numbered list in each chapter. To do this:
    1. Right-click on the first list paragraph and choose Paragraph.
    2. Go to the Outline & Numbering tab. In the Numbering section, select the checkbox for Restart at this paragraph and select the checkbox for Start with, making sure the number is 1.
    3. Click OK to save the change.
  13. Check that the copyright pages and TOCs of the individual chapters do NOT appear in the book, and that the [Component} Guide paragraph does not appear on the individual chapters' title pages. Fix in the problem chapter as needed.
    Note: Do not make changes to chapters within a master document, because they are lost when you close the file.
  14. Review the compiled index. If any entries need to be changed, open the relevant chapter and make the changes in the chapter file, not in the index visible in the master document. See also How to index a user guide chapter.
  15. If you have made any changes to the chapters, reload the master document and wait for it to paginate again. Recheck to ensure all is well. Repeat as needed.
  16. A bug in OOo (or a gremlin in some of our older files) causes some figure and table numbers, and some cross-references to figures and tables, to be incorrect in the master doc, even though they are correct in the subdocs. You really need to go through the entire book, checking and fixing any incorrect figure numbers or references. This is a major PITA, so we do not regenerate the books very often. To fix the x-refs, open the subdoc itself, delete the wrong x-refs, and recreate them—even though they appear to be correct in the subdoc. This will usually cure the problem (for that x-ref) in the master document. After editing the subdocs, reload the chapters into the master document.
  17. When all changes have been done, regenerate the TOC and index in the master document. Save the master document.
  18. Create one ODT file from the master doc and its subdocs, as explained in Chapter 13 (Working with Master Documents) in the Writer Guide. Remove the links to the sections, to embed the text into the ODT file. Then either remove the write protection on the sections or remove the sections completely (the contents remain; only the section markers are removed). Name this ODT file according to the naming convention for published documents (see below).
  19. Check the ODT file you just created again to make sure the cross-references, page breaks, list numbering, and other potential problems are fixed.
  20. Select File > Export as PDF. Choose the following settings:
    • On the General tab, select Export bookmarks.
    • On the Initial View tab, in the Page layout section, select Continuous facing.
  21. Name the PDF according to the naming convention for published documents (see below).

Publishing the book

  1. Upload the changed master doc file, the ODT file containing the full book, and the PDF file to the Published Chapters folder for the book, replacing the previous version of the master doc and the book. Set the state of the master doc (.odm) and the PDF to "externally visible" but set the state of the ODT as "internally published".
  2. If any chapter files have been modified during book production, upload the changed files to the Published Chapters folder for the book, replacing the previous versions. Set the state to "externally visible".
  3. Log in to the OpenOffice.org wiki and replace the book file (PDF). To do this:
    1. Use an address similar to http://wiki.services.openoffice.org/wiki/File:0100GS3-GettingStartedOOo3.pdf to get to the File History wiki page for the book.
    2. Choose Upload a new version of this file.
    3. On the Upload File page, browse for the book file, type something in the File Changes box (usually "corrected typos" or "updated for version x.x" or similar is sufficient). Select the Ignore any warnings checkbox and click the Upload file button.
  4. Go to the User Guides page. Edit that page to show the publication date and file size for the revised book.
  5. For the convenience of translators, create a zip file containing the master document (ODM) and all the individual chapters (ODT). Create another zip file containing all the individual PDFs. Upload these zip files to o the Published Chapters folder for the book, replacing the previous versions. Set the state to "externally visible".
  6. Tell the Authors list that you have republished the book.

Naming convention for published books

To ensure that chapters and books are listed correctly on the Documentation Project's website, file names take the following form:
AA00CC3-Name.pdf, where
AA=book number, 00=book (these are zeros), CC=book initials, 3=OOo3, Name=Chapter name.

Book number and initials:
01 = GS = Getting Started
02 = WG = Writer Guide
03 = CG = Calc Guide
04 = DG = Draw Guide
05 = IG = Impress Guide
06 = MG = Migration Guide
07 = BG = Database Guide

The book name is given in full; each word begins with a capital letter and there are no spaces between words. So for example, the file name for the Getting Started with OOo3 book is
0100GS3-GettingStarted.pdf


Legal Disclaimers and Limitations | Privacy Policy | Impressum (Legal Info) | Copyright information: Unless otherwise specified, all text and images on this website are licensed under the Creative Commons Attribution-Share Alike 3.0. License. This does not include the source code of LibreOffice, which is licensed under the Mozilla Public License v2.0.

"LibreOffice" and "The Document Foundation" are registered trademarks in one or more countries. Their respective logos and icons are also subject to international copyright laws. Use thereof is explained in our trademark policy.