bug#3717: M-x man completion

[Kevin Ryde]

On the subject of M-x man "-k foo" being kept secret, I thought to
revise the docstring a bit per below (formatted for reading).

I think samples of what can be entered are easier to read than words,
especially if skimming.

The "-a" bit is per man-db, but it's not posix, so I wonder if it varies
on other mans.  Did for instance BSD from years ago have the equivalent
of -a as its default anyway?


2009-12-16  Kevin Ryde  <user42@zip.com.au>

        * man.el (man): Revise docstring to show -k and -l examples, and
        mention -a in the "all sections" bit.



Get a Un*x manual page and put it in a buffer.
This command is the top-level command in the man package.  It
runs a Un*x command to retrieve and clean a manpage in the
background and places the results in a `Man-mode' browsing
buffer.  See variable `Man-notify-method' for what happens when
the buffer is ready.  If a buffer already exists for this man
page, it will display immediately.

For a manpage from a certain section, use either of the following
forms.  "cat(1)" is how cross-references appear and is passed
to man as "1 cat".

    cat(1)
    1 cat

To see manpages from all sections related to a subject, put an
"all pages" option into `Man-switches', usually "-a", then
step through with `Man-next-manpage' (M-n) etc.

An explicit filename can be given.  Use -l if it might otherwise
look like a page name.

    /my/file/name.1.gz
    -l somefile.1

An "apropos" query with -k gives a buffer of matching page
names or descriptions.  The pattern argument is usually an
"egrep" style regexp.

    -k pattern