Creating a User Guide using a Master Document

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.

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

1. Be sure the *.odt file for the changed chapter is in the Published Chapters folder for the book.
2. If any new names have been added to the Authors section of the copyright page, take a note of them.
3. Open the *.ODM (master doc) file for the book. When asked "Update all links?" click Yes.
4. Wait while the file loads, paginates, and regenerates the table of contents. This may take several minutes.
5. Check that the Authors section of the master document's copyright page includes all the authors for the changed chapter.
6. Change the publication date on the copyright page to the current date.
7. Because of a bug in OOo, the first item in the first list in each chapter from Chapter 2 on may not be numbered "1" as it should be; it may continue the numbering from the last list in the preceeding chapter.
   
   Therefore you need to scroll through the full book file and if necessary reset to "1" the number of the first item in the first list in each chapter. If you cannot reset the number, that means the chapter is in a write-protected section. Go to Format > Sections and uncheck the Protected checkbox under Write protection. Now you can reset the list item to 1.
   
   Note: All manual changes to chapters in a master document will be lost when you close the file, so do not close it until after you have done the next step.
8. Another bug in OOo 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. It is best to fix the x-refs by opening the subdoc itself, deleting the wrong x-refs, and recreating them-- even though it appears correctly in the subdoc. This will often cure the problem (for that x-ref) in the master document, but it is no guarantee.
9. In the master document, select File > Export as PDF. Name the file according to the naming convention for published documents (see below).
10. Upload the changed master doc file and the PDF file to the Published Chapters folder for the relevant book, overwriting the previous version of the master doc and the book.
11. Tell the Authors list that you have republished the book.
12. Jean Weber uploads new and revised PDFs to the Documentation Project's website. Only people with CVS access to the Doc Project can do this. If Jean is away for an extended period of time, then you will need to create an issue at Docs, mark it as a task, assign it to "grsingleton", attach the PDF, and request that it be uploaded to the OOOAuthors2 directory and (if it is a new chapter) that it be added to the index.html page in that directory.

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:
AA00CC-Name.pdf, where
AA=book number, 00=book (these are zeros), CC=book initials, 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 book is
0100GS-GettingStarted.pdf