Re: [groff] 27/33: eqn(1): Fix content and style nits.

[G. Branden Robinson]

Hi Dave,

At 2022-10-17T04:21:46-0500, Dave Kemper wrote:
> >     * Drop internal cross reference to material about "translation
> >     limits" that doesn't seem to be present (and never has been
> >     according to "git log").
> 
> Commit d239103a7, an extensive eqn overhaul in which Eric Raymond
> added MathML output, added this cross reference pointing to the "Bugs"
> section, as well as two items in that section (each beginning with "In
> MathML mode, ...").  So I think it's fair to say the reference
> referred to those two items, even if its wording doesn't make that
> clear.  (It doesn't to me either.)  The two "In MathML mode" items in
> "Bugs" survive to this day, so this wasn't a dangling reference,
> merely a murky one.

Ah, yes, that seems possible.  When I read the phrase "translation
limits" in this context, I think of things like static boundaries on the
sizes of identifiers or symbol tables, not unimplemented features.

> Whether that justifies restoring it (with clarified wording) is a
> different question.  The cross reference was in the "MathML mode
> limitations" section, pointing to further information about MathML
> limitations, but arguably the two items under "Bugs" could just as
> easily be classified as limitations, so simply moving them might be
> more straightforward.  (Since they're limitations that might one day
> be removed, rather than ones inherent in the design differences
> between eqn and MathML, I can see why Eric filed them in a separate
> place, but I'm not convinced that raises them to the level of bugs.)

I've introduced or retained "Limitations" (sub)sections in several groff
man pages;[1] often I find it a better fit for discussion of issues than
the historically well-attested "Bugs".  Against Ingo's advice I tend not
to use that section title.  We have a bug tracker for bugs; as far as I
know, Room 1127 in Murray Hill didn't.  "Limitations" seems like a
better characterization of features that are inessential but desirable
and not yet implemented, or which would require redesign of other parts
of the software system to realize.

Regards,
Branden

[1] lj4_font(5), grotty(1), preconv(1), tbl(1), groff(1), grog(1),
    groff_trace(7), and groff_www(7)[2]

[2] That last one's dubious; its title is "Limitations of grohtml".
    (Why is that section not in grohtml(1)?) I haven't done a deep edit
    on that page yet.  Undertaking such a task tends to drive me to
    revise implementation problems that I discover and which drive me to
    distraction (see tbl(1), meref.me).

signature.asc
Description: PGP signature