* [PATCH 1/3] system_data_types.7: ffix
@ 2020-09-27 21:13 Alejandro Colomar
2020-09-27 21:13 ` [PATCH 2/3] system_data_types.7: Add 'FILE' Alejandro Colomar
` (2 more replies)
0 siblings, 3 replies; 22+ messages in thread
From: Alejandro Colomar @ 2020-09-27 21:13 UTC (permalink / raw)
To: mtk.manpages; +Cc: linux-man, libc-alpha, Alejandro Colomar
Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
---
man7/system_data_types.7 | 58 ++++++++++++++++++++--------------------
1 file changed, 29 insertions(+), 29 deletions(-)
diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
index 361e8d411..ff0403df9 100644
--- a/man7/system_data_types.7
+++ b/man7/system_data_types.7
@@ -66,7 +66,7 @@ system_data_types \- overview of system data types
.TP
.I aiocb
.RS
-.PP
+.br
Include:
.IR <aio.h> .
.PP
@@ -101,7 +101,7 @@ See also:
.TP
.I div_t
.RS
-.PP
+.br
Include:
.IR <stdlib.h> .
.PP
@@ -125,7 +125,7 @@ See also:
.TP
.I double_t
.RS
-.PP
+.br
Include:
.IR <math.h> .
.PP
@@ -167,7 +167,7 @@ type in this page.
.TP
.I fenv_t
.RS
-.PP
+.br
Include:
.IR <fenv.h> .
.PP
@@ -184,7 +184,7 @@ See also:
.TP
.I fexcept_t
.RS
-.PP
+.br
Include:
.IR <fenv.h> .
.PP
@@ -201,7 +201,7 @@ See also:
.TP
.I float_t
.RS
-.PP
+.br
Include:
.IR <math.h> .
.PP
@@ -243,7 +243,7 @@ type in this page.
.TP
.I gid_t
.RS
-.PP
+.br
Include:
.IR <sys/types.h> ;
or
@@ -280,7 +280,7 @@ See also:
.TP
.I id_t
.RS
-.PP
+.br
Include:
.IR <sys/types.h> ;
or
@@ -304,7 +304,7 @@ See also:
.TP
.I imaxdiv_t
.RS
-.PP
+.br
Include:
.IR <inttypes.h> .
.PP
@@ -328,7 +328,7 @@ See also:
.TP
.I lconv
.RS
-.PP
+.br
Include:
.IR <locale.h> .
.PP
@@ -377,7 +377,7 @@ See also:
.TP
.I ldiv_t
.RS
-.PP
+.br
Include:
.IR <stdlib.h> .
.PP
@@ -401,7 +401,7 @@ See also:
.TP
.I lldiv_t
.RS
-.PP
+.br
Include:
.IR <stdlib.h> .
.PP
@@ -425,7 +425,7 @@ See also:
.TP
.I pid_t
.RS
-.PP
+.br
Include
.IR <sys/types.h> ;
or
@@ -481,7 +481,7 @@ See also:
.TP
.I ptrdiff_t
.RS
-.PP
+.br
Include:
.IR <stddef.h> .
.PP
@@ -520,7 +520,7 @@ types in this page.
.TP
.I regmatch_t
.RS
-.PP
+.br
Include:
.IR <regex.h> .
.PP
@@ -545,7 +545,7 @@ See also:
.TP
.I regoff_t
.RS
-.PP
+.br
Include:
.IR <regex.h> .
.PP
@@ -577,7 +577,7 @@ types in this page.
.TP
.I sigevent
.RS
-.PP
+.br
Include:
.IR <signal.h> ;
or
@@ -626,7 +626,7 @@ structure in this page.
.TP
.I siginfo_t
.RS
-.PP
+.br
Include:
.IR <signal.h> ;
or
@@ -662,7 +662,7 @@ See also:
.TP
.I sigset_t
.RS
-.PP
+.br
Include:
.IR <signal.h> ;
or
@@ -691,7 +691,7 @@ See also:
.TP
.I sigval
.RS
-.PP
+.br
Include:
.IR <signal.h> .
.PP
@@ -723,7 +723,7 @@ in this page.
.TP
.I size_t
.RS
-.PP
+.br
Include:
.I <stddef.h>
or
@@ -846,7 +846,7 @@ types in this page.
.TP
.I ssize_t
.RS
-.PP
+.br
Include:
.IR <sys/types.h> ;
or
@@ -922,7 +922,7 @@ types in this page.
.TP
.I suseconds_t
.RS
-.PP
+.br
Include:
.IR <sys/types.h> ;
or
@@ -949,7 +949,7 @@ structure in this page.
.TP
.I time_t
.RS
-.PP
+.br
Include:
.I <sys/types.h>
or
@@ -992,7 +992,7 @@ See also:
.TP
.I timer_t
.RS
-.PP
+.br
Include:
.IR <sys/types.h> ;
or
@@ -1015,7 +1015,7 @@ See also:
.TP
.I timespec
.RS
-.PP
+.br
Include:
.IR <time.h> ;
or
@@ -1053,7 +1053,7 @@ See also:
.TP
.I timeval
.RS
-.PP
+.br
Include:
.IR <sys/time.h> ;
or
@@ -1086,7 +1086,7 @@ See also:
.TP
.I uid_t
.RS
-.PP
+.br
Include:
.IR <sys/types.h> ;
or
@@ -1120,7 +1120,7 @@ See also:
.TP
.I va_list
.RS
-.PP
+.br
Include:
.IR <stdarg> ;
or
--
2.28.0
^ permalink raw reply related [flat|nested] 22+ messages in thread
* [PATCH 2/3] system_data_types.7: Add 'FILE'
2020-09-27 21:13 [PATCH 1/3] system_data_types.7: ffix Alejandro Colomar
@ 2020-09-27 21:13 ` Alejandro Colomar
2020-09-28 6:04 ` Michael Kerrisk (man-pages)
2020-09-27 21:13 ` [PATCH 3/3] FILE.3: New link to system_data_types(7) Alejandro Colomar
2020-09-28 5:59 ` [PATCH 1/3] system_data_types.7: ffix Michael Kerrisk (man-pages)
2 siblings, 1 reply; 22+ messages in thread
From: Alejandro Colomar @ 2020-09-27 21:13 UTC (permalink / raw)
To: mtk.manpages; +Cc: linux-man, libc-alpha, Alejandro Colomar
Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
---
man7/system_data_types.7 | 23 +++++++++++++++++++++++
1 file changed, 23 insertions(+)
diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
index ff0403df9..16930985e 100644
--- a/man7/system_data_types.7
+++ b/man7/system_data_types.7
@@ -197,6 +197,29 @@ Conforming to: C99 and later; POSIX.1-2001 and later.
See also:
.BR fenv (3)
.RE
+.\"------------------------------------- FILE -------------------------/
+.TP
+.I FILE
+.RS
+.br
+Include:
+.IR <stdio.h> ;
+or
+.IR <wchar.h> .
+.PP
+An object type used for streams.
+.PP
+Conforming to: C99 and later; POSIX.1-2001 and later.
+.PP
+See also:
+.BR fclose (3),
+.BR flockfile (3),
+.BR fopen (3),
+.BR fread (3),
+.BR stdin (3),
+.BR stdio (3),
+.BR unlocked_stdio (3)
+.RE
.\"------------------------------------- float_t ----------------------/
.TP
.I float_t
--
2.28.0
^ permalink raw reply related [flat|nested] 22+ messages in thread
* [PATCH 3/3] FILE.3: New link to system_data_types(7)
2020-09-27 21:13 [PATCH 1/3] system_data_types.7: ffix Alejandro Colomar
2020-09-27 21:13 ` [PATCH 2/3] system_data_types.7: Add 'FILE' Alejandro Colomar
@ 2020-09-27 21:13 ` Alejandro Colomar
2020-09-28 5:59 ` [PATCH 1/3] system_data_types.7: ffix Michael Kerrisk (man-pages)
2 siblings, 0 replies; 22+ messages in thread
From: Alejandro Colomar @ 2020-09-27 21:13 UTC (permalink / raw)
To: mtk.manpages; +Cc: linux-man, libc-alpha, Alejandro Colomar
Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
---
man3/FILE.3 | 1 +
1 file changed, 1 insertion(+)
create mode 100644 man3/FILE.3
diff --git a/man3/FILE.3 b/man3/FILE.3
new file mode 100644
index 000000000..db50c0f09
--- /dev/null
+++ b/man3/FILE.3
@@ -0,0 +1 @@
+.so man7/system_data_types.7
--
2.28.0
^ permalink raw reply related [flat|nested] 22+ messages in thread
* Re: [PATCH 1/3] system_data_types.7: ffix
2020-09-27 21:13 [PATCH 1/3] system_data_types.7: ffix Alejandro Colomar
2020-09-27 21:13 ` [PATCH 2/3] system_data_types.7: Add 'FILE' Alejandro Colomar
2020-09-27 21:13 ` [PATCH 3/3] FILE.3: New link to system_data_types(7) Alejandro Colomar
@ 2020-09-28 5:59 ` Michael Kerrisk (man-pages)
2020-09-28 9:03 ` [PATCH v2 " Alejandro Colomar
2020-09-28 10:40 ` [PATCH " G. Branden Robinson
2 siblings, 2 replies; 22+ messages in thread
From: Michael Kerrisk (man-pages) @ 2020-09-28 5:59 UTC (permalink / raw)
To: Alejandro Colomar
Cc: mtk.manpages, linux-man, libc-alpha, G. Branden Robinson
Hi Alex,
On 9/27/20 11:13 PM, Alejandro Colomar wrote:
> Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
I do think this requires an explanation saying what you are
trying to do with this change (and then perhaps a more expansive
"Subject" also).
I can visually see what you are doing with this patch,
but I do wonder if there is a better way of doing it.
I've dropped Branden into CC. Perhaps he has a comment.
Thanks,
Michael
> ---
> man7/system_data_types.7 | 58 ++++++++++++++++++++--------------------
> 1 file changed, 29 insertions(+), 29 deletions(-)
>
> diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
> index 361e8d411..ff0403df9 100644
> --- a/man7/system_data_types.7
> +++ b/man7/system_data_types.7
> @@ -66,7 +66,7 @@ system_data_types \- overview of system data types
> .TP
> .I aiocb
> .RS
> -.PP
> +.br
> Include:
> .IR <aio.h> .
> .PP
> @@ -101,7 +101,7 @@ See also:
> .TP
> .I div_t
> .RS
> -.PP
> +.br
> Include:
> .IR <stdlib.h> .
> .PP
> @@ -125,7 +125,7 @@ See also:
> .TP
> .I double_t
> .RS
> -.PP
> +.br
> Include:
> .IR <math.h> .
> .PP
> @@ -167,7 +167,7 @@ type in this page.
> .TP
> .I fenv_t
> .RS
> -.PP
> +.br
> Include:
> .IR <fenv.h> .
> .PP
> @@ -184,7 +184,7 @@ See also:
> .TP
> .I fexcept_t
> .RS
> -.PP
> +.br
> Include:
> .IR <fenv.h> .
> .PP
> @@ -201,7 +201,7 @@ See also:
> .TP
> .I float_t
> .RS
> -.PP
> +.br
> Include:
> .IR <math.h> .
> .PP
> @@ -243,7 +243,7 @@ type in this page.
> .TP
> .I gid_t
> .RS
> -.PP
> +.br
> Include:
> .IR <sys/types.h> ;
> or
> @@ -280,7 +280,7 @@ See also:
> .TP
> .I id_t
> .RS
> -.PP
> +.br
> Include:
> .IR <sys/types.h> ;
> or
> @@ -304,7 +304,7 @@ See also:
> .TP
> .I imaxdiv_t
> .RS
> -.PP
> +.br
> Include:
> .IR <inttypes.h> .
> .PP
> @@ -328,7 +328,7 @@ See also:
> .TP
> .I lconv
> .RS
> -.PP
> +.br
> Include:
> .IR <locale.h> .
> .PP
> @@ -377,7 +377,7 @@ See also:
> .TP
> .I ldiv_t
> .RS
> -.PP
> +.br
> Include:
> .IR <stdlib.h> .
> .PP
> @@ -401,7 +401,7 @@ See also:
> .TP
> .I lldiv_t
> .RS
> -.PP
> +.br
> Include:
> .IR <stdlib.h> .
> .PP
> @@ -425,7 +425,7 @@ See also:
> .TP
> .I pid_t
> .RS
> -.PP
> +.br
> Include
> .IR <sys/types.h> ;
> or
> @@ -481,7 +481,7 @@ See also:
> .TP
> .I ptrdiff_t
> .RS
> -.PP
> +.br
> Include:
> .IR <stddef.h> .
> .PP
> @@ -520,7 +520,7 @@ types in this page.
> .TP
> .I regmatch_t
> .RS
> -.PP
> +.br
> Include:
> .IR <regex.h> .
> .PP
> @@ -545,7 +545,7 @@ See also:
> .TP
> .I regoff_t
> .RS
> -.PP
> +.br
> Include:
> .IR <regex.h> .
> .PP
> @@ -577,7 +577,7 @@ types in this page.
> .TP
> .I sigevent
> .RS
> -.PP
> +.br
> Include:
> .IR <signal.h> ;
> or
> @@ -626,7 +626,7 @@ structure in this page.
> .TP
> .I siginfo_t
> .RS
> -.PP
> +.br
> Include:
> .IR <signal.h> ;
> or
> @@ -662,7 +662,7 @@ See also:
> .TP
> .I sigset_t
> .RS
> -.PP
> +.br
> Include:
> .IR <signal.h> ;
> or
> @@ -691,7 +691,7 @@ See also:
> .TP
> .I sigval
> .RS
> -.PP
> +.br
> Include:
> .IR <signal.h> .
> .PP
> @@ -723,7 +723,7 @@ in this page.
> .TP
> .I size_t
> .RS
> -.PP
> +.br
> Include:
> .I <stddef.h>
> or
> @@ -846,7 +846,7 @@ types in this page.
> .TP
> .I ssize_t
> .RS
> -.PP
> +.br
> Include:
> .IR <sys/types.h> ;
> or
> @@ -922,7 +922,7 @@ types in this page.
> .TP
> .I suseconds_t
> .RS
> -.PP
> +.br
> Include:
> .IR <sys/types.h> ;
> or
> @@ -949,7 +949,7 @@ structure in this page.
> .TP
> .I time_t
> .RS
> -.PP
> +.br
> Include:
> .I <sys/types.h>
> or
> @@ -992,7 +992,7 @@ See also:
> .TP
> .I timer_t
> .RS
> -.PP
> +.br
> Include:
> .IR <sys/types.h> ;
> or
> @@ -1015,7 +1015,7 @@ See also:
> .TP
> .I timespec
> .RS
> -.PP
> +.br
> Include:
> .IR <time.h> ;
> or
> @@ -1053,7 +1053,7 @@ See also:
> .TP
> .I timeval
> .RS
> -.PP
> +.br
> Include:
> .IR <sys/time.h> ;
> or
> @@ -1086,7 +1086,7 @@ See also:
> .TP
> .I uid_t
> .RS
> -.PP
> +.br
> Include:
> .IR <sys/types.h> ;
> or
> @@ -1120,7 +1120,7 @@ See also:
> .TP
> .I va_list
> .RS
> -.PP
> +.br
> Include:
> .IR <stdarg> ;
> or
>
--
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
^ permalink raw reply [flat|nested] 22+ messages in thread
* Re: [PATCH 2/3] system_data_types.7: Add 'FILE'
2020-09-27 21:13 ` [PATCH 2/3] system_data_types.7: Add 'FILE' Alejandro Colomar
@ 2020-09-28 6:04 ` Michael Kerrisk (man-pages)
2020-09-28 9:06 ` [PATCH v2 " Alejandro Colomar
0 siblings, 1 reply; 22+ messages in thread
From: Michael Kerrisk (man-pages) @ 2020-09-28 6:04 UTC (permalink / raw)
To: Alejandro Colomar; +Cc: mtk.manpages, linux-man, libc-alpha
Hi Alex,
On 9/27/20 11:13 PM, Alejandro Colomar wrote:
> Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
> ---
> man7/system_data_types.7 | 23 +++++++++++++++++++++++
> 1 file changed, 23 insertions(+)
>
> diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
> index ff0403df9..16930985e 100644
> --- a/man7/system_data_types.7
> +++ b/man7/system_data_types.7
> @@ -197,6 +197,29 @@ Conforming to: C99 and later; POSIX.1-2001 and later.
> See also:
> .BR fenv (3)
> .RE
> +.\"------------------------------------- FILE -------------------------/
> +.TP
> +.I FILE
> +.RS
> +.br
See my previous mail. In the meantime, I'm okay with applying
this kind of formatting for this (and following) patches, though
it may need changing later.
> +Include:
> +.IR <stdio.h> ;
> +or
> +.IR <wchar.h> .
> +.PP
> +An object type used for streams.
> +.PP
> +Conforming to: C99 and later; POSIX.1-2001 and later.
> +.PP
> +See also:
> +.BR fclose (3),
> +.BR flockfile (3),
> +.BR fopen (3),
> +.BR fread (3),
> +.BR stdin (3),
> +.BR stdio (3),
> +.BR unlocked_stdio (3)
Let's have fscanf() and fprintf() here. On the other hand,
I think unlocked_stdio(3) probably isn't needed.
> +.RE
> .\"------------------------------------- float_t ----------------------/
> .TP
> .I float_t
Thanks,
Michael
--
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
^ permalink raw reply [flat|nested] 22+ messages in thread
* [PATCH v2 1/3] system_data_types.7: ffix
2020-09-28 5:59 ` [PATCH 1/3] system_data_types.7: ffix Michael Kerrisk (man-pages)
@ 2020-09-28 9:03 ` Alejandro Colomar
2020-09-28 10:34 ` Michael Kerrisk (man-pages)
2020-09-28 13:06 ` G. Branden Robinson
2020-09-28 10:40 ` [PATCH " G. Branden Robinson
1 sibling, 2 replies; 22+ messages in thread
From: Alejandro Colomar @ 2020-09-28 9:03 UTC (permalink / raw)
To: mtk.manpages; +Cc: linux-man, libc-alpha, g.branden.robinson, Alejandro Colomar
Normally, text under a section header starts in the next line after the
header, without a blank line. Follow that pattern.
Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
---
Hi Michael,
I had been using .PP because I hadn't seen .br before.
I think .br is the correct format,
following the pattern in already existing man pages.
BTW, is there any way to copy the CC list with git send-email
from the email I'm answering to?
Right now I'm manually copying all of them each time from Thunderbird.
Regards,
Alex
man7/system_data_types.7 | 58 ++++++++++++++++++++--------------------
1 file changed, 29 insertions(+), 29 deletions(-)
diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
index 361e8d411..ff0403df9 100644
--- a/man7/system_data_types.7
+++ b/man7/system_data_types.7
@@ -66,7 +66,7 @@ system_data_types \- overview of system data types
.TP
.I aiocb
.RS
-.PP
+.br
Include:
.IR <aio.h> .
.PP
@@ -101,7 +101,7 @@ See also:
.TP
.I div_t
.RS
-.PP
+.br
Include:
.IR <stdlib.h> .
.PP
@@ -125,7 +125,7 @@ See also:
.TP
.I double_t
.RS
-.PP
+.br
Include:
.IR <math.h> .
.PP
@@ -167,7 +167,7 @@ type in this page.
.TP
.I fenv_t
.RS
-.PP
+.br
Include:
.IR <fenv.h> .
.PP
@@ -184,7 +184,7 @@ See also:
.TP
.I fexcept_t
.RS
-.PP
+.br
Include:
.IR <fenv.h> .
.PP
@@ -201,7 +201,7 @@ See also:
.TP
.I float_t
.RS
-.PP
+.br
Include:
.IR <math.h> .
.PP
@@ -243,7 +243,7 @@ type in this page.
.TP
.I gid_t
.RS
-.PP
+.br
Include:
.IR <sys/types.h> ;
or
@@ -280,7 +280,7 @@ See also:
.TP
.I id_t
.RS
-.PP
+.br
Include:
.IR <sys/types.h> ;
or
@@ -304,7 +304,7 @@ See also:
.TP
.I imaxdiv_t
.RS
-.PP
+.br
Include:
.IR <inttypes.h> .
.PP
@@ -328,7 +328,7 @@ See also:
.TP
.I lconv
.RS
-.PP
+.br
Include:
.IR <locale.h> .
.PP
@@ -377,7 +377,7 @@ See also:
.TP
.I ldiv_t
.RS
-.PP
+.br
Include:
.IR <stdlib.h> .
.PP
@@ -401,7 +401,7 @@ See also:
.TP
.I lldiv_t
.RS
-.PP
+.br
Include:
.IR <stdlib.h> .
.PP
@@ -425,7 +425,7 @@ See also:
.TP
.I pid_t
.RS
-.PP
+.br
Include
.IR <sys/types.h> ;
or
@@ -481,7 +481,7 @@ See also:
.TP
.I ptrdiff_t
.RS
-.PP
+.br
Include:
.IR <stddef.h> .
.PP
@@ -520,7 +520,7 @@ types in this page.
.TP
.I regmatch_t
.RS
-.PP
+.br
Include:
.IR <regex.h> .
.PP
@@ -545,7 +545,7 @@ See also:
.TP
.I regoff_t
.RS
-.PP
+.br
Include:
.IR <regex.h> .
.PP
@@ -577,7 +577,7 @@ types in this page.
.TP
.I sigevent
.RS
-.PP
+.br
Include:
.IR <signal.h> ;
or
@@ -626,7 +626,7 @@ structure in this page.
.TP
.I siginfo_t
.RS
-.PP
+.br
Include:
.IR <signal.h> ;
or
@@ -662,7 +662,7 @@ See also:
.TP
.I sigset_t
.RS
-.PP
+.br
Include:
.IR <signal.h> ;
or
@@ -691,7 +691,7 @@ See also:
.TP
.I sigval
.RS
-.PP
+.br
Include:
.IR <signal.h> .
.PP
@@ -723,7 +723,7 @@ in this page.
.TP
.I size_t
.RS
-.PP
+.br
Include:
.I <stddef.h>
or
@@ -846,7 +846,7 @@ types in this page.
.TP
.I ssize_t
.RS
-.PP
+.br
Include:
.IR <sys/types.h> ;
or
@@ -922,7 +922,7 @@ types in this page.
.TP
.I suseconds_t
.RS
-.PP
+.br
Include:
.IR <sys/types.h> ;
or
@@ -949,7 +949,7 @@ structure in this page.
.TP
.I time_t
.RS
-.PP
+.br
Include:
.I <sys/types.h>
or
@@ -992,7 +992,7 @@ See also:
.TP
.I timer_t
.RS
-.PP
+.br
Include:
.IR <sys/types.h> ;
or
@@ -1015,7 +1015,7 @@ See also:
.TP
.I timespec
.RS
-.PP
+.br
Include:
.IR <time.h> ;
or
@@ -1053,7 +1053,7 @@ See also:
.TP
.I timeval
.RS
-.PP
+.br
Include:
.IR <sys/time.h> ;
or
@@ -1086,7 +1086,7 @@ See also:
.TP
.I uid_t
.RS
-.PP
+.br
Include:
.IR <sys/types.h> ;
or
@@ -1120,7 +1120,7 @@ See also:
.TP
.I va_list
.RS
-.PP
+.br
Include:
.IR <stdarg> ;
or
--
2.28.0
^ permalink raw reply related [flat|nested] 22+ messages in thread
* [PATCH v2 2/3] system_data_types.7: Add 'FILE'
2020-09-28 6:04 ` Michael Kerrisk (man-pages)
@ 2020-09-28 9:06 ` Alejandro Colomar
2020-09-29 13:15 ` Alejandro Colomar
0 siblings, 1 reply; 22+ messages in thread
From: Alejandro Colomar @ 2020-09-28 9:06 UTC (permalink / raw)
To: mtk.manpages; +Cc: linux-man, libc-alpha, g.branden.robinson, Alejandro Colomar
Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
---
man7/system_data_types.7 | 23 +++++++++++++++++++++++
1 file changed, 23 insertions(+)
Hi Michael,
Please hold until the ffix is applied (or not).
Thanks,
Alex
diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
index ff0403df9..16930985e 100644
--- a/man7/system_data_types.7
+++ b/man7/system_data_types.7
@@ -197,6 +197,29 @@ Conforming to: C99 and later; POSIX.1-2001 and later.
See also:
.BR fenv (3)
.RE
+.\"------------------------------------- FILE -------------------------/
+.TP
+.I FILE
+.RS
+.br
+Include:
+.IR <stdio.h> ;
+or
+.IR <wchar.h> .
+.PP
+An object type used for streams.
+.PP
+Conforming to: C99 and later; POSIX.1-2001 and later.
+.PP
+See also:
+.BR fclose (3),
+.BR flockfile (3),
+.BR fopen (3),
+.BR fprintf (3),
+.BR fread (3),
+.BR fscanf (3),
+.BR stdin (3),
+.BR stdio (3)
+.RE
.\"------------------------------------- float_t ----------------------/
.TP
.I float_t
--
2.28.0
^ permalink raw reply related [flat|nested] 22+ messages in thread
* Re: [PATCH v2 1/3] system_data_types.7: ffix
2020-09-28 9:03 ` [PATCH v2 " Alejandro Colomar
@ 2020-09-28 10:34 ` Michael Kerrisk (man-pages)
2020-09-28 10:37 ` Alejandro Colomar
2020-09-28 11:13 ` G. Branden Robinson
2020-09-28 13:06 ` G. Branden Robinson
1 sibling, 2 replies; 22+ messages in thread
From: Michael Kerrisk (man-pages) @ 2020-09-28 10:34 UTC (permalink / raw)
To: Alejandro Colomar; +Cc: linux-man, libc-alpha, G. Branden Robinson
Hi Alex,
On Mon, 28 Sep 2020 at 11:04, Alejandro Colomar <colomar.6.4.3@gmail.com> wrote:
>
> Normally, text under a section header starts in the next line after the
> header, without a blank line. Follow that pattern.
>
> Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
> ---
>
> Hi Michael,
>
> I had been using .PP because I hadn't seen .br before.
>
> I think .br is the correct format,
> following the pattern in already existing man pages.
I don't disagree with the formatting change, but I am wondering if
there's a better way to do it. I tend to consider (perhaps wrongly)
that the use of .sp and .br is unidiomatic, and over the years I have
replaced a large of them with alternatives. (For example, in many
cases, .sp was being used when .PP should have been.)
If Branden does not tell us of something better, I will just apply
your patch as is.
> BTW, is there any way to copy the CC list with git send-email
> from the email I'm answering to?
> Right now I'm manually copying all of them each time from Thunderbird.
Sorry, I don't know. (Not really an answer to your question,
but are you also aware of "git format-patch --to=... --cc=..." ?)
Thanks,
Michael
^ permalink raw reply [flat|nested] 22+ messages in thread
* Re: [PATCH v2 1/3] system_data_types.7: ffix
2020-09-28 10:34 ` Michael Kerrisk (man-pages)
@ 2020-09-28 10:37 ` Alejandro Colomar
2020-09-28 11:13 ` G. Branden Robinson
1 sibling, 0 replies; 22+ messages in thread
From: Alejandro Colomar @ 2020-09-28 10:37 UTC (permalink / raw)
To: mtk.manpages; +Cc: linux-man, libc-alpha, G. Branden Robinson
Hi Michael,
On 2020-09-28 12:34, Michael Kerrisk (man-pages) wrote:
>> BTW, is there any way to copy the CC list with git send-email
>> from the email I'm answering to?
>> Right now I'm manually copying all of them each time from Thunderbird.
>
> Sorry, I don't know. (Not really an answer to your question,
> but are you also aware of "git format-patch --to=... --cc=..." ?)
Nope, I didn't. I'll try them :)
Thanks!
Alex
^ permalink raw reply [flat|nested] 22+ messages in thread
* Re: [PATCH 1/3] system_data_types.7: ffix
2020-09-28 5:59 ` [PATCH 1/3] system_data_types.7: ffix Michael Kerrisk (man-pages)
2020-09-28 9:03 ` [PATCH v2 " Alejandro Colomar
@ 2020-09-28 10:40 ` G. Branden Robinson
2020-09-28 10:51 ` Alejandro Colomar
1 sibling, 1 reply; 22+ messages in thread
From: G. Branden Robinson @ 2020-09-28 10:40 UTC (permalink / raw)
To: Michael Kerrisk (man-pages); +Cc: Alejandro Colomar, linux-man, libc-alpha
[-- Attachment #1: Type: text/plain, Size: 2748 bytes --]
At 2020-09-28T07:59:14+0200, Michael Kerrisk (man-pages) wrote:
> > Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
>
> I do think this requires an explanation saying what you are
> trying to do with this change (and then perhaps a more expansive
> "Subject" also).
>
> I can visually see what you are doing with this patch,
> but I do wonder if there is a better way of doing it.
>
> I've dropped Branden into CC. Perhaps he has a comment.
Hi Michael, yes--thank you!
In my opinion, use of "raw" *roff requests in a man page is a "code
smell".
Let me have a look...
> > diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
> > index 361e8d411..ff0403df9 100644
> > --- a/man7/system_data_types.7
> > +++ b/man7/system_data_types.7
> > @@ -66,7 +66,7 @@ system_data_types \- overview of system data types
> > .TP
> > .I aiocb
> > .RS
> > -.PP
> > +.br
> > Include:
> > .IR <aio.h> .
> > .PP
This is changed already from my most recent "git pull", so things are
moving fast indeed in this area! Here's what I show currently:
.\"------------------------------------- aiocb ------------------------/
.TP
.I aiocb
.IP
Include:
.IR <aio.h> .
.IP
.EX
struct aiocb {
So first the indented paragraph was replaced (or proposed to be
replaced) by a relative inset (.RS) and a paragraph break (.PP). It's
not visible in this diff where the relative inset ends, but I reckon
it's right before the next tagged paragraph (.TP).
Now, the .PP is being replaced by .br, I guess because you want to
eliminate some vertical space between the paragraph tag ("aiocb" in
italics above) and the following material?
However, .TP already does this for you when the tag is wider than the
paragraph indentation. You probably discovered this yourself with
"ptrdiff_t".
I get the feeling you're going for something specific in terms of visual
presentation.
What is it that you don't like about the following pattern?
.TP
.I typename_t
Include
.IR <header.h> .
.IP
.EX
struct typename {
// ...
}
.EE
.IP
Notes and commentary.
The above visually aligns everything by the type name with all the
material related to each type inset, which makes the page easy to scan.
Literal code is not filled, so code indentation is respected and (on
typesetters) the code be in a monospaced font so it will stand out and
align correctly. You don't have to manage insets with .RS and .RE, and
you can still have as many paragraphs as you want with .IP.
I have some guesses as to what might be bothering you, but I don't want
to put words in your mouth, and my mails tend to run too long anwyay, so
I won't voice them right now. :)
Regards,
Branden
[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]
^ permalink raw reply [flat|nested] 22+ messages in thread
* Re: [PATCH 1/3] system_data_types.7: ffix
2020-09-28 10:40 ` [PATCH " G. Branden Robinson
@ 2020-09-28 10:51 ` Alejandro Colomar
2020-09-28 12:49 ` G. Branden Robinson
0 siblings, 1 reply; 22+ messages in thread
From: Alejandro Colomar @ 2020-09-28 10:51 UTC (permalink / raw)
To: G. Branden Robinson, Michael Kerrisk (man-pages); +Cc: linux-man, libc-alpha
Hi Branden,
On 2020-09-28 12:40, G. Branden Robinson wrote:
> At 2020-09-28T07:59:14+0200, Michael Kerrisk (man-pages) wrote:
>>> Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
>>
>> I do think this requires an explanation saying what you are
>> trying to do with this change (and then perhaps a more expansive
>> "Subject" also).
>>
>> I can visually see what you are doing with this patch,
>> but I do wonder if there is a better way of doing it.
>>
>> I've dropped Branden into CC. Perhaps he has a comment.
>
> Hi Michael, yes--thank you!
>
> In my opinion, use of "raw" *roff requests in a man page is a "code
> smell".
>
> Let me have a look...
>
>>> diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
>>> index 361e8d411..ff0403df9 100644
>>> --- a/man7/system_data_types.7
>>> +++ b/man7/system_data_types.7
>>> @@ -66,7 +66,7 @@ system_data_types \- overview of system data types
>>> .TP
>>> .I aiocb
>>> .RS
>>> -.PP
>>> +.br
>>> Include:
>>> .IR <aio.h> .
>>> .PP
>
> This is changed already from my most recent "git pull", so things are
> moving fast indeed in this area! Here's what I show currently:
>
> .\"------------------------------------- aiocb ------------------------/
> .TP
> .I aiocb
> .IP
> Include:
> .IR <aio.h> .
> .IP
> .EX
> struct aiocb {
>
> So first the indented paragraph was replaced (or proposed to be
> replaced) by a relative inset (.RS) and a paragraph break (.PP). It's
> not visible in this diff where the relative inset ends, but I reckon
> it's right before the next tagged paragraph (.TP).
>
> Now, the .PP is being replaced by .br, I guess because you want to
> eliminate some vertical space between the paragraph tag ("aiocb" in
> italics above) and the following material?
>
> However, .TP already does this for you when the tag is wider than the
> paragraph indentation. You probably discovered this yourself with
> "ptrdiff_t".
>
> I get the feeling you're going for something specific in terms of visual
> presentation.
>
> What is it that you don't like about the following pattern?
>
> .TP
> .I typename_t
> Include
> .IR <header.h> .
> .IP
> .EX
> struct typename {
> // ...
> }
> .EE
> .IP
> Notes and commentary.
That's the first thing we tried; actually if I remember correctly,
that's what Michael suggested first.
But as you said, when we documented types with a long name such as
ptrdiff_t, the alginment broke: sometimes Include was in the same line,
and sometimes in the next one.
That's when we opted for
.\"------------------------------------- aiocb ------------------------/
.TP
.I aiocb
.IP
Include:
.IR <aio.h> .
.IP
.EX
struct aiocb {
>
> The above visually aligns everything by the type name with all the
> material related to each type inset, which makes the page easy to scan.
> Literal code is not filled, so code indentation is respected and (on
> typesetters) the code be in a monospaced font so it will stand out and
> align correctly. You don't have to manage insets with .RS and .RE, and
> you can still have as many paragraphs as you want with .IP.
Then, a few days ago, I pushed the change that you still didn't see:
Replace .IP with .RS/.RE + .PP
I'll refer to the patch for the rationale: it was a bit long. Basically,
it better represents a whole block, and it's easier to further indent:
https://lore.kernel.org/linux-man/16c0890e-33c0-d052-d7ee-39385cd79299@gmail.com/T/#m21da4dba4b3a44b0a59cad1e7eacb13a68a91636
This change actually didn't have visual effects; just source changes.
>
> I have some guesses as to what might be bothering you, but I don't want
> to put words in your mouth, and my mails tend to run too long anwyay, so
> I won't voice them right now. :)
>
> Regards,
> Branden
>
Thanks,
Alex
^ permalink raw reply [flat|nested] 22+ messages in thread
* Re: [PATCH v2 1/3] system_data_types.7: ffix
2020-09-28 10:34 ` Michael Kerrisk (man-pages)
2020-09-28 10:37 ` Alejandro Colomar
@ 2020-09-28 11:13 ` G. Branden Robinson
1 sibling, 0 replies; 22+ messages in thread
From: G. Branden Robinson @ 2020-09-28 11:13 UTC (permalink / raw)
To: Michael Kerrisk (man-pages); +Cc: Alejandro Colomar, linux-man, libc-alpha
[-- Attachment #1: Type: text/plain, Size: 3693 bytes --]
Hi Michael and Alex!
At 2020-09-28T12:34:40+0200, Michael Kerrisk (man-pages) wrote:
> On Mon, 28 Sep 2020 at 11:04, Alejandro Colomar <colomar.6.4.3@gmail.com> wrote:
> > I had been using .PP because I hadn't seen .br before.
> >
> > I think .br is the correct format,
> > following the pattern in already existing man pages.
>
> I don't disagree with the formatting change, but I am wondering if
> there's a better way to do it.
There are a few ways to skin cats in even the restricted dialect of
man(7) that I advocate. (The other groff developers seem to generally
agree, but I will admit that I am probably more puritanical and maniacal
than most of them. :) )
> I tend to consider (perhaps wrongly) that the use of .sp and .br is
> unidiomatic,
In my book you're certainly right. There are a few reasons for keeping
the lexicon of macros/requests appearing in man pages small.
1. man pages, far more than any other type of *roff source document, get
parsed by things are not *roff typesetting engines. The less *roff
they have to simulate, the easier it will be for them to achieve
intelligible rendering. mandoc(1) is probably the premier example in
this respect, and I believe I understand from its current developer
Ingo Schwarze that it handles rather more *roff than we would prefer.
There have also been numerous "man2html" processors developed over
the years, typically of somewhat dispiriting quality.
2. Even in the world of *roff typesetters there is diversity. For a
long time groff was the only freely-licensed game in town, but
nowadays I know of Heirloom Doctools, Plan 9, Solaris 10, DWB 3.3,
and neatroff implementations. The smaller the language, the easier
it is to get consensus and parity around portable constructs.
3. A smaller language is easier to learn and easier to retain for
people who are part-time documenters. A person who only tackles
documentation maintenance once every four to six months, say, is
going to have an easier time with a language with maybe two dozen
tags, several of which fall into groupings with a predictable naming
pattern, than they will with, say, the 417 tags of DocBook[1].
For groff 1.22.4, released in December 2018, I made sure to
front-load the groff_man(7) page with a quick reference for all
non-deprecated tags. My hope is that man page writers who have been
around the block with the man(7) language once before can type "man
groff_man" and be refreshed after having to hit the space bar at most
twice.
A corollary of point (3), especially when it comes to the mixing of
*roff requests with macros, is that their subtle interactions can be
frustrating to learners--and even to experienced users. Someone who
leans what .sp does may be surprised to find it not working between a
section heading (.SH) and the first line of text afterwards. Similar
frustrations can arise with the .in request when mixed with .RS and .RE.
> and over the years I have replaced a large of them with alternatives.
> (For example, in many cases, .sp was being used when .PP should have
> been.)
>
> If Branden does not tell us of something better, I will just apply
> your patch as is.
_Personally_, I prefer system_data_types(7) as of
efbe7900b931789849a978c619106a8973e679cd to any intrusion of .br
requests. And as a C programmer I find it clear enough.
I do wonder about the huge list of header files providing `size_t`, but
I guess my raised eyebrow is better aimed at the ISO C committee than
here. :)
Regards,
Branden
[1] https://tdg.docbook.org/tdg/4.5/docbook.html
[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]
^ permalink raw reply [flat|nested] 22+ messages in thread
* Re: [PATCH 1/3] system_data_types.7: ffix
2020-09-28 10:51 ` Alejandro Colomar
@ 2020-09-28 12:49 ` G. Branden Robinson
0 siblings, 0 replies; 22+ messages in thread
From: G. Branden Robinson @ 2020-09-28 12:49 UTC (permalink / raw)
To: Alejandro Colomar; +Cc: Michael Kerrisk (man-pages), linux-man, libc-alpha
[-- Attachment #1: Type: text/plain, Size: 25481 bytes --]
Hi Alex!
I'll reorganize the content below a bit.
At 2020-09-28T12:51:08+0200, Alejandro Colomar wrote:
> Then, a few days ago, I pushed the change that you still didn't see:
> Replace .IP with .RS/.RE + .PP
>
> I'll refer to the patch for the rationale: it was a bit long. Basically,
> it better represents a whole block, and it's easier to further indent:
>
> https://lore.kernel.org/linux-man/16c0890e-33c0-d052-d7ee-39385cd79299@gmail.com/T/#m21da4dba4b3a44b0a59cad1e7eacb13a68a91636
>
> This change actually didn't have visual effects; just source changes.
Ah, okay. That makes sense in context. If it were me, I'd put a big
comment block in the man page sources to explain to future contributors
why it is structured (macro-wise) the way it is.
> On 2020-09-28 12:40, G. Branden Robinson wrote:
> > What is it that you don't like about the following pattern?
> >
> > .TP
> > .I typename_t
> > Include
> > .IR <header.h> .
> > .IP
> > .EX
> > struct typename {
> > // ...
> > }
> > .EE
> > .IP
> > Notes and commentary.
>
> That's the first thing we tried; actually if I remember correctly,
> that's what Michael suggested first.
>
> But as you said, when we documented types with a long name such as
> ptrdiff_t, the alginment broke: sometimes Include was in the same line,
> and sometimes in the next one.
>
> That's when we opted for
>
> .\"------------------------------------- aiocb ------------------------/
> .TP
> .I aiocb
> .IP
> Include:
> .IR <aio.h> .
> .IP
> .EX
> struct aiocb {
Hmm, yes, I was afraid of that. :)
Okay, there are other ways I can think of to skin this cat, ad which
will keep you from having to resort to .br to suppress the
inter-paragraph space that .IP produces.
However, first consider whether you can live with the default
arrangement. In my opinion, when working with a man page, we should
first look to semantic correctness before worrying about presentation
issues. It is entirely typical for tagged paragraphs in man pages (and
other *roff macro sets, as it happens), to shift their paragraph
beginnings depending on the width of the tag. You are setting a
definition list, not a table--if you want a table, tbl(1) has been
around since the mid-1970s to help you include one. :)
Still, my protest may be feeble because I too sometimes get preoccupied
with presentation issues and in any event, when preparing documents for
publication you _do_ have to sweat this sort of question, along with the
dreaded widows and orphans.
So let me propose some alternatives.
Alternative #1
==============
I actually thought of this one _after_ writing up the three below. It's
a bit outside the box relative to those.
You could force the paragraph bodies to start on the next line by making
the tags wider, and one way to do that is by _describing what the data
types are_ in a few words. This might be the most pedagogically useful
thing to do.
As long as you don't make the tag so wide that it will need to break,
you should't have any formatting problems. Allocate yourself a budget
of a dozen words or forty columns and you should be well within the
limits of any reasonable page rendering.
So, for instance:
.TP
.IR aiocb "\~\- asynchronous I/O control block"
.TP
.IR size_t "\~\- object size (unsigned)"
Alternative #2
==============
Is it acceptable to you to have _all_ the paragraphs end up on the same
line as the text body? In other words, is consistency the main thing
you're going for?
If so, the best solution I can think of is to do something I gently
discourage people from doing, which is to use the argument to the .TP
macro to set the minimum indentation for the tagged paragraphs.
However, here, it seems the least bad approach to me that doesn't
involve content changes. I'm appending a patch to implement it, for
your and Michael's consideration (I also "git pull"ed first :) ).
I checked PostScript output and the tag width works there, too.
However, I see that the comments in the aiocb struct overrun the right
margin a bit. (The rest of the page looks fine, though, or very close
to it.) Maybe that is why you _don't_ want to use this approach. If
that is the case, let's move on to...
Alternative #3
==============
I feel a little bit dirty suggesting this, but it doesn't break any of
the portability rules I prescribe in groff_man_style(7)[1], so I guess
I'm not a hypocrite for doing so...
Use the .TQ macro to add an additional tag, and then make that tag
empty.
So:
.TP
.I aiocb
.TQ
\&
Include:
.IR <aio.h> .
.IP
.EX
struct aiocb {
.TQ is a GNU extension dating back almost 14 years; but man-pages
already uses the .UR/.UE GNU extensions widely to mark up URLs, and .TQ
in one other place that I can see (keyctl.2, where it is used
idiomatically).
The above is a slight offense to the semantic markup gods, but I would
argue it's an excusable one because there's nothing sensible to
associate a null tag with, just like with ".IP \&". A semantic parser
should discard it.
There's a story behind \& and what to call it, but for the time being
the main thing to know is that it's portable; it's documented all the
way back in M. E. Lesk's nroff/troff User's Manual of 1976.
Perhaps a better solution would be for someone like me to expand the
interface of .TP to accept a second argument (the first is the tag width
in ens, and has been since 1979--it won't help for your use case) to
force a break before starting the paragraph body. A nice thing about
this approach is that it would fail gracefully with implementations that
don't support it; *roff macros are almost universally written to ignore
parameters that they don't require. By "fail gracefully", I mean you'll
get output that doesn't look any worse than the mixed-alignment
paragraph starts, which I don't think constitute a barrier to
reader understanding.
Alternative #4
==============
I can think of one other alternative--use tbl(1). However, that is a
pretty big gun for a problem of this size, and given the format you're
shooting for you're going to have lengthy "text blocks" for the right
column of every table row. Follow-up if you want to hear more about it.
Regards,
Branden
[1] https://man7.org/linux/man-pages/man7/groff_man_style.7.html
From 0c71d88532388dec5d308a497acb3487d6f2d9e9 Mon Sep 17 00:00:00 2001
From: "G. Branden Robinson" <g.branden.robinson@gmail.com>
Date: Mon, 28 Sep 2020 22:21:09 +1000
Subject: [PATCH] man7/system_data_types.7: ffix
Indent idiomatically.
Use an explicit indentation argument to the first tagged paragraph .TP
to accommodate the documented type with the widest name, suseconds_t.
The remaining .TP and .IP paragraphs at this nesting level will re-use
it automatically.
Use indented paragraphs (.IP) instead of ordinary ones (.PP) inside
relative insets (.RS/.RE) for discussion of each data type.
Document values of FLT_EVAL_METHOD inside a doubly-inset region.
---
man7/system_data_types.7 | 321 +++++++++++++++------------------------
1 file changed, 121 insertions(+), 200 deletions(-)
diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
index 6d24dee2f..aa05d38a9 100644
--- a/man7/system_data_types.7
+++ b/man7/system_data_types.7
@@ -63,13 +63,11 @@ system_data_types \- overview of system data types
.\"
.\" * See also
.\"------------------------------------- aiocb ------------------------/
-.TP
+.TP 12n \" wide enough for "suseconds_t"
.I aiocb
-.RS
-.br
Include:
.IR <aio.h> .
-.PP
+.IP
.EX
struct aiocb {
int aio_fildes; /* File descriptor */
@@ -81,12 +79,12 @@ struct aiocb {
int aio_lio_opcode;/* Operation to be performed */
};
.EE
-.PP
+.IP
For further information about this structure, see
.BR aio (7).
-.PP
+.IP
Conforming to: POSIX.1-2001 and later.
-.PP
+.IP
See also:
.BR aio_cancel (3),
.BR aio_error (3),
@@ -96,45 +94,41 @@ See also:
.BR aio_suspend (3),
.BR aio_write (3),
.BR lio_listio (3)
-.RE
.\"------------------------------------- div_t ------------------------/
.TP
.I div_t
-.RS
-.br
Include:
.IR <stdlib.h> .
-.PP
+.IP
.EX
typedef struct {
int quot; /* Quotient */
int rem; /* Remainder */
} div_t;
.EE
-.PP
+.IP
It is the type of the value returned by the
.BR div (3)
function.
-.PP
+.IP
Conforming to: C99 and later; POSIX.1-2001 and later.
-.PP
+.IP
See also:
.BR div (3)
-.RE
.\"------------------------------------- double_t ---------------------/
.TP
.I double_t
-.RS
-.br
Include:
.IR <math.h> .
-.PP
+.IP
The implementation's most efficient floating type at least as wide as
.IR double .
Its type depends on the value of the macro
.B FLT_EVAL_METHOD
(defined in
.IR <float.h> ):
+.RS
+.RS
.TP
0
.I double_t
@@ -150,67 +144,62 @@ is
.I double_t
is
.IR "long double" .
-.PP
+.RE
+.RE
+.IP
For other values of
.BR FLT_EVAL_METHOD ,
the type of
.I double_t
is implementation-defined.
-.PP
+.IP
Conforming to: C99 and later; POSIX.1-2001 and later.
-.PP
+.IP
See also the
.I float_t
type in this page.
-.RE
.\"------------------------------------- fenv_t -----------------------/
.TP
.I fenv_t
-.RS
-.br
Include:
.IR <fenv.h> .
-.PP
+.IP
This type represents the entire floating-point environment,
including control modes and status flags; for further details, see
.BR fenv (3).
-.PP
+.IP
Conforming to: C99 and later; POSIX.1-2001 and later.
-.PP
+.IP
See also:
.BR fenv (3)
-.RE
.\"------------------------------------- fexcept_t --------------------/
.TP
.I fexcept_t
-.RS
-.br
Include:
.IR <fenv.h> .
-.PP
+.IP
This type represents the floating-point status flags collectively;
for further details see
.BR fenv (3).
-.PP
+.IP
Conforming to: C99 and later; POSIX.1-2001 and later.
-.PP
+.IP
See also:
.BR fenv (3)
-.RE
.\"------------------------------------- float_t ----------------------/
.TP
.I float_t
-.RS
-.br
Include:
.IR <math.h> .
-.PP
+.IP
The implementation's most efficient floating type at least as wide as
.IR float .
Its type depends on the value of the macro
.B FLT_EVAL_METHOD
(defined in
.IR <float.h> ):
+.RS
+.RS
.TP
0
.I float_t
@@ -226,24 +215,23 @@ is
.I float_t
is
.IR "long double" .
-.PP
+.RE
+.RE
+.IP
For other values of
.BR FLT_EVAL_METHOD ,
the type of
.I float_t
is implementation-defined.
-.PP
+.IP
Conforming to: C99 and later; POSIX.1-2001 and later.
-.PP
+.IP
See also the
.I double_t
type in this page.
-.RE
.\"------------------------------------- gid_t ------------------------/
.TP
.I gid_t
-.RS
-.br
Include:
.IR <sys/types.h> ;
or
@@ -260,13 +248,13 @@ or
.I <sys/stat.h>
or
.IR <unistd.h> .
-.PP
+.IP
A type used to hold group IDs.
According to POSIX,
this shall be an integer type.
-.PP
+.IP
Conforming to: POSIX.1-2001 and later.
-.PP
+.IP
See also:
.BR chown (2),
.BR getgid (2),
@@ -275,17 +263,14 @@ See also:
.BR getresgid (2),
.BR getgrnam (2),
.BR credentials (7)
-.RE
.\"------------------------------------- id_t -------------------------/
.TP
.I id_t
-.RS
-.br
Include:
.IR <sys/types.h> ;
or
.IR <sys/resource.h> .
-.PP
+.IP
A type used to hold a general identifier.
According to POSIX,
this shall be an integer type that can be used to contain a
@@ -293,45 +278,39 @@ this shall be an integer type that can be used to contain a
.IR uid_t ,
or
.IR gid_t .
-.PP
+.IP
Conforming to: POSIX.1-2001 and later.
-.PP
+.IP
See also:
.BR getpriority (2),
.BR waitid (2)
-.RE
.\"------------------------------------- imaxdiv_t --------------------/
.TP
.I imaxdiv_t
-.RS
-.br
Include:
.IR <inttypes.h> .
-.PP
+.IP
.EX
typedef struct {
intmax_t quot; /* Quotient */
intmax_t rem; /* Remainder */
} imaxdiv_t;
.EE
-.PP
+.IP
It is the type of the value returned by the
.BR imaxdiv (3)
function.
-.PP
+.IP
Conforming to: C99 and later; POSIX.1-2001 and later.
-.PP
+.IP
See also:
.BR imaxdiv (3)
-.RE
.\"------------------------------------- lconv ------------------------/
.TP
.I lconv
-.RS
-.br
Include:
.IR <locale.h> .
-.PP
+.IP
.EX
struct lconv { /* Values in the "C" locale: */
char *decimal_point; /* "." */
@@ -360,72 +339,63 @@ struct lconv { /* Values in the "C" locale: */
char int_n_sign_posn; /* CHAR_MAX */
};
.EE
-.PP
+.IP
Contains members related to the formatting of numeric values.
In the "C" locale, its members have the values
shown in the comments above.
-.PP
+.IP
Conforming to: C11 and later; POSIX.1-2001 and later.
-.PP
+.IP
See also:
.BR setlocale (3),
.BR localeconv (3),
.BR charsets (5),
.BR locale (7)
-.RE
.\"------------------------------------- ldiv_t -----------------------/
.TP
.I ldiv_t
-.RS
-.br
Include:
.IR <stdlib.h> .
-.PP
+.IP
.EX
typedef struct {
long quot; /* Quotient */
long rem; /* Remainder */
} ldiv_t;
.EE
-.PP
+.IP
It is the type of the value returned by the
.BR ldiv (3)
function.
-.PP
+.IP
Conforming to: C99 and later; POSIX.1-2001 and later.
-.PP
+.IP
See also:
.BR ldiv (3)
-.RE
.\"------------------------------------- lldiv_t ----------------------/
.TP
.I lldiv_t
-.RS
-.br
Include:
.IR <stdlib.h> .
-.PP
+.IP
.EX
typedef struct {
long long quot; /* Quotient */
long long rem; /* Remainder */
} lldiv_t;
.EE
-.PP
+.IP
It is the type of the value returned by the
.BR lldiv (3)
function.
-.PP
+.IP
Conforming to: C99 and later; POSIX.1-2001 and later.
-.PP
+.IP
See also:
.BR lldiv (3)
-.RE
.\"------------------------------------- pid_t ------------------------/
.TP
.I pid_t
-.RS
-.br
Include
.IR <sys/types.h> ;
or
@@ -452,7 +422,7 @@ or
.I <unistd.h>
or
.IR <utmpx.h> .
-.PP
+.IP
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
@@ -460,9 +430,9 @@ where the width of
.I pid_t
is no greater than the width of the type
.IR long .
-.PP
+.IP
Conforming to: POSIX.1-2001 and later.
-.PP
+.IP
See also:
.BR fork (2),
.BR getpid (2),
@@ -476,22 +446,19 @@ See also:
.BR waitpid (2),
.BR sigqueue (3),
.BR credentials (7),
-.RE
.\"------------------------------------- ptrdiff_t --------------------/
.TP
.I ptrdiff_t
-.RS
-.br
Include:
.IR <stddef.h> .
-.PP
+.IP
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 ].
-.PP
+.IP
The length modifier for
.I ptrdiff_t
for the
@@ -507,23 +474,20 @@ or
for printing
.I ptrdiff_t
values.
-.PP
+.IP
Conforming to: C99 and later; POSIX.1-2001 and later.
-.PP
+.IP
See also the
.I size_t
and
.I ssize_t
types in this page.
-.RE
.\"------------------------------------- regmatch_t -------------------/
.TP
.I regmatch_t
-.RS
-.br
Include:
.IR <regex.h> .
-.PP
+.IP
.EX
typedef struct {
regoff_t rm_so; /* Byte offset from start of string
@@ -533,38 +497,35 @@ typedef struct {
substring */
} regmatch_t;
.EE
-.PP
+.IP
This is a structure type used in regular expression matching.
-.PP
+.IP
Conforming to: POSIX.1-2001 and later.
-.PP
+.IP
See also:
.BR regexec (3)
-.RE
.\"------------------------------------- regoff_t ---------------------/
.TP
.I regoff_t
-.RS
-.br
Include:
.IR <regex.h> .
-.PP
+.IP
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.
-.PP
+.IP
Conforming to: POSIX.1-2001 and later.
-.PP
+.IP
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.
-.PP
+.IP
See also the
.I regmatch_t
structure and the
@@ -572,12 +533,9 @@ structure and the
and
.I ssize_t
types in this page.
-.RE
.\"------------------------------------- sigevent ---------------------/
.TP
.I sigevent
-.RS
-.br
Include:
.IR <signal.h> ;
or
@@ -586,7 +544,7 @@ or
.I <mqueue.h>
or
.IR <time.h> .
-.PP
+.IP
.EX
struct sigevent {
int sigev_notify; /* Notification type */
@@ -598,12 +556,12 @@ struct sigevent {
/* Notification attributes */
};
.EE
-.PP
+.IP
For further details about this type, see
.BR sigevent (7).
-.PP
+.IP
Conforming to: POSIX.1-2001 and later.
-.PP
+.IP
Notes:
.I <aio.h>
and
@@ -611,27 +569,24 @@ and
define
.I sigevent
since POSIX.1-2008.
-.PP
+.IP
See also:
.BR timer_create (2),
.BR getaddrinfo_a (3),
.BR lio_listio (3),
.BR mq_notify (3)
-.PP
+.IP
See also the
.I aiocb
structure in this page.
-.RE
.\"------------------------------------- siginfo_t --------------------/
.TP
.I siginfo_t
-.RS
-.br
Include:
.IR <signal.h> ;
or
.IR <sys/wait.h> .
-.PP
+.IP
.EX
typedef struct {
int si_signo; /* Signal number */
@@ -643,38 +598,35 @@ typedef struct {
union sigval si_value; /* Signal value */
} siginfo_t;
.EE
-.PP
+.IP
Information associated with a signal.
For further details on this structure
(including additional, Linux-specific fields), see
.BR sigaction (2).
-.PP
+.IP
Conforming to: POSIX.1-2001 and later.
-.PP
+.IP
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
-.RS
-.br
Include:
.IR <signal.h> ;
or
.I <spawn.h>
or
.IR <sys/select.h> .
-.PP
+.IP
This is a type that represents a set of signals.
According to POSIX, this shall be an integer or structure type.
-.PP
+.IP
Conforming to: POSIX.1-2001 and later.
-.PP
+.IP
See also:
.BR epoll_pwait (2),
.BR ppoll (2),
@@ -686,31 +638,28 @@ See also:
.BR sigsuspend (2),
.BR sigwaitinfo (2),
.BR signal (7)
-.RE
.\"------------------------------------- sigval -----------------------/
.TP
.I sigval
-.RS
-.br
Include:
.IR <signal.h> .
-.PP
+.IP
.EX
union sigval {
int sigval_int; /* Integer value */
void *sigval_ptr; /* Pointer value */
};
.EE
-.PP
+.IP
Data passed with a signal.
-.PP
+.IP
Conforming to: POSIX.1-2001 and later.
-.PP
+.IP
See also:
.BR pthread_sigqueue (3),
.BR sigqueue (3),
.BR sigevent (7)
-.PP
+.IP
See also the
.I sigevent
structure
@@ -718,12 +667,9 @@ and the
.I siginfo_t
type
in this page.
-.RE
.\"------------------------------------- size_t -----------------------/
.TP
.I size_t
-.RS
-.br
Include:
.I <stddef.h>
or
@@ -778,7 +724,7 @@ or
.I <wchar.h>
or
.IR <wordexp.h> .
-.PP
+.IP
Used for a count of bytes. It is the result of the
.I sizeof
operator.
@@ -792,7 +738,7 @@ where the width of
.I size_t
is no greater than the width of the type
.IR long .
-.PP
+.IP
The length modifier for
.I size_t
for the
@@ -808,9 +754,9 @@ or
for printing
.I size_t
values.
-.PP
+.IP
Conforming to: C99 and later; POSIX.1-2001 and later.
-.PP
+.IP
Notes:
.IR <aio.h> ,
.IR <glob.h> ,
@@ -824,7 +770,7 @@ and
define
.I size_t
since POSIX.1-2008.
-.PP
+.IP
See also:
.BR read (2),
.BR write (2),
@@ -835,18 +781,15 @@ See also:
.BR memcpy (3),
.BR memset (3),
.BR offsetof (3)
-.PP
+.IP
See also the
.I ptrdiff_t
and
.I ssize_t
types in this page.
-.RE
.\"------------------------------------- ssize_t ----------------------/
.TP
.I ssize_t
-.RS
-.br
Include:
.IR <sys/types.h> ;
or
@@ -865,7 +808,7 @@ or
.I <sys/uio.h>
or
.IR <unistd.h> .
-.PP
+.IP
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,
@@ -875,7 +818,7 @@ where the width of
.I ssize_t
is no greater than the width of the type
.IR long .
-.PP
+.IP
Glibc and most other implementations provide a length modifier for
.I ssize_t
for the
@@ -901,9 +844,9 @@ by converting the value to
.I intmax_t
and using its length modifier
.RB ( j ).
-.PP
+.IP
Conforming to: POSIX.1-2001 and later.
-.PP
+.IP
See also:
.BR read (2),
.BR readlink (2),
@@ -911,25 +854,22 @@ See also:
.BR recv (2),
.BR send (2),
.BR write (2)
-.PP
+.IP
See also the
.I ptrdiff_t
and
.I size_t
types in this page.
-.RE
.\"------------------------------------- suseconds_t ------------------/
.TP
.I suseconds_t
-.RS
-.br
Include:
.IR <sys/types.h> ;
or
.I <sys/select.h>
or
.IR <sys/time.h> .
-.PP
+.IP
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],
@@ -938,18 +878,15 @@ where the width of
.I suseconds_t
is no greater than the width of the type
.IR long .
-.PP
+.IP
Conforming to: POSIX.1-2001 and later.
-.PP
+.IP
See also the
.I timeval
structure in this page.
-.RE
.\"------------------------------------- time_t -----------------------/
.TP
.I time_t
-.RS
-.br
Include:
.I <sys/types.h>
or
@@ -970,52 +907,46 @@ or
.I <sys/time.h>
or
.IR <utime.h> .
-.PP
+.IP
Used for time in seconds.
According to POSIX, it shall be an integer type.
-.PP
+.IP
Conforming to: C99 and later; POSIX.1-2001 and later.
-.PP
+.IP
Notes:
.I <sched.h>
defines
.I time_t
since POSIX.1-2008.
-.PP
+.IP
See also:
.BR stime (2),
.BR time (2),
.BR ctime (3),
.BR difftime (3)
-.RE
.\"------------------------------------- timer_t ----------------------/
.TP
.I timer_t
-.RS
-.br
Include:
.IR <sys/types.h> ;
or
.IR <time.h> .
-.PP
+.IP
Used for timer ID returned by
.BR timer_create (2).
According to POSIX,
there are no defined comparison or assignment operators for this type.
-.PP
+.IP
Conforming to: POSIX.1-2001 and later.
-.PP
+.IP
See also:
.BR timer_create (2),
.BR timer_delete (2),
.BR timer_getoverrun (2),
.BR timer_settime (2)
-.RE
.\"------------------------------------- timespec ---------------------/
.TP
.I timespec
-.RS
-.br
Include:
.IR <time.h> ;
or
@@ -1030,30 +961,27 @@ or
.I <sys/select.h>
or
.IR <sys/stat.h> .
-.PP
+.IP
.EX
struct timespec {
time_t tv_sec; /* Seconds */
long tv_nsec; /* Nanoseconds */
};
.EE
-.PP
+.IP
Describes times in seconds and nanoseconds.
-.PP
+.IP
Conforming to: C11 and later; POSIX.1-2001 and later.
-.PP
+.IP
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
-.RS
-.br
Include:
.IR <sys/time.h> ;
or
@@ -1062,18 +990,18 @@ or
.I <sys/select.h>
or
.IR <utmpx.h> .
-.PP
+.IP
.EX
struct timeval {
time_t tv_sec; /* Seconds */
suseconds_t tv_usec; /* Microseconds */
};
.EE
-.PP
+.IP
Describes times in seconds and microseconds.
-.PP
+.IP
Conforming to: POSIX.1-2001 and later.
-.PP
+.IP
See also:
.BR gettimeofday (2),
.BR select (2),
@@ -1081,12 +1009,9 @@ See also:
.BR adjtime (3),
.BR futimes (3),
.BR timeradd (3)
-.RE
.\"------------------------------------- uid_t ----------------------/
.TP
.I uid_t
-.RS
-.br
Include:
.IR <sys/types.h> ;
or
@@ -1101,13 +1026,13 @@ or
.I <sys/stat.h>
or
.IR <unistd.h> .
-.PP
+.IP
A type used to hold user IDs.
According to POSIX,
this shall be an integer type.
-.PP
+.IP
Conforming to: POSIX.1-2001 and later.
-.PP
+.IP
See also:
.BR chown (2),
.BR getuid (2),
@@ -1115,19 +1040,16 @@ See also:
.BR getresuid (2),
.BR getpwnam (2),
.BR credentials (7)
-.RE
.\"------------------------------------- va_list ----------------------/
.TP
.I va_list
-.RS
-.br
Include:
.IR <stdarg> ;
or
.I <stdio.h>
or
.IR <wchar.h> .
-.PP
+.IP
Used by functions with a varying number of arguments of varying types.
The function must declare an object of type
.I va_list
@@ -1138,15 +1060,14 @@ which is used by the macros
and
.BR va_end (3)
to traverse the list of arguments.
-.PP
+.IP
Conforming to: C99 and later; POSIX.1-2001 and later.
-.PP
+.IP
See also:
.BR va_start (3),
.BR va_arg (3),
.BR va_copy (3),
.BR va_end (3)
-.RE
.\"--------------------------------------------------------------------/
.SH NOTES
The structures described in this manual page shall contain,
--
2.20.1
[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]
^ permalink raw reply related [flat|nested] 22+ messages in thread
* Re: [PATCH v2 1/3] system_data_types.7: ffix
2020-09-28 9:03 ` [PATCH v2 " Alejandro Colomar
2020-09-28 10:34 ` Michael Kerrisk (man-pages)
@ 2020-09-28 13:06 ` G. Branden Robinson
2020-09-28 13:44 ` Alejandro Colomar
1 sibling, 1 reply; 22+ messages in thread
From: G. Branden Robinson @ 2020-09-28 13:06 UTC (permalink / raw)
To: Alejandro Colomar; +Cc: mtk.manpages, linux-man, libc-alpha
[-- Attachment #1: Type: text/plain, Size: 1158 bytes --]
Hi Alex!
At 2020-09-28T11:03:23+0200, Alejandro Colomar wrote:
> Normally, text under a section header starts in the next line after
> the header, without a blank line. Follow that pattern.
I think your terminology could confuse some people. A section heading
in a man page is what is typeset by the .SH macro. For instance, ".SH
Name", ".SH See also", and so forth[1].
In the below, "aiocb" (in italics) is properly termed a "paragraph tag",
hence the mnemonic for the macro right before it: "TP" for "tagged
paragraph".
Just FYI.
[...]
> diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
> index 361e8d411..ff0403df9 100644
> --- a/man7/system_data_types.7
> +++ b/man7/system_data_types.7
> @@ -66,7 +66,7 @@ system_data_types \- overview of system data types
> .TP
> .I aiocb
> .RS
> -.PP
> +.br
> Include:
> .IR <aio.h> .
> .PP
> @@ -101,7 +101,7 @@ See also:
Regards,
Branden
[1] Often section headings are written in full capitals in man page
source documents, which loses information. The next release of groff
will feature support for mixed-case section headings with optional
full-caps rendering under user control.
[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]
^ permalink raw reply [flat|nested] 22+ messages in thread
* Re: [PATCH v2 1/3] system_data_types.7: ffix
2020-09-28 13:06 ` G. Branden Robinson
@ 2020-09-28 13:44 ` Alejandro Colomar
2020-09-30 10:43 ` G. Branden Robinson
0 siblings, 1 reply; 22+ messages in thread
From: Alejandro Colomar @ 2020-09-28 13:44 UTC (permalink / raw)
To: G. Branden Robinson; +Cc: mtk.manpages, linux-man, libc-alpha
Hi Branden & Michael,
On 2020-09-28 15:06, G. Branden Robinson wrote:
> Hi Alex!
>
> At 2020-09-28T11:03:23+0200, Alejandro Colomar wrote:
>> Normally, text under a section header starts in the next line after
>> the header, without a blank line. Follow that pattern.
>
> I think your terminology could confuse some people. A section heading
> in a man page is what is typeset by the .SH macro. For instance, ".SH
> Name", ".SH See also", and so forth[1].
>
> In the below, "aiocb" (in italics) is properly termed a "paragraph tag",
> hence the mnemonic for the macro right before it: "TP" for "tagged
> paragraph".
>
> Just FYI.
I did mean .SH:
For each type we're separating the paragraphs by description,
conforming to, see also, ... similar to the .SH sections.
And therefore, I thought that we should use the same format for
consistency: After the title, or in this case the tag,
there should be no blank line.
However, if using .br is a big headache, I would rather not use
workarounds (as you proposed in an earlier email),
and instead just live with the blank line. It's not much of a problem.
But Michael did already apply the patch (was it by mistake? or did you
agree with the patch, Michael?)
I leave it up to you to decide what to do, Michael.
My proposals:
If you prefer consistency in the source, I'd rather not use
workarounds: I'd just leave .PP, and accept the blank line
I see those workarounds uglier than .br.
If you however prefer consistency in the visual page,
I'd use .br, or something that doesn't look like a workaround.
Regards,
Alex
>
> [...]
>> diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
>> index 361e8d411..ff0403df9 100644
>> --- a/man7/system_data_types.7
>> +++ b/man7/system_data_types.7
>> @@ -66,7 +66,7 @@ system_data_types \- overview of system data types
>> .TP
>> .I aiocb
>> .RS
>> -.PP
>> +.br
>> Include:
>> .IR <aio.h> .
>> .PP
>> @@ -101,7 +101,7 @@ See also:
>
> Regards,
> Branden
>
> [1] Often section headings are written in full capitals in man page
> source documents, which loses information. The next release of groff
> will feature support for mixed-case section headings with optional
> full-caps rendering under user control.
>
^ permalink raw reply [flat|nested] 22+ messages in thread
* Re: [PATCH v2 2/3] system_data_types.7: Add 'FILE'
2020-09-28 9:06 ` [PATCH v2 " Alejandro Colomar
@ 2020-09-29 13:15 ` Alejandro Colomar
2020-09-29 13:35 ` Michael Kerrisk (man-pages)
0 siblings, 1 reply; 22+ messages in thread
From: Alejandro Colomar @ 2020-09-29 13:15 UTC (permalink / raw)
To: mtk.manpages; +Cc: linux-man, libc-alpha, g.branden.robinson
Hi Michael,
Ping -c2 :)
patches 2/3 and 3/3 of this set are pending,
the patch which was holding them has already been applied,
and should have no conflicts in the current HEAD (tell me if otherwise).
Thanks,
Alex
On 2020-09-28 11:06, Alejandro Colomar wrote:
> Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
> ---
> man7/system_data_types.7 | 23 +++++++++++++++++++++++
> 1 file changed, 23 insertions(+)
>
> Hi Michael,
>
> Please hold until the ffix is applied (or not).
>
> Thanks,
>
> Alex
>
> diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
> index ff0403df9..16930985e 100644
> --- a/man7/system_data_types.7
> +++ b/man7/system_data_types.7
> @@ -197,6 +197,29 @@ Conforming to: C99 and later; POSIX.1-2001 and later.
> See also:
> .BR fenv (3)
> .RE
> +.\"------------------------------------- FILE -------------------------/
> +.TP
> +.I FILE
> +.RS
> +.br
> +Include:
> +.IR <stdio.h> ;
> +or
> +.IR <wchar.h> .
> +.PP
> +An object type used for streams.
> +.PP
> +Conforming to: C99 and later; POSIX.1-2001 and later.
> +.PP
> +See also:
> +.BR fclose (3),
> +.BR flockfile (3),
> +.BR fopen (3),
> +.BR fprintf (3),
> +.BR fread (3),
> +.BR fscanf (3),
> +.BR stdin (3),
> +.BR stdio (3)
> +.RE
> .\"------------------------------------- float_t ----------------------/
> .TP
> .I float_t
>
^ permalink raw reply [flat|nested] 22+ messages in thread
* Re: [PATCH v2 2/3] system_data_types.7: Add 'FILE'
2020-09-29 13:15 ` Alejandro Colomar
@ 2020-09-29 13:35 ` Michael Kerrisk (man-pages)
0 siblings, 0 replies; 22+ messages in thread
From: Michael Kerrisk (man-pages) @ 2020-09-29 13:35 UTC (permalink / raw)
To: Alejandro Colomar; +Cc: mtk.manpages, linux-man, libc-alpha, g.branden.robinson
On 9/29/20 3:15 PM, Alejandro Colomar wrote:
> Hi Michael,
>
> Ping -c2 :)
>
> patches 2/3 and 3/3 of this set are pending,
> the patch which was holding them has already been applied,
> and should have no conflicts in the current HEAD (tell me if otherwise).
Thanks for the prod! Those two patches are applied and pushed.
Thanks,
Michael
> On 2020-09-28 11:06, Alejandro Colomar wrote:
>> Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
>> ---
>> man7/system_data_types.7 | 23 +++++++++++++++++++++++
>> 1 file changed, 23 insertions(+)
>>
>> Hi Michael,
>>
>> Please hold until the ffix is applied (or not).
>>
>> Thanks,
>>
>> Alex
>>
>> diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
>> index ff0403df9..16930985e 100644
>> --- a/man7/system_data_types.7
>> +++ b/man7/system_data_types.7
>> @@ -197,6 +197,29 @@ Conforming to: C99 and later; POSIX.1-2001 and later.
>> See also:
>> .BR fenv (3)
>> .RE
>> +.\"------------------------------------- FILE -------------------------/
>> +.TP
>> +.I FILE
>> +.RS
>> +.br
>> +Include:
>> +.IR <stdio.h> ;
>> +or
>> +.IR <wchar.h> .
>> +.PP
>> +An object type used for streams.
>> +.PP
>> +Conforming to: C99 and later; POSIX.1-2001 and later.
>> +.PP
>> +See also:
>> +.BR fclose (3),
>> +.BR flockfile (3),
>> +.BR fopen (3),
>> +.BR fprintf (3),
>> +.BR fread (3),
>> +.BR fscanf (3),
>> +.BR stdin (3),
>> +.BR stdio (3)
>> +.RE
>> .\"------------------------------------- float_t ----------------------/
>> .TP
>> .I float_t
>>
--
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
^ permalink raw reply [flat|nested] 22+ messages in thread
* Re: [PATCH v2 1/3] system_data_types.7: ffix
2020-09-28 13:44 ` Alejandro Colomar
@ 2020-09-30 10:43 ` G. Branden Robinson
2020-09-30 21:32 ` Alejandro Colomar
0 siblings, 1 reply; 22+ messages in thread
From: G. Branden Robinson @ 2020-09-30 10:43 UTC (permalink / raw)
To: Alejandro Colomar; +Cc: mtk.manpages, linux-man, libc-alpha
[-- Attachment #1: Type: text/plain, Size: 2633 bytes --]
At 2020-09-28T15:44:46+0200, Alejandro Colomar wrote:
> I did mean .SH:
>
> For each type we're separating the paragraphs by description,
> conforming to, see also, ... similar to the .SH sections.
Okay, I see; you were using an analogy.
> And therefore, I thought that we should use the same format for
> consistency: After the title, or in this case the tag,
> there should be no blank line.
>
> However, if using .br is a big headache, I would rather not use
> workarounds (as you proposed in an earlier email),
> and instead just live with the blank line. It's not much of a
> problem.
Was an actual decision taken on this? I see patches continuing to roll
in containing this .br-based pattern. I think if the extra line is
live-withable, it should be lived with (or one of my four proposed
alternatives could be used :) ), in preference to setting the bad
example of the "naked" .br requests.
man page markup is highly prone to cargo-culting; on the groff list not
too long ago, some sleuthing revealed an example of a typo that crept
into the X Window System man pages over 30 years ago and was not only
diligently retained there but faithfully copied elsewhere by people who
didn't realize what they were copying[1].
> I leave it up to you to decide what to do, Michael.
>
> My proposals:
> If you prefer consistency in the source, I'd rather not use
> workarounds: I'd just leave .PP, and accept the blank line
> I see those workarounds uglier than .br.
Too bad for me. But I admit I'm not proud of that .TQ thing. :P
> If you however prefer consistency in the visual page,
That's not how it appears to me; I may be bringing too much insider
knowledge to the question, but I know when I see them that the things
you've termed section headings aren't true section headings. Primarily
I can tell by the fact that their indentation is wrong for an .SH macro.
But the knowledge isn't all that far inside. The worst hand-written man
page I have ever seen in my life, or expect to see, was written by
Albert Cahalan, who hated *roff with a passion I have reserved only for
love affairs. He learned just enough of the language to subvert man-db
and groff into accepting his plain-text document as a man page[2].
I don't know what ever became of Mr. Cahalan, but I imagine that he is
somewhere working on processing Markdown with XML:FO and enjoying
himself immensely.
Regards,
Branden
[1] https://lists.gnu.org/archive/html/groff/2019-03/msg00047.html
[2] https://gitlab.com/procps-ng/procps/blob/7ac9a0e1f5606696dc799b773d5ec70183ca91a3/ps/ps.1
[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]
^ permalink raw reply [flat|nested] 22+ messages in thread
* Re: [PATCH v2 1/3] system_data_types.7: ffix
2020-09-30 10:43 ` G. Branden Robinson
@ 2020-09-30 21:32 ` Alejandro Colomar
2020-10-01 7:37 ` Michael Kerrisk (man-pages)
0 siblings, 1 reply; 22+ messages in thread
From: Alejandro Colomar @ 2020-09-30 21:32 UTC (permalink / raw)
To: G. Branden Robinson, mtk.manpages; +Cc: linux-man, libc-alpha
Hi Branden & Michael,
On 2020-09-30 12:43, G. Branden Robinson wrote:
>> However, if using .br is a big headache, I would rather not use
>> workarounds (as you proposed in an earlier email),
>> and instead just live with the blank line. It's not much of a
>> problem.
>
> Was an actual decision taken on this? I see patches continuing to roll
> in containing this .br-based pattern. I think if the extra line is
> live-withable, it should be lived with (or one of my four proposed
> alternatives could be used :) ), in preference to setting the bad
> example of the "naked" .br requests.
No decision yet.
We continued with the patch,
considering that we might revert it
or change it to a different approach in the future.
Actually I thought Michael would have hold the patches until the decision,
but he merged them, and it may be easier this way...
we'll fix it when we decide.
For me, I can live with the extra blank line.
Michael, what are your thoughts?
>
> man page markup is highly prone to cargo-culting; on the groff list not
> too long ago, some sleuthing revealed an example of a typo that crept
> into the X Window System man pages over 30 years ago and was not only
> diligently retained there but faithfully copied elsewhere by people who
> didn't realize what they were copying[1].
As someone who has written man-pages only for about a month,
I completely ignore the problems about using .br.
I see it easy in my mind:
I want a line break (without fancy paragraph stuff), I write .br.
I guess it's somewhat more complicated than that :-)
You could probably convince me otherwise,
and in fact you may have already...
>
>> I leave it up to you to decide what to do, Michael.
>>
>> My proposals:
>> If you prefer consistency in the source, I'd rather not use
>> workarounds: I'd just leave .PP, and accept the blank line
>> I see those workarounds uglier than .br.
>
> Too bad for me. But I admit I'm not proud of that .TQ thing. :P
>
>> If you however prefer consistency in the visual page,
>
> That's not how it appears to me; I may be bringing too much insider
> knowledge to the question, but I know when I see them that the things
> you've termed section headings aren't true section headings. Primarily
> I can tell by the fact that their indentation is wrong for an .SH macro.
>
> But the knowledge isn't all that far inside. The worst hand-written man
> page I have ever seen in my life, or expect to see, was written by
> Albert Cahalan, who hated *roff with a passion I have reserved only for
> love affairs. He learned just enough of the language to subvert man-db
> and groff into accepting his plain-text document as a man page[2].
>
> I don't know what ever became of Mr. Cahalan, but I imagine that he is
> somewhere working on processing Markdown with XML:FO and enjoying
> himself immensely.
8-O
I'm curious as to how that man page displays...
>
> Regards,
> Branden
>
> [1] https://lists.gnu.org/archive/html/groff/2019-03/msg00047.html
> [2]
https://gitlab.com/procps-ng/procps/blob/7ac9a0e1f5606696dc799b773d5ec70183ca91a3/ps/ps.1
>
I was writing about the different options and testing them,
when by accident I discovered that .RS alone, which I introduced lately,
already fixed the problem we had in the beginning:
.RS forces a line break after the tag
(so .br is actually redundant right now).
I guess we'll all be happy with just .RS, right? :-}
Cheers,
Alex
^ permalink raw reply [flat|nested] 22+ messages in thread
* Re: [PATCH v2 1/3] system_data_types.7: ffix
2020-09-30 21:32 ` Alejandro Colomar
@ 2020-10-01 7:37 ` Michael Kerrisk (man-pages)
2020-10-01 7:52 ` Alejandro Colomar
0 siblings, 1 reply; 22+ messages in thread
From: Michael Kerrisk (man-pages) @ 2020-10-01 7:37 UTC (permalink / raw)
To: Alejandro Colomar, G. Branden Robinson
Cc: mtk.manpages, linux-man, libc-alpha
Hi Alex, Branden,
On 9/30/20 11:32 PM, Alejandro Colomar wrote:
> Hi Branden & Michael,
>
> On 2020-09-30 12:43, G. Branden Robinson wrote:
> >> However, if using .br is a big headache, I would rather not use
> >> workarounds (as you proposed in an earlier email),
> >> and instead just live with the blank line. It's not much of a
> >> problem.
> >
> > Was an actual decision taken on this? I see patches continuing to roll
> > in containing this .br-based pattern. I think if the extra line is
> > live-withable, it should be lived with (or one of my four proposed
> > alternatives could be used :) ), in preference to setting the bad
> > example of the "naked" .br requests.
>
> No decision yet.
> We continued with the patch,
> considering that we might revert it
> or change it to a different approach in the future.
Yes. I figure we can easily clean up the inconsistency later.
> Actually I thought Michael would have hold the patches until the decision,
I didn't want to slow you down,...
> but he merged them, and it may be easier this way...
> we'll fix it when we decide.
Yes.
> For me, I can live with the extra blank line.
> Michael, what are your thoughts?
I can live with it too.
[...]
>
> >
> > Regards,
> > Branden
> >
> > [1] https://lists.gnu.org/archive/html/groff/2019-03/msg00047.html
> > [2]
> https://gitlab.com/procps-ng/procps/blob/7ac9a0e1f5606696dc799b773d5ec70183ca91a3/ps/ps.1
> >
>
>
> I was writing about the different options and testing them,
> when by accident I discovered that .RS alone, which I introduced lately,
> already fixed the problem we had in the beginning:
> .RS forces a line break after the tag
> (so .br is actually redundant right now).
>
> I guess we'll all be happy with just .RS, right? :-}
I think so.
Cheers,
Michael
PS Alex, I believe we are at a sync point right now (i.e., I think
that I do not have any unprocessed patches from you). Let me know if
I'm wrong.
--
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
^ permalink raw reply [flat|nested] 22+ messages in thread
* Re: [PATCH v2 1/3] system_data_types.7: ffix
2020-10-01 7:37 ` Michael Kerrisk (man-pages)
@ 2020-10-01 7:52 ` Alejandro Colomar
2020-10-01 9:36 ` Michael Kerrisk (man-pages)
0 siblings, 1 reply; 22+ messages in thread
From: Alejandro Colomar @ 2020-10-01 7:52 UTC (permalink / raw)
To: Michael Kerrisk (man-pages); +Cc: G. Branden Robinson, linux-man, libc-alpha
Hi Michael,
On 2020-10-01 09:37, Michael Kerrisk (man-pages) wrote:
> PS Alex, I believe we are at a sync point right now (i.e., I think
> that I do not have any unprocessed patches from you). Let me know if
> I'm wrong.
>
There's only one patch missing:
https://lore.kernel.org/linux-man/20200929151047.GN6642@arm.com/T/#m7e7fe3066750196cfe26afd53a1a2a7896ddfa96
I hope it still applies.
Thanks,
Alex
^ permalink raw reply [flat|nested] 22+ messages in thread
* Re: [PATCH v2 1/3] system_data_types.7: ffix
2020-10-01 7:52 ` Alejandro Colomar
@ 2020-10-01 9:36 ` Michael Kerrisk (man-pages)
0 siblings, 0 replies; 22+ messages in thread
From: Michael Kerrisk (man-pages) @ 2020-10-01 9:36 UTC (permalink / raw)
To: Alejandro Colomar
Cc: mtk.manpages, G. Branden Robinson, linux-man, libc-alpha
On 10/1/20 9:52 AM, Alejandro Colomar wrote:
> Hi Michael,
>
> On 2020-10-01 09:37, Michael Kerrisk (man-pages) wrote:
>> PS Alex, I believe we are at a sync point right now (i.e., I think
>> that I do not have any unprocessed patches from you). Let me know if
>> I'm wrong.
>>
>
> There's only one patch missing:
>
> https://lore.kernel.org/linux-man/20200929151047.GN6642@arm.com/T/#m7e7fe3066750196cfe26afd53a1a2a7896ddfa96
>
> I hope it still applies.
It does. Applied and pushed.
Thanks,
Michael
--
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
^ permalink raw reply [flat|nested] 22+ messages in thread
end of thread, other threads:[~2020-10-01 9:36 UTC | newest]
Thread overview: 22+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2020-09-27 21:13 [PATCH 1/3] system_data_types.7: ffix Alejandro Colomar
2020-09-27 21:13 ` [PATCH 2/3] system_data_types.7: Add 'FILE' Alejandro Colomar
2020-09-28 6:04 ` Michael Kerrisk (man-pages)
2020-09-28 9:06 ` [PATCH v2 " Alejandro Colomar
2020-09-29 13:15 ` Alejandro Colomar
2020-09-29 13:35 ` Michael Kerrisk (man-pages)
2020-09-27 21:13 ` [PATCH 3/3] FILE.3: New link to system_data_types(7) Alejandro Colomar
2020-09-28 5:59 ` [PATCH 1/3] system_data_types.7: ffix Michael Kerrisk (man-pages)
2020-09-28 9:03 ` [PATCH v2 " Alejandro Colomar
2020-09-28 10:34 ` Michael Kerrisk (man-pages)
2020-09-28 10:37 ` Alejandro Colomar
2020-09-28 11:13 ` G. Branden Robinson
2020-09-28 13:06 ` G. Branden Robinson
2020-09-28 13:44 ` Alejandro Colomar
2020-09-30 10:43 ` G. Branden Robinson
2020-09-30 21:32 ` Alejandro Colomar
2020-10-01 7:37 ` Michael Kerrisk (man-pages)
2020-10-01 7:52 ` Alejandro Colomar
2020-10-01 9:36 ` Michael Kerrisk (man-pages)
2020-09-28 10:40 ` [PATCH " G. Branden Robinson
2020-09-28 10:51 ` Alejandro Colomar
2020-09-28 12:49 ` G. Branden Robinson
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).