bug#53977: Improve markup in man pages
On 2/14/22 15:00, Pádraig Brady wrote: I see Paul added the grep markup recently in a seemingly unrelated change: https://git.savannah.gnu.org/gitweb/?p=grep.git;a=commit;h=fe630c9f In the old days man pages' SEE ALSO sections mostly didn't use markup for references to other man pages. I see only one exception in 7th edition UNIX (1979): its man page for yacc used ".IR lex (1)" instead of plain "lex(1)". Nowadays it seems that ".BR lex (1)" is what's preferred for this sort of thing, so I've been switching to this style desultorily in man pages when someone points it out, most recently in diffutils today: https://git.savannah.gnu.org/gitweb/?p=diffutils.git;a=commitdiff;h=dd9deb765548679e821be565229bb2e142d93573 As usual man pages are low priority for the GNU project. That being said, this sort of thing is an easy change.
bug#53977: Improve markup in man pages
On 14/02/2022 13:52, Mario Blättermann wrote: Hello Pádraig, Am Mo., 14. Feb. 2022 um 13:15 Uhr schrieb Pádraig Brady : On 13/02/2022 13:19, Mario Blättermann wrote: Hello, the SEE ALSO sections in the man pages contain links which will be pulled in from *.x files by help2man. While help2man evaluates the Groff markup from --help and --version output, it doesn't bother with the markup in the *.x files. See the attached patch. The bold formatting of the links is especially useful in HTML output (but also in terminal output); the links become clickable and point to the respective man page in online collections [1]. You can test the behavior in the German version, where the links are already properly formatted [2]. [1] https://man.archlinux.org/man/cat.1 [2] https://man.archlinux.org/man/cat.1.de Sorry. I'm still not convinced on this. It seems like a layering violation to stipulate a style here. The renderer should have enough context to highlight appropriately. See for example: https://man7.org/linux/man-pages/man1/sort.1.html Maybe some renderers are smart enough to highlight this. But it shouldn't be up to the developers of such renderers to apply missing formattings virtually. Thanks for the consideration on this. I'm not strongly against hardcoding the formatting, but I do think it's worth discussing the need. Note we discussed this previously at: https://lists.gnu.org/archive/html/coreutils/2021-01/msg8.html The summary there was things have trended over time from a mixture of none,italic,bold style references to mostly bold. Note the man7.org renderer only highlights the SEE ALSO references, when ideally it would highlight all instances of this pattern. Anyway handling references outside of the SEE ALSO section, is another reason to have the renderer do this consistently. See for example all the appropriately highlighted references in: http://man.he.net/?topic=sort=all https://man.cx/sort Yes, but this doesn't work in all imaginable cases, because the renderer needs to be able to evaluate if it is a link or not. In your example, "shuf" is a link because it is tagged with the section number, but this wouldn't, then "shuf" would be as plain as other words. See the "diff3.1" man page [1]: > > -e, --ed output ed script incorporating changes from OLDFILE to YOURFILE into MYFILE If "ed" would be "ed(1)" then it would be detected as a command name here, but it isn't. But it isn't bold either. I suggest this page should be updated to use "ed(1)". Well, the best solution would be to dig in the Help2man code and try to improve the detection of parts worth to be formatted - provided solid Perl skills. But this would be outside of the topic of this bug report; Yes a `help2man --bold-refs` option seems useful. It give the option to apply the formatting, and more centrally, rather than inconsistently sprinkled through all man pages. Also this would be the only way to consistently style all references in coreutils, since some are output to the terminal through --help. let's go back to the SEE ALSO links. The man page man-pages(7) says [2]: »The name of the command, and its options, should always be formatted in bold.« In fact, the SEE ALSO links are also command names, although not the command the current man page describes. The bold here is pertaining to styling of the headers of the page, rather than to any command references in general IMHO. In general bold text interspersed in other text on the terminal can be quite distracting to read. Some terminals can make it bigger, brighter, blurrier, ... Let's have a look at other projects [that hardcode bold references] > grub, grep, kernel. I see Paul added the grep markup recently in a seemingly unrelated change: https://git.savannah.gnu.org/gitweb/?p=grep.git;a=commit;h=fe630c9f I could mention lots of similar examples, but just open an arbitrary man page in your terminal with "man", not in Vim; you will see that (almost …) all SEE ALSO links are formatted bold. I did check also, and see lots of inconsistencies. BTW re vim, the match for references is: syn match manReference "\f\+([1-9][a-z]\=)" With the bold formatting (and correct placing of the section number), you make sure that *all* renderers, both the simple ones like "man" in the terminal and the advanced HTML/DVI/PDF/whatever renderers, format the links correctly. "correctly" is a strong word here. [1] https://man.cx/diff3#heading3 [2] https://man.archlinux.org/man/man-pages.7.en#Formatting_conventions_for_manual_pages_describing_commands [3] https://git.savannah.gnu.org/cgit/grub.git/tree/docs/man/grub-editenv.h2m [4] https://git.savannah.gnu.org/cgit/grep.git/tree/doc/grep.in.1#n1359 [5] https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/tree/man1/mtrace.1#n64 [6] https://github.com/freebsd/freebsd-src/blob/main/usr.bin/sort/sort.1.in#L580 I've attached a patch to implement help2man --bold-refs. Brendan is that something that might be
bug#53977: Improve markup in man pages
Hello Pádraig, Am Mo., 14. Feb. 2022 um 13:15 Uhr schrieb Pádraig Brady : > > On 13/02/2022 13:19, Mario Blättermann wrote: > > Hello, > > > > the SEE ALSO sections in the man pages contain links which will be > > pulled in from *.x files by help2man. While help2man evaluates the > > Groff markup from --help and --version output, it doesn't bother with > > the markup in the *.x files. See the attached patch. The bold > > formatting of the links is especially useful in HTML output (but also > > in terminal output); the links become clickable and point to the > > respective man page in online collections [1]. You can test the > > behavior in the German version, where the links are already properly > > formatted [2]. > > > > [1] https://man.archlinux.org/man/cat.1 > > [2] https://man.archlinux.org/man/cat.1.de > > Sorry. I'm still not convinced on this. > It seems like a layering violation to stipulate a style here. > The renderer should have enough context to highlight appropriately. > See for example: > > https://man7.org/linux/man-pages/man1/sort.1.html > Maybe some renderers are smart enough to highlight this. But it shouldn't be up to the developers of such renderers to apply missing formattings virtually. > Note the man7.org renderer only highlights the SEE ALSO references, > when ideally it would highlight all instances of this pattern. > Anyway handling references outside of the SEE ALSO section, > is another reason to have the renderer do this consistently. > See for example all the appropriately highlighted references in: > > http://man.he.net/?topic=sort=all > https://man.cx/sort > Yes, but this doesn't work in all imaginable cases, because the renderer needs to be able to evaluate if it is a link or not. In your example, "shuf" is a link because it is tagged with the section number, but this wouldn't, then "shuf" would be as plain as other words. See the "diff3.1" man page [1]: -e, --ed output ed script incorporating changes from OLDFILE to YOURFILE into MYFILE If "ed" would be "ed(1)" then it would be detected as a command name here, but it isn't. Well, the best solution would be to dig in the Help2man code and try to improve the detection of parts worth to be formatted - provided solid Perl skills. But this would be outside of the topic of this bug report; let's go back to the SEE ALSO links. The man page man-pages(7) says [2]: »The name of the command, and its options, should always be formatted in bold.« In fact, the SEE ALSO links are also command names, although not the command the current man page describes. Let's have a look at other projects. The GRUB developers also use Help2man to generate man pages dynamically, and they use *.h2m files to feed Help2man, like Coreutils' *.x files do. An example [3]: [NAME] grub-editenv \- edit GRUB environment block [SEE ALSO] .BR grub-reboot (8), .BR grub-set-default (8) It seems to be obvious for them to format the links bold. But it is not special to Help2man-based projects to do so. Example from GNU Grep [4], which uses a static man page: .SH "SEE ALSO" .SS "Regular Manual Pages" .BR awk (1), .BR cmp (1), .BR diff (1), .BR find (1), .BR perl (1), ... Another example from the kernel's man pages [5]: .SH SEE ALSO .BR memusage (1), .BR mtrace (3) And last but not least, an example from an Mdoc based man page from FreeBSD [6]: .Sh SEE ALSO .Xr comm 1 , .Xr join 1 , .Xr uniq 1 I could mention lots of similar examples, but just open an arbitrary man page in your terminal with "man", not in Vim; you will see that (almost …) all SEE ALSO links are formatted bold. With the bold formatting (and correct placing of the section number), you make sure that *all* renderers, both the simple ones like "man" in the terminal and the advanced HTML/DVI/PDF/whatever renderers, format the links correctly. The additional lines in the *.x files don't eat up lots of disk space or other resources. Please think about to apply my patch once again. [1] https://man.cx/diff3#heading3 [2] https://man.archlinux.org/man/man-pages.7.en#Formatting_conventions_for_manual_pages_describing_commands [3] https://git.savannah.gnu.org/cgit/grub.git/tree/docs/man/grub-editenv.h2m [4] https://git.savannah.gnu.org/cgit/grep.git/tree/doc/grep.in.1#n1359 [5] https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/tree/man1/mtrace.1#n64 [6] https://github.com/freebsd/freebsd-src/blob/main/usr.bin/sort/sort.1.in#L580 Best Regards, Mario
bug#53977: Improve markup in man pages
On 13/02/2022 13:19, Mario Blättermann wrote: Hello, the SEE ALSO sections in the man pages contain links which will be pulled in from *.x files by help2man. While help2man evaluates the Groff markup from --help and --version output, it doesn't bother with the markup in the *.x files. See the attached patch. The bold formatting of the links is especially useful in HTML output (but also in terminal output); the links become clickable and point to the respective man page in online collections [1]. You can test the behavior in the German version, where the links are already properly formatted [2]. [1] https://man.archlinux.org/man/cat.1 [2] https://man.archlinux.org/man/cat.1.de Sorry. I'm still not convinced on this. It seems like a layering violation to stipulate a style here. The renderer should have enough context to highlight appropriately. See for example: https://man7.org/linux/man-pages/man1/sort.1.html Note the man7.org renderer only highlights the SEE ALSO references, when ideally it would highlight all instances of this pattern. Anyway handling references outside of the SEE ALSO section, is another reason to have the renderer do this consistently. See for example all the appropriately highlighted references in: http://man.he.net/?topic=sort=all https://man.cx/sort thanks, Pádraig
bug#53977: Improve markup in man pages
Hello, the SEE ALSO sections in the man pages contain links which will be pulled in from *.x files by help2man. While help2man evaluates the Groff markup from --help and --version output, it doesn't bother with the markup in the *.x files. See the attached patch. The bold formatting of the links is especially useful in HTML output (but also in terminal output); the links become clickable and point to the respective man page in online collections [1]. You can test the behavior in the German version, where the links are already properly formatted [2]. [1] https://man.archlinux.org/man/cat.1 [2] https://man.archlinux.org/man/cat.1.de Best Regards, Mario diff --git a/man/arch.x b/man/arch.x index 0a310b41f..487318207 100644 --- a/man/arch.x +++ b/man/arch.x @@ -3,4 +3,5 @@ arch \- print machine hardware name (same as uname -m) [DESCRIPTION] .\" Add any additional description here [SEE ALSO] -uname(1), uname(2) +.BR uname (1), +.BR uname (2) diff --git a/man/b2sum.x b/man/b2sum.x index 5a857ca15..bb5cabb5b 100644 --- a/man/b2sum.x +++ b/man/b2sum.x @@ -3,4 +3,4 @@ b2sum \- compute and check BLAKE2 message digest [DESCRIPTION] .\" Add any additional description here [SEE ALSO] -cksum(1) +.BR cksum (1) diff --git a/man/basename.x b/man/basename.x index e91ee57ee..a6554c217 100644 --- a/man/basename.x +++ b/man/basename.x @@ -3,4 +3,5 @@ basename \- strip directory and suffix from filenames [DESCRIPTION] .\" Add any additional description here [SEE ALSO] -dirname(1), readlink(1) +.BR dirname (1), +.BR readlink (1) diff --git a/man/cat.x b/man/cat.x index 9eb38cf05..e6eb90e38 100644 --- a/man/cat.x +++ b/man/cat.x @@ -3,4 +3,4 @@ cat \- concatenate files and print on the standard output [DESCRIPTION] .\" Add any additional description here [SEE ALSO] -tac(1) +.BR tac (1) diff --git a/man/chgrp.x b/man/chgrp.x index a61f3089e..a3d10bc27 100644 --- a/man/chgrp.x +++ b/man/chgrp.x @@ -3,4 +3,5 @@ chgrp \- change group ownership [DESCRIPTION] .\" Add any additional description here [SEE ALSO] -chown(1), chown(2) +.BR chown (1), +.BR chown (2) diff --git a/man/chmod.x b/man/chmod.x index 3ab8ed055..847ba9234 100644 --- a/man/chmod.x +++ b/man/chmod.x @@ -115,4 +115,4 @@ quickly when run; this is called the .IR "sticky bit" . .SH OPTIONS [SEE ALSO] -chmod(2) +.BR chmod (2) diff --git a/man/chown.x b/man/chown.x index ee79d1b7d..22564bd6d 100644 --- a/man/chown.x +++ b/man/chown.x @@ -27,4 +27,4 @@ If only a colon is given, or if the entire operand is empty, neither the owner nor the group is changed. .SH OPTIONS [SEE ALSO] -chown(2) +.BR chown (2) diff --git a/man/chroot.x b/man/chroot.x index fc1be5286..c21336d52 100644 --- a/man/chroot.x +++ b/man/chroot.x @@ -3,4 +3,4 @@ chroot \- run command or interactive shell with special root directory [DESCRIPTION] .\" Add any additional description here [SEE ALSO] -chroot(2) +.BR chroot (2) diff --git a/man/comm.x b/man/comm.x index d4d8e00da..b7ab4478e 100644 --- a/man/comm.x +++ b/man/comm.x @@ -3,4 +3,5 @@ comm \- compare two sorted files line by line [DESCRIPTION] .\" Add any additional description here [SEE ALSO] -join(1), uniq(1) +.BR join (1), +.BR uniq (1) diff --git a/man/dirname.x b/man/dirname.x index 09c46e4fe..3062f220b 100644 --- a/man/dirname.x +++ b/man/dirname.x @@ -3,4 +3,5 @@ dirname \- strip last component from file name [DESCRIPTION] .\" Add any additional description here [SEE ALSO] -basename(1), readlink(1) +.BR basename (1), +.BR readlink (1) diff --git a/man/echo.x b/man/echo.x index 61a36706b..be65d1640 100644 --- a/man/echo.x +++ b/man/echo.x @@ -3,4 +3,4 @@ echo \- display a line of text [DESCRIPTION] .\" Add any additional description here [SEE ALSO] -printf(1) +.BR printf (1) diff --git a/man/env.x b/man/env.x index c2cafbaa8..6c0a0035e 100644 --- a/man/env.x +++ b/man/env.x @@ -64,4 +64,6 @@ cooperating) programs." .RE [SEE ALSO] -sigaction(2), sigprocmask(2), signal(7) +.BR sigaction (2), +.BR sigprocmask (2), +.BR signal (7) diff --git a/man/expand.x b/man/expand.x index 06c538882..00f12a091 100644 --- a/man/expand.x +++ b/man/expand.x @@ -3,4 +3,4 @@ expand \- convert tabs to spaces [DESCRIPTION] .\" Add any additional description here [SEE ALSO] -unexpand(1) +.BR unexpand (1) diff --git a/man/groups.x b/man/groups.x index fad68455f..dab30d276 100644 --- a/man/groups.x +++ b/man/groups.x @@ -3,4 +3,4 @@ groups \- print the groups a user is in [DESCRIPTION] .\" Add any additional description here [SEE ALSO] -getent(1) +.BR getent (1) diff --git a/man/head.x b/man/head.x index 53d2662de..953a2ab75 100644 --- a/man/head.x +++ b/man/head.x @@ -3,4 +3,4 @@ head \- output the first part of files [DESCRIPTION] .\" Add any additional description here [SEE ALSO] -tail(1) +.BR tail (1) diff --git a/man/hostid.x b/man/hostid.x index 767a3e2b0..df82fb412 100644 --- a/man/hostid.x +++ b/man/hostid.x @@ -3,4 +3,4 @@ hostid \- print the numeric identifier for the current host [DESCRIPTION] .\" Add any
