Hi Alex, On 11/15/20 3:07 PM, Alejandro Colomar wrote: > Reported-by: G. Branden Robinson <g.branden.robinson@xxxxxxxxx> > Signed-off-by: Alejandro Colomar <alx.manpages@xxxxxxxxx> > --- > > Hi Michael, > > As we discussed, > I removed _every_ appearance of [.nf] and [.fi] from the pages. Ooops -- I don't quite recall the details of that discussion. But, this is not so simple. > There were some unmatched [.nf] appearances, > which I manually matched with [.EE]. In cases like this, it would probably be better to split this out into separate patches with a small preparatory patch that fixes the unbalanced .nf macros, followed by the bigger patch, but even so, it's not so simple... .nf/.fi appears in two places generally: (1) Inside the SYNOPSIS (many pages) (2) Elsewhere in the page (fewer pages) Probably, most (all?) cases in the second category should really be .EX/.EE. But in the SYNOPSIS, .nf/.fi is used inconsistently. The majority of pages use it, but a substantial minority (200+ pages) do not (e.g., chdir.2). (That inconsistency is a mess from history.) Why does this matter? Well, theoretically at least, pages might be rendered to something other than the terminal. I care at least a little bit about PDF rendering[1], and the inconsistency means that converting .nf/fi to .EX/.EE will produce a very different appearance in pages that currently do/don't use .nf/.fi in the SYNOPSIS. What to do? I'm not sure. When I look at the PDF renderings, using simply .nf/.fi (or nothing at all) in the SYNOPSIS produces a variable-width-font output that is visually appealing for the function prototypes. Switching to .EX/.EE, the result is not unpleasant, but I'm not sure I prefer it (in a PDF rendering).[2] As a first step, all pages should probably be using .nf/.fi in the SYNOPSIS. But, that's probably a painful manual edit. I've been manually fixing pages over the years, but many are not fixed yet. > That's the reason there are a few more insertions than deletions. I manually fixed chroot.2, memfd_create.2, and tailq.3. Were there any others? > Woah, 439 KiB of a patch... :-) > I tested a few of the pages to see > if anything changed in the rendered output. > Apparently, no. > I hope that holds throughout all of the modified pages. > > BTW, I had to script a bit to get the subject of the commit > (as you can probably guess I didn't write that myself :p) > Would you want to add that to 'scripts/'? I myself have a small script based around the output of git status | grep 'modified:' | awk '{print $NF}' How do you do it? Thanks, Michael [1] function pdfmanq { man -Tps -l $1 > /tmp/$(basename $1).$$.ps ps2pdf /tmp/$(basename $1).$$.ps $1.pdf } function pdfman { pdfmanq $1 evince $1.pdf # Or whatever PDF viewer you use } # pdfman somepage.n [2] But I am perhaps old school on this point. -- Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Linux/UNIX System Programming Training: http://man7.org/training/