Re: [PATCH] execveat.2: srcfix

Alejandro Colomar (man-pages)
2020-12-31T12:29:38Z

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
>>>>
>>>
>>>
>
>