Luca - De Whiskey's - De Vitis wrote:
> Debconf documentation is quite messy, or not moslty clear. I'll give you some
> examples of inconsistency i've foung between debconf_specification and
> debconf-devel(8)
>
> * debconf_specification lists type `text' as available while debconf-devel
> does not: none of them seems to assert it's the authoritative source of
> documentation.
This is because the text data-type is kind of unused and ill-supported
and deprecated. I have added a mention of it anyway.
The debconf specification is, as its title might suggest, authoratative.
The debconf-devel(7) man page is descriptive. And yes, it does refer
readers to the debconf specification for definitive docs, in at least 3
places.
> * neither debconf_specification nor debconf-devel(8) explicitly says that the
> Choices: field may include variables, but the example in debconf-devel(8)
> use this approach (ADVANCED PROGRAMING WITH DEBCONF -> Choosing among
> related packages)
This is mildly deprecated, and will be replaced with a better mechanism
in the future, if I can ever get anything through the policy process.
> * debconf_specification does not says anything about localization and fields
> name while debconf-devel(8) does.
> * More over, debconf-devel(8) does not speak about translated fields name
> like Description{-ll{_LL}} or Choices{-ll{_LL}}: you need to visit
> http://www.debian.org/intl/l10n/templates/hints to know anithing about
> this (ony about Description field.
> * debconf-devel(8) sugests to use po-debconf package, while
> http://www.debian.org/intl/l10n/templates/hints still suggests the
> `traditional' way.
I recently removed most of the details from debconf-devel(7) (which does
mention -ll fields still), since the internals of how the fields are
named is all handed by po-debconf now, like the man page says.
> Probably this bug should be cloned for debian-policy and debian-www.
> I suggests that 2 or 3 people to take the debconf documentation and start
> reorganizing it: i would be nicely one of these people.
Randolph Chung was planning at OLS to rewrite the debconf specifcation
into something that is understandable and up-to-date, but he has not
doing any work that I am aware of. There is my policy proposal #160776,
which I think hits most of the points you mentioned above BTW. That has
had two seconds in mid-september, but for some reason has not gotten
into recent releases of policy.
> I suggest that:
> * debconf-devel(8) should drop the section `THE TEMPLATES FILE', `THE CONFIG
> SCRIPT' and `THE DEBCONF PROTOCOL': these issues should be handled by the
> debconf_specification only which _must_ be the authoritative source.
debconf-devel(7) is there to be a single source that a package
maintainer should be able to read to learn pretty much everything they
need to know to use debconf. As such its descriptions of the debconf
protocol and templates file and config script are very important. Each
of these sections contains a lot of information and answers to FAQs that
will never get into the policy document. I will not be removing them. I
don't expect that keeping the few bits that overlap with the spec in
sync will be a big deal, since I have to update debconf's code anyway if
the spec changes.
> * debconf_specification _must_ be updated acordingly.
> * debconf-devel(8) should redirect to proper man pages keeping its content as
> small as possible. It's my opinon that this man page should only speack about
> hints and hacks developing with debconf.
I disagree. It's much nicer to have a single page that I can refer
developers to, and which can be read right though or used as a reference
than it is to have the docs scattered amoung many pages. I have gotten
many fewer repeated FAQs from developers about debconf since I wrote the
single large man page.
--
see shy jo
Attachment:
pgpsMzkC4sJEN.pgp
Description: PGP signature