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

[David Kastrup <dak@gnu.org>]

Paul Eggert <eggert@cs.ucla.edu> writes:

> On 12/09/2014 12:57 AM, David Kastrup wrote:
>>
>>> I do it all the time when I'm editing manuals, because I want to check
>>> the output.
>> But that's one manual then, not all the manuals.
>
> Sometimes it's just one Emacs manual, but often enough I'm editing
> multiple manuals.  Plus, even if it's just one manual, Texinfo 5 is
> still waayyy toooo sloooowww.
>
>> Make doc for LilyPond takes over an hour.
>
> That's too bad.  It shouldn't take an hour to check out one's changes
> to the documentation.  That's a sure way to discourage contributions
> to the documentation.

Not really.  For one thing, the normal "make" creates the Info
documentation (and no HTML docs at all) without images.  That catches at
least syntax errors in the text parts, and it's probably half a minute
of the overall compile time.  It's not much of a help for the
translators though since we provide Info only for English.

For another, if you create a documentation patch and submit it to our
tracker, it is picked up by the compile farms and tested for building
properly (including full documentation).

And third, the dependencies are done pretty well.  If you change one
source file, only the corresponding Info/HTML/PDF document gets
regenerated, and only changed images (which take the bulk of the time)
are recompiled: a system of hashing makes sure that any changes in the
image source result in a new file name for the file extracted from the
embedded source.

Of course, if you change the LilyPond executable and expect changes in
the docs because of the changes in the executable responsible for
generating the images, you need to run "make doc-clean": an explicit
dependency of everything on the executable would be too painful.

>> Texinfo is a small project. If one is serious about wanting to
>> invest time ("we need to do better" suggests so), it is likely spent
>> quite effectively there. 
>
> Only if we assume that Texinfo is the way to go for the future.  If
> not, our time is spent more effectively elsewhere.

It's under control of the GNU project and it does the job.  We are free
to spend time in it.  For projects external to GNU, we may or may not
even have the possibility to spend time/effort for making them better
suited for GNU.

-- 
David Kastrup