From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: "Stephen J. Turnbull" Newsgroups: gmane.emacs.devel Subject: Re: Have you all gone crazy? Was: On being web-friendly and why info must die Date: Sat, 20 Dec 2014 19:22:58 +0900 Message-ID: <87h9wqd3i5.fsf@uwakimon.sk.tsukuba.ac.jp> References: <87388bnzha.fsf@newcastle.ac.uk> <87k31mdbhe.fsf@uwakimon.sk.tsukuba.ac.jp> <87tx0qiv45.fsf@fencepost.gnu.org> NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 X-Trace: ger.gmane.org 1419071017 32343 80.91.229.3 (20 Dec 2014 10:23:37 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Sat, 20 Dec 2014 10:23:37 +0000 (UTC) Cc: Phillip Lord , "Allen S. Rout" , emacs-devel@gnu.org To: David Kastrup Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Sat Dec 20 11:23:30 2014 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by plane.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1Y2HC4-0003ho-5C for ged-emacs-devel@m.gmane.org; Sat, 20 Dec 2014 11:23:28 +0100 Original-Received: from localhost ([::1]:33968 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Y2HC3-0007OP-88 for ged-emacs-devel@m.gmane.org; Sat, 20 Dec 2014 05:23:27 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:58175) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Y2HBs-0007Ny-Nw for emacs-devel@gnu.org; Sat, 20 Dec 2014 05:23:24 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1Y2HBl-0000Qu-68 for emacs-devel@gnu.org; Sat, 20 Dec 2014 05:23:16 -0500 Original-Received: from shako.sk.tsukuba.ac.jp ([130.158.97.161]:36763) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Y2HBd-0000NK-1G; Sat, 20 Dec 2014 05:23:01 -0500 Original-Received: from uwakimon.sk.tsukuba.ac.jp (uwakimon.sk.tsukuba.ac.jp [130.158.99.156]) (using TLSv1 with cipher AES256-SHA (256/256 bits)) (No client certificate requested) by shako.sk.tsukuba.ac.jp (Postfix) with ESMTPS id A299C1C3929; Sat, 20 Dec 2014 19:22:58 +0900 (JST) Original-Received: by uwakimon.sk.tsukuba.ac.jp (Postfix, from userid 1000) id 7B0711A2CFC; Sat, 20 Dec 2014 19:22:58 +0900 (JST) In-Reply-To: <87tx0qiv45.fsf@fencepost.gnu.org> X-Mailer: VM undefined under 21.5 (beta34) "kale" acf1c26e3019 XEmacs Lucid (x86_64-unknown-linux) X-detected-operating-system: by eggs.gnu.org: GNU/Linux 3.x X-Received-From: 130.158.97.161 X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Original-Sender: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.devel:180364 Archived-At: 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.