Re: [PATCH] execveat.2: srcfix

["Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com>]

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


-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/