Bug#1076822: shutdown.8: Some remarks and editorial changes for this man page
Bjarni Ingi Gislason
bjarniig at simnet.is
Tue Jul 23 18:40:24 BST 2024
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
-------------- next part --------------
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
-------------- next part --------------
A non-text attachment was scrubbed...
Name: shutdown.8.diff
Type: text/x-diff
Size: 8731 bytes
Desc: not available
URL: <http://www.chiark.greenend.org.uk/pipermail/debian-init-diversity/attachments/20240723/a3ee5432/attachment-0001.diff>
More information about the Debian-init-diversity
mailing list