Program Documentation Standards

We considered a number of code documentation methods, and have selected one that is used by other projects, including wise2, at the Sanger Centre. The essential features are described below.

Words to be hyperlinked to URLs are defined at the start, one per line, and referred to as /{Word} later in the text, thus:

:ref Word http://www.url.addresss/

Headings are defined on one line, with 1 or more ">", with named entry points thus:

>Introduction    # ref:intro
>>Overview       # ref:overview

Paragraphs are identified by a single "." on a line.

Lists are defined as list structures, with hotlinks if necessary, thus:

:list
:: /{ref1} text1/
:: text2
!list

In this case, text1 is defined as a link to ref1 and text2 is plain text.

Examples from user terminal sessions are defined as shell structures thus:

:shell

%"ftp ftp.sanger.ac.uk"
Connected to netra.sanger.ac.uk.
220 netra FTP server (Version wu-2.4(2) Fri Nov 1 15:58:24 GMT 1996) ready.
Name (ftp.sanger.ac.uk:joe): "anonymous"
331 Guest login ok, send your complete e-mail address as password.
Password:"joe@bio.somewhere.edu"
...
...
...
ftp>"cd pub/somewhere"
ftp> "get file.tar.Z"
...
...
...
ftp>"quit"
!shell

All text in quotes is marked up in bold to show text typed in by the user.

Shell structures are automatically indented by 2 spaces.

Other quoted blocks can be represented as code structures thus:

:code
setenv ENVVAR /my/dir/tree
!code

:code perl

        # perl script

        ...
	system("blastx swiss $dna.fasta > $tempdir/$dna.blast.$$");
	system("MSPcrunch -x $tempdir/$dna.blast.$$ > $tempdir/$dna.exblx.$$");
	system("postwise -fetch 'getz5 -sf fasta -d \'[swissprot-id:%s]\'' $dna.fasta $tempdir/$dna.exblx.$$ > $dna.post");
	
!code

The "code perl" seems to do nothing extra - but we will look more closely.

The structures available are:

Name	Descriptions
:module
:code
:ref
:list

---