1

I have a question about the syntax of manpages.

I just wrote documentation in manpage format for my little project. I would like to allow users to type man commandname option as in git documentation, e.g., man git commit, but I don't know how to do it well. I know a "dirty" way of doing this by defining a man() function in .bashrc:

man()
{
    case ${#} in
        0) /usr/bin/man ;;
        1) /usr/bin/man "${1}" ;;
        2) /usr/bin/man "${1}-${2}" ;;
        *) echo "Too many arguments" ;;
    esac
}

Can somebody tell me how to improve my documentation so my users can pass an option into man?

  • 1
    Why do you consider using a function "dirty"? – glenn jackman May 23 at 17:20
2

The man page for man explains how giving pairs of names on the command line are handled specially:

   --no-subpages
          By default, man will try to interpret pairs of manual page names
          given on the command line as equivalent to a single manual  page
          name  containing  a  hyphen or an underscore.  This supports the
          common pattern of programs that implement a  number  of  subcom-
          mands,  allowing  them to provide manual pages for each that can
          be accessed using similar syntax as would be used to invoke  the
          subcommands themselves.  For example:
            $ man -aw git diff
            /usr/share/man/man1/git-diff.1.gz

So you just need to provide separate man page files for each of your options, just like git provides git.1.gz and git-diff.1.gz and so on, and you will automatically get what you want.

1

This is already a feature in mandb man, the implementation commonly seen on Linux distributions. From man 1 man:

--no-subpages
  By  default,  man  will  try  to  interpret pairs of manual page names given on the
  command line as equivalent to a single manual page name containing a hyphen  or  an
  underscore.   This  supports the common pattern of programs that implement a number
  of subcommands, allowing them to provide manual pages for each that can be accessed
  using  similar  syntax  as would be used to invoke the subcommands themselves.  For
  example:

    $ man -aw git diff
    /usr/share/man/man1/git-diff.1.gz

So all you need to is have a manpage properly named as <command>-<subcommand>.

This may not be a feature in other implementations. For example, macOS man doesn't support it:

~ man git commit
# shows git manpage
No manual entry for commit

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.