Custom predicates tutorial feedback

[telenieko]

Hi,

Following up to #279 (this comment by @alphapapa ):

@telenieko Glad to hear that the tutorial helped. You're one of only a few people who have read it carefully and used it to write their own predicate. Do you have any feedback on the tutorial? Was it easy to understand? Were any parts hard to follow or unhelpful?

The tutorial referenced is the Custom Predicates tutorial, defpred.org which is very easy to follow. The base example is quite common and relatable and you can quickly build upon it.

But it is a tutorial, which means that if you want to go further you'll have to dive into the code (which is neither good or bad).

There are a couple questions the tutorial rises on the reader that are not quite obvious after looking at the code (I'm still not completely sure I got the answers right).

Hence, this feedback bottom line is: There could be some more technical explanation for the advanced concepts, and pointers of "where to go from here". Specifically:

Normalizers vs. body

On the "Be formless" section you realize that a lot of custom predicates can be written as either :body or :normalizers which brings the questions... Which is better? When, how many times, is each one called?

Maybe that knowledge could be added as a single paragraph:

(after "It does!" in "Be formless"):
So, which is better? It depends on the use case.
:normalizers are run once (may be called more than once) before starting the search run. They "rewrite" the query and it is that resulting query that is then executed.
The normalized query could be quite different of the original. It may change calls to one predicate to calls to other predicates that your normalizer deems more performant, rename them (as shown above), etc. Even completely skipping the body of your predicate (as shown above too).
The :body is called once for each use of the predicate on the normalized query and for each org-element considered for searching.

There's another way to improve performance: :preambles, which limit the set of org headings considered for searching, thus reducing the calls to the predicate.

NOTE: All above could be wrong! I also mixed "org headings" and "org elements" not sure what is the appropiate wording.

Preambles

A similar question is raised with the preambles. Though this is not introduced in the tutorial, the README does explain what it does. So it looks like it is run once per search buffer to limit on what org headings the :body will be called upon (or the normalized query).

Pro question: which preambles are considered? the ones of the predicates of the "un normalized" query or the ones referenced by the "normalized" query? I think it's the later.

Maybe an honorable mention could be added on the tutorial.

See also

After reading the tutorial my first stop was going to the source code and see how the builtin predicates are written. Seems quite an obvious step, but maybe not always. Maybe the "Conclusion" could give you the idea:

Also, do not forget to look are the builtin predicates for more examples on how to write your own.
You will find them in `org-ql.el`, search for all those `(org-ql-defpred ...` calls!
You can also see how `:preambles` are used in several predicates to improve performance.

---

That is all, hope it's useful!

[alphapapa]

Hi Marc,

Thanks for your detailed review. That's very helpful. When I have time to work on this again, I'll address it and improve the tutorial accordingly.