I sometimes see people referring to tools, like ls append the manpage section number in parens, like the manpages themselves do (in ls's case ls(1)) in prose/text like answers and comments here on stackexchange.
Is that good practice?
Are there any sources about this practice?
Do any famous "entities", like big companies, mailing lists etc. do this?
Asked
Active
Viewed 42 times
2
Andreas
- 21
1 Answers
1
It helps to avoid ambiguity in some cases, when a single name refers to multiple manpages.
As an example, unlink has man pages under three sections:
- unlink(1), which describes the user-level command.
- unlink(2), which describes the system call at the kernel level that implements the unlink functionality.
- unlink(3p), which describes the library function that wraps around the system call. This page is a part of the POSIX Programmer's Manual.
To clarify which section you want to refer to in a specific context, it is helpful to specify the section number.
Since it is mentioned in the question, the ls command has two manpages - ls(1) for the local implementation and ls(1p) for the POSIX definition. It may be useful to specify the section number in this case.
With manpages that are non-ambiguous, the section number does not add much value. Examples: 1) fstab, which has a single page under section five; 2) cron, which has a single page under section eight.
All the manpages referenced above are listed here: https://www.man7.org/linux/man-pages/dir_all_alphabetic.html
Haxiel
- 8,361