Re: [PATCH] mctp.7: Add man page for Linux MCTP support

["Alejandro Colomar (man-pages)" <alx.manpages@gmail.com>]

Hi Branden,

On 10/18/21 7:57 AM, G. Branden Robinson wrote:
> Hi Jeremy,
> 
> At 2021-10-18T13:05:25+0800, Jeremy Kerr wrote:
>>>> +Addressing data is passed in socket system calls through
>>>> +.B struct sockaddr\_mctp
>>>
>>> That escape is unnecessary.  Did you see it in another page perhaps?
>>
>> I thought I'd seen some odd line-breaks at the underscore, but can't
>> replicate that now. Will remove.
> 
> My groff experiments don't reveal _ or \_ as being permissible
> break points[1].  However, the structure tag _could_ break like this:
> 
> sock‐addr_mctp
> 
> In other words (if my UTF-8 gets mangled), after "sock".
> 
> To prevent that, you can prefix the word with the hyphenation control
> escape sequence, "\%".  This escape sequence is extremely portable; it
> dates back to 1970s AT&T troff.

Hmm, this is one of the few points we disagree, it seems :)

As I said previously, I think this uglyfies code too much, for something 
that I think should be default (it is rarer to want break points at 
highlighted words than not wanting them).  But, to try to confirm my 
thoughts, I'll accept using this in the man-pages and see what happens 
(maybe some day, a winter day it shall be, you'll wake up and see a cold 
commit reaping them all :p)

> 
> Further, if you wanted to prevent breaking between the "struct" keyword
> and the structure tag, you could use a nonbreaking adjustable space
> escape sequence, "\~".  While this was a groff innovation (about 30
> years ago), it's been adopted by Heirloom Doctools troff and mandoc(1),
> so it's pretty portable to systems likely to install the Linux
> man-pages.

Ah yes, I should have spotted that one :p

> 
> So we might write
> 
> .B struct\~\%sockaddr_mctp

Okay.

> 
> for instance in running text (that is, in sentences).  (When filling is
> off, as in code examples and the synopses of most pages documenting C
> interfaces, neither of these escape sequences is necessary; unfilled
> lines are neither automatically hyphenated nor adjusted.)
> 
> Just a typographical FYI.  I know these issues sometimes frustrate
> people.
> 
> Regards, > Branden

Thanks!

Alex

> 
> [1] I'm using groff's defaults.  It's possible to change the groff
>      "hyphenation code" of any character, but few do so.
> 


-- 
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/