Package: ifupdown
Version: 0.8.44
Severity: minor
Tags: patch
* What led up to the situation?
Checking for defects with
test-[g|n]roff -mandoc -t -K utf8 -rF0 -rHY=0 -ww -b -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?
troff: backtrace: '/home/bg/git/groff/build/s-tmac/an.tmac':679: macro 'IR'
troff: backtrace: file '<stdin>':60
troff:<stdin>:60: warning: trailing space in the line
troff: backtrace: file '<stdin>':91
troff:<stdin>:91: warning: trailing space in the line
troff: backtrace: file '<stdin>':95
troff:<stdin>:95: warning: trailing space in the line
troff: backtrace: file '<stdin>':156
troff:<stdin>:156: warning: trailing space in the line
troff: backtrace: file '<stdin>':275
troff:<stdin>:275: 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.11.5-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 depends on:
ii adduser 3.137
ii iproute2 6.11.0-1
ii libc6 2.40-3
Versions of packages ifupdown recommends:
ii dhcpcd-base [dhcp-client] 1:10.1.0-1
ii isc-dhcp-client [dhcp-client] 4.4.3-P1-5
Versions of packages ifupdown suggests:
pn ppp <none>
pn rdnssd <none>
-- Configuration Files:
/etc/init.d/networking changed [not included]
-- no debconf information
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 ifup.8": (possibly shortened list)
mandoc: ifup.8:9:9: STYLE: whitespace at end of input line
mandoc: ifup.8:18:9: STYLE: whitespace at end of input line
mandoc: ifup.8:21:9: STYLE: whitespace at end of input line
mandoc: ifup.8:91:8: STYLE: whitespace at end of input line
mandoc: ifup.8:95:32: STYLE: whitespace at end of input line
mandoc: ifup.8:107:82: STYLE: input text line longer than 80 bytes: Exclude
interfaces f...
mandoc: ifup.8:128:86: STYLE: input text line longer than 80 bytes: Disable
special hand...
mandoc: ifup.8:129:85: STYLE: input text line longer than 80 bytes: (\fIlo\fR
on Linux) ...
mandoc: ifup.8:130:85: STYLE: input text line longer than 80 bytes: on \fBifup
-a\fR aut...
mandoc: ifup.8:131:84: STYLE: input text line longer than 80 bytes: the
interface is con...
mandoc: ifup.8:132:83: STYLE: input text line longer than 80 bytes: defined as
loopback,...
mandoc: ifup.8:146:82: STYLE: input text line longer than 80 bytes: For
\fBifquery\fR, d...
mandoc: ifup.8:147:85: STYLE: input text line longer than 80 bytes: lists all
interfaces...
mandoc: ifup.8:148:81: STYLE: input text line longer than 80 bytes: exits with
a status ...
mandoc: ifup.8:149:88: STYLE: input text line longer than 80 bytes: display
state of the...
mandoc: ifup.8:156:3: STYLE: whitespace at end of input line
mandoc: ifup.8:218:124: STYLE: input text line longer than 80 bytes: Ifupdown
uses per-in...
mandoc: ifup.8:225:120: STYLE: input text line longer than 80 bytes: the exit
status will...
mandoc: ifup.8:228:92: STYLE: input text line longer than 80 bytes: on an
interface that...
mandoc: ifup.8:233:119: STYLE: input text line longer than 80 bytes: will
normally return...
mandoc: ifup.8:235:84: STYLE: input text line longer than 80 bytes: will also
return wit...
mandoc: ifup.8:275:56: STYLE: whitespace at end of input line
-.-.
Remove space characters at the end of lines.
Use "git apply ... --whitespace=fix" to fix extra space issues, or use
global configuration "core.whitespace".
9:.B ifup
18:.B ifup
21:.B ifup
91:line in
95:Read interface definitions from
156:in
275:that appear as a result of hardware being installed and
-.-.
Change two HYPHEN-MINUSES (code 0x2D) to an em-dash (\(em),
if one is intended.
" \(em " creates a too big gap in the text (in "troff").
An en-dash is usually surrounded by a space,
while an em-dash is used without spaces.
"man" (1 byte characters in input) transforms an en-dash (\(en) to one
HYPHEN-MINUS,
and an em-dash to two HYPHEN-MINUSES without considering the space
around it.
If "--" are two single "-" (end of options) then use "\-\-".
ifup.8:175:.B ifquery -l --allow=hotplug
ifup.8:234:.B ifquery --state
-.-.
Change -- in x--y to \(em (em-dash), or, if an
option, to \-\-
175:.B ifquery -l --allow=hotplug
234:.B ifquery --state
-.-.
Use the correct macro for the font change of a single argument or
split the argument into two.
145:.BR \-\-state
186:.BR ifquery
191:.BR ip
203:.BR ifdown
-.-.
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.
70:Combined with \fB-\-allow\fP, acts on all interfaces of a specified class
130:on \fBifup -a\fR automatically. In the case the loopback device is
redefined by user,
153:.B ifup -a
169:.B ifdown -a
172:.B ifquery -l
175:.B ifquery -l --allow=hotplug
234:.B ifquery --state
-.-.
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.
74:currently listed in the state file. Only interfaces defined
108:\fIPATTERN\fR uses a usual shell glob syntax. If shell wildcards are not
used, it
109:must match the exact interface name. This option may be specified multiple
times
128:Disable special handling of the loopback interface. By default, the
loopback interface
130:on \fBifup -a\fR automatically. In the case the loopback device is
redefined by user,
131:the interface is configured just once anyway. If, however, another
interface is also
132:defined as loopback, it's configured as usual. Specifying this option
disables this
146:For \fBifquery\fR, dump the state of the interfaces. When no interfaces
specified,
148:exits with a status code indicating success. If one or more interfaces
specified,
150:given as arguments are up. Otherwise, 0 is returned.
180:configuration. Each key-value pair is printed out on individual
198:is still running. In that case,
-.-.
Test nr. 30:
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.
N.B.
The number of lines affected can be too large to be in a patch.
Line 107, length 82
Exclude interfaces from the list of interfaces to operate on by the
\fIPATTERN\fR.
Line 108, length 81
\fIPATTERN\fR uses a usual shell glob syntax. If shell wildcards are not used,
it
Line 128, length 86
Disable special handling of the loopback interface. By default, the loopback
interface
Line 129, length 85
(\fIlo\fR on Linux) is predefined internally as an auto interface, so it's
brought up
Line 130, length 85
on \fBifup -a\fR automatically. In the case the loopback device is redefined by
user,
Line 131, length 84
the interface is configured just once anyway. If, however, another interface is
also
Line 132, length 83
defined as loopback, it's configured as usual. Specifying this option disables
this
Line 146, length 82
For \fBifquery\fR, dump the state of the interfaces. When no interfaces
specified,
Line 147, length 85
lists all interfaces brought up together with logical interfaces assigned to
them and
Line 148, length 81
exits with a status code indicating success. If one or more interfaces
specified,
Line 149, length 88
display state of these interfaces only; successful code is returned if all of
interfaces
Line 218, length 124
Ifupdown uses per-interface locking to ensure that concurrent ifup and ifdown
calls to the same interface are run in serial.
Line 225, length 120
the exit status will be 0 if the given interface(s) have all been
(de)configured successfully, 1 if there was any error.
Line 228, length 92
on an interface that is already up will result in an exit status of 0, and
similarly running
Line 233, length 119
will normally return with exit status 0 if an interface with a matching iface
stanza, 1 if there is no matching stanza.
Line 235, length 84
will also return with exit status 1 if the given interface was known but was
not up.
-.-.
Split a punctuation from a single argument, if a two-font macro is meant
224:.B ifdown\fR,
-.-.
Test nr. 64:
Put a parenthetical sentence, phrase on a separate line,
if not part of a code.
See man-pages(7), item "semantic newline".
ifup.8:58:commands may be used to configure (or, respectively, deconfigure)
network
-.-.
No space is needed before a quote (") at the end of a line
60:.IR /etc/network/interfaces ". "
-.-.
Output from "test-groff -mandoc -t -K utf8 -rF0 -rHY=0 -ww -b -z ":
troff: backtrace: '/home/bg/git/groff/build/s-tmac/an.tmac':679: macro 'IR'
troff: backtrace: file '<stdin>':60
troff:<stdin>:60: warning: trailing space in the line
troff: backtrace: file '<stdin>':91
troff:<stdin>:91: warning: trailing space in the line
troff: backtrace: file '<stdin>':95
troff:<stdin>:95: warning: trailing space in the line
troff: backtrace: file '<stdin>':156
troff:<stdin>:156: warning: trailing space in the line
troff: backtrace: file '<stdin>':275
troff:<stdin>:275: warning: trailing space in the line
-.-.
--- ifup.8 2024-11-11 09:05:39.532775523 +0000
+++ ifup.8.new 2024-11-11 09:28:56.454198314 +0000
@@ -6,7 +6,7 @@ ifdown \- take a network interface down
.PP
ifquery \- parse interface configuration
.SH SYNOPSIS
-.B ifup
+.B ifup
[\fB\-nv\fR]
[\fB\-\-no\-act\fR]
[\fB\-\-verbose\fR]
@@ -15,10 +15,10 @@ ifquery \- parse interface configuration
[\fB\-\-allow\fR \fICLASS\fR]
\fB\-a\fR|\fIIFACE\fR...
.br
-.B ifup
+.B ifup
\fB\-h\fR|\fB\-\-help\fR
.br
-.B ifup
+.B ifup
\fB\-V\fR|\fB\-\-version\fR
.PP
.B ifdown
@@ -57,7 +57,7 @@ The
.BR ifup " and " ifdown
commands may be used to configure (or, respectively, deconfigure) network
interfaces based on interface definitions in the file
-.IR /etc/network/interfaces ". "
+.IR /etc/network/interfaces .
.BR ifquery " command may be used to parse interfaces configuration."
.SH OPTIONS
A summary of options is included below.
@@ -67,7 +67,7 @@ If given to \fBifup\fP, affect all inter
Interfaces are brought up in the order in which they are defined
in
.IR /etc/network/interfaces .
-Combined with \fB-\-allow\fP, acts on all interfaces of a specified class
+Combined with \fB\-\-allow\fP, acts on all interfaces of a specified class
instead.
If given to \fBifdown\fP, affect all defined interfaces.
Interfaces are brought down in the order in which they are
@@ -88,11 +88,11 @@ Show summary of options.
\fB\-\-allow=\fR\fICLASS\fR
Only allow interfaces listed in an
.I allow\-CLASS
-line in
+line in
.IR /etc/network/interfaces " to be acted upon."
.TP
\fB\-i\fR \fIFILE\fR, \fB\-\-interfaces=\fR\fIFILE\fR
-Read interface definitions from
+Read interface definitions from
.I FILE
instead of from
.IR /etc/network/interfaces "."
@@ -104,9 +104,12 @@ instead of in
.IR /run/network "."
.TP
.BI \-X " PATTERN\fR, " "\-\-exclude=" PATTERN
-Exclude interfaces from the list of interfaces to operate on by the
\fIPATTERN\fR.
-\fIPATTERN\fR uses a usual shell glob syntax. If shell wildcards are not used,
it
-must match the exact interface name. This option may be specified multiple
times
+Exclude interfaces from the list of interfaces to operate on by the
+\fIPATTERN\fR.
+\fIPATTERN\fR uses a usual shell glob syntax.
+If shell wildcards are not used,
+it must match the exact interface name.
+This option may be specified multiple times
resulting in more than one pattern being excluded.
.TP
.BI \-o " OPTION" "\fB=" VALUE
@@ -125,12 +128,17 @@ for more information about the mapping f
Don't run any scripts under /etc/network/if-*.d/
.TP
.B \-\-no\-loopback
-Disable special handling of the loopback interface. By default, the loopback
interface
-(\fIlo\fR on Linux) is predefined internally as an auto interface, so it's
brought up
-on \fBifup -a\fR automatically. In the case the loopback device is redefined
by user,
-the interface is configured just once anyway. If, however, another interface
is also
-defined as loopback, it's configured as usual. Specifying this option disables
this
-behaviour, so the loopback interface won't be configured automatically.
+Disable special handling of the loopback interface.
+By default, the loopback interface
+(\fIlo\fR on Linux)
+is predefined internally as an auto interface,
+so it's brought up on \fBifup \-a\fR automatically.
+In the case the loopback device is redefined by user,
+the interface is configured just once anyway.
+If, however, another interface is also defined as loopback,
+it's configured as usual.
+Specifying this option disables this behaviour,
+so the loopback interface won't be configured automatically.
.TP
.BR \-V ", " \-\-version
Show copyright and version information.
@@ -142,18 +150,22 @@ Show commands as they are executed.
For \fBifquery\fR, list all the interfaces which match the specified class.
If no class specified, prints all the interfaces listed as \fBauto\fR.
.TP
-.BR \-\-state
-For \fBifquery\fR, dump the state of the interfaces. When no interfaces
specified,
-lists all interfaces brought up together with logical interfaces assigned to
them and
-exits with a status code indicating success. If one or more interfaces
specified,
-display state of these interfaces only; successful code is returned if all of
interfaces
-given as arguments are up. Otherwise, 0 is returned.
+.B \-\-state
+For \fBifquery\fR,
+dump the state of the interfaces.
+When no interfaces specified,
+lists all interfaces brought up together with logical interfaces assigned to
+them and exits with a status code indicating success.
+If one or more interfaces specified,
+display state of these interfaces only;
+successful code is returned if all of interfaces given as arguments are up.
+Otherwise, 0 is returned.
.SH EXAMPLES
.TP
-.B ifup -a
+.B ifup \-a
Bring up all the interfaces defined with
.I auto
-in
+in
.I /etc/network/interfaces
.TP
.B ifup eth0
@@ -166,13 +178,13 @@ Bring up interface
as logical interface
.B home
.TP
-.B ifdown -a
+.B ifdown \-a
Bring down all interfaces that are currently up.
.TP
-.B ifquery -l
+.B ifquery \-l
Print names of all interfaces specified with the \fBauto\fR keyword.
.TP
-.B ifquery -l --allow=hotplug
+.B ifquery \-l \-\-allow=hotplug
Print names of all interfaces specified with the \fBallow-hotplug\fR keyword.
.TP
.B ifquery eth0
@@ -183,12 +195,12 @@ line using "\fB: \fR" as separator.
.BR ifup ,
.BR ifdown ,
and
-.BR ifquery
+.B ifquery
are actually the same program called by different names.
.P
The program does not configure network interfaces directly;
it runs low level utilities such as
-.BR ip
+.B ip
to do its dirty work.
.P
When invoked,
@@ -200,7 +212,7 @@ is still running. In that case,
is sent to ifup.
.P
During interface deconfiguration,
-.BR ifdown
+.B ifdown
ignores errors the same way as if
.B \-\-ignore\-errors
was specified.
@@ -215,24 +227,32 @@ for more information.
.I /run/network/ifstate
current state of network interfaces
.SH CONCURRENCY
-Ifupdown uses per-interface locking to ensure that concurrent ifup and ifdown
calls to the same interface are run in serial.
+Ifupdown uses per-interface locking to ensure that concurrent ifup and
+ifdown calls to the same interface are run in serial.
However, calls to different interfaces will be able to run in parallel.
.SH EXIT STATUS
For
.B ifup
and
-.B ifdown\fR,
-the exit status will be 0 if the given interface(s) have all been
(de)configured successfully, 1 if there was any error.
-The result of these commands is idempotent; running
+.BR ifdown ,
+the exit status will be 0 if
+the given interface(s) have all been (de)configured successfully,
+1 if there was any error.
+The result of these commands is idempotent;
+running
.B ifup
-on an interface that is already up will result in an exit status of 0, and
similarly running
+on an interface that is already up will result in an exit status of 0, and
+similarly running
.B ifdown
on an interface that is not up will also result in an exit status of 0.
.P
.B ifquery
-will normally return with exit status 0 if an interface with a matching iface
stanza, 1 if there is no matching stanza.
-.B ifquery --state
-will also return with exit status 1 if the given interface was known but was
not up.
+will normally return with exit status 0 if
+an interface with a matching iface stanza,
+1 if there is no matching stanza.
+.B ifquery \-\-state
+will also return with exit status 1
+if the given interface was known but was not up.
.SH KNOWN BUGS/LIMITATIONS
The program keeps records of whether network interfaces are up or down.
Under exceptional circumstances these records can become
@@ -272,7 +292,7 @@ without updating the file.
Note that the program does not run automatically:
.B ifup
alone does not bring up interfaces
-that appear as a result of hardware being installed and
+that appear as a result of hardware being installed and
.B ifdown
alone does not bring down interfaces
that disappear as a result of hardware being removed.
