Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

[Mentor Graphics] A Perforce-based Automatic Document Generation System


Published on

Mentor Graphics' DVT Technical Publications uses an automatic documentation generation system to create the InfoHub documentation libraries for its product distribution software. The backbone of this system is a Perforce installation, which provides the document control and management portion of the system. Get an overview of the system and see a typical author workflow.

Published in: Technology
  • Be the first to comment

  • Be the first to like this

[Mentor Graphics] A Perforce-based Automatic Document Generation System

  1. 1. 1  A Perforce-based AutomaticDocument Generation SystemChris ShawWriter, DVT DivisionMentor Graphics Corporationchris_shaw@mentor.comLogo area
  2. 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. 3  Agenda•  InfoHubs•  pubs4d•  Build Reports•  Other Features•  Summary
  4. 4. 4  InfoHubsMentor Graphics Document Delivery Platform
  5. 5. 5  InfoHubs•  Doc delivery platform•  Unique per software tarball•  HTML & PDF versions ofeach manual•  Advanced features•  Google-based intra-InfoHubsearch•  Targetable topics•  Javascript based
  6. 6. 6  InfoHubs (HTML/PDF)HTML PDF
  7. 7. 7  InfoHubs (Search)
  8. 8. 8  DocGen and Dmerge•  Document Generator•  DocGen developed by MGCTech Pubs Support•  Reads FrameMaker books•  Generates HTML & PDFversions of each book•  Accessible via Website orLinux Utility•  Handles a package of booksat a time•  InfoHub Updater•  InfoHub structure is handcrafted.•  Dmerge updates all linksafter a DocGen run
  9. 9. 9  Documents in Perforce•  DVT Division•  Uses Perforce for softwaredevelopment•  Natural depot for manuals•  DVT Tech Pubs•  Stores manuals in a techpubsdepot•  Manuals follow MGCTPstandard structure•  Files: *.fm, *.book, README,graphics/*.jpg
  10. 10. 10  pubs4d UtilityPerforce-based InfoHub Generation Daemon
  11. 11. 11  pubs4d Utility•  Perl utility•  Started as doc generationscript to simplify “end game”•  Added Perforce front end•  Migrated from old docgeneration scripts to DocGen.•  Daemon process•  Wrapper to DocGen•  Monitors techpubs depot•  Doc update causes pubs4d topackage the manuals anddispatch to DocGen•  Post-generation•  Manages target data•  Updates Build Reports•  Runs checklinks routine
  12. 12. 12  pubs4d UtilityLog OutputTuesday, March 19, 2013 4:06 PM: Processing docgen jobwith 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 /cant 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 startedprint LOG1 "n";
  13. 13. 13  pubs4d UtilityDynamic 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. 14  Build ReportsHyperlinked Web Page of DocGen Results
  15. 15. 15  Build Reports•  DocGen results•  Updated by pubs4d•  1 entry per manual (includestimestamp, release ID anddepot)•  Links to multiple DocGenreports•  Other Helpful Links•  Development InfoHubs•  Checklinks results•  pubs4d Logs
  16. 16. 16  Build ReportsTranslate No-GoERROR: Cannot open imported graphic file /wv/techpubs/docgen/jobs/1303061301ukhparts/pdf/quickstart_cdc_user/graphics/quickstart_autocheck.jpg.
  17. 17. 17  Build ReportsHTML Conversion Report
  18. 18. 18  Build ReportsHTML Graphics Report
  19. 19. 19  Build ReportsConversion Errors/Warnings Report
  20. 20. 20  Build Reports•  Development InfoHubs•  Documents in the Dev area•  Not yet promoted to Release
  21. 21. 21  Build Reports•  Checklinks Reports•  Hypertext links in an InfoHub•  Intra- and inter-manual links
  22. 22. 22  Build Reportspubs4d LogsLOG1: top log LOG2: detailed log
  23. 23. 23  Other FeaturesAdditional Benefits of the System
  24. 24. 24  Other FeaturesLinks with the GUIs
  25. 25. 25  Other Features•  Work Flows•  Authors: automatic docgeneration (sync, checkout,edit, checkin)•  Administrator: manual setup ofnew InfoHubs; addingdocuments (authors can addfiles inside documentdirectories)•  Promotion Utility (pubs4)•  Copies Dev docs to Releasedocs•  Generates data for GUI support•  Builds links to topics•  Extracts text for hover help•  Populates various copies (Wikisite, SupportNet staging site)•  Archives releases•  Displays xterm logs for authors tomonitor the progress ofdocument submission
  26. 26. 26  SummarySome Issues and a Conclusion
  27. 27. 27  Summary•  Some Issues•  Locks•  Manual document locking byauthors•  Some manuals have singleowners (no need for locks)•  Others have multiple authors,so we currently rely on process(it is rare to have collisions)•  Trigger•  Not yet implemented, butprobably the way to go•  Conclusion•  Script started as a wrapper for internaldocument generation utilities•  Evolved along 8 years ofimplementation (Perforce, new DocGenutility with server bank and parallelconversion, hyperlink checking, GUIdata extraction, error handling)•  Correct-by-construction methodology(gives developers early look at thedocumentation)•  Hyper-automates documentation “endgame”•  Frees authors to do better stuff (write!)
  28. 28. 28  SummaryPerforce is the backbone of the system. It offers a simple mechanismfor checking documents out and in. Interfacing with Perforce and thedocument depots through Perl is easy and efficient.The visual Perforce application (P4V) provides an elegant interface forwriters and other authors to use as a cockpit for their documentationmanagement tasks.
  29. 29. 29  A Perforce-based AutomaticDocumentation SystemChris Shawchris_shaw@mentor.comMentor Graphics Corporation,46871 Bayside Parkway,Fremont, California, 94538