The biggest issue was that I was the single bellybutton to all the documentation. I strived for a collaborative solution. I worked with Wiki’s and set out to install one. Our corporate structure would not allow me to install one. The company had just created one, and they only wanted one in the company culture. I was not sure that I wanted all my documentation out there for all to see. Because I work for a large aerospace company. However, I got over it; it was more important to have collaborative tools rather than my pride. I imported all the docbook information into our Wiki.

The biggest complaint of the wiki was its weak search. I wanted a way for a writer who is authoring in a SGML/XML file, to hit the help button and go to an exact area in the documentation. The Arbortext Editor has the Shift-F1 to present a customized help. I played with it trying to add hyperlinks to those files. With the help of the adepters mailing list and Clay Helberg (a Arbortext guru), he mentioned a few things, one being of which is remapping the Shift-F1 key. The other is how to open a file. So, I used the browse_url function which launches a HTML page, in my case a Wiki page. I needed to add more information in the URL based on the two things: the DTD name and element name. In the Wiki, I am using subpages which are like a collection. All pages will be a subpages grouped in “Structured-Elements” and also “38784″ (the DTD name) followed by the tag name. The tag is found using the ACL functions of oid_name(oid_caret()). The oid_caret is the cursor position and oid_name is the name of the element. So below is the code snippet: I placed it inside my ACL file located at  (<arbortext-home>/custom/editinit) which gets sourced when a document is opened.

When the writers place the cursor inside an element, for example,  <title>, and then does a Shift-F1, the Arbortext Editor will open to a Wiki page by element and DTD name.

That was the easy part, now is the hard part; populating the Wiki with content on the elements. With Mil-Spec DTD’s (some of our work uses them), we have a TDT file (it contains all the element names and attributes with descriptions). My co-worker, Joe, our other Software Engineer, wrote a Perl script to convert each element to a Wiki page. I will import a couple of hundred new Wiki pages here in the next few days.

The final part is adding extra links in these new pages to the established Wiki pages, therefore linking the entire project together.

First you will need a Perl program. I will use Hello World printed to screen as an example. Place the following code  inside a file called “hello.pl” and save it at C:\hello.pl.

Second, create a file called “hello.ism“:

Here is the syntax: Use the keyword Launch and the path to Window’s command shell. The switch (option) /k keeps the command window open. You can use /c to close the command window, but since we are wanting to see the results printed, we will leave the CMD shell open. Enter the full pathname and Perl file name, (e.g., c:\hello.pl)

Place the “hello.ism” inside the Macros folder. For example, my installation is: C:\Program Files\PTC\Arbortext IsoDraw 7.0\Program\Macros”.

Third, launch IsoDraw. Start > Program Files > PTC > Arbortext IsoDraw 7.0 > Arbortext IsoDraw 7.0

To  launch a Perl script from a batch file (.ism), from the menu: Macros > hello.

Hello Macro

The script will run and print the results in an open CMD shell and print “Hello World“.

Perl Results. "Hello World"

Again, this is a simple example but it does show how to launch Perl from IsoDraw.