Re: .RS

["G. Branden Robinson" <g.branden.robinson@gmail.com>]

[-- Attachment #1.1: Type: text/plain, Size: 2688 bytes --]

At 2020-11-11T16:34:15+0100, Alejandro Colomar (man-pages) wrote:
> Thanks, Branden!
> 
> And [+4n] is because you can also indent negatively?
> But I guess I can omit [+] safely always.

Yes.  The unary plus is redundant for both .RS and .in.  I see it used
much more frequently with .in requests, though.  I think it has to do
with the greater awareness of formatter state one has to maintain when
writing in "raw" roff requests.  People include the plus as a form of
documentation.

You can indent negatively, and even to an absolute horizontal page
position (with the '|' prefix).  I don't see this done in real world
man pages and I sure don't encourage it before the question of how well
non-roff man page renderers (like mandoc) handle it.

Here's how RS is defined in V7 Unix's tmac.an:

' # increase relative indent
.de RS
.nr ]\\n+()p \\n()I
.nr )\\n()p \\n()R
.ie !"\\$1"" .nr )R +\\$1n
.el .nr )R +\\n()I
.nr )I .5i
.}E
..

And here's groff's definition of the same macro, which hasn't changed in
20 years[2].

.de1 RS
.  nr an-saved-margin\\n[an-level] \\n[an-margin]
.  nr an-saved-prevailing-indent\\n[an-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-level +1
..

The leading plus sign when the macro argument $1 is interpolated ensures
that if the caller doesn't supply a sign, the value will be interpreted
as an increment when updating the register value.  This is part of
general register management syntax rather than anything to do with
indentations or page formatting.

An example with very simple register settings may help elucidate this.

$ nroff
.nr A 2
.nr B 3
.nr A +5
.nr B 5
.tm \nA
7
.tm \nB
5

(I'm sort of making nroff work like a REPL here--an underrated approach
to learning it, in my opinion.  I typed the requests, and nroff [really
groff] wrote the "7" and "5" to standard error.)

The interesting thing to me is that .RS in V7 doesn't do any indentation
itself; instead it uses registers a bit differently.  And the register
names are limited to a two-character name length.

For the attached document I get identical output[3] from groff and
Heirloom Doctools troff, which is a direct descendant of the AT&T
implementation.

Regards,
Branden

[1] https://minnie.tuhs.org/cgi-bin/utree.pl?file=V7/usr/lib/tmac/tmac.an
[2] 19 years for the very first line, because groff introduced the 'de1'
    request at that time.
[3] modulus groff's use of SGR escapes instead of overstriking to
    achieve bold output; see grotty(1).

[-- Attachment #1.2: RS-negative.man --]
[-- Type: application/x-troff-man, Size: 270 bytes --]

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]