Re: On being web-friendly and why info must die

[Eli Zaretskii <eliz@gnu.org>]

> Date: Fri, 05 Dec 2014 14:47:51 -0800
> From: Paul Eggert <eggert@cs.ucla.edu>
> Cc: emacs-devel@gnu.org
> 
> On 12/05/2014 01:51 PM, Eric S. Raymond wrote:
> >> So if we don't have better alternatives, why not stick with what we
> >> >have?
> > Because it's ugly, heavyweight, and a barrier to entry.
> 
> Although I know Texinfo well and asciidoc poorly and so am naturally 
> biased in favor of Texinfo, I can certainly attest to Texinfo being 
> heavyweight and having significant problems.  My 3-year-old desktop at 
> work currently takes over a minute to create info/elisp.info from 
> Emacs's Texinfo sources, and this is so annoyingly slow that it 
> discourages me from checking my work when I edit the Elisp manual.
> 
> I know some Emacs developers purposely run older versions of Texinfo 
> (which are faster) because of this performance problem, and this means 
> we can't assume reasonably modern Texinfo features, e.g., good support 
> for Unicode characters.

Since I'm one of those mentioned in the last paragraph, let me tell
you: this is a relatively minor problem for me.  I use an older
makeinfo mainly in protest: I couldn't believe the Texinfo users will
accept a new version that is uniformly 18 times slower than the
previous one.  Especially having gone through the outcry of Emacs
users when the new bidi display engine in Emacs 24 showed much smaller
(but still significant) slowdown in just some very corner use cases.

But if there is some language feature supported by a future Texinfo
that is a must, I will definitely switch to it, and suffer the
slowdown.

> Even though Texinfo made a lot of sense for many years and we should not 
> switch lightly, it may now be time to think of switching.  It'd be a win 
> if we could use a format with a decently-fast support.

The only reason why the Texinfo maintainer accepted the current slow
implementation is that no one was prepared to continue developing the
old C implementation, and so the only suggestion on the table was to
either accept the one based on Perl, which promised a future and a lot
of extensibility, or stagnate.

Therefore, an alternative to switching away from Texinfo would be to
volunteer to implement a much faster translator while keeping the
extensibility.  Texinfo is a small and a simple enough a language for
such a fast translator to be possible.  If someone with motivation and
enough interest is reading this, here is your cue.

And once again, no matter to which source language we switch, it will
not magically solve our documentation issues.  Contrary to what Eric
is saying, 90% of the effort of writing good documentation is not
producing markup -- each one is just a couple of keys in Emacs's
texinfo-mode.  No, the main part of the effort is thinking how to
describe a feature in a logical and didactically correct manner, and
then expressing that in clear and concise English text.  No markup
language will ever help us solve these problems, as they are
fundamentally human activities based on human creativity.  They need
human skills, not automated tools.