Package: procps
Version: 2:4.0.4-5
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: '/home/bg/git/groff/build/s-tmac/an.tmac':709: string
'an-result'
troff: backtrace: '/home/bg/git/groff/build/s-tmac/an.tmac':715: macro 'RI'
troff: backtrace: file '<stdin>':217
troff:<stdin>:217: warning: ignoring escape character before '+'
an.tmac:<stdin>:580: warning: cannot nest .TP or .TQ inside .TP; supply a tag
* 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.10.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 procps depends on:
ii init-system-helpers 1.66
ii libc6 2.40-2
ii libncursesw6 6.5-2
ii libproc2-0 2:4.0.4-5
ii libsystemd0 256.5-1
ii libtinfo6 6.5-2
Versions of packages procps recommends:
pn linux-sysctl-defaults <none>
ii psmisc 23.7-1
procps suggests no packages.
-- no debconf information
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', '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 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 -b -z"
export MAN_KEEP_STDERR=yes (or any non-empty value)
-.-.
Output from "mandoc -T lint ps.1": (possibly shortened list)
mandoc: ps.1:217:5: WARNING: undefined escape, printing literally: \+
mandoc: ps.1:579:2: WARNING: line scope broken: TP breaks TP
mandoc: ps.1:582:84: STYLE: input text line longer than 80 bytes: Set the date
format ...
mandoc: ps.1:713:87: STYLE: input text line longer than 80 bytes: If the column
width ...
mandoc: ps.1:2069:2: WARNING: skipping paragraph macro: PP empty
-.-.
Change two HYPHEN-MINUSES (code 0x2D) to an em-dash (\(em),
if one is intended. 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 "\-\-".
ps.1:1994:.B --ppid 2 -p 2 --deselect
-.-.
Change -- in x--y to \(em (em-dash), or, if an
option, to \-\-
1994:.B --ppid 2 -p 2 --deselect
-.-.
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.
1992:.B -e
-.-.
Find a repeated word
! 1243 --> included
-.-.
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.
473:formatting), specify the option in some other way (e.g. with
665:formatting), specify the option in some other way (e.g. with
900:(e.g. sorting on tty will sort into device number, not according to 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.
N.B.
The number of lines affected can be too large to be in the patch.
228:NOTE: The command name is not the same as the command line. Previous
versions
229:of procps and the kernel truncated this command name to 15 characters. This
230:limitation is no longer present in both. If you depended on matching only
309:additional filtering rules. The order of pids is unsorted
310:and preserved. No additional selection options, sorting
582:Set the date format of the \fBlstart\fR field to \fIformat\fR. This format
is parsed
1028:command with all its arguments as a string. Modifications to the arguments
1082:processor utilization. Currently, this is the integer value of the percent
1240:It is also known as DATA. Such memory may not yet be mapped to
1262:instruction pointer. As of kernel 4.9.xx will be zeroed out unless task is
1267:stack pointer. As of kernel 4.9.xx will be zeroed out unless task is
1293:path to the executable. Useful if path cannot be printed via
1384:time the command started. This will be in the form "DDD mmm HH:MM:SS YYY"
1436:nice value. This ranges from 19 (nicest) to \-20 (not nice to others),
1466:Out of Memory Score. The value, ranging from 0 to +1000, used to select
1471:Out of Memory Adjustment Factor. The value is added to the current out of
1489:mask of the pending signals. See
1759:see \fBstart_time\fR. (alias \fBstart_time\fR).
1993:option. This is equivalent to selecting
1995:instead. Also works in BSD mode.
2001:Default output format override. You may set this to a format
2065:month name in English. The fields \fBlstart\fR and \fBstime\fR will show
2100:Michael K. Johnson
-.-.
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 582, length 84
Set the date format of the \fBlstart\fR field to \fIformat\fR. This format is
parsed
Line 713, length 87
If the column width cannot show all signals, the column will end with a plus
"\fI+\fR".
Line 1024, length 81
The autogroup nice value which affects scheduling of all processes in that
group.
Line 1219, length 90
The CPU utilization of a process, including dead children, in an extended
"##.###" format.
Line 1239, length 81
data resident set size, the amount of private memory \fIreserved\fR by a
process.
Line 1577, length 89
Number of bytes which this process really did cause to be fetched from the
storage layer.
Line 1854, length 81
text resident set size, the amount of physical memory devoted to executable
code.
Line 1955, length 81
Number of bytes which this task has caused, or shall cause to be written to
disk.
-.-.
Change a HYPHEN-MINUS (code 0x55, 2D) to a dash
(\-, minus) if it matches "[[:alph:]]-[[:alpha:]]" in the name of an
option).
Facilitates the copy and paste of an option in UTF-8 text.
Is not needed in ordinary words like "mother-in-law", that are not
copied and pasted to a command line (which needs ASCII code)
587:.BI \-\-date-format \ format
-.-.
chk_man: -.- File temp.table -.-.
Change (or include a "FIXME" paragraph about) misused SI (metric)
numeric prefixes (or names) to the binary ones, like Ki (kibi), Mi
(mebi), Gi (gibi), or Ti (tebi), if indicated.
If the metric prefixes are correct, add the definitions or an
explanation to avoid misunderstanding.
22:s size memory size in kilobytes
53:l1B l1B lBw(\n[ColSize]n)
54:l1B l1 l.
653:kilobytes). (alias
-.-.
Use the correct macro for the font change of a single argument or
split the argument into two.
349:.BR args
-.-.
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 the patch.
81:command with all its arguments as a string. Modifications to the arguments
135:processor utilization. Currently, this is the integer value of the percent
293:It is also known as DATA. Such memory may not yet be mapped to
315:instruction pointer. As of kernel 4.9.xx will be zeroed out unless task is
320:stack pointer. As of kernel 4.9.xx will be zeroed out unless task is
346:path to the executable. Useful if path cannot be printed via
437:time the command started. This will be in the form "DDD mmm HH:MM:SS YYY"
489:nice value. This ranges from 19 (nicest) to \-20 (not nice to others),
519:Out of Memory Score. The value, ranging from 0 to +1000, used to select
524:Out of Memory Adjustment Factor. The value is added to the current out of
542:mask of the pending signals. See
812:see \fBstart_time\fR. (alias \fBstart_time\fR).
-.-.
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 the patch.
Line 77, length 81
The autogroup nice value which affects scheduling of all processes in that
group.
Line 272, length 90
The CPU utilization of a process, including dead children, in an extended
"##.###" format.
Line 292, length 81
data resident set size, the amount of private memory \fIreserved\fR by a
process.
Line 630, length 89
Number of bytes which this process really did cause to be fetched from the
storage layer.
Line 907, length 81
text resident set size, the amount of physical memory devoted to executable
code.
Line 1008, length 81
Number of bytes which this task has caused, or shall cause to be written to
disk.
-.-.
Output from "test-groff -b -mandoc -rF0 -rHY=0 -K utf8 -t -ww -z ":
troff: backtrace: '/home/bg/git/groff/build/s-tmac/an.tmac':709: string
'an-result'
troff: backtrace: '/home/bg/git/groff/build/s-tmac/an.tmac':715: macro 'RI'
troff: backtrace: file '<stdin>':217
troff:<stdin>:217: warning: ignoring escape character before '+'
an.tmac:<stdin>:580: warning: cannot nest .TP or .TQ inside .TP; supply a tag
--- ps.1 2024-09-14 22:54:41.337404465 +0000
+++ ps.1.new 2024-09-14 23:47:12.409157093 +0000
@@ -214,7 +214,7 @@ comma\-separated list. They can be used
Identical to
.B \-\-pid\ \fI123\fR.
.TP
-.RI \+ 123
+.RI + 123
Identical to
.B \-\-sid\ \fI123\fR.
.TP
@@ -470,7 +470,7 @@ option can act like
(user\-defined output format with some common fields predefined) or can be
used to specify sort order. Heuristics are used to determine the behavior of
this option. To ensure that the desired behavior is obtained (sorting or
-formatting), specify the option in some other way (e.g. with
+formatting), specify the option in some other way (e.g., with
.B \-O
or
.BR \-\-sort ).
@@ -577,10 +577,9 @@ Set screen width.
.B \-\-cumulative
Include some dead child process data (as a sum with the parent).
.TP
-.TP
.BI \-D \ format
-Set the date format of the \fBlstart\fR field to \fIformat\fR. This format is
parsed
-by
+Set the date format of the \fBlstart\fR field to \fIformat\fR.
+This format is parsed by
.BR strftime (3)
and should be a maximum of 24 characters to not mis-align columns.
.TP
@@ -662,7 +661,7 @@ option can act like
(user\-defined output format with some common fields predefined) or can be
used to specify sort order. Heuristics are used to determine the behavior of
this option. To ensure that the desired behavior is obtained (sorting or
-formatting), specify the option in some other way (e.g. with
+formatting), specify the option in some other way (e.g., with
.B \-O
or
.BR \-\-sort ).
@@ -710,7 +709,8 @@ For example:
.TP
.B \-\-signames
Show signal masks using abbreviated signal names and expands the collumn.
-If the column width cannot show all signals, the column will end with a plus
"\fI+\fR".
+If the column width cannot show all signals,
+the column will end with a plus "\fI+\fR".
Columns with only a hyphen have no signals.
.TP
.B w
@@ -897,7 +897,7 @@ option doesn't use these keys, but the s
section. Note that the values used in sorting are the internal values
.B ps
uses and not the "cooked" values used in some of the output format fields
-(e.g. sorting on tty will sort into device number, not according to the
+(e.g., sorting on tty will sort into device number, not according to the
terminal name displayed). Pipe
.B ps
output into the
@@ -1025,12 +1025,15 @@ The autogroup nice value which affects s
T}
args COMMAND T{
-command with all its arguments as a string. Modifications to the arguments
-may be shown. The output in this column may contain spaces. A process
-marked <defunct> is partly dead, waiting to be fully destroyed by its parent.
+command with all its arguments as a string.
+Modifications to the arguments may be shown.
+The output in this column may contain spaces.
+A process marked <defunct> is partly dead,
+waiting to be fully destroyed by its parent.
Sometimes the process args will be unavailable; when this happens,
.B ps
-will instead print the executable name in brackets. (alias
+will instead print the executable name in brackets.
+(alias
.BR cmd ", " command ).
See also the
.B comm
@@ -1079,8 +1082,10 @@ minutes of cpu time.
T}
c C T{
-processor utilization. Currently, this is the integer value of the percent
-usage over the lifetime of the process. (see
+processor utilization.
+Currently, this is the integer value of the percent
+usage over the lifetime of the process.
+(see
.BR %cpu ).
T}
@@ -1216,7 +1221,8 @@ cumulative CPU time in seconds (alias
T}
cuc %CUC T{
-The CPU utilization of a process, including dead children, in an extended
"##.###" format.
+The CPU utilization of a process, including dead children,
+in an extended "##.###" format.
(see also
.BR %cpu ,
.BR c ,
@@ -1236,11 +1242,12 @@ The CPU utilization of a process in an e
T}
drs DRS T{
-data resident set size, the amount of private memory \fIreserved\fR by a
process.
-It is also known as DATA. Such memory may not yet be mapped to
+data resident set size,
+the amount of private memory \fIreserved\fR by a process.
+It is also known as DATA.
+Such memory may not yet be mapped to
.B rss
-but will always be included
-included in the
+but will always be included in the
.B vsz
amount.
@@ -1259,12 +1266,14 @@ otherwise. (alias
T}
eip EIP T{
-instruction pointer. As of kernel 4.9.xx will be zeroed out unless task is
+instruction pointer.
+As of kernel 4.9.xx will be zeroed out unless task is
exiting or being core dumped.
T}
esp ESP T{
-stack pointer. As of kernel 4.9.xx will be zeroed out unless task is
+stack pointer.
+As of kernel 4.9.xx will be zeroed out unless task is
exiting or being core dumped.
T}
@@ -1290,10 +1299,11 @@ option can be used to force the decimal
T}
exe EXE T{
-path to the executable. Useful if path cannot be printed via
+path to the executable.
+Useful if path cannot be printed via
.BR cmd ", " comm
or
-.BR args
+.B args
format options.
T}
@@ -1381,7 +1391,8 @@ the
T}
lstart STARTED T{
-time the command started. This will be in the form "DDD mmm HH:MM:SS YYY"
+time the command started.
+This will be in the form "DDD mmm HH:MM:SS YYY"
unless changed by the \fB\-D\fR option.
T}
@@ -1433,7 +1444,8 @@ See
T}
ni NI T{
-nice value. This ranges from 19 (nicest) to \-20 (not nice to others),
+nice value.
+This ranges from 19 (nicest) to \-20 (not nice to others),
see
.IR nice (1).
(alias
@@ -1463,12 +1475,14 @@ if you want the kernel function name).
T}
oom OOM T{
-Out of Memory Score. The value, ranging from 0 to +1000, used to select
+Out of Memory Score.
+The value, ranging from 0 to +1000, used to select
task(s) to kill when memory is exhausted.
T}
oomadj OOMADJ T{
-Out of Memory Adjustment Factor. The value is added to the current out of
+Out of Memory Adjustment Factor.
+The value is added to the current out of
memory score which is then used to determine which task to kill when memory
is exhausted.
T}
@@ -1486,16 +1500,20 @@ see
T}
pending PENDING T{
-mask of the pending signals. See
+mask of the pending signals.
+See
.IR signal (7).
Signals pending on the process are distinct from signals pending on
-individual threads. Use the
+individual threads.
+Use the
.B m
option or the
.B \-m
-option to see both. According to the width of the field, a 32 or 64 bits
-mask in hexadecimal
-format is displayed, unless the \fB\-\-signames\fR option is used. (alias
+option to see both.
+According to the width of the field, a 32 or 64 bits mask in hexadecimal
+format is displayed,
+unless the \fB\-\-signames\fR option is used.
+(alias
.BR sig ).
T}
@@ -1569,12 +1587,14 @@ processor that process last executed on.
T}
pss PSS T{
-Proportional share size, the non-swapped physical memory, with shared memory
-proportionally accounted to all tasks mapping it.
+Proportional share size,
+the non-swapped physical memory,
+with shared memory proportionally accounted to all tasks mapping it.
T}
rbytes RBYTES T{
-Number of bytes which this process really did cause to be fetched from the
storage layer.
+Number of bytes which this process really did cause to be fetched from the
+storage layer.
T}
rchars RCHARS T{
@@ -1756,7 +1776,8 @@ see
T}
stime STIME T{
-see \fBstart_time\fR. (alias \fBstart_time\fR).
+see \fBstart_time\fR.
+(alias \fBstart_time\fR).
T}
suid SUID T{
@@ -1851,7 +1872,8 @@ connected to, or \-1 if the process is n
T}
trs TRS T{
-text resident set size, the amount of physical memory devoted to executable
code.
+text resident set size,
+the amount of physical memory devoted to executable code.
T}
tt TT T{
@@ -1952,7 +1974,8 @@ name of the kernel function in which the
T}
wchars WCHARS T{
-Number of bytes which this task has caused, or shall cause to be written to
disk.
+Number of bytes which this task has caused,
+or shall cause to be written to disk.
T}
wops WOPS T{
@@ -1989,9 +2012,9 @@ Date format.
.TP
.B LIBPROC_HIDE_KERNEL
Set this to any value to hide kernel threads normally displayed with the
-.B -e
+.B \-e
option. This is equivalent to selecting
-.B --ppid 2 -p 2 --deselect
+.B \-\-ppid 2 \-p 2 \-\-deselect
instead. Also works in BSD mode.
.TP
.B PS_COLORS
@@ -2066,7 +2089,6 @@ month name in English. The fields \fBlst
the abbreviated month name in the configured locale but may exceed the
column width due to the different lengths for abbreviated month and day
names across languages.
-.PP
.SH "SEE ALSO"
.BR pgrep (1),
.BR pstree (1),
@@ -2097,7 +2119,7 @@ was originally written by
Branko Lankester
.ME .
.MT johnsonm@\:redhat.\:com
-Michael K. Johnson
+Michael K.\& Johnson
.ME
re\-wrote it significantly to use the proc filesystem, changing a few things
in the process.
