[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

Re: doc-section madness

Greetings Daniele, [I have cc'd you, since I do not know if you are
subscribed to -policy]

* Daniele Cruciani <cruciani@cli.di.unipi.it> [001110 06:37]:
> 	I think this is the right place for asking change on policy
> about doc-base registering of package.

Sadly, I'm not sure what you are proposing can realistically be
accomplished in an organization such as Debian. (BTW, just for kicks,
take a look at OpenBSD's manual pages. Perhaps such quality is shared
amongst all the BSDs; I've only used OpenBSD.)

The major differences between OpenBSD and Debian is that OpenBSD (and
the other BSDs) is the origin of the programs. We take software from
wherever we can. They write/modify theirs as they see fit, and can
therefore make all the documentation fit in one place. I think we also
have a lot more software readily available than the BSDs, though there
is a much more clear distinction between 'core OS' and 'add-ons' in
those circles...

Debian, on the other hand, has many old pieces of software with manual
pages, GNU software with a philosophical bent against manpages (they use
info instead), and software from authors that either write their own
documentation software (eg, enlightenment's dox), or distribute
html/postscript/tex documentation.

There once was (still is?) the ability to install some programs on
debian that would turn http://localhost/doc/ or something similar into a
way of reading many of the sources of info at once -- man, info, html,
what is distributed in /usr/[share/]doc. Take a look at doc-central.

All in all, the various authors distribute docs how they feel, and until
someone cares enough (you? :) to merge all of the information into one
place, it just won't get done. (Point of proof -- on my machine with
roughly 500 packages installed (good god that is a lot of packages :)
there are roughly 350 manpages installed that point to the
"undocumented" manpage. Even though our policy currently requires
manpages of programs in packages, maintainers just end up using the
undocumented page to make users/lintian be quiet.)

It would seem to me that the only method of making it happen is to care
enough about it to do it yourself.

``Oh Lord; Ooh you are so big; So absolutely huge; Gosh we're all really
impressed down here, I can tell you.''

Reply to: