Re: managing tagged paragraphs (was: [PATCH 2/2] ioctl_pagemap_scan: add page for pagemap_scan IOCTL)

[Alejandro Colomar <alx@kernel.org>]

[-- Attachment #1: Type: text/plain, Size: 3293 bytes --]

Hi Branden,

On Sat, Oct 28, 2023 at 08:07:14AM -0500, G. Branden Robinson wrote:
> Hi Alex,
> 
> At 2023-10-24T12:40:55+0200, Alejandro Colomar wrote:
> > On Mon, Oct 23, 2023 at 09:48:02PM -0500, G. Branden Robinson wrote:
> > > If one has learned device-independent troff's output language (see
> > > groff_out(5)), one can see that the space after the comma is simply
> > > discarded.
> > 
> > Hmm, I might use .grout for the similarity with that manual page name.
> > ;)
> 
> Yes, I like the terms "trout" and "grout" for the original Kernighan
> device-independent troff format and GNU's extended version of it,
> respectively.  But I have met few other people who do.  :)
> 
> > > Good, yes.  I see what you're talking about.  We can now use
> > > ioctl_pagemap_scan(2) as a site for our horrific medical experiments.
> > > 3:-)
> > > 
> > > I think this is an instance of the tricky little constraint problem
> > > Michael Kerrisk and I discussed almost 3 years ago.
> > > 
> > > https://lore.kernel.org/linux-man/a79fc055-c7ab-1793-04eb-eb4f678e5035@gmail.com/
> > 
> > Yep, and like Michael, I also dislike the line break.  Is there any
> > chance that we could make it not break after TP so that it (RS) would
> > be usable there?
> 
> The exhibit was roughly this (based on ioctl_pageman_scan(2)):
> 
> .TH foo 2 2023-10-28 "groff test suite"
> .TP
> .B vec
> The address of
> .I page_region
> array for output.
> .IP
> .in +4n
> .EX
> struct page_region {
>     __u64  start;
>     __u64  end;
>     __u64  categories;
> };
> .EE
> .in
> Other text.
> 
> This already formats without a line break after `TP`.

I meant to ask if modifying RS's behavior to not break after TP was
something you'd consider viable.

[...]

> > Yup, but anyone new to man(7) will likely be put off by that page.
> > 
> > $ man groff_man_style | wc -l
> > 1439
> 
> Because we don't know your terminal width, that number doesn't
> communicate a lot.

Huh!  I thought I had used the standard width, but it seems I didn't.

$ man groff_man_style | wc
   1460   10154   81450

Even weirder is that it's not 89 either, which is the size of the
terminal when I use half screen.  And to crash my brain, I can't even
reproduce it with any terminal size:

$ MANWIDTH=82 man groff_man_style | wc
   1442   10152   81154
$ MANWIDTH=83 man groff_man_style | wc
   1435   10156   80990

> But it is just shy of 20k words in groff 1.23.0.
> The "reference" version, groff_man(7), is half as long.

$ groff --version
GNU groff version 1.23.0.497-e982

> 
> > If you're just contributing a few paragraphs, you may prefer to learn
> > by trial and error (which is a perfectly valid approach, and one that
> > I prefer).
> 
> Experimentation is certainly superior to guessing (or assuming).
> 
> > Only when I wanted to learn the more obscure details, or quote
> > to someone else, I've read that page (and I haven't read it entirely
> > yet!).
> 
> I look forward to your critique from a position of practical experience.

Me too.  I remember my promise to review it; I'm just very slow; even
slower than sloppy recuriters.

Cheers,
Alex

> 
> Regards,
> Branden



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

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