[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: On being web-friendly and why info must die
From: |
Phillip Lord |
Subject: |
Re: On being web-friendly and why info must die |
Date: |
Fri, 05 Dec 2014 14:01:00 +0000 |
User-agent: |
Gnus/5.13 (Gnus v5.13) Emacs/24.3 (gnu/linux) |
"Eric S. Raymond" <address@hidden> 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
Re: On being web-friendly and why info must die, Alan Mackenzie, 2014/12/05
Re: On being web-friendly and why info must die, Ivan Shmakov, 2014/12/05