Tiny is Fine! [Was Re: Removing the manpage requirement for GUI programs?]

Please don't let the PERFECT be the enemy of the GOOD. It would be perfect if we had complete man pages for all programs. But a one-line (not including NAME section header) man page like this: graphdraw - directed graph editor derived from drawtool is not just good; it is 100x better than no

Re: Removing the manpage requirement for GUI programs?

On 2010-03-10 13:52:15 +0100, Wouter Verhelst wrote: > Or it might have a gzipped PDF file, which is even more annoying, > for it requires me to copy, uncompress, read, remove the > documentation. zxpdf from xpdf-reader can handle it. But I wonder why the need for two separate commands while the f

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 +, 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

Re: Removing the manpage requirement for GUI programs?

On Thu, Mar 04, 2010 at 04:36:56PM +0100, Josselin Mouette wrote: > I can’t help noticing, though, that it would only duplicate > functionality that is already present in search engines of desktop help > systems (which are also able to search in manual pages, FWIW). I can't help noticing, though,

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 > 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, po

Re: [Rant] Re: Removing the manpage requirement for GUI programs?

On Sun, 2010-03-07 at 13:09 +, Sune Vuorela wrote: > On 2010-03-07, Frank Lin PIAT wrote: > >> GNOME, Xfce and KDE maintainers all explained that we have no interest > >> in working on manual pages, and our upstreams don???t either. > > > > This is an important information that many people wer

Re: [Rant] Re: Removing the manpage requirement for GUI programs?

On 2010-03-07, Frank Lin PIAT wrote: >> GNOME, Xfce and KDE maintainers all explained that we have no interest >> in working on manual pages, and our upstreams don???t either. > > This is an important information that many people weren't aware of (at > least, myself). So you didn't read the full

Re: [Rant] Re: Removing the manpage requirement for GUI programs?

On Sun, 2010-03-07 at 09:50 +0100, Josselin Mouette wrote: > Le vendredi 05 mars 2010 à 17:41 +, 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?

[Rant] Re: Removing the manpage requirement for GUI programs?

Le vendredi 05 mars 2010 à 17:41 +, 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 g

Re: Removing the manpage requirement for GUI programs?

Le vendredi 05 mars 2010 à 18:53 -0800, Russ Allbery a écrit : > This seems like an unnecessarily complex way of implementing the idea of > generating man pages from .desktop files. Why would you not simply write > a script that generates a traditional *roff man page from a .desktop file? > It see

Re: Removing the manpage requirement for GUI programs?

Charles Plessy writes: > for the record, I have sumbitted to the Debian fork of the man system > the idea of tapping into the desktop menu entries when a program has no > manpage. > https://savannah.nongnu.org/bugs/index.php?29083 This seems like an unnecessarily complex way of implementing the

Re: Removing the manpage requirement for GUI programs?

Hello everybody, for the record, I have sumbitted to the Debian fork of the man system the idea of tapping into the desktop menu entries when a program has no manpage. https://savannah.nongnu.org/bugs/index.php?29083 “For those who care about manpages”, I would like to point out that the origina

Re: Removing the manpage requirement for GUI programs?

On 2010-03-05 10:56:21 +0100, Daniel Leidert wrote: > Of course it does not happen, that evolution crashes for specific > mails and then keeps crashing on every new start, because it opens the > same mail. The only way to fix this, is to start with a different > component. Do you need the bug repor

Re: Removing the manpage requirement for GUI programs?

On 2010-03-05 11:04:48 +0100, Josselin Mouette wrote: > Command-line switches are documented where you expect them to be > documented: in command-line switches, with the standard --help option. This is nonsense. Not all commands understand --help. -- Vincent Lefèvre - Web:

Re: Removing the manpage requirement for GUI programs?

On 2010-03-05 17:41:25 +, brian m. carlson wrote: > Allowing "any format viewable in Debian" potentially requires the > average user to install lots of random packages just to view basic > documentation on invoking a program. Also, providing, for example, PDF > documentation as the sole form f

Re: Removing the manpage requirement for GUI programs?

On Thu, Mar 04, 2010 at 04:32:45PM +0100, Josselin Mouette wrote: > Le jeudi 04 mars 2010 à 15:20 +0100, Bill Allombert a écrit : > > On Thu, Mar 04, 2010 at 10:26:06AM +0100, Josselin Mouette wrote: > > > No. It’s just that they ship with HTML documentation, which is much more > > > suitable for d

