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
