Hi Alex,
>> .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.
>
> Hmm, didn't think about those.
> I agree that it may be nicer with .nf/.fi for the SYNOPSIS
> from what you say
> (I'll try it myself).
> I'll see if I can come up with a script that
> keeps .nf/.fi in the SYNOPSIS
> and changes everything else.
>
> For the rest, you would change to .EX/.EE, right?
I took a closer look [1], and it looks like only a minority
of these should be changed.
There are some that probably should be fixed (e.g., EXAMPLES)
to use .EX/.EE. I just fixed some of those.
But in other cases (e.g., perfmonctl.2, fenv.3), there are
inline function prototypes (as in SYNOPSIS) or some cases
where .nf/.fi is really being used to stop line filling.
Sometimes, in the latter case, .nf/.fi is being used to do
a "poor man's" table (e.g., see ioctl_tty.2); those should
be converted to real tables, since the "poor man's" version
does not render well in PDF (e.g., ioctl_tty.2). I just
fixed a few of the worst cases.
Of the remaining uses of .nf/.fi, I didn't notice any cases that
really bothered me. Maybe at this point it's a case of
"move along, there's nothing to see here" :-).
>>> 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?
>
> No... probably.
> I checked that the number of .nf+.fi was even for a single file,
> and that the total number of .nf equaled
> the total number of .fi in a directory
> (it was too much work to check every file).
I just checked in a script that I have for the task:
check_unbalanced_macros.sh
>>> 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?
>
> I just sent a patch before reading this email.
> Mine is a bit more reliable I think,
> but maybe you can still improve it :)
Thanks. If you could just resend with copyright and license,
I'll check it in.
Thanks,
Michael
[1]
for p in man?/*.[1-8]; do \
if cat $p | sed '/SH SYNOP/,/^\.SH/d' | grep -q '\.nf'; then echo $p; fi; \
done
--
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
