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

PDF

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