This document describes the specification for the addition of a book file to the MIF doclet. The book file provides a way of allowing the user to customize the order of the class and package files, add chapters, front matter, back matter, and book variables (replacing 36 command line options) all in a single file.

Add option to MIF Doclet to call book file:

     -book <file.xml>

Book File XML Format

DocBook File XML Format (not implemented)

1. Book file should contain two basic kinds of items:
   • A list of all packages and classes in the order to be documented. We call this the classlist. Also list front matter, table of contents, chapters, index and back matter. It is conceptually similar to the FrameMaker book file.
   • Options for content and format specific to any book. These are currently implemented as command line options. Moving them into the book file reduces the number of options dramatically, from 43 to 7.

2. User can design and set up FM templates for a generic type of book and create individual book files for specific books

   The book file should let you publish a new book on a completely different set of packages with the same look that the templates provide. The only other requirement would be changing the options -book, -sourcepath, -d and possibly -J-Xmx.

   This means once the design is fixed, NO EDITING OF FRAMEMAKER FILES IS NEEDED to create books on new packages. Text can come from two sources: doc comments in the source code and narrative sections written in HTML (which can also be included in the source tree). For example, you could produce separate, finished books and PDF documents on JavaMail, JavaSpaces and JINI without having to open or look at a FrameMaker file.

3. Allow:
   • A single master book file for all books that have the same structure, and
   • Individual nested "subbook" files for individual books within that group.

   In other words, as a corollary to goal #2 above, once you design and set up FM templates and master book file, have the ability to publish an entire book by setting up only the subbook file (and the 4 mentioned options). The master book file could contain:

   • boilerplate files
   • shared files
   • <include classlist>
   • <include subsection> (where a subsection is any series of filenames and/or book variables)
   • book variables (Bookfilename, ImportFormats, StylemapFile, Booktitle, BookSubtitle, BookAuthor, Book Version, BookCopyright, BookPublisher, BookDedication, OverviewFilename, OverviewTree, MemberHead, MemberSummmary, SummaryTablewidth, CommentTablewidth, Split, SortMembers, Author, Version, NoPackageSummary, NoDeprecated, etc...)

   Each "subbook" could have its own:

   • classlist
   • values that override the book variables
   • subsection (for example, allow the book to override the order that front matter files occur, or add a foreword, or remove a dedication without modifying the master book file)

   To support nested subbooks:

   • Create generalized functionality to search and replace any text in a MIF file. This would enable someone to create their own placeholder to be replaced. For example, they might add <BookTrademarkNotice> to the title page to be replaced by text they supply in the book file.
   • We might also need the ability to set a variable in the book file that will create a new FrameMaker variable in a MIF or FM file. If you look in Special > Variable, it lets you define and set FrameMaker variables. These are used in headers, footers and body text. For example, someone might create a new variable <FrontmatterHeader text> to set the header in front matter that is different from the header in the chapters.

4. Make bookfile easily readable
   • Allow list of packages and classes (which here we shall call classlist) to be in a separate file, and included by reference. Not knowing the "include" mechanism in XML, for illustrative purposes, I will indicate this by <include classlist>. This keeps the book file to about 100 lines, regardless of the number of classes. This also makes it easier to independently auto-generate classlist.
   • Consider allowing classlist to be interpreted as XML if it has an XML extension, but as text (actually, as a sequence file) if no XML extension. This makes the file easier to generate by other tools.
   • Place options with relevant content, so their scope is made obvious. XML makes this natural, as options can be placed within a section, such as frontmatter, chapters, backmatter, etc.
   • Allow easy way to sort packages and classes alphabetically. In this case, rather than requiring the packages and classes be listed, omitting the list triggers the default to list them alphabetically.
   • When converting options to variables, standardize their form to be easily readable. Also, no longer limited to fixed number of arguments per option. For example, change "-descriptionhead opcm" to <DescriptionHead overview package class member>

5. Want choice in the future to be able to:
   • generate book with most up-to-date master book and
   • re-generate entire book at any time in future exactly as it was last generated, even if the master book has changed (assuming template files have not changed)

   Solve this by writing a file at each run that is the book file but with all includes interpreted. The classlist would also be made explicit if it were previously implicit (because the default alphabetic order was used). Filename format: snapshot-yymmdd-time.xml, for example snapshot-000916-1200.xml. Put these in a directory "snapshot-bookfiles".

   The rationale for this is that the master file might be under someone else's control, and could change after your book is produced. This might also aid in debugging.

6. Allow FrameMaker and HTML files for chapters.

   I believe we currently allow only HTML files to define a new chapter (perhaps not even that, if that code is broken since removing styles.mif) Consider allowing multiple HTML files within a single chapter (not previously allowed).

7. Auto-generate the classlist for the user to re-order.

   Because a complete list includes inner classes, it is not possible to get a list of classes from a directory listing. Therefore, the doclet needs to generate this list. (Both static and non-static inner classes should be included in this list. By contrast, only static inner classes should be in the table of contents.) This list can be part of the snapshot mentioned above.

8. Allow easy updating of classlist as source code is developed.

   If someone provides a classlist (to reorder the classes), it would be useful to have a way to easily tell at a later date if any classes have been added to the source tree. There are a couple of possible ways to do this:

   • Automated - Have the doclet create an alphabetical list of all classes in the source tree, diff it against alphabetized classlist, then generate a diff report.

   • Manual - Automatically generate an alphabetical classlist every run (like stylemap.properties). This gives the user a list they can manually diff against the source tree to see if all classes are present. It would help for the list to contain a comment that gives the package and class count, like:

               # package count: 60, class count: 570
     

9. Allow all content specific to a particular book to be stored in text files (.java, .html) in the source tree. It therefore follows to allow relative paths to filenames in the book file to be relative to the source tree -- use -sourcepath for this.