Section 13-5: JAMF Specification

[ Previous chapter ][ This chapter ][ Next chapter ] (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 of the JAMF documentation and eventually execute 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..

Subsection 13.5.1

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 JAMF output format 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).

Subsection 13.5.2

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.

Subsection 13.5.3

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.

Subsection 13.5.4

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.

Subsection 13.5.5

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.

Subsection 13.5.6

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.

Subsection 13.5.7

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.

Subsection 13.5.8

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.

Subsection 13.5.9

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. 

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

Subsection 13.5.10

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 

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

Subsection 13.5.11

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

Subsection 13.5.12

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 

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

Subsection 13.5.13

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.

Subsection 13.5.14

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.

Subsection 13.5.15

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

Subsection 13.5.16

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  <

[next page] , or [overview] , or [table of contents]