-
Notifications
You must be signed in to change notification settings - Fork 161
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
StructureDescriptions fix #985
StructureDescriptions fix #985
Conversation
Hm, |
Current coverage is 49.63% (diff: 98.88%)@@ master #985 diff @@
==========================================
Files 424 424
Lines 223266 223277 +11
Methods 3430 3430
Messages 0 0
Branches 0 0
==========================================
+ Hits 110545 110821 +276
+ Misses 112721 112456 -265
Partials 0 0
|
@hungaborhorvath |
c27606f
to
da7b3a0
Compare
10ef0bb
to
0e2c47b
Compare
@hulpke Thank you, I have renamed these internal functions to make it more clear that they are really just internal functions. I squashed the commit into a previous one to make history more clear. @alex-konovalov this should fix #973 and also the discrepancy in BTW, currently all lines in |
f290c7a
to
194903e
Compare
@hungaborhorvath thanks - we still need to review this, but now the discrepancy in |
For the record, there are now 12 diffs in manual examples with default set of packages. I think they appeared after recent merges by @hungaborhorvath and @hulpke. Since there will be further changes, I may wait with fixing them till the code will stabilise a bit more, also trying to make some of the examples involved more reproducible:
|
194903e
to
66b4b1e
Compare
@alex-konovalov Thanks. I have rebased this PR to latest master, and ran a check on I confirm again that this PR solves the old issue with I am also running The manual diffs above are not related to my changes. I believe they are due to the changes made by @hulpke . They all look harmless. Edit: #1022 is a non-issue, I have not compiled my packages properly. There are no issues with |
Further, add Redispatch for SemidirectDecompositions
66b4b1e
to
fb63357
Compare
@alex-konovalov How should one reference attributes in the manual? E.g. is |
abbfcdf
to
fb63357
Compare
@hungaborhorvath yes, while there will be no error reported while building the manual, it's consistent to use The full list of what else can be used there could be seen in the
|
@alex-konovalov Thank you. I think in the last commit I managed to correct several inconsistencies in the documentation of |
In particular for StructureDescription. Prepare manual entries for DirectFactorsfFGroup and SemidirectDecompositions for possibly documenting them later.
d331801
to
79bb26a
Compare
## Adds the <A>obj</A> to the list <A>list</A>. If CanEasilySortElements | ||
## is true for <A>list</A> and <A>list</A> is a set, then AddSet is used | ||
## instead of Add. Does not return anything, but changes <list>. | ||
## </Description> |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
CanEasilySortElements
, AddSet
and Add
should use a proper markup (<Ref ...
elements when they could be cross-referenced, or <C>...</C>
otherwise.
## presentation. Note, that this may take a long time. | ||
## presentation. Note, that this may take a very long time if <A>G</A> has | ||
## many normal subgroups, e.g. if <A>G</A>/<A>G</A>' has many cyclic | ||
## factors. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Shouldn't it be <M><A>G</A>/<A>G</A>'</M>
?
@@ -49,6 +51,8 @@ gap> List(DirectFactorsOfGroup(G), IdGroup); | |||
[ [ 8, 3 ], [ 8, 3 ] ] | |||
gap> List(DirectFactorsOfGroup(SmallGroup(64,226):useKN), IdGroup); | |||
[ [ 8, 3 ], [ 8, 3 ] ] | |||
gap> List(DirectFactorsOfGroupKN(SmallGroup(8,5)), IdGroup); | |||
[ [ 2, 1 ], [ 2, 1 ], [ 2, 1 ] ] |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
TBH, I was confused when I've seen DirectFactorsOfGroupKN
and assumed that I've missed that we have introduced some other abbreviation like "NC". Then I figured out that this stands for "Kayal-Nezhmetdinov". Maybe I'd prefer DirectFactorsOfGroupByKN
more.
|
||
## this currently takes a veeeeeery long time (about 20 minutes) | ||
#gap> StructureDescription(Ree(27)); | ||
#"Ree(27)" |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This had been discussed in #987. Is this example critical to achieve code coverage, or could be easily removed?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I made it work with a hack, see above tst/testinstall/opers/StructureDescription.tst:87
. This would be cleaner, but I agree with what @hulpke says in #987, that it is not a real usecase. I could just remove this if you like (but it is commented out anyway).
Just to note that this example was not entirely in vain: the particular line this runs in StructureDescription
was incorrect, and this test made me correct it in this PR.
b90181e
to
b910b49
Compare
@alex-konovalov Thank you for the advices, I applied all of them. |
Replace DirectFactorsOfGroupKN by DirectFactorsOfGroupByKN (in tst files, as well). More use of <Ref ....> and <C> in grpnames.gd. More appropriate use of <M></M> in grpnames.gd. Apply <K></K> around true, false and fail.
b910b49
to
11d1587
Compare
@alex-konovalov Thank you, I have put |
@@ -24,8 +24,8 @@ | |||
## | |||
## <Description> | |||
## For normal subgroups <A>U</A> and <A>V</A> of <A>G</A>, | |||
## IsTrivialNormalIntersection returns | |||
## true if <A>U</A> and <A>V</A> intersect trivially, and false otherwise. | |||
## <Ref Oper="IsTrivialNormalIntersection"/> returns <K>true</K> if |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Hmm, I am sorry for the conradictory message, but this actually seems a bit odd -- it's kind of recursive: a function's description linking to itself... :-). Do we do this elsewhere? I'd hope we do not... How about instead rephrasing this as "This operation returns ..." ? Or keep the name, but in a or tag... ? I wonder if there are other examples of functions/operations referencing themselves in the manual, and how they solved this?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
StructureDescription
had this already, but somehow, never together with a link. Maybe because it referenced a function instead of an operation? I am not sure. Maybe @alex-konovalov can shed some light on how to do this properly.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This "self-referencing" is a valid question - I've also asked it at some point. It happens that GAPDoc renders references in a clever way, understanding when they refer to the same mansection or to another one. Compare, for example,
## <ManSection>
## <Var Name="GaussianIntegers"/>
##
## <Description>
## <Ref Var="GaussianIntegers"/> is the ring <M>&ZZ;[\sqrt{{-1}}]</M>
## of Gaussian integers.
## This is a subring of the cyclotomic field
## <Ref Func="GaussianRationals"/>.
## </Description>
## </ManSection>
with its documentation here.
The rationale behind this is (as I see it - maybe @frankluebeck had other considerations in mind while developing GAPDoc) as follows. Using just IsTrivialNormalIntersection is incorrect: one should use GAPDoc markup at least to distinguish it by using different font with <C>IsTrivialNormalIntersection</C>
. But:
- it may happen that the text will be moved to another place in the manual later, or copied and pasted as a template for another GAPDoc section. Then one should take care and replace
<C>
by<Ref>
to get a proper cross-reference. Using<Ref>
from the very start allows to avoid such hassles in the future. - one could of course argue that moving
<C>IsTrivialNormalIntersection</C>
to another location will not cause any problems, because it will be rendered successfully anyway. But then there will be no cross-reference to a documented thing - the quality of the documentation will suffer. It's a good practice to put cross-references to everything which is documented. If you try to cross-ref undocumented thing, you will see the warning. When you use just<C>
elements, you will never be warned, while it's good to care whether you mention documented or undocumented things. - finally, this will guarantee the correct behaviour if some future version of GAPDoc (or just rebuilding the manual with another settings) will change the style of these elements so that
<C>
and<Ref>
will be displayed differently.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Fair enough. In that case I have no objections.
@alex-konovalov This PR is blocked by your review requesting changes. Could you please either change this to approval/neutral, or else clarify which issues still need to be addressed? Thanks! |
@fingolfin thanks for reminding - done! |
@fingolfin do we agree to merge this then? |
The content seems OK. The only thing I am not completely happy with is the somewhat random asortment of commits - ideally, I prefer if commits are self-contained units, so that one can review a PR commit by commit. This probably was the case here originally, but isn't anymore with e.g. the last commit "Apply Alex Konovalov's advices". So if @hungaborhorvath was willing to improve that, I'd love it. But I'll also survive it is merged as is (but in general, I'd like for us to improve the quality of our commits ;-) |
Also, lest I sound ungrateful: @hungaborhorvath thank you for your contributions, I really appreciate them, and hope my constant change requests are not too tiresome... |
@fingolfin Could you please be more specific on what you are proposing? Should I somehow split the last two commits into several by some topic, or should I squash them? Or something else? I tried to explain what happens where in the more detailed commit messages, and tried to write the first comment of this PR so that it could be used for merge comment. |
@hungaborhorvath Just looked again at this PR, and it's really only the last commit "Apply Alex Konovalov's advices " which I don't like -- I'd prefer if it was split and the changes in it were incorporated into the commits they affect. But anyway, this is a super nitpick. So let's just merge this. |
This splits the current general
StructureDescription
code for an abelian for a finite and for a finite simple method, with redispatches.Further, it adds nice monomorphism in the proper way (into
grpnice.gi
), while removes it fromgrpnames.gi
.Corrects problematic tests, and fixes the
StructureDescription
part of #973.Added some more tests to increase the code coverage of
grpnames.gi
. Now all lines (except for the ones for which I have no idea if an example even exists for) are covered forStructureDescription
,DirectFactors
andSemidirectDecompositions
.Manual entries are cleaned up in these three functions and in some of the functions they use in
grpnames.gd
(for easier future documentation).