Obsoleting gapmacro.tex

[olexandr-konovalov]

I compiled a list of packages still not using GAPDoc.

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

• ace - see Convert manual to GAPDoc gap-packages/ace#1
• aclib
• alnuth - see Convert manual to GAPDoc gap-packages/alnuth#5
• automgrp
• autpgrp
• CaratInterface
• cohomolo - see Convert manual to GAPDoc gap-packages/cohomolo#1
• crisp
• cryst
• crystcat
• cubefree
• design
• fga
• format
• fplsa - done by @fingolfin in Convert manual to GAPDoc gap-packages/FPLSA#2
• fwtree
• grape
• grpconst
• irredsol
• itc - see Convert manual to GAPDoc gap-packages/itc#1
• kbmag - done by @cdwensley in Convert manual to GAPDoc gap-packages/kbmag#1
• liepring
• matgrp
• modisom - see Convert manual to GAPDoc gap-packages/modisom#9
• nilmat - see Convert manual to GAPDoc and/or AutoDoc format gap-packages/nilmat#1
• qaos (not really gapmacros, but rather a custom documentation) - done by @fingolfin in Convert manual to GAPDoc gap-packages/qaos#4
• radiroot - see Convert manual to GAPDoc gap-packages/radiroot#2
• rds
• sglppow
• sonata
• symbcompcc
• transgrp
• unipot - see Convert manual to GAPDoc gap-packages/unipot#2
• xgap - see Convert manual to GAPDoc gap-packages/xgap#1

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.

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