vkd.sp Specification of the vkd module
Version 0.1 - RA Parker  17.08.07

General
-------

The vkd module has a type "VKD" that holds van Kampen diagrams.  There
is also a specified "first" generator on the black face.

It should be noticed that 

----------xxxxxxxxxx----------xxxxxxxxxx----------xxxxxxxxxx----------xx

1.   vkd shall provide a header file vkd.h that shall provide

1.1  Typedef of a VKD type suitable for holding a van Kampen Diagram.
     in practice this may be a "void" or "int", since a vkd module that
     wishes to handle several orderings may well need to vary the 
     definition of the "VKD struct" at run time.

1.2  Prototypes for all the routines listed in section 2 

----------xxxxxxxxxx----------xxxxxxxxxx----------xxxxxxxxxx----------xx

2.   vkd shall provide the source code to implement all of the
     following functions.

2.1  int vkdorder(int * blimp7)
     so set the vkd module to work with the ordering defined in blimp7.
     This invalidates all existent VKDs, of which there should be none
     (since it is no longer even possible to vkddest them!) and sets
     some global memory to be ready to work with the ordering 
     specified.  If the ordering is acceptable, a positive number is
     returned (that may later indicate what functions work).  If the
     ordering is not acceptable, a negative number is returned.
2.2  VKD * vkdface(int * word, int len)
     to construct a VKD populated with a one-face diagram consisting of
     the given word only.  A pointer to the constructed VKD is returned.
     The specified first generator of the VKD is the first letter of 
     the given word.
2.3  void vkddest(VKD * vkd)
     to destroy the given VKD and free all the memory assiciated with
     it.
2.4  int vkdblack(VKD * vkd, int * word)
     to put the black face of the given van Kampen diagram into the
     area pointed to by "word", starting with the specified first 
     generator.  The length of the word is returned.
2.5  VKD * vkdjoin(VKD * vkd1, int rot1, VKD * vkd2, int rot2, int drop)
     A new VKD is constructed by joining together the two given VKDs.
     the join is made at the point rot1 from the specified first 
     generator of vkd1, and rot2 from the specified first generator of
     vkd2.  The specified first generator of the result shall be this 
     point of joining,  and "drop" generators "cancelled".  Hence the
     resulting black face is vkd1 rotated rot1 1 times then "drop" 
     letters removed from the right-hand end, followed by vkd2 rotated
     rot2 times, with "drop" letters removed from the left hand end.
2.6  int vkdshort(VKD * vkd)
     returns 1 if the proof is strictly shorter than the black face.
     otherwise 0 is returned.
2.7  int vkdcomp(VKD * vkd1, VKD * vkd2) 
     to compare the two VKDs.  If vkd1 is smaller, -1 is returned.  If
     vkd1 is larger 1 is returned.  If they are of the "same size", 0
     is returned.

----------xxxxxxxxxx----------xxxxxxxxxx----------xxxxxxxxxx----------xx

end of vkd.sp.