From mboxrd@z Thu Jan 1 00:00:00 1970 From: Achim Gratz Subject: Re: [RFC] Moving "manual.org" into core Date: Sat, 20 Jan 2018 18:41:26 +0100 Message-ID: <87tvvgmnqx.fsf@Rainer.invalid> References: <87bmhooaj9.fsf@nicolasgoaziou.fr> Mime-Version: 1.0 Content-Type: text/plain Return-path: Received: from eggs.gnu.org ([2001:4830:134:3::10]:42496) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1ecx9M-00062T-15 for emacs-orgmode@gnu.org; Sat, 20 Jan 2018 12:41:54 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1ecx9I-0006Gv-Ia for emacs-orgmode@gnu.org; Sat, 20 Jan 2018 12:41:52 -0500 Received: from [195.159.176.226] (port=57083 helo=blaine.gmane.org) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1ecx9I-0006G7-AS for emacs-orgmode@gnu.org; Sat, 20 Jan 2018 12:41:48 -0500 Received: from list by blaine.gmane.org with local (Exim 4.84_2) (envelope-from ) id 1ecx7F-0006GR-1D for emacs-orgmode@gnu.org; Sat, 20 Jan 2018 18:39:41 +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: emacs-orgmode@gnu.org Nicolas Goaziou writes: > "manual.org" was updated a month ago, and, so far, nobody complained > about it. So, I think it's a good time to discuss about what could be > done next. The lack of complaints is unlikely to mean that everybody tried it and found nothing to complain about. I haven't had much time to do anything with it so far, but I did at least check that I could use the build system extension that I created while Tom was working on his version with it. The export to texi is still relatively slow, but since I have a much faster machine now it works OK for me. I have not yet tried how long it would take on my old machine. > The first obvious step is to move the file into "doc/" directory. Then > I assume we could delete "org.texi" and "org.info" there and generate > new ones from the Org file. For example, the following command, called > from the "manual.org" file, > > (let ((org-texinfo-logfiles-extensions > (cons "texi" org-texinfo-logfiles-extensions))) > (org-texinfo-export-to-info)) > > produces an "org.info" file without an "org.texi". It thus prevents > direct editing of "org.texi". I assume this could be called by "make > info" target. Maybe not directly in the way you show it here, but yes. For the record, the build system extension from years ago involves creating a directory orgmanual, then you should symlink orgmanual.org to the actual file in contrib/, then put the follwing Makefile there: --8<---------------cut here---------------start------------->8--- TEXI2PDF+=--tidy BEXP=$(BATCH) \ --eval '(add-to-list '"'"'load-path "../lisp")' \ --eval '(setq org-footnote-auto-adjust nil)' EXTEXI= -l ox-texinfo \ --eval '(add-to-list '"'"'org-export-snippet-translation-alist '"'"'("info" . "texinfo"))' EXHTML= -l ox-html \ $(BTEST_POST) \ --eval '(add-to-list '"'"'org-export-snippet-translation-alist '"'"'("info" . "texinfo"))' ORG2TEXI=-f org-texinfo-export-to-texinfo ORG2HTML=-f org-html-export-to-html ORG2INFO=--eval "(org-texinfo-compile \"./$<\")" .SUFFIXES: # we don't need default suffix rules ifeq ($(MAKELEVEL), 0) $(error This make needs to be started as a sub-make from the toplevel directory.) endif .PHONY: all info html pdf all: $(ORG_MAKE_DOC) info: org.info html: orgmanual org.html pdf: org.pdf org.texi: orgmanual.org $(BEXP) $(EXTEXI) $< $(ORG2TEXI) org.info: org.texi $(MAKEINFO) --no-split $< -o $@ # LANG=C # to work around a bug in texi2dvi org.pdf: LC_ALL=C org.pdf: LANG=C org.pdf: org.texi $(TEXI2PDF) $< orgmanual: org.texi $(TEXI2HTML) $< -o $@ org.html: orgmanual.org $(BEXP) $(EXHTML) $< $(ORG2HTML) clean: $(RM) org org.t2d *.pdf *.html *.texi *.info *~ \ *.aux *.cp *.cps *.dvi *.fn *.fns *.ky *.kys *.pg *.pgs \ *.toc *.tp *.tps *.vr *.vrs *.log *.html *.ps cleanall: clean $(RMR) org.t2d orgmanual --8<---------------cut here---------------start------------->8--- Then add the following to local.mk --8<---------------cut here---------------end--------------->8--- .PHONY: orgmanual EXTRADIRS=orgmanual orgmanual: $(MAKE) -C $@ manclean: $(MAKE) -C orgmanual clean mancleanall: $(MAKE) -C orgmanual cleanall clean: manclean cleanall: mancleanall --8<---------------cut here---------------end--------------->8--- You can now say "make orgmanual" and have it do the right thing. YOu could even further extend local.mk so that the "doc" target includes the new manual by adding this line: --8<---------------cut here---------------end--------------->8--- doc: orgmanual --8<---------------cut here---------------end--------------->8--- The whole thing can easily be adapted to work in doc/ if it gets decided that we should switch to manual.org (or better org.org maybe) as our primary source file. > So basically, the idea would be to not provide anymore an "org.texi" > file. Only "manual.org" and "org.info". Emacs developers already apply > fixes to ORG-NEWS, which is a plain Org file, so I guess it would not > make their life harder if "manual.org" replaces "org.texi". Yes, once the org file is our primary source we should stop provding the texi file in Git at least. I don't have any preference w.r.t. whether an Org release tarball should still contain an org.texi or not, but that's a separate decision. I suspect that not delivering it would inconvenience at least the Debian folks somewhat since they keep insisting to use their own build recipes last I looked. Last but not least we'll have to check if we need any modifications for the ELPA distributions. Regards, Achim. -- +<[Q+ Matrix-12 WAVE#46+305 Neuron microQkb Andromeda XTk Blofeld]>+ Wavetables for the Waldorf Blofeld: http://Synth.Stromeko.net/Downloads.html#BlofeldUserWavetables