JAMF ArchiveBioCompanion as published in 1995THIS IS THE REFERENCE CODE AS PUBLISHED. Doelz, R. Optimal production of biological documentation: the JAM format. Comput. Applic. Biosci. 11, 224-226 (1995).The version you are currently viewing is the one printed and distributed via the Internet from the server of BioComputing Basel. Version 3.1 of the BioCompanion was published with version 2 of the JAMF software. The server that was indicated in the documentation has ceased to exist. Version 3.2 of the BioCompanion was not publicly available for free but was shareware that was distributed with GCG's software release 9. For the purpose of enhanced editing, JAMF was partially rewritten and the proprietary version 3.x of JAMF was used from 1996 onwards. The Biocompanion is available in a current version from the publisher . It has significantly changed both in software and content. |
|||
|
|
|
||
The following list of multi-user operating systems is neither
complete nor expected to be exhaustive. It simply explains some
names and terminology. In particular, the UNIX type of operating
system comes in two main flavours:
Berkley-type of UNIX (somewhat historically
as it is no longer exclusively shipped), and the most recent
version of UNIX System V
, release 4. It should be noted that the operating systems which
are generally used on personal computers (DOS, Windows, Macintosh
), do not run a multi-user operating
system . The main characteristics
of the larger systems are a user identification which is associated
with a reserved area on a storage device (hard disk), and access
and other privileges associated to the particular computer, such
as system management functions. The most privileged user is usually
called "root"
or "SYSTEM"
.
The VMS operating system is a proprietary
operating system manufactured by the company Digital Equipment
Corporation (DEC).
It used to run exclusively on VAX processors,
but newer machines of DEC can also run VMS on ALPHA processors
(also called AXP processors). The latter
can also run the OSF/1 flavour of UNIX (see below). VMS is called
OpenVMS today. The most current version as of this writing was
VMS 6.1.
The original VAX processors of the
company DEC (see above) were also capable of running the ULTRIX
operating system, which is another flavour of the UNIX (Berkeley
style) operating system. Later, the MIPS processors R3000 and
R4000 were used in classic "DEC stations". ULTRIX is currently
being phased out, as it is not supported on DEC's new AXP processors.
The last ULTRIX version was 4.3 with some alphabetic letter.
The OSF/1 operating system is the most
recent variant of DEC's implementation of UNIX on the AXP chip.
Most of the former Berkeley-style, and all System V type of UNIX
commands are expected to work correctly. The OSF/1 system is
available for the AXP chip of DEC. The most recent version of
OSF/1 at the time of this writing was 2.0.
The machines produced by the company
SUN used to run an operating system which
was a classic Berkeley-type of UNIX. Famous architectures like
Sun3 and Sun4, but also the early SPARCstations
used to run SunOS in a version which was more recently renamed
from SunOS 4.x to Solaris 1.x.
The most recent computers built by
the company SUN run an operating system called Solaris. This
system is mostly System V- like with some earlier Berkeley extensions
to enhance backwards compatibility. The most recent version was
Solaris 2.5.
The computers manufactured by the company
Silicon Graphics run an operating
system called IRIX. The current shipping version (5.3 and 6.0,
resp.) is System V-type UNIX. IRIX runs on the MIPS type of chip
(3000, 4000, 8000 and related).
In order to access a computer which is shared by others,
the method of choice is to use a name which
identifies your personal area in the computer. It will define
your disk space, privileges to do certain things and also allow
for security, as you are not expecting
others to read your private data. The name given to you is the
so-called account name. You might have several
accounts on a single computer, or use the same account on different
computers.
The cheapest and most widely used equipment in the past was
a vt100 - type of terminal. This is a text screen which allows
you to type in commands. No mouse was required, and the required
amount of data to be sent from and to the terminal is low. Many
colleagues still use this type of access using so-called terminal
emulators which run a program locally on the PC or Macintosh,
and simulate that the PC will behave as if it were a terminal.
Capabilities of the PC or Mac, then, become that of the terminal
emulated, which means that you will most probably not use the
mouse or local hard disk.
Local area networks are different from the commonly used term
"network" as the network on-campus is considered to be "trusted".
This applies specifically to the data which are possibly of proprietary
interest, or should be protected otherwise.
Usage of X One common
way to share resources over the network is to use the X-Windows
system. This allows a larger computer to open a window on your
local screen even if it is not using the local CPU to do so.
To achieve this, you must run a program
on your local desktop which will allow the remote computer to
send the window. If your local desktop is a PC or Macintosh,
you need to ask your local experts where to obtain this software.
Be warned, however: The use of the X-Windows system takes a lot
of resources and might not perform as fast as you are expecting
it to run. You also should take into consideration that a large
screen is required if you want to
display many windows simultaneously.
The Internet is the world-wide communication network, also
known as information highway and Datenautobahn.
SECURITY ADVICE: The databases and database engines of
the Internet do not run under the control of the local administration.
Access to these data or programs might result in answers which
are potentially not matching the quality constraints applied
usually. NO PROPRIETARY DATA MUST BE EXPORTED TO THE INTERNET
WITHOUT PRIOR CLEARANCE BY AUTHORITIES. This is true in particular
for industrial and other non-academic sites.
Each computer has its own number and name on the Internet.
If you are living in a closed environment, your connection to
the Internet will be via a
gateway or so-called "firewall". To protect your data from losses,
and avoid that undesired guests get into your system, the use
of Internet programs or Internet in general might be disabled
or restricted at your site.
Do not mix up the Internet protocols with the Internet itself.
The 'telnet' , World-Wide
Web and 'ftp' programs are so-called protocols
which will work regardless of your Internet connection.
These protocols are used to connect computers using a "language",
and will also work locally on the local area network.
HASSLE is the name of a network protocol
software which allows applications to be run remotely. Its current
application is in the biological area. The current version number
is 5, and was written by F.Eggenberger, R.Doelz and N.Redaschi.
As HASSLE is a protocol application, suitable input must be provided
by other programs. The current area of application is focussed
on Biology. In order to either integrate HASSLE into an existing
program environment (e.g., the GCG environment (see below)),
or to prepare input data from scratch, dedicated applications
are provided which are either programs or scripts and similar
procedures.
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.
(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. What is an Operating System?
VMS
UNIX: ULTRIX
UNIX: OSF/1
UNIX: SunOs
UNIX: Solaris
UNIX: IRIX
Technical Issues: Local Setup
Account
Equipment
Local Area Network
Technical Issues: Networking
Internet
'ftp'
'HASSLE'
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
JAMF Specification
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 <
JAM produced file:
APPEND13.HTML as [next page] , or [overview] , or [table of contents]