Add function to compile a README.org into a <package>.texi

DamienCassou commented 2 years ago

@minad and I recently discussed the generation of an info manual from a package's README.org. Some packages provide a README.org which can be compiled into a texi file which made me add the following to my .gitmodules file in 3 different places:

    build-step = borg-update-autoloads
    build-step = borg-compile
    build-step = (require 'ox-texinfo)
    build-step = "(save-excursion (find-file \"README.org\") (org-export-to-file 'texinfo (org-export-output-file-name \".texi\")))"
    build-step = borg-makeinfo

@minad asked me if it would make sense to add a borg-orgtotexi function that would take care of generating a texi. I think it would make sense but:

when should this function be executed? For every package automatically? Only when manually specified in build-step?
if we want to call the function automatically for all packages, we have to pay attention to a .texi file which could already be provided by the package as we wouldn't want to override that.

What do you think?

tarsius commented 2 years ago

My decision many years ago to write info manuals in org causes me frustration to this day.

If you do this and want all users to have access to the info manual then you won't get around checking in the generated texi files. Recently I have put a lot of work into overcoming this, but for now I had to suspend my efforts until the next Org release is out, at which point I might be able to do it.

Also, do not expect that those who write their info manuals in texi will consider your generated texi files to be anywhere near good enough.

It has been a time consuming and frustrating journey and by now "info from org" is pretty much my least favorite Emacs topic. I find it very hard to write about it without immediately entering rant mode.

In other words, you will get a response but it might be a while. So far I haven't even managed to properly think about what you are proposing, as I had to put all energy into containing the rant that wanted to come out.

DamienCassou commented 2 years ago

This is awesome, thank you very much!

tarsius commented 2 years ago

You are welcome!

emacscollective / borg

Add function to compile a README.org into a <package>.texi #121