Current documentation

Tue Jun 25 11:41:36 UTC 2002

This is the current state of EMBOSS documentation to the best of my knowledge.

EMBOSS documentation
--------------------

The current types and locations of documentation of EMBOSS are:

Files
=====
 - these are mainly plain text files in the EMBOSS distribution

Files in the EMBOSS top level directory
---------------------------------------
 - these are all distributed and are in the CVS tree

ChangeLog
 - a brief description of the changes made to any code for the
   next and previous releases. 
 - maintained by anyone who changes code
 - up-to-date

README 
 - a brief description of how to compile and install EMBOSS
 - maintained by (?)
 - up-to-date

FAQ 
 - a description of questions and answers on various topics in EMBOSS
 - maintained by Gary
 - OUT OF DATE

AUTHORS 
 - a brief list of authors
 - maintained by (?)
 - OUT OF DATE

THANKS 
 - thanks to people who have distributed code
 - maintained by (?)
 - OUT OF DATE

NEWS
 - brief description of changes in versions, now just says, see ChangeLog
 - maintained by (?)
 - up-to-date

Files in the EMBOSS 'doc/manuals' directory
-------------------------------------------
 - these are all distributed and are in the CVS tree

EMBOSS-FreeBSD-HOWTO.txt
 - how to install EMBOSS under FreeBSD
 - maintained by (?)
 - up-to-date ?

admin*
 - David Martin's Admin Guide
 - maintained by Gary
 - will be replaced by Peter Rice's Admin Guide

emboss_qg*
 - David Martin's EMBOSS Quick Guide
 - maintained by Gary
 - up-to-date (?)

internals*
 - Peter Rice's descriptions of the sequence access libraries
 - maintained by Peter
 - up-to-date

Files in the EMBOSS 'doc/programs/html' directory
--------------------------------------------
 - these are all distributed and are in the CVS tree
 - searched by wossname
 - this is a copy of the files in
   http://www.uk.embnet.org/Software/EMBOSS/Apps
   but will all HTML inline instead of using 'server-side includes'
   produced by running the script 'scripts/autodoc.pl'
 - maintained by Gary
 - up-to-date copy of http://www.uk.embnet.org/Software/EMBOSS/Apps

Files in the EMBOSS 'doc/programs/text' directory
--------------------------------------------
 - these are all distributed and are in the CVS tree
 - searched by wossname
 - this is a text copy of the files in the directory 'doc/programs/html'
   produced by running 'lynx -dump' as part of the script
   'scripts/autodoc.pl'
 - maintained by Gary
 - up-to-date copy of the directory 'doc/programs/html'

Files in the EMBOSS 'doc/tutorials' directory
---------------------------------------------
 - these are all distributed and are in the CVS tree

emboss-gcg.ppt
 - powerpoint file of talk given by Gary/Lisa May 2001 for those
   converting from GCG to EMBOSS
 - not maintained

emboss-interfaces.ppt
 - powerpoint file of talk given by Gary/Lisa May 2001 for those
   converting from GCG to EMBOSS
 - not maintained
 - OUT OF DATE (no mention of Jemboss)

emboss_tutorial*
 - TeX and PostScript files of the 'current' EMBOSS tutorial
 - authored mainly by Val Curwen
 - not maintained
 - COULD DO WITH A SUBSTANTIAL REWRITE

Files in in the EMBOSS 'emboss/acd' directory
---------------------------------------------
 - these are all distributed and are in the CVS tree
 - these are the .acd files
 - there is one file per application
 - they are generally maintained by the authors of the application
 - they contain the following types of documentation:

one-line documentation line 
 - to describe what the program does
 - it is displayed in many derived documents and programs
 - it is defined in 
   http://www.uk.embnet.org/Software/EMBOSS/Acd/syntax.html#Docattr9
 - The length of the doc: string should be kept to 63 characters or
   shorter in order to allow the wossname utility to display each
   program name and its documentation on one 80 character line. 
 - The doc: string should not end with a '.' character
 - Any acronyms or capatalised abbreviations in the doc: string should
   be written in upper-case.  (e.g: SNPs, EST, DNA, ABI, SRS, ASCII,
   CDS, mRNA, B-DNA, RNA, CpG, ORFs, MAR/SAR, PCR, STS, REBASE, SCOP,
   PROSITE, PRINTS, EMBL, TRANSFAC, BLAST, GCG, EMBOSS)
 - The doc: string should start with an upper-case letter. 

groups
 - to describe the general function of the program
 - it is defined in
   http://www.uk.embnet.org/Software/EMBOSS/Acd/syntax.html#Grpattr10
 - it is displayed in many derived documents and programs
 - the two-level structure and names of the groups are well-defined as a
   result of extensive negotiations with the Staden Team and other
   GUI-builders. 

