Development notes file, by Marco Costantini

This file contains notes for development and for releasing a new
version, it is not useful for the user.

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

MAKING A CHANGE:

* test the package functionality:

ReadTest( Filename( DirectoriesPackageLibrary( "openmath", "tst" ), "test_new" ) );

* update the local gap dev version:
cd /usr/local/gap_dev/4.0/
make 
cd
gap_dev -N
CreateCompletionFiles();

* test the package functionality:

ReadTest( Filename( DirectoriesPackageLibrary( "openmath", "tst" ), "test_new" ) );

* do the changes.

* if a new file is added, lines like
Revision.("openmath/dev_notes.txt") :=
    "@(#)$Id: dev_notes.txt,v 1.19 2006/03/02 21:24:33 gap Exp $";

* 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_dev < test_new.src
nano +30000 test_new
diff test_new test_new.bak
rm test_new.bak
gap_dev
ReadTest( Filename( DirectoriesPackageLibrary( "openmath", "tst" ), "test_new" ) );

* check that the README files and the manual contain the changes.

* test that the manual still compiles, and that the content is OK:

cd /usr/local/gap_dev/4.0/pkg/openmath/doc
./make_doc
xpdf manual.pdf &

* commit the various changes to the CVS repository.



PREPARING A NEW RELEASE:

* modify date and version number in file PackageInfo.g 
and version number in file doc/manual.tex

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

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

* commit PackageInfo.g and doc/manual.tex

* remove the various *.bak, *~ and files from compilation, otherwise get
a fresh copy from CVS repository.

* do chmod -x:
cd /usr/local/gap_dev/4.0/pkg/openmath
chmod -x tst/test5.omt

* compile the documentation:

cd doc
./make_doc
cd ..

* remove CVS subdirectories:
rm -r CVS/ */CVS/ */*/CVS/

* prepare the archive, with the right version number:
cd ..
tar cfvz openmath-06.01.03.tar.gz openmath/

* note the archive size:
ls -l openmath-*.tar.gz

* copy archive, PackageInfo.g, README to web page:
scp openmath-*.tar.gz openmath/PackageInfo.g openmath/README gate.science.unitn.it:

scp openmath-*.tar.gz PackageInfo.g README  degiorgi:public_html/gap_code/openmath/
rm openmath-*.tar.gz PackageInfo.g README

* check the PackageInfo.g online:

konqueror http://www.gap-system.org/Packages/Authors/authors.html &
http://www-math.science.unitn.it/~costanti/gap_code/openmath/PackageInfo.g

* update the web-page: modify version, link and size:
pico public_html/index.html

* get a fresh copy of CVS repository, with CVS directories.

* recompile, reconfigure, etc... :

cd openmath

cd doc
./make_doc
cd ..

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

chmod -x tst/test5.omt

* test again:

?OMTest
ReadTest( Filename( DirectoriesPackageLibrary( "openmath", "tst" ), "test_new" ) );

* Send a mail about the new release, now the person that takes care of
this is Bjoern Assmann:

to:
Bjoern Assmann <bjoern@mcs.st-andrews.ac.uk>

subject:
package openmath, new version

Dear Bjoern,
a new version of the package openmath is ready; 
the PackageInfo.g file is at
http://www-math.science.unitn.it/~costanti/gap_code/openmath/PackageInfo.g
(the same as before).
Would you please include in the Gap site?
Best wishes,
Marco

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

* advertise the new version



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

ENCODING:

OpenMath objects can be encoded into various formats:

XML	(as defined by OpenMath standard)
binary	(as defined by OpenMath standard)
gpipe	(defined as the output of the program 'gpipe', included in the package)


Conversion from OpenMath to Gap:

* 'OMgetObjectByteStream' takes a stream in gpipe encoding and returns a Gap object.
* 'gpipe' takes a file in XML or binary encoding, autodetects, and produces a gpipe encoded file.
* 'OMGetObject' takes a stream in XML or binary encoding, pipes it to 'gpipe', and calls 
'OMgetObjectByteStream'.

Conversion from Gap to OpenMath:

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

This package includes the external program 'tpipe' (OMCv1.3c/src/tpipe) that converts an OpenMath
object with unknown/binary/XML encoding to binary or XML encoding, , and 'gpipe' (bin/*/gpipe), that
converts an OpenMath object with unknown/binary/XML encoding to gpipe.


What OMGetObject, old version, does:

 OMGetObject:        stream ------------------------> r
                         gpipe: fromgap -> togap
                                  =          =
 PipeOpenMathObject: stream -> outstream
                   OMgetObjectByteStream: instream -> r
encoding           XML/binary, XML/binary,   gpipe,   GAP



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


VALIDATING XML:

The xml produced by this package can be 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://openmath.activemath.org/standard/om20-2004-06-30/openmath2.dtd">
<!DOCTYPE OMOBJ SYSTEM "http://openmath.activemath.org/standard/om11/omobj.dtd">
<!DOCTYPE OMOBJ SYSTEM "http://openmath.activemath.org/standard/relaxng/openmath1.dtd">



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


