Re: Removing the manpage requirement for GUI programs?
On Fri, Mar 05, 2010 at 03:53:14PM +0800, Paul Wise wrote:
> On Fri, Mar 5, 2010 at 3:41 PM, Daniel Leidert
> <Daniel.Leidert.Spam@gmx.net> wrote:
>
> > What's the problem, to write a short manual page, that points to the
> > --help switch? All the maintainer would have to do is to provide the
> > intention of the command, point to the help/usage switch, relevant
> > commands and to locally installed documentation. Such a manual page
> > won't unlikely become outdated and it doesn't need much maintenance.
> > This goes for both: authors and maintainers. But it still provides the
> > necessary information to the user.
>
> As a user I'd find such a manual page less than useless, it would be
> extremely annoying. In any case the undocumented(7) manual page covers
> these:
>
> http://manpages.debian.net/man/7/undocumented
Except that undocumented(7) does not say what the command does, and
makes guesses as to where the documentation is. A man page that says
"this program exists to do foo, and its documentation is at this exact
location" is infinitely more useful than man emitting "please go read
undocumented(7) and sod off".
> I find the following two options acceptable:
>
> Good, useful, up-to-date manual pages.
>
> No manual page at all.
>
> An outdated/unmaintained manual page or one that just points at --help
> or existing documentation isn't useful or acceptable.
It is useful if we can expect that each and every command in Debian
either has documentation or a pointer to documentation in its manual
page.
As things stand, one must guess: either the program has a man page, or
it has an info page, or it has a bunch of text or HTML files in
/usr/share/doc, or it is an interactive program that has an on-line help
system, or it has no packaged documentation at all and one must go find
it on some sourceforge.net wiki page. Or it might have a gzipped PDF
file, which is even more annoying, for it requires me to copy,
uncompress, read, remove the documentation.
Having a single way to figure out where the canonical documentation of a
program is, is *extremely* useful. Why not let the man page be that way?
Either it can be the canonical documentation itself, or it can have a
summary overview of the program and a good and exact pointer to where
the full documentation is.
I hate guessing almost as much as I hate hunting for documentation.
--
The biometric identification system at the gates of the CIA headquarters
works because there's a guard with a large gun making sure no one is
trying to fool the system.
http://www.schneier.com/blog/archives/2009/01/biometrics.html
Reply to: