JAMF DOCUMENTATION (Specification page) |
|||
This section details the specification of the JAMF language as of version 2.0, in 1995. This code was published in CABIOS as follows:
Doelz, R. Optimal production of biological documentation: the JAM format. Comput. Applic. Biosci. 11, 224-226 (1995).In order to maintain consistency of Internet references, the code is available from this server.
Reference: www.doelz.com/software/jamf/
(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. This chapter defines the format and shall serve as reference. Starters in JAMF should first read the introductory chapters and eventually the tutorial accompanying the software distribution.
The JAMF format has several classes
of statements:
The order of processing is as outlined above, i.e., first conditionals,
second formatting, etc..
Names
JAMF files are named preferentially in UPPERCASE letters
following the '8+3' rule. This is to allow an
easy conversion from one operating system to the other. The extensions
have been explained earlier
, and will be detailed again below. JAMF files reside all
in a single directory and will be called from the application,
which opens the file MASTER.JAM as first file
in the current directory.
NOTE: MASTER.JAM is the major file of JAMF . If this file
is absent or cannot be opened for read, the program executing
JAMF processing will exit.
Format
JAMF files contain text and processing commands in the same
file. The use of the characters %, #, *, =, and
- in the first column is reserved to JAMF. If
you need to write text which contains these characters at the
beginning of the line, you must make sure that these lines start
at column 2 only.
JAMF files are less than 132 characters wide and contain only
printable characters. Control characters and
lines longer than the limit will cause an abortion of the JAMF
processing run.
The <TAB> character is considered to be printable as it
is a 'whitespace'. However, as JAMF does not expand <TAB>
characters, it will depend on the output format whether the space
is retained or reduced to a single space. Therefore, try to avoid
<TAB> characters.
Input Files
JAMF uses the MASTER.JAM file
to determine the inclusion of other files. Extensions are not
enforced but defined by convention (Exception: .INT files
for 'international' scope). Other input files are possibly generated
automatically, e.g., the JAM.INX file is required
for HTML format.
Output Files
The JAMF program generates files with the following extensions:
RTF output will be, depending on the selected behaviour, in one
or more files. The references in the files of the DOS hypertext
sources contain .HTML as extension. This allows to transfer the
.HTM files to other platforms after renaming.
Additionally, depending on the selected format, zero or more
of
files are created.
Debugging of JAMF
All links are logged in the JAM.REF file.
This file is written in JAMF but not processed in RTF or LATEX.
in HTML, the processed file will be added as chapter after the
user-supplied files. In the HTML output, you might also want
to inspect the JAM.INX file to see the JAM.REF file before processing(sorting).
The source code might contain several configurable
files (extension .STE) which hold site-specific information such
as contact addresses for the local computing centre, which editor
to use, and similar localised elements. The local information,
as well as the residual text, allows the adaptation of both UNIX-
and VMS type of environments. The SCOPE of the
JAMF run will affect the used
extensions . If the international scope
is chosen, the file stem will be retained, and the extension
.INT will be used.
NOTE: The selection of the SCOPE in JAMF occurs at run-time
and is NOT performed via the JAMF source code.
The percent (%) character in column 1 indicates a comment.
Lines starting with % are processed first by ignoring them entirely.
NOTE: If the UNIX prompt (%) is used in the JAMF code,
the % character must be placed in any column but not the first,
in order to avoid that the line is recognised as comment.
The processing directives are extremely simple and similar
to the C-pre-processor and expanded before the formatting statements.
Both ifdef and include type
of constructs are supported.
Three keywords are recognised after
the first column , which must be a pound sign (#):
The nesting of #ifdef statements is fragile as it is possible
to extend them across files.
The include keyword
is recognised after the first column , which must be a pound
sign (#):
It is possible to include files in several levels. Unfortunately,
this also allows to create loops recursively, which must obviously
be avoided.
It is possible to use four
different types of non-flow text. These are
These formatting statements typically insert a break in the current
text flow and adds new line characters after each line if required.
It is important to honour the fact that interlinking of
formatting is not supported. The only formatting which is accepted
within some of the other statements is 'emphasis' (-E-),
Example:
Note that the indentation of verbatim, if anticipated, must be
inserted manually.
Format:
Format: Special text here.
In contrast to -V-, -S- -L- and -I-, the -E- statement does
not interrupt the text flow. Rather, it allows to emphasise text
in a single line.
Format:
Appearance:
This is text here, in emphasised fashion Format:
Format:
test1 test1 test1 test1 test1 test1 test1 test1 test1 test1 test1
test1 test1 test1 test1 test1 test1 test1 Format
This is the line after the page break.
Figure legends are not currently implemented. In LATEX and RTF,
a reference to the figure may be inserted, which points to the
figure in question, which is appended at the end of the current
chapter.
Format:
Structuring statements are processed after the conditional
and formatting statements and are automatically numbered. The
text structure is in three levels. Chapters, Sections, and Headlines
are implemented using asterisks embraced in dashes:
The purpose of referencing statements is to allow indexing
and transparent reference insertion. The items as listed in
the following table are allowed. The selection of the behaviour
at run-time will decide in HTML mode whether links will be addressed
or not.
NOTE: As JAMF will interpret links if they occur in verbatim
mode, the following displays the pipe character (|) as colon
(:). This is for didactic purposes only.
In order to have the hypertext links processed accordingly (as
in the example test2/3), an item like +:test2:+
must be buried in the text.
Again, we buried the | by colons (:) in this example for getting
it JAMF neutral.
The following table shows the text and how it will be interpreted.
The > and < characters embrace where the expression was
located before. Note that, as above, the first column uses colons
rather than pipes to avoid JAMF processing.
Today, documentation in biocomputing
must be available in various formats. Users
who have never used computers for research purposes 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, transferable 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.
We have, therefore, recognised the need to provide documentation
in different formats. Not surprisingly, this also applies to
our internal, daily work. As many of the group work on programming
and technology developments we need to have an easy way to communicate
our achievements easily in various formats. Word-processors on
personal computers are very convenient and powerful, but expensive
or incompatible with the UNIX workstation world. Electronic hypertext
is nice on WWW browsers but not convincing in printouts. Last
but not least, typesetting for the final documentation is required
but difficult to establish.
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 most popular formats, such as
However, the detailed spelling and presentation to the user is
different in each format and depends on the presentation context.
The following example shall illustrate
this.
Writing: Note:
This is an implementation of the what you see is what
you get principle - and you must insert the page reference
manually!
Source code:
Appearance:
Source code
Appearance in the browser:
In order to avoid shortcomings of translators, such as the lacking
ability to create the explanatory wrappers for cross-links as
depicted above, we have defined the JAMF format in
order to produce different formats from one single source.
Admittedly, authoring in various formats might be much better
supported for an individual system. We are well aware of the
features of the systems we would like to write in. We are convinced
that many of the features offered allow for a very nice, appealing
and luxury text layout if you have time to spend in editing
and beautifying text. JAMF follows
a different strategy
which is explained below.
One of the benefits of JAMF is that it can be
written independently of the processing system and does not require
that either of the used methods is available on the machine which
is used for display. JAMF editing may be performed from very
trivial texts in basic editors.
After this introduction, general aspects such as availability
and installation are discussed. A tutorial follows, with a more
advanced hint section. After a description of
the reflector system, the entire language specification
is appended.
KISS - Keep It Stupid Simple
We anticipate the benefits of JAMF to be as follows:
The text of JAMF is composed from different files in an
#include type of syntax, which implies that documents
can be reused or rearranged in chapters with minimal effort.
Modules can be used multiple times.
Additionally, we provide a set of definitions which can be used
like #ifdef statements in the text, and allow
to write documentation for various environments in a single document:
UNIX and VMS syntax, for example, can be explained in the same
document and as simple switch in JAMF will produce either documentation
easily.
Thirdly, we want to allow that others share experience and can
adopt the documents we produce into their environments smoothly.
This can be achieved if the text containing telephone numbers,
nail addresses etc. is kept in files which can be included with
the syntax mentioned above. However, a casual reader might not
want to do this. Therefore, we allow the usage of a scope
which can be either international or site-specific,
and use the corresponding include files by a single switch in
JAMF.
Headlines, chapters, sections etc. cause a certain effort in
editing. JAMF will do this all for you. It is primitive and easy:
Only three levels (chapters, sections, subsections) are provided.
More complex items can be constructed if really needed, but JAMF
will maintain these three automatically.
Typefaces (bold, italics, etc.) will require editing effort.
Even worse, to be # consistent is frequently
the larger problem. Again, JAMF will help in getting things down.
It supports only a single mode of emphasis such as this
text and one mode of italics for examples - you will
see this later in this document. Admittedly, this might seem
primitive to you- but it is much easier to administer.
Itemisation and lists are easy to read. They are not that easy
to edit as you need to shift the margins, have bullets in front
of the items, and shift the body of the text. JAMF does this
all for you. In fact, the list of advantages you are just viewing
is one of the appearances of JAMF lists.
JAMF will give you four types of link support: Anchors, Index
entries, Pointers and
Receptor/Reflector links. The latter is somewhat
special and applies only to the electronic (HTML) type of output.
Links are notoriously difficult to write if you do it in different
publishing systems. JAMF provides you with the necessary starting
files to set up overview pages in HTML or the table of contents
in word processor or typesetting systems.
User interfaces are provided in text and graphic versions. Nearly
all of the platforms we could get hold of are supported. As the
software is free, it should be THE software
for you!
This list is neither exhaustive nor complete. please refer
to the next chapters for details.
The JAMF
(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. This document describes JAMF version 2.1 which was significantly
enhanced as compared to earlier versions.
This is software provided as
is and no warranty or responsibility of BioComputing
Basel can be expected or granted. The use of the software, its
associated documentation and the use of results obtained by the
computer program(s) are subject to the individual user's responsibility.
JAMF may not be sold nor used in a commercial environment to
generate revenue by its use or products generated by the program.
Reference information
Doelz, R.: Comput-Appl-Biosci(1995) 11, 224-226.
Files
Input Flexibility: Customisation of Scope
Comment Statements
Conditional Statements
Conditions
#ifdef
#else
#endif
Inclusion
#include
Formatting Statements
___________________
-V-
-I-
o test
-i-
This is an example
-v-
___________________
will get you an error message. The correct setup is:
___________________
-I-
o test
-i-
-V-
This is an example
-v-
___________________
which will give you an appearance like the following:
------------
This is an example
------------
Verbatim Formatting
___________________
-V-
+--------------------+
| verbatim text here |
+--------------------+
-v-
___________________
Verbatim text is printed as written and all spaces and
carriage returns will be retained. Tabs are treated as single
space. Leading blanks will be removed. Tables can be incorporated
by pre-formatting these in JAMF code as 'text', i.e.,
----------------
+--------------------+
| verbatim text here |
+--------------------+
----------------
Some personal computers have a vertical character as well
as a (non-standard) interrupted pipe symbol. The latter is unsupported
as it does represent a non-standard ASCII-code and shall be avoided
as JAMF will exit once it detects these characters. The example
above was produced by allowing a single leading space. This is
a useful option to print verbatim examples in JAMF for tutorial
purposes without to have these interpreted by the JAMF processor.
Special Formatting
_____________________
-S-
Special text here.
-s-
_____________________
'Special' sections are for examples and similar emphasised
text, and a carriage return is retained; whereas text flow is
inserted where appropriate. Appearance:
---------------------
---------------------
Emphasised Text
_____________________
This is
-E-
text here,
-e-
in emphasised fashion
_____________________
'Emphasised' text can be used to attract attention.
---------------------
---------------------
Reference Links
_____________________
-L-
$FTP$/directory/file
[-l-]
_____________________
'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 text. In order to allow
flexibility, the file JAM.LNK in the same directory as the MASTER
file for jam will allow to define paths embraced by $ characters.
The -l- is optional as the file reference will always be processed
after -L-. example:
---------------------
---------------------
This is the same result as
---------------------
---------------------
The second link did not inherit the -l-.
Line Breaks and Paragraphs
_____________________
test test test test test test test test test
test test test test test test test test test
--
test1 test1 test1 test1 test1 test1 test1 test1 test1
test1 test1 test1 test1 test1 test1 test1 test1 test1
_____________________
The three dashes indicate that the current line enforces
a line break. Line breaks may not be accumulated in LATEX and
HTML due to the specific behaviour of these formats. Appearance:
---------------------
test test test test test test test test test test test
test test test test test test test
---------------------
Page Break
_____________________
This command will cause a page break like this one:
===
This is the line after the page break.
_____________________
This command will cause a page break like this one: Items and Lists of Items
_____________________
-I-
o (item here)
-i-
_____________________
'Itemised' sections do not honour carriage returns and
allow a line break only after a new item. An Item is anything
behind the 'o' character, such as this:
---------------------
---------------------
Note that, in the RTF code, the no item bullets are shown,
depending on the version of word processor employed.
Structuring Statements
* is a Chapter
-*- is a Section
-**- is a Subsection
Referencing Statements
Type Symbol Expansion to
-----------------------------------------------------------------
Index entry #:test1:# entry in index
Reference point +:test2:+ bold face word being referenced
Hint to reference *:test2:test3:* (virtual|real) hypertext link
HASSLE receptor [:test4:test5:] (virtual|real) hypertext link
if 'jam' is configured
as such, HTML link to reflector,
otherwise only emphasised.
#:test1:# will become > <
+:test2:+ will become ><
*:test2:test3:* will become > test3 <
[:test4:test5:] will become > test5 <
Just Another Metafile Format (JAMF)
Motivation
Why no Translators?
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.
-------
Structure of this Document
JAMF Philosophy
Conditions of Use
JAM produced file:
THE1.HTML as [next page] , or [overview] , or [table of contents]
documentation