2

I'm writing an interactive shell utility (it's a bash script), and I would like to provide a man page for it. It's a script that I expect the user to download and put in their PATH, not something that should require superuser privileges. Any idea where I should put the manual page?

For the moment I just put it next to the script, and from the script I can use something like dirname $0 to locate and display from inside the utility. However it would be nice to also make it available with man. For now I recommend man -l /path/to/script/help.1, but that's awkward and non-intuitive.

Note: I found this previous question, but I don't think the accepted answer actually answers the question correctly.

suvayu
  • 148

2 Answers2

4

As far as I know, there is no standard recommendation for a user-writable man page directory. The Filesystem Hierarchy Standard 3.0 refers to the XDG Base Directory Specification and the xdg-user-dirs specification regarding things within users' home directories, but neither of those has anything specific to say about man page directories.

Classically, this is because adding your own man page directory tree to the MANPATH environment variable used to be trivial. However, modern implementations of man often leave the MANPATH variable empty, and specify the man page directory hierarchies in e.g. /etc/manpath.config or a similar configuration file.

For backwards compatibility, if the MANPATH variable is set for these modern man implementations, it tends to override the man page search path completely, rather than provide a way to add to it, which can be inconvenient: as a user, you would have to read and understand the appropriate configuration file, and first create a MANPATH value that completely covers all the system man pages you wish to keep available to you, and then add your own custom man page directory to a suitable spot within that ordered list. However, you would generally only need to do this once, unless there are major updates to the system software and/or directory structures, so it should not be that hard to do.

Overall, the classic convention seemed to be that if a directory of executables (suitable for adding to PATH) were located at <some path>/bin/ or <some path>/sbin/, the root of the corresponding man page hierarchy would be at <some path>/man/ respectively. However, FHS 3.0 already deviates from that by specifying /usr/share/man/ as the primary man page hierarchy for the system, corresponding to both /[s]bin/ and /usr/[s]bin/ executable directories.

telcoM
  • 96,466
  • Thanks for the comprehensive answer to my dilemma. I see that there is no reliable way to do this. So I'll stick with my workaround, provide easy access to the man page via --help, similar to git help <cmd>. – suvayu May 22 '23 at 10:11
-1

If you are on the command line check the manpage for man:

man man

Manual pages are normally stored in nroff format under a directory such as /usr/share/man.

noflcl
  • 1
  • 1
    I know that, but it requires superuser access (which I want to avoid, as mentioned in my question). For now I have worked around this issue by invoking man to show the manual as part of the --help message, something like the git help <cmd>. – suvayu May 20 '23 at 15:14