Examples of Vector objects and Matrix objects

[cdwensley]

It was agreed by @fingolfin in PR#6320 that Chapter 26, Vector and Matrix Objects, needs lots of usage examples.
This is just an attempt to get this process started.
Newcomers to vector and matrix objects who start by reading this manual chapter (as opposed to those accessing a section by asking a question during a GAP session) need some examples early on, so this first commit adds a new section 26.2 doing just that.
Comments by one and all will be most welcome as further examples are added.
It was interesting to find that IsPlist{Vector/Matrix}Rep allow lists of type IsRangeRep as well as IsPlistRep.

[fingolfin]

Actually these can be omitted if one uses Matrix and Vector instead of NewMatrix and NewVector -- in that case default are chosen, based on the base domain.

My feeling is that we should generally advocate the use of the function variants without the New; the ones with New are constructors, and are the ones that people implementing MatrixObj ought to implement. Though I might be missing some nuance here, @ThomasBreuer ? I really should read up on what we wrote in the docs ...

But in any case, this is exactly the kind of thing that must be made clear in the manual, of course

[ThomasBreuer]

My point of view is that the starting point is the semiring R, in the sense that we want to do many computations with vectors and matrices over a given R.

Once we have fixed R, the functions Vector( R, list ) and Matrix( R, list ) (or Matrix( R, list, ncols )) give us vector and matrix objects in some representation that fits to R.

And once we have such a vector v or matrix M, new vectors and matrices that fit to them can be created with Vector( list, v ) and Matrix( list, M ).

This is the easy case.
If we do not want to rely on the default representation for R, we can look at some list of available representations (filters), and specify explicitly which one we choose.

Where is this useful or even necessary?
For example, suppose we need the matrix group GL( 4, GF(2) ), but we know already that later on this will be regarded as a subgroup of GL( 4, GF(2^10) ).
It may happen that the default representations for matrix objects over GF(2) and GF(2^10) differ.

In this situation, we should create GL( 4, GF(2) ) in such a way that the generators are written in a representation that is suitable also for matrices over GF(2^10).

Currently I see no easier way to achieve this than to create a matrix object over GF(2^10), to ask for its ConstructingFilter, and to specify this filter in the construction of the group GL( 4, GF(2) ).

[ThomasBreuer]

Two suggestions, which should fix the test failure (one more instance of the annoying setup described in #6274).

And one general remark, I agree with @fingolfin that Matrix and Vector are more important for users than NewMatrix and NewVector.

[cdwensley]

I have started to follow the suggestions of @fingolfin and @ThomasBreuer, but using GitHub in collaboration like this, and with GAPdev, is getting me in rather a tangle, so advice needed.
(1) the latest gapdev changes downloaded today result in errors when running GAP, so make_doc does not run:
("Error, Variable: 'EXTRACT_SUB_VECTOR' must have a value")
so is there a version of makedoc.g which will just produce the reference manual from within a GAP session?
(2) if I apply some of your suggestions within this PR, should I then "git pull upstream matrix-examples" before making any other changes locally? That did not seem to work well earlier today.

[codecov]

Codecov Report

❌ Patch coverage is 80.00000% with 2 lines in your changes missing coverage. Please review.
✅ Project coverage is 78.69%. Comparing base (aa52ee2) to head (550f275).
⚠️ Report is 3 commits behind head on master.

Files with missing lines	Patch %	Lines
lib/matobjplist.gi	50.00%	2 Missing ⚠️

Additional details and impacted files

@@           Coverage Diff           @@
##           master    #6339   +/-   ##
=======================================
  Coverage   78.69%   78.69%           
=======================================
  Files         684      684           
  Lines      292892   292900    +8     
  Branches     8660     8661    +1     
=======================================
+ Hits       230497   230506    +9     
  Misses      60581    60581           
+ Partials     1814     1813    -1     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[cdwensley]

NewMatrix(filt, R, ncols, list) & Matrix(filt, R, list, ncols) .... this confusing change of order will not do!