From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Alan Mackenzie Newsgroups: gmane.emacs.devel Subject: Re: On being web-friendly and why info must die Date: Fri, 5 Dec 2014 14:34:31 +0000 Message-ID: <20141205143431.GA3294@acm.acm> References: <20141205123549.GA29331@thyrsus.com> NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Trace: ger.gmane.org 1417790141 5178 80.91.229.3 (5 Dec 2014 14:35:41 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Fri, 5 Dec 2014 14:35:41 +0000 (UTC) Cc: emacs-devel@gnu.org To: "Eric S. Raymond" Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Fri Dec 05 15:35:34 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 1Xwtyn-0006Si-BG for ged-emacs-devel@m.gmane.org; Fri, 05 Dec 2014 15:35:33 +0100 Original-Received: from localhost ([::1]:50711 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Xwtym-0000a8-Ua for ged-emacs-devel@m.gmane.org; Fri, 05 Dec 2014 09:35:32 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:49596) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1XwtyK-0000PT-9Z for emacs-devel@gnu.org; Fri, 05 Dec 2014 09:35:10 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1XwtyE-0001YO-F6 for emacs-devel@gnu.org; Fri, 05 Dec 2014 09:35:04 -0500 Original-Received: from colin.muc.de ([193.149.48.1]:29551 helo=mail.muc.de) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1XwtyE-0001YE-4r for emacs-devel@gnu.org; Fri, 05 Dec 2014 09:34:58 -0500 Original-Received: (qmail 76305 invoked by uid 3782); 5 Dec 2014 14:34:54 -0000 Original-Received: from acm.muc.de (pD951ABA5.dip0.t-ipconnect.de [217.81.171.165]) by colin.muc.de (tmda-ofmipd) with ESMTP; Fri, 05 Dec 2014 15:34:53 +0100 Original-Received: (qmail 5091 invoked by uid 1000); 5 Dec 2014 14:34:31 -0000 Content-Disposition: inline In-Reply-To: <20141205123549.GA29331@thyrsus.com> User-Agent: Mutt/1.5.21 (2010-09-15) X-Delivery-Agent: TMDA/1.1.12 (Macallan) X-Primary-Address: acm@muc.de X-detected-operating-system: by eggs.gnu.org: FreeBSD 8.x X-Received-From: 193.149.48.1 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:178925 Archived-At: 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. > -- > Eric S. Raymond -- Alan Mackenzie (Nuremberg, Germany).