Package: libdebuginfod-common
Version: 0.191-2
Severity: minor
Tags: patch
* What led up to the situation?
Checking for defects with
[test-]groff -mandoc -t -K utf8 -rF0 -rHY=0 -ww -b -z < "man page"
[test-groff is a script in the repository for "groff"] (local copy and
"troff" slightly changed by me).
* What was the outcome of this action?
troff: backtrace: file '<stdin>':3
troff:<stdin>:3: warning: register 'zZ' not defined
troff: backtrace: file '<stdin>':13
troff:<stdin>:13: warning: macro 'zZ' not defined
* 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: trixie/sid
APT prefers testing
APT policy: (500, 'testing')
Architecture: amd64 (x86_64)
Kernel: Linux 6.10.9-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 libdebuginfod-common depends on:
ii debconf [debconf-2.0] 1.5.87
ii ucf 3.0043+nmu1
libdebuginfod-common recommends no packages.
libdebuginfod-common suggests no packages.
-- debconf information excluded
Any program (person), that produces man pages, should check its content for
defects by using
groff -mandoc -t -ww -b -z [ -K utf8 | k ] <man page>
The same goes for man pages that are used as an input.
For a style guide use
mandoc -T lint
-.-
So any 'generator' should check its products with the above mentioned
'groff', 'mandoc', and additionally with 'nroff ...'.
This is just a simple quality control measure.
The 'generator' may have to be corrected to get a better man page,
the source file may, and any additional file may.
Common defects:
Input text line longer than 80 bytes.
Not removing trailing spaces (in in- and output).
The reason for these trailing spaces should be found and eliminated.
Not beginning each input sentence on a new line.
Lines should thus be shorter.
See man-pages(7), item 'semantic newline'.
-.-
The difference between the formatted outputs can be seen with:
nroff -mandoc <file1> > <out1>
nroff -mandoc <file2> > <out2>
diff -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 of \'diff -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)
-.-.
Output from "mandoc -T lint debuginfod-client-config.7": (possibly shortened
list)
mandoc: debuginfod-client-config.7:5:2: WARNING: missing date, using "": TH
mandoc: debuginfod-client-config.7:7:97: STYLE: input text line longer than 80
bytes: debuginfod-client-co...
mandoc: debuginfod-client-config.7:10:104: STYLE: input text line longer than
80 bytes: Several environment ...
mandoc: debuginfod-client-config.7:13:2: ERROR: skipping unknown macro: .zZ
-.-.
Change (or include a "FIXME" paragraph about) misused SI (metric)
numeric prefixes (or names) to the binary ones, like Ki (kibi), Mi
(mebi), Gi (gibi), or Ti (tebi), if indicated.
If the metric prefixes are correct, add the definitions or an
explanation to avoid misunderstanding.
60:provide at least 100K of data within this many seconds is skipped. The
-.-.
Wrong distance 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.
52:This environment variable governs the default limit of retry attempts. If a
60:provide at least 100K of data within this many seconds is skipped. The
66:\fIcomplete\fP the download a file found on a server in seconds. It is best
67:used to ensure that a file is downloaded quickly or be rejected. The
73:download in bytes. This is best used if the user would like to ensure
74:only small files are downloaded. A value of 0 causes no consideration
81:outbound HTTP requests, one per line. The header lines shouldn't end with
82:CRLF, unless that's the system newline convention. Whitespace-only lines
-.-.
Split lines longer than 80 characters into two or more lines.
Appropriate break points are the end of a sentence and a subordinate
clause; after punctuation marks.
Line 7, length 97
debuginfod-client-config \- debuginfod client environment variables, cache
control files and etc.
Line 10, length 104
Several environment variables and control files control the behaviour of
debuginfod client applications.
-.-
Output from "test-groff -b -mandoc -rF0 -rHY=0 -K utf8 -t -ww -z ":
troff: backtrace: file '<stdin>':3
troff:<stdin>:3: warning: register 'zZ' not defined
troff: backtrace: file '<stdin>':13
troff:<stdin>:13: warning: macro 'zZ' not defined
--- debuginfod-client-config.7 2024-09-23 21:26:02.689262072 +0000
+++ debuginfod-client-config.7.new 2024-09-23 21:55:02.958339988 +0000
@@ -1,19 +1,24 @@
'\"! tbl | nroff \-man
'\" t macro stdmacro
+.\" Define macro zZ and register zZ if not defined
+.de zZ
+..
+.nr zZ +0
.if \n(zZ=1 .ig zZ
-
+.
.TH DEBUGINFOD-CLIENT-CONFIG 7
.SH NAME
-debuginfod-client-config \- debuginfod client environment variables, cache
control files and etc.
+debuginfod-client-config \- debuginfod client environment variables, cache \
+control files and etc.
.SH SYNOPSIS
-Several environment variables and control files control the behaviour of
debuginfod client applications.
+Several environment variables and control files control the behaviour of
+debuginfod client applications.
.\" The preceding section permits this man page to be viewed as if
self-contained.
.zZ
.\" The following section (only) gets included into other man pages via .so
-
.SH ENVIRONMENT VARIABLES
.TP
.B $TMPDIR
@@ -49,38 +54,43 @@ then the verbose output will be produced
.TP
.B $DEBUGINFOD_RETRY_LIMIT
-This environment variable governs the default limit of retry attempts. If a
-query failed with errno other than ENOENT, will initiate several attempts
-within the limit.
+This environment variable governs the default limit of retry attempts.
+If a query failed with errno other than ENOENT,
+will initiate several attempts within the limit.
.TP
.B $DEBUGINFOD_TIMEOUT
This environment variable governs the download \fIcommencing\fP
-timeout for each debuginfod HTTP connection. A server that fails to
-provide at least 100K of data within this many seconds is skipped. The
-default is 90 seconds. (Zero or negative means "no timeout".)
+timeout for each debuginfod HTTP connection.
+A server that fails to provide at least 100\~KB of data within this many
+seconds is skipped.
+The default is 90 seconds.
+(Zero or negative means "no timeout".)
.TP
.B $DEBUGINFOD_MAXTIME
This environment variable dictates how long the client will wait to
-\fIcomplete\fP the download a file found on a server in seconds. It is best
-used to ensure that a file is downloaded quickly or be rejected. The
-default is 0 (infinite time).
+\fIcomplete\fP the download a file found on a server in seconds.
+It is best used to ensure that a file is downloaded quickly or be rejected.
+The default is 0 (infinite time).
.TP
.B $DEBUGINFOD_MAXSIZE
This environment variable dictates the maximum size of a file to
-download in bytes. This is best used if the user would like to ensure
-only small files are downloaded. A value of 0 causes no consideration
-for size, and the client may attempt to download a file of any size.
+download in bytes.
+This is best used
+if the user would like to ensure only small files are downloaded.
+A value of 0 causes no consideration for size,
+and the client may attempt to download a file of any size.
The default is 0 (infinite size).
.TP
.B $DEBUGINFOD_HEADERS_FILE
This environment variable points to a file that supplies headers to
-outbound HTTP requests, one per line. The header lines shouldn't end with
-CRLF, unless that's the system newline convention. Whitespace-only lines
-are skipped.
+outbound HTTP requests, one per line.
+The header lines shouldn't end with CRLF,
+unless that's the system newline convention.
+Whitespace-only lines are skipped.
.SH CACHE
