--- Begin Message ---
Package: sysvinit-core
Version: 3.09-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 '<standard input>':42
troff:<standard input>:42: warning: trailing space in the line
troff: backtrace: file '<standard input>':43
troff:<standard input>:43: warning: trailing space in the line
troff: backtrace: file '<standard input>':44
troff:<standard input>:44: warning: trailing space in the line
troff: backtrace: file '<standard input>':74
troff:<standard input>:74: warning: trailing space in the line
troff: backtrace: file '<standard input>':110
troff:<standard input>:110: warning: trailing space in the line
troff: backtrace: file '<standard input>':117
troff:<standard input>:117: warning: trailing space in the line
troff: backtrace: file '<standard input>':125
troff:<standard input>:125: warning: trailing space in the line
troff: backtrace: file '<standard input>':126
troff:<standard input>:126: warning: trailing space in the line
troff: backtrace: file '<standard input>':127
troff:<standard input>:127: warning: trailing space in the line
troff: backtrace: file '<standard input>':128
troff:<standard input>:128: warning: trailing space in the line
troff: backtrace: file '<standard input>':129
troff:<standard input>:129: warning: trailing space in the line
troff: backtrace: file '<standard input>':163
troff:<standard input>:163: warning: trailing space in the line
troff: backtrace: file '<standard input>':164
troff:<standard input>:164: warning: trailing space in the line
troff: backtrace: file '<standard input>':174
troff:<standard input>:174: warning: trailing space in the line
troff: backtrace: file '<standard input>':175
troff:<standard input>:175: warning: trailing space in the line
* What outcome did you expect instead?
No output (warnings).
The remarks and the patch are in the attachments.
-- System Information:
Debian Release: trixie/sid
APT prefers testing
APT policy: (500, 'testing')
Architecture: amd64 (x86_64)
Kernel: Linux 6.9.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 sysvinit-core depends on:
ii initscripts 3.09-2
ii libc6 2.39-4
ii libselinux1 3.5-2+b3
ii mount 2.40.2-1
ii sysv-rc 3.09-2
ii sysvinit-utils 3.09-2
Versions of packages sysvinit-core recommends:
ii orphan-sysvinit-scripts 0.16
Versions of packages sysvinit-core suggests:
ii bootlogd 3.09-2
-- 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' 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 errors:
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
(that is not confined to a markup)
in the first column.
Line length should thus be reduced.
-.-
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 -z"
export MAN_KEEP_STDERR=yes (or any non-empty value)
-.-.
Output from "mandoc -T lint shutdown.8": (possibly shortened list)
mandoc: shutdown.8:42:40: STYLE: whitespace at end of input line
mandoc: shutdown.8:43:65: STYLE: whitespace at end of input line
mandoc: shutdown.8:44:66: STYLE: whitespace at end of input line
mandoc: shutdown.8:56:5: STYLE: unterminated quoted argument
mandoc: shutdown.8:69:83: STYLE: input text line longer than 80 bytes: Halt or
power off af...
mandoc: shutdown.8:74:69: STYLE: whitespace at end of input line
mandoc: shutdown.8:108:86: STYLE: input text line longer than 80 bytes: Reduce
the number of...
mandoc: shutdown.8:110:66: STYLE: whitespace at end of input line
mandoc: shutdown.8:117:66: STYLE: whitespace at end of input line
mandoc: shutdown.8:124:97: STYLE: input text line longer than 80 bytes: warning
(\fBSIGTERM\...
mandoc: shutdown.8:125:73: STYLE: whitespace at end of input line
mandoc: shutdown.8:126:93: STYLE: input text line longer than 80 bytes: three
seconds. Warni...
mandoc: shutdown.8:126:93: STYLE: whitespace at end of input line
mandoc: shutdown.8:127:80: STYLE: whitespace at end of input line
mandoc: shutdown.8:128:67: STYLE: whitespace at end of input line
mandoc: shutdown.8:129:87: STYLE: input text line longer than 80 bytes: When
\fBshutdown\fP ...
mandoc: shutdown.8:129:87: STYLE: whitespace at end of input line
mandoc: shutdown.8:163:77: STYLE: whitespace at end of input line
mandoc: shutdown.8:164:77: STYLE: whitespace at end of input line
mandoc: shutdown.8:174:67: STYLE: whitespace at end of input line
mandoc: shutdown.8:175:42: STYLE: whitespace at end of input line
mandoc: shutdown.8:207:87: STYLE: input text line longer than 80 bytes: that
variable to \fB...
-.-.
Input file is shutdown.8, case 1
Test nr. 1:
Remove space characters at the end of lines.
Use "git apply ... --whitespace=fix" to fix extra space issues, or use
global configuration "core.whitespace".
42:the time to save the file being edited,
43:mail and news processing programs a chance to exit cleanly, etc.
44:\fBshutdown\fP does its job by signalling the \fBinit\fP process,
74:Modifier to the \fB-h\fP flag. Halt action is to turn off the power.
110:countdown until \fItime\fP is reached. When \fB-q\fP is specified
117:countdown until \fItime\fP is reached. When \fB-Q\fP is specified
125:The default time, if no value is specified, between these two signals is
126:three seconds. Warning: when \fBshutdown\fP calls \fBinit\fP(8) to perform
the shutdown (the
127:default behavior), \fBinit\fP(8) checks to see if all processes have
terminated
128:and will stop waiting early once its children have all terminated.
129:When \fBshutdown\fP is called with the \fB-n\fP flag, it waits the full
time specified
163:up again. The boot rc file can test if this file is present, and decide
not
164:to run \fBfsck\fP(8) since the system has been shut down in the proper way.
174:The \fB-n\fP flag causes \fBshutdown\fP not to call \fBinit\fP(8),
175:but to kill all running processes itself.
-.-.
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.
49:if neither the \fB\-h\fP or \fB\-r\fP flag is given to \fBshutdown\fP.
55:.\"{{{ \-a
59:.\"{{{ \-k
63:.\"{{{ \-r
67:.\"{{{ \-h
69:Halt or power off after shutdown. Usually used with the \fB\-P\fP or
\fB\-H\fP flags,
72:.\"{{{ -P
74:Modifier to the \fB\-h\fP flag. Halt action is to turn off the power.
75:Must be used with the \fB\-h\fP flag.
77:.\"{{{ -H
79:Modifier to the \fB\-h\fP flag. Halt action is to halt or drop into boot
80:monitor on systems that support it. Must be used with the \fB\-h\fP flag.
84:use the \fB\-P\fP modifier instead.
86:.\"{{{ -f
90:.\"{{{ -F
94:.\"{{{ -n
100:.\"{{{ -c
106:.\"{{{ -q
110:countdown until \fItime\fP is reached. When \fB\-q\fP is specified
113:.\"{{{ -Q
117:countdown until \fItime\fP is reached. When \fB\-Q\fP is specified
121:.\"{{{ -t sec
129:When \fBshutdown\fP is called with the \fB\-n\fP flag, it waits the full
time specified
174:The \fB\-n\fP flag causes \fBshutdown\fP not to call \fBinit\fP(8),
186:one of the virtual consoles. If \fBshutdown\fP is called with the \fB\-a\fP
202:Note that if \fI/etc/shutdown.allow\fP is not present, the \fB\-a\fP
205:The \fB\-H\fP option just sets the \fBinit\fP environment variable
206:\fBINIT_HALT\fP to \fBHALT\fP, and the \fB\-P\fP option just sets
-.-.
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.
158:can signal init (i.e. it is cancelled or something goes wrong).
-.-.
Wrong distance between sentences.
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 the patch.
69:Halt or power off after shutdown. Usually used with the \fB-P\fP or \fB-H\fP
flags,
74:Modifier to the \fB-h\fP flag. Halt action is to turn off the power.
82:output on the screen for debugging purposes. Or when the user wants the OS to
83:stop, but leave the power on. To power off at the end of the shutdown
sequence
102:Cancel a waiting shutdown. (\fBshutdown now\fP is no longer waiting.) With
108:Reduce the number of warnings \fBshutdown\fP displays. Usually
\fBshutdown\fP displays
110:countdown until \fItime\fP is reached. When \fB-q\fP is specified
115:Silence warnings prior to shutting down. Usually \fBshutdown\fP displays
117:countdown until \fItime\fP is reached. When \fB-Q\fP is specified
118:\fBshutdown\fP only warns when the shutdown process actually happens. All
126:three seconds. Warning: when \fBshutdown\fP calls \fBinit\fP(8) to perform
the shutdown (the
156:logins. This file is created five minutes before the shutdown sequence
157:starts. \fBshutdown\fP removes this file if it is stopped before it
158:can signal init (i.e. it is cancelled or something goes wrong).
183:\fI/etc/inittab\fP. This means that everyone who has physical access
184:to the console keyboard can shut the system down. To prevent this,
186:one of the virtual consoles. If \fBshutdown\fP is called with the \fB-a\fP
190:that are logged in on a virtual console (from \fI/var/run/utmp\fP). Only
192:proceed. Otherwise it will write the message
198:to the (physical) system console. The format of \fI/etc/shutdown.allow\fP
199:is one user name per line. Empty lines and comment lines (prefixed by a
200:\fB#\fP) are allowed. Currently there is a limit of 32 users in this file.
207:that variable to \fBPOWEROFF\fP. The script (usually
\fI/etc/init.d/halt\fP) that calls
222:and are then puzzled by the error message \fBshutdown\fP produces. The
228:all key strokes. Some X11 environments make it possible to capture
232:\fBshutdown\fP wasn't designed to be run setuid. \fI/etc/shutdown.allow\fP
is
-.-.
Test nr. 31:
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 20, length 84
.TH SHUTDOWN 8 "November 12, 2003" "sysvinit " "Linux System Administrator's
Manual"
Line 69, length 83
Halt or power off after shutdown. Usually used with the \fB-P\fP or \fB-H\fP
flags,
Line 108, length 86
Reduce the number of warnings \fBshutdown\fP displays. Usually \fBshutdown\fP
displays
Line 124, length 97
warning (\fBSIGTERM\fP) and the kill signal (\fBSIGKILL\fP), before changing to
another runlevel.
Line 126, length 93
three seconds. Warning: when \fBshutdown\fP calls \fBinit\fP(8) to perform the
shutdown (the
Line 129, length 87
When \fBshutdown\fP is called with the \fB-n\fP flag, it waits the full time
specified
Line 207, length 87
that variable to \fBPOWEROFF\fP. The script (usually \fI/etc/init.d/halt\fP)
that calls
Line 226, length 85
\fBinit\fP(8) can only capture CTRL-ALT-DEL and start \fBshutdown\fP in console
mode.
-.-.
Output from "test-groff -b -mandoc -rF0 -rHY=0 -K utf8 -t -ww -z ":
troff: backtrace: file '<stdin>':42
troff:<stdin>:42: warning: trailing space in the line
troff: backtrace: file '<stdin>':43
troff:<stdin>:43: warning: trailing space in the line
troff: backtrace: file '<stdin>':44
troff:<stdin>:44: warning: trailing space in the line
troff: backtrace: file '<stdin>':74
troff:<stdin>:74: warning: trailing space in the line
troff: backtrace: file '<stdin>':110
troff:<stdin>:110: warning: trailing space in the line
troff: backtrace: file '<stdin>':117
troff:<stdin>:117: warning: trailing space in the line
troff: backtrace: file '<stdin>':125
troff:<stdin>:125: warning: trailing space in the line
troff: backtrace: file '<stdin>':126
troff:<stdin>:126: warning: trailing space in the line
troff: backtrace: file '<stdin>':127
troff:<stdin>:127: warning: trailing space in the line
troff: backtrace: file '<stdin>':128
troff:<stdin>:128: warning: trailing space in the line
troff: backtrace: file '<stdin>':129
troff:<stdin>:129: warning: trailing space in the line
troff: backtrace: file '<stdin>':163
troff:<stdin>:163: warning: trailing space in the line
troff: backtrace: file '<stdin>':164
troff:<stdin>:164: warning: trailing space in the line
troff: backtrace: file '<stdin>':174
troff:<stdin>:174: warning: trailing space in the line
troff: backtrace: file '<stdin>':175
troff:<stdin>:175: warning: trailing space in the line
--- shutdown.8 2024-07-22 22:17:11.727799653 +0000
+++ shutdown.8.new 2024-07-23 16:41:31.457930543 +0000
@@ -39,14 +39,14 @@ notified that the system is going down,
It is possible to shut the system down immediately or after a specified delay.
All processes are first notified that the system is going down by the
signal \fBSIGTERM\fP. This gives programs like \fBvi\fP(1)
-the time to save the file being edited,
-mail and news processing programs a chance to exit cleanly, etc.
-\fBshutdown\fP does its job by signalling the \fBinit\fP process,
+the time to save the file being edited,
+mail and news processing programs a chance to exit cleanly, etc.
+\fBshutdown\fP does its job by signalling the \fBinit\fP process,
asking it to change the runlevel.
Runlevel \fB0\fP is used to halt the system, runlevel \fB6\fP is used
to reboot the system, and runlevel \fB1\fP is used to put to system into
a state where administrative tasks can be performed; this is the default
-if neither the \fB-h\fP or \fB-r\fP flag is given to \fBshutdown\fP.
+if neither the \fB\-h\fP or \fB\-r\fP flag is given to \fBshutdown\fP.
To see which actions are taken on halt or reboot see the appropriate
entries for these runlevels in the file \fI/etc/inittab\fP.
.\"}}}
@@ -66,22 +66,24 @@ Reboot after shutdown.
.\"}}}
.\"{{{ -h
.IP \fB\-h\fP
-Halt or power off after shutdown. Usually used with the \fB-P\fP or \fB-H\fP flags,
-depending on whether we want to poweroff or simply stop the operating system.
+Halt or power off after shutdown.
+Usually used with the \fB\-P\fP or \fB\-H\fP flags,
+depending on whether we want to poweroff or
+simply stop the operating system.
.\"}}}
.\"{{{ -P
.IP \fB\-P\fP
-Modifier to the \fB-h\fP flag. Halt action is to turn off the power.
-Must be used with the \fB-h\fP flag.
+Modifier to the \fB\-h\fP flag. Halt action is to turn off the power.
+Must be used with the \fB\-h\fP flag.
.\"}}}
.\"{{{ -H
.IP \fB\-H\fP
-Modifier to the \fB-h\fP flag. Halt action is to halt or drop into boot
-monitor on systems that support it. Must be used with the \fB-h\fP flag.
+Modifier to the \fB\-h\fP flag. Halt action is to halt or drop into boot
+monitor on systems that support it. Must be used with the \fB\-h\fP flag.
Halting is often used to run through the shutdown process and leave
output on the screen for debugging purposes. Or when the user wants the OS to
stop, but leave the power on. To power off at the end of the shutdown sequence
-use the \fB-P\fP modifier instead.
+use the \fB\-P\fP modifier instead.
.\"}}}
.\"{{{ -f
.IP \fB\-f\fP
@@ -105,28 +107,33 @@ you can enter explanatory message argume
will be sent to all users.
.\"{{{ -q
.IP \fB\-q
-Reduce the number of warnings \fBshutdown\fP displays. Usually \fBshutdown\fP displays
+Reduce the number of warnings \fBshutdown\fP displays.
+Usually \fBshutdown\fP displays
warnings every 15 minutes and then every minute in the last 10 minutes of the
-countdown until \fItime\fP is reached. When \fB-q\fP is specified
+countdown until \fItime\fP is reached. When \fB\-q\fP is specified
\fBshutdown\fP only warns at 60 minute intervals, at the 10 minute mark,
at the 5 minute mark, and when the shutdown process actually happens.
.\"{{{ -Q
.IP \fB\-Q
Silence warnings prior to shutting down. Usually \fBshutdown\fP displays
warnings every 15 minutes and then every minute in the last 10 minutes of the
-countdown until \fItime\fP is reached. When \fB-Q\fP is specified
+countdown until \fItime\fP is reached. When \fB\-Q\fP is specified
\fBshutdown\fP only warns when the shutdown process actually happens. All
other warning intervals are suppressed.
.\"}}}
.\"{{{ -t sec
.IP "\fB\-t\fP \fIsec\fP"
Tell \fBinit\fP(8) to wait \fIsec\fP seconds between sending all processes the
-warning (\fBSIGTERM\fP) and the kill signal (\fBSIGKILL\fP), before changing to another runlevel.
-The default time, if no value is specified, between these two signals is
-three seconds. Warning: when \fBshutdown\fP calls \fBinit\fP(8) to perform the shutdown (the
-default behavior), \fBinit\fP(8) checks to see if all processes have terminated
-and will stop waiting early once its children have all terminated.
-When \fBshutdown\fP is called with the \fB-n\fP flag, it waits the full time specified
+warning (\fBSIGTERM\fP) and the kill signal (\fBSIGKILL\fP),
+before changing to another runlevel.
+The default time, if no value is specified, between these two signals is
+three seconds.
+Warning: when \fBshutdown\fP calls \fBinit\fP(8) to perform the shutdown
+(the default behavior),
+\fBinit\fP(8) checks to see if all processes have terminated
+and will stop waiting early once its children have all terminated.
+When \fBshutdown\fP is called with the \fB\-n\fP flag,
+it waits the full time specified
(or three seconds) even if all other processes have terminated.
.\"}}}
.\"{{{ time
@@ -155,13 +162,13 @@ If \fBshutdown\fP is called with a delay
which causes programs such as \fBlogin\fP(1) to not allow new user
logins. This file is created five minutes before the shutdown sequence
starts. \fBshutdown\fP removes this file if it is stopped before it
-can signal init (i.e. it is cancelled or something goes wrong).
+can signal init (i.e., it is cancelled or something goes wrong).
It also removes it before calling \fBinit\fP(8) to change the runlevel.
.PP
The \fB\-f\fP flag means `reboot fast'. This only creates an advisory
file \fI/fastboot\fP which can be tested by the system when it comes
-up again. The boot rc file can test if this file is present, and decide not
-to run \fBfsck\fP(8) since the system has been shut down in the proper way.
+up again. The boot rc file can test if this file is present, and decide not
+to run \fBfsck\fP(8) since the system has been shut down in the proper way.
After that, the boot process should remove \fI/fastboot\fP.
.PP
The \fB\-F\fP flag means `force fsck'. This only creates an advisory
@@ -171,8 +178,8 @@ to run \fBfsck\fP(8) with a special `for
unmounted file systems get checked.
After that, the boot process should remove \fI/forcefsck\fP.
.PP
-The \fB-n\fP flag causes \fBshutdown\fP not to call \fBinit\fP(8),
-but to kill all running processes itself.
+The \fB\-n\fP flag causes \fBshutdown\fP not to call \fBinit\fP(8),
+but to kill all running processes itself.
\fBshutdown\fP will then turn off quota, accounting, and swapping
and unmount all file systems.
.\"}}}
@@ -183,7 +190,7 @@ and unmount all file systems.
\fI/etc/inittab\fP. This means that everyone who has physical access
to the console keyboard can shut the system down. To prevent this,
\fBshutdown\fP can check to see if an authorized user is logged in on
-one of the virtual consoles. If \fBshutdown\fP is called with the \fB-a\fP
+one of the virtual consoles. If \fBshutdown\fP is called with the \fB\-a\fP
argument (add this to the invocation of shutdown in \fI/etc/inittab\fP),
it checks to see if the file \fI/etc/shutdown.allow\fP is present.
It then compares the login names in that file with the list of people
@@ -199,12 +206,13 @@ to the (physical) system console. The fo
is one user name per line. Empty lines and comment lines (prefixed by a
\fB#\fP) are allowed. Currently there is a limit of 32 users in this file.
.sp 1
-Note that if \fI/etc/shutdown.allow\fP is not present, the \fB-a\fP
+Note that if \fI/etc/shutdown.allow\fP is not present, the \fB\-a\fP
argument is ignored.
.SH HALT OR POWEROFF
-The \fB-H\fP option just sets the \fBinit\fP environment variable
-\fBINIT_HALT\fP to \fBHALT\fP, and the \fB-P\fP option just sets
-that variable to \fBPOWEROFF\fP. The script (usually \fI/etc/init.d/halt\fP) that calls
+The \fB\-H\fP option just sets the \fBinit\fP environment variable
+\fBINIT_HALT\fP to \fBHALT\fP, and the \fB\-P\fP option just sets
+that variable to \fBPOWEROFF\fP.
+The script (usually \fI/etc/init.d/halt\fP) that calls
the \fBhalt\fP(8) program as the last thing in the shutting down sequence should
check this environment variable and call the \fBhalt\fP(8) program with
the right options for these options to actually have any effect.
@@ -223,7 +231,8 @@ and are then puzzled by the error messag
\fItime\fP argument is mandatory; in 90 percent of all cases this argument
will be the word \fBnow\fP.
.PP
-\fBinit\fP(8) can only capture CTRL-ALT-DEL and start \fBshutdown\fP in console mode.
+\fBinit\fP(8) can only capture CTRL-ALT-DEL and
+start \fBshutdown\fP in console mode.
If the system is running the X window System, the X server processes
all key strokes. Some X11 environments make it possible to capture
CTRL-ALT-DEL, but what exactly is done with that event depends on
--- End Message ---
pgp3B7_XSF14N.pgp
