From: "Tim Van Holder" <tim DOT van DOT holder AT pandora DOT be>
To: "Eli Zaretskii" <eliz AT is DOT elta DOT co DOT il>
Cc: <djgpp-workers AT delorie DOT com>
Subject: Re: First draft: a64l/l64a
Date: Wed, 30 May 2001 20:48:41 +0200
Message-ID: <CAEGKOHJKAAFPKOCLHDIAEMBCDAA.tim.van.holder@pandora.be>
MIME-Version: 1.0
Content-Type: text/plain;
	charset="iso-8859-1"
Content-Transfer-Encoding: 7bit
X-Priority: 3 (Normal)
X-MSMail-Priority: Normal
X-Mailer: Microsoft Outlook IMO, Build 9.0.2416 (9.0.2910.0)
In-reply-to: <7458-Wed30May2001203047+0300-eliz@is.elta.co.il>
Importance: Normal
X-MimeOLE: Produced By Microsoft MimeOLE V5.50.4133.2400
Reply-To: djgpp-workers AT delorie DOT com
Errors-To: nobody AT delorie DOT com
X-Mailing-List: djgpp-workers AT delorie DOT com
X-Unsubscribes-To: listserv AT delorie DOT com
Precedence: bulk

> > --- nul	Tue May 29 22:09:11 2001
> > +++ radix64.c	Tue May 29 22:04:48 2001
>
> Please use /dev/null; nul won't work on Unix.
Will do.

> Also, please divide the source into two separate files.  There's no
> need to gratuitously bloat user programs with functions they don't
> call.
Well, since a64l is only useful if used on a string produced by l64a,
I thought it was acceptable to put them in a single file.  I'll split
them up.

> > +#ifdef TEST
> > +#include <stdio.h>
> > +
> > +int
> > +main(void)
> > +{
> > +  printf ("a64l(\"/.\")          -> %ld\n", a64l("/."));
> > +  printf ("a64l(\"DJGPP\")       -> %ld\n", a64l("DJGPP"));
>
> This is best put on a separate file in the tests directory (to become
> part of djtstNNN.zip).
Agreed - but this was just a first draft, and having some simple tests
inside the file was more convenient.  I'll of course add files to the
tests dir for the final draft.

> > +The result of @code{a64l()} is undefined if @var{s} is a null
> pointer, or
> > +the string it points to was not generated by a previous call to
> > +@code{l64a()}.
>
> At least in the case of a NULL pointer I think the result is pretty
> much known in advance.  In general, ``result is undefined'' is
> lawyerspeak; in our docs I think we should tell what will happen if we
> know that.
>
> > +This function takes a @code{long} argument and returns a pointer to its
> > +radix-64 representation.  The result is undefined if @var{value} is
> > +negative.
>
> Same here.
Okidoki.

> Finally, I'd suggest to mention base-64 somewhere in the docs, since
> someone might not realize what are you talking about.
I stuck to what the POSIX document called it; it clearly stated this wasn't
the encoding used by either version of the uuencode utility, but didn't say
whether or not it was the base64 method.  And referring to it as a base-64
encoding would be confusing if it wasn't actually the encoding used by
MIME's base64.
I will try to clear the docs a bit for the next draft.