alphapapa / alphapapa/org-ql

Custom predicates tutorial feedback

Abierto
#280 1 comentario 0 reacciones 1 asignado Reclamado por @alphapapa Ver en GitHub
docs
Lenguaje dominante
Emacs Lisp
Estrellas
1.6k
Forks
120
Métricas de merge de PR
Sin PR fusionados en 30 d

Descripción

Hi,

Following up to #279 ([this comment](https://github.com/alphapapa/org-ql/issues/279#issuecomment-1139500376_) 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](https://github.com/alphapapa/org-ql/blob/master/examples/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!

Guía de contribución

No hay ninguna guía de contribución indexada para este repositorio

Evaluación

Este issue todavía no se ha evaluado.

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.