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

[Nicolas Goaziou <mail@nicolasgoaziou.fr>]

Hello,

Achim Gratz <Stromeko@nexgo.de> writes:

Thank you for your answer. Some comments follow.

> The lack of complaints is unlikely to mean that everybody tried it and
> found nothing to complain about.

I didn't imply anything like that.

> The export to texi is still relatively slow,

I don't think it is much of a concern, since generating the texi file
only happens once in a while.

>> 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:
>
> TEXI2PDF+=--tidy
> BEXP=$(BATCH) \
> 	--eval '(add-to-list '"'"'load-path "../lisp")' \
> 	--eval '(setq org-footnote-auto-adjust nil)'

The second "--eval" is not needed.

> 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"))'

Both EXTEXI and EXHTML are not needed either.

> ORG2TEXI=-f org-texinfo-export-to-texinfo

Actually, I have another idea. We could implement a function generating
the manual, right in Org core. It can be useful for both packaging, like
the above, and for developers, who can update the manual on the fly.

Assuming the function above is called `org-generate-manuals', and
manual.org is located in doc/, what changes would be needed? I assume
they would be minimal.

> ORG2HTML=-f org-html-export-to-html

I think HTML should still be generated from the texi file. I assume
there is some compatibility to preserve among GNU manuals.

> ORG2INFO=--eval "(org-texinfo-compile \"./$<\")"

See above.

> 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.

What kind of modifications do you have in mind?

Regards,

-- 
Nicolas Goaziou