program shell(afile, shellp, bfile, output); (* shell: Example Delila System program (an empty shell) Thomas D. Schneider, Ph.D. National Institutes of Health National Cancer Institute Gene Regulation and Chromosome Biology Laboratory Molecular Information Theory Group Frederick, Maryland 21702-1201 schneidt@mail.nih.gov toms@alum.mit.edu (permanent) http://alum.mit.edu/www/toms (permanent) *) label 1; (* end of program *) const (* begin module version *) version = 3.00; (* of shell.p 2010 Sep 18 2010 Sep 18, 3.00: upgrade address 2005 Sep 01, 2.05: upgrade address 2004 Sep 10, 2.04: upgrade name 2000 Dec 4, 2.03: explain synopsis file types 2000 Nov 12, 2.02: the shell.p version number is here 1987 Sep 21, 1.00: origin *) updateversion = 1.00; (* defines lowest acceptable current parameter file *) (* end module version *) (* begin module describe.shell *) (* name shell: Example Delila System program (an empty shell) synopsis shell(afile: in, shellp: in, bfile: out, output: out) files afile: multiple line detailed description of the first file. bfile: multiple line detailed description of the second file. shellp: parameters to control the program. The file must contain the following parameters, one per line: parameterversion: The version number of the program. This allows the user to be warned if an old parameter file is used. The convention is that the name of the parameter file is formed by taking the name of the program and adding a 'p' on the end. Usually there are many parameters. Parameters are left justified when characters. Numbers can have spaces in front. Anything to the right is a comment. A useful trick is to insert a new temporary parameter on the left side while trying something out. For example, in makelogo there is a range parameter, which is two integers (from - to in bases for the sequence logo). So one might have: -20 +20 FROM to TO range to make the logo over The trick then would be to set the range bigger with -200 +200 -20 +20 FROM to TO range to make the logo over This way one can simply delete the new range to put it back the way it was. (Note that the "+" is not necessary, but often helps in visually identifying that a pair of numbers is a range.) makelogop: parameters for the makelogo program, version 8.76 or higher Be sure to check out the atchange program (see a link to it in the See Also section below). output: messages to the user description The purpose and use of the program. - This page is intended to be copied and edited for making new programs. To make it easy to add information later, do not delete sections, just leave them blank if they are not in use. - Here are descriptions of each section of the documentation: - The name section is a single line, always less than 78 characters, that briefly describes what the program does. - The synopsis defines the input (":in") and output (":out") files of the program. In rare cases there is also an input/output file ("inout"). Starting 2000 Dec 4 I will indicate one more kind of input, "stdin". This applies to any file named 'input', which is treated specially by pascal to mean the keyboard. Under unix operating systems it is the standard input file. For programs that use stdin, one can pipe the results into the program or redirect it. For example, rb < myfile > myfile.without.extra.blanks - The file section describes each file in detail. Delila programs frequently use many input and output files in parallel. The name given in the documentation must corresponds to a file in the current directory. This is a feature of Pascal that is either a blessing or a curse. It is a blessing because one can always identify the file by name. It is a curse because the name is not descriptive. So, for example, an input file to the Delila program is the inst file (instructions). This is not very descriptive! So I will often work with a descriptive name, fis.inst, for example. But Delila won't read that file, so it would be painful to keep copying fis.inst to inst. This is where the atchange program (see link below) comes in handy. I just work on the inst.fis file and have atchange copy it over to inst and then run delila automatically. - Any file that is mentioned as an "in" in the synopsis will need to be in your current working directory (under Unix). You do not need to make the output files, they will be generated automatically. Be sure that you don't overwrite something important. (RTFM to see which files are required by any particular program. RTFM stands for "Read The Manual", an old joke from MIT ;-) - The description section explains how to use the program. In the case of the shell program, it describes how to use Delila programs in general. - Examples are often worked out for you. They usually will correspond to examples in the See Also section. - Documentation is usually publications. - The See Also section contains active web links. - I'm putting those silly dashes on the left side so that this entire section is one paragraph. This allows me to delete the paragraph with the command "d}" in the text editor vi. examples An example of the use of this form is module describe.lister. See the link to the lister program below. Parts of documentation: name synopsis files description examples documentation see also author bugs technical notes documentation Other sources of information or documents on the program. see also {Example program with extensive documentation:} lister.p {} {In this section, text inside curlie brackets is copied and text outside become web links by the program} htmlink.p {.} {} {The ergonomic and fast vi program is described at} http://www.lecb.ncifcrf.gov/~toms/vi.html {} {The atchange program will automate your world:} http://www.lecb.ncifcrf.gov/~toms/atchange.html {} makelogo.p {uses the ranges mentioned in the section above about parameters.} {} delila.p {is the main program of the Delila system.} {} {Information about ranges is in the glossary:} http://www.lecb.ncifcrf.gov/~toms/glossary.html#range {} {The rb program mentioned above is:} rb.p author Thomas Dana Schneider bugs problems with the program and how to get around them (if known). technical notes Details about the implementation that may be relevant to a user. *) (* end module describe.shell *) var afile, (* file used by this program *) shellp, (* file used by this program *) bfile: text; (* file used by this program *) (* begin module halt *) procedure halt; (* stop the program. the procedure performs a goto to the end of the program. you must have a label: label 1; declared, and also the end of the program must have this label: 1: end. examples are in the module libraries. this is the only goto in the delila system. *) begin writeln(output,' program halt.'); goto 1 end; (* end module halt version = 'delmod 6.16 84 mar 12 tds/gds'; *) (* begin module shell.themain *) procedure themain(var afile, shellp, bfile: text); (* the main procedure of the program *) var parameterversion: real; (* parameter version number *) begin writeln(output,'shell ',version:4:2); reset(shellp); readln(shellp, parameterversion); if round(100*parameterversion) < round(100*updateversion) then begin writeln(output, 'You have an old parameter file!'); halt end; end; (* end module shell.themain *) begin themain(afile, shellp, bfile); 1: end.