JAM Text Format

The JAM (Just Another Metafile) Format has been developed at the Biocomputing Facility at Basel over the years and was put into the public domain in 1994.

Today, documentation in Biocomputing must be available in various formats. Users who have never used computers for this purpose before will not easily adopt all-electronic information and require professionally printed material. Colleagues at remote sites who wish to print the text locally in chapters, or send it around in electronic Mail messages, require a simple ASCII-type of format. Electronic hypertext systems, on the other hand, have become increasingly popular in recent years and have the tremendous advantage that the cross-references will be much more intuitive and easy to follow. Launching programs from hypertext is a very new technology and will be discussed below as well. Previously, the use of translators provided a preliminary way of switching in between worlds. There are various elements of text structuring and cross-references which are similar in between the formats discussed above, however, the detailed spelling and presentation to the user is different and depends on the presentation context. The following example shall illustrate this.

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 JAM format is suited to be translated into either LaTEX, html, or (limited) ASCII text format. An alphabetical index as well as a table of contents is provided within each format.

Printed version in LaTEX

The JAM processor produces a LaTEX souce file which can be processed with the usual LaTEX procedures. LaTEX processing requires an additional stylesheet in order to be processed further, and the 'makeindex' utility to generate the correct index ('makeindex' is part of a LaTEX installation).

On-line version in html

The JAM processor produces a set of files which can be viewed after proper installation with any WWW client. Both LYNX and Mosaic type of viewers are supported, i.e. there is no need for sophisticated FORMS support. JAM allows specific hypertext links for referencing to electronic sources. JAM can be configured to produce a html version which can talk to the HASSLE receptor. This is a separate program which must be installed and configured separately. The HASSLE receptor requires that your host is registered at the host which is running the html version on top of HASSLE in order to execute the commands. The HASSLE receptor allows a hyperlink to a program mentioned in the text actually executes at the local or remote site. HASSLE has been published earlier, and the HASSLE receptor is being published.

Electronic version in RTF

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


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.


The format has several classes of statements:

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:

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

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:

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


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


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   
-*-Referencing statements The purpose of referencing statements is to allow indexing and transparent reference insertion. The following items are allowed:
Type                 Symbol        Expansion to   
Index entry           entry in index   
Reference point      bold face word being referenced  
Hint to reference     (*)  hypertext lik (html)   
.                                  'see also, ...' (LaTEX)   
HASSLE receptor       (*)  if 'jam' is configured   
.                                  properly, html link, otherwise   
.                                  ignored. Ignored in LaTEX.  

Conventions and Pitfalls

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

- i-  
and similar will fail to execute. Typos are also a fairly common reason for problems.


Command-line Version

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

jam <output format> <SCOPE> [<defines> [<defines> [...]]]  
with <output format> to be any of

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

All other <SCOPE> will print usage information.


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.

Back to me!