From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: David Kastrup Newsgroups: gmane.emacs.devel Subject: Re: On being web-friendly and why info must die Date: Fri, 05 Dec 2014 22:23:13 +0100 Message-ID: <877fy5sse6.fsf@fencepost.gnu.org> References: <20141205123549.GA29331@thyrsus.com> <2815659.zRQ0WWWeRr@descartes> <87bnnirso0.fsf@fencepost.gnu.org> <3685170.jtTJPXXftF@descartes> NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=iso-8859-1 Content-Transfer-Encoding: quoted-printable X-Trace: ger.gmane.org 1417814658 30816 80.91.229.3 (5 Dec 2014 21:24:18 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Fri, 5 Dec 2014 21:24:18 +0000 (UTC) Cc: emacs-devel@gnu.org To: =?iso-8859-1?Q?R=FCdiger?= Sonderfeld Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Fri Dec 05 22:24:11 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 1Xx0MF-0008Mb-1t for ged-emacs-devel@m.gmane.org; Fri, 05 Dec 2014 22:24:11 +0100 Original-Received: from localhost ([::1]:52519 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Xx0ME-0000hP-Jt for ged-emacs-devel@m.gmane.org; Fri, 05 Dec 2014 16:24:10 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:46024) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Xx0Lw-0000f1-P7 for emacs-devel@gnu.org; Fri, 05 Dec 2014 16:23:53 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1Xx0Lv-0003ot-1x for emacs-devel@gnu.org; Fri, 05 Dec 2014 16:23:52 -0500 Original-Received: from fencepost.gnu.org ([208.118.235.10]:56956) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Xx0Lu-0003oi-Qn for emacs-devel@gnu.org; Fri, 05 Dec 2014 16:23:50 -0500 Original-Received: from localhost ([127.0.0.1]:34353 helo=lola) by fencepost.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Xx0Lu-0000IJ-7P; Fri, 05 Dec 2014 16:23:50 -0500 Original-Received: by lola (Postfix, from userid 1000) id 47ADEE0A31; Fri, 5 Dec 2014 22:23:13 +0100 (CET) In-Reply-To: <3685170.jtTJPXXftF@descartes> (=?iso-8859-1?Q?=22R=FCdiger?= Sonderfeld"'s message of "Fri, 05 Dec 2014 18:12:27 +0100") User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/25.0.50 (gnu/linux) X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6.x X-Received-From: 208.118.235.10 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:179019 Archived-At: R=FCdiger Sonderfeld writes: > I think Texinfo itself has a few issues as well. I only started using > it to write documentation for the 24.4 release. What I consider the main nuisance right now is indexing. Texinfo itself is affected: you'd want to have an index entry for @it that is called @it (and accessible from M-x info via i @it) but sorted under i (since otherwise the index will basically just be full of @). Texinfo 5 might be more amenable to making the indexing more flexible. It's definitely also a nuisance for LilyPond (where we are talking about the indexing of things like \relative, namely same indexing problem but with a backslash as starter). > I think Cross References (aka links) are a bit confusing. Copy&paste from the info manual of Texinfo (as rendered by M-x info, namely info format) is somewhat surreal regarding the mismatch between the claims in the text and the actual output: 8.6 '@ref' =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D '@ref' is nearly the same as '@xref' except that it does not generate a 'See' in the printed output, just the reference itself. This makes it useful as the last part of a sentence. For example, For more information, @pxref{This}, and @ref{That}. produces in Info: For more information, *note This::, and *note That::. and in printed output: For more information, see Section 1.1 [This], page 1, and Section 1.2 [That], page 2. The '@ref' command can tempt writers to express themselves in a manner that is suitable for a printed manual but looks awkward in the Info format. Bear in mind that your audience could be using both the printed and the Info format. For example: Sea surges are described in @ref{Hurricanes}. looks ok in the printed output: Sea surges are described in Section 6.7 [Hurricanes], page 72. but is awkward to read in Info, "note" being a verb: Sea surges are described in *note Hurricanes::. > Using a more popular language could lower the entry barrier. HTML isn't an input language. And AsciiDoc can hardly be called "more popular". > But then again I have a bit of a doubt that a change to a different > format would really attract more people to writing documentation More like "different people". > and on the other hand it would certainly be a hassle for the majority > of people already writing documentation. When there are sizable numbers. There is of course an ephemeral benefit for this kind of "let's switch to something new" activism if basically very little new material is being written in the current format, one can batch-convert to a new input format and the new input format has a few manyears of enthusiasm in it before the documentation writer base sizzles out into into the same manpower that the old documentation crew had at the point of change. I don't see that AsciiDoc buys us even that. --=20 David Kastrup