I recently started working on some SGML files that have large tables. I’m talking really large. I found that the performance of Arbortext Editor slowed considerably whenever I encountered one of these tables.

Then I received a great piece of advice: If you’re not working on tables, collapse them.

You can start by closing all of the tables in your file. Go to the View menu and select Collapse/Expand Divisions. Select the table element and click Collapse.

Now when you need to work on a specific table, expand that table, do whatever you need to do, and collapse it again when you’re done.

Let’s assume that you have an SGML file open and you know that a particular phrase or sentence is already a text entity — but you don’t know the unique name of the text entity. How can you easily figure out the name?

One of my co-workers said that she goes to the View menu and selects Text Entities. The content of the text entity is replaced by a tag that displays the name.

Then I told her my approach. Place your cursor inside the phrase or sentence and choose Entities > Text. The Text Entities dialog box appears with the entity highlighted.

My co-worker said that she liked my approach better. Sweet!

Liz took the raw recordings and enhanced them and the conversation sounded good. The podcast collection is called PubWright Podcasts; it is mostly about the Arbortext community. The PubWright podcast interviews Arbortext implementers, customers, and experts in an attempt to share knowledge with the greater Arbortext community. The first podcast featured me. I wanted few more episodes to be released, before I mentioned anything,  (the quality of the guest can only go up). So check out the podcast.

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.

I came across this ACL file from Karl Johan Kleist (original code by Rune Kallhovd) on Adepters website, listed below.

I named that code below as removeUnusedGraphics.acl and placed it in <arbortext home>/custom/scripts folder. I tied it to a menu on init ACL file (<arbortext home>/custom/editinit) that runs when a document is opened. It has these items added in the menu. First, the file is sourced. second, call the function, clean_unused_gfxents() when the menu item is selected.

Remove Unused Graphic Menu Pick

Items to add to the Menu*

Code File

* Menu article coming soon…

Arrays

Arrays are special variables with multiple “compartments”. Each compartment holds a value. Arrays consist of names and indexes. ACL has two types of one-dimensional arrays:

Normal arrays are indexed by integers subscripts.

Associative arrays are indexed by arbitrary strings or keys.

Declaring Arrays

Arrays can be defined as local or global. Define them like a variable, ($) name, square brackets, semicolon. Arrays can be set to a dimension such as having ten values, $array[10].  The square brackets [ ] are used to address or retrieve the elements of an array.

Accessing Array

Accessing the keys of an array, use the for loop, as in: for (key in array).
For example, the code below iterates over the two elements of the associative array color twice, once with Associative and once with Normal:

Variables

A variable is a keyword or phrase that is linked to a “value” stored in memory or an expression that can be evaluated. For instance, a variable might be called “total_count” and contains a number. Variables are usually defined in ACL beginning with a dollar sign ($), they do not have to, but it is very good practice. The variable is on the left side and the value is on the right of the assignment operator (=). When assigning variables, it best to read right to left.  For example, assigning the string or text, “red” with the equal sign (=), to a variable “color”. It is a good practice to end your assignments with a semi-colon (;).

Some common variable assignments using expressions.

Variable Scope

Variables exist in two locations or scopes, Global and Local.

The default is Local. It is a good practice to define the minimum amount of scope needed or limiting your variables. This is helpful in maintaining the code and debugging it. For example, it may be confusing if a variable is a Global $A and a Local variable called $A are both being used in a For-Each loop.

Global variables are accessible anywhere in the ACL code.

Tip: If defining a Global Variable, pick a naming convention such as all caps. This will be helpful when mixing Local and Global variables in code. For Local variables, choose, for example, Camel Case.

Local variables can be limited by a block of code (code inside the { }). When variables are assigned, inside blocks are local or limited just to that block. Blocks can be found in functions and items inside conditionals, such as an if statement.

Shortcut Assignments

If using a number variable as a counter, and the counter needs to increment by one, you could do:

A shortcut using the (+=) means increment and assign the value to itself.

If using a string variable using the dot operator (.) to concatenate or stitch together strings.

The variable $message resolves as “File Chapter 2 sent to be published!” if doc_name() was equivalent to “Chapter 2″.

Variable Evaluation

Variables inside double quotes will be evaluated, and variables inside single quotes are not evaluated.

Returns “Hello Tester!”

Returns “Hello $username!”

Comparative

Using variables for comparison. In a “if” statement, you may want the variable, if true, then do something with it. Comparisons can be strings equaling or not equaling other strings. As well as, numbers equaling (==), not equaling (!=), greater (>), lesser (<), greater or equal (>=) or less than or equal (<=) to other numbers.

String comparisons (==):

Number comparison (==, >, <, !=, <=, >=)

Here is a sample snippet of the input file of S1000D Issue 3, XML:

Here is the transformation stylesheet:

Here is the result.s tree (a snippet).