From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: joakim@verona.se Newsgroups: gmane.emacs.devel Subject: Re: On being web-friendly and why info must die Date: Fri, 05 Dec 2014 13:46:04 +0100 Message-ID: References: <20141205123549.GA29331@thyrsus.com> NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain X-Trace: ger.gmane.org 1417783626 26333 80.91.229.3 (5 Dec 2014 12:47:06 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Fri, 5 Dec 2014 12:47:06 +0000 (UTC) Cc: Nic Ferrier , 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 13:46:59 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 1XwsHi-0004QY-NK for ged-emacs-devel@m.gmane.org; Fri, 05 Dec 2014 13:46:59 +0100 Original-Received: from localhost ([::1]:50087 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1XwsHi-0007NX-C3 for ged-emacs-devel@m.gmane.org; Fri, 05 Dec 2014 07:46:58 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:55255) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1XwsHM-0007NB-VR for emacs-devel@gnu.org; Fri, 05 Dec 2014 07:46:44 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1XwsHF-0006im-Mr for emacs-devel@gnu.org; Fri, 05 Dec 2014 07:46:36 -0500 Original-Received: from mx6.bahnhof.se ([213.80.101.16]:42716) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1XwsHF-0006ic-CI for emacs-devel@gnu.org; Fri, 05 Dec 2014 07:46:29 -0500 Original-Received: from localhost (mf.bahnhof.se [213.80.101.20]) by mx6-reinject (Postfix) with ESMTP id E37FD41968; Fri, 5 Dec 2014 13:46:25 +0100 (CET) X-Virus-Scanned: by amavisd-new using ClamAV at bahnhof.se (MF4) Original-Received: from mf4.bahnhof.se ([127.0.0.1]) by localhost (mf4.bahnhof.se [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id eVl9ZIF1ERXU; Fri, 5 Dec 2014 13:46:15 +0100 (CET) Original-Received: from mta.verona.se (h-235-102.a149.priv.bahnhof.se [85.24.235.102]) by mf4.bahnhof.se (Postfix) with ESMTP id 6C76C3D787D; Fri, 5 Dec 2014 13:46:15 +0100 (CET) Original-Received: from localhost (unknown [127.0.0.1]) by mta.verona.se (Postfix) with ESMTP id 3CF4F5273E1; Fri, 5 Dec 2014 12:46:15 +0000 (UTC) X-Virus-Scanned: amavisd-new at verona.se Original-Received: from mta.verona.se ([127.0.0.1]) by localhost (exodia.verona.se [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id v19cmZVRjBn7; Fri, 5 Dec 2014 13:46:04 +0100 (CET) Original-Received: from exodia.verona.se (www.verona.se [192.168.200.15]) by mta.verona.se (Postfix) with ESMTP id 8BC505273E2; Fri, 5 Dec 2014 13:46:04 +0100 (CET) In-Reply-To: <20141205123549.GA29331@thyrsus.com> (Eric S. Raymond's message of "Fri, 5 Dec 2014 07:35:49 -0500") User-Agent: Gnus/5.130012 (Ma Gnus v0.12) Emacs/24.4.50 (gnu/linux) X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 213.80.101.16 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:178913 Archived-At: "Eric S. Raymond" writes: please see nics work in this area. > 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? -- Joakim Verona