This document describes an automatic document generation system used at Mentor Graphics that is based on Perforce for document management. It includes InfoHubs for delivering documentation, a pubs4d utility that monitors a Perforce depot for document changes and triggers regeneration, and build reports that provide links to the regeneration results. The system aims to hyper-automate the documentation "end game" and free authors to focus on writing by handling the processing and publishing of documents.

1. 1
A Perforce-based Automatic
Document Generation System
Chris Shaw
Writer, DVT Division
Mentor Graphics Corporation
chris_shaw@mentor.com
Logo area

2. 2
Chris Shaw
• MA Math, UC Santa Barbara
• 35 years tech writer: Intel, Cadence, Mentor…
• 12 years documenting design verification software
• Taught Perl @Cadence
• Interests: document generation automation,
publishing, gardening and dog showing

3. 3
Agenda
• InfoHubs
• pubs4d
• Build Reports
• Other Features
• Summary

4. 4
InfoHubs
Mentor Graphics Document Delivery Platform

5. 5
InfoHubs
• Doc delivery platform
• Unique per software tarball
• HTML & PDF versions of
each manual
• Advanced features
• Google-based intra-InfoHub
search
• Targetable topics
• Javascript based

6. 6
InfoHubs (HTML/PDF)
HTML PDF

7. 7
InfoHubs (Search)

8. 8
DocGen and Dmerge
• Document Generator
• DocGen developed by MGC
Tech Pubs Support
• Reads FrameMaker books
• Generates HTML & PDF
versions of each book
• Accessible via Website or
Linux Utility
• Handles a package of books
at a time
• InfoHub Updater
• InfoHub structure is hand
crafted.
• Dmerge updates all links
after a DocGen run

9. 9
Documents in Perforce
• DVT Division
• Uses Perforce for software
development
• Natural depot for manuals
• DVT Tech Pubs
• Stores manuals in a techpubs
depot
• Manuals follow MGCTP
standard structure
• Files: *.fm, *.book, README,
graphics/*.jpg

10. 10
pubs4d Utility
Perforce-based InfoHub Generation Daemon

11. 11
pubs4d Utility
• Perl utility
• Started as doc generation
script to simplify “end game”
• Added Perforce front end
• Migrated from old doc
generation scripts to DocGen.
• Daemon process
• Wrapper to DocGen
• Monitors techpubs depot
• Doc update causes pubs4d to
package the manuals and
dispatch to DocGen
• Post-generation
• Manages target data
• Updates Build Reports
• Runs checklinks routine

12. 12
pubs4d Utility
Log Output
Tuesday, March 19, 2013 4:06 PM: Processing docgen job
with 4 books.
0.0 Syncing FM files in /zin/pubs/docs/build directory.
qformal10.2 command_ref (10.2)
qformal10.2 autocheck_user (10.2)
qformal10.2 tutorials_user (10.2)
qformal10.2 cdc_user (10.2)
0.6 Sending job to docgen.
17.1 -->qformal10.2 tutorials_user....OK.
Fixing HTML for /zin/pubs/qformal10.2/htmldocs.
Copying conversion reports to dev/qf10.2/LOG.
Checking for Warnings.
Found 3 warnings.
Updating master build report.
. . .
Code snippets
$_ = `p4 -c cshaw-build sync -p $depot/$dir/... 2>&1
|tee -a $log2`;
if ($? != 0 or /can't sync/s){
print LOG1 "(Error: sync failed. Skipping....)n";
next MANUAL
}
. . .
printf LOG1 "%4.1ftSending job to docgen.",
(time - $time)/60;
$_ = `docgen -source $docgen_driver_file 2>&1
|tee -a $log2`;
sleep 240; #--- give docgen a chance to get started
print LOG1 "n";

13. 13
pubs4d Utility
Dynamic LOG Files
#---- Sub: display_xterm_log <geometry>, <title>, <logfile>
sub display_xterm_log {
if (fork == 0){
system 'xterm', '-sb', '-sl', '4000', '-geometry',
@_[0], '-title', @_[1], '-e', '/usr/bin/perl','-e',
qq^
$ptr = 0;
while (1){
$| = 1;
sleep 3;
next unless open LOG, "@_[2]";
seek LOG, $ptr, 0;
while (<LOG>){print}
$ptr = tell LOG;
close LOG
}
sleep; ^;
exit
} return
}
LOG1
Top
log
LOG2
Detailed
log

14. 14
Build Reports
Hyperlinked Web Page of DocGen Results

15. 15
Build Reports
• DocGen results
• Updated by pubs4d
• 1 entry per manual (includes
timestamp, release ID and
depot)
• Links to multiple DocGen
reports
• Other Helpful Links
• Development InfoHubs
• Checklinks results
• pubs4d Logs

16. 16
Build Reports
Translate No-Go
ERROR: fmprintdr.ps: Cannot open imported graphic file /wv/
techpubs/docgen/jobs/1303061301ukhparts/pdf/
quickstart_cdc_user/graphics/quickstart_autocheck.jpg.

17. 17
Build Reports
HTML Conversion Report

18. 18
Build Reports
HTML Graphics Report

19. 19
Build Reports
Conversion Errors/Warnings Report

20. 20
Build Reports
• Development InfoHubs
• Documents in the Dev area
• Not yet promoted to Release

21. 21
Build Reports
• Checklinks Reports
• Hypertext links in an InfoHub
• Intra- and inter-manual links

22. 22
Build Reports
pubs4d Logs
LOG1: top log LOG2: detailed log

23. 23
Other Features
Additional Benefits of the System

24. 24
Other Features
Links with the GUIs

25. 25
Other Features
• Work Flows
• Authors: automatic doc
generation (sync, checkout,
edit, checkin)
• Administrator: manual setup of
new InfoHubs; adding
documents (authors can add
files inside document
directories)
• Promotion Utility (pubs4)
• Copies Dev docs to Release
docs
• Generates data for GUI support
• Builds links to topics
• Extracts text for hover help
• Populates various copies (Wiki
site, SupportNet staging site)
• Archives releases
• Displays xterm logs for authors to
monitor the progress of
document submission

26. 26
Summary
Some Issues and a Conclusion

27. 27
Summary
• Some Issues
• Locks
• Manual document locking by
authors
• Some manuals have single
owners (no need for locks)
• Others have multiple authors,
so we currently rely on process
(it is rare to have collisions)
• Trigger
• Not yet implemented, but
probably the way to go
• Conclusion
• Script started as a wrapper for internal
document generation utilities
• Evolved along 8 years of
implementation (Perforce, new DocGen
utility with server bank and parallel
conversion, hyperlink checking, GUI
data extraction, error handling)
• Correct-by-construction methodology
(gives developers early look at the
documentation)
• Hyper-automates documentation “end
game”
• Frees authors to do better stuff (write!)

28. 28
Summary
Perforce is the backbone of the system. It offers a simple mechanism
for checking documents out and in. Interfacing with Perforce and the
document depots through Perl is easy and efficient.
The visual Perforce application (P4V) provides an elegant interface for
writers and other authors to use as a cockpit for their documentation
management tasks.

29. 29
A Perforce-based Automatic
Documentation System
Chris Shaw
chris_shaw@mentor.com
Mentor Graphics Corporation,
46871 Bayside Parkway,
Fremont, California, 94538