Re: RS/RE and paragraphing macros

[Alejandro Colomar]

Hi Branden,

On Tue, Feb 21, 2023, 17:49 G. Branden Robinson <
g.branden.robinson@gmail.com> wrote:

> Hi Alex,
>
> At 2023-02-21T11:09:13+0100, Alex Colomar wrote:
> > On 2/21/23 01:29, G. Branden Robinson wrote:
> > > .\" Start a relative inset level (by the amount given in the argument).
> > > .\" .RS [indent]
> >
> > Which reminds us that this was missing in your recent patch, right? :)
>
> That was deliberate; I'm willing to let the in-source comments lag
> terminological revisions to documentation a bit.
>

Okay.


> > > .de1 RS
> > > .  nr an-saved-margin\\n[an-inset-level] \\n[an-margin]
> > > .  nr an-saved-prevailing-indent\\n[an-inset-level] \
> > >       \\n[an-prevailing-indent]
> > > .  ie \\n[.$] .nr an-margin +(n;\\$1)
> > > .  el         .nr an-margin +\\n[an-prevailing-indent]
> > > .  in \\n[an-margin]u
> > > .  nr an-prevailing-indent \\n[IN]
> > > .  nr an-inset-level +1
> > > ..
> > >
> > > RS (1) saves the previous margin setting and "prevailing indent" (this
> > > term goes all the way back to McIlroy's 1979 man(7)); (2) insets (moves
> > > right) the margin by the amount in the argument, or by the
> > > aforementioned prevailing indent if there is no argument; (3) sets the
> > > formatter's indentation to this new value (not "0"); (4) updates the
> > > prevailing indent by the user-configurable standard indentation
> > > (register `IN`); and (5) increments the inset level.
> >
> > This confuses me again.  All the references to indentation mean the
> > inset-amount, right?
>
> No.
>
> "prevailing-indent" refers to the indentation.  The "inset-amount" is
> absorbed additively into the "margin".
>

Would you mind rewriting the above with more unambiguous terms?  Although
maybe it's not necessary.  I managed to make you say what I wanted you to
say (below).  That might be enough.


> > What happens to the actual indentation (as in IP)?
>
> It is disregarded, but preserved for possible restoration upon a
> subsequent `RE` call.
>

This sentence is precisely what I feel is missing in the documentation.
Don't you think?  Could you add this information to the manual page?



> > Let's try to improve that then.  I'm still not convinced ;)
>
> It would help me if you'd identify specific sentences I've quoted from
> the documentation that you feel are misleading or incomplete.
>

Sure, see above. :)

Cheers,

Alex


> Regards,
> Branden
>
--
<http://www.alejandro-colomar.es/>