Re: Removing the manpage requirement for GUI programs?
On Thu, Mar 04, 2010 at 10:40:57PM +0900, Charles Plessy wrote:
>
> Hello Josselin and everybody,
>
> I concur to much that has been written about obsolete manpages. In the past I
> often wrote manpages for my new packages, and in many cases they became a
> burden for me as a package maintainer when they did not get adopted upstream.
> Now my current point of view is that if there is no manpage, it is too often
> because the upstream author is not interested in writing and maintaining a
> manpage. Moreover, the nroff markup sytem is more suited to write novels than
> computer documentation (unless you like to put a backslash in front of every
> minus sign), so I use an intermediate format (usually DocBook), and in my
> experience, this source is often discarded, which makes it more difficult for
> me to help upstream to keep his manpage up to date. As a result, I do not write
> manpages anymore.
I'm one of those who think that a man page, that just says "This programme does
this, for more information look there" is better than no man page at all. It
helps those who think like me, it wouldn't put too much burden on the maintainer
and I don't see how it would do much harm to those, that think such a page minimal
page is useless.
> help2man is not the silver bullet either as it does not work on every help
> outputs. And if the goal is to be able to know about programs that are being
> run in the computer, the current policy is not enough anyway since some of them
> actually reside in /usr/lib or /usr/share, which are places out of the scope of
> Policy §12.1.
I recently prepared a patch to the package for rtmpdump for a new upstream version.
Command line options changed a bit and so the man pages had to be adapted. The
help output of the commands in this package produce a format that is almost but not
quite as help2man expects it. The obvious idea was to filter it through a simple
sed or awk script, but alas help2man insists on calling the command itself and
doesn't accept input on stdin. So maybe a wishlisht bug for help2man is in order? If
help2man was more flexible it might be useful in more circumstances.
> Still, it would be nice to be able to know about the purpose of the programs
> that are ran or stored on our computers. Would there be a way to hijack the
> whatis database of the man infrastructure for this, with for instance a section
> numero 0? A cheap solution would be to use manpages with only a NAME section.
> It would be trivial to write a helper script that is fed with a name and a
> one-line description, and that produces a Debian manpages. For programs with a
> GUI, the source of information could be the .desktop menu entry. It would have
> the great advantage that the information and the translations would be managed
> upstream.
Until such tools are available, a minimal man page is IMHO a good solution.
harry
Reply to: