Re: RS/RE and paragraphing macros

[G. Branden Robinson]

Hi Alex,

At 2023-02-21T00:30:19+0100, Alex Colomar wrote:
> Ahh, okay, so it breaks the line but it doesn't separate paragraphs.

That kind of depends on how a human reader interprets what they see.

> > Paragraphing macros in *roff packages _separate_ paragraphs; they do
> > not _enclose_ paragraphs.
> 
> Okay, so RS doesn't separate paragraphs.

I'll let you in on a secret.  As far as the formatter is concerned,
there is no such thing as a pargraph.  On the other hand, there is such
a thing as an output line.  Output lines have various properties.

> It does only break a line and move the left margin.  Where do you end
> up after breaking a line?  Since you didn't start a new paragraph, I'd
> guess that it would be reasonable to end up at the same indentation as
> the previous paragraph, no?  Let's see with an example what we get:
> 
> 
> $ cat br.man
> .TH a s d f
> .SH br
> foo bar baz
> .IP
> qwe rty uio
> .br
> zxc vbn xcv
> .PP
> lkjhjhjg hgfgfd
> $ man ./br.man | cat
> a(s)                                                              a(s)
> 
> br
>        foo bar baz
> 
>               qwe rty uio
>               zxc vbn xcv
> 
>        lkjhjhjg hgfgfd
> 
> f                                  d                              a(s)
> 
> 
> 
> Okay, this is what I expected.  .br continues at the same indentation of the
> IP, just at the next line.  Let's try the same with RS/RE; I'll use an inset
> of 0, to don't move the margin, so we only break the line.
> 
> 
> $ cat RS.man
> .TH a s d f
> .SH br
> foo bar baz
> .IP
> qwe rty uio
> .RS 0
> zxc vbn xcv
> .RE
> .PP
> lkjhjhjg hgfgfd
> alx@dell7760:~/tmp$ man ./RS.man | cat
> a(s)                                                              a(s)
> 
> br
>        foo bar baz
> 
>               qwe rty uio
>        zxc vbn xcv
> 
>        lkjhjhjg hgfgfd
> 
> f                                  d                              a(s)
> 
> 
> Hummm, this is definitely not as simple as "breaks the line and moves
> the margin".  The margin is not moved because of 0, so this should be
> just equivalent to .br from your own definition.  However, it's not.
> It does some extra magic, which I'd call "RS sets the indentation of
> the scoped block to 0; RE resets to the previous indentation".
> 
> I'm not saying that is necessarily bad, but we need to document it.
> In fact, after thinking about it, it can help to start a new block of
> indentation: that way, when you close with RE, you'll be able to
> continue bullet lists without specifying the indentation, even if some
> bullet within the list was rather long and had nested stuff.
> 
> So, I think RS/RE has the right choice; but it needs some more
> documentation.
> 
> Did that make sense to you?

Not completely.  I will go ahead and quote more of groff_man_style(7).
I was at great pains to craft this material.

  Horizontal and vertical spacing
    The indentation argument accepted by .IP, .TP, and the deprecated
    .HP is a number plus an optional scaling unit, as is .RS's inset-
    amount.  If no scaling unit is given, the man package assumes "n";
    that is, the width of a letter "n" in the font current when the
    macro is called (see section "Measurements" in groff(7)).  An
    indentation specified in a call to .IP, .TP, or the deprecated .HP
    persists until (1) another of these macros is called with an
    indentation argument, or (2) .SH, .SS, or .P or its synonyms is
    called; these clear the indentation entirely.  Insets created by .RS
    move the left margin and persist until .RS, .RE, .SH, or .SS is
    called.

    The indentation amount exhibited by ordinary paragraphs set with .P
    (and its synonyms) not within an .RS/.RE relative inset, and the
    default used when .IP, .RS, .TP, and the deprecated .HP are not
    given an indentation argument, is 7.2n for typesetting devices and
    7n for terminal devices (but see the -rIN option).  Headers, footers
    (both set with .TH), and section headings (.SH) are set at the left
    margin, and subsection headings (.SS) indented from it by 3n (but
    see the -rSN option).  HTML output devices ignore indentation.

    It may be helpful to think of the left margin and indentation as
    related but distinct concepts; groff's implementation of the man
    macro package tracks them separately.  The left margin is
    manipulated by .RS and .RE (and by .SH and .SS, which reset it to
    the default).  Indentation is controlled by the paragraphing macros
    (though, again, .SH and .SS reset it); it is imposed by the .TP,
    .IP, and deprecated .HP macros, and cancelled by .P and its
    synonyms.  An extensive example follows.

    This ordinary (.P) paragraph is not in a relative inset nor does it
    possess an indentation.

        Now we have created a relative inset (in other words, moved the
        left margin) with .RS and started another ordinary paragraph
        with .P.

        tag This tagged paragraph, set with .TP, is still within the .RS
            region, but lines after the first have a supplementary
            indentation that the tag lacks.

            A paragraph like this one, set with .IP, will appear to the
            reader as also associated with the tag above, because .IP
            re-uses the previous paragraph's indentation unless given an
            argument to change it.  This paragraph is affected both by
            the moved left margin (.RS) and indentation (.IP).
            +----------------------------------+
            | This table is affected both by   |
            | the left margin and indentation. |
            +----------------------------------+

        o   This indented paragraph has a bullet for a tag, making it
            more obvious that the left margin and indentation are
            distinct; only the former affects the tag, but both affect
            the text of the paragraph.

        This ordinary (.P) paragraph resets the indentation, but the
        left margin is still inset.
        +-----------------------------+
        | This table is affected only |
        | by the left margin.         |
        +-----------------------------+

    Finally, we have ended the relative inset by using .RE, which
    (because we used only one .RS/.RE pair) has reset the left margin to
    the default.  This is an ordinary .P paragraph.

...

Notes
    Some tips on troubleshooting your man pages follow.

...

    o .RS doesn't indent relative to my indented paragraph.
        The .RS macro sets the left margin; that is, the position at
        which an ordinary paragraph (.P and its synonyms) will be set.
        .IP, .TP, and the deprecated .HP use the same default
        indentation.  If not given an argument, .RS moves the left
        margin by this same amount.  To create an inset relative to an
        indented paragraph, call .RS repeatedly until an acceptable
        indentation is achieved, or give .RS an indentation argument
        that is at least as much as the paragraph's indentation amount
        relative to an adjacent .P paragraph.  See subsection
        "Horizontal and vertical spacing" above for the values.

        Another approach you can use with tagged paragraphs is to place
        an .RS call immediately after the paragraph tag; this will also
        force a break regardless of the width of the tag, which some
        authors prefer.  Follow-up paragraphs under the tag can then be
        set with .P instead of .IP.  Remember to use .RE to end the
        indented region before starting the next tagged paragraph (at
        the appropriate nesting level).

Regards,
Branden

signature.asc
Description: PGP signature