Re: Removing the manpage requirement for GUI programs?
Le Sat, Feb 27, 2010 at 08:06:37PM +0100, Josselin Mouette a écrit :
>
> currently policy §12.1 mandates that “each program, utility, and
> function should have an associated manual page”. However, the more I
> stomp on bug reports about manual pages, the less I am convinced of
> their usefulness for GUI programs.
> Therefore I propose that we drop the requirement of a manual page if
> these conditions are met:
> * the program requires graphical interaction with the user, and is
> not meant to be used from a script;
> * the command-line switches are properly documented with a --help
> option.
> For extra points, we could agree on a way to generate manual pages
> automatically, either at installation time or on the fly, using
> help2man.
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.
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.
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.
So in conclusion, I think that the "should" in Policy §12.1 is too strong, and
I think that the problem is not limited to GUI programs. Also, if patch is sent
to the Policy on this subject, I will propose an additional note that invites
people to do their manpage request or proposition upstream first. We already
have Lintian to tell us that there is no manpage, so there is no need to open a
bug.
Lastly, this issue is not specific to Debian. Does anybody knows what the other
systems are doing?
--
Charles Plessy
Tsurumi, Kanagawa, Japan
Reply to: