Bug#1037552: manpages: bad code
Package: docbook-xsl
Version: 1.79.2+dfsg-2
Severity: normal
Dear Maintainer,
here are some remarks about the creation of man pages with an example
from "valgrind.1".
####
Examples of bad formatting codes in the output from
DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
for a man page.
Example file is valgrind.1
Output from "mandoc -T lint valgrind.1"
mandoc: valgrind.1:36:2: WARNING: skipping paragraph macro: PP after SH
mandoc: valgrind.1:38:304: STYLE: input text line longer than 80 bytes: is a flexible progra...
and more.
#######
Lines with \c before lines that contain only '\}'.
Here the '\c' is redundant.
The Code block
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
should be in a macro or this should be enough
.IP \(bu 3m\" adjust width of the indent
#####
Remove space characters at the end of lines.
Use "git apply ... --whitespace=fix" to fix extra space issues, or use
global configuration "core.whitespace".
838:==15380==
842:==15380==
863:==15377==
868:==15377==
890:==15363==
913:==15370==
#####
Mark a full stop (.) with "\&",
if it does not mean an end of a sentence,
that is use ".\&".
This is a preventive action,
the paragraph could be reshaped, e.g., after changes.
When typing, one does not always notice when the line wraps after the
period.
There are too many examples of input lines in manuals,
that end with an abbreviation point.
This marking is robust, and independent of the position on the line.
It corresponds to "\ " in TeX, and to "@:" in Texinfo.
DO NOT PUT "\&" randomly in front of a full stop). Only when the full
stop is
1) at the start of a line
2) after a space character
that is
sed -e 's/^\./\\\&./' -e '/ \./ \\\&./g'
Similar applies to the single quote ('),
which is a control character in front of a command (request).
52:\fItoolname\fR, e\&.g\&. memcheck, cachegrind, callgrind, helgrind, drd, massif, dhat, lackey, none, exp\-bbv, etc\&.
102:\fB\-\-trace\-children\-skip=patt1,patt2,\&.\&.\&. \fR
#####
Use a font macro (.I, .B) for a font change if possible.
See man-pages(7).
52:\fItoolname\fR, e\&.g\&. memcheck, cachegrind, callgrind, helgrind, drd, massif, dhat, lackey, none, exp\-bbv, etc\&.
88:\fIexec\fR
92:\fIfork\fR
94:\fIfork\fR
96:\fIfork\fR
98:\fIexec\fR
123:\fIfork\fR
125:\fI\-\-trace\-children=\fR\&. Use of this option is also strongly recommended if you are requesting XML output (\fI\-\-xml=yes\fR), since otherwise the XML from child and parent may become mixed up, which usually makes it useless\&.
218:\fIv\&.info open_fds\fR\&. Along with each file descriptor is printed a stack backtrace of where the file was opened and any details relating to the file descriptor such as the file name or socket details\&. Use
255:\fIFOO\fR\&. If the
#####
Use the word "(in)valid" instead of "(il)legal" if not related to legal
matters.
See "www.gnu.org/prep/standards".
Think about translations into other languages!
valgrind.1:442:Enable/disable printing of illegal instruction diagnostics\&. Enabled by default, but defaults to disabled when
valgrind.1:446:When enabled, a warning message will be printed, along with some diagnostics, whenever an instruction is encountered that Valgrind cannot decode or translate, before the program is given a SIGILL signal\&. Often an illegal instruction indicates a bug in the program or missing support for the particular instruction in Valgrind\&. But some programs do deliberately try to execute an instruction that might be missing and trap the SIGILL signal to detect processor features\&. Using this flag makes it possible to avoid the diagnostic output that you would otherwise get in such cases\&.
valgrind.1:1925:\fIyes\fR, such loads do not produce an address error\&. Instead, loaded bytes originating from illegal addresses are marked as uninitialised, and those corresponding to legal addresses are handled in the normal way\&.
valgrind.1:1928:\fIno\fR, loads from partially invalid addresses are treated the same as loads from completely invalid addresses: an illegal\-address error is issued, and the resulting bytes are marked as initialised\&.
#####
Add a hair space (\^) around "|" to increase readability
85:\fB\-\-trace\-children=<yes|no> [default: no] \fR
120:\fB\-\-child\-silent\-after\-fork=<yes|no> [default: no] \fR
128:\fB\-\-vgdb=<no|yes|full> [default: yes] \fR
215:\fB\-\-track\-fds=<yes|no|all> [default: no] \fR
#####
Wrong distance between sentences.
APPLIES ALSO TO THE SOURCE FILE.
a) Separate the sentences and subordinate clauses; each begins on a new
line. See man-pages(7) and "info groff".
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.
The amount of space between sentences in the output can then be
controlled with the ".ss" request.
38:is a flexible program for debugging and profiling Linux executables\&. It consists of a core, which provides a synthetic CPU in software, and a series of debugging and profiling tools\&. The architecture is modular, so that new tools can be created easily and without disturbing the existing structure\&.
40:Some of the options described below work with all Valgrind tools, and some only work with a few or one\&. The section MEMCHECK OPTIONS and those below it describe tool\-specific options\&.
42:This manual page covers only basic usage and options\&. For more comprehensive information, please see the HTML documentation on your system:
52:\fItoolname\fR, e\&.g\&. memcheck, cachegrind, callgrind, helgrind, drd, massif, dhat, lackey, none, exp\-bbv, etc\&.
60:Show help for all options, both for the core and for the selected tool\&. If the option is repeated it is equivalent to giving
72:Show the version number of the Valgrind core\&. Tools can have their own version numbers\&. There is a scheme in place to ensure that tools only execute when the core version is one they are known to work with\&. This was done to minimise the chances of strange problems arising from tool\-vs\-core version incompatibilities\&.
77:Run silently, and only print error messages\&. Useful if you are running regression tests or have some other automated test machinery\&.
#####
-- System Information:
Debian Release: 12.0
APT prefers testing
APT policy: (500, 'testing')
Architecture: amd64 (x86_64)
Kernel: Linux 6.1.27-1 (SMP w/2 CPU threads; PREEMPT)
Kernel taint flags: TAINT_WARN
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 docbook-xsl depends on:
ii xml-core 0.18+nmu1
Versions of packages docbook-xsl recommends:
ii docbook-xml 4.5-12
Versions of packages docbook-xsl suggests:
pn dbtoepub <none>
pn docbook-xsl-doc-html | docbook-xsl-doc-pdf | docbook-xsl-doc-text | <none>
docbook-xsl-doc
pn docbook-xsl-saxon <none>
pn fop <none>
pn libsaxon-java <none>
pn libxalan2-java <none>
pn libxslthl-java <none>
pn xalan <none>
-- no debconf information
Reply to: