Re: [RFC] Moving "manual.org" into core

[Achim Gratz <Stromeko@nexgo.de>]

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