Proposed: rename `ptr` request to `pwh` (with transition period)

"G. Branden Robinson" <[email protected]> Tue, 23 Dec 2025 15:12:55 -0600

Newsgroups	gmane.comp.printing.groff.general
Message-ID	<20251223211255.wwx5vf5mvjpm3no3@illithid>

Hi folks,

The forthcoming groff 1.24 release has become festooned with new
requests that write human-readable disclosures of the formatter's
internal state, including the properties of user-defined objects.

We've long had:
pev
pm
pnr

For the 1.24 development cycle, I've added:
pchar
pcolor
pcomposite
pfp
pftr
phw
pline
pstream

Of these, _most_ correspond, if you strip off the leading `p`, to a
request that manipulates the formatter object interrogated by the
request. That is, one creates registers with `nr`, environments with
`ev`, user-defined characters with `char`, composite character mappings
with `composite`, and so on.[1]

However there are exceptions.

* `pm` reports the properties of a macro, string, or diversion. Also
it's the only one of these that appeared in CSTR #54/AT&T troff so
we're stuck with it. I also have no appetite for reform in this area
because these objects really are quite similar internally, and we are
faced with an embarrassment of riches in request names manipulating
them--ds/as/de/am/di, and that's just the classic AT&T ones.

* `pstream` has no corresponding `stream` request. Instead, one creates
streams with `open` or `opena`. `popen` would be a poor choice
because (1) a groff extension request of that name already exists; and
(2) it doesn't communicate in any way the type of object under
inspection.

* `pline` corresponds to no request. None exists for creating a
"pending output line"; that's constructed by numerous other
operations.

Unfortunately, given the foregoing scheme, `ptr`, which lists page
location traps, is pretty warty for two reasons. (A) Requests named
`wh` and `ch` are what actually manipulate these objects. (B) There's
already a `tr` request that deals with an utterly different matter
(character translations).[2]

`ptr` is a groff extension, so we're _not_ stuck with it.

My proposal is this:

1. Rename `ptr` to `pwh` ("print 'when' traps will spring") in the
formatter.
2. Supply a wrapper macro named `ptr` in the default "troffrc" to wrap
`pwh` and advise the user to migrate to the new name. Then, in a
later release, we can take the wrapper out.

I expect this change to be of low impact because, like all the `p*`
requests discussed above (except `popen`), it has no utility besides
aiding a human to debug a document or macro package (or, if you're a
"lucky" son of a gun like me, the formatter itself). The
reporting/dumping requests do not (should not) _change_ the state of the
formatter.[3]

Thoughts? Objections? Better ideas?

Regards,
Branden

[1] Relatedly, it recently became clear to me that it would be useful to
have dumper for diversions; not their "macro contents", which one
can already do (now) with the `pm` request, but for numerous _other_
properties they possess.

https://cgit.git.savannah.gnu.org/cgit/groff.git/tree/src/roff/troff/div.h?h=1.23.0#n102

I expect to call this request `pdi`, and for it to report on the
top-level diversion of given no argument. (The top-level diversion
does not have a name within the formatter.)

But I don't expect to work on that until after the 1.24.0 release.

[2] I'd actually _like_ to have a way to report character translations,
as it's obvious to me that users can get themselves into trouble
with them. But, I'd like to bind character translations to the
environment instead of having them be global, which I think better
matches the original intent of the future.

https://savannah.gnu.org/bugs/?62691

And, that done, `pev` could report an environment's associated
translations, if any. The hard part is coming up with a syntax for
reporting them, since there are potentially many, and they can act
upon not only every printable Basic Latin character--actually at
least one unprintable one as well :-|--and for historical/practical
reasons you can translate characters to things that aren't
characters at all. Double :-|.

[3] I recently was at pains to be careful about this.

https://savannah.gnu.org/bugs/?67711

signature.asc (application/pgp-signature, 833 B)