Waldek,
As I said before, I'm not suggesting that the reference documentation
tries to teach the mathematics but I do think it should allow potential
users to match the mathematics to the code. I think my ideal would be to
allow both short and long explanations in the '++' comments.
Try to look at this from the point of view of a potential new user:
convert : (List(S), List(FreeGroup(S))) -> GroupPresentation
++ convert(lg, lr) builds group presentation from list
++ of generators \spad{lg} and list of relations \spad{lr}.
Is it really as obvious as you suggest what this does?
If I was a potential new user and I was scanning through lots of files
and lots of functions and I had a quick scan of the above my first guess
would be that it might be adding a list of relations to a free group.
Especially as a new user they might not know how the domains are defined
(is an instance an element of the group or the whole group). So the user
has to do all this work when they don't even know if this is a function
they are looking for.
I think the explanation of this code that you gave earlier in this
thread is excellent but you seem determined to hide it away where new
users cant find it.
Martin
On 07/05/18 10:34, Waldek Hebisch wrote:
Martin Baker wrote:
If I was scanning through this very quickly I would probably have
assumed that the free group was a presentation without relations and
this function was adding the relations (that is the free group was the
generators and not the relations). Its obviously not that when you look
at the code but should a new user have to trace though the code for
every function they are considering using?
If you go to obvious place, that is Wikipedia, at:
https://en.wikipedia.org/wiki/Presentation_of_a_group
the fifth statement (so just at the start) says:
: Formally, the group G is said to have the above presentation if it
: is isomorphic to the quotient of a free group on S by the normal
: subgroup generated by the relations R.
We do not have resources to match Wikipedia math articles, so
we should direct our efforts to documenting things specific to
FriCAS or maybe computer algebra for which there is no adequate
documentation elsewere.
I think this information needs to be part of the reference documentation
(Its explaining what the code does not the maths) and I think it needs
to be somewhere where it can be automatically picked up by Ralfs
program: https://fricas.github.io/api/index.html and other programs like
this.
Is it too much to reqest that users do a Google search and go to
relevant pages? For most topics that will lead to Wikipedia.
In other words, for all parts of FriCAS you should consder
implicit link to Wikipedia.
--
You received this message because you are subscribed to the Google Groups "FriCAS -
computer algebra system" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to fricas-devel+unsubscr...@googlegroups.com.
To post to this group, send email to fricas-devel@googlegroups.com.
Visit this group at https://groups.google.com/group/fricas-devel.
For more options, visit https://groups.google.com/d/optout.
