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
