From kde-core-devel  Tue Jul 22 11:06:05 2003
From: Ben Burton <bab () debian ! org>
Date: Tue, 22 Jul 2003 11:06:05 +0000
To: kde-core-devel
Subject: Re: KDE man page generator..
X-MARC-Message: https://marc.info/?l=kde-core-devel&m=105891388109422


Hi.

> In order to fix long-standing Debian bug #116485, I've written a
> script that takes a KDE app, and generates a nice man page.

Just a couple of suggestions.

1. OPTIONS section

It would be very nice if the script could split the options into
sections (APP OPTIONS, QT OPTIONS, KDE OPTIONS).  Otherwise it's quite
difficult to find the app-specific options amongst the generic Qt/KDE
options.

In the man pages I've written for debian I in fact include *only* the
app-specific options (and the generic koffice options for koffice apps),
and at the beginning of the OPTIONS section I include a line similar to:

    Below are the kbabel-specific options.  For a full summary of options,
    run kbabel --help.

This makes it easy for the user to see at a glance what options kbabel
offers that every other KDE app does not.  Sure it's nice to have
everything in the man page, but in this case I'd strongly argue for
splitting into separate options sections as described above.  Otherwise
there's just too much information.

2. SEE ALSO section

It may also be worth expanding the SEE ALSO section to make it clear
that the help:/... URL needs to be typed into konqueror - some users of
KDE apps don't run KDE as their primary desktop environment.

As an example, the kugar manpage currently in debian states:

   Full user documentation is available through the KDE Help Centre.  You
   can also enter the URL help:/kugar/ directly into konqueror or you can
   run `khelpcenter help:/kugar/' from the command-line.

Ben. :)