From mboxrd@z Thu Jan 1 00:00:00 1970 From: Eric Abrahamsen Subject: Re: setting local variables Date: Thu, 03 Aug 2017 15:49:47 -0700 Message-ID: <87wp6kxo50.fsf@ericabrahamsen.net> References: <871sotiqld.fsf@ericabrahamsen.net> <87r2wsly88.fsf@nicolasgoaziou.fr> <877eykbpho.fsf@ericabrahamsen.net> <87a83gl382.fsf@nicolasgoaziou.fr> Mime-Version: 1.0 Content-Type: text/plain Return-path: Received: from eggs.gnu.org ([2001:4830:134:3::10]:42980) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1ddOxT-0004Ob-7e for emacs-orgmode@gnu.org; Thu, 03 Aug 2017 18:51:12 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1ddOxP-0000cE-Eu for emacs-orgmode@gnu.org; Thu, 03 Aug 2017 18:51:11 -0400 Received: from [195.159.176.226] (port=49965 helo=blaine.gmane.org) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1ddOxP-0000bA-8Z for emacs-orgmode@gnu.org; Thu, 03 Aug 2017 18:51:07 -0400 Received: from list by blaine.gmane.org with local (Exim 4.84_2) (envelope-from ) id 1ddOxG-0004lq-Ne for emacs-orgmode@gnu.org; Fri, 04 Aug 2017 00:50:58 +0200 List-Id: "General discussions about Org-mode." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org Sender: "Emacs-orgmode" To: emacs-orgmode@gnu.org Nicolas Goaziou writes: > Eric Abrahamsen writes: > >> Oh I don't think it's about shortcomings, just about having a version >> that's tweaked specifically for writing Emacs manuals. I _really_ want >> my packages to have info manuals, and I _really_ don't want to learn how >> to write texinfo. I saw Rasmus' Org manual in org, and it looked like a >> lot of work. Then I noticed that the Magit manuals used this >> texinfo-plus thing, and it seemed good enough. > > I think "ox-texinfo" is (almost) able to write Emacs manuals. > > IMO, you are comparing oranges and apples. Org's manual is historically > written as a (very convoluted) pure Texinfo document, with many macros > and different authors. Trying to convert it to Org for an Org to Texinfo > process is bound to be painful. OTOH, Magit's manual is probably more > straightforward, i.e., written as an Org document from the beginning, > with simpler requirements. > > In both cases, you cannot eschew learning a bit of Texinfo, if only for > the various indices commands and the installation part in the Info > directory. Well, I'll admit laziness has been my major motivation throughout the whole process. >> I think what might be nice would be to have another exporter, derived >> from ox-texinfo, specifically for writing Emacs manuals, that helps >> authors conform to the Emacs manual conventions. The way texinfo-plus >> handles lists of keybindings/user options/etc is nice, and it appears to >> set up the indexes for you, you only have to add concept index entries >> manually. > > AFAIU, the way texinfo-plus handles lists of ... is certainly nice, but > it's unrelated to Emacs manual conventions. It helps authors conform > Magit's author conventions. Those are fine, but I'm pretty sure not all > Emacs manuals follow them (Org doesn't, obviously). The main thing I was after was semi-automated indexing (obviously some of it you have to do yourself). I just looked more closely at the texi output that texinfo-plus produced, and it seems to only be doing concept and key indexing, not function or variable indexing. So that's not as helpful as I thought. >> Does that sound feasible? It would be great if this was available out of >> the box. > > Even though such specialized back-ends are a good thing, I don't think > Org needs another Texinfo back-end in core, however. > > "ox-texinfo.el" is really getting better. It is very versatile so it can > bend to almost any convention. > > I won't pretend it makes learning Texinfo useless, though, because you > need to learn it to write good manuals. The devil is in the details, and > those are sometimes located at the Texinfo level. I guess what I'm missing is clear guidelines on how to write manuals for Emacs. I did look around, didn't find anything, and then just decided I would use the easiest solution to hand, even if it wasn't ideal. If I had a clear sense of what I was working towards, I'd probably put in the time to learn the basics of texi and ox-texinfo. I guess I'll ask on emacs.help. At any rate, all this was in no way meant to be a criticism of ox-texinfo, which I obviously haven't taken the time to learn... Eric