Package: ifupdown-extra
Version: 0.34
Severity: minor
Tags: patch
* 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=10 -ww -z < "man
page"
[Use "groff -e ' $' <file>" to find 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?
an.tmac:<stdin>:10: misuse, warning: .RI is for at least 2 arguments, got 1
Use macro '.I' for one argument or split argument."
troff:<stdin>:21: warning: trailing space in the line
an.tmac:<stdin>:22: style: 1 leading space(s) on input line
troff:<stdin>:24: warning: trailing space in the line
an.tmac:<stdin>:25: style: 2 leading space(s) on input line
an.tmac:<stdin>:26: style: 2 leading space(s) on input line
troff:<stdin>:41: warning: trailing space in the line
troff:<stdin>:61: warning: trailing space in the line
troff:<stdin>:77: warning: trailing space in the line
troff:<stdin>:89: warning: trailing space in the line
troff:<stdin>:148: warning: trailing space in the line
* 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.12.6-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 ifupdown-extra depends on:
ii bind9-host [host] 1:9.20.4-3
ii curl 8.11.1-1
ii dpkg 1.22.11
ii iproute2 6.12.0-1
ii iputils-arping 3:20240905-1
ii iputils-ping [ping] 3:20240905-1
ii net-tools 2.10-1.1
ii netcat-openbsd 1.226-1.1
Versions of packages ifupdown-extra recommends:
pn ethtool <none>
pn ndisc6 <none>
ifupdown-extra suggests no packages.
-- no debconf information
Input file is network-test.1
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>
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 output of the original and patched file
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 network-test.1": (shortened list)
3 input text line longer than 80 bytes
17 whitespace at end of input line
-.-.
Output from "test-groff -mandoc -t -ww -z network-test.1": (shortened list)
1 .RI is for at least 2 arguments, got 1
1 Use macro '.I' for one argument or split argument."
7 trailing space in the line
-.-.
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
17
-.-.
Change '-' (\-) to '\(en' (en-dash) for a numeric range.
GNU gnulib has recently (2023-06-18) updated its
"build_aux/update-copyright" to recognize "\(en" in man pages.
network-test.1:177:Copyright (C) 2005-2020 Javier Fernandez-Sanguino
<j...@debian.org>.
-.-.
Use the correct macro for the font change of a single argument or
split the argument into two.
10:.RI -s
-.-.
Change a HYPHEN-MINUS (code 0x2D) to a minus(-dash) (\-),
if it
is in front of a name for an option,
is a symbol for standard input,
is a single character used to indicate an option,
or is in the NAME section (man-pages(7)).
N.B. - (0x2D), processed as a UTF-8 file, is changed to a hyphen
(0x2010, groff \[u2010] or \[hy]) in the output.
10:.RI -s
11:.RI [-v verbose level]
67:messages), 2 (Show error and warning messages), 3 (default level - show
69:from external APIs -IP address and GeoIP).
-.-.
Add a comma (or \&) after "e.g." and "i.e.", or use English words
(man-pages(7)).
Abbreviation points should be protected against being interpreted as
an end of sentence, if they are not, and that independent of the
current place on the line.
44:not the same as running as system administrator (i.e. root). If 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.
-.-
Mark a abbreviation point as such by suffixing them with "\&".
44:not the same as running as system administrator (i.e. root). If the
53:routes). It also uses \fBping\fR, \fBhost\fR, \fBcurl\fR, and \fBnc\fR
(netcat)
60:The log messages are sent also to the \fBlocal3\fR syslog facility. This is
66:the script should use. Valid values are: 0 (silent run), 1 (show only error
71:As the privacy policies of different external services vary. These services
are
79:and its associated web server. If you want to use a different check host you
100:that will be used for testing. By default it will use TCP port 80..
104:A web service to test network connectivity by downloading some content. By
default
113:A web service used to determine the system's public IPv4 address. By default
118:A web service used to determine the system's public IPv6 address. By default
133:errors by itself. It is also unable to detect if the network is failing due
to
147:connect through the Internet using a proxy gateway for services. The program
153:\fBping\fR. These tests might fail in hosts installed in networking
-.-.
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 35, length 85
including the actual Internet IPv4 address, IPv6 address as well as GeoIP
information
Line 104, length 82
A web service to test network connectivity by downloading some content. By
default
Line 123, length 96
A web service used to determine the system's Geographical information based on
public databases.
-.-.
Use \(en (en-dash) for a dash at the beginning of a line,
or between space characters,
not a minus (\-) or a hyphen (-), except in the NAME section.
network-test.1:67:messages), 2 (Show error and warning messages), 3 (default
level - show
-.-.
The section part for a manual page is set in roman font.
136:.B dmesg (1)
158:.B ip (8),
159:.B ncmli (1),
160:.B netstat (8),
161:.B ifconfig (8),
162:.B ethtool (8),
164:.B ping (8),
165:.B nc (1),
166:.B curl (1), and
167:.B host (1).
-.-.
Put a parenthetical sentence, phrase on a separate line,
if not part of a code.
See man-pages(7), item "semantic newline".
Not considered in a patch, too many lines.
network-test.1:50:\fBarp\fR, \fBnmcli\fR, and (when running as root and using
Ethernet interfaces)
network-test.1:61:useful if the script is run periodically (from \fBcron\fR)
and the system
network-test.1:67:messages), 2 (Show error and warning messages), 3 (default
level - show
network-test.1:68:informational messages), 4 (show detailed information) and 5
(Show information
network-test.1:181:the Free Software Foundation; either version 2, or (at your
option)
-.-.
Output from "test-groff -mandoc -t -K utf8 -rF0 -rHY=0 -rCHECKSTYLE=10 -ww -z
":
an.tmac:<stdin>:10: misuse, warning: .RI is for at least 2 arguments, got 1
Use macro '.I' for one argument or split argument."
troff:<stdin>:21: warning: trailing space in the line
an.tmac:<stdin>:22: style: 1 leading space(s) on input line
troff:<stdin>:24: warning: trailing space in the line
an.tmac:<stdin>:25: style: 2 leading space(s) on input line
an.tmac:<stdin>:26: style: 2 leading space(s) on input line
troff:<stdin>:41: warning: trailing space in the line
troff:<stdin>:61: warning: trailing space in the line
troff:<stdin>:77: warning: trailing space in the line
troff:<stdin>:89: warning: trailing space in the line
troff:<stdin>:148: warning: trailing space in the line
-.-
Additionally (general):
Abbreviations get a '\&' added after their final full stop (.) to mark them
as such and not as an end of a sentence.
--- network-test.1 2024-12-27 01:55:10.743039979 +0000
+++ network-test.1.new 2024-12-27 02:41:15.202568043 +0000
@@ -7,8 +7,8 @@
network-test \- check the network and test if everything is fine
.SH SYNOPSIS
.B network-test
-.RI -s
-.RI [-v verbose level]
+.B \-s
+.RB [ \-v "\fIverbose level\fR]"
.SH DESCRIPTION
The
@@ -18,10 +18,10 @@ tests and providing both information (\f
and possible errors (\fBERR\fP) based on the results of these tests.
It will check and report on:
.RS
-* Status of the network interfaces of the system including: link status,
+* Status of the network interfaces of the system including: link status,
IP addressing and number of transmitted packets and error rates.
-* Accessibility to configured routes to external networks,
+* Accessibility to configured routes to external networks,
including the default network route, checking the routers configured
to give access to the network
@@ -32,95 +32,112 @@ ICMP and simulating a web connections to
used for the tests can be configured through the environment, see below)
* Extra information of network connectivity using calls to external API
services
-including the actual Internet IPv4 address, IPv6 address as well as GeoIP
information
+including the actual Internet IPv4 address,
+IPv6 address as well as GeoIP information
(only if enabled by the user in the highest verbose level)
.RE
-.P
+.P
The program does not need special privileges to run as it does not
-do any system change.
+do any system change.
However, the behaviour of the program when running as an unprivileged user is
-not the same as running as system administrator (i.e. root). If the
-program is run as system administrator it will try to run some tools
-that are only available to it to speed up some of the tests.
+not the same as running as system administrator
+(i.e.\& root).
+If the program is run as system administrator
+it will try to run some tools,
+that are only available to it,
+to speed up some of the tests.
.P
The program relies on the use of \fBip\fR, \fBnetstat\fR, \fBifconfig\fR,
-\fBarp\fR, \fBnmcli\fR, and (when running as root and using Ethernet
interfaces)
+\fBarp\fR, \fBnmcli\fR, and
+(when running as root and using Ethernet interfaces)
\fBethtool\fR or \fBmii-tool\fR, to obtain information about the system's
networking configuration (status of available interfaces and configured network
-routes). It also uses \fBping\fR, \fBhost\fR, \fBcurl\fR, and \fBnc\fR (netcat)
-to do tests of the network connectivity and ensure that the host can connect to
-the Internet.
+routes).
+It also uses \fBping\fR, \fBhost\fR, \fBcurl\fR, and \fBnc\fR (netcat)
+to do tests of the network connectivity
+and ensure that the host can connect to the Internet.
.SH OPTIONS
.TP
.B \-s
-The log messages are sent also to the \fBlocal3\fR syslog facility. This is
-useful if the script is run periodically (from \fBcron\fR) and the system
-administrator wants to preserve the output in syslog
+The log messages are sent also to the \fBlocal3\fR syslog facility.
+This is useful
+if the script is run periodically
+(from \fBcron\fR)
+and the system administrator wants to preserve the output in syslog.
.TP
-.B \-v verbosity
+.BI \-v " verbosity"
Verbosity level is a value that defines the level of output information that
-the script should use. Valid values are: 0 (silent run), 1 (show only error
-messages), 2 (Show error and warning messages), 3 (default level - show
-informational messages), 4 (show detailed information) and 5 (Show information
-from external APIs -IP address and GeoIP).
-
-As the privacy policies of different external services vary. These services are
-only queried if the user selects the highest verbosity level (5).
+the script should use.
+Valid values are:
+0 (silent run),
+1 (show only error messages),
+2 (Show error and warning messages),
+3 (default level \(en show informational messages),
+4 (show detailed information)
+and
+5 (Show information from external APIs -IP address and GeoIP).
+
+As the privacy policies of different external services vary.
+These services are only queried
+if the user selects the highest verbosity level (5).
.SH ENVIRONMENT
-The program will, by default, check
+The program will, by default, check
.B www.debian.org
-and its associated web server. If you want to use a different check host you
-can setup the environment as follows:
+and its associated web server.
+If you want to use a different check host
+you can setup the environment as follows:
.br
-.TP
+.TP
.B CHECK_HOST
The name of a host to use when testing DNS resolution.
By default 'www.debian.org'
-.TP
+.TP
.B CHECK_IP_ADRESS
-The
+The
.B CHECK_HOST
\'s IP address. By default defined with the following value: 194.109.137.218
-.TP
+.TP
.B CHECK_WEB_HOST
The web server to use for testing purposes when testing network connectivity.
By default it will use 'www.debian.org'
-.TP
+.TP
.B CHECK_WEB_PORT
The web server port of server
.B CHECK_WEB_HOST
-that will be used for testing. By default it will use TCP port 80..
+that will be used for testing.
+By default it will use TCP port 80.
.TP
.B CHECK_WEB_URL
-A web service to test network connectivity by downloading some content. By
default
-it will use 'http://network-test.debian.org/moo'
+A web service to test network connectivity by downloading some content.
+By default it will use 'http://network-test.debian.org/moo'
-.TP
+.TP
.B CHECK_WEB_MD5
The MD5sum value of the content being checked.
-.TP
+.TP
.B CHECK_IP_URL
-A web service used to determine the system's public IPv4 address. By default
-it will use 'https://api.ipify.org'
+A web service used to determine the system's public IPv4 address.
+By default it will use 'https://api.ipify.org'
-.TP
+.TP
.B CHECK_IP6_URL
-A web service used to determine the system's public IPv6 address. By default
-it will use 'https://api6.ipify.org'
+A web service used to determine the system's public IPv6 address.
+By default it will use 'https://api6.ipify.org'
-.TP
+.TP
.B CHECK_GEOIP_URL
-A web service used to determine the system's Geographical information based on
public databases.
+A web service used to determine the system's Geographical information
+based on public databases.
By default it will use 'http://api.geoiplookup.net/'
@@ -130,12 +147,13 @@ The program will exit with error (1) if
.SH BUGS
This program does not have \fIsuper cow powers\fP so it is unable to fix the
-errors by itself. It is also unable to detect if the network is failing due to
-a local firewall policy been in place so make sure you check your system logs
-with
-.B dmesg (1)
-to detect if some of the active tests are being dropped due to your local
-firewall.
+errors by itself.
+It is also unable to detect
+if the network is failing due to a local firewall policy been in place
+so make sure you check your system logs with
+.BR dmesg (1)
+to detect
+if some of the active tests are being dropped due to your local firewall.
Other known issues that might make the program not work reliable are:
@@ -144,27 +162,31 @@ Other known issues that might make the p
tests might be biased towards IPv4 and might fail in IPv6 environments.
* Proxies: The program does not check network connectivity for hosts that
-connect through the Internet using a proxy gateway for services. The program
-might report issues in hosts using proxies even when these might
-connect to the Internet properly through proxied services.
+connect through the Internet using a proxy gateway for services.
+The program might report issues in hosts using proxies
+even when these might connect to the Internet properly through proxied
+services.
* Firewall environments: some of the tests rely on direct connectivity
to external hosts, which are tested using ICMP queries (through the use of
-\fBping\fR. These tests might fail in hosts installed in networking
-environments with firewalls that block outbound ICMP communication.
+\fBping\fR.
+These tests might fail in hosts installed in networking
+environments with firewalls
+that block outbound ICMP communication.
.RE
.SH SEE ALSO
-.B ip (8),
-.B ncmli (1),
-.B netstat (8),
-.B ifconfig (8),
-.B ethtool (8),
-.B mii-tool (8),
-.B ping (8),
-.B nc (1),
-.B curl (1), and
-.B host (1).
+.BR ip (8),
+.BR ncmli (1),
+.BR netstat (8),
+.BR ifconfig (8),
+.BR ethtool (8),
+.BR mii-tool (8),
+.BR ping (8),
+.BR nc (1),
+.BR curl (1),
+and
+.BR host (1).
.SH AUTHOR
@@ -174,13 +196,14 @@ GNU/Linux distribution.
.SH COPYRIGHT AND LICENCE
-Copyright (C) 2005-2020 Javier Fernandez-Sanguino <j...@debian.org>.
+Copyright (C) 2005\(en2020 Javier Fernandez-Sanguino <j...@debian.org>.
-This program is free software; you can redistribute it and/or modify
-it under the terms of the GNU General Public License as published by
-the Free Software Foundation; either version 2, or (at your option)
-any later version.
+This program is free software;
+you can redistribute it
+and/or modify it under the terms of the GNU General Public License as
+published by the Free Software Foundation;
+either version 2,
+or (at your option) any later version.
On Debian systems, a copy of the GNU General Public License may be
found in /usr/share/common-licenses/GPL.
-
