JAMF Archive

BioCompanion as published in 1995
THIS 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.

JAMF source code

LATEX version source code

	

location: Home > Archive > BioCompanion V2.x (1995)

Chapter 13: Appendix

Appendix


What is an Operating System?

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" .

VMS

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.

UNIX: ULTRIX

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.

UNIX: OSF/1

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.

UNIX: SunOs

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.

UNIX: Solaris

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.

UNIX: IRIX

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).


Technical Issues: Local Setup

Account

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.

Equipment

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 Network

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.


Technical Issues: Networking

Internet

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.

'ftp'

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'

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.


Just Another Metafile Format (JAMF)

Motivation

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.

Why no Translators?

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:

 
This program (page 17) has been discussed earlier.  

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:

 
This program (see also, \ref{seqed}) has been discussed earlier.  

Appearance:

 
This program (see also, 3.1.5) has been discussed earlier.  

Source code

 
This <a href=editing#seqed> program </a> has been discussed  
earlier.  

Appearance in the browser:

 
This program has been discussed earlier.  
     -------  

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.

Structure of this Document

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.

JAMF Philosophy

KISS - Keep It Stupid Simple

We anticipate the benefits of JAMF to be as follows:

This list is neither exhaustive nor complete. please refer to the next chapters for details.

Conditions of Use

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.


JAMF Specification

(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..

Files

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.

NOTE: If you edit JAMF files in word processors or other programs which allow formatting, makes sure that the desired files are saved in TEXT WITH LINE BREAK format of possible.

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).

Input Flexibility: Customisation of Scope

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.

Comment Statements

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.

Conditional Statements

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.

Conditions

Three keywords are recognised after the first column , which must be a pound sign (#):

 
#ifdef  
#else  
#endif   

The nesting of #ifdef statements is fragile as it is possible to extend them across files.

Inclusion

The include keyword is recognised after the first column , which must be a pound sign (#):

 
#include  

It is possible to include files in several levels. Unfortunately, this also allows to create loops recursively, which must obviously be avoided.

Formatting Statements

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:

 
 ___________________  
  
  
 -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  
 
------------  

Note that the indentation of verbatim, if anticipated, must be inserted manually.

Verbatim Formatting

Format:

 
 ___________________  
  
 -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

Format:

 
 _____________________  
   
 -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:
 
 ---------------------  

Special text here.

 
 ---------------------  

Emphasised Text

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:

 
 _____________________  
   
 This is   
 -E-  
 text here,  
 -e-   
 in emphasised fashion  
 _____________________  
  
'Emphasised' text can be used to attract attention.

Appearance:

 
 ---------------------  

This is text here, in emphasised fashion

 
 ---------------------  

Reference Links

Format:

 
 _____________________  
  
 -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:
 
 ---------------------  

Reference:

 
 ---------------------  
This is the same result as
 
 ---------------------  

Reference:

 
 ---------------------  
The second link did not inherit the -l-.

Line Breaks and Paragraphs

Format:

 
 _____________________  
  
  
 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

test1 test1 test1 test1 test1 test1 test1 test1 test1 test1 test1 test1 test1 test1 test1 test1 test1 test1

 
 ---------------------  

Page Break

Format

 
 _____________________  
  
 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:



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.

Items and Lists of Items

Format:

 
 _____________________  
  
 -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

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:

 
 *      is a Chapter   
 -*-    is a Section   
 -**-   is a Subsection   

Referencing Statements

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.

 
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.   

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.

 
#: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]