Re: [Rant] Re: Removing the manpage requirement for GUI programs?
On Sun, Mar 07, 2010 at 09:50:12AM +0100, Josselin Mouette wrote:
> Le vendredi 05 mars 2010 à 17:41 +0000, brian m. carlson a écrit :
> > This still has the problem that I don't know immediately where to get
> > the documentation. Do I use the GNOME help system? KDE's? man? info?
> > a DVI? a PDF? The benefit of manual pages is that there is one uniform
> > way to get basic documentation on a command and how it is to be run.
> > Other documentation can be referenced from that manual page.
>
> This discussion is running into circles.
>
> GNOME, Xfce and KDE maintainers all explained that we have no interest
> in working on manual pages, and our upstreams don’t either.
You don't need to. All you need to do is make sure that "man $prog"
returns something useful. "This program does foo, and the documentation
is over at bar" is something useful, and could be done by a script that
has three points of information: the name of the program, whatever "foo"
is, and whatever "bar" is.
> Those who are nostalgic of the time when a text-only documentation
> system was enough keep repeating ad nauseam “but we need manual pages”.
No, we need a uniform documentation system. Personally, I don't care
whether that uniform documentation system is "man pages" or "HTML
files" or something else, but traditionally, in Debian, that
documentation system has been "man pages", so in the absense of a
compelling argument as to why we should change that, I do not see why we
should -- especially because changing from one documentation system to
another would involve a load of work.
Also note that any alternate uniform documentation system should be
usable for all our users, be they GNOME, KDE or XFCE users, webserver
sysadmins with only a shell through SSH, or those of us who simply
prefer text-only documentation.
Having a uniform documentation system that occasionally says "in this
particular case you need to go look at this other documentation system
rather than me" is not really a problem. Having a "uniform"
documentation system that occasionally says "I don't know what the fuck
you're talking about, sod off", however, is a problem, because it
defeats the point of having a uniform documentation system in the first
place.
[...]
> At this point of the discussion, this should be clear: either you do
> whatever it takes to have your precious manual pages in all Debian
> packages, either you don’t. And if you don’t, I would appreciate that
> you just STFU instead. Maintainers who are already overloaded are not
> here just to take orders from others.
You were suggesting that we just give up on our uniform documentation
system because we're not there yet, and people are understandably upset
about that.
Nobody is suggesting that you take on work that you don't want to take
on; people are instead suggesting that it's okay to have those bugs
open, but that they should still be considered bugs, since they break
the assumption of a uniform documentation system.
> I will personally just sit on policy §12.1, mark manpage-related bugs as
> wontfix, and, to plagiarize Yves-Alexis, it won’t prevent me from
> sleeping at night.
Which is perfectly fine -- they're not RC.
--
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: