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: Mon, 08 Dec 2014 18:08:26 +0200 Message-ID: <83ppbuxgxx.fsf@gnu.org> References: <20141205123549.GA29331@thyrsus.com> <2815659.zRQ0WWWeRr@descartes> <20141205175810.GD3120@thyrsus.com> <87lhmlncb1.fsf@earlgrey.lan> <20141205193643.GB5067@thyrsus.com> <83egsd3kyi.fsf@gnu.org> <871toapbh9.fsf@newcastle.ac.uk> Reply-To: Eli Zaretskii NNTP-Posting-Host: plane.gmane.org X-Trace: ger.gmane.org 1418055231 30860 80.91.229.3 (8 Dec 2014 16:13:51 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Mon, 8 Dec 2014 16:13:51 +0000 (UTC) Cc: esr@thyrsus.com, cwebber@dustycloud.org, emacs-devel@gnu.org, ruediger@c-plusplus.de To: phillip.lord@newcastle.ac.uk (Phillip Lord) Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Mon Dec 08 17:13:42 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 1Xy0wN-0005Dl-Jr for ged-emacs-devel@m.gmane.org; Mon, 08 Dec 2014 17:13:39 +0100 Original-Received: from localhost ([::1]:34769 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Xy0wM-00013O-Vp for ged-emacs-devel@m.gmane.org; Mon, 08 Dec 2014 11:13:38 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:40859) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Xy0ra-0002XT-0F for emacs-devel@gnu.org; Mon, 08 Dec 2014 11:08:46 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1Xy0rV-0002DG-Kg for emacs-devel@gnu.org; Mon, 08 Dec 2014 11:08:41 -0500 Original-Received: from mtaout23.012.net.il ([80.179.55.175]:61746) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Xy0rV-0002DB-6c for emacs-devel@gnu.org; Mon, 08 Dec 2014 11:08:37 -0500 Original-Received: from conversion-daemon.a-mtaout23.012.net.il by a-mtaout23.012.net.il (HyperSendmail v2007.08) id <0NG900F00U534400@a-mtaout23.012.net.il> for emacs-devel@gnu.org; Mon, 08 Dec 2014 18:08:35 +0200 (IST) Original-Received: from HOME-C4E4A596F7 ([87.69.4.28]) by a-mtaout23.012.net.il (HyperSendmail v2007.08) with ESMTPA id <0NG900F7AU6A0A70@a-mtaout23.012.net.il>; Mon, 08 Dec 2014 18:08:35 +0200 (IST) In-reply-to: <871toapbh9.fsf@newcastle.ac.uk> X-012-Sender: halo1@inter.net.il X-detected-operating-system: by eggs.gnu.org: Solaris 10 X-Received-From: 80.179.55.175 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:179405 Archived-At: > From: phillip.lord@newcastle.ac.uk (Phillip Lord) > Cc: , , , > Date: Mon, 08 Dec 2014 12:33:38 +0000 > > Eli Zaretskii writes: > > >> > But a lot of this is cosmetic. We could improve Texinfo to look much > >> > better probably (and that would positively affect a lot of existing GNU > >> > projects). > >> > >> But it would still be Texinfo, still be an essentially pointless > >> barrier to learning how to contribute. > > > > Nonsense. What evidence do you have to back that up? > > I think it is intrinsically hard to get evidence for why people do NOT > do something. What I had in mind was some evidence, even anecdotal one, that people considered contributing a chunk of docs, but decided against that because of Texinfo. > I did try and learn texinfo once, but stopped. I could never understand > why it had all the menu stuff in it. Running occur gives me this... > > 4 matches for "List Processing" in buffer: emacs-lisp-intro.texi > 238:* List Processing:: What is Lisp? > 277:List Processing > 998:@node List Processing > 999:@chapter List Processing > > Can it really be the case that the same text appears four times? Yes. > If I use latex, I just do "\tableofcontents". I think you are misinterpreting what you see. The first and the second "List Processing" hits will be produced automatically by a suitable command of Texinfo mode -- that's the moral equivalent of your "\tableofcontents". The 4th one could be a different string (there's no requirement that a node and its chapter/section have the same name, and more often than not they don't), but the author decided to use the same text for both in this case. The 3rd one is the only one you need to write by hand. > Texinfo seems to totally conflate document structure and > navigation. I just want to maintain one of these. Not sure what you mean by that, please clarify. A Texinfo document's structure is a graph of nodes, each node is a chapter/section/subsection. (Usually, the graph is actually a tree, but that's not a requirement, and at least one popular manual I know of does not present a tree.) You can navigate a Texinfo document in any way you want, either via next/prev/up/down links or any other way. Following the links takes you in the same order as you'd read a book, should the document be printed. > Texinfo seems to have all the complexity of latex with less of the > advantages. The advantage is that it is simpler and easier to learn. Of course, if you are already a TeX/LaTeX user, this is not a real advantage, but it is definitely an advantage when you ask code developers, which mostly don't use LaTeX, to provide documentation for their code. > Everything that has been said about the indexing in info is entirely > true. Like everyone else, I navigate extensively with indexing; > although, perhaps this is partly because info doesn't do inline > hyperlinks. Imagine: > > "At any time, one window is the "selected window". On a graphical > display, the selected window shows a more prominent cursor (usually > solid and blinking) > > like: > > "At any time, one window (see Windows) is the "selected window" (see > selected-window). On a graphical display (see Graphical Display), > the selected window (see selected-window) shows a more prominent > cursor (set Cursor) (usually solid and blinking (see set-cursor-color)" > > Unreadable right? Now, if info used wiki style hyperlinks, maybe I would > never use the index explicitly. What you show above aren't index links, they are direct hyperlinks to other places in text. Indexing is not visible in the formatted document (except in the Index node, which is auto-generated), only in the Texinfo source. And Info does support such "inline hyperlinks". Here's an example (in Texinfo; you need to format it and view in Emacs to see the results): "At any time, one @ref{Windows, window} is the "@ref{selected-window, selected window}". On a @ref{Graphical Display, graphical display}, the selected window shows a more prominent @ref{Cursor, cursor} (usually solid and blinking, @pxref{set-cursor-color}). (The node names are not visible when you read the Info document in Emacs, so only the hyperlinks remain.) Okay? > As it stands, though, if I were starting a new project, I cannot see > why I would start off with texinfo. We are not starting a new project; that would be a whole different ball game. > Does this make it worth changing from? That's a much harder question. Well, that's the question discussed here. Texinfo is well known to people who work on Emacs documentation, and it has excellent support in Emacs (Texinfo mode) that alleviates many aspects of Texinfo people consider to be disadvantages.