From mboxrd@z Thu Jan 1 00:00:00 1970 From: Nicolas Goaziou Subject: Re: [RFC] Moving "manual.org" into core Date: Mon, 05 Mar 2018 15:20:59 +0100 Message-ID: <87k1uq4n90.fsf@nicolasgoaziou.fr> References: <87bmhooaj9.fsf@nicolasgoaziou.fr> <87y3j8dw45.fsf@bzg.fr> <87lgf8f93b.fsf@nicolasgoaziou.fr> <87lgf89lro.fsf@gnu.org> Mime-Version: 1.0 Content-Type: text/plain Return-path: Received: from eggs.gnu.org ([2001:4830:134:3::10]:54079) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1esqzB-0002JY-RR for emacs-orgmode@gnu.org; Mon, 05 Mar 2018 09:21:07 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1esqzA-0007h6-JD for emacs-orgmode@gnu.org; Mon, 05 Mar 2018 09:21:05 -0500 In-Reply-To: <87lgf89lro.fsf@gnu.org> (Bastien's message of "Sun, 04 Mar 2018 11:29:31 +0100") 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: Bastien Cc: Glenn Morris , Achim Gratz , Org Mode List Hello, Bastien writes: > But I'm sure there will be some. True, as I'm sure there are some "challenges" with the current Texinfo manual. Therefore, I do not see the point of insisting on the fact that a new paradigm brings new problems. > I don't have strong opinions on this issue. I read it otherwise. > When I said "Let's test org capabilities against a giant .org file." > I was not just thinking about editing it, but also e.g. exporting. Spending time on the Org version of the manual included exporting it on a regular basis. > Testing the .texi exporter (and maybe .html and .pdf) against this big > file will be interesting. This is what I am asking for since I announced the Org manual was ready. Have you tried to export it? Have you looked at the generated Info manual? Does it look so unsatisfying to you? > Testing the process of running "make pdf" while emacs will in charge > of producing a PDF file (.org => .texi => .pdf) will be interesting, > and potentially more error-prone than the current .texi=>.pdf process. I didn't invest time in the Makefile, so I don't know. > I have not read the conventions yet, and other contributors may not > have read them, so this those conventions are just a proposal for now. > Core contributors need to formally discuss them and explicitely agree. If you want to actually do something, you need to make choices. I made them. Some are arbitrary, other are a result of trial and error, some are even the result of a thinking process. You can of course spend energy and time to discuss every single convention I used, although I suggest to spend them elsewhere. Moreover, if you have better conventions, feel free to apply them thoroughly and document them. Let's just move forward, really. > Again, the question is: what problem are we trying to solve? Org boasts itself as a format to write, among other things, documentation. Do you think it is confidence-inspiring if we do not write our own documentation in our format? See also . This problem is now solved. Also, no matter how you look at it, doing any non-trivial edit in "org.texi" is painful. I want to ease that pain for current contributors (at least me), too. > Do you agree with the one I suggested? I disagree. My motivation is not to attract more contributors. I don't think this was Thomas and Jonathan's motivation when they started the project either, but I may be wrong. Having more manual contributors would be a nice side-effect. However, I'm opposed to consider it as a good measurement for the switch. Also, I'm not suggesting to get rid of "org.texi". I'm suggesting to generate it from "manual.org" and to avoid as much as possible editing it manually thereafter. In practice, this change is so small that I do not understand what all this fuss is about. This should be simple: move "manual.org" to doc/, overwrite "org.texi", and, when we feel confident enough, if it ever happens, remove "org.texi" altogether from the repository, generating it only before bundling a new Org release or merging it with Emacs. Regards, -- Nicolas Goaziou 0x80A93738