[[email protected]: apt.conf.5: Some remarks and a patch with editorial changes for this man page]

  Additional remarks.

  Mails from me to "[email protected]" are no longer acknowledged.  A
Debian maintainer told me, that he would contact the mail administrator
about me not wanting to send bugs upstream.

----- Forwarded message from Bjarni Ingi Gislason <[email protected]> -----

Date: Fri, 10 Apr 2026 02:57:07 +0000
From: Bjarni Ingi Gislason <[email protected]>
To: Debian Bug Tracking System <[email protected]>
Subject: apt.conf.5: Some remarks and a patch with editorial changes for this man page
X-Mailer: reportbug 13.2.0

Package: apt
Version: 3.2.0
Severity: minor
Tags: patch

Dear Maintainer,

>From "/usr/share/doc/debian/bug-reporting.txt.gz":

  Don't file bugs upstream

   If you file a bug in Debian, don't send a copy to the upstream software
   maintainers yourself, as it is possible that the bug exists only in
   Debian. If necessary, the maintainer of the package will forward the
   bug upstream.

-.-

  For forwarding bug reports to upstream see:

https://www.debian.org/Bugs/Developer#forward

-.-

  I do not send reports upstream if I have to get an account there.
The Debian maintainers have one already.

  If I get a negative (or no) response from upstream, I send henceforth
bugs to Debian.

-.-

   * What led up to the situation?

     Checking for defects with a new version

test-[g|n]roff -mandoc -t -K utf8 -rF0 -rHY=0 -rCHECKSTYLE=0 -ww -z < "man page"

  [Use 

grep -n -e ' $' -e '\\~$' -e ' \\f.$' -e ' \\"' <file>

  to find (most) trailing spaces.]

  ["test-groff" is a script in the repository for "groff"; is not shipped]
