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.
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. 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).
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. 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.
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.
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).
The percent (%) character in column1 indicates a comment.
Lines starting with % are processed first by ignoring them entirely.
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.
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.
Each formatting statement starts with a dash (-), a letter,
and another dash at column 1: and, not implemented yet
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 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: Debugging is possible by inspecting the individual output
files. In particular, JAM will compile readily on all major platforms. The command
line format is simple: 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. 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. The user items 'USR1' and 'USR2' do not have counterparts.
You may use those for your own-defined matters.
This program (page 17) has been discussed earlier.
This program (see also, \ref{seqed}) has been discussed earlier.
This program (see also, 3.1.5) has been discussed earlier.
This <a href=editing#seqed> program </a> has been discussed
earlier.
This program has been discussed earlier.
-------
General aspects
Printed version in LaTEX
On-line version in html
Electronic version in RTF
JAM processor availability
JAM Format specification
Customization
Hierarchy
Comment statements
Conditional statements
o ifdef
o else
o endif
Formatting statements
Rules for formatting statements
Itemization
Links
Structuring statements
* 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
Valid: Invalid:
- i-
and similar will fail to execute. Typos are also a fairly
common reason for problems.
JAM USER GUIDE
Command-line Version
jam <output format> <SCOPE> [<defines> [<defines> [...]]]
with <output format> to be any of
JAM GUI
JAM supported operating systems
Extending the Survival Guide