* [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; 24+ 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] 24+ 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; 24+ 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] 24+ 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; 24+ 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] 24+ 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; 24+ 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] 24+ 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; 24+ 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] 24+ 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; 24+ 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] 24+ 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; 24+ 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] 24+ 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; 24+ 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] 24+ 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; 24+ 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] 24+ 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; 24+ 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] 24+ 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; 24+ 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] 24+ 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; 24+ 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] 24+ 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; 24+ 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] 24+ 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; 24+ 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] 24+ 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; 24+ 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] 24+ 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; 24+ 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] 24+ 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; 24+ 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] 24+ 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; 24+ 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] 24+ 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; 24+ 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] 24+ 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; 24+ 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] 24+ 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; 24+ 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] 24+ 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; 24+ 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] 24+ messages in thread
* [PATCH 0/3] Document regmatch_t (and a ffix) @ 2020-09-18 13:29 Alejandro Colomar 2020-09-18 13:29 ` [PATCH 1/3] system_data_types.7: ffix Alejandro Colomar 0 siblings, 1 reply; 24+ messages in thread From: Alejandro Colomar @ 2020-09-18 13:29 UTC (permalink / raw) To: mtk.manpages; +Cc: linux-man, libc-alpha, Alejandro Colomar Hi Michael, Documentation for regmatch_t + a ffix patch. (apply after regoff_t patches). Thanks, Alex Alejandro Colomar (3): system_data_types.7: ffix system_data_types.7: Document regmatch_t regmatch_t.3: New page for new documented type in system_data_types(7) man3/regmatch_t.3 | 1 + man7/system_data_types.7 | 27 +++++++++++++++++++++++---- 2 files changed, 24 insertions(+), 4 deletions(-) create mode 100644 man3/regmatch_t.3 -- 2.28.0 ^ permalink raw reply [flat|nested] 24+ messages in thread
* [PATCH 1/3] system_data_types.7: ffix 2020-09-18 13:29 [PATCH 0/3] Document regmatch_t (and a ffix) Alejandro Colomar @ 2020-09-18 13:29 ` Alejandro Colomar 2020-09-18 20:42 ` Michael Kerrisk (man-pages) 0 siblings, 1 reply; 24+ messages in thread From: Alejandro Colomar @ 2020-09-18 13:29 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 | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/man7/system_data_types.7 b/man7/system_data_types.7 index 16dcb7d66..2ccbfe817 100644 --- a/man7/system_data_types.7 +++ b/man7/system_data_types.7 @@ -65,7 +65,7 @@ system_data_types \- overview of system data types .I ptrdiff_t .IP Include: -.I <stddef.h>. +.IR <stddef.h> . .IP Used for a count of elements, and array indices. It is the result of subtracting two pointers. @@ -85,7 +85,7 @@ types in this page. .I regoff_t .IP Include: -.I <regex.h>. +.IR <regex.h> . .IP According to POSIX, it shall be a signed integer type capable of storing the largest value that can be stored in either a -- 2.28.0 ^ permalink raw reply related [flat|nested] 24+ messages in thread
* Re: [PATCH 1/3] system_data_types.7: ffix 2020-09-18 13:29 ` [PATCH 1/3] system_data_types.7: ffix Alejandro Colomar @ 2020-09-18 20:42 ` Michael Kerrisk (man-pages) 0 siblings, 0 replies; 24+ messages in thread From: Michael Kerrisk (man-pages) @ 2020-09-18 20:42 UTC (permalink / raw) To: Alejandro Colomar; +Cc: mtk.manpages, linux-man, libc-alpha On 9/18/20 3:29 PM, Alejandro Colomar wrote: > Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com> Thanks, Alex. Patch applied. Cheers, Michael > --- > man7/system_data_types.7 | 4 ++-- > 1 file changed, 2 insertions(+), 2 deletions(-) > > diff --git a/man7/system_data_types.7 b/man7/system_data_types.7 > index 16dcb7d66..2ccbfe817 100644 > --- a/man7/system_data_types.7 > +++ b/man7/system_data_types.7 > @@ -65,7 +65,7 @@ system_data_types \- overview of system data types > .I ptrdiff_t > .IP > Include: > -.I <stddef.h>. > +.IR <stddef.h> . > .IP > Used for a count of elements, and array indices. > It is the result of subtracting two pointers. > @@ -85,7 +85,7 @@ types in this page. > .I regoff_t > .IP > Include: > -.I <regex.h>. > +.IR <regex.h> . > .IP > According to POSIX, it shall be a signed integer type > capable of storing the largest value that can be stored in either a > -- 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] 24+ messages in thread
end of thread, other threads:[~2020-10-01 9:36 UTC | newest] Thread overview: 24+ 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 -- strict thread matches above, loose matches on Subject: below -- 2020-09-18 13:29 [PATCH 0/3] Document regmatch_t (and a ffix) Alejandro Colomar 2020-09-18 13:29 ` [PATCH 1/3] system_data_types.7: ffix Alejandro Colomar 2020-09-18 20:42 ` Michael Kerrisk (man-pages)
This is an external index of several public inboxes, see mirroring instructions on how to clone and mirror all data and code used by this external index.