Hi Jason, On Tue, Jan 14, 2025 at 08:00:27AM -0500, Jason Yundt wrote: > Recently, I submitted my first patch to the Linux man-pages project. In > my patch, I had created a new manual page. On the manual page’s title > line, I had written the title of my new page in all caps because > man-pages(7) said that I should write it that way. It turns out that > man-pages(7) was wrong and that the title should have been written in > lowercase [1]. This commit corrects man-pages(7) so that it tells > contributors to use lowercase when writing titles on title lines. > > [1]: <https://lore.kernel.org/linux-man/rph24kz36vysoeix4qoxxxcwq3c3fskws2vmxkkgcb2lpits3f@ysm7ug66svzh/T/#mc84250a6634d7f776118879021331001cceccbe5> > --- > man/man7/man-pages.7 | 4 ++-- > 1 file changed, 2 insertions(+), 2 deletions(-) > > diff --git a/man/man7/man-pages.7 b/man/man7/man-pages.7 > index dc117662f..49c02d3fd 100644 > --- a/man/man7/man-pages.7 > +++ b/man/man7/man-pages.7 > @@ -95,8 +95,8 @@ .SS Title line > The arguments of the command are as follows: > .TP > .I title > -The title of the man page, written in all caps (e.g., > -.IR MAN-PAGES ). > +The title of the man page, written in lowercase (e.g., > +.IR man-pages ). Actually, the title should follow the name of the page. Usually, this is lowercase, but in some cases it should be sentence case, or upper case, if the name is something like UTF-8, or something like that. So, I would instead just remove the ", written in ..." part. Thanks for the patch! Cheers, Alex > .TP > .I section > The section number in which the man page should be placed (e.g., > -- > 2.47.0 > I should have fixed man-pages(7) when I committed the following commit: commit 4c1c52748a06141996fccbf23fb8d9e15cba11e8 Author: Alejandro Colomar <alx@xxxxxxxxxx> Date: Sun Oct 30 18:59:09 2022 +0100 Many pages: Use correct letter case in page titles (TH) Scripted change: $ find man* -type f \ | xargs grep -L '\.so' \ | while read f; do P=$(basename $f); T=$(grep '\.TH ' $f | cut -f2,3 -d' ' | sed 's/ /./'); p=$(echo $P | tr '[:upper:]' '[:lower:]'); t=$(echo $T | tr '[:upper:]' '[:lower:]'); Tn=$(echo $T | sed 's/\.[^.]\+$//') Pn=$(echo $P | sed 's/\.[^.]\+$//') N=$(man_section $f NAME \ | sed -n '/NAME/,/ - /p' \ | sed 's/ - .*//' \ | grep -v '^NAME$' \ | tr ', ' '\n' \ | grep -i "^$Pn$" \ | head -n1) test $P = $T \ && test -n $N \ && continue; if test "x$p" != "x$t"; then echo 1 $P $T $N; elif test -z "$N"; then echo 2 $P $T $N; else sed -i "/\.TH /s/$Tn/$N/" $f; fi; done; On 10/30/22 23:00, G. Branden Robinson wrote: > For those to whom this change is coming as an unpleasant surprise, the > forthcoming groff 1.23.0 features an option that will reverse this > change at rendering time. > > From groff_man(7): > > -rCT=1 Capitalize titles, setting the man page title (the first > argument to .TH) in full capitals in headers and footers. > This transformation is off by default because it discards > case distinction information. > > This register can also be set in a site-local "man.local" file to force > it on for all pages. On Debian-based systems, this file is in > /etc/groff. The following line will do the trick. > > .nr CT 1 > > The groff_man_style(7) man page offers further examples of such > rendering customization. > > /usr/local/share/groff/site-tmac/man.local > Put site‐local changes and customizations into this file. > > .\" Use narrower indentation on terminals and similar. > .if n .nr IN 4n > .\" Put only one space after the end of a sentence. > .ss 12 0 \" See groff(7). > .\" Keep pages narrow even on wide terminals. > .if n .if \n[LL]>78n .nr LL 78n > .\" Ensure hyperlinks are enabled for terminals. > .nr U 1 > > On multi‐user systems, it is more considerate to users whose > preferences may differ from the administrator’s to be less > aggressive with such settings, or to permit their override > with a user‐specific man.local file. This can be achieved by > placing one or both of following requests at the end of the > site‐local file. > .soquiet \V[XDG_CONFIG_HOME]/man.local > .soquiet \V[HOME]/.man.local > However, a security‐sandboxed man(1) program may lack > permission to open such files. Cc: Ingo Schwarze <schwarze@xxxxxxxxxxx> Cc: "G. Branden Robinson" <g.branden.robinson@xxxxxxxxx> Signed-off-by: Alejandro Colomar <alx@xxxxxxxxxx> -- <https://www.alejandro-colomar.es/>
Attachment:
signature.asc
Description: PGP signature
