Re: bookmarks for concept index

[Eli Zaretskii]

On Sun, 5 May 2002, Werner LEMBERG wrote:

> I think you are too conservative here.

Someone has to ;-)

> I want
> texinfo a general purpose documenting system, and until this isn't
> reached (to a certain degree), I won't stop making suggestions for new
> keywords if the current ones don't suffice.

I'm not saying Texinfo should stagnate.  I'm saying that we should try to 
introduce changes in a way that they will ``work'' (i.e. be silently 
ignored) by older versions of Texinfo processors.  I'm also saying that 
compatibility with old versions should be a factor of _some_ importance 
in the decision-making process when we consider new features.

> My address@hidden' suggestion,
> for example, which I still believe is a good idea (I'll try to provide
> a patch if time permits, except you say that you dislike it completely

Please try to think whether such a functionality can be introduced by 
extending an existing directive.  For example, how about extending 
@ignore to produce the effect you want?  IIRC, makeinfo throws away 
everything until "@end ignore", including the rest of the line after 
@ignore, so there's a possibility here to add an extension while avoiding
incompatibility.  For example:

  @ignore foo bar baz
  @end ignore

will cause makeinfo to pass the three directives @foo, @bar, and @baz 
unaltered.

> -- BTW, you haven't commented on my last reply regarding this topic).

Sorry, I'm hard pressed for free time.  Your message is still on my todo.

> > So I'd much prefer changes we make in the language are
> > back-compatible, in the sense that they do not cause older versions
> > of makeinfo and texinfo.tex to choke, or crash and burn.
> 
> This is unavoidable to a certain degree.

Right, but there's nothing wrong in trying to make that degree lower ;-)

>  But usually
> `backwards-compatible' means the opposite, i.e., old documents can be
> run without problems using newer versions of texinfo.

Even this is not very true with Texinfo.  For example, old documents 
might need switches like --ifnottex to be processed, or even source-level 
changes.  I've seen enough of those.

> AFAIK, it is common practice (or even in the GNU guidelines?) to
> provide processed texinfo files with a distribution

True.

> this avoids the version problem completely.

Not true: if the user changes the Texinfo sources, she needs makeinfo 
that can process the modified sources.  The freedom to change the docs is 
an important part of free software goals.

> What about a switch which makes unknown keywords and
> environments a warning instead of an error?  I know Eli will hate me
> for this, but I suggest a @version keyword (similar to LaTeX) so that
> makeinfo/texinfo.tex aborts gracefully if unknown features are used.

If the implementation is compatible, I won't hate you ;-)  For example, 
we could extend @comment to take parameters, or something similar.

(Btw, there should be no need for @version, since each Texinfo processor 
already knows its version.  What we need is a conditional directive that 
can take a version as an argument, similar to "#if __GNUC__ >= 3".)