X-Authentication-Warning: delorie.com: mail set sender to djgpp-workers-bounces using -f
Date: Fri, 07 Jan 2005 00:08:22 +0200
From: "Eli Zaretskii" <eliz AT gnu DOT org>
Sender: halo1 AT zahav DOT net DOT il
To: djgpp-workers AT delorie DOT com
Message-ID: <01c4f43c$Blat.v2.2.2$620c39c0@zahav.net.il>
Content-Transfer-Encoding: 7BIT
Content-Type: text/plain; charset=ISO-8859-1
X-Mailer: emacs 21.3.50 (via feedmail 8 I) and Blat ver 2.2.2
In-reply-to: <bcppt01o8hrjnj92qu6rbdq91s74aauird@4ax.com> (message from Brian
	Inglis on Thu, 06 Jan 2005 00:16:24 -0700)
Subject: Re: *time_r patch
References:  <bcppt01o8hrjnj92qu6rbdq91s74aauird AT 4ax DOT com>
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

> Date: Thu, 06 Jan 2005 00:16:24 -0700
> From: Brian Inglis <Brian DOT Inglis AT SystematicSw DOT ab DOT ca>
> 
> Here's a patch to src/libc/ansi/ctime.c, src/libc/ansi/ctime.txh,
> and include/libc/stubs.h to add POSIX thread safe functions
> asctime_r(), ctime_r(), gmtime_r(), and localtime_r(). 

Thanks.

> +++ src/libc/ansi/time/ctime.txh	6 Jan 2005 07:00:19 -0000
> @@ -13,6 +13,7 @@ char *ctime(const time_t *cal);
>  This function returns an ASCII representation of the time in @var{cal}. 
>  This is equivalent to @code{asctime(localtime(cal))}.  @xref{asctime}.
>  @xref{localtime}.
> +@xref{ctime_r}.

Why did you add this 3rd cross-reference?  The other two are there
because ctime is explained in terms of calling those two functions;
by contrast, ctime_r is not mentioned anywhere in the text.

If you wanted a ``see-also'' type of reference, that is okay, but
please add some text that would explain why you think it is useful for
the reader to look there.  In other words, give the readers enough
information to decide whether they want to read about the referenced
function.

> +This is equivalent to @code{asctime_r(localtime_r(cal,&tm), buf)},
> +where @var{tm} is automatically/dynamically allocated.

This text is confusing wrt the "&tm" part.  I suggest to reword like
this:

  This is equivalent to @code{asctime_r(localtime_r(cal,&tm), buf)},
  where @var{tm} is a variable of the type @code{struct tm}.

> +@xref{asctime_r}.
> +@xref{localtime_r}.
> +@xref{ctime}.

See above about the 3rd xref.

> +This function returns an ASCII representation,
> +as generated by @ref{asctime},
> +of the broken down calendar time from @var{tptr},

I'd advise against such ``clever'' uses of @ref (they look awkard in
Info and simply wrong in the printed copy of the manual).  Instead,
say something like

  This function returns an ASCII representation of the broken down
  calendar time from @var{tptr}, which is identical to the one
  generated by @code{asctime} (@pxref{asctime}),

> +See @ref{gmtime}, for the description of @code{struct tm}.

"See @ref" is exactly equivalent to "@xref", so please use the latter
here.  (Yes, I know that "See @ref" is used elsewhere in the manual;
feel free to fix those other places as well, if you have time and
energy.)

Thanks again for working on this.