Re: .RS

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

[-- Attachment #1: Type: text/plain, Size: 5568 bytes --]

Hi Alex!

And hi to Michael, too.  I'm sorry I haven't responded to your pings
about a good idiom for inset code examples.  The main reason is that I
don't yet have one that satisfies all of your criteria.  The other is
that groff is heaving its vast bulk toward a release, and I've been in a
perfectionist frenzy trying to clear my plate of my personal release
goals for it.  This includes man pages totalling 323 pages (not counting
groff_mdoc(7)[1]), which might not sound all that daunting to the author
of the scale-tipping _LPMI_ codex.  :D

At 2020-11-11T15:22:27+0100, Alejandro Colomar (man-pages) wrote:
> Hi,
> 
> We already talked about something similar some time ago.
> 
> I see [.RS 4] and [.RS +4n] used in the man pages.
> And there are also [.in +4n] and I think I've also seen [.in 4].
> Is there any difference between [+4n] and a simple [4]?

Not usually.  *roff parameters can be dimensionless (like hyphenation
modes), but many of them, like page length, line length, page offset,
indent(ation), and many others, have dimensions.  groff, like AT&T troff
before it, supports the expression of dimensions in a variety of units,
including U.S. traditional, metric, and printer's units (points, picas).
Ultimately, internally, all these different units are converted to
"basic units" which are meaningless outside of the formatter (but you
sometimes see them in diagnostic messages).

So when you use a request or a built-in register that has a dimension
associated with it, you need to either know what units are required to
get predictable output, or _tell_ *roff what units you want to use.
The way you do that is with a letter called a "scaling indicator".

These are documented.  See the section "NUMERICAL EXPRESSIONS"[2] in
groff(7) for a complete list.

Requests and (some) registers have a "default scaling indicator".  These
are document with the corresponding item.

"n" refers to "ens", a typographer's unit that is, roughly half an "em",
and an "em" is the width of a lowercase "m" in the current font.  For
character-cell terminals, 1m equals 1n equals 1 character cell, so it's
pretty easy to get a handle on.

> Which is the preferred one?

That's a terrific question.  I've wavered on this issue myself.
Semantically, there is no difference between ".RS" (or ".in") "4" and
"4n"--because the default scaling indicator for this macro (or request)
is "n".

At present I kind of lean toward "4n" because I think it disserves man
page authors to get too far away from the knowledge that groff is a
_typesetting_ system as troff and nroff (and roff, and Saltzer's RUNOFF)
were before it.

If man pages were only ever rendered to character-cell terminals[3], I'd
probably just settle on ignoring scaling indicators.  In fact, I'm not
sure they existed in *roff languages before Ossanna wrote troff.  As I
understand it, on Teletypes and line printers, your horizontal dimension
was character cells, your vertical dimension was lines, and you had
special logic for reverse line feeds and half line feeds in either
direction, and that was as granular as things got.

> And BTW, does [.RS] do anything different than [.in]?

At its core, no--but it saves a lot of state so that you can nest
further .RS calls, and use .RE, and so that the sectioning macros (.SH
and .SS) can undo their effect without causing havoc.

> I guess the code implementing those macros is written somewhere.
> Where can I have a look at that code to see it myself?

Here's the bleeding edge version:

https://git.savannah.gnu.org/cgit/groff.git/tree/tmac/an-old.tmac

There is almost certainly a copy of this file, probably from groff
1.22.4 on your system.  On my Debian box, it's at
/usr/share/groff/1.22.4/tmac/an-old.tmac.

Thomas Dickey once complained about the lack of comments in this
file--he's right, the things that a casual user most needs commented,
are not.  I've tried to remedy that defect in groff_man(7), but a more
Doxygenish approach to the package source itself would also be a good
idea.

Regards,
Branden

[1] groff_mdoc(7) will _ship_, but a person _really_ doesn't want to
know why it's not in my page count.  Ask me if you want a challenge
involving possibly diversions and traps.

[2] In groff 1.23.0, to no longer be in shouty capitals.  :D

[3] I sometimes get into a bit of conflict with some man page writers
who care less than nothing for any output device that isn't a terminal.
I want to accommodate such people as much as I can without compromising
quality for those who want to want to see man pages properly typeset.

The most recent episode of contretemps involves the sad history of
ASCII, ISO 8859, Unicode, and how exactly ' and ` (and to a lesser
extent, ^ and ~) should be rendered.  Some painful choices were made in
the 1970s, and some procrastination was coddled in the 2000s, that have
people grumbling today.  People threaten that the masses will just "go
to Markdown" if ignorance is not coddled.  For people who really care
_only_ about terminal input, I'm not sure such an out-migration can be
stopped, or should be.  Proper typesetting carries a lot of complexity
and it's hard to justify that complexity to people who don't want what
it can accomplish.

About the only challenge Markdown faces is filling, and I'm sure there
are tools to handle that it in its much simpler problem domain.  That,
or people just resize or horizontally scroll their terminals.  The
mindset is a bit foreign to me.

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