From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: "Eric S. Raymond" Newsgroups: gmane.emacs.devel Subject: On being web-friendly and why info must die Date: Fri, 5 Dec 2014 07:35:49 -0500 Organization: Eric Conspiracy Secret Labs Message-ID: <20141205123549.GA29331@thyrsus.com> Reply-To: esr@thyrsus.com NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Trace: ger.gmane.org 1417782985 15542 80.91.229.3 (5 Dec 2014 12:36:25 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Fri, 5 Dec 2014 12:36:25 +0000 (UTC) To: emacs-devel@gnu.org Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Fri Dec 05 13:36:17 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 1Xws7M-0007yY-7n for ged-emacs-devel@m.gmane.org; Fri, 05 Dec 2014 13:36:16 +0100 Original-Received: from localhost ([::1]:50072 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Xws7L-0005aR-0d for ged-emacs-devel@m.gmane.org; Fri, 05 Dec 2014 07:36:15 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:53452) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Xws72-0005aD-Id for emacs-devel@gnu.org; Fri, 05 Dec 2014 07:36:01 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1Xws6w-00032B-Eg for emacs-devel@gnu.org; Fri, 05 Dec 2014 07:35:56 -0500 Original-Received: from static-71-162-243-5.phlapa.fios.verizon.net ([71.162.243.5]:54118 helo=snark.thyrsus.com) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Xws6w-00031w-41 for emacs-devel@gnu.org; Fri, 05 Dec 2014 07:35:50 -0500 Original-Received: by snark.thyrsus.com (Postfix, from userid 1000) id 46645382C02; Fri, 5 Dec 2014 07:35:49 -0500 (EST) Content-Disposition: inline X-Eric-Conspiracy: There is no conspiracy User-Agent: Mutt/1.5.21 (2010-09-15) X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 71.162.243.5 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:178912 Archived-At: Several recent posts in the metaproblem threads have had the common theme that Emacs's web resources are weak, scattered, and unfocused. In particular, guidance for new developers that should be public, prominent and webbed is buried in obscure text files deep in the Emacs source distribution. I think the major reason this has not happened is because the Emacs development culture is still largely stuck in a pre-Web mindset. There are a number of historically contingent reasons for this, but enumerating them is not really important. What matters is recognizing that this is a problem and fixing it. There are two reasons it's a problem: one of capability, one of positioning. 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? The capability problem is that the younger developers are objectively right to laugh. Because these resources are not rendered to Web, they're an informational ghetto with an impoverished internal link structure. The fact that some of them, like /etc/CONTRIBUTE, are plain text with no link structure at all certainly doesn't help. The EmacsWiki is a valiant stab at fixing part of the problem, but its utility is severely damaged by the fact that it can't readily link inwards to the stuff carried in the distribution. 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 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. 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. I'm willing to take on the tools end, but I can't do it all. Someone needs to take ownership of the policy/organization end of the documentation problem. Will any of the people righly complaining about this step up? -- Eric S. Raymond