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.
Automating Google Workspace (GWS) & more with Apps Script
[Mentor Graphics] A Perforce-based Automatic Document Generation System
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
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
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
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
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
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