[gmpy-commits] CVS: gmpy/doc gmpydoc.txt,1.4,1.5 index.html,1.5,1.6

SourceForge Headquarters 225 Broadway Suite 1600 San Diego, CA 92101 +1 (858) 422-6466

Update of /cvsroot/gmpy/gmpy/doc
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv19507/doc

Modified Files:
	gmpydoc.txt index.html 
Log Message:

Part-edited docs (TODO: finish editing gmpydoc.txt)

Index: gmpydoc.txt
===================================================================
RCS file: /cvsroot/gmpy/gmpy/doc/gmpydoc.txt,v
retrieving revision 1.4
retrieving revision 1.5
diff -C2 -d -r1.4 -r1.5
*** gmpydoc.txt	8 Aug 2003 09:15:57 -0000	1.4
--- gmpydoc.txt	12 Nov 2005 00:04:45 -0000	1.5
***************
*** 1,4 ****
! gmpy module -- a complete Python 2 interface for GMP 3.1
! (including a Win32/MSVC++ build).

--- 1,4 ----
! gmpy module -- a complete Python 2.{2,3,4} interface for GMP 4
! (including Win32/MSVC++ binary builds).

***************
*** 38,41 ****
--- 38,43 ----
  Minor editing for version 1.0 (2003/08/08).

+ Minor editing for version 1.01 (2005/11/12).
+ 

  *Acknowledgments*
***************
*** 45,49 ****
  removed feature: conditional possibility to substitute
  this implementation in place of Python's built-in longs;
! Lots and lots of added features).

  Special thanks are due to Pearu Peterson for his MANY
--- 47,51 ----
  removed feature: conditional possibility to substitute
  this implementation in place of Python's built-in longs;
! lots and lots of added features).

  Special thanks are due to Pearu Peterson for his MANY
***************
*** 57,98 ****
  *Installation and testing*

! Pre-requisites: Python 2.3, GMP 4.0.1 (see later for Win32).
! GMP 3.1.1 is still supported for the moment (but will
! be phased out soon) -- testing and bugfixes only for
! bugs reproducible in GMP 4 (no more workarounds for
! GMP 3 - only bugs).  Not yet any GMP 4 only functionality.
! No known use of Python 2.3-only functionality yet, but
! no support/bugfixes planned for older Python releases.

  To build gmpy from sources, unpack the sources zipfile
! (gmpy-sources-10.zip, for example, for release 1.0)
! into a new, dedicated directory; cd to that directory
! (from any shell on Unix/Linux, from a 'Dos box' aka
! 'command box' on Windows, etc), and run the command:
      python setup.py install
! the DistUtils that come with Python 2 take over and
! build and install the gmpy module for you.
! 
! On Unix, GMP 4.0.1 must have been previously and separately
! installed; on Win32, the gmp.lib and gmp.h supplied (in the
! gmpy-win32 package, only; file gmpy-win32-library-06.zip,
! please unzip it in the same directory as the sources) can
! be used (the linker will give two warnings, but they are
! innocuous ones -- please ignore them).  GMP 3.1.1 for MSVC++
! 6 is found at: ftp://ftp.whiterose.net/pub/lundman -- but
! you don't need to download that to build and use gmpy.

! GMP 4 for Windows has not been checked out yet.  Take care
! when installing GMP 4 that an older GMP 3 doesn't keep
! being used, e.g. on Linux if you have a system-installed
! GMP 3 in /usr/lib and install the newer GMP 4 by default
! (it goes into /usr/local/lib, and depending on various
! details of your system configuration the /usr/lib version
! may keep being used instead).

  Distutils are not yet supported for the pre-built gmpy.pyd
! for windows, that comes in the gmpy-win32-binary-10.zip
  file -- just move the gmpy.pyd it contains to c:\Python23
  (or wherever you have your Python 2.3 installation).

  The sources zipfile also contains this file (gmpydoc.txt),
--- 59,92 ----
  *Installation and testing*

! Pre-requisites: Python 2.2 or better, and GMP 4.0.1 or better (see
! later for Win32).  GMP 3.* is not being tested any more.  Not yet
! any GMP 4 only functionality.  No support nor bugfixes planned for
! older releases of either Python or GMP.

  To build gmpy from sources, unpack the sources zipfile
! (gmpy-sources-101.zip, for example, for release 1.01) into a new,
! dedicated directory; cd to that directory (from any shell on
! Unix/Linux, from a 'Dos box' aka 'command box' on Windows, from
! Terminal on Mac OS X, etc), and run the command:
      python setup.py install
! the DistUtils that come with Python take over and build and
! install the gmpy module for you (you may need to use 'sudo' or
! 'su' appropriately to actually perform the isntallation, depending
! on the permissions you're using on Python's site-packages).

! On Unix, GMP 4.0.1 or better must have been previously and
! separately installed; for Win32, see
! http://www.cs.nyu.edu/exact/core/gmp/ .  Take care when installing
! GMP 4 that an older GMP 3 doesn't keep being used instead, e.g. on
! Linux if you have a system-installed GMP 3 in /usr/lib and install
! the newer GMP 4 using GMP's default settings (it then goes into
! /usr/local/lib, and depending on various details of your system
! configuration the /usr/lib version may keep being used instead).

  Distutils are not yet supported for the pre-built gmpy.pyd
! for windows, that comes in the gmpy-win32-binary-101.zip
  file -- just move the gmpy.pyd it contains to c:\Python23
  (or wherever you have your Python 2.3 installation).
+ [[TODO: clarify binary issue and release ones here!!!]]

  The sources zipfile also contains this file (gmpydoc.txt),
***************
*** 110,133 ****
  where you unpacked the sources, run at the command prompt:

          python gmpy_test.py

  Expected output is something like (details may differ!):
  """
! Unit tests for gmpy 1,0 alpha
!     on Python 2.3+ (#1, Aug  5 2003, 17:15:06)
! [GCC 3.2.2 (Mandrake Linux 9.1 3.2.2-3mdk)]
! Testing gmpy 1.0 (GMP 4.0.1), default caching (20, 20, -2..11)
  gmpy_test_cvr 262 tests, 0 failures
  gmpy_test_rnd  26 tests, 0 failures
! gmpy_test_mpf 140 tests, 0 failures
! gmpy_test_mpq 242 tests, 0 failures
! gmpy_test_mpz 310 tests, 0 failures
! 5 items had no tests:
      gmpy_test_cvr._test
      [[ snip snip ]]
! 25 items passed all tests:
      [[ snip snip ]]
! 980 tests in 30 items.
! 980 passed and 0 failed.
  Test passed.
  """
--- 104,133 ----
  where you unpacked the sources, run at the command prompt:

+         ct test
+ 
+ and then, at the next prompt:
+ 
          python gmpy_test.py

+ 
  Expected output is something like (details may differ!):
+ 
  """
! Unit tests for gmpy 1.01 release candidate
!     on Python 2.4.1 (#1, Apr 21 2005, 11:14:17)
! [GCC 3.2.2 20030222 (Red Hat Linux 3.2.2-5)]
! Testing gmpy 1.01 (GMP 4.1.2), default caching (20, 20, -2..11)
  gmpy_test_cvr 262 tests, 0 failures
  gmpy_test_rnd  26 tests, 0 failures
! gmpy_test_mpf 154 tests, 0 failures
! gmpy_test_mpq 260 tests, 0 failures
! gmpy_test_mpz 370 tests, 0 failures
! 6 items had no tests:
      gmpy_test_cvr._test
      [[ snip snip ]]
! 28 items passed all tests:
      [[ snip snip ]]
! 1072 tests in 34 items.
! 1072 passed and 0 failed.
  Test passed.
  """
***************
*** 142,156 ****

  *PLEASE* report any failures to gmpy's maintainers, with
! any details you can supply on your machine, on your OS, and
! on your installation of GMP 4, gmpy 1.0, Python 2.3, and any
! other relevant issue (your C/C++ compiler & libraries, &c).
! *THANKS* in advance -- bug reporting and feedback is your
  key contribution to the gmpy project!  (Reports of any
  _successful_ installations will also be welcome, if it's
  accompanied by enough details -- again, THANKS in advance!).

  *General notes on gmpy*

  gmpy exposes to Python three types of numbers that are
  implemented in both GMP 3 and GMP 4:
--- 142,161 ----

  *PLEASE* report any failures to gmpy's maintainers, with
! all details you can supply on your machine, on your OS, and
! on your installation of GMP 4, gmpy 1.01, Python 2.3 or 2.4,
! and any other relevant issue (your C/C++ compiler & libraries,
! &c).  *THANKS* in advance -- bug reporting and feedback is your
  key contribution to the gmpy project!  (Reports of any
  _successful_ installations will also be welcome, if it's
  accompanied by enough details -- again, THANKS in advance!).
+ The best way to report bugs (including unit-test failures) is via
+ https://sourceforge.net/tracker/?group_id=13335&atid=113335 , the
+ Sourceforce bug tracker.

  *General notes on gmpy*

+ TODO: update from here
+ 
  gmpy exposes to Python three types of numbers that are
  implemented in both GMP 3 and GMP 4:

Index: index.html
===================================================================
RCS file: /cvsroot/gmpy/gmpy/doc/index.html,v
retrieving revision 1.5
retrieving revision 1.6
diff -C2 -d -r1.5 -r1.6
*** index.html	8 Aug 2003 09:48:57 -0000	1.5
--- index.html	12 Nov 2005 00:04:45 -0000	1.6
***************
*** 14,19 ****
  <BODY>
  <FONT SIZE=-1>
! Last updated on: 2003, Aug 8;
! for GMPY release: 1.0 alpha
  <A href="http://sourceforge.net">
  <IMG src="http://sourceforge.net/sflogo.php?group_id=13335&type=1"
--- 14,19 ----
  <BODY>
  <FONT SIZE=-1>
! Last updated on: 2005, Nov 12;
! for GMPY release: 1.01 beta
  <A href="http://sourceforge.net">
  <IMG src="http://sourceforge.net/sflogo.php?group_id=13335&type=1"
***************
*** 47,52 ****
  The first GMPY goal is to develop this module into a complete
  exposure of MPZ, MPF (floating-point), and MPQ (rational)
! functionality of current GMP (release 4.0), that will fully
! support current Python (release 2.3) and its handy 'distutils'
  (and also support a "C API" allowing some level of interoperation
  with other C-written extension modules for Python).
--- 47,52 ----
  The first GMPY goal is to develop this module into a complete
  exposure of MPZ, MPF (floating-point), and MPQ (rational)
! functionality of current GMP (release 4), that will fully
! support current Python releases (2.2, 2.3, 2.4) and the 'distutils'
  (and also support a "C API" allowing some level of interoperation
  with other C-written extension modules for Python).
***************
*** 90,95 ****

  <H1>Project Status and near-future plans</H1>
! The gmpy module's alpha release (latest current release
! as of 2002/08/08: 1.0) is available for download in both
  source and Windows-binary form.  It exposes all of the mpz, mpq
  and mpf functionality that was already available in GMP 3.1, and 
--- 90,95 ----

  <H1>Project Status and near-future plans</H1>
! The gmpy module's beta release (latest current release
! as of 2005/11/12: 1.01) is available for download in both
  source and Windows-binary form.  It exposes all of the mpz, mpq
  and mpf functionality that was already available in GMP 3.1, and 
***************
*** 112,132 ****
  <p>
  We started the GMPY project using a VC++ port of GMP.LIB "just found on
! the net", but have currently switched to the port by Jorgen Lundman
! found at <a href="ftp://ftp.whiterose.net/pub/lundman/">
!     ftp://ftp.whiterose.net/pub/lundman/</a> (bravo Lundy!). Windows
! users do not need to download from Jorgen's site: a separate 'binary
! library' package, including Lundy's ports of GMP.LIB and GMP.H, is made
! available on the gmpy project's ftp-space for Windows/VC++6 users that
! do want to re-build the gmpy module from sources; and also, another
! separate 'binary module' package is supplied, containing only the
! pre-built GMPY.PYD, for those who do <b>not</b> want to re-build from
! sources.  For GMP 4.0, the plan is to use the native support it offers
! for the Windows platform, but this has not yet been explored in
! detail.
  <p>
  <b>Do</b> note, however, that <b>all</b> gmpy users should download the
  gmpy source-package as well, as currently that is the one including
  <b>gmpy</b> documentation and unit-tests!
