Re: .RS

["Alejandro Colomar (man-pages)" <alx.manpages@gmail.com>]

Thanks, Branden!

And [+4n] is because you can also indent negatively?
But I guess I can omit [+] safely always.

Thanks,

Alex

On 11/11/20 4:09 PM, G. Branden Robinson wrote:
> 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.
>