dev_notes.txt

Development notes file:
* started by Marco Costantini
* updated by Alexander Konovalov

This file contains notes for development and for releasing a new version; 
it is not intended to be a part of the release.

###########################################################################

MAKING A CHANGE:

* update the local GAP.dev installation

* build the manual and manual test files with 
  
ReadPackage("openmath/gap/buildman.g");

* test the package functionality:

Read( Filename( DirectoriesPackageLibrary( "openmath", "tst" ), "testall.g" ) );

* do the changes.

* check that new features or bug fixes are included in the test file, 
  and, if test file is modified, test the package functionality.

cd /usr/local/gap_dev/4.0/pkg/openmath/tst
nano test_new.src
mv test_new test_new.bak
gap -T -r -A -b < test_new.src
nano +30000 test_new

(to remove lines after STOP_TEST)

diff test_new test_new.bak
rm test_new.bak
  
Read( Filename( DirectoriesPackageLibrary( "openmath", "tst" ), "testall.g" ) );

* check that the README files and the manual contain the changes.
* commit the various changes to the CVS repository.

###########################################################################

PREPARING A NEW RELEASE:

* check the functionality

* modify date and version number in PackageInfo.g 
  and in the example of a banner in doc/intro.xml
  
* build the manual and manual test files with 
  
  ReadPackage("openmath/gap/buildman.g");  

* test the PackageInfo.g, and that the documentation is available in GAP:

ValidatePackageInfo( Filename( DirectoriesPackageLibrary( "openmath", "" ), "PackageInfo.g" ) );
?OMPrint

* commit PackageInfo.g and doc/intro.xml

* check file permissions, doing chmod 755 for directories and chmod 644 
  for files when necessary

* edit variables in the "publish" script and then call it to wrap an archive

* update the web-page: modify version and links.

* Send a mail about the new release to the GAP Support to include it in the
  next update of the packages archive

* check that the new version is uploaded on the Gap site.

* advertise the new version


######################################################################

ENCODING AND CONVERSIONS

OpenMath objects can be encoded into various formats, as defined by the
OpenMath standard:
- XML OpenMath
- binary OpenMath

Conversion from OpenMath to Gap:

* 'OMgetObjectXMLTree' converts the OpenMath XML into a tree (using the
function ParseTreeXMLString from package GapDoc) and parses it.

Conversion from Gap to OpenMath:

OMPutObject takes a Gap object and puts into a stream, with XML or binary
encoding.

######################################################################


VALIDATING XML:


The following function can be used to validate the OpenMath XML objects
produced by the package. It requires the program 'xmllint', from
Libxml2, the XML C library for Gnome, available from
http://www.xmlsoft.org/ and included in most modern Linux distributions. 


OMValidate := function ( obj )

    local  file, fromgap_stream, togap_stream, togap, xmllint_exec, openmath2_rng, OMPutObject;

    OMPutObject := function ( stream, x )
          OMIndent := 0;
          OMWriteLine( stream, [ "<OMOBJ xmlns=\"http://www.openmath.org/OpenMath\">" ] );
          OMIndent := OMIndent + 1;
          OMPut( stream, x );
          OMIndent := OMIndent - 1;
          OMWriteLine( stream, [ "</OMOBJ>" ] );
          return;
      end;

    file := Filename( OMDirectoryTemporary, "testfile" );
    fromgap_stream := OutputTextFile( file, false );
    SetPrintFormattingStatus( fromgap_stream, false );
    OMPutObject( fromgap_stream, obj );
    CloseStream( fromgap_stream );

    xmllint_exec := Filename( DirectoriesSystemPrograms(  ), "xmllint" );
    openmath2_rng := Filename( DirectoriesPackageLibrary( "openmath", "tst" ), "openmath2.rng" );

    togap := "";
    togap_stream := OutputTextString( togap, false );
    SetPrintFormattingStatus( togap_stream, false );
    Process( OMDirectoryTemporary, xmllint_exec, InputTextNone(), togap_stream,
     [ "--noout", "--relaxng", openmath2_rng, "testfile" ] );
    CloseStream( togap_stream );

    if togap <> "testfile validates\n" and togap <> "testfile fails to validate\n"  then
        Print( togap );
    fi;

    return togap = "testfile validates\n";
