Obsoleting gapmacro.tex

[olexandr-konovalov]

I compiled a list of packages still not using GAPDoc.

It was luck that thanks to @bh11 a couple of issues with gapmacro.tex were resolved, but I would like to remind that we do not support gapmacro.tex since GAP 4.5, and only provide it for backwards compatibility for authors of the packages listed above. I am creating this issue in order to monitor the progress of the transition to GAPDoc. The first candidates for the conversion are likely those packages with their names hyperlinked to GitHub repositories, so this could be helped via a pull request.

Among 130 packages that will appear in GAP 4.8.2, there are 33 packages which do not have GAPDoc-based manuals.

Status as of 2026-08-11, checked against the current package distribution. 8 of the 34 listed packages are converted; 26 remain.

Package	Status	PR	Released
alnuth	✅ converted	issue 5	yes
autpgrp	✅ converted	#11 by @james-d-mitchell	yes
cubefree	✅ converted	#15	yes, v1.22
fga	✅ converted		yes
fplsa	✅ converted	issue 2 by @fingolfin	yes
kbmag	✅ converted	issue 1 by @cdwensley	yes
qaos	✅ converted (custom format, not gapmacro)	#4 by @fingolfin	no longer distributed
radiroot	✅ converted	#15	yes, v2.10
liepring	✅ merged	#36	not yet
symbcompcc	✅ merged	#8	not yet
CaratInterface	🔄 PR open	#42
crystcat	🔄 PR open	#20
nilmat	🔄 PR open	#11
sglppow	🔄 PR open	#12
ace	☐ todo	see issue 1
aclib	☐ todo
automgrp	☐ todo
cohomolo	☐ todo	see issue 1
crisp	☐ todo
cryst	☐ todo
design	☐ todo
format	☐ todo
fwtree	☐ todo
grape	☐ todo
grpconst	☐ todo
irredsol	☐ todo
itc	☐ todo	see issue 1
matgrp	☐ todo
modisom	☐ todo	see issue 9
rds	☐ todo
sonata	☐ todo	ships several books under doc/<book>/
transgrp	☐ todo
unipot	☐ todo	see issue 2
xgap	☐ todo	see issue 1

Note that crisp, irredsol and matgrp no longer ship a doc/make_doc, but their manuals are still plain TeX.

dev/gapmacro2gapdoc.g has been replaced by a Python rewrite, #6496, which is what the recent conversions used. It converts the chapter files, resolves cross-references against manual.six, takes each declaration's type from the package's own Declare... calls, and reports what it could not work out. The result still needs review, but the bulk is mechanical.

One thing that turned up in every package converted so far: the old build extracted the manual examples to a gitignored file that nothing ever ran, so they had quietly gone stale. AutoDoc extracts them into tst/, where they do run — expect to spend most of the effort there rather than on the markup.

[fingolfin]

Some people still create new packages using gapmacro, though (e.g. Bettina)

[fingolfin]

I am not exactly sure what the point of this issue is? I mean, what harm is done by just leaving package docs in gapmacro format? Sure, I personally find the GAPDoc manuals easier to read and use, but that's a relatively minor thing, and probably quite subjective, too?

Also, I don't see anybody investing tons of effort to convert all these package manuals to GAPDoc; and even if, I am not sure all package authors would accept patches doing that. Finally, as I wrote earlier, there likely will still be new package using gapmacro anyway.

[olexandr-konovalov]

I've checked the list above vs the newly generated list at gap-system/gap-distribution#49, and ticked only one box there - for FLPSA. So little changes happened here over two years, and also the new TransGrp package has gapmacro-based manual.

On the other hand, for the packages in the list above certain progress has been achieved in establishing their public repositories - now only 7 packages from that list do not have known to us public repositories at the moment, while two years ago the picture was diametrically opposite. So in many cases prerequisites have been achieved. Will the same happen in two years with their manuals? I am not sure, but if their number will be reduced below 10, and only several more packages would remain, I'd possibly agree to invest some efforts in converting the remaining ones.

There is no rush with this, but should any problem with gapmacro arise, fixing it may prove to be difficult.

By the way, we have zero coverage for helpt2t.gi which, as its comment says, does the following:

##  The files  helpt2t.g{d,i} contain the  probably longest function  in the
##  GAP library. It converts TeX source code written in `gapmacro.tex' style
##  into text for the "screen" online help viewer.

We can construct a test like this:

gap> l:=HELP_PRINT_SECTION_TEXT(HELP_BOOK_INFO("transgrp"),1,1).lines;;
gap> for t in l do Print(t,"\n");od;
Transitive Permutation Groups ___________ The Library of Transitive Groups

> TransitiveGroupsAvailable( <deg> )                                     F

returns   whether  the  transitive  groups  groups  of  degree  <deg>  are
...
...
...
-------------------------------- Example ---------------------------------
gap> TransitiveIdentification(Group((1,2),(1,2,3)));
2
--------------------------------------------------------------------------

gap>

Because TransGrp still uses gapmacro.tex and is needed to run GAP, there may be some merit in adding a test. OTOH, even a small change in the TransGrp manual will break such test - one should pick up a section that looks most stable.... but then it will not exercise most of the code for special characters /shrug and because gapmacro,tex is not supported, investing time in constructing a special manual for the test is not so interesting... Maybe the test should call HELP_PRINT_SECTION_TEXT just to check that it runs without errors, and print nothing?

About the original question: I'd like to keep this issue open as a declaration of the intention that in the long run we would like to get rid of gapmacro. It will help to monitor the situation to decide when is the time to do so.

[fingolfin]

I don't see how "having a public repository" is necessary for converting a manual to GAPDoc -- nor do I see how it constitutes progress towards the latter. From my POV, there has been zero progress in the past two years on that, and I expect zero going forward -- unless e.g. you want to sit down and convert manuals. But I'd urge anybody doing that to reconsider -- aren't there far more useful things to do with that time?

[fingolfin]

In order to test help2t, I think the correct solution would be to add a fake manual using it somewhere, say into tst/fakepkg/; but to use it, the test system needs to have TeX installed (which isn't a problem on Travis, though).

[olexandr-konovalov]

1. Not having access to a (private or public) package repository is a demotivating factor - for me at least. I would not invest efforts in helping some other package with switching to GAPDoc if I need to send patches by email (I would still be happy to send them critical patches though).
2. Furthermore, establishing public repository makes source code discoverable, and creates a slight chance that someone else may be interested in doing this.
3. Apparently you only need tex files for the mock package, and perhaps manual.six for the navigation, to run the test. If you prepare them on a machine with TeX and then commit to tst/fakepkg/doc, the test can be run elsewhere, including Windows.

[fingolfin]

I don't see this as a realistic goal these days. Too many packages use this, with nobody available to convert them. On the flip side, it also is unclear why we would want to do this? Sure, we don't want to advertise this, and would prefer if new packages don't use it, but in the end, this is a problem for package authors, not us?

Given that there has been essentially no progress since 2016 (other than a few manuals that mostly were converted by me), and last activity on this issue was in 2018, I see no point in keeping this open.