Re: Have you all gone crazy? Was: On being web-friendly and why info must die

[Stephen J. Turnbull]

David Kastrup writes:

 > Well, a lot of the complaints of people preferring man pages over
 > info pages significantly concern the organization of the _content_
 > rather than a problem with the format.

I'm sure they do.  And I'm sure Emacs documentation could be vastly
improved in that respect.  But let me repeat myself: I don't know of
any software manual that really shines.  I know of a couple of great
textbooks and the occasional excellent tutorial, but that's quite
different from a reference manual.

 > The whole Git documentation is still available as Info [...].

 > Perl documentation is structured into man pages [...].

Praising with faint damns, again?

These have to be the poster children for "man page.s suck, *please* get
us a better format."  Turning them into Info make make them bearable.

 > > Sorry, David, but this is a *plus*, not a *minus*.  The Emacs manuals
 > > will continue to be distributed with Emacs.  Users with a full Emacs
 > > installed (OK, Debian users won't get them in the default "free"
 > > distribution) will have local access to the manuals.  Local access is
 > > plenty fast whether broken up into multiple files or as a single large
 > > file, as applications like S5 prove.
 > 
 > For mostly text-centric stuff, maybe.

S5 happily does the usual number of equations and graphs for a lecture
on economics (about 150 of the former and 50 of the latter, total of
200 images, for a typical 75 minute lecture with 50 slides).  There
are no noticable delays in Safari, Firefox, or Chrome.  That should be
sufficient for an Emacs documentation target format, I think.  (I
mostly still use LaTeX and PDF, though, because there's nothing like
AUCTeX for doing technical writing, thank you very much, David.)

 > But that's what the HTML fans loudly claim to be uncool.

I don't care what HTML fans claim to be uncool.  I care about what has
a chance of getting implemented in the Emacs project.  Once we get the
the HTML horse inside the walls, then the fanboys and gals can jump
out and do their damnedest to turn Emacs documentation psychedelic.
ISTM, though, that if it doesn't do text acceptably well it has no
chance of being accepted, and on the contrary, nobody who matters to
whether it is accepted (except you) will care if Lilypond docs are a
bit slow.

 > Once you work on the divided HTML form, finding stuff via plain
 > text search and/or index gets really painful.  And jumping around
 > several files refetches and rerenders them all the time.

Oh, sure.  Once again, we're agreeing violently.  The problems of
indexing and efficient node navigation need to be solved.  I'm just
saying that I believe they can be solved.  We just need someone who
cares enough about the format switch to step up to the plate and get
to first base with a proof of concept.

Unfortunately, I don't care that much.  I just want people to stop
vituperating about obsolete formats and minor inconveniences, and do
something useful if they care enough.