A Perforce-Based Automatic Documentation Generation System

3 A Perforce-Based Automatic Documentation Generation SystemDOCGEN FacilityWriters author Technical Publications’ documentation in Adobe® FrameMaker (version 8). Thesource files for these documents are .fm files and imported graphics (typically JPEGs).Mentor Graphics’ Technical Publications Support team supplies a DOCGEN facility thatgenerates the HTML and PDF targets from the source FrameMaker files [1]. Jobs consisting ofmultiple manuals can be submitted. The facility farms out the manual translations to a grid ofservers to handle in parallel.The DOCGEN facility is accessed either through a Linux utility (docgen) or via a web site.Publications groups who use the web site typically generate the HTML/PDFs at the end of arelease cycle. This process might take about a week.The DVT publications group uses a different approach based on the Linux docgen utility. Withour documentation generation system, docgen runs automatically as documents are editedand are submitted to the depository. This mechanism results in a “correct-by-construction”InfoHub image. It has the advantage of being continually ready to promote into the distributionsoftware package. Last-minute changes can make it into the release and the final target isready to go within minutes.The final step in the generic document generation process is to update the InfoHub. MentorGraphics’ Technical Publications Support team provides a Linux utility (dmerge) to do just that.Documents in PerforceDVT source documents are stored in a techpubs depot in the division’s dvt depot (see Figure2). Each techpubs subdirectory corresponds to a documentation library (except for bin andarchive). Some document libraries are packaged as InfoHubs. Others are not; instead, theyare inserted into multiple InfoHubs.Figure 2: Techpubs depot in PerforceThe source files for the InfoHub shown in Figure 1 are located in the //dvt/techpubs/zin10.1 depot (see Figure 3) [2]. Each subdirectory corresponds to a single manual. For example, thecommand_ref subdirectory contains the source files for the Questa Formal Technology Command This is text for annotations in footer. Similar to footnotes treatment.

4 A Perforce-Based Automatic Documentation Generation SystemReference.Figure 3: zin10.1 Contains source for InfoHubThe Technical Publications organization has strict rules on naming conventions and manualdirectory organization. Figure 4 shows an example.Figure 4: command_ref StructureAll .fm and .book files are stored at the top level of the manual directory; imported graphics arestored in the graphics subdirectory. The man.book file is the “book” file for the manual. README is a control file used by the DOCGEN facility.This is text for annotations in footer. Similar to footnotes treatment.

9 A Perforce-Based Automatic Documentation Generation SystemThe Tech Pubs Build Reports page has a side bar that links to various InfoHub-relatedinformation and pubs4d session logs. Each entry in the InfoHubs section brings up itsassociated InfoHub. Authors can check how their edits appear in the documentation set in(virtual) real time. The Checklinks entries bring up the checklinks reports for the associatedInfoHubs. The Build Logs are the LOG1 and LOG2 outputs of the pubs4d utility.Author Work Flow The work flow for authors is remarkably simple. We use the Perforce system (either commandlineor P4V interface, or typically both). The author checks out a manual, performs edits, andchecks the manual back in. The pubs4d daemon (with the help of docgen) performs thetranslations and InfoHub update. Meanwhile, the author monitors translation progress from anxterm log.When translation and InfoHub generation are complete, the author checks the Tech Pubs BuildReports web page for errors and warnings. The author also can check the graphics report,bring up the associated InfoHub to check document edits and look at the checklinks report tofind and debug bad hypertext links.Administrator Work Flow The documentation system administrator performs the manual tasks. Surprisingly, these areminimal and uncomplicated. Aside from maintaining the build/release utilities (pubs4d andpubs4), the administrator handles adding and removing manuals and InfoHubs.Creating a custom InfoHub is a Tech Pubs procedure and just entails copying an existing huband modifying several files. Work to insert the new InfoHub into the Documentation GenerationSystem consists of putting the InfoHub into the dev area, updating the Build Reports pagemanually, and updating pubs4d to recognize the depots that contain manuals to process.Adding a manual to the system consists of adding an entry for it in the Build Reports page andadding the initial document to the Perforce techpubs depot.Adjustments can be made by authors as well as the administrator: .fm files and the graphicsfiles are added to, or removed from, the depot. Our experience is that administratorintervention is only needed when major changes happen, such as rolling over the software fora major release (which happens once a year).History The DVT Tech Pubs Documentation Generation System has been in operation for about 6years. In that time, it has evolved considerably. It originally started out running HTML and PDFtranslators separately and had loads of sanity-checking code. It only ran on old Solaris boxes.In addition to being painfully slow, it ran translations sequentially. An extensive documentrebuild—for example, 8 large books—might take more than 10 hours to complete.This was OK. We could wait overnight and hope the build performed without error. But, thesystem still replaced the tedious manual task of running translators directly and comparinglogs.Since then, the Technical Publications Support team created docgen, which moved FM-to-This is text for annotations in footer. Similar to footnotes treatment.

