|
By downloading this code you agree to the
Source Code Use License (PDF). |
{ version = 3.03; (* of shell.p 2018 Feb 23}
(* begin module describe.shell *)
(*
name
shell: One line description: 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
https://alum.mit.edu/www/toms/vi.html
The atchange program will automate your world:
https://alum.mit.edu/www/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:
https://alum.mit.edu/www/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 *)
{This manual page was created by makman 1.45}
{created by htmlink 1.62}