end;


The XML produced by this package can be partially validated with http://validator.w3.org

Just prepend the following line to a file generated by this package,

<?xml version="1.0" encoding="iso-8859-1"?>

and one of the following, for OpenMath version 2.0, 1.1, 1.0 respectively.

<!DOCTYPE OMOBJ SYSTEM "http://www.openmath.org/standard/om20-2004-06-30/openmath2.dtd">
<!DOCTYPE OMOBJ SYSTEM "http://www.openmath.org/standard/om11/omobj.dtd">
<!DOCTYPE OMOBJ SYSTEM "http://www.openmath.org/standard/relaxng/openmath1.dtd">



######################################################################

KNOWN PROBLEMS:
These problems are from the original code by Andrew Solomon.

* A set doesn't store to be a set, hence the method ``OMPut: for a set''
is used only for the empty set. 

IsSet([ 1, true, false ]);
OMPrint([ 1, true, false ]);
OMPrint([  ]);


* Conversion of CharacterTable doesn't work.

OMTest(CharacterTable( AlternatingGroup( [ 1 .. 3 ] ) ));


* Consecutive comments <!-- ... --> or encodings <? ... ?> inside an
input stream are not supported.

stream := InputTextUser(); g := OMGetObject(stream);CloseStream(stream);

<!-- ... -->
<? .

* OMPut: for a Hasse diagram creates OpenMath variables like <OMV name="1"/>
which are invalid OpenMath variables names.

######################################################################

TODO:

* Include experimental, or updated CDs
http://www.openmath.org/cdnames.html

- For converting Gap -> OpenMath, add a method for 'OMPut', in file
gap/omput.gi .

- For converting OpenMath -> Gap, add in 'OMsymTable_new', in file
gap/new.g .

- For converting a nullary symbol OpenMath -> Gap, add code in
'OMnullarySymbolToGAP', in file gap/gap.g . (Remark: OMnullarySymbolToGAP
removed by AK in April 2009, now all is done by OMsymLookup function).

- For a conversion in Yacas, use there OMDef(yacasSymbol, cd, name)


######################################################################

TODO:

* Convert OMsymTable and related stuff from list to record
(Remark: done by AK in April 2009 with renaming to OMsymRecord).

* Remove the difference between nullary and n-ary symbols, and use the
OpenMath roles instead, see the OpenMath Standard, version 2.0, section
"2.1.4 OpenMath Symbol Roles". (Remark: OMnullarySymbolToGAP
removed by AK in April 2009, now all is done by OMsymLookup function).

######################################################################

TODO:

* In function OMgapNativeStatementFunc, of gap/gap.g, is it necessary to
use READ_COMMAND (instead e.g. of Read) ?

Is it necessary to use ViewString ? 

Would it be possible to remove ViewString, or to use StringView from the
GapDoc package, and to remove the file gap/printutil.g? 

The only purpose of gap/printutil.g is to provide ViewString to
OMgapNativeStatementFunc. 

######################################################################

TODO:

Check the functions OMnextToken and OMinstreamNextByte: they do the same.

Some IsHasseDiagram stuff is already defined in main Gap library
lib/relation.gd:

#P  IsHasseDiagram(<rel>)
##
##  returns `true' if the binary relation <rel>  is  a  Hasse  Diagram  of  a
##  partial  order,  i.e.  was  computed   via   `HasseDiagramBinaryRelation'
##  (see~"HasseDiagramBinaryRelation").
##
DeclareProperty("IsHasseDiagram", IsBinaryRelation);

Something from hasse/hasse.g could be removed.

######################################################################

