Convert manual to GAPDoc

[olexandr-konovalov]

Keeping gapmacro-based manual has some inconveniences when one uses ReleaseTools. First, I can not publish a release from any place, since it has a relative path to gapmacro.tex. Second, symlinking the clone into gap/pkg did not help. So I had to make a new clone of the repository. Third, inside that clone I had to recreate gh-pages subdirectory with:

cd modisom
git clone git@github.com:gap-packages/modisom.git gh-pages
cd gh-pages
git fetch origin gh-pages
git checkout gh-pages

With GAPDoc, none of these steps would be needed...

[fingolfin]

You can publish a location from (almost) any place, by placing a symlink to GAP's doc dir into a suitable place (i.e., such that gapmacro.tex is found). I rely on that all the time in my local setup. No need for a new clone.

But if you make a new clone, then yeah, you need to again clone gh-pages, as described in the GitHubPagesForGAP README. But release should produce an error if one forgets to.

BTW, even with GAPDoc, one has to be very careful if one builds the package outside the GAPROOT, as there is a risk that one ends up with absolute paths in the generated HTML, namely for links to documentation in other packages, if one has any of those. I think we applied various tricks to mitigate that in AutoDoc, so if you use AutoDoc in your makedoc.g, it's indeed usually OK; but I still check for absolute paths like that in the ReleaseTools, precisely because they have a tendency to creep in again if one is no careful

[limakzi]

@olexandr-konovalov, @margollo This seems to be very valuable.
Especially that I want to and need to rewrite BinsByGT structure. 😹

Any notes / important before starting working on this?