Re: [PATCH] difftime.3: be more explict about "difference".

[Alejandro Colomar <alx@kernel.org>]

[-- Attachment #1: Type: text/plain, Size: 3320 bytes --]

Hi Paul!

On Wed, Nov 08, 2023 at 01:10:12PM -0800, Paul Eggert wrote:
> On 9/25/23 17:18, Alejandro Colomar wrote:
> > Please use semantic newlines.
> Sure, revised patch attached. (A bit delayed since this fell off the end of
> my queue....)

Heh, no problem!

Some small formatting comments below.

> From 07866b20cbacb39146d513f85d43c4c7f97d56e1 Mon Sep 17 00:00:00 2001
> From: Paul Eggert <eggert@cs.ucla.edu>
> Date: Wed, 8 Nov 2023 13:05:57 -0800
> Subject: [PATCH] Improve timestamp documentation
> 
> Improve discussion of leap seconds, year-2038 etc.
> ---
>  man2/clock_getres.2    | 37 ++++++++++++++++++++++++++-----------
>  man2/clock_nanosleep.2 |  2 +-
>  man2/time.2            | 37 +++++++++++++++++--------------------
>  man2/timer_create.2    |  2 +-
>  man3/difftime.3        | 23 +++++++----------------
>  man3type/time_t.3type  |  2 ++
>  6 files changed, 54 insertions(+), 49 deletions(-)
> 

[...]

> diff --git a/man3/difftime.3 b/man3/difftime.3
> index 5504ea8ff..7f129d30d 100644
> --- a/man3/difftime.3
> +++ b/man3/difftime.3
> @@ -26,9 +26,13 @@ The
>  function returns the number of seconds elapsed
>  between time \fItime1\fP and time \fItime0\fP, represented as a
>  .IR double .
> -Each of the times is specified in calendar time, which means its
> -value is a measurement (in seconds) relative to the
> -Epoch, 1970-01-01 00:00:00 +0000 (UTC).
> +Each time is a count of seconds.
> +.P
> +.BI "difftime( time1 ", " time0 )

We use all italics for inline code samples.  See man-pages(7):

     If the command is short, then it can be included  inline  in  the
     text,  in  italic  format, for example, man 7 man‐pages.  In this
     case, it may be worth using nonbreaking spaces (\[ti])  at  suit‐
     able places in the command.  Command options should be written in
     italics (e.g., -l).

     Expressions,  if  not written on a separate indented line, should
     be specified in italics.  Again, the use  of  nonbreaking  spaces
     may be appropriate if the expression is inlined with normal text.

The rest of the patch looks good to me.  Thanks!

Cheers,
Alex

> +acts like
> +.BI ( time1 \- time2 )
> +except that the result does not overflow and is rounded to
> +.BR double .
>  .SH ATTRIBUTES
>  For an explanation of the terms used in this section, see
>  .BR attributes (7).
> @@ -47,19 +51,6 @@ T}	Thread safety	MT-Safe
>  C11, POSIX.1-2008.
>  .SH HISTORY
>  POSIX.1-2001, C89, SVr4, 4.3BSD.
> -.SH NOTES
> -On a POSIX system,
> -.I time_t
> -is an arithmetic type, and one could just
> -define
> -.P
> -.in +4n
> -.EX
> -#define my_difftime(t1,t0) (double)(t1 \- t0)
> -.EE
> -.in
> -.P
> -when the possible overflow in the subtraction is not a concern.
>  .SH SEE ALSO
>  .BR date (1),
>  .BR gettimeofday (2),
> diff --git a/man3type/time_t.3type b/man3type/time_t.3type
> index fb788b823..0dba4afb0 100644
> --- a/man3type/time_t.3type
> +++ b/man3type/time_t.3type
> @@ -81,6 +81,8 @@ the width of
>  .I time_t
>  can be controlled with the feature test macro
>  .BR _TIME_BITS .
> +See
> +.BR feature_test_macros (7).
>  .P
>  The following headers also provide
>  .IR time_t :
> -- 
> 2.41.0
> 


-- 
<https://www.alejandro-colomar.es/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]