Re: [PATCH 1/9] ldconfig.8: Fix markup nits

Alejandro Colomar <alx.manpages@xxxxxxxxx> · Wed, 4 Jan 2023 19:41:51 +0100

Hi Branden,

On 1/4/23 16:55, G. Branden Robinson wrote:
Hi Alex,

At 2023-01-04T13:26:33+0100, Alejandro Colomar wrote:
This patch looks good to me.  However, I didn't apply it, since I have
a few comments below.

Ok.  V3, here we come!

   .SH NAME
   ldconfig \- configure dynamic linker run-time bindings
   .SH SYNOPSIS

We should wrap this in .nf/.fi

That will have a cost.  It will mean using a lot of \c escape sequences
to connect the output lines.

The existing synopsis fits within 74 output columns on a terminal.

Do you think it's worth it?

But, it we don't use it, if someone uses a smaller terminal, there might appear 
our beloved hyphens breaking a word...

Although maybe this goes better in the style patch, since it's a
formatting fix.

I can shift it.

I will suggest again that I believe \% should be the default in manual
pages. Count how many times you want to break highlighted stuff vs how
many times you want to not break such stuff.

I don't see good prospects of this for the same reason that I was able
to talk Ingo Schwarze out of keeping section headings in shouting
capitals.  It's a matter of preference, but one preference means
discarding information irrevocably in the source document, and the other
means that the information is present but unused.

Is there anything that "reverts" \%?  So that if it were the default, we could 
use \anti-% to say "groff, you might break this word"?

groff man(7) _has_ a mechanism for this, and has since groff 1.19
(2003).  It's the `HY` register.  People can put this in their man.local
files (on Debian-based systems, that's in /etc/groff).

.nr HY 0

I know, but I don't think we should write manual pages in a way that forces 
distributors to use such a thing.  Either the pages are written plagued with \%, 
and the distros don't need to use .HY, or we write pages lazily so that distros 
need to fix the hyphenation.  But writing the pages lazily and having 
distributors ignore it would result in suboptimal pages for our readers.

Colin Watson's man-db man(1) also has a feature to suppress hyphenation,
using a hack; it's not pretty but it works even on other *roff
formatters.

Does that disable hyphenation for macros, or for the entire document?  I only 
want to disable it in highlighting macros.

I don't insist that people keep hyphenation enabled, but assuming that
no one will do so will keep us from putting worthwhile information in
our man pages.

If you dread the tedium of adding \% escape sequences to "keywords" all
over the place, I don't blame you.  This is one reason I proposed my
most ambitious man(7) extension yet, a two-macro semantic tag mechanism.

https://marc.info/?l=linux-man&m=165868366126909&w=2

I still don't know what to think about that.

As with the new `MR` in groff 1.23, you could then suppress hyphenation
in the internal macros that wrap "tagged" keywords.

-.\" FIXME glibc 2.7 added -i

And this is why comments are harmful.  I fint it rather uncommon for
comments to be up-to-date with the code :P

I generally find FIXME comments useful.  It's a happy day when I find
one that's already been addressed.  :)

:)

I had fun with one last month:

<https://github.com/shadow-maint/shadow/commit/428a2078b6c435f1780ec8f381033e7bd937d29e>

I'll quote it here:

"XXX - quick hack, should disappear before anyone notices :)."

Of course, the quick hack never disappeared after Oct 7, 2007, when it was 
written in stone.

I have plans to get rid of it, but other dinosaurs and magic creatures keep 
getting in my way.

And another one (this one I got rid of it):

<https://github.com/shadow-maint/shadow/commit/6b6e005ce1cc4a5e4fc7fc40a52f2ed229f54b5b>

"XXX - is the above ok or should it be <time.h> on ultrix?"

Regards,
Branden

Cheers,

Alex

--
<http://www.alejandro-colomar.es/>
Attachment:
OpenPGP_signature

Description: OpenPGP digital signature