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

["Stephen J. Turnbull" <stephen@xemacs.org>]

David Kastrup writes:

 > There is actually another hidden hurdle that has not been
 > mentioned: the target format "Info" is not independent from the
 > manual's organization of content: content is organized into
 > node-sized chunks, with a somewhat hierarchical organization
 > intended to make all non-bottom nodes fit on a screen if feasible
 > in order to make navigation fast.

I don't think this is a big problem, though.  I don't see any reason
why the organization into "nodes" or "pages" (as in the original
intent of *nix "man page") would change.  It's the obvious way (at
least to me) to provide modularity in documentation to correspond to
the modularity of the program.

 > However, this kind of "fast" implies that not every following of a
 > link requires substantial time fetching and rerendering pages.
 > HTML (let alone http and the Internet) is not intended for fast
 > flipping back and forth between independent pages, and the HTML
 > browsers are not supposed to deal with humongous pages comprising a
 > whole manual either.

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.  I can't testify to "humongous"
files (eg, the Emacs Lisp manual), but historically those have been
divided for Info presentation, too.

So what you get with a web-friendly manual is accessibility (though
somewhat degraded) for those who *don't* have the manuals installed
locally.  For many of the advocates, it's not obvious that degraded
performance would be observed even for large manuals.  Even in Japan I
often get sub-500ms click-to-readable performance on pages that I
believe are hosted in the US (although that may be biased; the Python
manuals I consult frequently that way may be hosted on a CDN, and of
course Savannah access is often painful -- a Savannah-hosted manual
wouldn't be very useful to me).

 > Finding tolerable compromises in organizing a manual into HTML-browsing
 > suitable form that is not in one of several ways more painful or awkward
 > to work with than avoidable requires a quite less hierarchical
 > organization than a good Info manual provides.

Agreed, that is a problem that (to my knowledge, which is limited) has
not been solved.  I don't see why HTML is inherently less suited to
presenting non-hierarchical aspects of software documentation than
Info, though.  I believe that this problem is likely to be amenable to
a few Ecmascript tweaks and some CSS to get fast, agile navigation.
(Granted, I don't have proof of concept.)

I think it's quite undesirable to compromise on agile navigation.  But
I also think it's probably unnecessary.

 > There have been people looking at the organization of the Emacs
 > manual in its HTML form in this thread who claimed that it is just
 > awfully badly organized and written.

Awful is relative.  By and large software manuals suck pretty badly,
and Emacs is well to the "better" end of the continuum.  Given the
emphasis on "drive-by" contributions, I wonder if the critics are not
looking for tutorials rather than manuals.  The manuals distributed
with Emacs are not long on "how to" tutorials.

 > The impression would likely be different if the typical HTML
 > rendition of a manual would closer resemble a folding editor or
 > other non-flat but still instantly accessible representation.

It's possible achieve that.  Again I refer to "S5", for example.  But
that kind of presentation would require significant amounts of
Ecmascript.