prompts
 - each qualifier of the program should have a prompt
 - this information is NOT displayed anywhere when help is requested!

help
 - gives help on the qualifier
 - it is displayed in many derived documents and when running with '-help'
 - each qualifier can have an unlimited amount of text describing it.
 - THIS IS OFTEN MISSING
 - I suggest that all .acd files should be reviewed and help added as a 
   matter of urgency.

Web pages
=========
 - These are mainly HTML documents (also some text & GIF)
 - They are mainly hand-crafted
 - Top-level URL is
   http://www.uk.embnet.org/Software/EMBOSS
 - These files are NOT distributed with EMBOSS.
 - They probably should be distributed so that other sites can set up their
   own copies. 
 - They should certainly be included in the CVS tree so any author can
   edit them.

Index page
----------
 - Maintained by Gary
 - Up-to-date
 - Links to overview, applications, userdocs, interfaces, downloading,
   admin, internals, mailinglist, coordination, licencing, credits. 

Overview
--------
 - Brief description of EMBOSS
 - Maintained by Gary
 - Up-to-date

Applications
------------
 - Links to groups and EMBASSY application pages
 - Table of links to each applications's page
 - Maintained by Gary 
 - Up-to-date

Userdocs
--------
 - A link to the tutorial (a copy of the tutorial in the EMBOSS
   'doc/tutorials' directory)
 - Links to descriptions of:
   - Uniform Sequence Addresses
   - Sequence Formats
   - Alignment Formats
   - Feature Formats
   - Report Formats
 - All of these are maintained by Gary
 - Up-to-date

Interfaces
----------
 - links to Jemboss and other interface sites
 - Maintained by Gary
 - Some descriptions and links may need attention

Downloading
-----------
 - Brief description of how to download and unpack EMBOSS
 - Maintained by Gary and Alan
 - Up-to-date

Admin
-----
 - Links to David Martin's Admin Guide.
 - Maintained by Gary
 - Up-to-date (Admin Guide being re-written by Peter Rice)

Internals
---------
 - Links to:
   - Developer's Introduction
   - Guide to Writing EMBOSS Applications
   - Ajax Command Definition
   - Ajax Library documentation 
   - Nucleus Library documentation
   - PLplot Graphics Library original documentation 
   - EMBOSS C programming standards
   - EMBOSS code documentation standards 
   - EMBOSS user manual standards 
   - C versus C++
   - Using the CVS Server
   - EMBOSS Interface Projects 
   - EMBOSS Database Definitions 
 - Links to EFUNC and EDATA which are SRS databases of the documentation
   derived from the comments in the headers of Ajax and Nucleus routines
   automatically created by running the script 'scripts/emboss*.pl'
 - All of these are maintained by (?)
 - Up-to-date (?)

Mailinglist
-----------
 - Brief description of the mailing lists
 - Maintained by Gary 
 - Up-to-date
 - Should we have a searchable archive of messages?

Coordination
------------
 - Links to minutes of planning meetings
 - Maintained by Jon
 - Up-to-date

Licencing
---------
 - Description of GNU Licence
 - Maintained by Gary 
 - Up-to-date

Credits
-------
 - People who have worked on EMBOSS
 - Maintained by Gary
 - Up-to-date (?)

Individual application documentation
====================================
 - The primary documentation for the programs is held in 
   http://www.uk.embnet.org/Software/EMBOSS/Apps/
 - The documentation is processed and also held in the EMBOSS directories
   'doc/programs/html'  and 'doc/programs/text'  (see above).
 - The documentation is held in an HTML file whose name is simply the
   name of the application with the extension '.html'. 
 - There are many server-side includes. The standard ones are:
   inc/*.ione - file containing the one-line description as produced by
      the application 'wossname'
   inc/*.ihelp - file containing the -help output by 
      'application -help'
   inc/*.itable - file containing the command table as output by 
      'application -help -acdtable'
   inc/*.isee - file containing the associated programs as output by the
      application 'seealso'
 - The rest of the file is hand-edited.
 - The script 'scripts/edithtml.pl' allows you to create a web page by
   filling in details of the description, usage, input and output files,
   etc. It uses the template file 'template.html.save' as a starting point.
 - The script 'scripts/autodoc.pl' will go through all of the
   applications updating any whose help details have changed and offering
   to commit them to the CVS tree for you. 
 - The example usage and input and output example files should be the
   same as in the 'test/qatest.dat' QA testing data.  Some applications
   have this, but not all.  It would be useful if this information could be
   derived from the QA tests automatically. 
 - Maintained by Gary
 - NOT UP-TO-DATE - still waiting for documentation from the authors of
   many Protein structure applications!