The current environment for providing documentation for users in molecular biology frequently requires written information for both printed and electronic media. The JAM (Just Another Metafile) Format requires that only a single file of text is written. This is, then, processed by the jam program which converts this text to a document set which is suitable for on-line documentation in the hypertext mark-up language (HTML) of the World Wide Web system. For printed output, the jam program can produce either text in wordprocessor-ready Rich Text Format (RTF), or source code for the LaTEX typesetting system. The latter allows for professional text layout and can generate, amongst other formats, postscript files to be printed on a variety of device

Doelz, R.

RERO DOC Digital Library

CABIOS COMMUNICATION Vol. 11 no. 2 1995Pages 224-226Optimal production of biological documentation:the JAM formatR.DoelzAbstractThe current environment for providing documentation forusers in molecular biology frequently requires writteninformation for both printed and electronic media. TheJAM (Just Another Metafile) Format requires that only asingle file of text is written. This is, then, processed by thejam program which converts this text to a document setwhich is suitable for on-line documentation in the hypertextmark-up language (HTML) of the World Wide Websystem. For printed output, the jam program can produceeither text in wordprocessor-ready Rich Text Format(RTF), or source code for the LaTEX typesetting system.The latter allows for professional text layout and cangenerate, amongst other formats, postscript files to beprinted on a variety of devices.Today, documentation in the biocomputing disciplinesmust be available in various formats. Users who havenever used computers for biocomputing purposes beforewill not easily adopt all-electronic information and requireprofessionally printed material. Colleagues at remote siteswho wish to print the text locally in chapters, or send itaround in electronic Mail messages, require a reasonableformat to communicate structured text which can befurther processed on-site. Electronic hypertext systems, onthe other hand, have become increasingly popular inrecent years and have the tremendous advantage that thecross-references are much more intuitive and easy tofollow with sophisticated browsers such as Mosaic (aprogram that interprets and displays hypertext asformatted 'pages', and allows to follow links with mouseclicks).For documentation that has been created in the biologyuser support sector, the use of translators provided apreliminary way of switching between different media.Various elements of text structuring and cross referencesare similar between the printed and electronic formats,and allow translators to achieve a one-to-one imaging ofthe text formats. However, the detailed wording andpresentation to the user are different and depend on thecontext of the document. Some information is lost duringBiocomputing, Biozentrum der Universittlt Basel, Klingelbergstrasse 70,CH 4056 Basel. Switzerlandthe translation, and the reader might have difficulty tounderstand details.The required formats include the plain text as used inword processors on personal computers, text preparedfor the LaTEX typesetting system, and 'hypertext mark-up language', HTML. The following example illustratesthe desired appearance, which cannot be achieved bytranslators:ASCII TEXTThis pro gram has be en discussed earlier.LaTEX source (usually not visible to the user)This program (see also, \ref{seqed}) has beendiscussed earlier.LaTEX appearance:This program (see also, 3.1.5) has beendiscussed ear l ie r .HTML source (usually not visible to the user)This < a href = editing#seqed > program < /a > hasbeen discussed earlier.HTML appearanceThis program has been discussed earlier.To avoid the obvious shortcomings of translators, whichwere unable to create the explanatory wrappers forcrosslinks as depicted above, we have created the JAMformat in order to produce different formats from onesingle source. This source can be edited and handledindependently and does not require that either of the toolsfor formatting (Word processor, LaTEX or WWWbrowser) is available during editing.The Just Another Metafile (JAM) formatThis JAM format is suited to be translated into eitherLaTEX, hypertext markup language (HTML), or RichText Format as commonly accepted by word processors.An alphabetical index as well as a table of contents isprovided within each different format.All resulting presentation takes full advantage of thespecific capabilities of the word processing system used.LaTEX processingThe jam program produces a LaTEX source file which canbe processed with the usual LaTEX procedures. LaTEX224 © Oxford University PressOptimal production of biological documentation: the JAM formatprocessing requires an additional stylesheet which comeswith JAM in order to be processed, and the makeindexutility to generate the correct index {makeindex is part ofeach LaTEX installation).On-line version in HTMLThe jam program produces a set of files which can beviewed after proper installation with any WWW client.Both LYNX and Mosaic type of viewers are supported,i.e. there is no need for sophisticated FORMS support.Jam allows specific hypertext links for referencingelectronic sources.Electronic /printed version in RTFThe RTF version generated from JAM Format has arunning head for nice printing in word processors.Hypertext links outside of the document are not resolvedbut hidden text elements are available to create both indexand table of contents if this feature is available within theword processor.Other formatsThe jam program implementation is clearly structured andeasily allows the adaptation of other formats such as plaintext (ASCII, not covered in the distributed version).JAM processor availabilityThe jam program has been implemented on the OSF/1flavour of the UNIX operating system and was success-fully compiled on IRK, ULTRIX, ATX, Solaris, AXP/VMS, VAX/VMS, Microsoft Windows 3.11 and Mac-intosh 7.1 operating systems. The JAM Format has beendeveloped at the Biocomputing Facility in Basel over theyears and was put into the public domain in 1994. Thecode is available from the author (doelz@comp.bioz.unibas .ch) on request, or via anonymous ftp fromb i o f t p . u n i b a s . c h in the programs/b iof tp-sw/jam directory. Binaries as well as source code areavailable. In order to recompile the code with thegraphical user interface, the VIBRANT toolkit (Kahnset ai, NCBI) must be installed.Application of the JAM FormatThe 'Biocomputing Survival Guide' is a cookbook whichwe have prepared at our site for the computer novice. Itallows users unfamiliar with molecular biology computingto work in our environment effectively and with ease. Wehave updated the guide as version 2.0 and rewritten it inJAM format. The Guide can be translated into either aVMS or a UNIX version, and allows for site-specificdetails within more than ten include files. The overallmaterial to be changed to adapt the guide to a given site isless than five pages and can be modified with great ease.We have further created a 'teaching application' usingthe JAM format. Courses which we offer at theBiozentrum include 'question sheets' and 'answers'. Theanswers explain how to approach the problems mentionedin the 'question sheets' using the 'Biocomputing SurvivalGuide' as a reference. The 'Biocomputing Survival Guide',the 'question sheets', the 'answers' and all reference datarequired to cross-check the obtained results are availablevia anonymous ftp on b i o f t p . u n i b a s . c h in thea r c h i v e _ d a t a / s u r v i v a l directory tree in eitherRTF or LaTEX format. The HTML versions are alsoon-line as hypertext version, on the URL (universalresource locator) h t t p : / / be ta . embne t . u n i b a s .c h / b a s e l / c o u r s e . h t m l you will find a page to guideyou to the various parts of the teaching and documenta-tion section.CustomizationIn order to utilize documentation containing site-specificinformation, extensive editing is usually required. TheJAM text source, however, may contain several configur-able files which hold site-specific information such ascontact addresses for the local computing centre, whicheditor to use, and similar localized elements. The localinformation, as well as the residual text, therefore allowsthe adaptation of individual elements in a single fashion,i.e. both UNIX- and VMS type of environments may bedescribed in the same text tile. In order to adapt adocument for different environment than the one it wasoriginally developed for, it is sufficient to modify only site-specific files which are included into the document by thejam program. Both 'Biocomputing Survival Guide' andteaching material, therefore, may be easily adapted to fitindividual needs.JAM Format specificationThe format has several classes of statements, which areprocessed in the following order:CommentsThe percent (%) character in column 1 of a line indicates acomment.Conditional statementsThe processing directives are extremely simple and similarto the C-pre-processor and expanded before the format-ting statements. The use of #if def, #else , and #endifstatements allows several configurations in the same225R. Doebformat (i.e. VMS and UNIX) to be written in the sameJAM source code. Another conditional statement is the#include directive that permits site-specific text to bewritten in separate files, which allows a readily availablegeneral version to be 'adapted' to specific sites easily.Formatting statementsIt is required to display four different types of non-flowtext. These are• verbatim (e.g. all is printed as written)• itemized (such as this text)• special (e.g. different appearance but not verbatim,used for 'examples')• explicit links (most useful for the HTML version)Each of these formatting statements inserts a break in thecurrent text flow and a new line starts after each of theseformatting statements. For example, verbatim is printedas written and all formatting of the original text will beretained. Special sections are for examples and similarlyemphasised text. Itemized sections do not honourformatting, but rather build a list-like appearance.Explicit Link sections display a hypertext link in theHTML version, whereas in the text version the link is onlydescribed in writing.Structuring statementsStructuring statements are processed after the conditionaland formatting statements and are automatically num-bered. The text structure permits three levels. Chapters,Sections, and Headlines are implemented.Referencing statementsThe purpose of referencing statements is to allow indexingand transparent reference insertion. Index entries, pointersto anchors and anchors are allowed.Detailed syntax descriptions, hints, recommendationsand examples how to implement various elements ofspecific text are included in the documentation of theprogram distribution.Received January 20, 1995, accepted February 6, 1995226

Optimal production of biological documentation: the JAM format

Abstract

Similar works

Full text

Available Versions

RERO DOC Digital Library