Documenting bash functions

Question

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?

Are we talking about _real_ shell _functions_ which are defined with `foo(){ echo foo; }` or are we talking about _programs_ (which _may_ be implemented by a shell script) which are installed somewhere in a `*/bin` directory? — A.H., Dec 21 '11 at 11:06

score 3 · Answer 1 · answered Dec 21 '11 at 10:57

If you have your man pages created (which is a task in itself) then what you can do is put them somewhere on the system like /usr/local/man (or wherever you like, really), then edit the system-wide $MANPATH variable to include that location. Then the man pages will be available.

score 2 · Accepted Answer · answered Dec 21 '11 at 12:41

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. :-)

Documenting bash functions

2 Answers2