[PATCH 1/2] system_data_types.7: srcfix

[PATCH 1/2] system_data_types.7: srcfix

[Alejandro Colomar]

Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
---
 man7/system_data_types.7 | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
index 43e88942a..caca5bb3c 100644
--- a/man7/system_data_types.7
+++ b/man7/system_data_types.7
@@ -454,7 +454,7 @@ Used for a count of elements, and array indices.
 It is the result of subtracting two pointers.
 According to the C language standard, it shall be a signed integer type
 capable of storing values in the range
-.BR "" [ PTRDIFF_MIN ,
+.RB [ PTRDIFF_MIN ,
 .BR PTRDIFF_MAX ].
 .IP
 The length modifier for
-- 
2.28.0

[PATCH 2/2] system_data_types.7: srcfix

[Alejandro Colomar]

The contents of each type are a logic block that is indented as a block.
They are not separate paragraphs that happen to be indented separately,
but a set of continuous paragraphs, all in the same level,
indented as a block from the list entry--the name of the type--.
Therefore, it makes more sense to use block indentation, represented by
.RS/.RE, rather than indenting each paragraph separately.
That way it's also easier to further indent a separate paragraph inside
a block, which happens for example in the case of float_t & double_t.
It's simply much easier now to use .IP specifically in those cases where
you want to indent just a single paragraph.

Also added an ending separator comment line just after the last type.

Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
---

Hi Michael,

Please, apply after float_t patches.

Thanks,

Alex

 man7/system_data_types.7 | 331 +++++++++++++++++++++++----------------
 1 file changed, 192 insertions(+), 139 deletions(-)

diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
index caca5bb3c..e07ddb468 100644
--- a/man7/system_data_types.7
+++ b/man7/system_data_types.7
@@ -65,10 +65,11 @@ system_data_types \- overview of system data types
 .\"------------------------------------- aiocb ------------------------/
 .TP
 .I aiocb
-.IP
+.RS
+.PP
 Include:
 .IR <aio.h> .
-.IP
+.PP
 .EX
 struct aiocb {
     int             aio_fildes;    /* File descriptor */
@@ -80,12 +81,12 @@ struct aiocb {
     int             aio_lio_opcode;/* Operation to be performed */
 };
 .EE
-.IP
+.PP
 For further information about this structure, see
 .BR aio (7).
-.IP
+.PP
 Conforming to: POSIX.1-2001 and later.
-.IP
+.PP
 See also:
 .BR aio_cancel (3),
 .BR aio_error (3),
@@ -95,40 +96,43 @@ See also:
 .BR aio_suspend (3),
 .BR aio_write (3),
 .BR lio_listio (3)
+.RE
 .\"------------------------------------- div_t ------------------------/
 .TP
 .I div_t
-.IP
+.RS
+.PP
 Include:
 .IR <stdlib.h> .
-.IP
+.PP
 .EX
 typedef struct {
     int quot; /* Quotient */
     int rem;  /* Remainder */
 } div_t;
 .EE
-.IP
+.PP
 It is the type of the value returned by the
 .BR div (3)
 function.
-.IP
+.PP
 Conforming to: C99 and later; POSIX.1-2001 and later.
-.IP
+.PP
 See also:
 .BR div (3)
+.RE
 .\"------------------------------------- double_t ---------------------/
 .TP
 .I double_t
-.IP
+.RS
+.PP
 Include:
 .IR <math.h> .
-.IP
+.PP
 The implementation's most efficient floating type at least as wide as
 .IR double .
 Its type depends on the value of the macro
 .BR FLT_EVAL_METHOD :
-.RS
 .IP *
 0;
 .I double_t
@@ -146,55 +150,59 @@ is
 .IR "long double" .
 .IP *
 Other implementation-defined values.
-.RE
-.IP
+.PP
 Conforming to: C99 and later; POSIX.1-2001 and later.
-.IP
+.PP
 See also the
 .I float_t
 type in this page.
+.RE
 .\"------------------------------------- fenv_t -----------------------/
 .TP
 .I fenv_t
-.IP
+.RS
+.PP
 Include:
 .IR <fenv.h> .
-.IP
+.PP
 This type represents the entire floating-point environment,
 including control modes and status flags; for further details, see
 .BR fenv (3).
-.IP
+.PP
 Conforming to: C99 and later; POSIX.1-2001 and later.
-.IP
+.PP
 See also:
 .BR fenv (3)
+.RE
 .\"------------------------------------- fexcept_t --------------------/
 .TP
 .I fexcept_t
-.IP
+.RS
+.PP
 Include:
 .IR <fenv.h> .
-.IP
+.PP
 This type represents the floating-point status flags collectively;
 for further details see
 .BR fenv (3).
-.IP
+.PP
 Conforming to: C99 and later; POSIX.1-2001 and later.
-.IP
+.PP
 See also:
 .BR fenv (3)
+.RE
 .\"------------------------------------- float_t ----------------------/
 .TP
 .I float_t
-.IP
+.RS
+.PP
 Include:
 .IR <math.h> .
-.IP
+.PP
 The implementation's most efficient floating type at least as wide as
 .IR float .
 Its type depends on the value of the macro
 .BR FLT_EVAL_METHOD :
-.RS
 .IP *
 0;
 .I float_t
@@ -212,17 +220,18 @@ is
 .IR "long double" .
 .IP *
 Other implementation-defined values.
-.RE
-.IP
+.PP
 Conforming to: C99 and later; POSIX.1-2001 and later.
-.IP
+.PP
 See also the
 .I double_t
 type in this page.
+.RE
 .\"------------------------------------- gid_t ------------------------/
 .TP
 .I gid_t
-.IP
+.RS
+.PP
 Include:
 .IR <sys/types.h> ;
 or
@@ -239,13 +248,13 @@ or
 .I <sys/stat.h>
 or
 .IR <unistd.h> .
-.IP
+.PP
 A type used to hold group IDs.
 According to POSIX,
 this shall be an integer type.
-.IP
+.PP
 Conforming to: POSIX.1-2001 and later.
-.IP
+.PP
 See also:
 .BR chown (2),
 .BR getgid (2),
@@ -254,15 +263,17 @@ See also:
 .BR getresgid (2),
 .BR getgrnam (2),
 .BR credentials (7)
+.RE
 .\"------------------------------------- id_t -------------------------/
 .TP
 .I id_t
-.IP
+.RS
+.PP
 Include:
 .IR <sys/types.h> ;
 or
 .IR <sys/resource.h> .
-.IP
+.PP
 A type used to hold a general identifier.
 According to POSIX,
 this shall be an integer type that can be used to contain a
@@ -270,41 +281,45 @@ this shall be an integer type that can be used to contain a
 .IR uid_t ,
 or
 .IR gid_t .
-.IP
+.PP
 Conforming to: POSIX.1-2001 and later.
-.IP
+.PP
 See also:
 .BR getpriority (2),
 .BR waitid (2)
+.RE
 .\"------------------------------------- imaxdiv_t --------------------/
 .TP
 .I imaxdiv_t
-.IP
+.RS
+.PP
 Include:
 .IR <inttypes.h> .
-.IP
+.PP
 .EX
 typedef struct {
     intmax_t    quot; /* Quotient */
     intmax_t    rem;  /* Remainder */
 } imaxdiv_t;
 .EE
-.IP
+.PP
 It is the type of the value returned by the
 .BR imaxdiv (3)
 function.
-.IP
+.PP
 Conforming to: C99 and later; POSIX.1-2001 and later.
-.IP
+.PP
 See also:
 .BR imaxdiv (3)
+.RE
 .\"------------------------------------- lconv ------------------------/
 .TP
 .I lconv
-.IP
+.RS
+.PP
 Include:
 .IR <locale.h> .
-.IP
+.PP
 .EX
 struct lconv {                  /* Values in the "C" locale: */
     char   *decimal_point;      /* "." */
@@ -333,66 +348,72 @@ struct lconv {                  /* Values in the "C" locale: */
     char    int_n_sign_posn;    /* CHAR_MAX */
 };
 .EE
-.IP
+.PP
 Contains members related to the formatting of numeric values.
 In the "C" locale, its members have the values
 shown in the comments above.
-.IP
+.PP
 Conforming to: C11 and later; POSIX.1-2001 and later.
-.IP
+.PP
 See also:
 .BR setlocale (3),
 .BR localeconv (3),
 .BR charsets (5),
 .BR locale (7)
+.RE
 .\"------------------------------------- ldiv_t -----------------------/
 .TP
 .I ldiv_t
-.IP
+.RS
+.PP
 Include:
 .IR <stdlib.h> .
-.IP
+.PP
 .EX
 typedef struct {
     long    quot; /* Quotient */
     long    rem;  /* Remainder */
 } ldiv_t;
 .EE
-.IP
+.PP
 It is the type of the value returned by the
 .BR ldiv (3)
 function.
-.IP
+.PP
 Conforming to: C99 and later; POSIX.1-2001 and later.
-.IP
+.PP
 See also:
 .BR ldiv (3)
+.RE
 .\"------------------------------------- lldiv_t ----------------------/
 .TP
 .I lldiv_t
-.IP
+.RS
+.PP
 Include:
 .IR <stdlib.h> .
-.IP
+.PP
 .EX
 typedef struct {
     long long   quot; /* Quotient */
     long long   rem;  /* Remainder */
 } lldiv_t;
 .EE
-.IP
+.PP
 It is the type of the value returned by the
 .BR lldiv (3)
 function.
-.IP
+.PP
 Conforming to: C99 and later; POSIX.1-2001 and later.
-.IP
+.PP
 See also:
 .BR lldiv (3)
+.RE
 .\"------------------------------------- pid_t ------------------------/
 .TP
 .I pid_t
-.IP
+.RS
+.PP
 Include
 .IR <sys/types.h> ;
 or
@@ -419,7 +440,7 @@ or
 .I <unistd.h>
 or
 .IR <utmpx.h> .
-.IP
+.PP
 This type is used for storing process IDs, process group IDs, and session IDs.
 According to POSIX, it shall be a signed integer type,
 and the implementation shall support one or more programming environments
@@ -427,9 +448,9 @@ where the width of
 .I pid_t
 is no greater than the width of the type
 .IR long .
-.IP
+.PP
 Conforming to: POSIX.1-2001 and later.
-.IP
+.PP
 See also:
 .BR fork (2),
 .BR getpid (2),
@@ -443,20 +464,22 @@ See also:
 .BR waitpid (2),
 .BR sigqueue (3),
 .BR credentials (7),
+.RE
 .\"------------------------------------- ptrdiff_t --------------------/
 .TP
 .I ptrdiff_t
-.IP
+.RS
+.PP
 Include:
 .IR <stddef.h> .
-.IP
+.PP
 Used for a count of elements, and array indices.
 It is the result of subtracting two pointers.
 According to the C language standard, it shall be a signed integer type
 capable of storing values in the range
 .RB [ PTRDIFF_MIN ,
 .BR PTRDIFF_MAX ].
-.IP
+.PP
 The length modifier for
 .I ptrdiff_t
 for the
@@ -472,21 +495,23 @@ or
 for printing
 .I ptrdiff_t
 values.
-.IP
+.PP
 Conforming to: C99 and later; POSIX.1-2001 and later.
-.IP
+.PP
 See also the
 .I size_t
 and
 .I ssize_t
 types in this page.
+.RE
 .\"------------------------------------- regmatch_t -------------------/
 .TP
 .I regmatch_t
-.IP
+.RS
+.PP
 Include:
 .IR <regex.h> .
-.IP
+.PP
 .EX
 typedef struct {
     regoff_t    rm_so; /* Byte offset from start of string
@@ -496,36 +521,38 @@ typedef struct {
                           substring */
 } regmatch_t;
 .EE
-.IP
+.PP
 This is a structure type used in regular expression matching.
-.IP
+.PP
 Conforming to: POSIX.1-2001 and later.
-.IP
+.PP
 See also:
 .BR regexec (3)
+.RE
 .\"------------------------------------- regoff_t ---------------------/
 .TP
 .I regoff_t
-.IP
+.RS
+.PP
 Include:
 .IR <regex.h> .
-.IP
+.PP
 According to POSIX, it shall be a signed integer type
 capable of storing the largest value that can be stored in either a
 .I ptrdiff_t
 type or a
 .I ssize_t
 type.
-.IP
+.PP
 Conforming to: POSIX.1-2001 and later.
-.IP
+.PP
 Notes: Prior to POSIX.1-2008, the type was capable of storing
 the largest value that can be stored in either an
 .I off_t
 type or a
 .I ssize_t
 type.
-.IP
+.PP
 See also the
 .I regmatch_t
 structure and the
@@ -533,10 +560,12 @@ structure and the
 and
 .I ssize_t
 types in this page.
+.RE
 .\"------------------------------------- sigevent ---------------------/
 .TP
 .I sigevent
-.IP
+.RS
+.PP
 Include:
 .IR <signal.h> ;
 or
@@ -545,7 +574,7 @@ or
 .I <mqueue.h>
 or
 .IR <time.h> .
-.IP
+.PP
 .EX
 struct sigevent {
     int             sigev_notify; /* Notification type */
@@ -557,12 +586,12 @@ struct sigevent {
                                   /* Notification attributes */
 };
 .EE
-.IP
+.PP
 For further details about this type, see
 .BR sigevent (7).
-.IP
+.PP
 Conforming to: POSIX.1-2001 and later.
-.IP
+.PP
 Notes:
 .I <aio.h>
 and
@@ -570,25 +599,27 @@ and
 define
 .I sigevent
 since POSIX.1-2008.
-.IP
+.PP
 See also:
 .BR timer_create (2),
 .BR getaddrinfo_a (3),
 .BR lio_listio (3),
 .BR mq_notify (3)
-.IP
+.PP
 See also the
 .I aiocb
 structure in this page.
+.RE
 .\"------------------------------------- siginfo_t --------------------/
 .TP
 .I siginfo_t
-.IP
+.RS
+.PP
 Include:
 .IR <signal.h> ;
 or
 .IR <sys/wait.h> .
-.IP
+.PP
 .EX
 typedef struct {
     int      si_signo;  /* Signal number */
@@ -600,36 +631,38 @@ typedef struct {
     union sigval si_value;  /* Signal value */
 } siginfo_t;
 .EE
-.IP
+.PP
 Information associated with a signal.
 For further details on this structure
 (including additional, Linux-specific fields), see
 .BR sigaction (2).
-.IP
+.PP
 Conforming to: POSIX.1-2001 and later.
-.IP
+.PP
 See also:
 .BR pidfd_send_signal (2),
 .BR rt_sigqueueinfo (2),
 .BR sigaction (2),
 .BR sigwaitinfo (2),
 .BR psiginfo (3)
+.RE
 .\"------------------------------------- sigset_t ---------------------/
 .TP
 .I sigset_t
-.IP
+.RS
+.PP
 Include:
 .IR <signal.h> ;
 or
 .I <spawn.h>
 or
 .IR <sys/select.h> .
-.IP
+.PP
 This is a type that represents a set of signals.
 According to POSIX, this shall be an integer or structure type.
-.IP
+.PP
 Conforming to: POSIX.1-2001 and later.
-.IP
+.PP
 See also:
 .BR epoll_pwait (2),
 .BR ppoll (2),
@@ -641,29 +674,31 @@ See also:
 .BR sigsuspend (2),
 .BR sigwaitinfo (2),
 .BR signal (7)
+.RE
 .\"------------------------------------- sigval -----------------------/
 .TP
 .I sigval
-.IP
+.RS
+.PP
 Include:
 .IR <signal.h> .
-.IP
+.PP
 .EX
 union sigval {
     int     sigval_int; /* Integer value */
     void   *sigval_ptr; /* Pointer value */
 };
 .EE
-.IP
+.PP
 Data passed with a signal.
-.IP
+.PP
 Conforming to: POSIX.1-2001 and later.
-.IP
+.PP
 See also:
 .BR pthread_sigqueue (3),
 .BR sigqueue (3),
 .BR sigevent (7)
-.IP
+.PP
 See also the
 .I sigevent
 structure
@@ -671,10 +706,12 @@ and the
 .I siginfo_t
 type
 in this page.
+.RE
 .\"------------------------------------- size_t -----------------------/
 .TP
 .I size_t
-.IP
+.RS
+.PP
 Include:
 .I <stddef.h>
 or
@@ -729,7 +766,7 @@ or
 .I <wchar.h>
 or
 .IR <wordexp.h> .
-.IP
+.PP
 Used for a count of bytes.  It is the result of the
 .I sizeof
 operator.
@@ -743,7 +780,7 @@ where the width of
 .I size_t
 is no greater than the width of the type
 .IR long .
-.IP
+.PP
 The length modifier for
 .I size_t
 for the
@@ -759,9 +796,9 @@ or
 for printing
 .I size_t
 values.
-.IP
+.PP
 Conforming to: C99 and later; POSIX.1-2001 and later.
-.IP
+.PP
 Notes:
 .IR <aio.h> ,
 .IR <glob.h> ,
@@ -775,7 +812,7 @@ and
 define
 .I size_t
 since POSIX.1-2008.
-.IP
+.PP
 See also:
 .BR read (2),
 .BR write (2),
@@ -786,16 +823,18 @@ See also:
 .BR memcpy (3),
 .BR memset (3),
 .BR offsetof (3)
-.IP
+.PP
 See also the
 .I ptrdiff_t
 and
 .I ssize_t
 types in this page.
+.RE
 .\"------------------------------------- ssize_t ----------------------/
 .TP
 .I ssize_t
-.IP
+.RS
+.PP
 Include:
 .IR <sys/types.h> ;
 or
@@ -814,7 +853,7 @@ or
 .I <sys/uio.h>
 or
 .IR <unistd.h> .
-.IP
+.PP
 Used for a count of bytes or an error indication.
 According to POSIX, it shall be a signed integer type
 capable of storing values at least in the range [-1,
@@ -824,7 +863,7 @@ where the width of
 .I ssize_t
 is no greater than the width of the type
 .IR long .
-.IP
+.PP
 Glibc and most other implementations provide a length modifier for
 .I ssize_t
 for the
@@ -850,9 +889,9 @@ by converting the value to
 .I intmax_t
 and using its length modifier
 .RB ( j ).
-.IP
+.PP
 Conforming to: POSIX.1-2001 and later.
-.IP
+.PP
 See also:
 .BR read (2),
 .BR readlink (2),
@@ -860,23 +899,25 @@ See also:
 .BR recv (2),
 .BR send (2),
 .BR write (2)
-.IP
+.PP
 See also the
 .I ptrdiff_t
 and
 .I size_t
 types in this page.
+.RE
 .\"------------------------------------- suseconds_t ------------------/
 .TP
 .I suseconds_t
-.IP
+.RS
+.PP
 Include:
 .IR <sys/types.h> ;
 or
 .I <sys/select.h>
 or
 .IR <sys/time.h> .
-.IP
+.PP
 Used for time in microseconds.
 According to POSIX, it shall be a signed integer type
 capable of storing values at least in the range [-1, 1000000],
@@ -885,16 +926,18 @@ where the width of
 .I suseconds_t
 is no greater than the width of the type
 .IR long .
-.IP
+.PP
 Conforming to: POSIX.1-2001 and later.
-.IP
+.PP
 See also the
 .I timeval
 structure in this page.
+.RE
 .\"------------------------------------- time_t -----------------------/
 .TP
 .I time_t
-.IP
+.RS
+.PP
 Include:
 .I <sys/types.h>
 or
@@ -915,48 +958,52 @@ or
 .I <sys/time.h>
 or
 .IR <utime.h> .
-.IP
+.PP
 Used for time in seconds.
 According to POSIX, it shall be an integer type.
-.IP
+.PP
 Conforming to: C99 and later; POSIX.1-2001 and later.
-.IP
+.PP
 Notes:
 .I <sched.h>
 defines
 .I time_t
 since POSIX.1-2008.
-.IP
+.PP
 See also:
 .BR stime (2),
 .BR time (2),
 .BR ctime (3),
 .BR difftime (3)
+.RE
 .\"------------------------------------- timer_t ----------------------/
 .TP
 .I timer_t
-.IP
+.RS
+.PP
 Include:
 .IR <sys/types.h> ;
 or
 .IR <time.h> .
-.IP
+.PP
 Used for timer ID returned by
 .BR timer_create (2).
 According to POSIX,
 there are no defined comparison or assignment operators for this type.
-.IP
+.PP
 Conforming to: POSIX.1-2001 and later.
-.IP
+.PP
 See also:
 .BR timer_create (2),
 .BR timer_delete (2),
 .BR timer_getoverrun (2),
 .BR timer_settime (2)
+.RE
 .\"------------------------------------- timespec ---------------------/
 .TP
 .I timespec
-.IP
+.RS
+.PP
 Include:
 .IR <time.h> ;
 or
@@ -971,28 +1018,30 @@ or
 .I <sys/select.h>
 or
 .IR <sys/stat.h> .
-.IP
+.PP
 .EX
 struct timespec {
     time_t  tv_sec;  /* Seconds */
     long    tv_nsec; /* Nanoseconds */
 };
 .EE
-.IP
+.PP
 Describes times in seconds and nanoseconds.
-.IP
+.PP
 Conforming to: C11 and later; POSIX.1-2001 and later.
-.IP
+.PP
 See also:
 .BR clock_gettime (2),
 .BR clock_nanosleep (2),
 .BR nanosleep (2),
 .BR timerfd_gettime (2),
 .BR timer_gettime (2)
+.RE
 .\"------------------------------------- timeval ----------------------/
 .TP
 .I timeval
-.IP
+.RS
+.PP
 Include:
 .IR <sys/time.h> ;
 or
@@ -1001,18 +1050,18 @@ or
 .I <sys/select.h>
 or
 .IR <utmpx.h> .
-.IP
+.PP
 .EX
 struct timeval {
     time_t      tv_sec;  /* Seconds */
     suseconds_t tv_usec; /* Microseconds */
 };
 .EE
-.IP
+.PP
 Describes times in seconds and microseconds.
-.IP
+.PP
 Conforming to: POSIX.1-2001 and later.
-.IP
+.PP
 See also:
 .BR gettimeofday (2),
 .BR select (2),
@@ -1020,10 +1069,12 @@ See also:
 .BR adjtime (3),
 .BR futimes (3),
 .BR timeradd (3)
+.RE
 .\"------------------------------------- uid_t ----------------------/
 .TP
 .I uid_t
-.IP
+.RS
+.PP
 Include:
 .IR <sys/types.h> ;
 or
@@ -1038,13 +1089,13 @@ or
 .I <sys/stat.h>
 or
 .IR <unistd.h> .
-.IP
+.PP
 A type used to hold user IDs.
 According to POSIX,
 this shall be an integer type.
-.IP
+.PP
 Conforming to: POSIX.1-2001 and later.
-.IP
+.PP
 See also:
 .BR chown (2),
 .BR getuid (2),
@@ -1052,6 +1103,8 @@ See also:
 .BR getresuid (2),
 .BR getpwnam (2),
 .BR credentials (7)
+.RE
+.\"--------------------------------------------------------------------/
 .SH NOTES
 The structures described in this manual page shall contain,
 at least, the members shown in their definition, in no particular order.
-- 
2.28.0

Re: [PATCH 1/2] system_data_types.7: srcfix

[Michael Kerrisk (man-pages)]

On 9/25/20 10:03 AM, Alejandro Colomar wrote:
> Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
> ---
>  man7/system_data_types.7 | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
> index 43e88942a..caca5bb3c 100644
> --- a/man7/system_data_types.7
> +++ b/man7/system_data_types.7
> @@ -454,7 +454,7 @@ Used for a count of elements, and array indices.
>  It is the result of subtracting two pointers.
>  According to the C language standard, it shall be a signed integer type
>  capable of storing values in the range
> -.BR "" [ PTRDIFF_MIN ,
> +.RB [ PTRDIFF_MIN ,

Patch applied. I should have spotted that and told you earlier about
the right way...

Thanks,

Michael

>  .BR PTRDIFF_MAX ].
>  .IP
>  The length modifier for
> 


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Re: [PATCH 2/2] system_data_types.7: srcfix

[Michael Kerrisk (man-pages)]

Hi Alex,

On 9/25/20 10:03 AM, Alejandro Colomar wrote:
> The contents of each type are a logic block that is indented as a block.
> They are not separate paragraphs that happen to be indented separately,
> but a set of continuous paragraphs, all in the same level,
> indented as a block from the list entry--the name of the type--.
> Therefore, it makes more sense to use block indentation, represented by
> .RS/.RE, rather than indenting each paragraph separately.
> That way it's also easier to further indent a separate paragraph inside
> a block, which happens for example in the case of float_t & double_t.
> It's simply much easier now to use .IP specifically in those cases where
> you want to indent just a single paragraph.
> 
> Also added an ending separator comment line just after the last type.
> 
> Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>

Just to confirm: I think I'm supposed to waiting on a revised 
version of this patch, right? (This version of the patch doesn't
apply in my tree.)

Thanks,

Michael

> ---
> 
> Hi Michael,
> 
> Please, apply after float_t patches.
> 
> Thanks,
> 
> Alex
> 
>  man7/system_data_types.7 | 331 +++++++++++++++++++++++----------------
>  1 file changed, 192 insertions(+), 139 deletions(-)
> 
> diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
> index caca5bb3c..e07ddb468 100644
> --- a/man7/system_data_types.7
> +++ b/man7/system_data_types.7
> @@ -65,10 +65,11 @@ system_data_types \- overview of system data types
>  .\"------------------------------------- aiocb ------------------------/
>  .TP
>  .I aiocb
> -.IP
> +.RS
> +.PP
>  Include:
>  .IR <aio.h> .
> -.IP
> +.PP
>  .EX
>  struct aiocb {
>      int             aio_fildes;    /* File descriptor */
> @@ -80,12 +81,12 @@ struct aiocb {
>      int             aio_lio_opcode;/* Operation to be performed */
>  };
>  .EE
> -.IP
> +.PP
>  For further information about this structure, see
>  .BR aio (7).
> -.IP
> +.PP
>  Conforming to: POSIX.1-2001 and later.
> -.IP
> +.PP
>  See also:
>  .BR aio_cancel (3),
>  .BR aio_error (3),
> @@ -95,40 +96,43 @@ See also:
>  .BR aio_suspend (3),
>  .BR aio_write (3),
>  .BR lio_listio (3)
> +.RE
>  .\"------------------------------------- div_t ------------------------/
>  .TP
>  .I div_t
> -.IP
> +.RS
> +.PP
>  Include:
>  .IR <stdlib.h> .
> -.IP
> +.PP
>  .EX
>  typedef struct {
>      int quot; /* Quotient */
>      int rem;  /* Remainder */
>  } div_t;
>  .EE
> -.IP
> +.PP
>  It is the type of the value returned by the
>  .BR div (3)
>  function.
> -.IP
> +.PP
>  Conforming to: C99 and later; POSIX.1-2001 and later.
> -.IP
> +.PP
>  See also:
>  .BR div (3)
> +.RE
>  .\"------------------------------------- double_t ---------------------/
>  .TP
>  .I double_t
> -.IP
> +.RS
> +.PP
>  Include:
>  .IR <math.h> .
> -.IP
> +.PP
>  The implementation's most efficient floating type at least as wide as
>  .IR double .
>  Its type depends on the value of the macro
>  .BR FLT_EVAL_METHOD :
> -.RS
>  .IP *
>  0;
>  .I double_t
> @@ -146,55 +150,59 @@ is
>  .IR "long double" .
>  .IP *
>  Other implementation-defined values.
> -.RE
> -.IP
> +.PP
>  Conforming to: C99 and later; POSIX.1-2001 and later.
> -.IP
> +.PP
>  See also the
>  .I float_t
>  type in this page.
> +.RE
>  .\"------------------------------------- fenv_t -----------------------/
>  .TP
>  .I fenv_t
> -.IP
> +.RS
> +.PP
>  Include:
>  .IR <fenv.h> .
> -.IP
> +.PP
>  This type represents the entire floating-point environment,
>  including control modes and status flags; for further details, see
>  .BR fenv (3).
> -.IP
> +.PP
>  Conforming to: C99 and later; POSIX.1-2001 and later.
> -.IP
> +.PP
>  See also:
>  .BR fenv (3)
> +.RE
>  .\"------------------------------------- fexcept_t --------------------/
>  .TP
>  .I fexcept_t
> -.IP
> +.RS
> +.PP
>  Include:
>  .IR <fenv.h> .
> -.IP
> +.PP
>  This type represents the floating-point status flags collectively;
>  for further details see
>  .BR fenv (3).
> -.IP
> +.PP
>  Conforming to: C99 and later; POSIX.1-2001 and later.
> -.IP
> +.PP
>  See also:
>  .BR fenv (3)
> +.RE
>  .\"------------------------------------- float_t ----------------------/
>  .TP
>  .I float_t
> -.IP
> +.RS
> +.PP
>  Include:
>  .IR <math.h> .
> -.IP
> +.PP
>  The implementation's most efficient floating type at least as wide as
>  .IR float .
>  Its type depends on the value of the macro
>  .BR FLT_EVAL_METHOD :
> -.RS
>  .IP *
>  0;
>  .I float_t
> @@ -212,17 +220,18 @@ is
>  .IR "long double" .
>  .IP *
>  Other implementation-defined values.
> -.RE
> -.IP
> +.PP
>  Conforming to: C99 and later; POSIX.1-2001 and later.
> -.IP
> +.PP
>  See also the
>  .I double_t
>  type in this page.
> +.RE
>  .\"------------------------------------- gid_t ------------------------/
>  .TP
>  .I gid_t
> -.IP
> +.RS
> +.PP
>  Include:
>  .IR <sys/types.h> ;
>  or
> @@ -239,13 +248,13 @@ or
>  .I <sys/stat.h>
>  or
>  .IR <unistd.h> .
> -.IP
> +.PP
>  A type used to hold group IDs.
>  According to POSIX,
>  this shall be an integer type.
> -.IP
> +.PP
>  Conforming to: POSIX.1-2001 and later.
> -.IP
> +.PP
>  See also:
>  .BR chown (2),
>  .BR getgid (2),
> @@ -254,15 +263,17 @@ See also:
>  .BR getresgid (2),
>  .BR getgrnam (2),
>  .BR credentials (7)
> +.RE
>  .\"------------------------------------- id_t -------------------------/
>  .TP
>  .I id_t
> -.IP
> +.RS
> +.PP
>  Include:
>  .IR <sys/types.h> ;
>  or
>  .IR <sys/resource.h> .
> -.IP
> +.PP
>  A type used to hold a general identifier.
>  According to POSIX,
>  this shall be an integer type that can be used to contain a
> @@ -270,41 +281,45 @@ this shall be an integer type that can be used to contain a
>  .IR uid_t ,
>  or
>  .IR gid_t .
> -.IP
> +.PP
>  Conforming to: POSIX.1-2001 and later.
> -.IP
> +.PP
>  See also:
>  .BR getpriority (2),
>  .BR waitid (2)
> +.RE
>  .\"------------------------------------- imaxdiv_t --------------------/
>  .TP
>  .I imaxdiv_t
> -.IP
> +.RS
> +.PP
>  Include:
>  .IR <inttypes.h> .
> -.IP
> +.PP
>  .EX
>  typedef struct {
>      intmax_t    quot; /* Quotient */
>      intmax_t    rem;  /* Remainder */
>  } imaxdiv_t;
>  .EE
> -.IP
> +.PP
>  It is the type of the value returned by the
>  .BR imaxdiv (3)
>  function.
> -.IP
> +.PP
>  Conforming to: C99 and later; POSIX.1-2001 and later.
> -.IP
> +.PP
>  See also:
>  .BR imaxdiv (3)
> +.RE
>  .\"------------------------------------- lconv ------------------------/
>  .TP
>  .I lconv
> -.IP
> +.RS
> +.PP
>  Include:
>  .IR <locale.h> .
> -.IP
> +.PP
>  .EX
>  struct lconv {                  /* Values in the "C" locale: */
>      char   *decimal_point;      /* "." */
> @@ -333,66 +348,72 @@ struct lconv {                  /* Values in the "C" locale: */
>      char    int_n_sign_posn;    /* CHAR_MAX */
>  };
>  .EE
> -.IP
> +.PP
>  Contains members related to the formatting of numeric values.
>  In the "C" locale, its members have the values
>  shown in the comments above.
> -.IP
> +.PP
>  Conforming to: C11 and later; POSIX.1-2001 and later.
> -.IP
> +.PP
>  See also:
>  .BR setlocale (3),
>  .BR localeconv (3),
>  .BR charsets (5),
>  .BR locale (7)
> +.RE
>  .\"------------------------------------- ldiv_t -----------------------/
>  .TP
>  .I ldiv_t
> -.IP
> +.RS
> +.PP
>  Include:
>  .IR <stdlib.h> .
> -.IP
> +.PP
>  .EX
>  typedef struct {
>      long    quot; /* Quotient */
>      long    rem;  /* Remainder */
>  } ldiv_t;
>  .EE
> -.IP
> +.PP
>  It is the type of the value returned by the
>  .BR ldiv (3)
>  function.
> -.IP
> +.PP
>  Conforming to: C99 and later; POSIX.1-2001 and later.
> -.IP
> +.PP
>  See also:
>  .BR ldiv (3)
> +.RE
>  .\"------------------------------------- lldiv_t ----------------------/
>  .TP
>  .I lldiv_t
> -.IP
> +.RS
> +.PP
>  Include:
>  .IR <stdlib.h> .
> -.IP
> +.PP
>  .EX
>  typedef struct {
>      long long   quot; /* Quotient */
>      long long   rem;  /* Remainder */
>  } lldiv_t;
>  .EE
> -.IP
> +.PP
>  It is the type of the value returned by the
>  .BR lldiv (3)
>  function.
> -.IP
> +.PP
>  Conforming to: C99 and later; POSIX.1-2001 and later.
> -.IP
> +.PP
>  See also:
>  .BR lldiv (3)
> +.RE
>  .\"------------------------------------- pid_t ------------------------/
>  .TP
>  .I pid_t
> -.IP
> +.RS
> +.PP
>  Include
>  .IR <sys/types.h> ;
>  or
> @@ -419,7 +440,7 @@ or
>  .I <unistd.h>
>  or
>  .IR <utmpx.h> .
> -.IP
> +.PP
>  This type is used for storing process IDs, process group IDs, and session IDs.
>  According to POSIX, it shall be a signed integer type,
>  and the implementation shall support one or more programming environments
> @@ -427,9 +448,9 @@ where the width of
>  .I pid_t
>  is no greater than the width of the type
>  .IR long .
> -.IP
> +.PP
>  Conforming to: POSIX.1-2001 and later.
> -.IP
> +.PP
>  See also:
>  .BR fork (2),
>  .BR getpid (2),
> @@ -443,20 +464,22 @@ See also:
>  .BR waitpid (2),
>  .BR sigqueue (3),
>  .BR credentials (7),
> +.RE
>  .\"------------------------------------- ptrdiff_t --------------------/
>  .TP
>  .I ptrdiff_t
> -.IP
> +.RS
> +.PP
>  Include:
>  .IR <stddef.h> .
> -.IP
> +.PP
>  Used for a count of elements, and array indices.
>  It is the result of subtracting two pointers.
>  According to the C language standard, it shall be a signed integer type
>  capable of storing values in the range
>  .RB [ PTRDIFF_MIN ,
>  .BR PTRDIFF_MAX ].
> -.IP
> +.PP
>  The length modifier for
>  .I ptrdiff_t
>  for the
> @@ -472,21 +495,23 @@ or
>  for printing
>  .I ptrdiff_t
>  values.
> -.IP
> +.PP
>  Conforming to: C99 and later; POSIX.1-2001 and later.
> -.IP
> +.PP
>  See also the
>  .I size_t
>  and
>  .I ssize_t
>  types in this page.
> +.RE
>  .\"------------------------------------- regmatch_t -------------------/
>  .TP
>  .I regmatch_t
> -.IP
> +.RS
> +.PP
>  Include:
>  .IR <regex.h> .
> -.IP
> +.PP
>  .EX
>  typedef struct {
>      regoff_t    rm_so; /* Byte offset from start of string
> @@ -496,36 +521,38 @@ typedef struct {
>                            substring */
>  } regmatch_t;
>  .EE
> -.IP
> +.PP
>  This is a structure type used in regular expression matching.
> -.IP
> +.PP
>  Conforming to: POSIX.1-2001 and later.
> -.IP
> +.PP
>  See also:
>  .BR regexec (3)
> +.RE
>  .\"------------------------------------- regoff_t ---------------------/
>  .TP
>  .I regoff_t
> -.IP
> +.RS
> +.PP
>  Include:
>  .IR <regex.h> .
> -.IP
> +.PP
>  According to POSIX, it shall be a signed integer type
>  capable of storing the largest value that can be stored in either a
>  .I ptrdiff_t
>  type or a
>  .I ssize_t
>  type.
> -.IP
> +.PP
>  Conforming to: POSIX.1-2001 and later.
> -.IP
> +.PP
>  Notes: Prior to POSIX.1-2008, the type was capable of storing
>  the largest value that can be stored in either an
>  .I off_t
>  type or a
>  .I ssize_t
>  type.
> -.IP
> +.PP
>  See also the
>  .I regmatch_t
>  structure and the
> @@ -533,10 +560,12 @@ structure and the
>  and
>  .I ssize_t
>  types in this page.
> +.RE
>  .\"------------------------------------- sigevent ---------------------/
>  .TP
>  .I sigevent
> -.IP
> +.RS
> +.PP
>  Include:
>  .IR <signal.h> ;
>  or
> @@ -545,7 +574,7 @@ or
>  .I <mqueue.h>
>  or
>  .IR <time.h> .
> -.IP
> +.PP
>  .EX
>  struct sigevent {
>      int             sigev_notify; /* Notification type */
> @@ -557,12 +586,12 @@ struct sigevent {
>                                    /* Notification attributes */
>  };
>  .EE
> -.IP
> +.PP
>  For further details about this type, see
>  .BR sigevent (7).
> -.IP
> +.PP
>  Conforming to: POSIX.1-2001 and later.
> -.IP
> +.PP
>  Notes:
>  .I <aio.h>
>  and
> @@ -570,25 +599,27 @@ and
>  define
>  .I sigevent
>  since POSIX.1-2008.
> -.IP
> +.PP
>  See also:
>  .BR timer_create (2),
>  .BR getaddrinfo_a (3),
>  .BR lio_listio (3),
>  .BR mq_notify (3)
> -.IP
> +.PP
>  See also the
>  .I aiocb
>  structure in this page.
> +.RE
>  .\"------------------------------------- siginfo_t --------------------/
>  .TP
>  .I siginfo_t
> -.IP
> +.RS
> +.PP
>  Include:
>  .IR <signal.h> ;
>  or
>  .IR <sys/wait.h> .
> -.IP
> +.PP
>  .EX
>  typedef struct {
>      int      si_signo;  /* Signal number */
> @@ -600,36 +631,38 @@ typedef struct {
>      union sigval si_value;  /* Signal value */
>  } siginfo_t;
>  .EE
> -.IP
> +.PP
>  Information associated with a signal.
>  For further details on this structure
>  (including additional, Linux-specific fields), see
>  .BR sigaction (2).
> -.IP
> +.PP
>  Conforming to: POSIX.1-2001 and later.
> -.IP
> +.PP
>  See also:
>  .BR pidfd_send_signal (2),
>  .BR rt_sigqueueinfo (2),
>  .BR sigaction (2),
>  .BR sigwaitinfo (2),
>  .BR psiginfo (3)
> +.RE
>  .\"------------------------------------- sigset_t ---------------------/
>  .TP
>  .I sigset_t
> -.IP
> +.RS
> +.PP
>  Include:
>  .IR <signal.h> ;
>  or
>  .I <spawn.h>
>  or
>  .IR <sys/select.h> .
> -.IP
> +.PP
>  This is a type that represents a set of signals.
>  According to POSIX, this shall be an integer or structure type.
> -.IP
> +.PP
>  Conforming to: POSIX.1-2001 and later.
> -.IP
> +.PP
>  See also:
>  .BR epoll_pwait (2),
>  .BR ppoll (2),
> @@ -641,29 +674,31 @@ See also:
>  .BR sigsuspend (2),
>  .BR sigwaitinfo (2),
>  .BR signal (7)
> +.RE
>  .\"------------------------------------- sigval -----------------------/
>  .TP
>  .I sigval
> -.IP
> +.RS
> +.PP
>  Include:
>  .IR <signal.h> .
> -.IP
> +.PP
>  .EX
>  union sigval {
>      int     sigval_int; /* Integer value */
>      void   *sigval_ptr; /* Pointer value */
>  };
>  .EE
> -.IP
> +.PP
>  Data passed with a signal.
> -.IP
> +.PP
>  Conforming to: POSIX.1-2001 and later.
> -.IP
> +.PP
>  See also:
>  .BR pthread_sigqueue (3),
>  .BR sigqueue (3),
>  .BR sigevent (7)
> -.IP
> +.PP
>  See also the
>  .I sigevent
>  structure
> @@ -671,10 +706,12 @@ and the
>  .I siginfo_t
>  type
>  in this page.
> +.RE
>  .\"------------------------------------- size_t -----------------------/
>  .TP
>  .I size_t
> -.IP
> +.RS
> +.PP
>  Include:
>  .I <stddef.h>
>  or
> @@ -729,7 +766,7 @@ or
>  .I <wchar.h>
>  or
>  .IR <wordexp.h> .
> -.IP
> +.PP
>  Used for a count of bytes.  It is the result of the
>  .I sizeof
>  operator.
> @@ -743,7 +780,7 @@ where the width of
>  .I size_t
>  is no greater than the width of the type
>  .IR long .
> -.IP
> +.PP
>  The length modifier for
>  .I size_t
>  for the
> @@ -759,9 +796,9 @@ or
>  for printing
>  .I size_t
>  values.
> -.IP
> +.PP
>  Conforming to: C99 and later; POSIX.1-2001 and later.
> -.IP
> +.PP
>  Notes:
>  .IR <aio.h> ,
>  .IR <glob.h> ,
> @@ -775,7 +812,7 @@ and
>  define
>  .I size_t
>  since POSIX.1-2008.
> -.IP
> +.PP
>  See also:
>  .BR read (2),
>  .BR write (2),
> @@ -786,16 +823,18 @@ See also:
>  .BR memcpy (3),
>  .BR memset (3),
>  .BR offsetof (3)
> -.IP
> +.PP
>  See also the
>  .I ptrdiff_t
>  and
>  .I ssize_t
>  types in this page.
> +.RE
>  .\"------------------------------------- ssize_t ----------------------/
>  .TP
>  .I ssize_t
> -.IP
> +.RS
> +.PP
>  Include:
>  .IR <sys/types.h> ;
>  or
> @@ -814,7 +853,7 @@ or
>  .I <sys/uio.h>
>  or
>  .IR <unistd.h> .
> -.IP
> +.PP
>  Used for a count of bytes or an error indication.
>  According to POSIX, it shall be a signed integer type
>  capable of storing values at least in the range [-1,
> @@ -824,7 +863,7 @@ where the width of
>  .I ssize_t
>  is no greater than the width of the type
>  .IR long .
> -.IP
> +.PP
>  Glibc and most other implementations provide a length modifier for
>  .I ssize_t
>  for the
> @@ -850,9 +889,9 @@ by converting the value to
>  .I intmax_t
>  and using its length modifier
>  .RB ( j ).
> -.IP
> +.PP
>  Conforming to: POSIX.1-2001 and later.
> -.IP
> +.PP
>  See also:
>  .BR read (2),
>  .BR readlink (2),
> @@ -860,23 +899,25 @@ See also:
>  .BR recv (2),
>  .BR send (2),
>  .BR write (2)
> -.IP
> +.PP
>  See also the
>  .I ptrdiff_t
>  and
>  .I size_t
>  types in this page.
> +.RE
>  .\"------------------------------------- suseconds_t ------------------/
>  .TP
>  .I suseconds_t
> -.IP
> +.RS
> +.PP
>  Include:
>  .IR <sys/types.h> ;
>  or
>  .I <sys/select.h>
>  or
>  .IR <sys/time.h> .
> -.IP
> +.PP
>  Used for time in microseconds.
>  According to POSIX, it shall be a signed integer type
>  capable of storing values at least in the range [-1, 1000000],
> @@ -885,16 +926,18 @@ where the width of
>  .I suseconds_t
>  is no greater than the width of the type
>  .IR long .
> -.IP
> +.PP
>  Conforming to: POSIX.1-2001 and later.
> -.IP
> +.PP
>  See also the
>  .I timeval
>  structure in this page.
> +.RE
>  .\"------------------------------------- time_t -----------------------/
>  .TP
>  .I time_t
> -.IP
> +.RS
> +.PP
>  Include:
>  .I <sys/types.h>
>  or
> @@ -915,48 +958,52 @@ or
>  .I <sys/time.h>
>  or
>  .IR <utime.h> .
> -.IP
> +.PP
>  Used for time in seconds.
>  According to POSIX, it shall be an integer type.
> -.IP
> +.PP
>  Conforming to: C99 and later; POSIX.1-2001 and later.
> -.IP
> +.PP
>  Notes:
>  .I <sched.h>
>  defines
>  .I time_t
>  since POSIX.1-2008.
> -.IP
> +.PP
>  See also:
>  .BR stime (2),
>  .BR time (2),
>  .BR ctime (3),
>  .BR difftime (3)
> +.RE
>  .\"------------------------------------- timer_t ----------------------/
>  .TP
>  .I timer_t
> -.IP
> +.RS
> +.PP
>  Include:
>  .IR <sys/types.h> ;
>  or
>  .IR <time.h> .
> -.IP
> +.PP
>  Used for timer ID returned by
>  .BR timer_create (2).
>  According to POSIX,
>  there are no defined comparison or assignment operators for this type.
> -.IP
> +.PP
>  Conforming to: POSIX.1-2001 and later.
> -.IP
> +.PP
>  See also:
>  .BR timer_create (2),
>  .BR timer_delete (2),
>  .BR timer_getoverrun (2),
>  .BR timer_settime (2)
> +.RE
>  .\"------------------------------------- timespec ---------------------/
>  .TP
>  .I timespec
> -.IP
> +.RS
> +.PP
>  Include:
>  .IR <time.h> ;
>  or
> @@ -971,28 +1018,30 @@ or
>  .I <sys/select.h>
>  or
>  .IR <sys/stat.h> .
> -.IP
> +.PP
>  .EX
>  struct timespec {
>      time_t  tv_sec;  /* Seconds */
>      long    tv_nsec; /* Nanoseconds */
>  };
>  .EE
> -.IP
> +.PP
>  Describes times in seconds and nanoseconds.
> -.IP
> +.PP
>  Conforming to: C11 and later; POSIX.1-2001 and later.
> -.IP
> +.PP
>  See also:
>  .BR clock_gettime (2),
>  .BR clock_nanosleep (2),
>  .BR nanosleep (2),
>  .BR timerfd_gettime (2),
>  .BR timer_gettime (2)
> +.RE
>  .\"------------------------------------- timeval ----------------------/
>  .TP
>  .I timeval
> -.IP
> +.RS
> +.PP
>  Include:
>  .IR <sys/time.h> ;
>  or
> @@ -1001,18 +1050,18 @@ or
>  .I <sys/select.h>
>  or
>  .IR <utmpx.h> .
> -.IP
> +.PP
>  .EX
>  struct timeval {
>      time_t      tv_sec;  /* Seconds */
>      suseconds_t tv_usec; /* Microseconds */
>  };
>  .EE
> -.IP
> +.PP
>  Describes times in seconds and microseconds.
> -.IP
> +.PP
>  Conforming to: POSIX.1-2001 and later.
> -.IP
> +.PP
>  See also:
>  .BR gettimeofday (2),
>  .BR select (2),
> @@ -1020,10 +1069,12 @@ See also:
>  .BR adjtime (3),
>  .BR futimes (3),
>  .BR timeradd (3)
> +.RE
>  .\"------------------------------------- uid_t ----------------------/
>  .TP
>  .I uid_t
> -.IP
> +.RS
> +.PP
>  Include:
>  .IR <sys/types.h> ;
>  or
> @@ -1038,13 +1089,13 @@ or
>  .I <sys/stat.h>
>  or
>  .IR <unistd.h> .
> -.IP
> +.PP
>  A type used to hold user IDs.
>  According to POSIX,
>  this shall be an integer type.
> -.IP
> +.PP
>  Conforming to: POSIX.1-2001 and later.
> -.IP
> +.PP
>  See also:
>  .BR chown (2),
>  .BR getuid (2),
> @@ -1052,6 +1103,8 @@ See also:
>  .BR getresuid (2),
>  .BR getpwnam (2),
>  .BR credentials (7)
> +.RE
> +.\"--------------------------------------------------------------------/
>  .SH NOTES
>  The structures described in this manual page shall contain,
>  at least, the members shown in their definition, in no particular order.
> 


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

[PATCH v2 2/2] system_data_types.7: srcfix

[Alejandro Colomar]

The contents of each type are a logic block that is indented as a block.
They are not separate paragraphs that happen to be indented separately,
but a set of continuous paragraphs, all in the same level,
indented as a block from the list entry--the name of the type--.
Therefore, it makes more sense to use block indentation, represented by
.RS/.RE, rather than indenting each paragraph separately.
That way it's also easier to further indent a separate paragraph inside
a block, which happens for example in the case of float_t & double_t.
It's simply much easier now to use .IP specifically in those cases where
you want to indent just a single paragraph.

Also added an ending separator comment line just after the last type.

Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
---

Hi Michael,


On 2020-09-25 12:40, Michael Kerrisk (man-pages) wrote:
> Just to confirm: I think I'm supposed to waiting on a revised
> version of this patch, right? (This version of the patch doesn't
> apply in my tree.)
> 
> Thanks,
> 
> Michael

Right.

It was somewhat complicated to fix the commits in the middle
and rebase and then fix breakages and rebase again and fix more commits...
I learned a lot of git today :)

Cheers,

Alex


 man7/system_data_types.7 | 331 +++++++++++++++++++++++----------------
 1 file changed, 192 insertions(+), 139 deletions(-)

diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
index e3a3856a2..0837087fb 100644
--- a/man7/system_data_types.7
+++ b/man7/system_data_types.7
@@ -65,10 +65,11 @@ system_data_types \- overview of system data types
 .\"------------------------------------- aiocb ------------------------/
 .TP
 .I aiocb
-.IP
+.RS
+.PP
 Include:
 .IR <aio.h> .
-.IP
+.PP
 .EX
 struct aiocb {
     int             aio_fildes;    /* File descriptor */
@@ -80,12 +81,12 @@ struct aiocb {
     int             aio_lio_opcode;/* Operation to be performed */
 };
 .EE
-.IP
+.PP
 For further information about this structure, see
 .BR aio (7).
-.IP
+.PP
 Conforming to: POSIX.1-2001 and later.
-.IP
+.PP
 See also:
 .BR aio_cancel (3),
 .BR aio_error (3),
@@ -95,42 +96,45 @@ See also:
 .BR aio_suspend (3),
 .BR aio_write (3),
 .BR lio_listio (3)
+.RE
 .\"------------------------------------- div_t ------------------------/
 .TP
 .I div_t
-.IP
+.RS
+.PP
 Include:
 .IR <stdlib.h> .
-.IP
+.PP
 .EX
 typedef struct {
     int quot; /* Quotient */
     int rem;  /* Remainder */
 } div_t;
 .EE
-.IP
+.PP
 It is the type of the value returned by the
 .BR div (3)
 function.
-.IP
+.PP
 Conforming to: C99 and later; POSIX.1-2001 and later.
-.IP
+.PP
 See also:
 .BR div (3)
+.RE
 .\"------------------------------------- double_t ---------------------/
 .TP
 .I double_t
-.IP
+.RS
+.PP
 Include:
 .IR <math.h> .
-.IP
+.PP
 The implementation's most efficient floating type at least as wide as
 .IR double .
 Its type depends on the value of the macro
 .BR FLT_EVAL_METHOD ,
 defined in
 .IR <float.h> :
-.RS
 .TP
 0
 .I double_t
@@ -152,57 +156,61 @@ For other values of
 the type of
 .I double_t
 is implementation-defined.
-.RE
-.IP
+.PP
 Conforming to: C99 and later; POSIX.1-2001 and later.
-.IP
+.PP
 See also the
 .I float_t
 type in this page.
+.RE
 .\"------------------------------------- fenv_t -----------------------/
 .TP
 .I fenv_t
-.IP
+.RS
+.PP
 Include:
 .IR <fenv.h> .
-.IP
+.PP
 This type represents the entire floating-point environment,
 including control modes and status flags; for further details, see
 .BR fenv (3).
-.IP
+.PP
 Conforming to: C99 and later; POSIX.1-2001 and later.
-.IP
+.PP
 See also:
 .BR fenv (3)
+.RE
 .\"------------------------------------- fexcept_t --------------------/
 .TP
 .I fexcept_t
-.IP
+.RS
+.PP
 Include:
 .IR <fenv.h> .
-.IP
+.PP
 This type represents the floating-point status flags collectively;
 for further details see
 .BR fenv (3).
-.IP
+.PP
 Conforming to: C99 and later; POSIX.1-2001 and later.
-.IP
+.PP
 See also:
 .BR fenv (3)
+.RE
 .\"------------------------------------- float_t ----------------------/
 .TP
 .I float_t
-.IP
+.RS
+.PP
 Include:
 .IR <math.h> .
-.IP
+.PP
 The implementation's most efficient floating type at least as wide as
 .IR float .
 Its type depends on the value of the macro
 .BR FLT_EVAL_METHOD ,
 defined in
 .IR <float.h> :
-.RS
 .TP
 0
 .I float_t
@@ -224,17 +232,18 @@ For other values of
 the type of
 .I float_t
 is implementation-defined.
-.RE
-.IP
+.PP
 Conforming to: C99 and later; POSIX.1-2001 and later.
-.IP
+.PP
 See also the
 .I double_t
 type in this page.
+.RE
 .\"------------------------------------- gid_t ------------------------/
 .TP
 .I gid_t
-.IP
+.RS
+.PP
 Include:
 .IR <sys/types.h> ;
 or
@@ -251,13 +260,13 @@ or
 .I <sys/stat.h>
 or
 .IR <unistd.h> .
-.IP
+.PP
 A type used to hold group IDs.
 According to POSIX,
 this shall be an integer type.
-.IP
+.PP
 Conforming to: POSIX.1-2001 and later.
-.IP
+.PP
 See also:
 .BR chown (2),
 .BR getgid (2),
@@ -266,15 +275,17 @@ See also:
 .BR getresgid (2),
 .BR getgrnam (2),
 .BR credentials (7)
+.RE
 .\"------------------------------------- id_t -------------------------/
 .TP
 .I id_t
-.IP
+.RS
+.PP
 Include:
 .IR <sys/types.h> ;
 or
 .IR <sys/resource.h> .
-.IP
+.PP
 A type used to hold a general identifier.
 According to POSIX,
 this shall be an integer type that can be used to contain a
@@ -282,41 +293,45 @@ this shall be an integer type that can be used to contain a
 .IR uid_t ,
 or
 .IR gid_t .
-.IP
+.PP
 Conforming to: POSIX.1-2001 and later.
-.IP
+.PP
 See also:
 .BR getpriority (2),
 .BR waitid (2)
+.RE
 .\"------------------------------------- imaxdiv_t --------------------/
 .TP
 .I imaxdiv_t
-.IP
+.RS
+.PP
 Include:
 .IR <inttypes.h> .
-.IP
+.PP
 .EX
 typedef struct {
     intmax_t    quot; /* Quotient */
     intmax_t    rem;  /* Remainder */
 } imaxdiv_t;
 .EE
-.IP
+.PP
 It is the type of the value returned by the
 .BR imaxdiv (3)
 function.
-.IP
+.PP
 Conforming to: C99 and later; POSIX.1-2001 and later.
-.IP
+.PP
 See also:
 .BR imaxdiv (3)
+.RE
 .\"------------------------------------- lconv ------------------------/
 .TP
 .I lconv
-.IP
+.RS
+.PP
 Include:
 .IR <locale.h> .
-.IP
+.PP
 .EX
 struct lconv {                  /* Values in the "C" locale: */
     char   *decimal_point;      /* "." */
@@ -345,66 +360,72 @@ struct lconv {                  /* Values in the "C" locale: */
     char    int_n_sign_posn;    /* CHAR_MAX */
 };
 .EE
-.IP
+.PP
 Contains members related to the formatting of numeric values.
 In the "C" locale, its members have the values
 shown in the comments above.
-.IP
+.PP
 Conforming to: C11 and later; POSIX.1-2001 and later.
-.IP
+.PP
 See also:
 .BR setlocale (3),
 .BR localeconv (3),
 .BR charsets (5),
 .BR locale (7)
+.RE
 .\"------------------------------------- ldiv_t -----------------------/
 .TP
 .I ldiv_t
-.IP
+.RS
+.PP
 Include:
 .IR <stdlib.h> .
-.IP
+.PP
 .EX
 typedef struct {
     long    quot; /* Quotient */
     long    rem;  /* Remainder */
 } ldiv_t;
 .EE
-.IP
+.PP
 It is the type of the value returned by the
 .BR ldiv (3)
 function.
-.IP
+.PP
 Conforming to: C99 and later; POSIX.1-2001 and later.
-.IP
+.PP
 See also:
 .BR ldiv (3)
+.RE
 .\"------------------------------------- lldiv_t ----------------------/
 .TP
 .I lldiv_t
-.IP
+.RS
+.PP
 Include:
 .IR <stdlib.h> .
-.IP
+.PP
 .EX
 typedef struct {
     long long   quot; /* Quotient */
     long long   rem;  /* Remainder */
 } lldiv_t;
 .EE
-.IP
+.PP
 It is the type of the value returned by the
 .BR lldiv (3)
 function.
-.IP
+.PP
 Conforming to: C99 and later; POSIX.1-2001 and later.
-.IP
+.PP
 See also:
 .BR lldiv (3)
+.RE
 .\"------------------------------------- pid_t ------------------------/
 .TP
 .I pid_t
-.IP
+.RS
+.PP
 Include
 .IR <sys/types.h> ;
 or
@@ -431,7 +452,7 @@ or
 .I <unistd.h>
 or
 .IR <utmpx.h> .
-.IP
+.PP
 This type is used for storing process IDs, process group IDs, and session IDs.
 According to POSIX, it shall be a signed integer type,
 and the implementation shall support one or more programming environments
@@ -439,9 +460,9 @@ where the width of
 .I pid_t
 is no greater than the width of the type
 .IR long .
-.IP
+.PP
 Conforming to: POSIX.1-2001 and later.
-.IP
+.PP
 See also:
 .BR fork (2),
 .BR getpid (2),
@@ -455,20 +476,22 @@ See also:
 .BR waitpid (2),
 .BR sigqueue (3),
 .BR credentials (7),
+.RE
 .\"------------------------------------- ptrdiff_t --------------------/
 .TP
 .I ptrdiff_t
-.IP
+.RS
+.PP
 Include:
 .IR <stddef.h> .
-.IP
+.PP
 Used for a count of elements, and array indices.
 It is the result of subtracting two pointers.
 According to the C language standard, it shall be a signed integer type
 capable of storing values in the range
 .RB [ PTRDIFF_MIN ,
 .BR PTRDIFF_MAX ].
-.IP
+.PP
 The length modifier for
 .I ptrdiff_t
 for the
@@ -484,21 +507,23 @@ or
 for printing
 .I ptrdiff_t
 values.
-.IP
+.PP
 Conforming to: C99 and later; POSIX.1-2001 and later.
-.IP
+.PP
 See also the
 .I size_t
 and
 .I ssize_t
 types in this page.
+.RE
 .\"------------------------------------- regmatch_t -------------------/
 .TP
 .I regmatch_t
-.IP
+.RS
+.PP
 Include:
 .IR <regex.h> .
-.IP
+.PP
 .EX
 typedef struct {
     regoff_t    rm_so; /* Byte offset from start of string
@@ -508,36 +533,38 @@ typedef struct {
                           substring */
 } regmatch_t;
 .EE
-.IP
+.PP
 This is a structure type used in regular expression matching.
-.IP
+.PP
 Conforming to: POSIX.1-2001 and later.
-.IP
+.PP
 See also:
 .BR regexec (3)
+.RE
 .\"------------------------------------- regoff_t ---------------------/
 .TP
 .I regoff_t
-.IP
+.RS
+.PP
 Include:
 .IR <regex.h> .
-.IP
+.PP
 According to POSIX, it shall be a signed integer type
 capable of storing the largest value that can be stored in either a
 .I ptrdiff_t
 type or a
 .I ssize_t
 type.
-.IP
+.PP
 Conforming to: POSIX.1-2001 and later.
-.IP
+.PP
 Notes: Prior to POSIX.1-2008, the type was capable of storing
 the largest value that can be stored in either an
 .I off_t
 type or a
 .I ssize_t
 type.
-.IP
+.PP
 See also the
 .I regmatch_t
 structure and the
@@ -545,10 +572,12 @@ structure and the
 and
 .I ssize_t
 types in this page.
+.RE
 .\"------------------------------------- sigevent ---------------------/
 .TP
 .I sigevent
-.IP
+.RS
+.PP
 Include:
 .IR <signal.h> ;
 or
@@ -557,7 +586,7 @@ or
 .I <mqueue.h>
 or
 .IR <time.h> .
-.IP
+.PP
 .EX
 struct sigevent {
     int             sigev_notify; /* Notification type */
@@ -569,12 +598,12 @@ struct sigevent {
                                   /* Notification attributes */
 };
 .EE
-.IP
+.PP
 For further details about this type, see
 .BR sigevent (7).
-.IP
+.PP
 Conforming to: POSIX.1-2001 and later.
-.IP
+.PP
 Notes:
 .I <aio.h>
 and
@@ -582,25 +611,27 @@ and
 define
 .I sigevent
 since POSIX.1-2008.
-.IP
+.PP
 See also:
 .BR timer_create (2),
 .BR getaddrinfo_a (3),
 .BR lio_listio (3),
 .BR mq_notify (3)
-.IP
+.PP
 See also the
 .I aiocb
 structure in this page.
+.RE
 .\"------------------------------------- siginfo_t --------------------/
 .TP
 .I siginfo_t
-.IP
+.RS
+.PP
 Include:
 .IR <signal.h> ;
 or
 .IR <sys/wait.h> .
-.IP
+.PP
 .EX
 typedef struct {
     int      si_signo;  /* Signal number */
@@ -612,36 +643,38 @@ typedef struct {
     union sigval si_value;  /* Signal value */
 } siginfo_t;
 .EE
-.IP
+.PP
 Information associated with a signal.
 For further details on this structure
 (including additional, Linux-specific fields), see
 .BR sigaction (2).
-.IP
+.PP
 Conforming to: POSIX.1-2001 and later.
-.IP
+.PP
 See also:
 .BR pidfd_send_signal (2),
 .BR rt_sigqueueinfo (2),
 .BR sigaction (2),
 .BR sigwaitinfo (2),
 .BR psiginfo (3)
+.RE
 .\"------------------------------------- sigset_t ---------------------/
 .TP
 .I sigset_t
-.IP
+.RS
+.PP
 Include:
 .IR <signal.h> ;
 or
 .I <spawn.h>
 or
 .IR <sys/select.h> .
-.IP
+.PP
 This is a type that represents a set of signals.
 According to POSIX, this shall be an integer or structure type.
-.IP
+.PP
 Conforming to: POSIX.1-2001 and later.
-.IP
+.PP
 See also:
 .BR epoll_pwait (2),
 .BR ppoll (2),
@@ -653,29 +686,31 @@ See also:
 .BR sigsuspend (2),
 .BR sigwaitinfo (2),
 .BR signal (7)
+.RE
 .\"------------------------------------- sigval -----------------------/
 .TP
 .I sigval
-.IP
+.RS
+.PP
 Include:
 .IR <signal.h> .
-.IP
+.PP
 .EX
 union sigval {
     int     sigval_int; /* Integer value */
     void   *sigval_ptr; /* Pointer value */
 };
 .EE
-.IP
+.PP
 Data passed with a signal.
-.IP
+.PP
 Conforming to: POSIX.1-2001 and later.
-.IP
+.PP
 See also:
 .BR pthread_sigqueue (3),
 .BR sigqueue (3),
 .BR sigevent (7)
-.IP
+.PP
 See also the
 .I sigevent
 structure
@@ -683,10 +718,12 @@ and the
 .I siginfo_t
 type
 in this page.
+.RE
 .\"------------------------------------- size_t -----------------------/
 .TP
 .I size_t
-.IP
+.RS
+.PP
 Include:
 .I <stddef.h>
 or
@@ -741,7 +778,7 @@ or
 .I <wchar.h>
 or
 .IR <wordexp.h> .
-.IP
+.PP
 Used for a count of bytes.  It is the result of the
 .I sizeof
 operator.
@@ -755,7 +792,7 @@ where the width of
 .I size_t
 is no greater than the width of the type
 .IR long .
-.IP
+.PP
 The length modifier for
 .I size_t
 for the
@@ -771,9 +808,9 @@ or
 for printing
 .I size_t
 values.
-.IP
+.PP
 Conforming to: C99 and later; POSIX.1-2001 and later.
-.IP
+.PP
 Notes:
 .IR <aio.h> ,
 .IR <glob.h> ,
@@ -787,7 +824,7 @@ and
 define
 .I size_t
 since POSIX.1-2008.
-.IP
+.PP
 See also:
 .BR read (2),
 .BR write (2),
@@ -798,16 +835,18 @@ See also:
 .BR memcpy (3),
 .BR memset (3),
 .BR offsetof (3)
-.IP
+.PP
 See also the
 .I ptrdiff_t
 and
 .I ssize_t
 types in this page.
+.RE
 .\"------------------------------------- ssize_t ----------------------/
 .TP
 .I ssize_t
-.IP
+.RS
+.PP
 Include:
 .IR <sys/types.h> ;
 or
@@ -826,7 +865,7 @@ or
 .I <sys/uio.h>
 or
 .IR <unistd.h> .
-.IP
+.PP
 Used for a count of bytes or an error indication.
 According to POSIX, it shall be a signed integer type
 capable of storing values at least in the range [-1,
@@ -836,7 +875,7 @@ where the width of
 .I ssize_t
 is no greater than the width of the type
 .IR long .
-.IP
+.PP
 Glibc and most other implementations provide a length modifier for
 .I ssize_t
 for the
@@ -862,9 +901,9 @@ by converting the value to
 .I intmax_t
 and using its length modifier
 .RB ( j ).
-.IP
+.PP
 Conforming to: POSIX.1-2001 and later.
-.IP
+.PP
 See also:
 .BR read (2),
 .BR readlink (2),
@@ -872,23 +911,25 @@ See also:
 .BR recv (2),
 .BR send (2),
 .BR write (2)
-.IP
+.PP
 See also the
 .I ptrdiff_t
 and
 .I size_t
 types in this page.
+.RE
 .\"------------------------------------- suseconds_t ------------------/
 .TP
 .I suseconds_t
-.IP
+.RS
+.PP
 Include:
 .IR <sys/types.h> ;
 or
 .I <sys/select.h>
 or
 .IR <sys/time.h> .
-.IP
+.PP
 Used for time in microseconds.
 According to POSIX, it shall be a signed integer type
 capable of storing values at least in the range [-1, 1000000],
@@ -897,16 +938,18 @@ where the width of
 .I suseconds_t
 is no greater than the width of the type
 .IR long .
-.IP
+.PP
 Conforming to: POSIX.1-2001 and later.
-.IP
+.PP
 See also the
 .I timeval
 structure in this page.
+.RE
 .\"------------------------------------- time_t -----------------------/
 .TP
 .I time_t
-.IP
+.RS
+.PP
 Include:
 .I <sys/types.h>
 or
@@ -927,48 +970,52 @@ or
 .I <sys/time.h>
 or
 .IR <utime.h> .
-.IP
+.PP
 Used for time in seconds.
 According to POSIX, it shall be an integer type.
-.IP
+.PP
 Conforming to: C99 and later; POSIX.1-2001 and later.
-.IP
+.PP
 Notes:
 .I <sched.h>
 defines
 .I time_t
 since POSIX.1-2008.
-.IP
+.PP
 See also:
 .BR stime (2),
 .BR time (2),
 .BR ctime (3),
 .BR difftime (3)
+.RE
 .\"------------------------------------- timer_t ----------------------/
 .TP
 .I timer_t
-.IP
+.RS
+.PP
 Include:
 .IR <sys/types.h> ;
 or
 .IR <time.h> .
-.IP
+.PP
 Used for timer ID returned by
 .BR timer_create (2).
 According to POSIX,
 there are no defined comparison or assignment operators for this type.
-.IP
+.PP
 Conforming to: POSIX.1-2001 and later.
-.IP
+.PP
 See also:
 .BR timer_create (2),
 .BR timer_delete (2),
 .BR timer_getoverrun (2),
 .BR timer_settime (2)
+.RE
 .\"------------------------------------- timespec ---------------------/
 .TP
 .I timespec
-.IP
+.RS
+.PP
 Include:
 .IR <time.h> ;
 or
@@ -983,28 +1030,30 @@ or
 .I <sys/select.h>
 or
 .IR <sys/stat.h> .
-.IP
+.PP
 .EX
 struct timespec {
     time_t  tv_sec;  /* Seconds */
     long    tv_nsec; /* Nanoseconds */
 };
 .EE
-.IP
+.PP
 Describes times in seconds and nanoseconds.
-.IP
+.PP
 Conforming to: C11 and later; POSIX.1-2001 and later.
-.IP
+.PP
 See also:
 .BR clock_gettime (2),
 .BR clock_nanosleep (2),
 .BR nanosleep (2),
 .BR timerfd_gettime (2),
 .BR timer_gettime (2)
+.RE
 .\"------------------------------------- timeval ----------------------/
 .TP
 .I timeval
-.IP
+.RS
+.PP
 Include:
 .IR <sys/time.h> ;
 or
@@ -1013,18 +1062,18 @@ or
 .I <sys/select.h>
 or
 .IR <utmpx.h> .
-.IP
+.PP
 .EX
 struct timeval {
     time_t      tv_sec;  /* Seconds */
     suseconds_t tv_usec; /* Microseconds */
 };
 .EE
-.IP
+.PP
 Describes times in seconds and microseconds.
-.IP
+.PP
 Conforming to: POSIX.1-2001 and later.
-.IP
+.PP
 See also:
 .BR gettimeofday (2),
 .BR select (2),
@@ -1032,10 +1081,12 @@ See also:
 .BR adjtime (3),
 .BR futimes (3),
 .BR timeradd (3)
+.RE
 .\"------------------------------------- uid_t ----------------------/
 .TP
 .I uid_t
-.IP
+.RS
+.PP
 Include:
 .IR <sys/types.h> ;
 or
@@ -1050,13 +1101,13 @@ or
 .I <sys/stat.h>
 or
 .IR <unistd.h> .
-.IP
+.PP
 A type used to hold user IDs.
 According to POSIX,
 this shall be an integer type.
-.IP
+.PP
 Conforming to: POSIX.1-2001 and later.
-.IP
+.PP
 See also:
 .BR chown (2),
 .BR getuid (2),
@@ -1064,6 +1115,8 @@ See also:
 .BR getresuid (2),
 .BR getpwnam (2),
 .BR credentials (7)
+.RE
+.\"--------------------------------------------------------------------/
 .SH NOTES
 The structures described in this manual page shall contain,
 at least, the members shown in their definition, in no particular order.
-- 
2.28.0

Re: [PATCH v2 2/2] system_data_types.7: srcfix

[Michael Kerrisk (man-pages)]

Hi Alex,

On 9/25/20 1:28 PM, Alejandro Colomar wrote:
> The contents of each type are a logic block that is indented as a block.
> They are not separate paragraphs that happen to be indented separately,
> but a set of continuous paragraphs, all in the same level,
> indented as a block from the list entry--the name of the type--.
> Therefore, it makes more sense to use block indentation, represented by
> .RS/.RE, rather than indenting each paragraph separately.
> That way it's also easier to further indent a separate paragraph inside
> a block, which happens for example in the case of float_t & double_t.
> It's simply much easier now to use .IP specifically in those cases where
> you want to indent just a single paragraph.
> 
> Also added an ending separator comment line just after the last type.
> 
> Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>

Patch applied. Thanks!

> ---
> 
> Hi Michael,
> 
> 
> On 2020-09-25 12:40, Michael Kerrisk (man-pages) wrote:
>> Just to confirm: I think I'm supposed to waiting on a revised
>> version of this patch, right? (This version of the patch doesn't
>> apply in my tree.)
>>
>> Thanks,
>>
>> Michael
> 
> Right.
> 
> It was somewhat complicated to fix the commits in the middle
> and rebase and then fix breakages and rebase again and fix more commits...
> I learned a lot of git today :)

:-}. Okay -- you can probably give me lessons!

Okay -- I declare a sync-point: as far as I know, I have nothing
outstanding from you. Let me know if I missed something.

Cheers,

Michael

-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Re: [PATCH v2 2/2] system_data_types.7: srcfix

[Alejandro Colomar]

Hi Michael,

On 2020-09-25 14:02, Michael Kerrisk (man-pages) wrote:
> Hi Alex,
>> I learned a lot of git today :)
> 
> :-}. Okay -- you can probably give me lessons!

:)

> 
> Okay -- I declare a sync-point: as far as I know, I have nothing
> outstanding from you. Let me know if I missed something.
> 
> Cheers,
> 
> Michael
> 


Yes, everything is synced.

Cheers,

Alex.

Re: [PATCH 1/2] system_data_types.7: srcfix

[G. Branden Robinson]

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

At 2020-09-25T10:03:30+0200, Alejandro Colomar wrote:
> @@ -454,7 +454,7 @@ Used for a count of elements, and array indices.
>  It is the result of subtracting two pointers.
>  According to the C language standard, it shall be a signed integer type
>  capable of storing values in the range
> -.BR "" [ PTRDIFF_MIN ,
> +.RB [ PTRDIFF_MIN ,
>  .BR PTRDIFF_MAX ].
>  .IP
>  The length modifier for

Ooh, thanks for that.  The deleted line is a terrible anti-pattern and
you're doing everyone a solid by removing the temptation to copy it.

groff_man_style(7) attempts to lead people to the light:

 Optional macro arguments are indicated by surrounding them with square
 brackets.  If a macro accepts multiple arguments, those containing
 space characters must be double-quoted to be interpreted correctly.  An
 empty macro argument can be specified with a pair of double-quotes
 (“""”), but the man package is designed such that this should seldom be
 necessary.  Unused macro arguments are more often simply omitted, or
 good style suggests that a more appropriate macro be chosen, that ear‐
 lier arguments are more important than later ones, or that arguments
 have identical significance such that skipping any is superfluous.

...but alas, groff 1.22.5, or 1.23 or whatever we call it, is not yet
released.

Regards,
Branden

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

Re: [PATCH 1/2] system_data_types.7: srcfix

[Alejandro Colomar]

Hi Branden,

On 2020-09-27 08:10, G. Branden Robinson wrote:
 > At 2020-09-25T10:03:30+0200, Alejandro Colomar wrote:
 >> @@ -454,7 +454,7 @@ Used for a count of elements, and array indices.
 >>   It is the result of subtracting two pointers.
 >>   According to the C language standard, it shall be a signed integer 
type
 >>   capable of storing values in the range
 >> -.BR "" [ PTRDIFF_MIN ,
 >> +.RB [ PTRDIFF_MIN ,
 >>   .BR PTRDIFF_MAX ].
 >>   .IP
 >>   The length modifier for
 >
 > Ooh, thanks for that.  The deleted line is a terrible anti-pattern and
 > you're doing everyone a solid by removing the temptation to copy it.

Yup, I introduced that line a few patches ago because
I didn't know .RB existed :)

BTW, thanks for all your comments.
Thanks to them I improved the style in system_data_types.7,
which I started a few weeks ago.

Thanks,

Alex

 >
 > groff_man_style(7) attempts to lead people to the light:
 >
 >   Optional macro arguments are indicated by surrounding them with square
 >   brackets.  If a macro accepts multiple arguments, those containing
 >   space characters must be double-quoted to be interpreted correctly.  An
 >   empty macro argument can be specified with a pair of double-quotes
 >   (“""”), but the man package is designed such that this should seldom be
 >   necessary.  Unused macro arguments are more often simply omitted, or
 >   good style suggests that a more appropriate macro be chosen, that ear‐
 >   lier arguments are more important than later ones, or that arguments
 >   have identical significance such that skipping any is superfluous.
 >
 > ...but alas, groff 1.22.5, or 1.23 or whatever we call it, is not yet
 > released.
 >
 > Regards,
 > Branden
 >

Re: [PATCH 1/2] system_data_types.7: srcfix

[G. Branden Robinson]

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

At 2020-09-27T22:24:19+0200, Alejandro Colomar wrote:
> Yup, I introduced that line a few patches ago because
> I didn't know .RB existed :)

At the risk of being the sort of tedious jerk who promotes is own work,
I recommend the table at the beginning of groff_man(7)[1], which can
serve almost as a quick-reference card for the macro package.

> BTW, thanks for all your comments.
> Thanks to them I improved the style in system_data_types.7,
> which I started a few weeks ago.

I've noticed!  I'm subscribed to the list and I think your efforts have
tripled the average monthly traffic. :D

But it's a good thing.  Section 7 of the manual is criminally underused,
and data types have long been badly neglected in documentation, with
functions sucking up all the oxygen.  In my opinion, every
externally-visible symbol a library exposes should be documented.

Regards,
Branden

[1] https://man7.org/linux/man-pages/man7/groff_man.7.html

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

Re: [PATCH 1/2] system_data_types.7: srcfix

[Jakub Wilk]

Hi Branden!

In groff_man_style(7) you wrote:
>Unused macro arguments are more often simply omitted, or good style 
>suggests that a more appropriate macro be chosen, that earlier 
>arguments are more important than later ones, or that arguments have 
>identical significance such that skipping any is superfluous.

After 15 minutes of gawking at this sentence, I still don't understand 
what are you trying to say here. The sentence should be either 
thoroughly rephrased or removed.

-- 
Jakub Wilk

Re: [PATCH 1/2] system_data_types.7: srcfix

[G. Branden Robinson]

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

At 2020-09-28T15:29:59+0200, Jakub Wilk wrote:
> Hi Branden!
> 
> In groff_man_style(7) you wrote:
> > Unused macro arguments are more often simply omitted, or good style
> > suggests that a more appropriate macro be chosen, that earlier
> > arguments are more important than later ones, or that arguments have
> > identical significance such that skipping any is superfluous.
> 
> After 15 minutes of gawking at this sentence, I still don't understand
> what are you trying to say here. The sentence should be either
> thoroughly rephrased or removed.

<laugh>  Oh, dear.

The page source is interleaved with comments that illustrate
anti-patterns.  You'll see that the second case is of the kind that Alex
just fixed.

Unused macro arguments are more often simply omitted,
.\" antipattern: '.TP ""' (just '.TP' will do)
or good style suggests that a more appropriate macro be chosen,
.\" antipattern: '.BI "" italic bold' (use '.IB' instead)
that earlier arguments are more important than later ones,
.\" antipattern: '.TH foo 1 "" "foo 1.2.3"' (don't skip the date!)
.\" antipattern: '.IP "" 4n' (use .TP or .RS/.RE, depending on needs)
or that arguments have identical significance such that skipping any is
superfluous.
.\" antipattern: '.B one two "" three' (pointless)
.\"   Technically, the above has a side-effect of additional space
.\"   between "two" and "three", but there are much more obvious ways of
.\"   getting it if desired.
.\"     .B "one two  three"
.\"     .B one "two " three
.\"     .B one two " three"
.\"     .B one two\~ three

I think that paragraph started life before I split off the
groff_man_style(7) page, and I was trying to keep things terse for the
benefit of people who wanted groff_man(7) to stay short.

The page is no longer being pulled in two directions, so I think this
material can be expanded out into real examples now.

I should probably move it later in the page, after the macros have been
fully introduced, and put a forward reference to it in the current
location.

Thanks for the critique.

With chagrinned regards,
Branden

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

Re: [PATCH 1/2] system_data_types.7: srcfix

[Michael Kerrisk (man-pages)]

On 9/28/20 3:29 PM, Jakub Wilk wrote:
> Hi Branden!
> 
> In groff_man_style(7) you wrote:
>> Unused macro arguments are more often simply omitted, or good style 
>> suggests that a more appropriate macro be chosen, that earlier 
>> arguments are more important than later ones, or that arguments have 
>> identical significance such that skipping any is superfluous.
> 
> After 15 minutes of gawking at this sentence, I still don't understand 
> what are you trying to say here. The sentence should be either 
> thoroughly rephrased or removed.

I must say that I too found it hard to parse. I presume, Branden,
that you mean:

[[
Unused macro arguments are more often simply omitted, or good style 
suggests
EITHER (1) 
that a more appropriate macro be chosen, 
(2)
that earlier arguments are more important than later ones, or
(3)
that arguments have 
identical significance such that skipping any is superfluous.
]]

But it takes a few scans to work that out. Perhaps break 
this into smaller pieces, or add some explicit structuring
elements to the sentence?

Thanks,

Michael


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Re: [PATCH 1/2] system_data_types.7: srcfix

[G. Branden Robinson]

[-- Attachment #1.1: Type: text/plain, Size: 1776 bytes --]

Hi Jakub and Michael,

At 2020-09-29T14:13:26+0200, Michael Kerrisk (man-pages) wrote:
> On 9/28/20 3:29 PM, Jakub Wilk wrote:
> > Hi Branden!
> > 
> > In groff_man_style(7) you wrote:
> >> Unused macro arguments are more often simply omitted, or good style
> >> suggests that a more appropriate macro be chosen, that earlier
> >> arguments are more important than later ones, or that arguments
> >> have identical significance such that skipping any is superfluous.
> > 
> > After 15 minutes of gawking at this sentence, I still don't
> > understand what are you trying to say here. The sentence should be
> > either thoroughly rephrased or removed.
> 
> I must say that I too found it hard to parse. I presume, Branden,
> that you mean:
> 
> [[
> Unused macro arguments are more often simply omitted, or good style 
> suggests
> EITHER (1) 
> that a more appropriate macro be chosen, 
> (2)
> that earlier arguments are more important than later ones, or
> (3)
> that arguments have 
> identical significance such that skipping any is superfluous.
> ]]

You got it.  But it was too much work.

> But it takes a few scans to work that out. Perhaps break this into
> smaller pieces, or add some explicit structuring elements to the
> sentence?

I was trying to be comprehensive with respect to several anti-patterns I
had in mind.  However, using the anti-patterns concretely is premature
at that point in the page.  So I both expanded and relocated the
material.

I'm attaching what I've just committed to groff git.

Further feedback is welcome, of course; revision of documentation is a
process that is never completed, only abandoned.  And I haven't given up
yet.  :)

Thank you both for your reviews.

Regards,
Branden

[-- Attachment #1.2: excise_standardese.diff --]
[-- Type: text/x-diff, Size: 3858 bytes --]

commit dd2c4cf05a659ae7127e342924668ff0fa0deaa1
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
Date:   Wed Sep 30 19:56:38 2020 +1000

    groff_man_style(7): Clarify empty macro arguments.
    
    Rewrite some ersatz standardese I had managed to concoct regarding why
    empty macro arguments are usually not needed.  Put an expanded
    discussion, with anti-patterns and remedies, in section "Notes", with
    forward reference from subsection "Macro reference preliminaries".
    
    Thanks to Jakub Wilk and Michael Kerrisk for the critique.

diff --git a/tmac/groff_man.7.man.in b/tmac/groff_man.7.man.in
index c62d97ba..b96cbaf4 100644
--- a/tmac/groff_man.7.man.in
+++ b/tmac/groff_man.7.man.in
@@ -281,23 +281,8 @@ but the
 package is designed such that this should seldom be necessary.
 _ifstyle()dnl
 .
-Unused macro arguments are more often simply omitted,
-.\" antipattern: '.TP ""' (just '.TP' will do)
-or good style suggests that a more appropriate macro be chosen,
-.\" antipattern: '.BI "" italic bold' (use '.IB' instead)
-that earlier arguments are more important than later ones,
-.\" antipattern: '.TH foo 1 "" "foo "1.2.3"' (don't skip the date!)
-.\" antipattern: '.IP "" 4n' (use .TP or .RS/.RE, depending on needs)
-or that arguments have identical significance such that skipping any is
-superfluous.
-.\" antipattern: '.B one two "" three' (pointless)
-.\"   Technically, the above has a side-effect of additional space
-.\"   between "two" and "three", but there are much more obvious ways of
-.\"   getting it if desired.
-.\"     .B "one two  three"
-.\"     .B one "two " three
-.\"     .B one two " three"
-.\"     .B one two\~ three
+See section \(lqNotes\(rq below for examples of cases where better
+alternatives to empty arguments in macro calls are available.
 _endif()dnl
 .
 Most macro arguments are strings that will be output as text;
@@ -3235,6 +3220,63 @@ Some tips on troubleshooting your man pages follow.
 .
 .
 .TP
+\(bu Do I ever need to use an empty macro argument ("")?
+Probably not.
+.
+When this seems necessary,
+often a shorter or clearer alternative is available.
+.
+.\" antipattern: '.TP ""' (just '.TP' will do)
+.\" antipattern: '.BI "" italic bold' (use '.IB' instead)
+.\" antipattern: '.TH foo 1 "" "foo 1.2.3"' (don't skip the date!)
+.\" antipattern: '.IP "" 4n' (use .TP or .RS/.RE, depending on needs)
+.\" antipattern: '.B one two "" three' (pointless)
+.\"   Technically, the above has a side-effect of additional space
+.\"   between "two" and "three", but there are much more obvious ways of
+.\"   getting it if desired.
+.\"     .B "one two  three"
+.\"     .B one "two " three
+.\"     .B one two " three"
+.\"     .B one two\~ three
+.TS
+c c
+lfCB lfCB.
+Instead of.\|.\.	.\|.\|.do this.
+_
+\&.TP \(dq\(dq	.TP
+\&.BI \(dq\(dq italic-text bold-text	.IB italic-text bold-text
+\&.TH foo 1 \(dq\(dq \(dqfoo 1.2.3\(dq	.TH foo 1 \
+\f(CIyyyy\fP-\f(CImm\fP-\f(CIdd\fP \(dqfoo 1.2.3\(dq
+\&.IP \(dq\(dq 4n	.TP 4n
+\&.B one two \(dq\(dq three	.B one two three
+.TE
+.
+.
+.IP
+In the title heading
+.RB ( .TH ),
+the date of the page's last revision is more important than packaging
+information;
+it should not be omitted.
+.
+Ideally,
+a page maintainer will keep both up to date.
+.
+.
+.IP
+In the last example,
+the empty argument does have a subtly different effect than its
+suggested replacement;
+the empty argument becomes an additional space character\(embut it is a
+regular breaking space,
+so it can be discarded at the end of an output line.
+.
+It is better not to be subtle,
+particularly with space,
+which can be overlooked in source and rendered forms.
+.
+.
+.TP
 .RB \(bu " .RS" " doesn't indent relative to my indented paragraph"
 The
 .B .RS

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

Re: [PATCH 1/2] system_data_types.7: srcfix

[Jakub Wilk]

* G. Branden Robinson <g.branden.robinson@gmail.com>, 2020-09-30 20:12:
>+\(bu Do I ever need to use an empty macro argument ("")?
>+Probably not.

FWIW, man-pages(7) says it's OK to use empty string for the 4th 
argument of .TH:

"For library calls that are part of glibc or one of the other common GNU 
libraries, just use GNU C Library, GNU, or an empty string."

There used to be a lot of such .TH calls; now there's only a few left:

$ grep -r '[.]TH .*""' man*/
man7/posixoptions.7:.TH POSIXOPTIONS 7 2021-08-27 "" "Linux Programmer's Manual"
man7/bpf-helpers.7:.TH BPF-HELPERS 7 "" "" ""
man8/zdump.8:.TH ZDUMP 8 2020-04-27 "" "Linux System Administration"
man8/zic.8:.TH ZIC 8 2020-08-13 "" "Linux System Administration"

-- 
Jakub Wilk

Re: [PATCH 1/2] system_data_types.7: srcfix

[Alejandro Colomar]

Hi Jakub,

On 8/19/22 20:03, Jakub Wilk wrote:
> * G. Branden Robinson <g.branden.robinson@gmail.com>, 2020-09-30 20:12:
>> +\(bu Do I ever need to use an empty macro argument ("")?
>> +Probably not.
> 
> FWIW, man-pages(7) says it's OK to use empty string for the 4th argument 
> of .TH:
> 
> "For library calls that are part of glibc or one of the other common GNU 
> libraries, just use GNU C Library, GNU, or an empty string."
> 
> There used to be a lot of such .TH calls; now there's only a few left:

Yeah, I fixed most of them to silence a warning, IIRC.

The below, I couldn't fix them for 2 different reasons.

In posixoptions(7), I don't know what to use.  POSIX?

The other pages are taken from other projects; we don't maintain them:

$ cat MAINTAINER_NOTES
Externally generated pages
==========================

A few pages come from external sources. Fixes to the pages should really
go to the upstream source.

tzfile(5), zdump(8), and zic(8) come from the tz project
(https://www.iana.org/time-zones).

bpf-helpers(7) is autogenerated from the kernel sources using scripts.
See man-pages commits 53666f6c3 and 19c7f7839 for details.


> 
> $ grep -r '[.]TH .*""' man*/
> man7/posixoptions.7:.TH POSIXOPTIONS 7 2021-08-27 "" "Linux Programmer's 
> Manual"
> man7/bpf-helpers.7:.TH BPF-HELPERS 7 "" "" ""
> man8/zdump.8:.TH ZDUMP 8 2020-04-27 "" "Linux System Administration"
> man8/zic.8:.TH ZIC 8 2020-08-13 "" "Linux System Administration"
> 


Cheers,

Alex

Re: [PATCH 1/2] system_data_types.7: srcfix

[G. Branden Robinson]

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

At 2022-08-19T20:03:23+0200, Jakub Wilk wrote:
> * G. Branden Robinson <g.branden.robinson@gmail.com>, 2020-09-30 20:12:
> > +\(bu Do I ever need to use an empty macro argument ("")?
> > +Probably not.
> 
> FWIW, man-pages(7) says it's OK to use empty string for the 4th
> argument of .TH:
> 
> "For library calls that are part of glibc or one of the other common
> GNU libraries, just use GNU C Library, GNU, or an empty string."
> 
> There used to be a lot of such .TH calls; now there's only a few left:

In my opinion it would benefit readers of the Linux man-pages if the
fourth argument to `TH` were what it is in many other man pages: an
identifier for the name and version number of the release originating
them.  In every page it would be clear what version of the man-pages was
being viewed.  Little sophistication would be demanded of the user to
check the Web to determine the relative age of the pages, independently
of the modification date of the particular page.  Such usage would be
congruent with the argument's purpose in AT&T and BSD Unix, where this
datum was "7th Edition", "System III", or "4.2 Berkeley Distribution",
or similar.

Further, as the libc-related man pages in this project expand coverage
to other libcs than GNU's, the alternatives to the empty string
proferred in man-pages(7) seem less and less appropriate.

> $ grep -r '[.]TH .*""' man*/
> man7/posixoptions.7:.TH POSIXOPTIONS 7 2021-08-27 "" "Linux Programmer's Manual"
> man7/bpf-helpers.7:.TH BPF-HELPERS 7 "" "" ""
> man8/zdump.8:.TH ZDUMP 8 2020-04-27 "" "Linux System Administration"
> man8/zic.8:.TH ZIC 8 2020-08-13 "" "Linux System Administration"

The replacement fifth arguments above seem pointless, and in the case of
bpf-helpers(7), downright unhelpful.

       .TH title section [footer‐middle] [footer‐inside] [header‐middle]
[...]
              If section is a simple integer between 1 and 9
              (inclusive), there is no need to specify header‐middle;
              an.tmac will supply text for it.

However, I realize that bpf-helpers(7) is generated from another format,
and so code would have to be written to more usefully populate 2 of the
3 blank fields.  (I would leave the third unspecified instead of making
it explicitly empty.)

Regards,
Branden

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

.TH 4th field (Was: [PATCH 1/2] system_data_types.7: srcfix)

[Alejandro Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 5206 bytes --]

Hi Branden,

On 8/20/22 07:43, G. Branden Robinson wrote:
> At 2022-08-19T20:03:23+0200, Jakub Wilk wrote:
>> * G. Branden Robinson <g.branden.robinson@gmail.com>, 2020-09-30 20:12:
>>> +\(bu Do I ever need to use an empty macro argument ("")?
>>> +Probably not.
>>
>> FWIW, man-pages(7) says it's OK to use empty string for the 4th
>> argument of .TH:
>>
>> "For library calls that are part of glibc or one of the other common
>> GNU libraries, just use GNU C Library, GNU, or an empty string."
>>
>> There used to be a lot of such .TH calls; now there's only a few left:
> 
> In my opinion it would benefit readers of the Linux man-pages if the
> fourth argument to `TH` were what it is in many other man pages: an
> identifier for the name and version number of the release originating
> them.  In every page it would be clear what version of the man-pages was
> being viewed.  Little sophistication would be demanded of the user to
> check the Web to determine the relative age of the pages, independently
> of the modification date of the particular page.  Such usage would be
> congruent with the argument's purpose in AT&T and BSD Unix, where this
> datum was "7th Edition", "System III", or "4.2 Berkeley Distribution",
> or similar.

I thought about it in the past...  That field was the only thing that 
said where a function came from.  If we removed GNU (or something else), 
how would someone know where does the function or whatever comes from??

I guess that's also why the colophon was appended to the pages by 
Michael.  Since we couldn't use the 4th field for that, we had to have a 
COLOPHON section.

However, the addition of the LIBRARY section seems to fix this issue, 
and so now we have an even more precise way to determine where a given 
function comes from (including the library file name, and the linker 
option).

This gives me another argument for those who don't like to have a 
LIBRARY section for libc stuff (since -lc is unnecessary), and consider 
it noise.

> 
> Further, as the libc-related man pages in this project expand coverage
> to other libcs than GNU's, the alternatives to the empty string
> proferred in man-pages(7) seem less and less appropriate.

Agree.  LIBRARY seems much more appropriate for that purpose.

And this helps remove the COLOPHON section (or at least, we don't need 
to autogenerate it, since the version number now comes in .TH, and the 
COLOPHON is static; so I can even move it to a smaller REPORTING BUGS 
section).

> 
>> $ grep -r '[.]TH .*""' man*/
>> man7/posixoptions.7:.TH POSIXOPTIONS 7 2021-08-27 "" "Linux Programmer's Manual"
>> man7/bpf-helpers.7:.TH BPF-HELPERS 7 "" "" ""
>> man8/zdump.8:.TH ZDUMP 8 2020-04-27 "" "Linux System Administration"
>> man8/zic.8:.TH ZIC 8 2020-08-13 "" "Linux System Administration"
> 
> The replacement fifth arguments above seem pointless, and in the case of
> bpf-helpers(7), downright unhelpful.
> 
>         .TH title section [footer‐middle] [footer‐inside] [header‐middle]
> [...]
>                If section is a simple integer between 1 and 9
>                (inclusive), there is no need to specify header‐middle;
>                an.tmac will supply text for it.
> 
> However, I realize that bpf-helpers(7) is generated from another format,
> and so code would have to be written to more usefully populate 2 of the
> 3 blank fields.  (I would leave the third unspecified instead of making
> it explicitly empty.)

For the date, I already reported a bug to rst2man(1).  For the 4th 
field, I guess we should specify Linux kernel and version (so I should 
patch the kernel to pass that info to us).


Now that I'm convinced to fix the 4th argument as something like "Linux 
man-pages 5.13" for all pages, I'd like you to help on this.

The script for replacing them all was easy.  I produced the following 
temporary commit in my tree:

     All pages: Replace the 4th argument to .TH by "Linux man-pages 
<version>"

     Scripted change:

     $ find man* -type f \
       |xargs sed -i '/^.TH /s/\(.TH \+[^ ]\+ \+[^ ]\+ \+[^ ]\+\) 
\+"[^"]\+"/\1 "Linux man-pages 5.13"/'

     $ find man* -type f \
       |xargs sed -i '/^.TH /s/\(.TH \+[^ ]\+ \+[^ ]\+ \+[^ ]\+\) \+[^" 
]\+/\1 "Linux man-pages 5.13"/'

     Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>


Now, we should decide what to put exactly in that field, and when/how to 
generate it.

The project name, I think it's clear that it should be "Linux man-pages" 
(are there any voices against?).  As the version, for releases it also 
seems clear: the version number; but what about unreleased pages?should 
I write a generic placeholder?  Or maybe keep the last version number? 
Or maybe put the expected next version number (that's risky).  Or put 
the git version (i.e., man-pages-5.19-rc1-173-g6620898d3)?  The git 
version would be the most precise, but it's also the most complex to do: 
I'd need to modify the _installed_ pages, since of course I'm not going 
to edit the original pages with that info.

Cheers,

Alex
-- 
Alejandro Colomar
<http://www.alejandro-colomar.es/>

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

Re: .TH 4th field (Was: [PATCH 1/2] system_data_types.7: srcfix)

[G. Branden Robinson]

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

Hi Alex!

At 2022-08-20T13:57:15+0200, Alejandro Colomar wrote:
[migrating `TH` 4th argument to something like "Linux man-pages 5.13"]
> I thought about it in the past...  That field was the only thing that
> said where a function came from.  If we removed GNU (or something
> else), how would someone know where does the function or whatever
> comes from??
> 
> I guess that's also why the colophon was appended to the pages by
> Michael.  Since we couldn't use the 4th field for that, we had to have
> a COLOPHON section.
> 
> However, the addition of the LIBRARY section seems to fix this issue,
> and so now we have an even more precise way to determine where a given
> function comes from (including the library file name, and the linker
> option).
> 
> This gives me another argument for those who don't like to have a
> LIBRARY section for libc stuff (since -lc is unnecessary), and
> consider it noise.
>
> > Further, as the libc-related man pages in this project expand
> > coverage to other libcs than GNU's, the alternatives to the empty
> > string proferred in man-pages(7) seem less and less appropriate.
> 
> Agree.  LIBRARY seems much more appropriate for that purpose.

Yes.  I endorse the above reasoning.

> For the date, I already reported a bug to rst2man(1).  For the 4th
> field, I guess we should specify Linux kernel and version (so I should
> patch the kernel to pass that info to us).

Maybe the glory of seeing "Linux 6.0" in the footer of the bpf-helpers
man page will inspire more kernel developers to follow that page's
example.

> Now that I'm convinced to fix the 4th argument as something like "Linux
> man-pages 5.13" for all pages, I'd like you to help on this.
> 
> The script for replacing them all was easy.  I produced the following
> temporary commit in my tree:
> 
>     All pages: Replace the 4th argument to .TH by "Linux man-pages
> <version>"
> 
>     Scripted change:
> 
>     $ find man* -type f \
>       |xargs sed -i '/^.TH /s/\(.TH \+[^ ]\+ \+[^ ]\+ \+[^ ]\+\)
> \+"[^"]\+"/\1 "Linux man-pages 5.13"/'
> 
>     $ find man* -type f \
>       |xargs sed -i '/^.TH /s/\(.TH \+[^ ]\+ \+[^ ]\+ \+[^ ]\+\) \+[^"
> ]\+/\1 "Linux man-pages 5.13"/'
> 
>     Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>

Looks reasonable to me, at a glace.

> Now, we should decide what to put exactly in that field, and when/how to
> generate it.
> 
> The project name, I think it's clear that it should be "Linux man-pages"
> (are there any voices against?).

You've got a license named for you in SPDX now--you're stuck with it. ;)

> As the version, for releases it also seems clear: the version number;
> but what about unreleased pages?should I write a generic placeholder?
> Or maybe keep the last version number? Or maybe put the expected next
> version number (that's risky).  Or put the git version (i.e.,
> man-pages-5.19-rc1-173-g6620898d3)?  The git version would be the most
> precise, but it's also the most complex to do: I'd need to modify the
> _installed_ pages, since of course I'm not going to edit the original
> pages with that info.

I would add " (in preparation)" to the string, and have the script that
finalizes a release strip that out.

But even if you go with the garrulous output of "git describe", I have
good news.  In groff 1.23, overlong header and footer material is
abbreviated with an ellipsis.  (This was an educational experience in
string processing with groff.)

Regards,
Branden

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

Re: .TH 4th field (Was: [PATCH 1/2] system_data_types.7: srcfix)

[Alejandro Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 3902 bytes --]

Hi Branden,

On 8/20/22 14:20, G. Branden Robinson wrote:
> Hi Alex!
> 
> At 2022-08-20T13:57:15+0200, Alejandro Colomar wrote:
> [migrating `TH` 4th argument to something like "Linux man-pages 5.13"]

[...]

>>
>> Agree.  LIBRARY seems much more appropriate for that purpose.
> 
> Yes.  I endorse the above reasoning.

Great.  I'll get rid of the scripts for appending a COLOPHON.

Should I keep the static part of the COLOPHON in a REPORTING BUGS section?

And an even more general question?  Should a manual page state the 
COPYRIGHT, AUTHORS, and REPORTING BUGS of the software it documents, or 
of the page itself, or both?

Ingo, I'm also interested in hearing you about this.

> 
>> For the date, I already reported a bug to rst2man(1).  For the 4th
>> field, I guess we should specify Linux kernel and version (so I should
>> patch the kernel to pass that info to us).
> 
> Maybe the glory of seeing "Linux 6.0" in the footer of the bpf-helpers
> man page will inspire more kernel developers to follow that page's
> example.

That could help! :)

Maybe we will see a future man9 section, even if autogenerated.

> 
>> Now that I'm convinced to fix the 4th argument as something like "Linux
>> man-pages 5.13" for all pages, I'd like you to help on this.
>>
>> The script for replacing them all was easy.  I produced the following
>> temporary commit in my tree:
>>
>>      All pages: Replace the 4th argument to .TH by "Linux man-pages
>> <version>"
>>
>>      Scripted change:
>>
>>      $ find man* -type f \
>>        |xargs sed -i '/^.TH /s/\(.TH \+[^ ]\+ \+[^ ]\+ \+[^ ]\+\)
>> \+"[^"]\+"/\1 "Linux man-pages 5.13"/'
>>
>>      $ find man* -type f \
>>        |xargs sed -i '/^.TH /s/\(.TH \+[^ ]\+ \+[^ ]\+ \+[^ ]\+\) \+[^"
>> ]\+/\1 "Linux man-pages 5.13"/'
>>
>>      Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
> 
> Looks reasonable to me, at a glace.
> 
>> Now, we should decide what to put exactly in that field, and when/how to
>> generate it.
>>
>> The project name, I think it's clear that it should be "Linux man-pages"
>> (are there any voices against?).
> 
> You've got a license named for you in SPDX now--you're stuck with it. ;)

;)

> 
>> As the version, for releases it also seems clear: the version number;
>> but what about unreleased pages?should I write a generic placeholder?
>> Or maybe keep the last version number? Or maybe put the expected next
>> version number (that's risky).  Or put the git version (i.e.,
>> man-pages-5.19-rc1-173-g6620898d3)?  The git version would be the most
>> precise, but it's also the most complex to do: I'd need to modify the
>> _installed_ pages, since of course I'm not going to edit the original
>> pages with that info.
> 
> I would add " (in preparation)" to the string, and have the script that
> finalizes a release strip that out.

I'll use "Linux man-pages (unreleased)" for the repo pages, just to be 
more similar to Debian's changelog format.  I don't like inventing stuff 
if I don't need to.  Does it make sense to you?

Having a fixed string there will be good, since that way I won't disturb 
the script updating the last-modified date.

> 
> But even if you go with the garrulous output of "git describe", I have
> good news.  In groff 1.23, overlong header and footer material is
> abbreviated with an ellipsis.  (This was an educational experience in
> string processing with groff.)

Don't you like git-describe(1)?  I like it.  I'll check if it fits a 
normal terminal, and if so, I think I'll use it.  If not, I'll think 
about it a bit more.


So, I'll have the Makefile produce this stuff, for both `make install` 
and `make dist`, and it will be produced in generated pages, but never 
modify repo ones.

Cheers,

Alex


-- 
Alejandro Colomar
<http://www.alejandro-colomar.es/>

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

Re: .TH 4th field (Was: [PATCH 1/2] system_data_types.7: srcfix)

[Alejandro Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 1305 bytes --]

Hi Branden,

On 8/20/22 14:40, Alejandro Colomar wrote:
> Hi Branden,
> 
> On 8/20/22 14:20, G. Branden Robinson wrote:
[...]
>> I would add " (in preparation)" to the string, and have the script that
>> finalizes a release strip that out.
> 
> I'll use "Linux man-pages (unreleased)" for the repo pages, just to be 
> more similar to Debian's changelog format.  I don't like inventing stuff 
> if I don't need to.  Does it make sense to you?
> 
> Having a fixed string there will be good, since that way I won't disturb 
> the script updating the last-modified date.

I think this will be the definitive commit:


     All pages: Replace the 4th argument to .TH by "Linux man-pages 
<version>"

     Scripted change:

     $ find man* -type f \
       |xargs sed -Ei '/^.TH /s/(.TH +[^ ]+ +[^ ]+ +[^ ]+) +"[^"]*"/\1 
"Linux man-pages (unreleased)"/'

     $ find man* -type f \
       |xargs sed -Ei '/^.TH /s/(.TH +[^ ]+ +[^ ]+ +[^ ]+) +[^" ]+/\1 
"Linux man-pages (unreleased)"/'

     $ git restore man5/tzfile.5
     $ git restore man8/zdump.8
     $ git restore man8/zic.8
     $ git restore man7/bpf-helpers.7

     Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>


Cheers,

Alex

-- 
Alejandro Colomar
<http://www.alejandro-colomar.es/>

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

Re: .TH 4th field (Was: [PATCH 1/2] system_data_types.7: srcfix)

[Alejandro Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 603 bytes --]

On 8/20/22 14:40, Alejandro Colomar wrote:
> So, I'll have the Makefile produce this stuff, for both `make install` 
> and `make dist`, and it will be produced in generated pages, but never 
> modify repo ones.

Nah, I'll keep 'make install' simple, so it'll keep the '(unreleased)' 
watermark.  So if someone installs from git, they'll have 
'(unreleased)'.  However, the tarballs will have the git-describe(1) 
version from which they were generated, and so a `make install` from a 
tarball will be different.

Cheers,

Alex

-- 
Alejandro Colomar
<http://www.alejandro-colomar.es/>

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

Re: .TH 4th field (Was: [PATCH 1/2] system_data_types.7: srcfix)

[Ingo Schwarze]

Hi Alejandro,

Alejandro Colomar wrote on Sat, Aug 20, 2022 at 02:40:58PM +0200:

> Should I keep the static part of the COLOPHON in a REPORTING BUGS section?

I do not think a manual page should include *any* boilerplate text.
Text that is the same everywhere is nothing but a distraction
and a waste of screen real estate.

> And an even more general question?  Should a manual page state the 
> COPYRIGHT,

No, it should *not* state any Copyright in the *formatted* text.
Every file should contain a Copyright and license header at the top
as a comment though: in a manual page file, .\" stating the Coypright
and license of that particular manual page, in a program source file,
/* */ stating the Coypright and license of that particular source file.

Manual pages are for users who want to use the program or function.
For merely using it, they do not need to consider *any* Copyright or
license, at least as long as it is more or less free software.

Stating the Copyright and license matters for packagers and for
developers or companies who consider copying parts of files for their
own projects, and those people are used to looking at source files.

> AUTHORS,

Mentioning the main AUTHORS of the original implementation of the program -
for example, Robert Morris and Lorinda Cherry for bc(1) - and also
mentioning the main AUTHORS of your current implementation, if it
was rewritten from scratch, seems most important to me.

Mentioning the AUTHORS of the manual page seems much less relevant
to me, and it is usually omitted.  Mentioning them is not wrong, though,
and it some cases, it can be interesting.  For example, some programs
used to be notorious for not having any manual page whatsoever until
some Debian developers - who were not even associated with the projects
maintaining those programs - took pity and wrote a manual page.
Crediting those brave souls feels fair to me, just as an example.

If you mention people who wrote the manual but did not contribute
significantly to the program itself, be explicit that they wrote
the manual page.

> and REPORTING BUGS of the software it documents, or 
> of the page itself, or both?

Any REPORTING BUGS section feels like a bad idea to me - see above
regarding boilerplate text.

Besides, if a user is unable to use whatever package manager they
have, inspect which package the program they are using (and its
manual page) belong to, and inspect the project website how to
properly report a bug, would you really expect a useful bug report?
I certainly wouldn't.  So not having a REPORTING BUGS section
will discourage only extremely clueless users, whereas having one
will likely annoy anyone of even minimal competence.

On top of that, i have often seen bug reporting instructions in
manual pages that were literally several decades out of date,
up to and including advertising bang path mail addresses.
I guess you would not like ending up in that trap, right?

Yours,
  Ingo

Re: .TH 4th field (Was: [PATCH 1/2] system_data_types.7: srcfix)

[Alejandro Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 4370 bytes --]

Hi Ingo,

On 8/24/22 15:22, Ingo Schwarze wrote:
> Hi Alejandro,
> 
> Alejandro Colomar wrote on Sat, Aug 20, 2022 at 02:40:58PM +0200:
> 
>> Should I keep the static part of the COLOPHON in a REPORTING BUGS section?
> 
> I do not think a manual page should include *any* boilerplate text.
> Text that is the same everywhere is nothing but a distraction
> and a waste of screen real estate.

Agree.  I was hesitant of removing that, which mtk added a long time 
ago, since he claimed an important improvement in awareness of the 
existence of the project.  But I prefer using reportbug(1) and dpkg(1) 
or apt(8) (or equivalent in other distros) to find out how to report bugs.

> 
>> And an even more general question?  Should a manual page state the
>> COPYRIGHT,
> 
> No, it should *not* state any Copyright in the *formatted* text.
> Every file should contain a Copyright and license header at the top
> as a comment though: in a manual page file, .\" stating the Coypright
> and license of that particular manual page, in a program source file,
> /* */ stating the Coypright and license of that particular source file.
> 
> Manual pages are for users who want to use the program or function.
> For merely using it, they do not need to consider *any* Copyright or
> license, at least as long as it is more or less free software.

Greg KH expressed concern about the copyright of the example programs 
some time ago.  He asked what license applies to them, and how should a 
user know, that is, is a user allowed to create derived programs from 
those examples?  Should we state their license in a C comment within the 
example program?  Or just assume that it's a meaningless program and 
that anyone can just copy it indiscriminately because, who cares about 
such a tiny insignificant piece of code?

> 
> Stating the Copyright and license matters for packagers and for
> developers or companies who consider copying parts of files for their
> own projects, and those people are used to looking at source files.
> 
>> AUTHORS,
> 
> Mentioning the main AUTHORS of the original implementation of the program -
> for example, Robert Morris and Lorinda Cherry for bc(1) - and also
> mentioning the main AUTHORS of your current implementation, if it
> was rewritten from scratch, seems most important to me.

I guess in the Linux man-pages that means just don't use it at all. 
Original authors of Linux and GNU are Linux and RMS and that's well 
known.  Current author of any given feature is probably a combination of 
thousands of people.

> 
> Mentioning the AUTHORS of the manual page seems much less relevant
> to me, and it is usually omitted.  Mentioning them is not wrong, though,
> and it some cases, it can be interesting.  For example, some programs
> used to be notorious for not having any manual page whatsoever until
> some Debian developers - who were not even associated with the projects
> maintaining those programs - took pity and wrote a manual page.
> Crediting those brave souls feels fair to me, just as an example.
> 
> If you mention people who wrote the manual but did not contribute
> significantly to the program itself, be explicit that they wrote
> the manual page.
> 
>> and REPORTING BUGS of the software it documents, or
>> of the page itself, or both?
> 
> Any REPORTING BUGS section feels like a bad idea to me - see above
> regarding boilerplate text.
> 
> Besides, if a user is unable to use whatever package manager they
> have, inspect which package the program they are using (and its
> manual page) belong to, and inspect the project website how to
> properly report a bug, would you really expect a useful bug report?
> I certainly wouldn't.  So not having a REPORTING BUGS section
> will discourage only extremely clueless users, whereas having one
> will likely annoy anyone of even minimal competence.
> 
> On top of that, i have often seen bug reporting instructions in
> manual pages that were literally several decades out of date,
> up to and including advertising bang path mail addresses.
> I guess you would not like ending up in that trap, right?

Yup!

So, I'll just drop the COLOPHON section without replacement.

Cheers,

Alex

> 
> Yours,
>    Ingo

-- 
Alejandro Colomar
<http://www.alejandro-colomar.es/>

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

Re: .TH 4th field (Was: [PATCH 1/2] system_data_types.7: srcfix)

[Ingo Schwarze]

Hi Alejandro,

Alejandro Colomar wrote on Wed, Aug 24, 2022 at 05:04:57PM +0200:
> On 8/24/22 15:22, Ingo Schwarze wrote:
>> Alejandro Colomar wrote on Sat, Aug 20, 2022 at 02:40:58PM +0200:

>>> Should I keep the static part of the COLOPHON in a REPORTING BUGS section?

>> I do not think a manual page should include *any* boilerplate text.
>> Text that is the same everywhere is nothing but a distraction
>> and a waste of screen real estate.

> Agree.  I was hesitant of removing that, which mtk added a long time 
> ago, since he claimed an important improvement in awareness of the 
> existence of the project.  But I prefer using reportbug(1) and dpkg(1) 
> or apt(8) (or equivalent in other distros) to find out how to report bugs.

Hum.  Interesting aspect.  Maybe Micheal had a point that advertising
the Linux man-pages project - even in such an aggressive way - had some
value in the early days.  I'm not an expert in Linux history, but i
believe use of manual pages was initially much less common in Linux-
based operating systems compared to AT&T UNIX, other commercial UNIX
systems, and BSD.  Also, due to the fragmentation of Linux-based
operating systems into Linux (the kernel), GNU (the most important
parts of userland), and software from many third-party sources,
a single, uniform corpus of manual pages was slower to develop for
Linux than, for example, in BSD.

But nowadays, i would no longer subscribe to such a theory, it seems
to me that times have changed in this respect.  Debian has fostered
some progress in writing missing manual pages.  Web sites like
manpages.debian.org and even man.archlinux.org now provide more
comprehensive collections of manual pages than even BSDs do.
And such sites usually clearly identify package names, much reducing
the effects of the conceptual fragmentation.  So i expect many more
Linux users are now aware of the man-pages project than used to be,
and even those who aren't yet are likely to find out once they need to.

> Greg KH expressed concern about the copyright of the example programs 
> some time ago.  He asked what license applies to them, and how should a 
> user know, that is, is a user allowed to create derived programs from 
> those examples?  Should we state their license in a C comment within the 
> example program?  Or just assume that it's a meaningless program and 
> that anyone can just copy it indiscriminately because, who cares about 
> such a tiny insignificant piece of code?

That is an interesting question, too.  I believe it never occurred
to me because EXAMPLES in OpenBSD manual pages are typically kept so
short and simple that they only demonstrate well-established aspects
of prior art and do not really involve any creative act by the author
of the manual pages, hence obviously being in in the public domain
in the first place.

But in the Linux man-pages project, you have many long and complex
programs below EXAMPLES, some of which certainly pass the test of
originality, hence being protected by Copyright law.

Now obviously, unless otherwise stated, such examples are covered
by the SPDX-License-Identifier: at the top of the file.  For pages
licensed under the BSD or MIT licenses, everything is obviously
fine, anyone can use such example code in any project.  For pages
under GPL licenses, the situation is also tolerable: while BSD
projects cannot use these example, at least GPL projects can, which
feels like the main purpose of a Linux project.  I sense a real
problem with EXAMPLES in Linux-man-pages-copyleft pages though:
Those can *neither* be used in BSD projects *nor* in GPL projects
as far as i can see.

Maybe it would be worth finding the authors of significant examples
in Linux-man-pages-copyleft pages and getting their permission
to add a line like

  /* This example code is released into the public domain. */

at the top of such examples, maybe together with a roff(7) comment
like

  .\" This example code was written by Alice and Bob in 2015.

Anything more complicated, like refering to GPL-2+ would seem like
overkill to me.

>>> AUTHORS,

>> Mentioning the main AUTHORS of the original implementation of the program -
>> for example, Robert Morris and Lorinda Cherry for bc(1) - and also
>> mentioning the main AUTHORS of your current implementation, if it
>> was rewritten from scratch, seems most important to me.

> I guess in the Linux man-pages that means just don't use it at all. 
> Original authors of Linux and GNU are Linux and RMS and that's well 
> known.  Current author of any given feature is probably a combination of 
> thousands of people.

I didn't mean naming all contributors; that would be completely
unreasonable even in the (usually smaller) BSD projects.  It seems
sufficient to me to name the main and original author(s).  For
example, for GNU troff, that is James Clark.  I don't doubt there
is much GNU software where Linus and RMS are not the principle
authors.

However, i realize that

 (1) AUTHORS sections are on average less useful in sections 2, 3, and 4
     than in sections 1 and 8, and the Linux man-pages projects is
     sparse in sections 1 and 8, for obvious reasons;

 (2) If something really goes back all the way to Linus or RMS,
     not explicitly saying so would be reasonable for similar
     reasons as BSD manual pages rarely use AUTHORS sections for
     features that have existed since the 1970s because those
     were usually invented by Dennis Ritchie or Ken Thompson.
     We do use AUTHORS sections for programs written from 1BSD
     (1978) onwards, even if written by Bill Joy, Keith Bostic,
     Eric Allman, Mary Ann Horton, Kurt Shoens, Rob Pike, or
     similarly well-known people.

I think it's a case-by-case decision: is there clear enough and
significant enough authorship of the initial version, or was it
a cast of many right from the start?

Yours,
  Ingo

Re: .TH 4th field (Was: [PATCH 1/2] system_data_types.7: srcfix)

[Alejandro Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 5308 bytes --]

Hi Ingo,

On 8/24/22 19:12, Ingo Schwarze wrote:
> Hi Alejandro,
> 
> Alejandro Colomar wrote on Wed, Aug 24, 2022 at 05:04:57PM +0200:
>> On 8/24/22 15:22, Ingo Schwarze wrote:
>>> Alejandro Colomar wrote on Sat, Aug 20, 2022 at 02:40:58PM +0200:
> 
>>>> Should I keep the static part of the COLOPHON in a REPORTING BUGS section?
> 
>>> I do not think a manual page should include *any* boilerplate text.
>>> Text that is the same everywhere is nothing but a distraction
>>> and a waste of screen real estate.
> 
>> Agree.  I was hesitant of removing that, which mtk added a long time
>> ago, since he claimed an important improvement in awareness of the
>> existence of the project.  But I prefer using reportbug(1) and dpkg(1)
>> or apt(8) (or equivalent in other distros) to find out how to report bugs.
> 
> Hum.  Interesting aspect.  Maybe Micheal had a point that advertising
> the Linux man-pages project - even in such an aggressive way - had some
> value in the early days.  I'm not an expert in Linux history, but i
> believe use of manual pages was initially much less common in Linux-
> based operating systems compared to AT&T UNIX, other commercial UNIX
> systems, and BSD.  Also, due to the fragmentation of Linux-based
> operating systems into Linux (the kernel), GNU (the most important
> parts of userland), and software from many third-party sources,
> a single, uniform corpus of manual pages was slower to develop for
> Linux than, for example, in BSD.
> 
> But nowadays, i would no longer subscribe to such a theory, it seems
> to me that times have changed in this respect.  Debian has fostered
> some progress in writing missing manual pages.  Web sites like
> manpages.debian.org and even man.archlinux.org now provide more
> comprehensive collections of manual pages than even BSDs do.
> And such sites usually clearly identify package names, much reducing
> the effects of the conceptual fragmentation.  So i expect many more
> Linux users are now aware of the man-pages project than used to be,
> and even those who aren't yet are likely to find out once they need to.

Removed: 
<https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/commit/?id=8c3052b0322580eba62de91f04ba657f7dfe360e>

this time it seems your name and email are correct :)

> 
>> Greg KH expressed concern about the copyright of the example programs
>> some time ago.  He asked what license applies to them, and how should a
>> user know, that is, is a user allowed to create derived programs from
>> those examples?  Should we state their license in a C comment within the
>> example program?  Or just assume that it's a meaningless program and
>> that anyone can just copy it indiscriminately because, who cares about
>> such a tiny insignificant piece of code?
> 
> That is an interesting question, too.  I believe it never occurred
> to me because EXAMPLES in OpenBSD manual pages are typically kept so
> short and simple that they only demonstrate well-established aspects
> of prior art and do not really involve any creative act by the author
> of the manual pages, hence obviously being in in the public domain
> in the first place.
> 
> But in the Linux man-pages project, you have many long and complex
> programs below EXAMPLES, some of which certainly pass the test of
> originality, hence being protected by Copyright law.
> 
> Now obviously, unless otherwise stated, such examples are covered
> by the SPDX-License-Identifier: at the top of the file.  For pages
> licensed under the BSD or MIT licenses, everything is obviously
> fine, anyone can use such example code in any project.  For pages
> under GPL licenses, the situation is also tolerable: while BSD
> projects cannot use these example, at least GPL projects can, which
> feels like the main purpose of a Linux project.  I sense a real
> problem with EXAMPLES in Linux-man-pages-copyleft pages though:
> Those can *neither* be used in BSD projects *nor* in GPL projects
> as far as i can see.
> 
> Maybe it would be worth finding the authors of significant examples
> in Linux-man-pages-copyleft pages and getting their permission
> to add a line like
> 
>    /* This example code is released into the public domain. */
> 
> at the top of such examples, maybe together with a roff(7) comment
> like
> 
>    .\" This example code was written by Alice and Bob in 2015.
> 
> Anything more complicated, like refering to GPL-2+ would seem like
> overkill to me.

I'll do that (PD) with all of my examples, and will also request a 
comment stating either PD or a specific license for contributions to 
EXAMPLES.  For existing examples, since most come from Michael, I'll 
wait until he comes back some day, if he does...  Otherwise, I'll just 
do nothing until someone asks for a license for a specific piece of 
code, and then ask the specific author.

> 
>>>> AUTHORS,

[...]

> I think it's a case-by-case decision: is there clear enough and
> significant enough authorship of the initial version, or was it
> a cast of many right from the start?

For now, since mtk was against that section, I'll keep that trend.

Cheers,

Alex

> 
> Yours,
>    Ingo

-- 
Alejandro Colomar
<http://www.alejandro-colomar.es/>

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