From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.devel Subject: Re: On being web-friendly and why info must die Date: Wed, 17 Dec 2014 17:39:00 +0200 Message-ID: <8361dawajv.fsf@gnu.org> References: <20141205123549.GA29331@thyrsus.com> <2815659.zRQ0WWWeRr@descartes> <20141205175810.GD3120@thyrsus.com> <87wq66ufyt.fsf@wanadoo.es> <87zjb04tlw.fsf@gmx.us> <87bnnfve9c.fsf@dod.no> <871to5kt1a.fsf@newcastle.ac.uk> <87y4q8yi4j.fsf@newcastle.ac.uk> <871tnywkjt.fsf@newcastle.ac.uk> Reply-To: Eli Zaretskii NNTP-Posting-Host: plane.gmane.org X-Trace: ger.gmane.org 1418830784 25946 80.91.229.3 (17 Dec 2014 15:39:44 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Wed, 17 Dec 2014 15:39:44 +0000 (UTC) Cc: emacs-devel@gnu.org, sb@dod.no, rms@gnu.org, kyle.c.andrews@gmail.com To: phillip.lord@newcastle.ac.uk (Phillip Lord) Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Wed Dec 17 16:39:36 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 1Y1GhM-0003F9-4V for ged-emacs-devel@m.gmane.org; Wed, 17 Dec 2014 16:39:36 +0100 Original-Received: from localhost ([::1]:50292 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Y1GhL-0004ad-In for ged-emacs-devel@m.gmane.org; Wed, 17 Dec 2014 10:39:35 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:33835) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Y1Gh2-0004aI-Jg for emacs-devel@gnu.org; Wed, 17 Dec 2014 10:39:21 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1Y1Ggw-0004zq-0A for emacs-devel@gnu.org; Wed, 17 Dec 2014 10:39:16 -0500 Original-Received: from mtaout26.012.net.il ([80.179.55.182]:37132) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Y1Ggv-0004zN-KF; Wed, 17 Dec 2014 10:39:09 -0500 Original-Received: from conversion-daemon.mtaout26.012.net.il by mtaout26.012.net.il (HyperSendmail v2007.08) id <0NGQ00C00GN4U500@mtaout26.012.net.il>; Wed, 17 Dec 2014 17:38:15 +0200 (IST) Original-Received: from HOME-C4E4A596F7 ([87.69.4.28]) by mtaout26.012.net.il (HyperSendmail v2007.08) with ESMTPA id <0NGQ007JNGRRZ650@mtaout26.012.net.il>; Wed, 17 Dec 2014 17:38:15 +0200 (IST) In-reply-to: <871tnywkjt.fsf@newcastle.ac.uk> X-012-Sender: halo1@inter.net.il X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6.x X-Received-From: 80.179.55.182 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:180229 Archived-At: > From: phillip.lord@newcastle.ac.uk (Phillip Lord) > Date: Wed, 17 Dec 2014 12:03:02 +0000 > Cc: kyle.c.andrews@gmail.com, sb@dod.no, emacs-devel@gnu.org > > > > I find texinfo a fairly busy format because of all the menus and node > > > information. > > > > I'm sorry you dislike it, but that information has to be specified > > in the manual source somehow. > > No, it really doesn't. I think you only say that because you consider a subset of Texinfo's capabilities wrt document structuring, and/or assume that such a subset is all that's needed. See below. > Well, Eli says that this is a non-issue because Emacs can put it in > place with a few keypresses. Okay, well, why does Emacs have to do it? > Why does texinfo not do the job? It does. > Consider this snippet.... > > @node Abbrevs > @chapter Abbrevs > > A defined @dfn{abbrev} is a word which @dfn{expands}, if you insert > it, into some different text. > > @menu > * Abbrev Concepts:: Fundamentals of defined abbrevs. > * Defining Abbrevs:: Defining an abbrev, so it will expand when typed. > @end menu > > @node Abbrev Concepts > @section Abbrev Concepts > > An @dfn{abbrev} is a word that has been defined to @dfn{expand} into > a specified @dfn{expansion}. > > > In org this would be: > > * Abbrevs > > A defined \abbrev\ is a word which \expands\, if you insert it into some > different text. > > ** Abbrev Concepts > > An \abbrev\ is a word that has been defined to \expand\ into a > specificed \expansion\. > > > Now, I agree that the loss of semantics from @dfn is not good. But org > (or markdown or asciidoc or latex) can work out the navigation from the > document structure. So does 'makeinfo', but I guess you are not aware of that. I explain a little bit of that below, but there's more to Texinfo than meets the eye, so you are encouraged to study it in more detail, because IMO criticizing Texinfo without detailed knowledge of its features frankly doesn't feel right. What you wrote above in Org format defines a chapter and its subordinate section. And that's the _only_ structure supported by the above paradigm: a tree, whereby the child nodes must immediately follow their parents, in the depth-first order. By contrast, Texinfo manuals do not have to have a tree structure. Their structure can be an arbitrary graph. At least one popular Info manual (info.info) actually uses this feature: it doesn't present a tree-like structure, but instead has a cycle or two within it. _That_ is why there are node pointers in Texinfo. And what the Emacs commands I briefly mentioned do is create them automatically on the assumption that the manual structure is indeed a simple tree. Moreover, as long as the structure is indeed a tree, and the menus (see below) are correctly written in each parent node naming its child nodes, the Prev/Next/Up node pointers are not needed at all, because 'makeinfo' will deduce them automatically, and also validate the document structure as a nice bonus. As for menus, they provide one more degree of freedom for arranging a manual in a non-tree structure: each menu item is a link to another node, and can in general lead anywhere, including to another manual. AFAIK, to do that in Org, you need to create a link; the outline-style document you show above won't cut it. IOW, Org requires you in that case to insert links very similar to Texinfo menus. As with node pointers, the Emacs Texinfo mode commands can automatically create the menus as well, again on the assumption that the section nodes immediately following a chapter node are child nodes of that chapter, recursively. Thus, in simple tree-like documents, generating these menus is a keystroke away. So, as you see, both Org and Texinfo solve the same problems, and they do that in similar, albeit different, ways. I see no advantage to Org methods here, as long as you consider Texinfo together with its Emacs support. On the contrary, I see an advantage to Texinfo, because it can easily express non-tree structured documents, something that in Org is not so easy, perhaps even not easy at all.