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 more and more common with GUIs, as if a
> graphical program could always be self-explanatory.
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 screenshots, which are mandatory.
> I completely agree that a debian maintainer can't take the burden to
> write every man page upstream has not written, but that doesn't change
> the fact that a missing, outdated or incomplete manual is a bug - to
> be forwarded upstream if possible.
So far, such bugs have been mostly ignored by upstreams. And when they
have not, that’s where things get worse; some upstreams integrated the
manual pages and didn’t maintain them when they changed the command line
switches.
> 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 to do with our developer time and project resources.
> On a side note, I find the habit of replacing the manual with on-line
> html documentation terrible - we don't live in an always on-line world
> yet.
HTML documentation doesn’t have to be online. Packages that do that can
just copy the HTML tree in /usr/share/doc/$package.
> > Manual pages, OTOH, are not maintained properly by upstream developers.
>
> Sadly you are right.
> Please try to educate upstream whenever possible.
> Writing good documentation has never been fun, but it dramatically
> improves the usefulness of a program.
Upstreams often write good documentation. It just happens not to be in
the manual page format, which is not suitable for GUIS, but in --help
output and in HTML format.
Cheers,
--
.''`. Josselin Mouette
: :' :
`. `' “A handshake with whitnesses is the same
`- as a signed contact.” -- Jörg Schilling
Reply to: