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

[Alejandro Colomar <alx.manpages@gmail.com>]

[-- Attachment #1.1: Type: text/plain, Size: 4099 bytes --]

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 #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]