Re: [PATCH] execveat.2: srcfix

["Alejandro Colomar (man-pages)" <alx.manpages@gmail.com>]

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@gmail.com> 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@gmail.com>
>>>> ---
>>>>
>>>>  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
>>>>
>>>
>>>
> 
>