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@xxxxxxxxx/ > > 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:
signature.asc
Description: PGP signature
