Some documentation suggestions

[Kevin Ryde]

Kent Boortz <kent@erix.ericsson.se> writes:
>
>       But how can I find
>       out what version of GMP it is, preferable without using
>       the C compiler (AC_TRY_RUN)?

AC_EGREP_CPP is cross-compile friendly.  I was going to put an example
of it, but thought it better to recommend testing the symbols one
wants, rather than parsing up a version number.

>         AC_TRY_RUN([
>         #include <stdio.h>
>         #include <gmp.h>

Bad when cross compiling, alas.

>       I can use
>       AC_CHECK_LIB(gmp, __gmpz_export) as suggested in the manual

Yep, that's the best way.

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

Can't say anything about experimental versions.  Anyone getting one of
those has to keep it to themselves.  But no released version used
mpz_import or export for anything other than what they now are.

>   2.  It is not documented in what version of GMP a new function was
>       introduced (except the source ChangeLog).

The NEWS file lists them.

>       Probably best documented together with the function.

Perhaps.  Personally I'd encourage packages to simply demand a new
enough gmp from anyone who has trouble.

>       I would have preferred that
>       passing NULL as the buffer pointer made the function return the
>       size without doing the conversion

With hindsight that might have been better.  It's sort of what C99
snprintf does.

>       For this reason I suggest a new function
>       mpz_export_size() for the size calculation.

I think we discussed that, but decided against it.  I forget exactly
why.  It wouldn't do much more than the little calculation shown.

>       But if you don't
>       think the calculation example in the manual will break in future
>       releases

That code fragment is based purely on what's already documented for
mpz_export and mpz_sizeinbase, so it should be as good as any of our
promises about compatibility.  :-)

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

Yes.  And thanks, I'll try to clarify that.

> If I understand autoconf correctly the only "standard location"
> configure searches is "/usr", not "/usr/local" where GMP is located on
> many systems.

I think the theory is that the user adds stuff to "LIBS" or "LDFLAGS",
and possibly "CPPFLAGS".  The basic autoconf instructions
(INSTALL.autoconf) don't really give much guidance on that
unfortunately.

> AC_ARG_WITH(gmp,
> [  --with-gmp=PATH         specify location of GNU MP include and lib

Rumour has it that taking a path like that is an abuse of "--with"
(see the gnu coding standars), but when you have to do something like
that then it does seem fairly natural.

Incidentally if gmp is optional a nice default might be
--with-gmp=detect, to use it if it's found.  I did that for
--with-readline for the demo programs in gmp.