This is information for authors about what files they should and should
not edit. Users should find more information in the README file in this
directory or in manual.*, chapInd.html or chapInd.txt in the doc
subdirectory.

Files to edit for documentation:
===============================
The following files can be edited to change the documentation:
- version/README.in for README
- version/PackageInfo.g for PackageInfo.g

- doc/gbnp_doc.xml.in to edit the manual. This manual also includes:
  + lib/*gi for included function descriptions
  + doc/examples/*g for examples in the manual
  The manual is written in GAPDoc format, see also 
  http://www.math.rwth-aachen.de/~Frank.Luebeck/GAPDoc/index.html

- version/README (information about the files in version/)
- TODO (list of some things that could be done)
- doc/TODO (some things that could be changed in the documentation)
- lib/OPTIONS (information about some options)
- lib/TODO (some things that could be changed in the code)
- GNUMakefile (can be edited to change the version)
- README_AUTHORS (this file)
- COPYRIGHT (copyright text)

Files that are overwritten automatically: (do not edit)
========================================
- README and PackageInfo.g
- in doc: gbnp_doc.xml and also manual.* chap*
- in examples: *xml
- in test: all files

To rebuild the documentation:
=============================
>gmake clean (NOTE: this deletes files)
>gmake workspace (for faster running of exercises)
** enter the ``export GAP="..."'' line shown to the shell ** (for use with
	bash, *csh users modify this line, it might also be added to your
	.profile)
>gmake doc

To rerun individual examples:
=============================
- cd doc/examples
- ../../scripts/gapscript example07
  (for example07.g)
  (setting $GAP after gmake workspace speeds this process up)

To update the uses/used in lines:
=================================
A sed script to update these is generated by a different program gap-calltree,
which is in the private subversion. Here a GNUmakefile exists which generates
"gbnp-uses.sed" as well as a graph in gxl and dot format (but the graphs
contain too many nodes to be useful).

to run gap-calltree
- cd lib
- cat *gi > gbnp-all.g
- cd ../../gap-calltree
- start gap
- (in gap) Read("init.g");
- (in gap) Read("read.g");
- make gap-uses.sed
- cp gap-uses.sed ../gbnp/lib

to update the files do something like:
- cd lib
- mkdir tmp
- cp *.gi tmp/
- cd tmp/
- for i in *gi; do sed -f '../gbnp-uses.sed' "$i">../"$i";done
- cd ..
- rm -r tmp/
Now check against the subversion repository and commit if everything seems all
right.

Updating copyright text:
========================
The copyright text can be found in the file /COPYRIGHT. This file can be
edited by the authors. A file containing the COPYRIGHTS in comment format can
be generated by: 
- gmake comment

This generates build/COPYRIGHTcmt and a vim-script build/changecomment.vim
which allows to modify the comment semi-automatically with 
  vim -s ${SCRIPTNAME} ${SOURCEFILE}
Example:
- for i in lib/*.gd lib/*.gi scripts/* read.g init.g make_doc.g testall.g doc/examples/*.g doc/examples/GNUmakefile doc/examples/makedepend GNUmakefile; do \
    vim -s build/changecomment.vim "$i" ;\
  done

- in vim check if the result is correct and save with ZZ
- also check before submitting to subversion by using "svn diff" first

For a release:
==============
- (optional) update the uses/used in lines (see item above)
- (optional) update the copyright text (see item above)

- check the version in GNUmakefile
- check the date (two formats!) in GNUmakefile
- check doc/timing.xml
- gmake clean
- gmake workspace
- copy the line to set $GAP (if it is not already set)
- gmake www
- cd test && gmake svn (to check for undesired changes)
- copy www to the webdirectory and enter the url of the PackageInfo.g at
  http://www.gap-system.org/Packages/Authors/authors.html
  to verify it.

