Documentation tools and conventions
The source file for the Magit manual is magit.org (located in
docs/). In a first step that file is converted to
magit.texi, and in a second step that in turn is converted to
magit.info, magit.pdf, magit.html and magit/*.html.
Between those files you should only ever edit magit.org by hand.
Note that these instructions also apply to the manuals of some of my other packages.
magit.org is exported to magit.texi using Org mode’s export feature
(specifically the texinfo exporter). Currently this requires the
development version of Org (at least release_9.5.2-390-g282a01f22).
If you don’t want to, you don’t have to install Org’s development
version. Just edit magit.org and leave the rest to us. We will then
run the commands described below and amend the generated changes to
your commit before merging them.
Even though magit.texi is a generated file we have to track it in the
repository. Neither Melpa nor package.el support using Org export to
convert *.org files to *.texi. Because of that the generated file
currently has to be checked into Git. I am trying to change that but
it is an uphill battle.
Assuming that a suitable version of Org has been installed, you can
generate magit.texi by pressing C-c C-e i t in the buffer visiting
magit.org. To also generate magit.info, use C-c C-e i i.
On the command line you can update just magit.texi using:
make texi
Or magit.texi as well as magit.info using:
make texi info
Note that you have to specify both targets. texi is not a
dependency of info, because if it were, then users would need the
latest Org release to generate the manual.
