Maybe a section in the readme differentiating with org-ql ?

[Trevoke]

This looks like https://github.com/alphapapa/org-ql, though it looks like org-ml might be more comprehensive?

What are the differences / what's the relationship between the two?

[ndwarshuis]

From what I can tell org-ql is geared toward searching org files for headlines/headings that match a certain set of characteristics (and it looks like it is only intended for headline searching and not other objects/elements such as tables or links). It also seems to have a user-interface (ie interactive functions) that provide a front-end for the query functionality, although there doesn't seem to be anything stopping someone from using it as a backend for something bigger.

org-ml is more general in that it can (functionally) manipulate anything in an org file using its abstract syntax tree (AST) representation (basically a giant list) generated by org-element. Basically there are three types of functions: org -> AST (read), AST -> org (write), and AST -> AST' (everything else). The idea is that the first two types are 'impure operations' (they have side effects) and the third are 'pure'. This makes it easy to program in a functional style (eg more like Clojure/Scheme/Haskell/etc) since the read/write operations are totally separate from the things you might wish to do with the data to be read/written.

Given the title of this issue and the content, is the issue that the README isn't clear in explaining how this package should be used or is it specific to org-ql?