(local copy and "troff" slightly changed by me).

  [The fate of "test-nroff" was decided in groff bug #55941.]

   * What was the outcome of this action?

Output from "test-nroff  -mandoc -t -K utf8 -rF0 -rHY=0 -rCHECKSTYLE=0 -ww -z ":

troff:<stdin>:223: warning [page 1, line 135]: cannot adjust (align) with both margins ; underset by 30n


   * What outcome did you expect instead?

     No output (no warnings).

-.-

  General remarks and further material, if a diff-file exist, are in the
attachments.


-- System Information:
Debian Release: forky/sid
  APT prefers testing
  APT policy: (500, 'testing')
Architecture: amd64 (x86_64)

Kernel: Linux 6.19.10+deb14-amd64 (SMP w/2 CPU threads; PREEMPT)
Locale: LANG=is_IS.iso88591, LC_CTYPE=is_IS.iso88591 (charmap=ISO-8859-1), LANGUAGE not set
Shell: /bin/sh linked to /usr/bin/dash
Init: sysvinit (via /sbin/init)

Versions of packages apt depends on:
ii  adduser                 3.155
ii  base-passwd             3.6.8
ii  debian-archive-keyring  2025.1
ii  libapt-pkg7.0           3.2.0
ii  libc6                   2.42-14
ii  libgcc-s1               16-20260322-1
ii  libseccomp2             2.6.0-2+b1
ii  libssl3t64              3.6.1-3
ii  libstdc++6              16-20260322-1
ii  libsystemd0             260.1-1
ii  sqv                     1.3.0-5

Versions of packages apt recommends:
ii  ca-certificates  20260223

Versions of packages apt suggests:
ii  apt-doc         3.2.0
ii  aptitude        0.8.13-8+b1
ii  dpkg-dev        1.23.7
ii  gnupg           2.4.9-4
pn  powermgmt-base  <none>

-- no debconf information

Input file is apt.conf.5

Output from "mandoc -T lint  apt.conf.5": (shortened list)

    140 STYLE: input text line longer than 80 bytes: 
      2 WARNING: empty block: RS
     16 WARNING: skipping paragraph macro: PP after SH

-.-.

Output from
test-nroff -mandoc -t -Kutf8 -ww -z apt.conf.5: (shortened list)

      1 cannot adjust (align) with both margins ; underset by 30n

-.-.

Show if docman-to-man created this.

Patches to generated man pages are to show where the generator failed to
make a "clean" man page rendering (that is without warnings) and sometimes
what could be a better generated man page.

4:.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>

-.-.

Remove space characters (whitespace) at the end of lines.
Use "git apply ... --whitespace=fix" to fix extra space issues, or use
global configuration "core.whitespace".

Number of lines affected is

3

-.-.

Add a (no-break, "\ " or "\~") space between a number and a unit,
as these are not one entity.

715:The maximum file size of Release/Release\&.gpg/InRelease files\&. The default is 10MB\&.

-.-.

Wrong distance (not two spaces) between sentences in the input file.

  Separate the sentences and subordinate clauses; each begins on a new
line.  See man-pages(7) ("Conventions for source file layout") and
"info groff" ("Input Conventions").

  The best procedure is to always start a new sentence on a new line,
at least, if you are typing on a computer.

Remember coding: Only one command ("sentence") on each (logical) line.

E-mail: Easier to quote exactly the relevant lines.

Generally: Easier to edit the sentence.

Patches: Less unaffected text.

Search for two adjacent words is easier, when they belong to the same line,
and the same phrase.

  The amount of space between sentences in the output can then be
controlled with the ".ss" request.

Mark a final abbreviation point as such by suffixing it with "\&".

Some sentences (etc.) do not begin on a new line.

Split (sometimes) lines after a punctuation mark; before a conjunction.

  Lines with only one (or two) space(s) between sentences could be split,
so latter sentences begin on a new line.

Use

#!/usr/bin/sh

sed -e '/^\./n' \
-e 's/\([[:alpha:]]\)\.  */\1.\n/g' $1

to split lines after a sentence period.
Check result with the difference between the formatted outputs.
See also the attachment "general.bugs"

[List of affected lines removed.]

-.-

Split lines longer than 80 characters (fill completely
an A4 sized page line on a terminal)
into two or more lines.
Appropriate break points are the end of a sentence and a subordinate
clause; after punctuation marks.
Add "\:" to split the string for the output, "\<newline>" in the source.  

[List of affected lines removed.]

Longest line is number 328 with 822 characters
The immediate configuration marker is also applied in the potentially problematic case of circular dependencies, since a dependency with the immediate flag is equivalent to a Pre\-Dependency\&. In theory this allows APT to recognise a situation in which it is unable to perform immediate configuration, abort, and suggest to the user that the option should be temporarily deactivated in order to allow the operation to proceed\&. Note the use of the word "theory" here; in the real world this problem has rarely been encountered, in non\-stable distribution versions, and was caused by wrong dependencies of the package in question or by a system in an already broken state; so you should not blindly disable this option, as the scenario mentioned above is not the only problem it can help to prevent
  in the first place\&.

-.-.

Remove unnecessary double font change (e.g., \fR\fI) in a row or (better)
use a two-fonts macro.

780:\fBBinary::\fR\fB\fIspecific\-binary\fR\fR

-.-.

Put a parenthetical sentence, phrase on a separate line,
if not part of a code.
See man-pages(7), item "semantic newline".

[List of affected lines removed.]

-.-

Use a character "\(->" instead of plain "->" or "\->", if not typeset with
a constant width font.

1205:package\-name <a\&.b\&.c \-> d\&.e\&.f | x\&.y\&.z> (section)

-.-.

No need for '\&' to be in front of a period (.),
if there is a character in front of it.

Remove with "sed -e 's/\(.\)\\&\./\1./g'".

[List of affected lines removed.]

-.-.

Only one space character is after a possible end of sentence
(after a punctuation, that can end a sentence).

[List of affected lines removed.]

-.-.

Remove quotes when there is a printable
but no space character between them
and the quotes are not for emphasis (markup),
for example as an argument to a macro.

apt.conf.5:10:.TH "APT\&.CONF" "5" "05\ \&March\ \&2026" "APT 3.2.0" "APT"
apt.conf.5:30:.SH "NAME"
apt.conf.5:32:.SH "DESCRIPTION"
apt.conf.5:100:.SH "SYNTAX"
apt.conf.5:790:.SH "DIRECTORIES"
apt.conf.5:1273:.SH "EXAMPLES"
apt.conf.5:1277:.SH "FILES"
apt.conf.5:1295:.SH "BUGS"
apt.conf.5:1302:.SH "AUTHORS"
apt.conf.5:1316:.SH "NOTES"

-.-.

Remove excessive "\&" when it has no functional purpose.

1297:\m[blue]\fBAPT bug page\fR\m[]\&\s-2\u[1]\d\s+2\&. If you wish to report a bug in APT, please see
1312:\fBDaniel Burrows\fR <\&dburrows@debian\&.org\&>

-.-.

Change comment lines of type '.\" ====', '.\" ---', and an empty
'.\"' line) to a single period, as they contain no information and waste
work each time they are processed.

