The following is a procedure that I have tested and almost perfected over the past couple of months to make a FrameMaker User Guide (and hence a PDF file) from a set of DITA topics originally targeted as online help.
1. I want my User Guide to have a classic "book" structure rather than the Task/Reference/Concept structure of the online help, so I create a separate DITAMAP file specifically for the User Guide. Bear in mind that only top-level topic references in the DITAMAP file will map to chapters in the FrameMaker book.
2. Create a DITAVAL file. Create or register this DITAVAL file with DITA-FMx using the DITA-FMx > Ditaval manager menu option. Create two entries in the DITAVAL file; "print" and "online". For the User Guide, you'll need to set the print action to "include" and the online action to "exclude". For example:
<val>
<prop att="audience" val="print" action="exclude" />
<prop att="audience" val="online" action="include" />
</val>
3. Add any User Guide-specific content to your DITA topic files. For example, I want screen captures to appear in the User Guide but not in the online help, so I add <fig> elements wherever appropriate. Set the audience attribute on the
4. In the DITA-Fmx options window, set the DITA book application to the appropriate "book generation" application. Your application developer should have set this up for you: basically the Book application is a Structured application registered with FrameMaker that points to all the Template, EDD, and DTD files necessary to generate the book. You can review the available applications with StructureTools > Edit Application Definitions. The value of the ApplicationName element is the name that appears in DITA-Fmx's list of available applications.
5. Choose DITA-FMx > Generate Book from Map. You will probably get a "Validation of XML file failed" message box with a bunch of errors. Ignore these for now.
6. Choose the book name. You will be using a "dummy" book originally, so I generally call it something like "DUMMY.book".
7. When the Book window appears, save it immediately with the "real" name (File > Save book as).
8. Working now with the "real" book, add title page, front matter, and back matter files as necessary. I typically have Titlepage, Preface, TOC, and Index files, for example. Add these in a "nonstructured" way as you would with unstructured FrameMaker.
9. I generally use the Titlepage document to contain all the universal variables that I use in the unstructured files and in the headers and footers of the structured files. For example, I set up ProductName and BookTitle variables. This way, I can easily import the variables into all the unstructured and structured files. More of this later.
At this stage, you'll probably want to do a bout of debugging to set up the "real" book exactly as you want it. For fixes to the structured files, obviously do them in the original DITA topic files and DITAMAP, or they'll get overwritten the next time you re-generate the "dummy" book.
When everything is set up as I want, I proceed as follows whenever I need to re-generate my User Guide:
1. Make the User Guide DITAMAP file the current document.
2. Check that the DITAVAL file is set up with "print=include" and "online="exclude".
3. Choose DITA-FMx > Generate Book From Map. Overwrite the "dummy" book file and confirm overwriting all files.
4. Close the "dummy" book file and open the "real" book file.
5. Open the Title page and import its variables into all other files in the book (File > Import > Formats).
6. Apply the correct Master pages to the generated files in the book (Format > Page Layout > Apply Master Pages).
7. Run DITA-FMx > Apply Ditaval as conditions. This sets all text that is marked as "exclude" in the DITAVAL file as conditional text and hides it.
8. Optionally, turn off Conditional text indicators in each of the generated files (by default, text tagged with the "print" action appears in red).
9. Generate the book (Edit > Update book).
10. When it's what you want, File > Save as PDF and create your PDF file.
I have this second procedure down to about 5 minutes per book now!
The only caveat is that if ever you update your DITAMAP with a new top-level entry that causes a new FrameMaker chapter file to be created, you'll need to remember to manually add the new file to the "real" book.
One other "bug" I have noticed is that if you use the locktitle attribute in your DITAMAP to specify Title text specifically for the User Guide, the navtitle text doesn't get copied to the PDF bookmarks when you generate a PDF file. Hopefully this will get fixed in a future release.
No comments:
Post a Comment