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 -- To UNSUBSCRIBE, email to debian-devel-requ...@lists.debian.org with a subject of "unsubscribe". Trouble? Contact listmas...@lists.debian.org Archive: http://lists.debian.org/20100310141329.gd10...@celtic.nixsys.be
