Some documentation suggestions

[Kent Boortz]

In GMP 4.1 the functions mpz_import() and mpz_export() was introduced,
just what I needed to convert to and from our own bignum format to the
GMP format! Below some suggestions for additions to the manual.

  1.  It is really nice with a special chapter about how to use
      autoconf and gmp! Saved me lots of time. But how can I find
      out what version of GMP it is, preferable without using
      the C compiler (AC_TRY_RUN)? I have seen code like

        AC_MSG_CHECKING(for gmp import export we need GMP 4.1)
        AC_TRY_RUN([
        #include <stdio.h>
        #include <gmp.h>

        int main()
        {
          int major = __GNU_MP_VERSION;
          int minor = __GNU_MP_VERSION_MINOR;
          if(major > 4 or (major == 4 and minor >= 1)) exit(0);
          else exit(1);
        }
        ],
           AC_MSG_RESULT(ok),
           AC_MSG_RESULT(no)
        )

      But maybe finding out the version of GMP is the wrong way to
      find out if I have mpz_import/export? I can use
      AC_CHECK_LIB(gmp, __gmpz_export) as suggested in the manual but
      can I trust that there where no experimental version of
      mpz_import/mpz_export in earlier versions of GMP that where
      broken or used different arguments?

  2.  It is not documented in what version of GMP a new function was
      introduced (except the source ChangeLog). Probably best
      documented together with the function. Or it could be a separate
      section "Changes", more like an API ChangeLog. Without this
      knowledge it is hard to write configure tests.

  3.  Calculating the size needed for the output buffer for
      mpz_export() is a bit "low level". I would have preferred that
      passing NULL as the buffer pointer made the function return the
      size without doing the conversion but a NULL pointer is already
      used to enable (in my opinion less useful) automatic
      allocation. For this reason I suggest a new function
      mpz_export_size() for the size calculation. But if you don't
      think the calculation example in the manual will break in future
      releases I guess this is not really enough reason to introduce a
      new function.

  4.  Maybe how to handle the sign with mpz_import/export could
      be clearified. I assume I use mpz_neg() after importing
      to set the sign and read the sign using mpz_sgn() when 
      exporting.  

A separate issue that shouldn't be documented in the GMP manual but
has to do with the fact that I don't know autoconf that well yet ;-)
If I understand autoconf correctly the only "standard location"
configure searches is "/usr", not "/usr/local" where GMP is located on
many systems. I ended up with the a bit messy code included below. If
you have a suggestion how to write this "the right way" or in a
cleaner way I will be very thankful,

kent


AC_ARG_WITH(gmp,
[  --with-gmp=PATH         specify location of GNU MP include and lib
  --with-gmp              use GNU MP (default if found)
  --without-gmp           don't use GNU MP])

if test "x$with_gmp" = "xno"; then
    AC_MSG_NOTICE([GNU MP support was explicitly disabled])
elif test "x$with_gmp" = "xyes" -o "x$with_gmp" = "x" ;then
    for dir in /usr/pkg /usr/local /opt/local /sw /usr /opt; do
        AC_CHECK_HEADER($dir/include/gmp.h, ac_cv_gmp=yes, ac_cv_gmp=no)
        if test $ac_cv_gmp = yes ; then
            AC_MSG_RESULT(yes)
            CFLAGS="$CFLAGS -I$dir/include -L$dir/lib"
            AC_DEFINE(HAVE_GMP_H)
            break
        fi
        AC_MSG_RESULT(no)
    done
    if test $ac_cv_gmp = no ; then
        AC_MSG_WARN([No GNU MP installation found, encode/decode_bignum() \
will not be defined])
    fi
else
    # Option given with PATH to package
    AC_MSG_CHECKING(for GNU MP)
    if test ! -d "$with_gmp" ; then
        AC_MSG_ERROR(Invalid path to option --with-gmp=PATH)
    fi
    AC_MSG_RESULT(yes)
    CFLAGS="$CFLAGS -I$with_gmp/include -L$with_gmp/lib"
    AC_DEFINE(HAVE_GMP_H)
fi

# We don't just want any GNU MP version, we want 4.1 or later
# that contain the import/export functions we need.
AC_CHECK_LIB(gmp, __gmpz_export)