On Mon, May 28, 2018 at 02:47:40AM +0200, Guillem Jover wrote: > 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. :) ] > I usually only test for warnings from "groff". If there are some, I run the whole testing script on the man pages, if there are not too many. Otherwise just patches to eliminate the warnings.
> On Thu, 2018-05-24 at 22:34:36 +0000, Bjarni Ingi Gislason wrote: >[...] > > Protect an ellipsis on both sides, '\&...\&'. > > Why do we need this? > This is to make the same "form" for an ellipsis everywhere (only one version of an ellipsis) The best, simplest way is to define a string, for example the following is usually used: .de EL \&.\|.\|.\& The first '\&' is for the case the ellipsis starts on the beginning of a line. The second to neutralize the "end-of-sentence" meaning of the period. > > Protect a full stop, exclamation mark, that is not an end of sentence. > > Idem? > I do not understand this. > > 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. > People write "foo..." because 1) The first ones did not know better 2) Other saw this and copied it. Read about ellipsis in relation to the text before it. foo... means missing letters, foo ... means missing words (or more types of text "foo" are possible)) > > 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. > My patches changes this only if there are a few cases. Some prefer the escapes, but I find it harder to read and understand than the macros. And the italic corrections are too often missing. > > 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. > Man pages use two spaces, that is the legacy form. To avoid controversies of style a new line is the best choice; also better for patches. I only split a line if there is only one space character between sentences and there are not many cases. Sometimes I only add the second character. I find it better to fix this when discovered, than waste somebody's time later. > > ##### > > > > 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. > The best way is to drop these Latin abbreviations and use the English words; there is no need to shorten text nowadays. So I will change common abbreviations to words in the future. -- Bjarni I. Gislason
