Man page coverage

[Basil Mohamed Gohar]

On Mon, 2008-12-29 at 21:20 +0530, Mani A wrote:
>  Basil Mohamed Gohar  wrote:
> > 1) Identify which packages are missing man pages altogether in
> Fedora
> > 2) Identify which packages having sub-par man pages
> 
> If we require that each man page should contain a few examples of
> usage, then we will find a lot more.
> 
> Many KDE applications lack proper man pages. Maybe #man  for those
> should call
> #khelpcenter help:/ or offer to install them (in case they are
> missing). OR do we consider the reverse conversion 2man??. Again there
> is the kde developer documentation (can be handled as well with man
> 1,2,...)
> 
> > What I could use help with from the more experienced would be, for
> > example, a way to identify the existence of man pages for packages.
> For
> > example, is it enough to have a single man page for a package, or do
> we
> > want a man page for every executable file?
> 
> Ideally references should be complete and every executable covered.
> 
> Take k3b for example. Its manual (GUI or CLI) does not get dynamically
> updated with the addition of executables (relevant ones).
Thanks for the interest & info!

I tend to agree that every executable as well as package (since that is
what some people may look for) should have a man page, even if it is
just a stub or refers to another.

In the case of KDE apps, if there does exist better documentation
coverage via another method, then we can extract content from there,
assuming it is licensed appropriately - I think most KDE apps are GPL,
so I imagine that or something compatible covers the documentation they
come with, as well.

I think examples of usage aren't necessary for coverage, but I think
it'd be great to identify man pages for level of helpfulness - for
example, we can have a rough checklist:
     1. Is the application or package given any kind of explanation?
     2. Are all command-line arguments explained?
     3. Are common caveats included?
     4. Is authorship mentioned and/or a place to report bugs?
     5. Are some examples of usage provided?
I'm sure this list could be better, this is just what I could think of
off the top of my head.

The idea of having complete man page coverage is to provide a universal
method for reference, upon which we can build other forms of
documentation, including Yelp or khelpcenter or web-based documentation.
This may go as far as having DocBook sources for original documentation
with man pages as a target (ala Publican, if such a feature gets
implemented).

There are all kinds of ideas that have been floated, but I think the man
page coverage is a great way to grab some low-hanging fruit, since all
that content would be licensed freely in the end, and bring about the
most benefit, both for Fedora, upstream, as well as other distributions.