Documenting bash functions

Question

I would like to add documentation for bash functions so that users can search for functions using man . There should be no visible difference between my functions and the actual commands.

I know I can do this by overriding man with a function that tests my own functions. Is there another way?

Answer 1

The real shell functions are not documented by separate man pages, but with the help help built-in. You will have to override this. But even I would not look for information.

Just create normal man pages and throw them in /usr/local/man/manX or /usr/local/share/man/manX - regardless of what your distribution already provides. Check /etc/manpath.config that this directory is already mentioned there. Thus, no one should bother in their startup files with the MANPATH environment MANPATH .

Each man page should also contain a clearly visible section explaining that this is a function, not a command, and what is the difference.

After that, the social part begins: talk about this documentation every time. For everyone, I mean everyone, not only suitable .:-)

Answer 2

If you have created your pages with a person (which in itself is a task), then you can put them somewhere in the system, for example /usr/local/man (or anywhere, actually), and then edit the system-wide $MANPATH to enable this location. Then the manual pages will be available.