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:
signature.asc
Description: PGP signature