TODO:

* cleanup in the cds directory.
* fill placeholders in OMsymRecord with more symbols where appropriate
* test and move entries from OMsymRecord_new in new.g to gap.g
* implement more private CDs from the SCIEnce project

######################################################################

HISTORICAL NOTES:

Some historical notes from previous releases are collected below.

######################################################################

Readme of the last release containing INRIA library:

                           The OpenMath Package
                           --------------------

The package provides an OpenMath phrasebook for GAP: it allows GAP 
users to import and export mathematical objects encoded in OpenMath, 
for the purpose of exchanging them with other OpenMath-enabled 
applications. 

Copyright:
==========

The OpenMath package is free software; you can redistribute it and/or 
modify it under the terms of the GNU General Public License as published 
by the Free Software Foundation; either version 2 of the License, or 
(at your option) any later version. For details, see the FSF's own site
http://www.gnu.org/licenses/gpl.html.

Additionally, it contains code developed at INRIA (copyright INRIA), 
under the ESPRIT project number 24969 (OpenMath). The user may not use 
the library in commercial products without seeking permission from the 
GAP group ([email protected]) and the CAFE team at INRIA SA 
([email protected]).

Installation:
=============

This package is installed as a normal Gap package: see Gap reference
manual, chapter "74 GAP Packages" (and if you don't have write access to
the Gap installation see also section "9.2 GAP Root Directory"), for
details.

The binaries should be compiled in two stages:
- compilation of the OpenMath C library from INRIA
- compilation of the 'gpipe' program

To do this, change to the package directory gap4r4/pkg/openmath
and perform the following commands:

cd OMCv1.3c/src/
./configure
make
cd ../../
./configure ../../
make


The part in C language compiles and runs also on Windows with Cygwin 
(see http://www.cygwin.com/).
A Windows user may also try to get a precompiled OMC binary from
ftp://ftp-sop.inria.fr/safir/OM (I didn't try), and thereafter

cd pkg/openmath

./configure ../../
make

Some historical notes from previous releases and changelogs
are collected below.

To contact developers, please write to:
alexk at mcs dot st-andrews dot ac dot uk


Alexander Konovalov

April 2009


##############################################################################

       * * * Readme of the first release of the package (2000) * * * 

The compilation is non-standard! See below.

This package has been developed to allow GAP users to
import and export mathematical objects encoded in OpenMath,
for the purpose of exchanging them with other applications that
are OpenMath enabled.


1. Copyright

This package is distributed under GPL license and the terms of the GAP
copyright. Additionally, it contains code developed at INRIA
(copyright INRIA), under the ESPRIT project number 24969 (OpenMath).
The user may not use the library in commercial products without seeking
permission from the GAP group ([email protected]) and the 
CAFE team at  INRIA SA ([email protected]).

It may be redistributed ``as is'' together with this notice.


2. Technicalities and installation

This package includes a C program, and works with full functionality
only if this program has been compiled.

To install this package (after extracting the packages archive
file to the GAP pkg directory):

a) go to the directory `pkg/openmath/OMCv1.3c/src' and call 

/bin/sh ./configure

and then call `make' to compile the INRIA library (producing libOM.a).


b) go to the directory `pkg/openmath' (the
directory containing this README file) and call

/bin/sh ./configure <path>

where <path> is a path to the main GAP root directory (so normally you would
call /bin/sh ./configure ../..).

afterwards call `make' to compile the binary. See file examples for usage examples.

c) you also need to modify the file hasse/config.g
to make the Hasse diagram stuff work.


3. The INRIA library

The files in the directory `openmath/OMCv1.3c' are the OpenMath C library
version 1.3c developed by the CAFE group at INRIA SA. For the latest 
version, contact: [email protected] , or try
ftp://ftp-sop.inria.fr/safir/OM .


Andrew Solomon ([email protected]),
Department of Computer Science,
University of St. Andrews.

9 March 2000.

##############################################################################