Re: RS/RE and paragraphing macros

[Alex Colomar]

Hi Branden,

On 2/21/23 01:09, G. Branden Robinson wrote:
[...]

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

Okay.

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

This sentence is very unclear to me.  The indentation amount of .P is 0. 
 What's this intending to say?

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

Hmmm, this seems like absolute movement of the left margin.  Isn't it? 
Although you can consider these are resetting all previous inset and 
indentation, which effectively results in absolute setting to 0 and 3n.

>      HTML output devices ignore indentation.

Do they ignore left margin, indentation or both?  You could be more precise.

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

The example above lacks something.  You could show how when an IP is 
followed by a lot of stuff inset with RS, followed by RE and IP, the IP 
after RE has the same indentation as specified by the first IP, even if 
in the middle there were Ps.

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

Cheers,

Alex

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

OpenPGP_signature
Description: OpenPGP digital signature