Re: [PATCH] Various pages: tfix

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

Hi Alex,

On Wed, 23 Dec 2020 at 20:03, Alejandro Colomar <alx.manpages@gmail.com> wrote:
>
> Remove "." at the end of sentence fragments/short single sentences
> in comments.  See: c2e81ff9641a7743b1f47cbf4fcf899c391df77f.
>
> $ sed -i '/[^.]\. \*\//s%\. \*/% */%' man?/*
>
> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>

There is probably still a bit of inconsistency in the pages, But, your
change removes some periods what really should be present.

For example:

> --- a/man2/clone.2
> +++ b/man2/clone.2
> @@ -1843,7 +1843,7 @@ childFunc(void *arg)
>
>      /* Keep the namespace open for a while, by sleeping.
>         This allows some experimentation\-\-for example, another
> -       process might join the namespace. */
> +       process might join the namespace */
>
>      sleep(200);
>
> @@ -1887,7 +1887,7 @@ main(int argc, char *argv[])
>      sleep(1);           /* Give child time to change its hostname */
>
>      /* Display hostname in parent\(aqs UTS namespace. This will be
> -       different from hostname in child\(aqs UTS namespace. */
> +       different from hostname in child\(aqs UTS namespace */

Here are a couple of cases where the comment contains two sentences,
but the change removes the period from the second sentence. That's
definitely not right.

My general philosophy is complete sentences in comments should be
terminated by periods. In sentence fragments, especially for tag
comments (i.e., comment on same line as the code), I'm inclined to
omit the period. And there are doubtless inconsistencies in existing
pages (and grey areas). Commit c2e81ff964 was intended to clean up
some of the most obvious cases.

I've made a few more commits now to bring more consistency. (I think
Branden's suggestion that complete sentences should generally always
be punctuated is true.) And I've added some notes to man-pages(7). See
commits f18f9c409...46b20ca1b

Thanks,

Michael

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