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-09-11. Of the 34 listed packages, 15 are converted and released — 14 in the distribution, and qaos is no longer distributed. Five more are merged but have not reached the distribution yet, six are in progress, and eight remain. The last distribution I checked, from 2026-08-18, still ships 16 packages with a doc/make_doc.

Package	Status	PR	Released
ace	🔄 PR open	#48
aclib	✅ converted	#17	yes, v1.4
alnuth	✅ converted	issue 5	yes
automgrp	🔄 converted, PR pending
autpgrp	✅ converted	#11 by @james-d-mitchell	yes
CaratInterface	✅ merged	#42	released v2.3.10, not yet in the distribution
cohomolo	✅ converted	#41	yes, v1.7.0
crisp	☐ todo
cryst	✅ converted	#61	yes, v4.1.32
crystcat	✅ merged	#20	released v1.1.12, not yet in the distribution
cubefree	✅ converted	#15	yes, v1.22
design	☐ todo
fga	✅ converted		yes
format	🔄 PR open	#11
fplsa	✅ converted	issue 2 by @fingolfin	yes
fwtree	✅ converted	#13	yes, v1.4
grape	☐ todo
grpconst	✅ converted	#14	yes, v2.7.0
irredsol	☐ todo
itc	☐ todo	see issue 1
kbmag	✅ converted	issue 1 by @cdwensley	yes
liepring	✅ merged	#36	released v2.9.3, not yet in the distribution
matgrp	☐ todo
modisom	✅ merged	#32	not yet, v3.1.0 predates the conversion
nilmat	🔄 PR open	#11
qaos	✅ converted (custom format, not gapmacro)	#4 by @fingolfin	no longer distributed
radiroot	✅ converted	#15	yes, v2.10
rds	🔄 converted, PR pending
sglppow	✅ merged	#12	released v2.6, not yet in the distribution
sonata	🔄 converted, PR pending	ships two books under doc/ref/ and doc/tut/
symbcompcc	✅ converted	#8	yes, v1.4.0
transgrp	☐ todo
unipot	✅ converted	#12	yes, v1.7
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.

Some things worth knowing before starting on the remaining ones:

• Examples indented in the source are read by GAP's test format as expected output rather than input, so a whole block fails as one chunk. sonata indented every one of its examples. The converter now dedents <Example> (but not <Log>, whose indentation can be deliberate).
• Sessions that cannot reproduce belong in <Log>: timings, temporary paths, Print/View output with no trailing newline, anything whose result depends on what ran before it (set orderings, Indeterminate numbering, groups that print differently once named).
• Chapters reached by plain TeX's \input rather than \Input are invisible to the converter and get dropped silently — sonata's Preface and Copyright chapters were only in the front matter.
• GAPDoc's title page has Copyright, Acknowledgements and Colophon fields, so a copyright chapter does not need to stay a chapter.
• etc/ release scripts in the cryst family also referenced doc/make_doc, the plain-TeX output and an htm/ directory; they need updating along with the manual.

[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.

[fingolfin]

For anyone who wants to convert from gapmacros to gapdoc, the script dev/gapmacro2gapdoc.g in the GAP repository can help with that. I used it for multiple package manuals to convert them.

But it has some known issues and its output always needs additional manual intervention. These plus usage instructions are documented inside the file.

Presumably it could be improved to minimize the extra work needed, but someone has to invest that work into it first. OTOH it was apparently good enough to help convert the GAP reference manual itself, and one should carefully check the result of the conversion anyhow, so I am not sure it'd be worth it.

[fingolfin]

Re-opening this during GAP Days Summer 2025 as @james-d-mitchell has expressed some interest and might have some students who might be interested in working on this.