Bug#1110873: dpkg: DPKG_ROOT documentation unexpectedly mentions instdir

Hi!

On Tue, 2025-08-12 at 11:35:21 +0200, Ferenc Wágner wrote:
> What I miss here is when dpkg sets the DPKG_ROOT variable to something
> non-empty.  From the text I understand that dpkg sets DPKG_ROOT to the
> empty string when --root and --instdir are not set (so "normally").
> Furthermore, dpkg also sets DPKG_ROOT to the empty string when --root or
> --instdir is set, *unless* --force-script-chrootless is also specified
> (because the maintainer scripts are run in a chroot then).  So it would
> seem sensible if dpkg set DPKG_ROOT to the value of --instdir (or
> --root) if either of them is specified, *and* --force-script-chrootless
> is also specified.  But the text does not say that, instead it contrasts
> DPKG_ROOT being empty with instdir being non-empty.  This is unexpected,
> and I don't even understand instdir in the "Internal environment"
> context where this paragraph resides.
> 
> I'm not sure I managed to express my difficulty any better now...

Ah! I think I see what you mean now. Would the attached patch fix the
confusing text?

(I also noticed that there's no documentation for dpkg honoring
DPKG_ROOT and DPKG_ADMINDIR being set when it runs, which was a
recentish behavior change, will document that too.)

Thanks,
Guillem

diff --git i/man/dpkg.pod w/man/dpkg.pod
index 8349f0afd..001373b75 100644
--- i/man/dpkg.pod
+++ w/man/dpkg.pod
@@ -1438,8 +1438,8 @@ During normal operation, this variable is empty.
 When installing packages into a different B<instdir>, B<dpkg>
 normally invokes maintainer scripts using L<chroot(2)> and leaves
 this variable empty, but if B<--force-script-chrootless> is
-specified then the L<chroot(2)> call is skipped and B<instdir>
-is non-empty.
+specified then the L<chroot(2)> call is skipped and
+this variable is set to B<instdir> (which will be non-empty).
 
 =item B<DPKG_ADMINDIR>