From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: phillip.lord@newcastle.ac.uk (Phillip Lord) Newsgroups: gmane.emacs.devel Subject: Re: On being web-friendly and why info must die Date: Fri, 05 Dec 2014 14:01:00 +0000 Message-ID: <87mw72i4bn.fsf@newcastle.ac.uk> References: <20141205123549.GA29331@thyrsus.com> NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain X-Trace: ger.gmane.org 1417788087 2938 80.91.229.3 (5 Dec 2014 14:01:27 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Fri, 5 Dec 2014 14:01:27 +0000 (UTC) Cc: emacs-devel@gnu.org To: Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Fri Dec 05 15:01:22 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 1XwtRg-0006TZ-5Z for ged-emacs-devel@m.gmane.org; Fri, 05 Dec 2014 15:01:20 +0100 Original-Received: from localhost ([::1]:50568 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1XwtRf-0005F6-Rs for ged-emacs-devel@m.gmane.org; Fri, 05 Dec 2014 09:01:19 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:41975) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1XwtRW-00057U-LQ for emacs-devel@gnu.org; Fri, 05 Dec 2014 09:01:16 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1XwtRQ-0004By-Rg for emacs-devel@gnu.org; Fri, 05 Dec 2014 09:01:10 -0500 Original-Received: from cheviot22.ncl.ac.uk ([128.240.234.22]:35057) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1XwtRQ-0004Bs-Md for emacs-devel@gnu.org; Fri, 05 Dec 2014 09:01:04 -0500 Original-Received: from smtpauth-vm.ncl.ac.uk ([10.8.233.129] helo=smtpauth.ncl.ac.uk) by cheviot22.ncl.ac.uk with esmtp (Exim 4.63) (envelope-from ) id 1XwtRN-0005h4-DK; Fri, 05 Dec 2014 14:01:01 +0000 Original-Received: from jangai.ncl.ac.uk ([10.66.67.223] helo=localhost) by smtpauth.ncl.ac.uk with esmtpsa (TLSv1:AES128-SHA:128) (Exim 4.63) (envelope-from ) id 1XwtRM-00073c-S9; Fri, 05 Dec 2014 14:01:00 +0000 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.13 (Gnus v5.13) Emacs/24.3 (gnu/linux) X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6.x X-Received-From: 128.240.234.22 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:178920 Archived-At: "Eric S. Raymond" writes: > 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. I've written quite a lot of asciidoc in my time. It's not a bad format, although it is not extensible, so I have resorted at times to using gpp on source to get what I want (which messes up line numbers in error reports, so there are problems with this approach). Emacs support for asciidoc is not that good, to my knowledge. I have been using adoc-mode, which does good syntax highlighting but is poor for cross-referencing for instance. It also has a hang emacs bug (there is a fix in my fork). So, I suspect that this would need fixing. I recently went through these issues with a book I am writing. My experiences are here. http://www.russet.org.uk/blog/3020 I ended up with latex, although for documentation (which is much less linear) I might reach a different conclusion. In particular, I would ask about org -- the tools here already exist and the emacs support is obviously good. > 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? I am almost certainly not the person to do this, but I am willing to contribute to the documentation. I write well, or at least I think I do but then who doesn't. Phil