Converting CALS tables to ASCII

Last updated 10NOV98

Here is the software:

cals2ascii.tar.gz: Unix gzipped tar file.
cals2ascii.zip: Windows zip file.

The cals2ascii.xom OmniMark program converts CALS tables to formatted monospaced ASCII. The program is designed to be called, when a CALS table is detected, by another OmniMark conversion utility or it can be used in a stand-alone mode invoked directly from a command line.

When calling cals2ascii, the parent conversion program passes it the name of a file, where it has placed the detected CALS table, the name of the file where it wants the ASCII version of the table written, and any command line options.

Upon completion, cals2ascii writes the ASCII formatted table to the specified output file and exits. The calling program then reads the ASCII table and positions it as required in the body of the conversion it is performing.

The program as written currently supports the following elements in table cells, from the DTD that was supplied with it:

para
code
ftnote
emph
ordered-list
simple-list
unordered-list

You can modify the supported elements by adding or deleting element rules in the cals2ascii program. You can also modify the programs behavior by adding or deleting matches in the build-outrow function. Some elements will not be possible to support due to the limited capabilities of displaying them in ASCII.

Setting up the Program

The find-start rule in the program contains a scan statement that reads in the DTD. Modify this statement so that it points to the location in your file system of the c2a.dtd file. This DTD can be modified to suit your needs, but I would recommend getting the program running before you change the DTD.

Sample Tables

Three sample tables, cms-tbl1, cms-tbl2, and tbl1.sgml are included with this program. The monospaced ASCII versions of the samples, created by cals2ascii.xom, are in: cms1.out, cms2.out, and tbl1.out.

Syntax

The following syntax example illustrates how the program can be called from a command line. Calling this program from another program will depend on the type of program and the operating system, but the structure of the command string should remain as shown.

NOTE: command line options surrounded by greater-than and less-that symbols are required. Those options surrounded by square brackets are optional.

omniv401 -s cals2ascii.xom <input> -of <output> [-d hsize 000] [-d ccode <ccpath>] [-d msg debug]

<input>: is replaced with the name of the file that contains the table to be processed. The program expects the file to contain a table element and its contents only. This means that the program that calls cals2ascii.xom must extract the table and place it in an external file.
<output>: is replaced with the name of the file the output from this program will be written to.
-d hsize 000: "000" is replaced with the finished width of the ASCII representation of the table. If this argument is omitted the program will default to writing an ASCII table that is 96 characters wide.
-d ccode <ccpath>: is an optional command line argument used only in situations where this program is being called by a script. The <ccpath> is replaced with the full path to a file being used to pass an execution condition code. Upon successful completion this program will write a "0" to the condition code file. If the program detects fatal errors during execution it writes a "1" to the file and aborts. The controlling script checks the value in the condition code file when each sub-process finishes. If the condition code indicates that the sub-process failed then the entire process is halted.
-d msg debug: is an optional argument, if present it turns on the programs debugging messages.

Version Notes:

2.1: Support has been added for tables with column widths defined in inches instead of proportional (relative) units. Now the program will attempt a crude transformation of the widths into relative units so that processing can continue.
2.4: Support for the "-d ccode xxxx" command line argument was added.
2.5: The program will now suppresses emph, online-only, hardcopy-only, and idx element tags. Any content within these tags is passed through to the formatted table output. Links in footnotes are now supported. Links in table cells, not in footnotes, are suppressed with only their content being passed to the formatted tbl. Links with empty content, as before, are replaced with a "link goes here" message in the formatted table cell.
2.6: Added support for ordered, simple, and unordered, lists.
2.8: Corrected problem that caused nested vertically spanned cell text to be dropped. Corrected problem that caused extra partial horizontal rule to be emitted in drill down tables. Corrected problem that caused tables right hand vertical rule to be omitted it right hand cells of a row were omitted in mark up.

Support

This application was written by Craig Sampson sascrs@unx.sas.com.

I am releasing this code under the GNU General Public Licence. Please feel free to make use of the code, but remember that I have other commitments and will not be able to supply any technical support for it.