[Debconf-devel] Bug#1124774: debconf-doc: Where is the user’s guide?

[Manny]

Package: debconf-doc
Version: 1.5.82
Severity: normal
X-Debbugs-Cc: debbug.debconf-doc at sideload.33mail.com

/usr/share/doc/debconf/README.Debian says:

> If you're looking for documentation on debconf, install the debconf-doc
> package and see debconf(7) and the other man pages in that package.

Running “aptitude show debconf-doc” shows:

> This package contains lots of additional documentation for Debconf,
> including the debconf user's guide, documentation about using
> different backend databases via the /etc/debconf.conf file, and a
> developer's guide to debconf.

This states that there is a “debconf user's guide”. When working on
Debian offline, such a thing would be indispensible. But it apparently
does not exist in that package. After installing debconf-doc, I
checked /usr/share/doc/debconf-doc and only see NEWS, copyright, and a
changelog. According to “apt-file show debconf-doc”, there are just a
few man pages.

The man page for debconf(1) does not pass for a user’s guide. The
debconf(7) man page gives some more information but still could not
pass for a user’s guide. Where are all the configuration fields
documented?

For example, I needed to solve a simple problem that should in
principle be solvable using a debconf command. After a new Debian
installation using primarily default options, we end up with
gnome. The machine goes to sleep very quick, after like 5 min of no
GUI activity. This is quite annoying for a terminal user because
typing running apps does not count as activity. Sleep mode could be
disabled in Gnome’s power settings, but the setting has no
effect. This is perhaps because a normal user should not have control
over system power modes.

Fair enough, but how does root change that?  When offline, we would
expect root to be able to use debconf to change that setting. But the
power settings are not mentioned nowhere in the debconf docs.

I see 2 possible fixes here:

 - (high effort) produce a comprehensive document that covers all possible pkg config fields
 - (low effort) edit the debconf-doc pkg description in apt to say something like “this is just a basic man page in English, French, and Spanish, and NOT a user guide covering config fields; (help wanted to create a comprehensive user guide)”.


-- System Information:
Debian Release: 12.12
  APT prefers oldstable-updates
  APT policy: (990, 'oldstable-updates'), (990, 'oldstable-security'), (990, 'stable'), (990, 'oldstable'), (500, 'oldoldstable')
Architecture: amd64 (x86_64)
Foreign Architectures: i386

Kernel: Linux 5.10.0-28-amd64 (SMP w/2 CPU threads)
Kernel taint flags: TAINT_OOT_MODULE, TAINT_UNSIGNED_MODULE
Locale: LANG=en_US.UTF-8, LC_CTYPE=en_US.UTF-8 (charmap=UTF-8), LANGUAGE not set
Shell: /bin/sh linked to /usr/bin/dash
Init: systemd (via /run/systemd/system)
LSM: AppArmor: enabled

debconf-doc depends on no packages.

debconf-doc recommends no packages.

Versions of packages debconf-doc suggests:
pn  debian-policy  <none>

-- no debconf information