Re: [PATCH bpf-next v3] bpf: Fix a few typos in BPF helpers documentation

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

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

Hi Quentin,

On 8/26/22 11:44, Quentin Monnet wrote:
> On 25/08/2022 23:12, Alejandro Colomar wrote:
>> Hi Quentin,
>>
> 
>>> - *        ctx. Providing an *len_diff* adjustment that is larger than
>>> the
>>
>> I just noticed:  groff(1) uses double spaces after an end-of-sentence
>> period.  Otherwise, it is understood as something like initials, or an
>> abbreviature, and it causes some issues.  Please check the whole
>> document, as I've seen a mix of styles.
>>
>> Search for something like '.\. [^ ]'
> 
> This is a strange restriction in my opinion, but I can look into this as
> a follow-up. I've not noticed issues with the rendered page so far, out
> of curiosity what issues are we talking about?

It's not so visible, and I'm not a groff(1) expert, so maybe there are 
more issues than the ones I know, but I'll explain it as I understand it:

For groff's output, there are two kinds of spaces: interword and 
intersentence spaces.  Interword space is normally a single character in 
monospaced fonts.  Intersentence is also a single space by default in 
monospace fonts, but it is not substituting interword space, but rather 
adding to it, so effectively the intersentence separation is two spaces 
in a monospaced font.  That can be configured, and one can for example 
ask their intersentence space to be 2 chars, and therefore have an 
intersentence effective sepparation of 3 chars.

In PDF output, the difference may be also noticeable slightly differently.

I prepared a simple file that will show you how it can make sentences 
much more readable, even if the theoretical difference might not be 
noticeable at first glance to the untrained eye:

$ cat sp.man
.TH spaces 7 today experiments
.SH correct spacing
Hello world!  Today is Friday.  This are extra words to fill.
And even more words.
.SH incorrect spacing
Hello world! Today is Monday. This are extra words to fill. And even 
more words.
$ man -P cat ./sp.man
spaces(7)          Miscellaneous Information Manual          spaces(7)

correct spacing
        Hello  world!   Today is Friday.  This are extra words to fill.
        And even more words.

incorrect spacing
        Hello world! Today is Monday. This are extra words to fill. And
        even more words.

experiments                      today                       spaces(7)



Notice how the first one is much more nicely rendered.  I rendered it in 
a 72-col terminal because my mailer would wrap at that boundary anyway. 
You can render the file at 80 columns and see a different rendering, 
where it is even bigger the difference in favor of the correctly written 
one.


> 
> Also before that, it would be good to sync and see what other formatting
> elements need be addressed on the page, so we can fix them in a batch
> rather than submitting them one after the other like we're doing.

Sure!  It'll take some time from my side, but I'll try to come up with a 
list of issues in that page.

> 
> Quentin


Cheers,

Alex

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

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