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/
