At 2025-02-06T23:23:57-0600, Dave Kemper wrote: > On Tue, Feb 4, 2025 at 6:05 PM Tadziu Hoffmann > <hoffm...@usm.uni-muenchen.de> wrote: > > Given that so many attributes (for example, the hyphenation > > mode) are in fact associated with the environment, I just > > found it surprising that this isn't, (and the info file > > doesn't mention it). > > The info file documents it the same way it documents everything else: > any attribute associated with an environment has this association > explicitly stated; attributes without this explicit statement are > global.
The practice mirrors CSTR #54, where a capital "E" in the synopsis of a
request marks it as being (in my term) "environmental". It's not quite
obvious that anything that isn't environmental is global in AT&T troff,
because there's no annotation for a global property, and the same field
of the synopsis is used to list properties of diversions, default
scaling units, break implication, typesetting-specific operations, and a
few other things.
(I'll opine here that I dislike the documentary practice of using a
simple list (compounded by the use of implicit nulls) to enumerate
orthogonal parameters. I gather that one can project R^n onto the real
line, but the mechanism used to achieve any such mapping is seldom
obvious to the reader.)
Also, while some escape sequences (like `\f`, `\s`, `\S`, and `\H`)
affect the environment, escape sequences do not carry synopsizing
annotations in CSTR #54, and the point does not appear to me (in a quick
skim) to be explicitly considered. (#54 mavens may wish to peruse
§§2.2, 2.3 closely to check me.)
> (The latter point is perhaps not stated outright in the info
> file, though.)
I don't think it is either, and our Texinfo manual could be improved by
doing so.
> The "Environments" section does say that "hyphenation parameters" are
> part of an environment, without enumerating those parameters.
Is the selection of hyphenation language a hyphenation parameter?
Setting aside your knowledge of formatter behavior leading to this
thread, what would your assumption have been based on those words?
> So there's perhaps room to claim some ambiguity here.
I hadn't thought to marshal that point, so now I think we had, prior to
the bug #66387 fix, an _even worse_ problem--the formatter was behaving
contrary to its documentation. Reversion of the fix would therefore, if
we are to act as good stewards with clear consciences, also include an
update to the documentation recording the anomaly.
> But I think enumerating every environment-specific parameter in this
> section would not be doing the reader any favors.
I agree.
> A blanket statement of "anything not documented to be part of an
> environment is global" would better serve.
Yes. Unaware of this specific problem, I have for years fretted over
the fact that we, in our Texinfo manual, hurl these boilerplate
sentences regarding "the environment" at the reader repeatedly before
getting, fairly late in Chapter 5, to a presentation of what the heck
"environments" actually are.
I think the term "environment" needs some sort of preliminary
introduction prior its first use in request and escape sequence
descriptions. We can hedge and mumble about "advanced usage" if we
must, but this introduction needs to say something intelligible and,
ideally, will give the novice reader a good chance of guessing correctly
whether it's something they expect to care about in the near future.
I've done something similar with device and font file descriptions.
They, too, come up early, in Chapter 2, because we present there the
formatter's command-line syntax, including the `-F` option.
Here's the Texinfo source of what that looks like in groff Git.
@cindex device description file, introduced
@cindex description file, device, introduced
@cindex file, device description, introduced
@cindex font description file, introduced
@cindex description file, font, introduced
@cindex file, font description, introduced
The GNU @command{troff} formatter and @code{groff}'s output drivers read
@slanted{device} and @slanted{font description files} that detail the
output device and the typefaces available to it, including their glyph
repertoires and the @slanted{metrics} (dimensions) of each glyph. This
information permits the formatter to accurately place glyphs with
respect to each other. The device description file is always named
@file{DESC}; fonts are typically described in files with short names
like @file{TR}, @file{CR}, @file{HBI}, or
@file{S}.@footnote{@xref{Device and Font Description Files}.}
Regards,
Branden
signature.asc
Description: PGP signature