9:.\"
11:.\" -----------------------------------------------------------------
13:.\" -----------------------------------------------------------------
14:.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
17:.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
20:.\" -----------------------------------------------------------------
22:.\" -----------------------------------------------------------------
27:.\" -----------------------------------------------------------------
29:.\" -----------------------------------------------------------------

-.-.

Output from "test-nroff  -mandoc -t -K utf8 -rF0 -rHY=0 -rCHECKSTYLE=0 -ww -z ":

troff:<stdin>:223: warning [page 1, line 135]: cannot adjust (align) with both margins ; underset by 30n

-.-

Generally:

Split (sometimes) lines after a punctuation mark; before a conjunction.

-.-

Tables:

  Use the preprocessor 'tbl' to make tables.

  Put data, that are wider than the header in the (centered) last column,
in a "T{...\nT}" block(, when the table gets wider than the output line).

  Table headers, that are wider than any data in the corresponding column,
do not need to be centered, so left adjustment (l, L) is sufficient.

--- apt.conf.5	2026-04-10 01:31:00.484637264 +0000
+++ apt.conf.5.new	2026-04-10 02:45:40.162281911 +0000
@@ -6,31 +6,30 @@
 .\"    Manual: APT
 .\"    Source: APT 3.2.0
 .\"  Language: English
-.\"
-.TH "APT\&.CONF" "5" "05\ \&March\ \&2026" "APT 3.2.0" "APT"
-.\" -----------------------------------------------------------------
+.
+.TH APT.CONF 5 "05\ \&March\ \&2026" "APT 3.2.0" APT
+.
 .\" * Define some portability stuff
-.\" -----------------------------------------------------------------
-.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.
+.
 .\" http://bugs.debian.org/507673
 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
