Convert documentation to GAPDoc/AutoDoc - #17
Open
fingolfin wants to merge 3 commits into
Open
Conversation
Replace the plain-TeX (gapmacro.tex) manual with GAPDoc XML built via AutoDoc, and drop doc/make_doc in favour of a makedoc.g in the package root. See gap-system/gap#639. Converted mechanically with dev/gapmacro2gapdoc.py from the GAP repository, which also corrected two declarations against the package's own source: OrientationModule is an attribute and BettiNumber an operation, both documented as functions. IsomorphismPcpGroup belongs to Polycyclic, so it is an <Attr> here by hand. The rest was documentation that had gone stale unnoticed, the old build having extracted its examples to a file nothing ran: * aclib.bib gave an author as "Kenneth S.\ Brown". GAPDoc splits names itself and cannot parse TeX there; it aborted the whole build with an unassigned list element from inside NormalizedNameAndKey. * Recorded output predates GAP writing "Pcp-group" rather than "Pcp group" and "id" rather than "identity". Refreshed from what GAP prints. * Two examples pass false as the parameter list, which the manual itself documents as asking for a random one, so they cannot be reproduced and are <Log>. tst/manual.example-3.tst and -4.tst were the old extraction of those same examples. AutoDoc generates tst/aclib01.tst and tst/aclib02.tst now, so they go. They also pinned one of those random parameter lists, which held only as long as nothing else drew from the random source first. The test suite passes. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## master #17 +/- ##
==========================================
- Coverage 38.72% 38.20% -0.52%
==========================================
Files 11 11
Lines 5431 5431
==========================================
- Hits 2103 2075 -28
- Misses 3328 3356 +28 🚀 New features to boost your workflow:
|
Most of this is fallout from the GAPDoc conversion: {\sf Polycyclic}
became " Polycyclic", \{...\} lost its backslashes, {\rm Aut} became
"{ Aut}", and a paragraph introducing the holonomy group ended up inside
the IsomorphismPcpGroup entry, leaving that function without a
description of its own.
Content errors fixed along the way: the catalog is one of *almost*
crystallographic groups; BettiNumbers returns numbers, not a number;
OrientationModule returns matrices in GL(1,Z), not below it; a parameter
set was written (k_1,...,k_4,k_4,k_6); and the "more extended
description" pointed at the theory section rather than at 3.3, which is
where types and parameters are actually described.
In README and PackageInfo.g: the package is AClib, the book is
"Almost-Bieberbach Groups", and two homepages moved.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
AutoDoc turns the `entities` record in PackageInfo.g into &Polycyclic; and friends, which is shorter in the source and keeps the markup in one place. &AClib; comes for free. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
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
1 participant
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.
Replace the plain-TeX (gapmacro.tex) manual with GAPDoc XML built via
AutoDoc, and drop doc/make_doc in favour of a makedoc.g in the package
root. See gap-system/gap#639.
Converted mechanically with dev/gapmacro2gapdoc.py from the GAP
repository, which also corrected two declarations against the package's
own source: OrientationModule is an attribute and BettiNumber an
operation, both documented as functions. IsomorphismPcpGroup belongs to
Polycyclic, so it is an here by hand.
The rest was documentation that had gone stale unnoticed, the old build
having extracted its examples to a file nothing ran:
aclib.bib gave an author as "Kenneth S.\ Brown". GAPDoc splits names
itself and cannot parse TeX there; it aborted the whole build with an
unassigned list element from inside NormalizedNameAndKey.
Recorded output predates GAP writing "Pcp-group" rather than "Pcp
group" and "id" rather than "identity". Refreshed from what GAP prints.
Two examples pass false as the parameter list, which the manual itself
documents as asking for a random one, so they cannot be reproduced and
are .
tst/manual.example-3.tst and -4.tst were the old extraction of those same
examples. AutoDoc generates tst/aclib01.tst and tst/aclib02.tst now, so
they go. They also pinned one of those random parameter lists, which held
only as long as nothing else drew from the random source first.
The test suite passes.
Co-Authored-By: Claude Opus 5 noreply@anthropic.com