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

["G. Branden Robinson" <g.branden.robinson@gmail.com>]

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

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`.

$ nroff -man -Tascii ATTIC/vec.man
foo(2)                        System Calls Manual                       foo(2)

       vec    The address of page_region array for output.

                  struct page_region {
                      __u64  start;
                      __u64  end;
                      __u64  categories;
                  };
              Other text.

groff test suite                  2023-10-28                            foo(2)

If the paragraph tag is long, man(7) will break the line after it.

$ nroff -man -Tascii ATTIC/vec.man
foo(2)                        System Calls Manual                       foo(2)

       vecvecvec
              The address of page_region array for output.

                  struct page_region {
                      __u64  start;
                      __u64  end;
                      __u64  categories;
                  };
              Other text.

groff test suite                  2023-10-28                            foo(2)

If you want to set the tag on the same line as the tag, you need to give
`TP` an argument indicating the desired width of the tag.  E.g.,
".TP 11n".

$ nroff -man -Tascii ATTIC/vec.man
foo(2)                        System Calls Manual                       foo(2)

       vecvecvec  The address of page_region array for output.

                      struct page_region {
                          __u64  start;
                          __u64  end;
                          __u64  categories;
                      };
                  Other text.

groff test suite                  2023-10-28                            foo(2)

If you want to _force_ a break after tag no matter its width, there are
a few ways, but for practical purposes, an inset region is useful.

I'm considerably elaborating the example here to illustrate the
adaptability of the "nest-RS-and-RE-within-TP" approach.

$ cat ATTIC/vec.man
.TH foo 2 2023-10-28 "groff test suite"
.TP
.B vec
.RS
The address of
.I page_region
array for output.
.P
Further details about page regions.
.RS
.P
.EX
struct page_region {
    __u64  start;
    __u64  end;
    __u64  categories;
};
.EE
.RE
.P
Further discussion of
.BR vec .
.RE
.P
We will talk about something else now.

$ nroff -man -Tascii ATTIC/vec.man
foo(2)                        System Calls Manual                       foo(2)

       vec
              The address of page_region array for output.

              Further details about page regions.

                     struct page_region {
                         __u64  start;
                         __u64  end;
                         __u64  categories;
                     };

              Further discussion of vec.

       We will talk about something else now.

groff test suite                  2023-10-28                            foo(2)

Notice how I needed neither `in` requests nor the `IP` macro for that.

This approach is fairly flexible, and still works for simple cases (but
does _force_ a break after the tag).

$ cat ATTIC/vec.man
.TH foo 2 2023-10-28 "groff test suite"
.TP
.B vec
.RS
The address of
.I page_region
array for output.
.RE
.TP
.B vec_len
The length of the
.I page_region
struct array.

$ nroff -man -Tascii ATTIC/vec.man
foo(2)                        System Calls Manual                       foo(2)

       vec
              The address of page_region array for output.

       vec_len
              The length of the page_region struct array.

groff test suite                  2023-10-28                            foo(2)

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

> 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.

Regards,
Branden

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