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

[Óscar Fuentes]

Paul Eggert <address@hidden> writes:

> 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.

Some formats (like Org) are "final", in the sense that the source text
(the equivalent of *.texi) is intended for consumption (it is the *.info
too, although not as pretty as some of its other representations such as
HTML.) Failures on the structure are visible, links can be checked right
away, etc. Hence, revising one of those alternative representations of
the Org document makes as much sense as revising *both* the .info and
.html products of the source .texi: it is ok for checking aesthetic
details, but overkill as a means of checking the correctness of the
*.texi itself.

>> 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.

There are several aspects of correctness which affects the *who* and the
*when*:

1. the author of the change shall convey the information on the
   documentation.

2. checking the resulting document in terms of appearance criteria can
   be done by another individual.

3. checking the resulting document in terms of clarity, completeness,
   style, etc. *must* be done by someone who is not the author.

For you as the author, it is a good thing to do 1 ASAP. If the
documentation tool allows you to do the job without "building the docs"
to check that you didn't break the build, etc., you stop caring about
the speed of that process.

But we can delay 2 and 3 until a late stage of the development cycle.
This avoids re-testing the same areas as they are successively touched
by changes, but makes even more sense because documentation is expected
to be a coherent corpus, something you can't check when you test the
changes as soon as they are introduced.

> 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.

No, that's not what I was proposing at all.

> 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.

Yes, as I mentioned on other message (thread?) requiring documentation
with the code change is something that would increase the quality of
Emacs and shorten the release cycles (which makes the project more
attractive for contributors as well; when one hacker makes a
contribution, he probably wishes to see it released before his
retirement.)