Re: RS/RE and paragraphing macros

[G. Branden Robinson]

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