Re: Improvements/Fixes to Dpkg manual pages

[Guillem Jover <guillem@debian.org>]

Hi!

On Sun, 2025-08-24 at 08:51:55 +0000, Helge Kreutzmann wrote:
> I just updated the dpkg man pages translation and noticed the
> following:
> 
> deb-changelog
> =============
> The sentence is lacking any »ignored«?
> 
> "Any line that consists entirely (i.e., no leading whitespace) of B<#> or B</"
> "* */> style comments or RCS keywords."

Indeed, this looks like a regression from
commit e326eda15c84d0456aa2e1c22c996e89ef6c40f2.

I've added a "should be ignored" at the end of the sentence.

> deb-src-control
> ===============
> FIXME [!linux-any], → [!linux-any]

The trailing comma is correct in the source package template control
file context, because it makes it possible to add or removing entries
to the list without having to touch the preceding ones.

> " # Comment.\n"
> " Source: dpkg\n"
> " Section: admin\n"
> " Priority: required\n"
> " Maintainer: Dpkg Developers <debian-dpkg@lists.debian.org>\n"
> " # This field is copied to the binary and source packages.\n"
> " XBS-Upstream-Release-Status: stable\n"
> " Homepage: https://wiki.debian.org/Teams/Dpkg\n";
> " Vcs-Browser: https://git.dpkg.org/cgit/dpkg/dpkg.git\n";
> " Vcs-Git: https://git.dpkg.org/git/dpkg/dpkg.git\n";
> " Standards-Version: 4.7.2\n"
> " Build-Depends:\n"
> "  dpkg-build-api (= 1),\n"
> "  debhelper-compat (= 13),\n"
> "  debhelper (>= 13.10~),\n"
> "  pkgconf,\n"
> "  libselinux1-dev (>= 1.28-4) [!linux-any],\n"
> "\n"

> deb
> ===
> B<tar> → L<tar(1)>?
> 
> "The B<tar> archives currently allowed are:"

I think B<tar> is fine, because if it was a link it should probably be
L<tar(5)>, but we implement our own subset, so referring to an
external page describing what they support does not seem helpful.

> tar archive → B<tar> archive

> "The second required member is a tar archive containing the package control "
> "information."

Right, I see the inconsistency, and the same for «ar», but I'm not
sure whether marking all of them in bold would be too overwhelming.
Will ponder about it before pushing the changes.

> since 1.17.6 → since dpkg 1.17.6
> 
> "* xz (with B<.xz> extension, supported since 1.17.6)"

Thanks, applied.

> deb822(5) → L<deb822(5)>
> 
> "Mandatory core control information, in deb822(5) format."

Thanks, applied.

> dpkg-buildflags
> ===============
> and export → and exports
> 
> "Makefile snippet that loads (and optionally export) all flags supported by "
> "B<dpkg-buildflags> into variables (since dpkg 1.16.1)."

> export them → exports them
> 
> "Makefile snippet that sets suitable host and build tools (and optionally "
> "export them) into variables (since dpkg 1.19.0)."

Thanks, both applied.

> dpkg-query and dpkg
> ===================
> B<less> → L<less(1)>
> B<more> → L<more(1)>
> B<cat> → L<cat(1)>
> 
> "The B<DPKG_PAGER> overrides the B<PAGER> environment variable (since dpkg "
> "1.19.2).  If none of the programs pointed by B<DPKG_PAGER> or B<PAGER> are "
> "present, the following programs will be tried in order (since dpkg 1.22.12): "
> "the default pager B<%DPKG_DEFAULT_PAGER%>, then B<less>, B<more>, and "
> "finally B<cat>."

Thanks, applied.

> dpkg
> ====
> B<directory> → I<dir>
> 
> "Set the root directory to B<directory>, which sets the installation "
> "directory to «I<dir>» and the administrative directory to "
> "«I<dir>B<%ADMINDIR%>» if B<DPKG_ROOT> has not been set (since dpkg 1.21.10)."

Nice catch! I went instead with renaming «dir» to «directory» to match
all the other options in the same and other man pages.

Will include these in my next push, tomorrow or next day or so.

Thanks,
Guillem