[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

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

From: Paul Eggert
Subject: Re: On being web-friendly and why info must die
Date: Wed, 10 Dec 2014 14:20:00 -0800
User-agent: Mozilla/5.0 (X11; Linux x86_64; rv:31.0) Gecko/20100101 Thunderbird/31.3.0

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.

reply via email to

[Prev in Thread] Current Thread [Next in Thread]