USING WITH GAP 4.3:

A partial workaround like this can be used

OMPath := "/usr/local/gap_dev/4.0/pkg/openmath";

ReadPackage := function ( nn, file )
    Read( Concatenation( OMPath, file ) );
    return;
end;

Read( Concatenation( OMPath, "/", "init.g" ) );
Read( Concatenation( OMPath, "/", "read.g" ) );



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

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. However, for an empty set, it could
return [ cd = "set1", name = "emptyset" ] instead.

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);

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


* Conversion from OpenMath to Gap of a string containing '+' doesn't work.

OMTest("+");


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

TODO:


* Include experimental, or updated CDs
http://www.openmath.org/cocoon/openmath/cdfiles2/cdnamess.html

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

- 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 .

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


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

TODO:


* Check the file permissions: in some case -rw-rw-r-- should be replaced
with -rw-r--r-- .


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

TODO:


* Switch to the XML stuff from package GapDoc. (It may be useful at most
one from this and the next).


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

TODO:

* switch to compile with -Wall -O2 (after removing the warning).


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

TODO:

* update OMCv1.3c library

---> The library is available from:
ftp://ftp-sop.inria.fr/safir/OM

The package contains the OMCv1.3c library, it could be updated to
OMCv1.4a. It is available also at
http://www.openmath.org/cocoon/openmath/software/OMCv1.4a.tgz

There is file with a wrong name: this is fixed with (compare also with
OMCv1.3c):

cd OMCv1.4a/src
mv test1.omx test1.omt


After compiling, I get 

--- doing some auto-tests for OpenMath lib libOM.a ...

auto testing general IO...
ok: test pipe1
ok: test pipe2
failed: test pipe3 (please check file BUGREP)

auto testing automatic encoding detection...
failed: test binary encoding auto detect (please check file BUGREP)
ok: test XML encoding auto detect

Hence it is not clear to me whether it works correctly or not.


Mail about this.

OpenMath INRIA C library

Da: 
Marco Costantini <costanti@science.unitn.it>

A: 
olivier.arsac@sophia.inria.fr, stephane.dalmas@sophia.inria.fr

Data: 
19:09, 20/12/2005

Dear Olivier Arsac and Stéphane Dalmas,
I have downloaded the file "OpenMath INRIA C library" 
http://www.openmath.org/cocoon/openmath/software/OMCv1.4a.tgz

Is there a newer version, or is the latest version available at 
http://www.openmath.org/cocoon/openmath/software/ ?

In src directory there is a file test1.omx , but the test in Makefile requires 
test1.omt .


However, the test fails: I get (on a Linux 2.4.21-0.13mdk i686 machine)

--- doing some auto-tests for OpenMath lib libOM.a ...

auto testing general IO...
ok: test pipe1
ok: test pipe2
failed: test pipe3 (please check file BUGREP)

auto testing automatic encoding detection...
failed: test binary encoding auto detect (please check file BUGREP)
ok: test XML encoding auto detect

auto testing encodings...
ok: test enc string XML
ok: test enc string binary
ok: test enc wide char string XML
ok: test enc wide char string binary
ok: test enc array XML
ok: test enc array binary
ok: test enc double XML
ok: test enc double binary

--- auto-tests done.

What can I do to solve/further investigate  this problem? I cannot find any 
"file BUGREP".

Best regards,
Marco Costantini



Re: OpenMath INRIA C library

Da: 
Stephane Dalmas <Stephane.Dalmas@sophia.inria.fr>

A: 
costanti@science.unitn.it

Data: 
venerdì 15:14:00

> Dear Olivier Arsac and Stéphane Dalmas,
>   
Dear Marco (Olivier is no longer here, he works for a company now),
> I have downloaded the file "OpenMath INRIA C library" 
> http://www.openmath.org/cocoon/openmath/software/OMCv1.4a.tgz
>
> Is there a newer version, or is the latest version available at 
> http://www.openmath.org/cocoon/openmath/software/ ?
>   
I'm afraid it is the latest version...  It dates back from a time when 
there was no readily available XML library.
> In src directory there is a file test1.omx , but the test in Makefile requires 
> test1.omt .
>   
It's attached at the end of this message.
>
> However, the test fails: I get (on a Linux 2.4.21-0.13mdk i686 machine)
>
>   
I checked here and it works right (on a Fedora Core 3 Linux 
distribution, first time I tried to compile the library in 3 years...). 
Maybe it is because "test1.omt" is missing ?
> What can I do to solve/further investigate  this problem? I cannot find any 
> "file BUGREP".
>   
The file says that there is no know bug ! and that you should mail us if 
you find one.

I'm no more working on that and thus won't be able to help you a lot...

Best regards,
   
    Stéphane.




The home-page of Olivier Arsac is now

http://www-sop.inria.fr/cafe/Olivier.Arsac/


