Search code examples
bashmanpage

Documenting bash functions


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

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


Solution

  • Real shell functions are not documented by individual man pages but by the help builtin command. You would have to override that. But even I would not look there for information.

    Just generate normal man pages and throw them into /usr/local/man/manX or /usr/local/share/man/manX - whatever your distribution already provides. Check /etc/manpath.config that this directory is already mentioned there. That way no one must fiddle in their startup files with the MANPATH environment variable.

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

    After that the social part kicks in: Tell everyone at every occasion about that documetation. By every I mean every, not only suitable. :-)