I’m looking through the documentation trying to understand the following predicates:
term_factorized/3 and term_factorized/4
term_minimal/2
term_automaton/2
automaton_minimal/2 and automaton_minimal/3
But I have to be honest I don’t understand what the documentation is trying to say. I can see what e.g. term_factorized/3 does (it replaces unifying sub-terms with a variable) but I don’t know why this predicate exists, for example, what is a typical use-case?
[EDIT: I initially thought term_factorize might have something to do with factors in unification, i.e. literals in a clause that can be replaced with a variable to speed up unification but it doesn’t look like that’s the use case here since term_factorized/[2,3] replaces terms, rather than literals].
[EDIT2 Oh hang on, yep, that’s what it does. Well, it would be nice if this was made clear in the documentation! Especially for users that don’t know what factorization is in unification.]
I don’t understand anything in the documentation of the other three predicates. For example, the documentation for term_automaton/2 says
True when Automaton is the term graph of Term written out as an explicit automaton, and Term is the term its start state denotes.
but I can’t understand what kind of “automaton” the documentation means and I’m not even sure what is a “term graph”.
It would be nice if these subjects were explained in a bit more high-level detail accessible to non-experts, and it would be even nicer if the examples of use clarified how these predicates would be useful to the average Prolog programmer.
Btw I remember there was a similarly confused comment on numbervars/3 saying that the predicate makes no sense to anyone who doesn’t already know how to use it, I think. Now, I know what numbervars/3 does: it Skolemizes variables. But I agree that some of the concepts behind certain predicates in the SWI library are a bit … esoteric maybe, and it would be helpful to give pointers to those concepts for anyone looking in the library to try and find capabilities they may need.