I guess we could approach this topic a different way (the statements below are
just my guesses and not based on any particular insight I have into the history
of this syntax):
1) If this alternate syntax is not actively supported, then that could be
stated as the reason why it is not (further) documented -- because it is
deprecated and error-prone and unsupported. "The alternate syntax is
error-prone and is considered a historical mistake. It should not be
propagated into new code. And since it is unsupported, the maintainers will
not be expending effort to fix bugs related to it or to document it further."
2) However, if the alternate syntax is actively supported, then I think it
*should* be documented, even if it is considered error-prone and if
"best-practice" is to avoid it.
The alternative is to have people, like me, stumbling on this undocumented
syntax and spending a considerable amount of time trying to explore what it is
and why it is undocumented.
I *do* understand your concern to avoid expending maintainer effort in the
direction of something that you'd rather just go away. I'm trying to see if
there is a reasonable middle ground between the two concerns.
I understand that, ultimately, you have to chose the solution that you feel is
the best balance overall.
Thanks for your maintenance of a critical piece of modern infrastructure!
-- John
On Monday, March 10, 2025 at 09:51:44 AM EDT, Chet Ramey
<[email protected]> wrote:
On 3/10/25 9:38 AM, John Wiersba wrote:
> Maybe a comment in the documentation along the lines of:
>
> There are also alternate, deprecated syntactic constructs for these loops
> which will not be documented here
>
> would serve both aims?
How is that better? It leads to the inevitable "well, what are they?"
questions and the just as inevitable "then why aren't they documented?"
and you're back where you started.
--
``The lyf so short, the craft so long to lerne.'' - Chaucer
``Ars longa, vita brevis'' - Hippocrates
Chet Ramey, UTech, CWRU [email protected] http://tiswww.cwru.edu/~chet/
