Package: valgrind
Version: 1:3.20.0-2.1
Severity: minor
Tags: upstream
* What led up to the situation?
Checking for defects with a new version
test-[g|n]roff -mandoc -t -K utf8 -rF0 -rHY=0 -rCHECKSTYLE=10 -ww -z < "man
page"
[Use "groff -e ' $' <file>" to find obvious 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:<stdin>:214: warning: [page 2, 8.4i]: cannot break line
Output from "test-nroff -mandoc -t -K utf8 -rF0 -rHY=0 -rCHECKSTYLE=10 -ww -z
":
troff:<stdin>:204: warning [page 2, line 54]: cannot break line
troff:<stdin>:209: warning [page 2, line 57]: cannot break line
troff:<stdin>:214: warning [page 2, line 60]: cannot break 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.12.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 valgrind depends on:
ii libc6 2.40-5
ii libc6-dbg 2.40-5
Versions of packages valgrind recommends:
ii gdb 15.2-1+b1
pn valgrind-dbg <none>
Versions of packages valgrind suggests:
pn kcachegrind <none>
pn valgrind-mpi <none>
-- no debconf information
Input file is vgdb.1
Output from "mandoc -T lint vgdb.1": (shortened list)
1 input text line longer than 80 bytes: ("Valgrind to GDB") ...
1 input text line longer than 80 bytes: As a standalone util...
1 input text line longer than 80 bytes: Gives the number of ...
1 input text line longer than 80 bytes: If you specify a lar...
1 input text line longer than 80 bytes: In combination with ...
3 input text line longer than 80 bytes: Instructs a standalo...
1 input text line longer than 80 bytes: Instructs vgdb to se...
1 input text line longer than 80 bytes: Instructs vgdb to us...
1 input text line longer than 80 bytes: Must be given to bot...
1 input text line longer than 80 bytes: Specifies the PID of...
1 input text line longer than 80 bytes: To give more than on...
1 input text line longer than 80 bytes: argument in the GDB ...
1 input text line longer than 80 bytes: argument is not give...
1 input text line longer than 80 bytes: to a relay vgdb, you...
4 skipping paragraph macro: PP after SH
-.-.
Output from "test-groff -mandoc -t -ww -z vgdb.1": (shortened list)
1 cannot break line
-.-.
Show if docman-to-man created this.
Who is actually creating this man page? Debian or upstream?
Is the generating software out of date?
4:.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
-.-.
Remove space characters (whitespace) at the end of lines.
Use "git apply ... --whitespace=fix" to fix extra space issues, or use
global configuration "core.whitespace".
Number of lines affected is
1
-.-.
Strings longer than 3/4 of a standard line length (80).
Use "\:" to split the string at the end of an output line, for example a
long URLs (web address)
204
\%http://www.valgrind.org/docs/manual/manual-core-adv.html#manual-core-adv.gdbserver
209
\%http://www.valgrind.org/docs/manual/manual-core-adv.html#manual-core-adv.vgdb
214
\%http://www.valgrind.org/docs/manual/manual-core-adv.html#manual-core-adv.valgrind-monitor-commands
-.-.
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.
Mark a final abbreviation point as such by suffixing it with "\&".
38:("Valgrind to GDB") is used as an intermediary between Valgrind and GDB or a
shell\&. It has two usage modes:
48:As a standalone utility, it is used from a shell command line to send
monitor commands to a process running under Valgrind\&. For this usage, the
vgdb OPTION(s) must be followed by the monitor command to send\&. To send more
than one command, separate them with the
61:In combination with GDB "target remote |" command, it is used as the relay
application between GDB and the Valgrind gdbserver\&. For this usage, only
OPTION(s) can be given, but no COMMAND can be given\&.
67:Specifies the PID of the process to which vgdb must connect to\&. This
option is useful in case more than one Valgrind gdbserver can be connected
to\&. If the
79:Instructs vgdb to search for available Valgrind gdbservers for the specified
number of seconds\&. This makes it possible start a vgdb process before
starting the Valgrind gdbserver with which you intend the vgdb to
communicate\&. This option is useful when used in conjunction with a
81:that is unique to the process you want to wait for\&. Also, if you use the
83:argument in the GDB "target remote" command, you must set the GDB
remotetimeout to a value bigger than the \-\-wait argument value\&. See option
90:Gives the number of milliseconds after which vgdb will force the invocation
of gdbserver embedded in Valgrind\&. The default value is 100 milliseconds\&. A
value of 0 disables forced invocation\&. The forced invocation is used when
vgdb is connected to a Valgrind gdbserver, and the Valgrind process has all its
threads blocked in a system call\&.
92:If you specify a large value, you might need to increase the GDB
"remotetimeout" value from its default value of 2 seconds\&. You should ensure
that the timeout (in seconds) is bigger than the
94:value\&. For example, for
112:Instructs a standalone vgdb to exit if the Valgrind gdbserver it is
connected to does not process a command in the specified number of seconds\&.
The default value is to never time out\&.
117:Instructs vgdb to use tcp/ip and listen for GDB on the specified port nr
rather than to use a pipe to communicate with GDB\&. Using tcp/ip allows one to
have GDB running on one computer and debugging a Valgrind process running on
another target computer\&. Example:
151:\fB\-c\fR\&. Example:
176:Instructs a standalone vgdb to show the state of the shared memory used by
the Valgrind gdbserver\&. vgdb will exit after having shown the Valgrind
gdbserver shared memory state\&.
181:Instructs vgdb to produce debugging output\&. Give multiple
183:args to increase the verbosity\&. When giving
-.-.
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 38, length 109
("Valgrind to GDB") is used as an intermediary between Valgrind and GDB or a
shell\&. It has two usage modes:
Line 48, length 265
As a standalone utility, it is used from a shell command line to send monitor
commands to a process running under Valgrind\&. For this usage, the vgdb
OPTION(s) must be followed by the monitor command to send\&. To send more than
one command, separate them with the
Line 61, length 204
In combination with GDB "target remote |" command, it is used as the relay
application between GDB and the Valgrind gdbserver\&. For this usage, only
OPTION(s) can be given, but no COMMAND can be given\&.
Line 67, length 158
Specifies the PID of the process to which vgdb must connect to\&. This option
is useful in case more than one Valgrind gdbserver can be connected to\&. If the
Line 69, length 137
argument is not given and multiple Valgrind gdbserver processes are running,
vgdb will report the list of such processes and then exit\&.
Line 74, length 174
Must be given to both Valgrind and vgdb if you want to change the default
prefix for the FIFOs (named pipes) used for communication between the Valgrind
gdbserver and vgdb\&.
Line 79, length 283
Instructs vgdb to search for available Valgrind gdbservers for the specified
number of seconds\&. This makes it possible start a vgdb process before
starting the Valgrind gdbserver with which you intend the vgdb to
communicate\&. This option is useful when used in conjunction with a
Line 83, length 144
argument in the GDB "target remote" command, you must set the GDB remotetimeout
to a value bigger than the \-\-wait argument value\&. See option
Line 90, length 347
Gives the number of milliseconds after which vgdb will force the invocation of
gdbserver embedded in Valgrind\&. The default value is 100 milliseconds\&. A
value of 0 disables forced invocation\&. The forced invocation is used when
vgdb is connected to a Valgrind gdbserver, and the Valgrind process has all its
threads blocked in a system call\&.
Line 92, length 192
If you specify a large value, you might need to increase the GDB
"remotetimeout" value from its default value of 2 seconds\&. You should ensure
that the timeout (in seconds) is bigger than the
Line 112, length 187
Instructs a standalone vgdb to exit if the Valgrind gdbserver it is connected
to does not process a command in the specified number of seconds\&. The default
value is to never time out\&.
Line 117, length 265
Instructs vgdb to use tcp/ip and listen for GDB on the specified port nr rather
than to use a pipe to communicate with GDB\&. Using tcp/ip allows one to have
GDB running on one computer and debugging a Valgrind process running on another
target computer\&. Example:
Line 150, length 86
To give more than one command to a standalone vgdb, separate the commands by an
option
Line 166, length 107
Instructs a standalone vgdb to report the list of the Valgrind gdbserver
processes running and then exit\&.
Line 176, length 180
Instructs a standalone vgdb to show the state of the shared memory used by the
Valgrind gdbserver\&. vgdb will exit after having shown the Valgrind gdbserver
shared memory state\&.
Line 185, length 144
to a relay vgdb, you better redirect the standard error (stderr) of vgdb to a
file to avoid interaction between GDB and vgdb debugging output\&.
Line 194, length 96
\m[blue]\fBDebugging your program using Valgrind\*(Aqs gdbserver and
GDB\fR\m[]\&\s-2\u[1]\d\s+2
Line 204, length 84
\%http://www.valgrind.org/docs/manual/manual-core-adv.html#manual-core-adv.gdbserver
Line 214, length 100
\%http://www.valgrind.org/docs/manual/manual-core-adv.html#manual-core-adv.valgrind-monitor-commands
-.-.
The name of a man page is typeset in bold and the section in roman
(see man-pages(7)).
189:valgrind(1),
-.-.
Put a parenthetical sentence, phrase on a separate line,
if not part of a code.
See man-pages(7), item "semantic newline".
Not considered in a patch, too many lines.
vgdb.1:74:Must be given to both Valgrind and vgdb if you want to change the
default prefix for the FIFOs (named pipes) used for communication between the
Valgrind gdbserver and vgdb\&.
vgdb.1:92:If you specify a large value, you might need to increase the GDB
"remotetimeout" value from its default value of 2 seconds\&. You should ensure
that the timeout (in seconds) is bigger than the
-.-.
No need for "\&" to be in front of a period (.),
if there is a character in front of it
10:.TH "VGDB" "1" "01/02/2024" "Release 3\&.20\&.0" "vgdb"
38:("Valgrind to GDB") is used as an intermediary between Valgrind and GDB or a
shell\&. It has two usage modes:
48:As a standalone utility, it is used from a shell command line to send
monitor commands to a process running under Valgrind\&. For this usage, the
vgdb OPTION(s) must be followed by the monitor command to send\&. To send more
than one command, separate them with the
50:option\&.
61:In combination with GDB "target remote |" command, it is used as the relay
application between GDB and the Valgrind gdbserver\&. For this usage, only
OPTION(s) can be given, but no COMMAND can be given\&.
67:Specifies the PID of the process to which vgdb must connect to\&. This
option is useful in case more than one Valgrind gdbserver can be connected
to\&. If the
69:argument is not given and multiple Valgrind gdbserver processes are running,
vgdb will report the list of such processes and then exit\&.
74:Must be given to both Valgrind and vgdb if you want to change the default
prefix for the FIFOs (named pipes) used for communication between the Valgrind
gdbserver and vgdb\&.
79:Instructs vgdb to search for available Valgrind gdbservers for the specified
number of seconds\&. This makes it possible start a vgdb process before
starting the Valgrind gdbserver with which you intend the vgdb to
communicate\&. This option is useful when used in conjunction with a
81:that is unique to the process you want to wait for\&. Also, if you use the
83:argument in the GDB "target remote" command, you must set the GDB
remotetimeout to a value bigger than the \-\-wait argument value\&. See option
85:(just below) for an example of setting the remotetimeout value\&.
90:Gives the number of milliseconds after which vgdb will force the invocation
of gdbserver embedded in Valgrind\&. The default value is 100 milliseconds\&. A
value of 0 disables forced invocation\&. The forced invocation is used when
vgdb is connected to a Valgrind gdbserver, and the Valgrind process has all its
threads blocked in a system call\&.
92:If you specify a large value, you might need to increase the GDB
"remotetimeout" value from its default value of 2 seconds\&. You should ensure
that the timeout (in seconds) is bigger than the
94:value\&. For example, for
112:Instructs a standalone vgdb to exit if the Valgrind gdbserver it is
connected to does not process a command in the specified number of seconds\&.
The default value is to never time out\&.
117:Instructs vgdb to use tcp/ip and listen for GDB on the specified port nr
rather than to use a pipe to communicate with GDB\&. Using tcp/ip allows one to
have GDB running on one computer and debugging a Valgrind process running on
another target computer\&. Example:
145:where targetip is the ip address or hostname of the target computer\&.
151:\fB\-c\fR\&. Example:
157:vgdb v\&.set log_output \-c leak_check any
166:Instructs a standalone vgdb to report the list of the Valgrind gdbserver
processes running and then exit\&.
171:Instructs vgdb to add timestamps to vgdb information messages\&.
176:Instructs a standalone vgdb to show the state of the shared memory used by
the Valgrind gdbserver\&. vgdb will exit after having shown the Valgrind
gdbserver shared memory state\&.
181:Instructs vgdb to produce debugging output\&. Give multiple
183:args to increase the verbosity\&. When giving
185:to a relay vgdb, you better redirect the standard error (stderr) of vgdb to
a file to avoid interaction between GDB and vgdb debugging output\&.
190:$INSTALL/share/doc/valgrind/html/index\&.html
192:http://www\&.valgrind\&.org/docs/manual/index\&.html,
196:\m[blue]\fBValgrind monitor commands\fR\m[]\&\s-2\u[3]\d\s+2\&.
199:Philippe Waroquiers\&.
-.-.
Use ".na" (no adjustment) instead of ".ad l" and then ".ad" to begin the
same adjustment again as before
26:.ad l
-.-.
Output from "test-groff -mandoc -t -K utf8 -rF0 -rHY=0 -rCHECKSTYLE=10 -ww -z
":
troff:<stdin>:214: warning: [page 2, 8.4i]: cannot break line
Output from "test-nroff -mandoc -t -K utf8 -rF0 -rHY=0 -rCHECKSTYLE=10 -ww -z
":
troff:<stdin>:204: warning [page 2, line 54]: cannot break line
troff:<stdin>:209: warning [page 2, line 57]: cannot break line
troff:<stdin>:214: warning [page 2, line 60]: cannot break line
-.-.
Additionally (general):
FSF office address update. See
https://lists.gnu.org/archive/html/bug-gnulib/2024-09/msg00004.html
-.-
Abbreviations get a '\&' added after their final full stop (.) to mark them
as such and not as an end of a sentence.
There is no need to add a '\&' before a full stop (.) if it has a character
before it!
'\&' is only needed at the beginning of a line, if it otherwise starts with
a control character "." or "'".
Table headers, that are wider than any data in the corresponding column,
do not need to be centered, so left adjustment is sufficient.
The default value for kerning (.kern) and ligature (.lg) is one (1),
so for n-mode (nroff) it should be set to zero (0) to avoid the processing
of unnecessary code.
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
-.-
Any "autogenerator" should check its products with the above mentioned
'groff', 'mandoc', and additionally with 'nroff ...'.
It should also check its input files for too long (> 80) lines.
This is just a simple quality control measure.
The "autogenerator" may have to be corrected to get a better man page,
the source file may, and any additional file may.
Common defects:
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.
Line length should thus be reduced.
The script "reportbug" uses 'quoted-printable' encoding when a line is
longer than 1024 characters in an 'ascii' file.
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 from '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)
-.-
