[ Previous chapter ][ This chapter ][ Next chapter ]
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.
Subsection 13.4.2 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.
-------
Subsection 13.4.3 Structure of this Document
Subsection 13.4.4 JAMF Philosophy
Subsection 13.4.5 Conditions of Use
[ previous chapter ],[
this chapter ][ next chapter ]
, [next page/section] , or [overview] , or [table of contents]