Update tools for building the manual

[tarsius]

Use Ox-Texinfo+ to build the manual. It looks like you were planning on doing that anyway but got stuck halfway through when setting up the build tools.

Instructions on how to use Ox-Texinfo+ can be found at https://github.com/magit/magit/wiki/Documentation-tools-and-conventions.

The additions to the Makefile and the boilerplate in the manual are based on what I use for many other packages that come with a proper manual. I have left out the parts that are not necessary to build the manual.

The generated Texi file has to be checked in because Melpa does not support generating exporting the Org file as Texi.

I have added many FIXMEs to "magithub.org", primarily to mark incomplete "Key" items (the command is required).

[vermiculus]

You are an amazing human being; I was hitting my head against this problem for hours before I eventually gave up to do something less... opaque to me :-) (This was before the wiki page over on Magit, I think.)

I can go through and fix all the FIXMEs right before merge. Is there anything that has to be done to the MELPA recipe to install the info manual? (Possibly something here as well, but it doesn't look like Magit's doing that thing, either; Magit's manual is also not available to me. I've asked a small follow-up question at https://emacs.stackexchange.com/q/26631/2264.)

Thank you, seriously. When I saw this notification, you made my day.

[vermiculus]

Here's a question -- how would you recommend documenting documenting the configuration variables I'm using with magit-popup? The commands themselves are internal-scoped (e.g., magithub-settings--set-magithub\.enabled) and feel weird to document as commands.

[vermiculus]

Is there a minimum required makeinfo version?

$ make doc
Generating magithub.info
magithub.texi:6: warning: unrecognized encoding name `UTF-8'.
Generating dir
Generating magithub.html
makeinfo: unrecognized option `--css-ref'
Try `makeinfo --help' for more information.
make: *** [magithub.html] Error 1
$ makeinfo --version
makeinfo (GNU texinfo) 4.8

Copyright (C) 2004 Free Software Foundation, Inc.
There is NO warranty.  You may redistribute this software
under the terms of the GNU General Public License.
For more information about these matters, see the files named COPYING.

[tarsius]

Looks like it. I have

[~] % makeinfo --version
texi2any (GNU texinfo) 6.3

Copyright (C) 2016 Free Software Foundation, Inc.
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.

[vermiculus]

Cool, that was the issue there. make doc works like a charm now.

For my own reference, it doesn't look like Texinfo has a good way to represent conffile variables like this. I'll probably just have to come up with a system (or perhaps enhance Texinfo/ox-texinfo+ to establish a format -- might require a TeX macro).

It does look like the manuals have made themselves available (don't know what was happening last night), so I took the liberty of looking at Ghub and it doesn't seem like it's doing anything special to include itself in Info-directory-list. Probably taken care of by package.el would be my guess.

[tarsius]

Probably taken care of by package.el would be my guess.

Yes, that does create the *.info and dir files and add an entry to Info-directory-list. So does borg. Our Makfile should still generate the dir file though, in case it is missing after make clean. (Which reminds me, I think I forgot to update that.)