README of the Grobner Package for GAP 4
=======================================

Date:
=====
         8 March 2016

Version:
========

         1.0.3

Summary:
========
We provide algorithms, written in the GAP 4 programming language, for
computing Grobner bases of non-commutative polynomials with coefficients from
a field implemented in GAP, and some variations, such as a weighted and
truncated version and a tracing facility.

The word algorithm is interpreted loosely: in general one cannot
expect such an algorithm to terminate, as it would imply solvability
of the word problem for finitely presented (semi)groups.


Installation:
=============
To install GBNP, just unpack GBNP-1.0.3.tar.gz in the pkg subdirectory
of your GAP installation (or in the pkg subdirectory of any other
GAP root directory) with the following command:

tar -xvzf GBNP-1.0.3.tar.gz

GBNP is then loaded with the GAP command

gap> LoadPackage( "GBNP" );

Acknowledgments:
================
 - The package is based on an earlier version by Rosane Ushirobira
 - The bulk of the package is written by Arjeh M. Cohen and Dié A.H. Gijsbers.
 - The theory is mainly taken from literature by Teo Mora and Edward L. Green.
 - From Version 0.8.3 on the package has three additional files (fincheck.g,
   tree.g graphs.g) with routines for finding the Hilbert function and testing
   finite-dimensionality when given a GB by Chris Krook, based on work by
   Victor Ufnarovski.
 - From Version 0.9 on the package is enriched with support for GAP fields and
   additional prefix rules for quotient modules as well as some speed
   improvements by Jan Willem Knopper. Knopper has also formatted the
   documentation in GAPDoc.
 - From Version 1.0 on the package is extended with NMO (for Noncommutative
   Monomial Orderings) by Randall Cone. This enables the GBNP user to choose a
   wider selection of monomial orderings than the standard one built into GBNP
   itself. The files of this extension can be found in doc/nmo,
   doc/examples/nmo, and lib/nmo.

Authors:
========
    Arjeh M. Cohen & Jan Willem Knopper

Address:
=======
         RIACA,   Dept. Math. and Comp. Sc., TU/e,
         POB 513, 5600 MB Eindhoven, the Netherlands
         email A.M.Cohen@tue.nl J.W.Knopper@tue.nl

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.