10A Perforce-Based Automatic Documentation Generation SystemHTML/PDF translation to a Solaris grid (of old but big machines). The interface is now Linuxbased and the translations are performed in parallel. The docgen utility even supports entry andtarget points at our various sites around the world.Now, an extensive document rebuild of more than 8 manuals might take an hour—if themanuals are huge and have many graphics and the grid has a lot of traffic. But typical usage is5 to 15 minutes for the average multiple-manual translation.Plans for the Future The system is scalable. In addition to new writers, we are opening the system up toengineering authors.For example, our Verification IP group creates testbench IP that exercises tests of IC busesand interfaces. Protocols for these interfaces are meticulous and arcane. Documentation forthese products is detailed and tedious and constitutes thousands of pages. We are slowlysetting up engineering authors and technical experts to author directly in our FrameMakersource files. They not only author topic sections, but they also add embedded comments fortheir writers to resolve. Since they invariably have prior knowledge of the Perforce system, theramp up for authoring is quick. We plan to continue to roll out this methodology to otherengineers.Other Issues Some issues are beyond the scope of this paper, including:• LocksOur organizational setup precludes collisions—writers tend to work on separatemanuals and chapters. When collisions are possible—for example, when a writer workswith an engineering author—the team members agree to lock files when they arechecked out. Although not currently necessary, we might consider system locks withcheckouts. With FrameMaker, DIFFs are more difficult than with text files. However,FrameMaker does have a document compare facility, which makes resolving documentcollisions a simple, albeit manual process.• TriggersUsing a trigger to wake up the pubs4d daemon is probably the way to go. But, we optedto have a periodically- waking, sleeping daemon for various innocuous reasons.• PromotionGenerating the InfoHub targets is only part of the process of delivering documentationto the development software location, which also gets built into the distribution software.Secondary processes shape the deliverable documentation targets. These are bakedinto a multipurpose Perl script we call pubs4.This script “promotes” the dev image to the release image. Along the way, it scans theHTML and creates support files for the GUIs so Help buttons on dialogs link properly tothe corresponding topics in the documentation. Generated GUI files also include textextracted from tables in documents that are displayed by hover help. This process helpsThis is text for annotations in footer. Similar to footnotes treatment.

Pathway1 to Innovation El Ind 14 June 2003 © Dieter Ernst, East-West Center, Honolulu, Hawaii, USAIn the semiconductor industry, Japanese firms have started already in the mid-1990s todevelop outsourcing arrangements and strategic alliances with Taiwanese firms (Ernstand Ravenhill, 1999). They are investing in R&D centers, both in China and SoutheastAsia, where the focus now shifts from product customization and process adjustment toIC design and software services. Moreover, Japanese firms continue to play importantrole as a provider of management techniques for Asian suppliers 10 .b) China’s ascentA second important transformation of Asia’s economic geography in the electronicsindustry is the new role played by China. Until the mid-1990s, four first-tier NIEs(Korea, Taiwan, Hong Kong, and Singapore), and two second-tier NIEs (Malaysia andThailand), were considered to be the standard bearers of the so-called “East AsianMiracle”. That changed however, once China emerged as a major market andmanufacturing base for increasingly sophisticated industrial products. China’s inwardFDI during the first 10 months of 2002 was $ 46.4 billion (UNCTAD, 2003). Even if oneassumes that “round-tripping” 11 constitutes 35% of inward FDI, China’s actual FDIinflows would be $32 billion. This would still represent 80% of all FDI inflows to Asia,excluding Japan. This new wave of inward foreign direct investment (FDI) and theconsequent integration into GPNs of new clusters in South and East China has generatedfears of trade and investment diversion in the rest of Asia.A vast pool of cheap labor allows China to continue to compete as a low-costmanufacturing base 12 . At the same time, however, China is distinguished by a broad baseof accumulated capabilities in R&D, developed in the Chinese Academy of Science andrelated institutions, and in the defense sector. It would thus be a great mistake to viewChina only as the cheap-labor workshop for the global electronics industry. China’s newattractiveness results from a combination of five developments: a booming market for ITproducts and services, when the rest of the world is in recession; China’s unlimitedsupply of low-cost IT skills; abundant land and a rapidly improving infrastructure; amassive rush of capital flows into China; and, catching this opportunity, support policiespursued by the central government, as well as regional and local authorities to developlocal capabilities and to rely on FDI as an accelerator of industrial upgrading.The share of foreign-invested affiliates in technology-intensive industries (primarilyelectronics) has risen from 59% in 1996 to 81% in 2000. In the electronics industry,leading global market leaders (whether from the US, Japan, Europe, or Korea), theirglobal suppliers from Korea and Taiwan, and, more recently, the leading U.S. contractmanufacturers have identified China as a priority investment target. The penetration ofFDI is particularly pronounced in three sectors: electronic components (especiallysemiconductors), computers, and telecommunications. Until 1999, investment in Chinaґs10 Among the many fascinating examples is Namtai…11 Actual inward FDI into China falls short of official estiamtes owing to the prevalence of “roundtripping”: lower tax rates on foreign capital create an incentive for domestic entrepreneurs to move moneyoffshore (e.g., to Hong Kong and the Virgin Islands) and introduce it as FDI.12 An estimate based on 2000 data indicates that broadly defined unemployment in China has reached 207million, or 29.1% of the total active population (Imai, 2002: p.33)8