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

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

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

Hi Branden,

On 1/4/23 21:59, G. Branden Robinson wrote:
> Hi Alex,
> 
> At 2023-01-04T21:15:00+0100, Alejandro Colomar wrote:
>>> That's true.  But what is _not_ true is that you don't have a
>>> minimum expected terminal width.  You do, you just might not know
>>> what it is and it may not even have been consciously chosen.
>>
>> I haven't consciously chosen it, but I often use 66-col terminals,
>> especially when I plan to paste text into an email.
> 
> Well, by "you" I mean in your capacity as Linux man-pages maintainer.
> 
> There is some threshold of terminal width in the corpus of pages below
> which things start to look really horrible.
> 
> Maybe you'd like my shell wrapper for man(1).
> 
>      # View a man page but report all warnings.
>      man () {
>          if command man "$@"
>          then
>              command man --warnings=w "$@" >/dev/null
>          fi
>      }
> 
> It shows me the formatter's warnings _after_ the page is rendered.

Hmmm, yes, I'll get that one!

[...]

>> I mean something like \X\%foobar, so that the \X "cancels" the \%.
>> Not manually inserting break points.  So, imagining a world in which
>> hyphenation was disabled _only_ within font-selection macros, I could
>> specify that a word is fine to be hyphenated like this:
>>
>> .B \Xidontcareifthisishyphenated
> 
> Hmm, no, there is no *roff escape sequence for "apply automatic
> hyphenation to the following word".
> 
> But your hypothetical is already a counterfactual.  Macros like .B
> _already_ don't disable hyphenation.  So it seems to me like you're
> proposing second-order machinery to get yourself out of the bind you're
> creating with your first-order demand to make the font macros disable
> hyphenation.
> 
> It really seems better to me to leave the font macros alone and have
> a semantic tagging facility for those things you really don't want
> hyphenated.
> 
> Or, proceed as the groff man pages have to date, stick to the font
> selection macros as they are, and use \% with them.
> 
> Most of the 94 printable Basic Latin characters already have meaning
> as *roff escape sequences when preceded by an escape character.  The
> scarce name space that remains must be occupied only with great
> consideration.  Dave Kemper and I have kicked around ideas for an
> "extension" character for escape sequences to surmount this problem.  \<
> is available, and despite giving me nightmare memories of HTML, it might
> be the best choice among what remains.[1]
> 
>>> Like changes in lettercase, this is _information_.
>>
>> I don't argue against that, but if there was a way to return that
>> information explicitly, we wouldn't be loosing it.
> 
> As noted above, I think a good way to achieve that is by not discarding
> it such that it needs recovery later.
> 
>> Oh, I do complain a lot; however, I don't express it too much in the
>> form of bug reports, since I don't believe it's the fault of the
>> writer, but rather lack of support from groff(1).
> 
> I don't think groff is missing support for anything you want here; we
> have a disagreement over the design of the man(7) package.

Yes, that might be another way to phrase it; probably a more accurate one.

So, you defend hyphenation within .I and .B because they are not semantic macros.

But, of course, by presenting a word differently, you're implying that it's more 
important than the surrounding words.  And since we try to avoid overuse of 
presentational macros, this importance should be somewhat consistent.

If a word is more important than the others, it is very likely that readers will 
try to search for it more often (for which hyphenation is a big problem in less(1)).

It also makes sense to not hyphenate it so that it stands more readable.

Isn't it an exception when you don't mind hyphenating a B or I word, rather than 
a rule?

Do you have any statistics?  Could you get an approximate ratio of words where 
you don't mind at all hyphenating, compared to those where you don't want 
hyphenation?

Something like of course restricted to B or I words):

	                       words that can hyphenate
         -----------------------------------------------------------------------
         words that can't hyphenate  +  w. that use \%  +  w. that can hyphenate

Could you get that from groff's pages?  I expect those will be the most 
consistent ones in use of \%.

I expect that to be less than 0.1; probably even below 0.01.  Isn't that a good 
hint that it would be better to flip the default there?

[...]

>>
>> My problem is not about pasting text.  That's very minor.  My problem
>> is finding text.
> 
> Yes, I've seen many people complain about this, justifiably, over the
> years.  When people leave hyphenation enabled and try full-text searches
> of man pages, often inside less(1), they get frustrated by the broken
> words.
> 

Yeah, for full-text searches, I cd(1) into the man-pages dir and search in the 
source :).

[...]

> 
> I have only two recommendations.
> 
> 1.  Disable hyphenation in your man.local; or

I try to avoid custom configuration files.  That has several advantages; one of 
them in the case of manual pages is noticing when inexpert users will find them 
less useful than I will.

> 2.  Back my play for semantic tagging in man(7).  ;-)

:)

> 
>>> I think marking break points, hyphenated and otherwise (as with
>>> URLs), is the opposite of laziness.  It is a level of fastidiousness
>>> I don't actually expect of many man(7) writers apart from myself.
>>
>> I would want to use \:.  What I want is a tool which re-enables the
>> default hyphenation points after they have been cancelled.
> 
> I submit again: if you don't cancel them in the first place, they don't
> have to be reconstructed.
> 
>> I would.  I wouldn't be able to count how many times I've tried to
>> search for such a keyword, and it was hyphenated.
> 
> Semantic tags would solve this problem.
> 
> Regards,
> Branden
> 
> [1] What's available?
> 
>      \+ \1 \2 \3 \4 \5 \6 \7 \8 \9 \; \< \= \> \@
>      \G \i \I \j \J \P \T \U \W \y \]

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

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]