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


--
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/1267694766.15754.13.ca...@meh

Reply via email to