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

[Alan Mackenzie <acm@muc.de>]

Hello, Eric.

On Fri, Dec 05, 2014 at 07:35:49AM -0500, Eric S. Raymond wrote:

[ ... ]

> The positioning problem is that info/Texinfo makes us look like a
> steam-powered archaic joke to younger developers.  Text-only
> presentation with obtrusive links and a complex command set for a
> viewer that's *not a web browser*?  In 2014?  Really?

Links, by their very nature, are obtrusive.  A complex command set for a 
text-only editor is what Emacs (in essence) is.  I can't see what your
point is, here.

But it does strike me that many of your criticisms, below, of Texinfo
could equally be directed at Emacs as a whole.

> The capability problem is that the younger developers are objectively
> right to laugh.  Because these resources are not rendered to Web, ...

But they are.  Certainly, the Emacs manuals are online in HTML format.

> .... they're an informational ghetto with an impoverished internal link
> structure.

Impoverished?

> The fact that some of them, like /etc/CONTRIBUTE, are plain text with
> no link structure at all certainly doesn't help.

Maybe not.

[ ... ]

> 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 don't want to have to read Emacs manuals in web presentation.  HTML is
a least common denominator format, lacking many (most?) of the things we
take for granted in info.  In fact, an alien landing on Earth for the
first time would be astonished to learn that info is the older format,
and would wonder what had caused us to regress.

If info is to die, then there must first be a better program to take its
place.  A web browser is not it.

> 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 just looked at the asciidoc website.  It would appear there's no
text based rendering format, and I didn't find any mention of any
end-format tools, comparable with info, for reading such doc.

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

What features are we going to lose, compared with info?  What features,
if any, are we going to gain?

I don't think dumbing down our documentation source format is going to
help in attracting new devolpers.  But it will certainly soak up a _lot_
of effort to do.

> -- 
> 		<a href="http://www.catb.org/~esr/">Eric S. Raymond</a>

-- 
Alan Mackenzie (Nuremberg, Germany).