[mentor graphics] a perforce-based automatic document generation system
Post on 07-Dec-2014
301 Views
Preview:
DESCRIPTION
TRANSCRIPT
1
A Perforce-based Automatic Document Generation System
Chris Shaw Writer, DVT Division Mentor Graphics Corporation chris_shaw@mentor.com
Logo area
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
Agenda
• InfoHubs • pubs4d • Build Reports • Other Features • Summary
4
InfoHubs Mentor Graphics Document Delivery Platform
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
InfoHubs (HTML/PDF)
HTML
7
InfoHubs (Search)
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
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
pubs4d Utility Perforce-based InfoHub Generation Daemon
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
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.1f\tSending 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
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
Build Reports Hyperlinked Web Page of DocGen Results
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
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
Build Reports
HTML Conversion Report
18
Build Reports
HTML Graphics Report
19
Build Reports
Conversion Errors/Warnings Report
20
Build Reports
• Development InfoHubs • Documents in the Dev area • Not yet promoted to Release
21
Build Reports
• Checklinks Reports • Hypertext links in an InfoHub • Intra- and inter-manual links
22
Build Reports
pubs4d Logs
LOG1: top log LOG2: detailed log
23
Other Features Additional Benefits of the System
24
Other Features
Links with the GUIs
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
Summary Some Issues and a Conclusion
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
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
A Perforce-based Automatic Documentation System Chris Shaw chris_shaw@mentor.com Mentor Graphics Corporation, 46871 Bayside Parkway, Fremont, California, 94538
top related