Package: net-tools
Version: 2.10-1.1
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: file '<stdin>':31
troff:<stdin>:31: warning: trailing space in the line
troff: backtrace: file '<stdin>':94
troff:<stdin>:94: warning: trailing space in the line
troff: backtrace: file '<stdin>':114
troff:<stdin>:114: warning: trailing space in the line
troff: backtrace: file '<stdin>':127
troff:<stdin>:127: warning: trailing space in the line
troff: backtrace: file '<stdin>':138
troff:<stdin>:138: warning: trailing space in the line
troff: backtrace: file '<stdin>':166
troff:<stdin>:166: warning: trailing space in the line
troff: backtrace: file '<stdin>':193
troff:<stdin>:193: warning: trailing space in the line
troff: backtrace: file '<stdin>':203
troff:<stdin>:203: warning: trailing space in the line
troff: backtrace: file '<stdin>':208
troff:<stdin>:208: warning: trailing space in the line
troff: backtrace: file '<stdin>':209
troff:<stdin>:209: 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 net-tools depends on:
ii libc6 2.40-3
ii libselinux1 3.7-3
net-tools recommends no packages.
net-tools suggests no packages.
-- 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 ifconfig.8": (possibly shortened list)
mandoc: ifconfig.8:31:19: STYLE: whitespace at end of input line
mandoc: ifconfig.8:94:18: STYLE: whitespace at end of input line
mandoc: ifconfig.8:114:37: STYLE: whitespace at end of input line
mandoc: ifconfig.8:127:52: STYLE: whitespace at end of input line
mandoc: ifconfig.8:138:4: STYLE: whitespace at end of input line
mandoc: ifconfig.8:143:8: STYLE: whitespace at end of input line
mandoc: ifconfig.8:166:24: STYLE: whitespace at end of input line
mandoc: ifconfig.8:193:17: STYLE: whitespace at end of input line
mandoc: ifconfig.8:203:32: STYLE: whitespace at end of input line
mandoc: ifconfig.8:208:75: STYLE: whitespace at end of input line
mandoc: ifconfig.8:209:70: 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".
31:(TCP/IP, default),
94:Enable or disable
114:Add an IPv6 address to an interface.
127:Set the start address in I/O space for this device.
138:are
143:.B AUI
166:flag for the interface.
193:telnet too much.
203:rules for the address using the
208:counters with IEC 60027-2 units. So 1 KiB are 2^10 byte. Note, the numbers
209:are truncated to one decimal (which can by quite a large error if you
-.-.
Add a (no-break, "\ " or "\~") space between a number and a unit,
as these are not one entity.
142:(twisted-pair 10Mbps Ethernet),
-.-.
Use the correct macro for the font change of a single argument or
split the argument into two.
75:.BR "-"
-.-.
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.
5:.B "ifconfig [-v] [-a] [-s] [interface]"
7:.B "ifconfig [-v] interface [aftype] options | address ..."
49:.B -a
52:.B -s
53:display a short list (like netstat -i)
55:.B -v
75:.BR "-"
-.-.
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.
68:Note: for every scope (i.e. same net with address/netmask combination) all
76:to the alias (e.g.
-.-.
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.
N.B.
The number of lines affected can be too large to be in a patch.
45:the number is interpreted as decimal). Use of hexadecimal and octal numbers
62:for the first Ethernet interface. If your kernel supports alias interfaces,
65:for the first alias of eth0. You can use them to assign more addresses. To
68:Note: for every scope (i.e. same net with address/netmask combination) all
183:Set the multicast flag on the interface. This should not normally be needed
190:Set the length of the transmit queue of the device. It is useful to set this
196:Change the name of this interface to \fInewname\fR. The interface must be
shut
200:alias interfaces anymore. The statistics printed for the original address
201:are shared with all alias addresses on the same device. If you want
per-address
208:counters with IEC 60027-2 units. So 1 KiB are 2^10 byte. Note, the numbers
214:it is most likely a interrupt conflict. See
245:Fred N. van Kempen, <wal...@uwalt.nl.mugnet.org>
-.-.
Use \(en (en-dash) for a dash between space characters,
not a minus (\-) or a hyphen (-), except in the NAME section.
ifconfig.8:243:http://physics.nist.gov/cuu/Units/binary.html - Prefixes for
binary multiples
-.-.
Put a parenthetical sentence, phrase on a separate line,
if not part of a code.
See man-pages(7), item "semantic newline".
ifconfig.8:53:display a short list (like netstat -i)
ifconfig.8:68:Note: for every scope (i.e. same net with address/netmask
combination) all
ifconfig.8:120:Create a new SIT (IPv6-in-IPv4) device, tunnelling to the given
destination.
ifconfig.8:191:to small values for slower devices with a high latency (modem
links, ISDN)
ifconfig.8:213:.I (SIOCSIIFLAGS: Resource temporarily unavailable)
-.-.
Use SI units, not abbreviations, bps -> bit/s
142:(twisted-pair 10Mbps Ethernet),
-.-.
Output from "test-groff -mandoc -t -K utf8 -rF0 -rHY=0 -ww -b -z ":
troff: backtrace: file '<stdin>':31
troff:<stdin>:31: warning: trailing space in the line
troff: backtrace: file '<stdin>':94
troff:<stdin>:94: warning: trailing space in the line
troff: backtrace: file '<stdin>':114
troff:<stdin>:114: warning: trailing space in the line
troff: backtrace: file '<stdin>':127
troff:<stdin>:127: warning: trailing space in the line
troff: backtrace: file '<stdin>':138
troff:<stdin>:138: warning: trailing space in the line
troff: backtrace: file '<stdin>':166
troff:<stdin>:166: warning: trailing space in the line
troff: backtrace: file '<stdin>':193
troff:<stdin>:193: warning: trailing space in the line
troff: backtrace: file '<stdin>':203
troff:<stdin>:203: warning: trailing space in the line
troff: backtrace: file '<stdin>':208
troff:<stdin>:208: warning: trailing space in the line
troff: backtrace: file '<stdin>':209
troff:<stdin>:209: warning: trailing space in the line
-.-.
Spelling: informations -> information
Add man page "units(7)" to the "SEE ALSO" paragraph (see bug report #570965).
Additionally (general):
Abbreviations get a '\&' added after their final full stop (.) to mark them
as such and not as an end of a sentence.
--- ifconfig.8 2024-11-11 00:02:06.828175212 +0000
+++ ifconfig.8.new 2024-11-11 01:16:13.962456594 +0000
@@ -2,9 +2,10 @@
.SH NAME
ifconfig \- configure a network interface
.SH SYNOPSIS
-.B "ifconfig [-v] [-a] [-s] [interface]"
+.BR ifconfig " [" \-v "] [" \-a "] [" \-s "] [" \fIinterface\fR]
.br
-.B "ifconfig [-v] interface [aftype] options | address ..."
+.BR ifconfig " [" \-v ]
+.IR interface " [" aftype "] " options " | " address " ..."
.SH DESCRIPTION
.B Ifconfig
is used to configure the kernel-resident network interfaces. It is
@@ -28,7 +29,7 @@ the name of a supported address family,
used for decoding and displaying all protocol addresses. Currently
supported address families include
.B inet
-(TCP/IP, default),
+(TCP/IP, default),
.B inet6
(IPv6),
.B ax25
@@ -42,7 +43,8 @@ supported address families include
All numbers supplied as parts in IPv4 dotted decimal notation may be decimal,
octal, or hexadecimal, as specified in the ISO C standard (that is, a leading
0x
or 0X implies hexadecimal; otherwise, a leading '0' implies octal; otherwise,
-the number is interpreted as decimal). Use of hexadecimal and octal numbers
+the number is interpreted as decimal).
+Use of hexadecimal and octal numbers
is not RFC-compliant and therefore its use is discouraged.
.SH OPTIONS
.TP
@@ -59,19 +61,23 @@ be more verbose for some error condition
The name of the interface. This is usually a driver name followed by
a unit number, for example
.B eth0
-for the first Ethernet interface. If your kernel supports alias interfaces,
+for the first Ethernet interface.
+If your kernel supports alias interfaces,
you can specify them with syntax like
.B eth0:0
-for the first alias of eth0. You can use them to assign more addresses. To
-delete an alias interface use
+for the first alias of eth0.
+You can use them to assign more addresses.
+To delete an alias interface use
.BR "ifconfig eth0:0 down" .
-Note: for every scope (i.e. same net with address/netmask combination) all
-aliases are deleted, if you delete the first (primary).
+Note: for every scope
+(i.e., same net with address/netmask combination)
+all aliases are deleted,
+if you delete the first (primary).
.TP
.B up
-This flag causes the interface to be activated. It is implicitly
-specified if an address is assigned to the interface; you can suppress this
-behavior when using an alias interface by appending an
+This flag causes the interface to be activated.
+It is implicitly specified if an address is assigned to the interface;
+you can suppress this behavior when using an alias interface by appending an
.BR "-"
to the alias (e.g.
.BR "eth0:0-" ).
@@ -87,11 +93,12 @@ Enable or disable the use of the ARP pro
.B "[\-]promisc"
Enable or disable the
.B promiscuous
-mode of the interface. If selected, all packets on the network will
-be received by the interface.
+mode of the interface.
+If selected,
+all packets on the network will be received by the interface.
.TP
.B "[\-]allmulti"
-Enable or disable
+Enable or disable
.B all-multicast
mode. If selected, all multicast packets on the network will be
received by the interface.
@@ -111,7 +118,7 @@ usual class A, B or C network mask (as d
address), but it can be set to any value.
.TP
.B "add addr/prefixlen"
-Add an IPv6 address to an interface.
+Add an IPv6 address to an interface.
.TP
.B "del addr/prefixlen"
Remove an IPv6 address from an interface.
@@ -124,7 +131,7 @@ Set the interrupt line used by this devi
dynamically change their IRQ setting.
.TP
.B "io_addr addr"
-Set the start address in I/O space for this device.
+Set the start address in I/O space for this device.
.TP
.B "mem_start addr"
Set the start address for shared memory used by this device. Only a
@@ -135,12 +142,12 @@ Set the physical port or medium type to
all devices can change this setting, and those that can vary in what
values they support. Typical values for
.B type
-are
+are
.B 10base2
(thin Ethernet),
.B 10baseT
-(twisted-pair 10Mbps Ethernet),
-.B AUI
+(twisted-pair 10\~Mbit/s Ethernet),
+.B AUI
(external transceiver) and so on. The special medium type of
.B auto
can be used to tell the driver to auto-sense the media. Again, not
@@ -163,7 +170,7 @@ the other side of the link, just like th
.B dstaddr
keyword does. Otherwise, set or clear the
.B IFF_POINTOPOINT
-flag for the interface.
+flag for the interface.
.TP
.B hw class address
Set the hardware address of this interface, if the device driver
@@ -180,38 +187,45 @@ and
(AMPR NET/ROM).
.TP
.B multicast
-Set the multicast flag on the interface. This should not normally be needed
+Set the multicast flag on the interface.
+This should not normally be needed
as the drivers set the flag correctly themselves.
.TP
.B address
The IP address to be assigned to this interface.
.TP
.B txqueuelen length
-Set the length of the transmit queue of the device. It is useful to set this
-to small values for slower devices with a high latency (modem links, ISDN)
+Set the length of the transmit queue of the device.
+It is useful to set this to small values for slower devices with a high
+latency
+(modem links, ISDN)
to prevent fast bulk transfers from disturbing interactive traffic like
-telnet too much.
+telnet too much.
.TP
.B name \fInewname\fR
-Change the name of this interface to \fInewname\fR. The interface must be shut
-down first.
+Change the name of this interface to \fInewname\fR.
+The interface must be shut down first.
.SH NOTES
Since kernel release 2.2 there are no explicit interface statistics for
-alias interfaces anymore. The statistics printed for the original address
-are shared with all alias addresses on the same device. If you want per-address
-statistics you should add explicit accounting
-rules for the address using the
+alias interfaces anymore.
+The statistics printed for the original address
+are shared with all alias addresses on the same device.
+If you want per-address statistics
+you should add explicit accounting rules for the address using the
.BR iptables (8)
command.
.LP
Since net\-tools 1.60\-4 ifconfig is printing byte counters and human readable
-counters with IEC 60027-2 units. So 1 KiB are 2^10 byte. Note, the numbers
-are truncated to one decimal (which can by quite a large error if you
-consider 0.1 PiB is 112.589.990.684.262 bytes :)
+counters with IEC 60027-2 units.
+So 1\~KiB are 2^10 bytes.
+Note, the numbers are truncated to one decimal
+(which can by quite a large error
+if you consider 0.1\~PiB is 112.589.990.684.262 bytes :)
.LP
Interrupt problems with Ethernet device drivers fail with EAGAIN
.I (SIOCSIIFLAGS: Resource temporarily unavailable)
-it is most likely a interrupt conflict. See
+it is most likely a interrupt conflict.
+See
.I http://www.scyld.com/expert/irq\-conflict.html
for more information.
.SH FILES
@@ -238,11 +252,12 @@ altered by this command.
.BR rarp (8),
.BR iptables (8),
.BR ifup (8),
-.BR interfaces (5)
+.BR interfaces (5),
+.BR units (7)
.br
http://physics.nist.gov/cuu/Units/binary.html - Prefixes for binary multiples
.SH AUTHORS
-Fred N. van Kempen, <wal...@uwalt.nl.mugnet.org>
+Fred N.\& van Kempen, <wal...@uwalt.nl.mugnet.org>
.br
Alan Cox, <alan....@linux.org>
.br
