Re: [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: 3907 bytes --]

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.

> I changed that slightly.
[...]
> We try to use \~ for a fillable space; it has the nice effect of
> removing the quotes.
> 
> -.IR "sizeof(struct pm_scan_arg)" .
> +.IR sizeof(struct\~pm_scan_arg) .

Yes.  This is portable _almost_ everywhere (certainly anyplace where
_Linux_ man pages are available), and it can prevent a lot of ugliness.

groff_man_style(7):

       \~        Adjustable non‐breaking space.  Use this escape
                 sequence to prevent a break inside a short phrase or
                 between a numerical quantity and its corresponding
                 unit(s).

                        Before starting the motor,
                        set the output speed to\~1.
                        There are 1,024\~bytes in 1\~KiB.
                        CSTR\~#8 documents the B\~language.

                 \~ is a GNU extension also supported by Heirloom
                 Doctools troff 050915 (September 2005), mandoc 1.9.14
                 (2009‐11‐16), neatroff (commit 1c6ab0f6e, 2016‐09‐13),
                 and Plan 9 from User Space troff (commit 93f8143600,
                 2022‐08‐12), but not by Solaris or Documenter’s
                 Workbench troffs.

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

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

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

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