Re: CVS commit: src/share/man/man5

[Valery Ushakov <uwe%stderr.spb.ru@localhost>]

On Sun, Jun 11, 2023 at 22:19:42 +1000, Luke Mewburn wrote:

>   | I'm not sure what do you mean.  The difference between .Ss and .Sh is
>   | only the indent:
> 
> Ahh, you're right, I misspoke. Tired brain when working on the commit.
> 
> IMHO, they both suffer from lack of blank line there, where personally I
> would prefer the blank line, especially before a list, and especially
> for .Ss because its indent is only 2 in from the main paragraph. But I'm
> not considering an mdoc change for that any time soon.
[...]
> For me, having a para before it and the outdented heading makes the BSDOBJDIR
> "pop" more in a quick eyeball scan, plus easier section searching.
> 
> YMMV.

I guess my own preference is half-way, with .Ss, but with the extra
text you added to prevent the .Bl from blending in with the heading.
.Sh ALL CAPS HEADING pokes out to the left margin and has a bit too
much visual gravity, and so, IMHO, also distracts a bit from the
all-caps variables in the list.  But as there are only three such
headings, it's not really that important (if there were more, my
preference towards .Ss Normal Case would be much stronger).  But
that's not my yak to shave... :)

I was just reacting to that confusing statement in the commit message.
mdoc has enough urban legends and cargo cult around it...


> My goal is to get the mk.conf(5) up to date and correct, and more usable.
> I intend to remove the duplication in BUILDING and bsd.README
> and refer back to mk.conf(5) to avoid the copypasta, with some updated
> boilerplate in BUILDING to describe how to find the referenced manual pages
> within BUILDING if you're not on an NetBSD system.

That would be very nice, thanks.


-uwe