Re: RS/RE and paragraphing macros

[Alejandro Colomar]

Hi Branden,

On 2/15/23 03:16, G. Branden Robinson wrote:
[...]

> --end snip--
> 
> I know the above is lengthy; please point out any part of it that you
> find difficult to follow.
> 
> I came up with a list of constraints that Michael had on how he wanted
> to set code examples in the Linux man-pages.
> 
> https://lore.kernel.org/linux-man/20201113094755.bg6pl7g2s5h2w4mu@localhost.localdomain/
> 
> Phrasing one of them a different way, I _think_ one of the things
> Michael wanted was to be able to relocate examples within man pages with
> complete disregard for the left margin/indentation used in the
> surrounding context.  (I suspect this was so that the diffs would be
> really clean, and so he'd have extreme flexibility in example placement,
> never having to worry about remeasuring the output line lengths.)
> 
> I _suppose_ we could do something like add an argument to the `EX` macro
> to specify an "absolute indentation amount", or maybe it would be better
> to extend the semantics of `RS` (with a second argument, or
> interpretation of its first argument as a string initially, permitting
> some sort of alternative operation mode).  Both of these would of course
> be ignored by other implementations--certainly at first, and perhaps
> forever.
> 
> But before we start designing anything, we need to be on the same page
> with respect to what's going on; only then can we clearly articulate the
> nature of the desired change.

Okay, so now it makes sense.  There's indentation and left margin, and
they're different things (still weird that the amount of movement(?) of
the left margin is also called indentation (.RS [indentation])).

But I still have some doubts:

Is RS a paragraphing macro?  Does it start a new "normal" paragraph?  Or
does it continue in the same paragraph?  Empirically, I'd say it starts
a new paragraph, but that seems undocumented.

If it doesn't start a new paragraph, then I guess it needs to respect
whatever the running paragraph was, and so keep the indentation of the
paragraph.  I'll try to explain with code:


.PP
foo
.IP \[bu] 3
.RS 2
bar
.RE
.IP \[bu]
.PP
qwe
.IP \[bu]
zxc



RS
       foo

       •
         bar

       •  baz

       qwe

       •      zxc



Does RS force a new paragraph, or does it continue in the IP one?
If it continues in the IP paragraph, left margin has been moved by 2,
and indentation is 3 with respect to left margin, so "bar"
should be written at +5n compared to "foo".  This would be the more
intuitive behavior, I'd say (but it seems not the actual one).

If it forces a new paragraph, does it clean paragraphing as SH/SS do?
It seems not either, because baz continues with the indentation of 3,
so groff seems to know of a continuity in the paragraphing (compare
that to "qwe" and "zxc": "que" breaks the continuity in IP paragraphs,
so "zxc" has an indentation of 7).

But then, what does it exactly do with regards to paragraphing?  It
doesn't continue in the current paragraph, but doesn't start a new
one either.  When starting this email, I was going to suggest adding
a sentence to the documentation of RS similar to that of SH and SS:
"Text after heading‐text is set as an ordinary paragraph (.P).".
But now that doesn't make sense either.

Cheers,

Alex

> 
> Well, we need goals for groff 1.24, don't we?  ;-)

I might even call it a bug for 1.23, if you agree. ;)
However, we're already late for the freeze, so I don't want to make
it worse.  BTW, we're already in soft freeze dates (although I don't
follow Debian mailing lists and don't know if they are following the
planned timeline).

<https://release.debian.org/testing/freeze_policy.html>

Cheers,

Alex

> 
> Regards,
> Branden

-- 
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5

OpenPGP_signature
Description: OpenPGP digital signature