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

[David Kastrup <dak@gnu.org>]

"Stephen J. Turnbull" <stephen@xemacs.org> writes:

> The right way to stir things up is to appeal to the choir, not to the
> tourists gawking at the icons in the back of the hall.  The criterion
> for appeal of a new documentation format is clear: present a proof of
> concept translation of a "representative" Emacs manual[1] to the new
> source format, along with built manuals in the target format(s) and
> any tools needed to implement the desired navigation features.  The
> cost is high, but experience shows that worthwhile moves usually have
> redundant costs being paid.

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

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.

So it is not just a question of a flat conversion to get from a good
Info manual to a good HTML manual.

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.

But this impression is much more pervasive when using the manual in the
HTML renderings than in Info mode.  This kind of criticism might even
partly apply to the Info rendering, but if it does not significantly
impact working with the manual in its Info rendition, improvement
efforts tend to go somewhere else first.

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.

-- 
David Kastrup