Undocumented argument for NewFilter/DeclareFilter

[fingolfin]

The manual gives the signatures NewFilter( name[, rank] ) and DeclareFilter( name[, rank] ). But looking at the code, there is a third optional argument: NewFilter( <name>[, <implied>][, <rank>] ) and likewise for DeclareFilter.

As far as I can tell, nothing uses this argument for NewFilter, but some callers for DeclareFilter do; mostly in HPC-GAP code, but also in a few other files, and most importantly, in packages.

So I guess we should simply document this extra argument.

[ThomasBreuer]

Implications between filters can cause problems when one manually resets a filter for a given object: Shall the implied filters also be reset?
As far as I remember, NewFilter/DeclareFilter has been introduced in order to model filters that can be set and reset (one could call them "switch") in an object, whereas NewCategory/DeclareCategory were intended for filters that should not be reset in an object once they had been set.
The NewFilter/DeclareFilter filters should then not imply other filters, whereas the NewCategory/DeclareCategory filters may imply other filters.
Of course these rules/conventions are not in the documentation.
Once we document implied filters as admissible for NewFilter/DeclareFilter, these rules do not make sense at all.
(But then we should at least document the abovementioned problem with implications somewhere.)

[fingolfin]

We discussed this orally, and decided that this feature has been out and in use for too long; so it seems best to just document it. Perhaps with another stern warning that this makes it even more risky to use ResetFilterObj on such filters, and that one should better use DeclareCategory instead...