Although, well, now I think we could consider /* Send the signal. */ to be a full sentence, so... I'll let it be :) Cheers, Alex On 12/28/20 10:20 AM, Alejandro Colomar (man-pages) wrote: > Hi Michael and Branden! > > I agree with having periods in full sentences in comments. > > I've been looking at the 3 commits, and I'm seeing some inconsistencies. > I'll have a look at it, and maybe send you a patch (v2). See for > example the changes in pidfd_send_signal.2: > > - /* Send the signal */ > + /* Send the signal. */ > > Thanks, > > Alex > > On 12/27/20 12:54 PM, Michael Kerrisk (man-pages) wrote: >> Hi Alex, >> >> On Wed, 23 Dec 2020 at 20:03, Alejandro Colomar <alx.manpages@xxxxxxxxx> 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@xxxxxxxxx> >> >> 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 >> > -- Alejandro Colomar Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/ http://www.alejandro-colomar.es/
