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

[Paul Eggert]

On 12/10/2014 11:47 AM, Óscar Fuentes wrote:
> Paul Eggert <address@hidden> writes:
>
> > Typically I
> > focus on that editing the .texi file first to get the content right.
> > Then, I want to make sure the result is readable so I generate the
> > output and look at it.
> I reckon that those issues are related to the texinfo format,
> specifically. Other formats can be checked for readability without
> exporting them first.

Sorry, I'm lost.  To me, "texinfo format" is the format of (say) 
doc/lispref/intro.texi.  But I can check that for readability as I edit 
it.  The problem is that I also need to check the info-format output, 
which is in info/elisp.info.  To do that, I need to run 'makeinfo', 
which takes over a minute on my machine.

True, I can often just as easily check the HTML output of 'makeinfo' 
instead.  But the HTML takes even longer to generate than the info 
output does (78 seconds as opposed to 64 seconds on my machine), so 
that's not a realistic alternative.

> Isn't it possible to defer those issues to an advanced stage where the 
> areas with documentation changes are checked ``en-masse'' instead of 
> checking one change at a time? 

That's less efficient.  When I'm making a change I'm conscious of it and 
can check it easily.  If I (or worse, someone else) checks it several 
months later, it'll take them more time to get into the swing of things.

More generally, it's not good practice for Emacs developers to check in 
poorly-documented changes, and expect this to get fixed en masse later 
in a documentation pass.  It's better if a change results in a coherent 
Emacs (code, documentation, tests, etc.) and is installed all at once 
(perhaps as a merge commit).  I realize this isn't always possible, but 
still it's a good goal.  Also, I realize that this policy hasn't always 
been a goal in Emacs development, but that's something I'd like to see 
changed as we move forward.