🚀 go-pugleaf

> Date: Sat, 23 Jun 2012 15:07:38 +0200
> From: Patrice Dumas <pertusus@free.fr>
> Cc: bug-gdb@gnu.org, karl@freefriends.org
> 
> You missed my point.  The manual is formatted fine, but since it uses an
> undocummented Texinfo feature it is in a bad shape Texinfo-wise and the
> formatting could change in the future, more or less drastically.
> 
> > If you make such backwards incompatible changes in behavior, people
> > will complain, and rightly so.
> 
> Not rightly.  Undocumented features should not be counted on.

But they are, all the time.  Breaking that causes users to complain,
and insisting on breaking them makes maintainers look unfriendly.

> > How is an empty argument to @w any better than an empty @item?  One
> > day someone might even decide that such empty arguments to @w "don't
> > make sense", and will produce a warning for that, too.
> 
> Sure, unless the fact that an empty @item is wrong but an @item with an
> empty @w{} is correct is documented in the manual, in which case it
> becomes 'set in stone' that this is a correct construct.

First, we should agree that one is "right" while the other is "wrong",
and for that we need a good reason to reject the 'wrong" one.

And second, documenting things rarely makes them "set in stone",
because users have a habit of rejecting unreasonable (from their POV)
restrictions, even if they are documented.

> > A user-friendly tool lets users do whatever they want, so long as the
> > result is to users' liking.  If I learned anything from the days back
> > when I was hacking makeinfo, it's that users will use the tools in
> > every imaginable way and some unimaginable ones.  Restricting them or
> > annoying them with gratuitous messages, without a very good reason, is
> > just annoyance.
> 
> I interpret your point in the exact opposite direction.  To me, the fact
> that 'users will use the tools in every imaginable way and some
> unimaginable ones' means that users should only have expectations on the
> documented features, and that we may want to precise the right ways
> at any time.

This doesn't work in practice, and I hope Texinfo will not go that
way.

> If you look at the manual, the @top is in an @ifnottex block, but
> the idea is that the rule about @contents should not depend on the
> output format.

If there's no good reason for a rule, it simply should not exist.