Hi! [ I've seen you have filed a different bug report for each man page you have checked/reviewed, but that might mean tons of bugs for lots of pages. Probably better to reuse one of this for further fixes, or this might get a bit out of control. :) ]
On Thu, 2018-05-24 at 22:34:36 +0000, Bjarni Ingi Gislason wrote: > Package: dpkg > Version: 1.19.0.5+b1 > Severity: minor > Tags: patch > Warnings from "groff": > > <dpkg-deb.1>:133 (macro IR): only 1 argument, but more are expected > <dpkg-deb.1>:210 (macro BR): only 1 argument, but more are expected > <dpkg-deb.1>:279 (macro BR): only 1 argument, but more are expected > > Output is from: test-groff -b -e -mandoc -T utf8 -rF0 -t -w w -z > > ["test-groff" is a developmental version of "groff"] Ah, nice stuff. Thanks for trying to cleanup the markup, it's always appreciated. :) > ### > > Summary: Some of these I do not agree with, and in addition might even make a possible conversion to POD (<https://git.hadrons.org/cgit/debian/dpkg/dpkg.git/log/?h=pu/man-switch-to-pod-trial>) I've been pondering about, more difficult. Some others might actually make it easier, and some might be irrelevant, as pod2man does unfortunately not care (such as the - and \- distinction). > Remove extra quotation mark ("). Good. > Use '\(en', not '\-' to denote a range of numbers. Ok I guess, with POD we could encode it with E<>, or ignore it. > Protect an ellipsis on both sides, '\&...\&'. Why do we need this? > Protect a full stop, exclamation mark, that is not an end of sentence. Idem? > Know the difference between "abc..." and "abc ...". This one seems wrong. In the cases I've seen changed, it applies to command-line argument description, where "foo..." has a distinctive meaning of repetition, so splitting it seems wrong. > Print a reverse solidus (\) with '\e', not '\\'. Ok I guess. Although I think in POD we'd just use \\. > Use a macro 'I', 'IX', or 'XI' instead of escape requests, where the > italic correction is too often missing in the text. If this was being writen from scratch, then I guess, but given the current text I think it makes little sense, and it makes the conversion uglier. So I'd rather avoid it. Also if we wanted better markup I'd rather consider switching from man to mdoc macros. > Begin each sentence on a new line (or use two spaces between them, > which is not recommended as the text contains formatting commands). > See man-pages(7) [package "manpages"] and "info groff". This is a somewhat controversial style dispute in general, and I find two spaces uglier. :) In addition vim seems to agree, and prints red on ". " with syntax highlighting. > ##### > > Test nr. 40: > > Add a comma after "e.g." and "i.e." (man-pages(7) [package "manpages"]). > > 251:members (i.e. \fBcontrol.tar\fP and \fBdata.tar\fP; since dpkg 1.17.6). This probably needs to be done globally over the entire git repo's contents. Thanks, Guillem
