Hi Alex, Sorry for the delay in replying, I've been whacking on groff source pretty furiously and doing a _lot_ of testing.
At 2023-02-15T03:56:44+0100, Alejandro Colomar wrote: > > Phrasing one of them a different way, I _think_ one of the things > > Michael wanted was to be able to relocate examples within man pages > > with complete disregard for the left margin/indentation used in the > > surrounding context. (I suspect this was so that the diffs would be > > really clean, and so he'd have extreme flexibility in example > > placement, never having to worry about remeasuring the output line > > lengths.) > > > > I _suppose_ we could do something like add an argument to the `EX` > > macro to specify an "absolute indentation amount", or maybe it would > > be better to extend the semantics of `RS` (with a second argument, > > or interpretation of its first argument as a string initially, > > permitting some sort of alternative operation mode). Both of these > > would of course be ignored by other implementations--certainly at > > first, and perhaps forever. > > > > But before we start designing anything, we need to be on the same > > page with respect to what's going on; only then can we clearly > > articulate the nature of the desired change. > > Okay, so now it makes sense. There's indentation and left margin, and > they're different things (still weird that the amount of movement(?) > of the left margin is also called indentation (.RS [indentation])). That's such a good point that I pushed a fix for it. https://git.savannah.gnu.org/cgit/groff.git/commit/?id=b14a7dda59bf0fcf10667a40a31fabe78e479ebd > But I still have some doubts: > > Is RS a paragraphing macro? No. It breaks the line and moves the margin. > Does it start a new "normal" paragraph? Yes and no? I suspect you are thinking of paragraph macros as things that have scope. Or of things like HTML elements that open <tag> and close </tag>. Paragraphing macros in *roff macro packages generally are not designed this way, because designing them that way would raise the question of whether text that occurs between paragraphs is a paragraph or not. The answer to that question rapidly becomes philosophical and leads, I suspect, to a bunch of contrived concepts that make things murkier rather than clearer. > Or does it continue in the same paragraph? Empirically, I'd say it > starts a new paragraph, but that seems undocumented. Paragraphing macros in *roff packages _separate_ paragraphs; they do not _enclose_ paragraphs. groff's an.tmac has a common macro that is called by all paragraphing macros. .\" Break a paragraph. Restore defaults, except for indentation. .de an-break-paragraph . ft R . ps \\n[PS]u . vs \\n[VS]u . sp \\n[PD]u . ns .. This (1) sets the font style to roman; resets the type size and vertical spacing to the default. It puts vertical space on the output (which causes a break) in the amount of the configured inter-paragraph distance. It then enables "no-space" mode, which keeps input like this... Foo. .P .P .P .P .P Bar. ...from looking stupid. > If it doesn't start a new paragraph, then I guess it needs to respect > whatever the running paragraph was, and so keep the indentation of the > paragraph. I'll try to explain with code: [...] > Does RS force a new paragraph, or does it continue in the IP one? > If it continues in the IP paragraph, left margin has been moved by 2, > and indentation is 3 with respect to left margin, so "bar" > should be written at +5n compared to "foo". This would be the more > intuitive behavior, I'd say (but it seems not the actual one). > > If it forces a new paragraph, does it clean paragraphing as SH/SS do? > It seems not either, because baz continues with the indentation of 3, > so groff seems to know of a continuity in the paragraphing (compare > that to "qwe" and "zxc": "que" breaks the continuity in IP paragraphs, > so "zxc" has an indentation of 7). > > But then, what does it exactly do with regards to paragraphing? It > doesn't continue in the current paragraph, but doesn't start a new > one either. When starting this email, I was going to suggest adding > a sentence to the documentation of RS similar to that of SH and SS: > "Text after heading‐text is set as an ordinary paragraph (.P).". > But now that doesn't make sense either. I cannot follow most of this because it is predicated on a mental model of paragraphing that I do not think describes *roff macro packages very well, including man(7). If I strain to adopt what I think your mental model is, I fear I am not going to do well. I will probably say incorrect things, or develop such elaborate explanatory contrivances to try and impedance-match between us that I don't end up illuminating anything. Fortunately, I can recommend two alternatives. I already wrote my way out of this problem by contributing several introductory sections to the "GNU troff reference" part of groff's Texinfo manual. Like many other changes, you won't find it in groff 1.22.4 but you can obtain it from your groff checkout. Most of it also appears in the roff(7) man page. But some people hate Texinfo (hello, Larry McVoy) and man page authors in general hate reading documentation even more than they hate writing it. So the most distilled boiling down of basic *roff typesetting concepts I have yet managed is also now in the groff_man_style(7) page. Here it is (UTF-8 follows). Fundamental concepts groff is a programming system for typesetting: we thus often use the verb “to set” in the sense “to typeset”. The formatter troff(1) collects words from the input and fills output lines with as many as will fit. Words are separated by spaces and newlines. A transition to a new output line is called a break. When formatted, a word may be broken at hyphens, at \% or \: escape sequences (see subsection “Portability” below), or at predetermined locations if automatic hyphenation is enabled (see the -rHY option in section “Options” below). An output line may be supplemented with inter‐sentence space, and then optionally adjusted with more space to a consistent line length (see the -dAD option). roff(7) details these processes. An input line that starts with a dot (.) or neutral apostrophe (') is a control line. To call a macro, put its name after a dot on a control line. We refer to macros in this document using this leading dot. Some macros interpret arguments, words that follow the macro name. A newline, unless escaped (see subsection “Portability” below), marks the end of the macro call. An input line consisting of a dot followed by a newline is called the empty request; it does nothing. Text lines are input lines that are not control lines. We describe below several man macros that plant one‐line input traps: the next input line that directly produces formatted output is treated specially. For man documents that follow the advice in section “Portability” below, this means that control lines using the empty request and uncommented input lines ending with an escaped newline do not spring the trap; anything else does (but see the .TP macro description). Here is the discussion of paragraphing. Paragraphing macros An ordinary paragraph (.P) like this one is set without a first‐line indentation at the current left margin. In man pages and other technical literature, definition lists are frequently encountered; these can be set as “tagged paragraphs”, which have one (.TP) or more (.TQ) leading tags followed by a paragraph that has an additional indentation. The indented paragraph (.IP) macro is useful to continue the indented content of a narrative started with .TP, or to present an itemized or ordered list. All of these macros break the output line. If another paragraph macro has occurred since the previous .SH or .SS, they (except for .TQ) follow the break with a default amount of vertical space, which can be changed by the deprecated .PD macro; see subsection “Horizontal and vertical spacing” below. They also reset the type size and font style to defaults (.TQ again excepted); see subsection “Font style macros” below. If you forget about paragraph enclosure macros and start from the foregoing with a clear mind, does the picture that emerges make sense? Regards, Branden
signature.asc
Description: PGP signature