Convert documentation to GAPDoc/AutoDoc, fix some errors in it - #32
Merged
Conversation
Replace the plain-TeX manual with GAPDoc XML built via AutoDoc, and drop doc/make_doc for a makedoc.g in the package root. See gap-system/gap#639. Converted with dev/gapmacro2gapdoc.py from the GAP repository, which corrected AlgebraByTable from a function to an operation and rewrote 31 TeX accents in the bibliography as Unicode. The rest was the examples, which the old build extracted to a file nothing ran: * A rec() spread over six lines had no "> " continuation prompts, so the extracted test read the first line as a whole statement, failed on the syntax, and took the remainder for expected output. * Four examples print a record containing a "time" field in milliseconds, and the walkthrough of the groups from [GLM24] ends in a break loop after a computation that, as the manual says, "was not progressing for several hours" -- with a path on the author's machine in the traceback. Those are <Log>. So are the examples that follow the pasted definitions of G and H, since the definitions are a <Listing> and never run. * KuroshAlgebra's example elides its progress output as "... some printout ..", which cannot pass as a test; kept as written, as <Log>. * The recorded output of the remaining examples has drifted. Refreshed from what GAP prints. Note that BinsByGTAllFields(2,6) now gives ten bins where the manual had eight: the shipping code says so, but it is a mathematical result rather than formatting, and worth a check. The test suite passes. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Also correct two formulas: |G| <= p^(p+1) had lost its bars, and C_G(G/Phi(G')) should be C_G(G'/Phi(G')) as elsewhere in the chapter.
The conversion put function names, calls, record components and globals into <M>, which renders them as italic maths. Documented functions now use <Ref>, the rest <C>, false <K>, and MIPBinSplit's parameters <A>. Also repairs constructs the conversion split across two <M> elements, such as <M>SmallGroup(p</M>^<M>n, i)</M>, and a stray MIPBinsSplit.
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## master #32 +/- ##
==========================================
+ Coverage 94.08% 94.09% +0.01%
==========================================
Files 62 62
Lines 26569 26569
==========================================
+ Hits 24997 25000 +3
+ Misses 1572 1569 -3 🚀 New features to boost your workflow:
|
olexandr-konovalov
approved these changes
Aug 20, 2026
olexandr-konovalov
left a comment
olexandr-konovalov
left a comment
Member
There was a problem hiding this comment.
To me this looks good. I have reviewed the process rather than the manual though - instead of comparing TeX and XML files, or comparing old and new PDF files, I have compared doc/autiso.tex and doc/autiso.xml which GitHub by some reasons nicely shows, and was content with that. I have scrolled through all diffs shown under this PR and looked at the resulting PDF in GitHub actions. All looks good, and trust that @fingolfin's conversion script is well tested.
|
@olexandr-konovalov, @fingolfin I would prefer to have it merged in "steps" so we can follow what model changed. |
Member
|
@limakzi it's not a model, it is |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
4 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Resolves #9