Re: Removing the manpage requirement for GUI programs?

On Fri, Mar 05, 2010 at 04:09:05PM +0800, Paul Wise wrote: > 2010/2/28 Josselin Mouette : > > > 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 convi

Re: Removing the manpage requirement for GUI programs?

On 5 March 2010 17:46, Yves-Alexis Perez wrote: > Le 27/02/2010 22:11, markus schnalke a écrit : > >> Man pages have one more important advantage: Every command has one. > > Which is not true, and the point of the discussion. I think it should have read: They (should) provide a uniform way to ac

Re: Removing the manpage requirement for GUI programs?

Le 27/02/2010 22:11, markus schnalke a écrit : > [2010-02-27 20:06] Josselin Mouette >> >> I think it is a waste of time to write manual pages that won't be >> maintained upstream, and that won't contain more useful information than >> --help. The purpose of a manual page is to document precisely

Re: Removing the manpage requirement for GUI programs?

Le 05/03/2010 11:04, Josselin Mouette a écrit : > Furthermore, for a few releases now, evolution has stopped displaying a > message that triggered a crash on startup. If it still happens for you, > you might consider filing a bug (in addition to the one where you submit > the backtrace for your cra

Re: Removing the manpage requirement for GUI programs?

Le 05/03/2010 08:41, Daniel Leidert a écrit : > You need a dozen GROFF macros and 2 or 3 escapes. And this is a > burden to you guys? Really? Yes. But if you volunteer to do that upstream, I'm sure it'll be really appreciated. I have stuff way more interesting and/or urgent to do on Debian (and as

Re: Removing the manpage requirement for GUI programs?

Le vendredi 05 mars 2010 à 10:56 +0100, Daniel Leidert a écrit : > Of course it does not happen, that evolution crashes for specific > mails and then keeps crashing on every new start, because it opens the > same mail. The only way to fix this, is to start with a different > component. Do you need

Re: Removing the manpage requirement for GUI programs?

Josselin Mouette wrote: > Le vendredi 05 mars 2010 à 09:30 +0100, Vincent Lefevre a écrit : > > > Because the users have not yet decided if they want to start the > > > application > > > and they look to the manpage for guidance. > > > > Yes, and for various reasons, it may happen that the applic

Re: Removing the manpage requirement for GUI programs?

Le vendredi 05 mars 2010 à 08:41 +0100, Daniel Leidert a écrit : > You need a dozen GROFF macros and 2 or 3 escapes. And this is a > burden to you guys? Really? Given the benefit, which is close to zero? Yes. -- .''`. Josselin Mouette : :' : `. `' “A handshake with whitnesses is the same

Re: Removing the manpage requirement for GUI programs?

Le vendredi 05 mars 2010 à 09:30 +0100, Vincent Lefevre a écrit : > > Because the users have not yet decided if they want to start the application > > and they look to the manpage for guidance. > > Yes, and for various reasons, it may happen that the application > doesn't start (e.g. due to incorr

Re: Removing the manpage requirement for GUI programs?

On 2010-03-05, Daniel Leidert wrote: > You need a dozen GROFF macros and 2 or 3 escapes. And this is a > burden to you guys? Really? Patches welcome. I think we have the need of a couple of hundred in KDE. Probably something similar in gnome land. and also quite many in xfce. /Sune -- To UNSU

Re: Removing the manpage requirement for GUI programs?

On 2010-03-04 17:12:15 +0100, Bill Allombert wrote: > On Thu, Mar 04, 2010 at 04:32:45PM +0100, Josselin Mouette wrote: > > Because, of course, the user is too stupid to click the “Help” menu > > inside the application. > > Because the users have not yet decided if they want to start the applicati

Re: Removing the manpage requirement for GUI programs?

On Fri, 2010-03-05 at 15:53 +0800, Paul Wise wrote: > On Fri, Mar 5, 2010 at 3:41 PM, Daniel Leidert > 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

Re: Removing the manpage requirement for GUI programs?

2010/2/28 Josselin Mouette : > 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. How about replacing "an

Re: Removing the manpage requirement for GUI programs?

On Fri, Mar 5, 2010 at 3:41 PM, Daniel Leidert 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 instal

Re: Removing the manpage requirement for GUI programs?

Yves-Alexis Perez wrote: > On jeu., 2010-03-04 at 22:54 +1100, Ben Finney wrote: > > Josselin Mouette writes: > > > > > Letting alone policy issues: what do you propose, *concretely* to > > > improve the situation? > > > > The situation is as it is: many commands lack proper manual pages. I > >

Re: Removing the manpage requirement for GUI programs?

On ven., 2010-03-05 at 09:49 +1100, Ben Finney wrote: > Yves-Alexis Perez writes: > > > On jeu., 2010-03-04 at 22:54 +1100, Ben Finney wrote: > > > file bug reports, work with upstream to have properly maintained > > > manpages, close the bug reports as fixed when that happens. > > > > My upstrea

Re: Removing the manpage requirement for GUI programs?

Yves-Alexis Perez writes: > On jeu., 2010-03-04 at 22:54 +1100, Ben Finney wrote: > > file bug reports, work with upstream to have properly maintained > > manpages, close the bug reports as fixed when that happens. > > My upstream position is exactly what started the thread: no need to > have dup

Re: Removing the manpage requirement for GUI programs?

On 04/03/10 20:00, Yves-Alexis Perez wrote: > > Josselin Mouette writes: > > > Letting alone policy issues: what do you propose, *concretely* to > > > improve the situation? A man page containing a *brief* (one or two lines) description of what the program does and pointers to further more compre

Re: Removing the manpage requirement for GUI programs?

Josselin Mouette writes: > Le jeudi 04 mars 2010 à 01:22 +0100, Luca Niccoli a écrit : >> As has already been noted, the policy says there SHOULD be a manual >> page, so a missing one doesn't make a package RC buggy. > No, but it fills the BTS with pointless bugs. I think we have better > things

Re: Removing the manpage requirement for GUI programs?

On jeu., 2010-03-04 at 22:54 +1100, Ben Finney wrote: > Josselin Mouette writes: > > > Letting alone policy issues: what do you propose, *concretely* to > > improve the situation? > > The situation is as it is: many commands lack proper manual pages. I > don't propose to change the existing appr

Re: Removing the manpage requirement for GUI programs?

On Thu, Mar 04, 2010 at 04:32:45PM +0100, Josselin Mouette wrote: > Le jeudi 04 mars 2010 à 15:20 +0100, Bill Allombert a écrit : > > On Thu, Mar 04, 2010 at 10:26:06AM +0100, Josselin Mouette wrote: > > > No. It’s just that they ship with HTML documentation, which is much more > > > suitable for d

Re: Removing the manpage requirement for GUI programs?

Le jeudi 04 mars 2010 à 22:40 +0900, Charles Plessy a écrit : > 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 > sec

Re: Removing the manpage requirement for GUI programs?

Le jeudi 04 mars 2010 à 15:20 +0100, Bill Allombert a écrit : > On Thu, Mar 04, 2010 at 10:26:06AM +0100, Josselin Mouette wrote: > > No. It’s just that they ship with HTML documentation, which is much more > > suitable for documenting a GUI. A manual page cannot contain things as > > trivial as sc

Re: Removing the manpage requirement for GUI programs?

On Thu, Mar 04, 2010 at 10:26:06AM +0100, Josselin Mouette wrote: > Le jeudi 04 mars 2010 à 01:22 +0100, Luca Niccoli a écrit : > > Manuals are not only for documenting command line switches, they > > should actually explain how to use a program. > > I found the lack of good man pages one of the mo

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 w

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

Re: Removing the manpage requirement for GUI programs?

Josselin Mouette writes: > Letting alone policy issues: what do you propose, *concretely* to > improve the situation? The situation is as it is: many commands lack proper manual pages. I don't propose to change the existing approach for dealing with this: file bug reports, work with upstream to

Re: Removing the manpage requirement for GUI programs?

On Thu, Mar 04, 2010 at 10:20:44AM +0100, Josselin Mouette wrote: > So far the only thing that I can conclude from this “discussion” (just a > gathering of rants, actually) is that we should just remove manual pages > that are not maintained upstream and tag all related bugs wontfix. YMMV. I've pe

Re: Removing the manpage requirement for GUI programs?

Le jeudi 04 mars 2010 à 01:22 +0100, Luca Niccoli a écrit : > Manuals are not only for documenting command line switches, they > should actually explain how to use a program. > I found the lack of good man pages one of the most annoying and > widespread problems of OSS. > Unfortunately, this gets m

Re: Removing the manpage requirement for GUI programs?

Le jeudi 04 mars 2010 à 09:07 +1100, Ben Finney a écrit : > It's already been pointed out that good manpages are plenty useful for > those programs in the proposed exclusion class. The “should” applies > equally well to those programs too. > > Sure, some programs don't have good manpages. But that

Re: Removing the manpage requirement for GUI programs?

On Wed, Mar 03, 2010 at 07:17:14PM +0100, Yves-Alexis Perez wrote: > On 28/02/2010 01:32, Ben Finney wrote: > > Josselin Mouette writes: > > > >> > Yes, I overall agree with your arguments. However having it in the > >> > policy means we get bug reports about manual pages and have to deal > >> >

Re: Removing the manpage requirement for GUI programs?

2010/2/27 Josselin Mouette : > GUI applications usually take only a few simple command-line options, > and more importantly, when you use a modern development framework, these > options will always be documented correctly with the --help switch. Manuals are not only for documenting command line s

Re: Removing the manpage requirement for GUI programs?

Yves-Alexis Perez writes: > On 28/02/2010 01:32, Ben Finney wrote: > > If manpages were useful only for documenting command-line options, > > this would be a valid point. As has been pointed out, though, > > manpages for programs are useful for much more than that. > > But that's why he doesn't p

Re: Removing the manpage requirement for GUI programs?

On 28/02/2010 01:32, Ben Finney wrote: > Josselin Mouette writes: > >> > Yes, I overall agree with your arguments. However having it in the >> > policy means we get bug reports about manual pages and have to deal >> > with them, while they are not the primary source of documentation for >> > comm

Re: Removing the manpage requirement for GUI programs?

On Sat, Feb 27, 2010 at 08:06:37PM +0100, Josselin Mouette wrote: > Hi, > > 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; >

Re: Removing the manpage requirement for GUI programs?

On 2010-02-27 21:03:04 +0100, Josselin Mouette wrote: > We are talking of programs that you will not have the idea to run with > the command line unless you know what they do. Programs that are usually > run through a graphical menu. They are sometimes found by shell completion. Moreover, before c

Re: Removing the manpage requirement for GUI programs?

On Sat, Feb 27, 2010 at 03:30:49PM -0800, Don Armstrong wrote: > The crux of your argument is that for many GUI programs, manpages > aren't as essential as other forms of documentation, and developer > time would be better spent doing making other improvements. I acknowledge this part of the probl

Re: Removing the manpage requirement for GUI programs?

]] Josselin Mouette | In my opinion, we’d be better off with no manual page than with one | that is not maintained correctly. However the current policy | encourages shipping a buggy manual page over not shipping it at all. Would a reasonable compromise be to ship a man page that says something

Re: Removing the manpage requirement for GUI programs?

Josselin Mouette writes: > Yes, I overall agree with your arguments. However having it in the > policy means we get bug reports about manual pages and have to deal > with them, while they are not the primary source of documentation for > command-line options. If manpages were useful only for doc

Re: Removing the manpage requirement for GUI programs?

2010/2/27 Josselin Mouette : > Hi, > > 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. > > GUI applicati

Re: Removing the manpage requirement for GUI programs?

"brian m. carlson" writes: > On Sat, Feb 27, 2010 at 08:06:37PM +0100, Josselin Mouette wrote: > > 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

Re: Removing the manpage requirement for GUI programs?

On Sun, 28 Feb 2010, Josselin Mouette wrote: > However having it in the policy means we get bug reports about > manual pages and have to deal with them, while they are not the > primary source of documentation for command-line options. I'd hope you'd still get bug reports even if it wasn't in poli

Re: Removing the manpage requirement for GUI programs?

Josselin Mouette writes: > Yes, I overall agree with your arguments. However having it in the > policy means we get bug reports about manual pages and have to deal with > them, while they are not the primary source of documentation for > command-line options. > In my opinion, we’d be better off

Re: Removing the manpage requirement for GUI programs?

Le samedi 27 février 2010 à 15:30 -0800, Don Armstrong a écrit : > If the manpage doesn't contain any more information than the help > output, then it probably should be replaced with help2man so that it > stays up to date. > > The crux of your argument is that for many GUI programs, manpages > a

Re: Removing the manpage requirement for GUI programs?

On Sat, 27 Feb 2010, Josselin Mouette wrote: > The current situation is that there are a lot of outdated and/or > inaccurate manpages, while the --help output contains the same amount of > information and is guaranteed to be up-to-date. If the manpage doesn't contain any more information than the

RE: Removing the manpage requirement for GUI programs?

Le samedi 27 février 2010 à 20:14 +, Fuentes, Adolfo a écrit : > I think it is a good idea to have a centralized system where one can > find information about a particular program. Otherwise we take the > risk of having a sparse information system. If help2man helps to > create the man page fro

Re: Removing the manpage requirement for GUI programs?

Le samedi 27 février 2010 à 20:29 +, brian m. carlson a écrit : > lakeview ok % gcalctool --help > Usage: > gcalctool - Perform mathematical calculations > Tell me what user files gcalctool may access, using only this > information. Also tell me, using *only the information provided*, how

Re: Removing the manpage requirement for GUI programs?

Josselin Mouette wrote the following on 27.02.2010 21:03 -- -- > Indeed it is not sufficient for gcc-4.4. But I still think it is > sufficient for gcalctool. I have just downloaded the lenny gcalctool_5.22.3-2_i386.deb. Where in /usr/share/gnome/help/gcalctool do you read about the file "~/.gca

Re: Removing the manpage requirement for GUI programs?

markus schnalke wrote: > [2010-02-27 20:06] Josselin Mouette >> I think it is a waste of time to write manual pages that won't be >> maintained upstream, and that won't contain more useful information than >> --help. The purpose of a manual page is to document precisely the >> behavior of a progra

Re: Removing the manpage requirement for GUI programs?

[2010-02-27 20:06] Josselin Mouette > > I think it is a waste of time to write manual pages that won't be > maintained upstream, and that won't contain more useful information than > --help. The purpose of a manual page is to document precisely the > behavior of a program, and for GUI application

Re: Removing the manpage requirement for GUI programs?

On Sat, 2010-02-27 at 11:14 -0800, Russ Allbery wrote: > Josselin Mouette writes: > > > GUI applications usually take only a few simple command-line options, > > and more importantly, when you use a modern development framework, these > > options will always be documented correctly with the --hel

RE: Removing the manpage requirement for GUI programs?

an proverb) From: Josselin Mouette [j...@debian.org] Sent: 27 February 2010 20:03 To: debian-devel@lists.debian.org Subject: Re: Removing the manpage requirement for GUI programs? Le samedi 27 février 2010 à 19:49 +, brian m. carlson a écrit : > Additionally, in some cases, the --help

Re: Removing the manpage requirement for GUI programs?

On Sat, Feb 27, 2010 at 09:03:04PM +0100, Josselin Mouette wrote: > Le samedi 27 février 2010 à 19:49 +, brian m. carlson a écrit : > > Additionally, in some cases, the --help output is not sufficient to > > explain what a program does. "gcc-4.4 --help" does not list all the > > options; one

Re: Removing the manpage requirement for GUI programs?

Le samedi 27 février 2010 à 19:49 +, brian m. carlson a écrit : > Additionally, in some cases, the --help output is not sufficient to > explain what a program does. "gcc-4.4 --help" does not list all the > options; one has to use "gcc-4.4 -v --help". Also, using only the > latter, please tel

Re: Removing the manpage requirement for GUI programs?

On Sat, Feb 27, 2010 at 08:06:37PM +0100, Josselin Mouette wrote: > 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; > * t

Re: Removing the manpage requirement for GUI programs?

Keep in mind that the apropos command only searches man pages, so I strongly support keeping them around and creating them (even if only from --help) when they're missing. 2010/2/27 Josselin Mouette > Hi, > > currently policy §12.1 mandates that “each program, utility, and > function should have

Re: Removing the manpage requirement for GUI programs?

Josselin Mouette writes: > GUI applications usually take only a few simple command-line options, > and more importantly, when you use a modern development framework, these > options will always be documented correctly with the --help switch. > Manual pages, OTOH, are not maintained properly by up

Removing the manpage requirement for GUI programs?

Hi, 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. GUI applications usually take only a few simple command-