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 (==, >, <, !=, <=, >=)

Continuing from where I left off on the last ACL post. Part 1 stopped where the function was returning a value. More often than not, you will want to store the results returning from a function. You can return the results into a variable and later use that value.

To create a variable, it is a process of running the function, returning the results and placing it into the variable (or temporary storage). We are going to use the variable to display a response. Variables start with some kind of scope, in this example we are using Global creates the variable that can be used anywhere in the current package (the scripts workspace).  We use a dollar sign ($) to tell ACL to assign it to a name (our example, $user). To help ACL understand when a statement is complete, use the semicolon (;) at the end.

Running this code, either as a snippet (small code part in a file) or copying and pasting each line into Arbortext’s command line, will produce a response to the user’s name.

Comments

In the last code example there was the use of # sign. Everything after the pound sign is a comment and will be ignored by ACL. It is for humans (not machines) to place comments on why the code was written. Keep in mind, what is fresh in you mind today may not be in six months from now. However, if someone follows after you, it will help them understand why you did what you did. It is not very important to comment on everything as much as commenting on complex areas.

You can stick comments on top (above example) or to the right of the code.

Blocks of Code

A block is a section of code that is a cohesive unit. It is delimited with curly braces { }. You will see them where functions are lengthy, if/else branching, in while and for loops.

While Loop

Below is an example of a function that removes comments inside an entire document. It uses a while loop and the find command.  The while loop will do something while it is true and will stop when that condition changes to false.

For Loop

Below is an example of a for loop. The function task is to remove an element named change. It uses a for loop going over each element. If it is a change element, it deletes it.  If it’s not a change element, it skips it, and continues in the loop until all the elements have been reviewed. A for loop will do something until it reaches a limit (the number of oids (explained in a future article) i<=count(oids)). In this example, it uses a counter and on each pass increments the counter by one (i++).

ACL language is the command line tool, similar to other tools, like Perl or C used inside the Arbortext Editor tools. It provides a way to control the editor or make changes to a document. It can control dialogs and interface to other software components. In the next couple of articles, I will describe how to use ACL to accomplish some simple and some complex tasks. I will be giving examples as I go.

ACL, as a scripting language, has common constructs such as:

• variables and arrays
• functions
• works with files
• modifies documents
• callbacks and hooks to handle events

Syntax

The syntax usually proceeds a command name followed by a argument(s). Blocks of commands can be added into functions. For example, the help command, by entering the word help, on the command line, will start the help file.

Note: the command line needs to be displayed. If not visible, turn it on from the File > Tools > Preferences pick the Category, “Window” and make sure the Command Line item is checked.

Commands

From the Arbortext Command Line, type help and enter a return. This command will launch the help file.

Functions

Functions are more complex and allow for multiple commands or functions into a block of code. Functions often, but not always, return a value. The syntax is functionname (argument, argument, …). A simple function username() can be run from the command line.

When you ran the function from the command line, you would notice that there wasn’t any output, pop-ups or results presented in the status area. However, it did not generate an error, so it completed your request. If you misspelled the function, it would generate an error response in the status area (see below).

To see results, we will add the response() function to get the result of the user’s name function. Since, response() is a function itself , the username() function will go inside the response() function or inside the parenthesize .

Tip: Pressing the arrow up key selects a previous command from your command history; similarly, the arrow down key selects the next command.

The results generate a Response box (click OK to dismiss).