On Tue, Apr 24, 2007 at 08:12:46AM -0700, Steve Langasek wrote:
> > If we are talking about hand-written documentation you're of course
> > right. However if you're talking about documentation which can be
> > generated automatically from sources (and not that it was the "ideal"
> > point of Neil) than you're not.
> There are ways to generate manpages from --help output of programs. We
> still have a lot of programs in Debian with no manpages.
According to my experience with html2man doesn't work that properly
every time, but I see your point. But still I don't get the objection:
is the laziness of people a good reason not to state the "right" path?
> > It happened to me many times to find library -dev packages with upstream
> > sources commented with some literate programming stuff but nevertheless
> > missing the corresponding automatically generated API docs in the
> > package. That's a pity. And that's something the policy should address.
>
> Hmm, I don't agree that it needs to be addressed in policy, FWIW.
Fair enough, but note that having man pages is actually addressed by the
policy. Why do you think API doc shouldn't? After all man pages are docs
for users and API doc are too, with the only difference that in the
latter case the "users" are programmers.
Cheers.
--
Stefano Zacchiroli -*- PhD in Computer Science ............... now what?
zack@{cs.unibo.it,debian.org,bononia.it} -%- http://www.bononia.it/zack/
(15:56:48) Zack: e la demo dema ? /\ All one has to do is hit the
(15:57:15) Bac: no, la demo scema \/ right keys at the right time
Attachment:
signature.asc
Description: Digital signature