Hi Michael, Another design question about SYNOPSIS: When to leave a blank between prototypes? capget.2 has it. printf.3 doesn't. I prefer to be compact, especially when prototypes fit in one line. Some exceptions are the queue.3 derivatives, which become unreadable if compacted. Cheers, Alex On 12/31/20 11:06 AM, Michael Kerrisk (man-pages) wrote: > Hi ALex, > > On 12/31/20 12:28 AM, Alejandro Colomar (man-pages) wrote: >> >> >> On 12/30/20 11:27 PM, Michael Kerrisk (man-pages) wrote: >>> Hi Alex, >>> >>> On Wed, 30 Dec 2020 at 22:41, Alejandro Colomar <alx.manpages@xxxxxxxxx> wrote: >>>> >>>> Use .nf/.fi in the SYNOPSIS. >>> >>> I'm not against the patch. But why this particular page? >> >> Hello Michael, >> >> I fixed this while adding the notes about missing headers in that page, >> but I felt that it was better as a separate patch. >> And the other patch I didn't send it in the last moment as I found a >> missing line :p > > Ahhh -- that explains a lot :-). > >> >> Would you prefer a global fix about .nf/.fi or just fix as we go? > > So, I think by now there's a lot of inconsistency in the layout > in SYNOPSIS, and before making a global change, there should be > some design decisions. > > There are things to consider: > * .nf/.fi should probably be used around the all functions > signatures. > * There should be no .br between function signatures. > * .PP should be used where appropriate to get white space > separation between function signatures. > > The worst mess though is probably the Feature Test Macro (FTM) > requirements. Even though nearly all of this information was > added by me, and I tried to be consistent, this was complicated > by the fact that (a) the info was added over several years and > (b) the details are surprisingly complicated sometimes, mainly > because of changes to FTM requirements across glibc versions > and that several functions might be documented in the same page > (e.g., see chmod(2), setpgid(2)). So, there is some inconsistency > (perhaps worse in the actual page source, than in the rendered > output). Also, the material in the FTM text is heavily oriented > around the assumption of an 80-column display. > > I'm not sure how much effort it is worth putting into fixing > this, but before any global edit, there probably needs to be > quite a bit of discussion. > > All of that said, I've just made a bunch of commits to tidy > up some of the more obviously messy pieces. > > Thanks, > > Michael > >>>> Signed-off-by: Alejandro Colomar <alx.manpages@xxxxxxxxx> >>>> --- >>>> >>>> man2/execveat.2 | 11 ++++++----- >>>> 1 file changed, 6 insertions(+), 5 deletions(-) >>>> >>>> diff --git a/man2/execveat.2 b/man2/execveat.2 >>>> index 7c31d8f17..c5cd843f9 100644 >>>> --- a/man2/execveat.2 >>>> +++ b/man2/execveat.2 >>>> @@ -27,13 +27,13 @@ >>>> .SH NAME >>>> execveat \- execute program relative to a directory file descriptor >>>> .SH SYNOPSIS >>>> +.nf >>>> .B #include <unistd.h> >>>> .PP >>>> -.BI "int execveat(int " dirfd ", const char *" pathname "," >>>> -.br >>>> -.BI " char *const " argv "[], char *const " envp "[]," >>>> -.br >>>> +.BI "int execveat(int " dirfd ", const char *" pathname , >>>> +.BI " char *const " argv "[], char *const " envp [], >>>> .BI " int " flags ); >>>> +.fi >>>> .SH DESCRIPTION >>>> .\" commit 51f39a1f0cea1cacf8c787f652f26dfee9611874 >>>> The >>>> @@ -224,7 +224,8 @@ where scripts recursively employ >>>> .\" For an example, see Michael Kerrisk's 2015-01-10 reply in this LKML >>>> .\" thread (http://thread.gmane.org/gmane.linux.kernel/1836105/focus=20229): >>>> .\" >>>> -.\" Subject: [PATCHv10 man-pages 5/5] execveat.2: initial man page.\" for execveat(2 >>>> +.\" Subject: [PATCHv10 man-pages 5/5] execveat.2: initial man page >>>> +.\" for execveat(2) >>>> .\" Date: Mon, 24 Nov 2014 11:53:59 +0000 >>>> .SH SEE ALSO >>>> .BR execve (2), >>>> -- >>>> 2.29.2 >>>> >>> >>> > >