-.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.
 .ie \n(.g .ds Aq \(aq
 .el       .ds Aq '
-.\" -----------------------------------------------------------------
+.
 .\" * set default formatting
-.\" -----------------------------------------------------------------
+.
 .\" disable hyphenation
 .nh
 .\" disable justification (adjust text to left margin only)
 .ad l
-.\" -----------------------------------------------------------------
+.
 .\" * MAIN CONTENT STARTS HERE *
-.\" -----------------------------------------------------------------
-.SH "NAME"
+.
+.SH NAME
 apt.conf \- Configuration file for APT
-.SH "DESCRIPTION"
-.PP
+.SH DESCRIPTION
 /etc/apt/apt\&.conf
 is the main configuration file shared by all the tools in the APT suite of tools, though it is by no means the only place options can be set\&. The suite also shares a common command line parser to provide a uniform environment\&.
 .PP
@@ -97,8 +96,7 @@ all options set in the binary specific c
 .\}
 the command line options are applied to override the configuration directives or to load even more configuration files\&.
 .RE
-.SH "SYNTAX"
-.PP
+.SH SYNTAX
 The configuration file is organized in a tree with options organized into functional groups\&. Option specification is given with a double colon notation; for instance
 APT::Get::Assume\-Yes
 is an option within the APT tool group, for the Get tool\&. Options do not inherit from their parent groups\&.
@@ -182,7 +180,6 @@ implicitly)\&. Using both syntaxes toget
 \fIwrong\fR
 syntax in the hope of appending to a list will achieve the opposite, as only the last assignment for this option "::" will be used\&. Future versions of APT will raise errors and stop working if they encounter this misuse, so please correct such statements now while APT doesn\*(Aqt explicitly complain about them\&.
 .SH "THE APT GROUP"
-.PP
 This group of options controls general APT behavior as well as holding the options for all of the tools\&.
 .PP
 \fBArchitecture\fR
@@ -223,7 +220,7 @@ and similar commands\&. The following op
 \fBAPT::Color::Action::Downgrade\fR,
 \fBAPT::Color::Action::Remove\fR; corresponding to their lists in the
 \fBapt\fR(8)
-output\&.
+output.
 .sp
 Each color may reference one or more other color options by name, relative to
 \fBAPT::Color\fR\&. Their escape sequences will be combined\&.
@@ -410,7 +407,6 @@ Define the regular expression(s) for ver
 Keep a custom amount of kernels when autoremoving and defaults to 2, meaning two kernels are kept\&. Apt will always keep the running kernel and the latest one\&. If the latest kernel is the same as the running kernel, the second latest kernel is kept\&. Because of this, any value lower than 2 will be ignored\&. If you want only the latest kernel, you should set APT::Protect\-Kernels to false\&.
 .RE
 .SH "THE ACQUIRE GROUP"
-.PP
 The
 Acquire
 group of options controls the download of packages as well as the various "acquire methods" responsible for the download itself (see also
@@ -712,7 +708,7 @@ When downloading, force to use only the
 .PP
 \fBMaxReleaseFileSize\fR
 .RS 4
-The maximum file size of Release/Release\&.gpg/InRelease files\&. The default is 10MB\&.
+The maximum file size of Release/Release.gpg/InRelease files. The default is 10\~MB.
 .RE
 .PP
 \fBEnableSrvRecords\fR
@@ -766,7 +762,6 @@ Acquire::Snapshots::URI::Override::Origi
 @SNAPSHOTID@\&. The special value \*(Aqno\*(Aq is available for this option indicating that this source cannot be used to acquire snapshots from\&. Another source will be tried if available in this case\&.
 .RE
 .SH "BINARY SPECIFIC CONFIGURATION"
-.PP
 Especially with the introduction of the
 \fBapt\fR
 binary it can be useful to set certain options only for a specific binary as even options which look like they would effect only a certain binary like
@@ -777,7 +772,7 @@ as well as
 \fBapt\fR\&.
 .PP
 Setting an option for a specific binary only can be achieved by setting the option inside the
-\fBBinary::\fR\fB\fIspecific\-binary\fR\fR
+\fBBinary::\fIspecific\-binary\fR
 scope\&. Setting the option
 \fBAPT::Get::Show\-Versions\fR
 for the
@@ -787,8 +782,7 @@ only can e\&.g\&. by done by setting
 instead\&.
 .PP
 Note that as seen in the DESCRIPTION section further above you can\*(Aqt set binary\-specific options on the commandline itself nor in configuration files loaded via the commandline\&.
-.SH "DIRECTORIES"
-.PP
+.SH DIRECTORIES
 The
 Dir::State
 section has directories that pertain to local state information\&.
@@ -877,7 +871,6 @@ or
 \&.dpkg\-[a\-z]+
 is silently ignored\&. As seen in the last default value these patterns can use regular expression syntax\&.
 .SH "APT IN DSELECT"
-.PP
 When APT is used as a
 \fBdselect\fR(1)
 method several configuration directives control the default behavior\&. These are in the
@@ -926,7 +919,6 @@ If true the [U]pdate operation in
 will always prompt to continue\&. The default is to prompt only on error\&.
 .RE
 .SH "HOW APT CALLS DPKG(1)"
-.PP
 Several configuration directives control how APT invokes
 \fBdpkg\fR(1)\&. These are in the
 DPkg
@@ -1017,7 +1009,6 @@ to let
 handle all required configurations and triggers\&. This option is activated by default, but deactivating it could be useful if you want to run APT multiple times in a row \- e\&.g\&. in an installer\&. In this scenario you could deactivate this option in all but the last run\&.
 .RE
 .SH "SYSTEMD INHIBITORS"
-.PP
 APT will communicate with systemd to inhibit conflicting system operations while running
 \fBdpkg\fR(1), to avoid systems ending up with partial upgrades and broken packages\&.
 .PP
@@ -1035,7 +1026,6 @@ See
 \m[blue]\fB\%https://systemd.io/INHIBITOR_LOCKS/\fR\m[]
 for further information\&.
 .SH "PERIODIC AND ARCHIVES OPTIONS"
-.PP
 APT::Periodic
 and
 APT::Archives
@@ -1043,7 +1033,6 @@ groups of options configure behavior of
 /usr/lib/apt/apt\&.systemd\&.daily
 script\&. See the top of this script for the brief documentation of these options\&.
 .SH "DEBUG OPTIONS"
-.PP
 Enabling options in the
 Debug::
 section will cause debugging information to be sent to the standard error stream of the program utilizing the
@@ -1202,13 +1191,13 @@ MarkDelete
 or
 MarkInstall
 followed by
-package\-name <a\&.b\&.c \-> d\&.e\&.f | x\&.y\&.z> (section)
+package\-name <a.b.c \(-> d.e.f | x.y.z> (section)
 where
-a\&.b\&.c
+a.b.c
 is the current version of the package,
-d\&.e\&.f
+d.e.f
 is the version considered for installation and
-x\&.y\&.z
+x.y.z
 is a newer version, but not considered for installation (because of a low pin score)\&. The later two can be omitted if there is none or if it is the same as the installed version\&.
 section
 is the name of the section the package appears in\&.
@@ -1270,12 +1259,10 @@ DPkg::{Pre,Post}\-Invoke
 or
 APT::Update::{Pre,Post}\-Invoke\&.
 .RE
-.SH "EXAMPLES"
-.PP
+.SH EXAMPLES
 /usr/share/doc/apt/examples/configure\-index
 is a configuration file showing example values for all possible options\&.
-.SH "FILES"
-.PP
+.SH FILES
 /etc/apt/apt\&.conf
 .RS 4
 APT configuration file\&. Configuration Item:
@@ -1288,32 +1275,25 @@ APT configuration file fragments\&. Conf
 Dir::Etc::Parts\&.
 .RE
 .SH "SEE ALSO"
-.PP
 \fBapt-cache\fR(8),
 \fBapt-config\fR(8),
 \fBapt_preferences\fR(5)\&.
-.SH "BUGS"
-.PP
-\m[blue]\fBAPT bug page\fR\m[]\&\s-2\u[1]\d\s+2\&. If you wish to report a bug in APT, please see
-/usr/share/doc/debian/bug\-reporting\&.txt
+.SH BUGS
+\m[blue]\fBAPT bug page\fR\m[]\s-2\u[1]\d\s+2. If you wish to report a bug in APT, please see
+/usr/share/doc/debian/bug\-reporting.txt
 or the
 \fBreportbug\fR(1)
 command\&.
-.SH "AUTHORS"
-.PP
+.SH AUTHORS
 \fBJason Gunthorpe\fR
-.RS 4
-.RE
 .PP
 \fBAPT team\fR
-.RS 4
-.RE
 .PP
-\fBDaniel Burrows\fR <\&dburrows@debian\&.org\&>
+\fBDaniel Burrows\fR <[email protected]>
 .RS 4
-Initial documentation of Debug::*\&.
+Initial documentation of Debug::*.
 .RE
-.SH "NOTES"
+.SH NOTES
 .IP " 1." 4
 APT bug page
 .RS 4

  Any program (person), that produces man pages, should check the output
for defects by using (both groff and nroff)

[gn]roff -mandoc -t -ww -b -z -K utf8 <man page>

  To find trailing space use

grep -n -e ' $' -e ' \\f.$' -e ' \\"' <man page>

  The same goes for man pages that are used as an input.

-.-

  For a style guide use

  mandoc -T lint

-.-

  For general input conventions consult the man page "nroff(7)" (item
"Input conventions") or the Texinfo manual about the same item.

-.-

  Any "autogenerator" should check its products with the above mentioned
'groff', 'mandoc', and additionally with 'nroff ...'.

  It should also check its input files for too long (> 80) lines.

  This is just a simple quality control measure.

  The "autogenerator" may have to be corrected to get a better man page,
the source file may, and any additional file may.

-.-

  Common defects:

  Not removing trailing spaces (in in- and output).
  The reason for these trailing spaces should be found and eliminated.

  "git" has a "tool" to point out whitespace,
see for example "git-apply(1)" and git-config(1)")

-.-

  Not beginning each input sentence on a new line.

Line length and patch size should thus be reduced when that has been fixed.

  The script "reportbug" uses 'quoted-printable' encoding when a line is
longer than 1024 characters in an 'ascii' file.

  See man-pages(7), item "semantic newline".

-.-

The difference between the formatted output of the original
and patched file can be seen with:

  nroff -mandoc <file1> > <out1>
  nroff -mandoc <file2> > <out2>
  diff -d -u <out1> <out2>

and for groff, using

\"printf '%s\n%s\n' '.kern 0' '.ss 12 0' | groff -mandoc -Z - \"

instead of 'nroff -mandoc'

  Add the option '-t', if the file contains a table.

  Read the output from 'diff -d -u ...' with 'less -R' or similar.

-.-.

  If 'man' (man-db) is used to check the manual for warnings,
the following must be set:

  The option "-warnings=w"

  The environmental variable:

export MAN_KEEP_STDERR=yes (or any non-empty value)

  or

  (produce only warnings):

export MANROFFOPT="-ww -b -z"

export MAN_KEEP_STDERR=yes (or any non-empty value)

-.-


----- End forwarded message -----