Re: [PATCH 2/2] ioctl_pagemap_scan: add page for pagemap_scan IOCTL

[Alejandro Colomar <alx@kernel.org>]

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

Hi Branden,

On Mon, Oct 23, 2023 at 09:48:02PM -0500, G. Branden Robinson wrote:
> Hi Alex,
> 
> At 2023-10-23T23:52:28+0200, Alejandro Colomar wrote:
> > [CC += Branden]
> > > +.SH SYNOPSIS
> > > +.nf
> > > +.BR "#include <linux/fs.h>" "  /* Definition of " struct " " pm_scan_arg ", "
> > > +.BR "                          struct page_region "and " PAGE_IS_* "constants " */"
> > 
> > That space is not necessary after a closing '"' is something I don't
> > know why exists.
> 
> Right; since filling is off, and the line will be broken after
> "pm_scan_arg," (with typeface changes) anyway, this attempts to put a
> space at the end of the line.  But that would be invisible, and an
> according-to-Hoyle *roff formatter would get rid of such spaces at the
> end of the line before sending them to the output device anyway.
> 
> $ printf '.TH foo 1 date package\n.B "pm_scan_arg, "\n' \
>   | groff -Tutf8 -man -Z | sed -n '/pm_scan_arg/,/package/p'
> tpm_scan_arg,
> n40 0
> f1
> V200
> H0
> tpackage
> 
> 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.  ;)

[...]

> 
> > > +.TP
> > > +.B vec
> > > +The address of
> > > +.I page_region
> > > +array for output.
> > > +.PP
> > > +.in +8n
> > 
> > Ahh, this is great, because I needed to explain to groff(1)
> > maintainers what is the problem with TP that I was complaining about
> > in another thread.
> > 
> > Branden, here's what I mean.
> 
> 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?

> 
> In all that time, no flash of brilliance has yet illuminated a solution
> (that wouldn't involve extending the man(7) language, like recognizing
> an additional argument to TP or other paragraphing macros).
> 
> > If you're new to man(7), it is rather unintuitive what to do here.
> 
> Yes.  groff_man_style(7) attempts to offer advice here, in subsections
> "Horizontal and vertical spacing" and as one of the FAQs in "Notes"
> (".RS doesn't indent relative to my indented paragraph.").

Yup, but anyone new to man(7) will likely be put off by that page.

$ man groff_man_style | wc -l
1439

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

Cheers,
Alex

> 
> That's more material than I care to quote to this list, so I will just
> advise anyone who doesn't already have groff 1.23.0 installed to check
> out pages 261 and 269 of
> <https://www.gnu.org/software/groff/manual/groff-man-pages.pdf>.
> 
> > Muhammad, in this project, we usually use IP to continuate a TP.
> 
> More projects than this one use it for that purpose; when `IP` itself is
> given no tag argument, it is idiomatic usage going back to 1979.
> 
> Regards,
> Branden



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

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