- 
  <H2>Currently-open issues</h2>
  <p>
--- 112,128 ----
  <p>
  We started the GMPY project using a VC++ port of GMP.LIB "just found on
! the net", and later a port by Jorgen Lundman, but are currently relying
! on other volunteers to build Windows binaries since we don't have any
! Windows machine any more.  <a
! href="http://www.cs.nyu.edu/exact/core/gmp/">This site</a> does appear
! to offer all needed files and instructions for Windows developers who
! want to re-build the gmpy module from sources; the gmpy project itself
! just supplies a separate 'binary module' package is supplied, containing
! only the pre-built GMPY.PYD, for those who do <b>not</b> want to
! re-build from sources.
  <p>
  <b>Do</b> note, however, that <b>all</b> gmpy users should download the
  gmpy source-package as well, as currently that is the one including
  <b>gmpy</b> documentation and unit-tests!
  <H2>Currently-open issues</h2>
  <p>
***************
*** 151,156 ****
  Unit tests are not considered a weak point any more; the over 1000
  unit-tests now being run provide a decent cover of 93+% SLOC for gmpy.c,
! up from 72% in 0.7.  The non-covered SLOCs (about 170 of gmpy.c's
! current 2600) are mostly disaster-tests to handle out-of-memory
  situations, code providing optional debugging output (for debugging the
  gmpy module -- see the set_debug facility), a smattering of 'defensive
--- 147,152 ----
  Unit tests are not considered a weak point any more; the over 1000
  unit-tests now being run provide a decent cover of 93+% SLOC for gmpy.c,
! up from 72% in 0.7.  The non-covered SLOCs (about 370 of gmpy.c's
! current 5820) are mostly disaster-tests to handle out-of-memory
  situations, code providing optional debugging output (for debugging the
  gmpy module -- see the set_debug facility), a smattering of 'defensive
***************
*** 159,168 ****
  (mostly provided for the specific use of PySymbolic, and intended to be
  tested by that package).  We'll have to do better, eventually, but, for
! now, this can be considered OK for an alpha-release.
  <p>
  In the attempt to make gmpy as useful as can be for both stand-alone
  use, and also in the context of PySymbolic, a tad too many design
  decisions have been delayed/postponed by introducing module-level
! flags, letting us 'have it both ways' in the current alpha 
  gmpy; this has produced a somewhat unwieldy mix of module-level
  flag-setting and call-back functions.  This whole area's architecture
--- 155,164 ----
  (mostly provided for the specific use of PySymbolic, and intended to be
  tested by that package).  We'll have to do better, eventually, but, for
! now, this can be considered OK for a beta-release.
  <p>
  In the attempt to make gmpy as useful as can be for both stand-alone
  use, and also in the context of PySymbolic, a tad too many design
  decisions have been delayed/postponed by introducing module-level
! flags, letting us 'have it both ways' in the current beta
  gmpy; this has produced a somewhat unwieldy mix of module-level
  flag-setting and call-back functions.  This whole area's architecture
***************
*** 176,183 ****
  proven unnecessary.  All relevant GMP 4 functionality will be exposed.
  <p>
! No predictions on timing, though.  gmpy 1.0 meets all current needs
  of the main author, so his motivation to work more on it is low:-).
  So, don't hold your breath (pitching in and helping it happen, on the
! other hand, _might_ be advisable:-).
  <p>
  <A HREF="http://sourceforge.net/projects/gmpy/">Project
--- 172,179 ----
  proven unnecessary.  All relevant GMP 4 functionality will be exposed.
  <p>
! No predictions on timing, though.  gmpy 1.01 meets all current needs
  of the main author, so his motivation to work more on it is low:-).
  So, don't hold your breath (pitching in and helping it happen, on the
! other hand, _might_ be advisable, and will surely yield results:-).
  <p>
  <A HREF="http://sourceforge.net/projects/gmpy/">Project