JAM Text Format

In order to avoid the obvious shortcomings of translators, which were unable to create the explanatory wrappers for cross-links as depicted above, we have created the JAM format in order to produce different formats from one single source.

General aspects

The Rich Text Format (RTF) version of text generated from JAM Format has the ability to be incorporated in any word processor. After adding page numbers, the utilities of the word processor can be used to create index and and references on a page basis. Hypertext links outside of the document are not referenced.

JAM processor availability

The 'jam' program has been implemented on the OSF/1 flavour of the UNIX operating system and should run easily on other UNIX systems. If it is required to run 'jam' on another platform, the sorting of the index files has to be modified accordingly, as the current version uses the 'sort'utility from the UNIX operating system. The program is available from the author.

JAM Format specification

Customization

The source code contains several configurable files (extension .STE) which hold site-specific information such as contact addresses for the local computing center, which editor to use, and similar localized elements. The local information, as well as the residual text, allows the adaption of both UNIX- and VMS type of environments.

Hierarchy

The order of processing is as outlined above, i.e. first conditionals, second formatting, etc.. The program 'beautify' can produce very verbose output on the processing and therefore also allows a more silent mode (description see below).

Comment statements

The percent (%) character in column1 indicates a comment. Lines starting with % are processed first by ignoring them entirely.

Conditional statements

The processing directives are extemely simple and similar to the C-preprocessor and expanded before the formatting statements. Rules are:

• 1st column is a pound sign (#)

• immediately after the pond sign there is either

   
  o ifdef  
  o else  
  o endif   
  

• include

This implies that only a subset of the C-preprocessor syntax is implemented. In particular, nesting of #ifdef statements is fragile.

Formatting statements

It is required to display four different types of non-flow text. These are

• verbatim (i.e., all is printed as written)

• itemized (such as this text)

• special (i.e., generally in different font but not verbatim)

• links (most useful for the HTML version)

Each of these formatting statements inserts a break in the current text flow and adds newline characters after each line if required. I.e., verbatim is printed as written and all spaces and carriage returns will be retained. (Tabs are treated as single space). 'Special' sections are for examples and similar ephasized text, and a carriage return is retained; whereas text flow is inserted where appropriate. 'Itemized' sections do not honour carriage returns and allow a line break only after a new item (see below). 'Link' sections display a hypertext link in the html version, whereas in the text version the link is only described in words rather than a real hyperlink, embraced by parenthesis.

Rules for formatting statements

Each formatting statement starts with a dash (-), a letter, and another dash at column 1:

• -V- starts Verbatim

• -I- starts Itemization

• -S- starts Special text

  and, not implemented yet

• -L- starts Link description

The end of each corresponding section is indicated by an identical statement which is written in lower case:

• -v- ends Verbatim

• -i- ends Itemization

• -s- ends Special text

• -l- ends Link description

Itemization

The itemization directive is slightly special as items are introduced with a special token:

• one lowercase 'o' and a space.

Links

The link description always has and only has two lines. The first line is the target of the link in the format of a universal resource locator (URL), and the second line holds the title of the link.

Structuring statements

Structuring statements are processed after the conditional and formatting statements and are auomatically numbered. The text structure is in three levels. Chapters, Sections, and Headlines are implemented using asterices embraced in dashes:

 
*  	is a chapter   
-*- 	is a section   
-**- is a Headline   

Debugging is possible by inspecting the individual output files. In particular,

 
- i-  

JAM USER GUIDE

Command-line Version

JAM will compile readily on all major platforms. The command line format is simple:

 
jam <output format> <SCOPE> [<defines> [<defines> [...]]]  

• LATEX

• HTML

• RTF

All other <format> will print usage information. <SCOPE> is any of

• I (for International)

• S (for SITE-SPECIFIC).

All other <SCOPE> will print usage information.

JAM GUI

Just start, click, enjoy. Thanks to the NCBI staff for maintaining the VIBRANT code.

JAM supported operating systems

We have successfully tested JAM on DEC, SGI, Windows, and Mac. The VIBRANT toolkit is required for recompilation if you want to rebuild the JAM code. We have successfully tested the RTF code on Microsoft Word on Mac and Windows, versions 4 to 6.

Extending the Survival Guide

The user items 'USR1' and 'USR2' do not have counterparts. You may use those for your own-defined matters.