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

[Paul Eggert]

Óscar Fuentes wrote:

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

This is an advantage of Org mode over Texinfo.

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

It's certainly better to have a non-author also check appearance and style.  But 
this doesn't affect the point that it's better when the author can check these 
things easily too, right away when writing the change.  Right now, though, 
Texinfo 5 is making it unnecessarily hard for Emacs documentation authors to 
check their work.

Besides, we need to be realistic: we don't have an army of documentation 
developers and we're unlikely to gain one while our doc tools are more awkward 
than they need to be.  If we stick with our current development process this 
problem will likely just fester.

Would it be reasonable to pick one part of the Emacs manual -- 
doc/misc/org.texi, say -- and convert it to Org mode?  The idea is to see how 
well Org mode would work for representing all of the Emacs documentation, and 
perhaps we can convert it one manual at a time rather than trying to do it all 
at once.