Documentation Costs Avoided using Python and other Open

Documentation Costs Avoided using Python and other Open Standards Andrew Jonathan Fine Operating Systems Software Organization Engines, Systems, and Services Honeywell International

Original Core Data Flow Single Python application • set of front end translators • content inserter • post-processing formatter

Front End Translator • Selected by caller • Caller specifies input file containing corporate data • Extracts components from file ü Pictures ü Tables ü Paragraphs • Saves to Python dictionary

Inserter • Caller selects components from Python dictionaries made by front-ends for respective documents. • Inserter creates a Word document • Inserter uses Python/Com to insert components into document

Back End Formatter • Scans corporate Word document template • Scans Word document made by inserter • Makes final style corrections.

Why? The flow was designed to cope with changes in requirements! • • New projects New teams New data source formats New standards for existing formats

First front-end translator Take pictures, tables, and data from a recursive property list constructed by an aerospace industry software visual programming tool called BEACON. (… actual design of translator outside the scope of this paper…)

Initial Design of Inserter • Straightforward use of principles demonstrated by Mark Hammond's book, Python Programming in Win 32. • Chapter containing a thorough treatment of how to have Python use the Word 97 COM object model to create and manipulate a Word Document.

Problems!!! • Must cope with huge amounts of corporate data such as table cells. . • Speed of COM interface for new individual elements. • Reuse issues for detailed typesetting of elements.

What I wanted: • Faster conversion • Existing standard • Callable from Python What I found: • Faster conversion (Open. Jade) • Existing standard (Doc. Book SGML)

Why Call from Python? • New scripting language to replace islands of automation (Perl, MSDOS, internal test stand controller language). • Easier to connect islands after writing in Python. • Open source thus continuously peer reviewed. • Tremendous user base! Plenty of wrappers written in Python around open source libraries supporting open standards. … so I wrote a Python wrapper around some Doc. Book rules …

Revised Core Data Flow • Python wrapper writes Doc. Book SGML • Open. Jade translates Doc. Book SGML to Word RTF

A Doc. Book Informal table rendered by Open. Jade into Word Name Type statex Intege r statey Long

Input to Open. Jade as local Doc. Book SGML Name Type statex Integer statey Long

from Doc. Book import Doc. Book class Italic. Index. Phrase (Doc. Book. Rules. Phrase): "italic indexible text phrase" TITLE = Doc. Book. Rules. Phrase def __init__ (self, text): Doc. Book. Rules. Phrase. __init__ (self, 'xe', 'italic') self. data = [ text ] class Name. Cell (Doc. Book. Rules. Entry): "table row cell describing name of identifier (italic and indexible text!)" TITLE = Doc. Book. Rules. Entry def __init__ (self, text): Doc. Book. Rules. Entry. __init__ (self) self. data = [ Italic. Index. Phrase (text) ] class Storage. Cell (Doc. Book. Rules. Entry): "table row cell describing storage type of identifier (ordinary text)" TITLE = Doc. Book. Rules. Entry def __init__ (self, text): Doc. Book. Rules. Entry. __init__ (self) self. data = text class TRow (Doc. Book. Rules. Row): "each row in application's informal table body" TITLE = Doc. Book. Rules. Row def __init__ (self, binding): (identifier, storage) = binding Doc. Book. Rules. Row. __init__ (self, [ Name. Cell (identifier), Storage. Cell (storage) ]) class TBody (Doc. Book. Rules. TBody): "application's informal table body" TITLE = Doc. Book. Rules. TBody def __init__ (self, items): Doc. Book. Rules. TBody. __init__ (self, map (TRow, items)) class TGroup (Doc. Book. Rules. TGroup): "application's informal table group" COLSPECS = [ Doc. Book. Rules. Col. Spec ('Name', 75, 'left'), Doc. Book. Rules. Col. Spec ('Type', 64, 'center') ] SHAPE TBODY = [ '2', '1', 'center' ] = TBody class Informal. Table (Doc. Book. Rules. Informal. Table): "application's informal table" TGROUP = TGroup class Example (Doc. Book): 'example application of Doc. Book formatting class' SECTION = str (Informal. Table) def __call__ (self): self. data = [ Informal. Table ()(self. data) ] return Doc. Book. __call__ (self) if __name__ == '__main__': print Example ([('statex', 'Integer'), ('statey', 'Long')]) () Python code to translate data into Open. Jade input in local Doc. Book SGML (based on Python to Doc. Book sample wrapper class Doc. Book)

Using class Doc. Book • class Doc. Book from Doc. Book. py in Appendix F is the top-level interface callable class • Application inherits from class Doc. Book • Contents of application inherit from classes contained by Doc. Book. Rules • Use overrides to specify structure, formatting, and text.

Open. Jade • Open. Jade is an open source DSSSL execution engine available from Source. Forge. • DSSSL is an ISO standard for typesetting specification and document conversion. • Open. Jade reads Doc. Book DSSSL stylesheets and our local DSSSL stylesheets if any. • The DSSSL is executed by Open. Jade upon SGML source text to write a final document for later loading into a word processor.

Doc. Book Post-Processing using Word Automation with Python/COM • Doc. Book/Open. Jade emits RTF with different Word document style identifier names than in corporate Word DOT file. • Much faster to change document using Python/COM than to create document! • Cannibalized Python code from inserter first draft to create post-processor. • Reads RTF, changes, saves as final DOC.

Return on Investment 5 projects ranging from 30 BEACON files to 150, average about 75 files Each project has 2 releases per year where each file must generate hard copy. Previously (cut/paste by hand): Each project release: 1/5 * 75 * 4 hours 3/5 * 75 * 8 hours 1/5 * 75 * 16 hours = = = Two releases per year: Five projects needing releases: Two year period (2002 -2003) Total effort avoided: hours = 1, 320 = 6, 600 = 13, 200 -----13, 200 * 2 * 5 * 2 60 360 240 ----660 hours hours Automated: Automated releases over 2 year period: My effort (12 * 140 hours per labor month): Total investment: Net effort avoided, 2002 -3: Net avoided by customers 2002 -3 at $100/hour: 160 hours 1 680 hours 1 840 hours 11 360 hours 1 136 000 dollars Net labor years avoided 2002 -3 at 1680 hours/year: Headcount avoided per year: ROI (Total effort avoided / total invested) 2002 -3: 6. 76 years 3. 38 people 7. 17

Python and Doc. Book together • Python connects our department’s engineering specific islands of automation. • Python with Doc. Book created Word documents from engineering data. • The combination of an open language with an open standard eliminated a real-world business process bottleneck. • The return on investment was substantial.