README_AUTHORS

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:

- doc/gbnp_doc.xml 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

- 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)
========================================
- in doc: manual.* chap*
- in examples: *xml
- in tst: 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
- ../../etc/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 etc/* read.g init.g makedoc.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:
==============
Use https://github.com/gap-system/ReleaseTools