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

[phillip.lord@newcastle.ac.uk (Phillip Lord)]

"Eric S. Raymond" <esr@thyrsus.com> writes:
> The solution must be partly a change in mechanism and partly a change
> in policy and attitude.  The change in technology is the simple part;
> info and Texinfo must die.  They must be replaced with a common format
> for documentation masters that is Web-friendly, and by Web
> presentation.
>
> I have discussed this with RMS and, pending my ability to actually write
> proper translation tools, we have agreed on asciidoc as a new master 
> format.  This is what should replace Texinfo and the gallimaufry of
> ad-hoc text files like /etc/CONTRIBUTE and the admin/notes stuff.

I've written quite a lot of asciidoc in my time. It's not a bad format,
although it is not extensible, so I have resorted at times to using gpp
on source to get what I want (which messes up line numbers in error
reports, so there are problems with this approach).

Emacs support for asciidoc is not that good, to my knowledge. I have
been using adoc-mode, which does good syntax highlighting but is poor
for cross-referencing for instance. It also has a hang emacs bug (there
is a fix in my fork). So, I suspect that this would need fixing.

I recently went through these issues with a book I am writing. My
experiences are here.

http://www.russet.org.uk/blog/3020

I ended up with latex, although for documentation (which is much less
linear) I might reach a different conclusion. In particular, I would ask
about org -- the tools here already exist and the emacs support is
obviously good.


> The policy part of the job will in some ways be more difficult because
> the requirements are harder to define.  We need to change the way we
> think about Emacs's documentation; we need to concieve and organize it
> as a single, coherent, richly linked hypertext that renders to HTML as
> its major target.  This may mean giving up on some features supporting
> rendering to print manuals; I'm not sure yet. If so, it's time to bite
> that bullet.
>
> I'm willing to take on the tools end, but I can't do it all.  Someone
> needs to take ownership of the policy/organization end of the documentation 
> problem. Will any of the people righly complaining about this step up?

I am almost certainly not the person to do this, but I am willing to
contribute to the documentation. I write well, or at least I think I do
but then who doesn't.

Phil