jiri/org-ql
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Docs: Improve ToCs

Browse source
This commit is contained in:
Adam Porter 2020-01-10 10:21:55 -06:00
parent 1f79632372
commit c4f9a58fd6
2 changed files with 92 additions and 85 deletions
Download patch file Download diff file Expand all files Collapse all files

55
README.org
View file

@ -19,6 +19,9 @@ It includes three libraries: The =org-ql= library is flexible and may be used as
- [[#usage][Usage]] - [[#usage][Usage]]
- [[#commands][Commands]] - [[#commands][Commands]]
- [[#queries][Queries]] - [[#queries][Queries]]
- [[#non-sexp-query-syntax][Non-sexp query syntax]]
- [[#predicates][Predicates]]
- [[#datetime-predicates][Date/time predicates]]
- [[#functions--macros][Functions / Macros]] - [[#functions--macros][Functions / Macros]]
- [[#changelog][Changelog]] - [[#changelog][Changelog]]
- [[#notes][Notes]] - [[#notes][Notes]]
@ -57,22 +60,13 @@ Installing with [[https://framagit.org/steckerhalter/quelpa][Quelpa]] is easy:
#+END_SRC #+END_SRC
* Usage * Usage
:CONTENTS:
- [[#commands][Commands]]
- [[#queries][Queries]]
- [[#functions--macros][Functions / Macros]]
:END:
These commands and functions are included: # These links work on GitHub's Org renderer but not in Org.
+ *Showing an agenda-like view:*
- ~org-ql-search~ (command)
- ~org-ql-view~ (command)
- ~org-ql-view-sidebar~ (command)
- ~org-ql-block~ (agenda block function)
+ *Showing a tree in a buffer:*
- ~org-ql-sparse-tree~ (command)
+ *Showing results with Helm*:
- ~helm-org-ql~ (command)
+ *Returning a list of matches or acting on them:*
- ~org-ql~ (macro)
- ~org-ql-select~ (function)
- ~org-ql-query~ (function)
Feedback on these APIs is welcome. Eventually, after being tested and polished, they will be considered stable. Feedback on these APIs is welcome. Eventually, after being tested and polished, they will be considered stable.
@ -84,6 +78,16 @@ Lisp code examples are in [[examples.org]].
:TOC: ignore-children :TOC: ignore-children
:END: :END:
+ *Showing an agenda-like view:*
- [[#org-ql-search][org-ql-search]] (command)
- [[#org-ql-view][org-ql-view]] (command)
- [[#org-ql-view-sidebar][org-ql-view-sidebar]] (command)
- [[#org-ql-view-recent-items][org-ql-view-recent-items]] (command)
+ *Showing a tree in a buffer:*
- [[#org-ql-sparse-tree][org-ql-sparse-tree]] (command)
+ *Showing results with Helm*:
- [[#helm-org-ql][helm-org-ql]] (command)
*** org-ql-search *** org-ql-search
/Note: This command supports both sexp queries and [[#non-sexp-query-syntax][non-sexp queries]]./ /Note: This command supports both sexp queries and [[#non-sexp-query-syntax][non-sexp queries]]./
@ -139,6 +143,11 @@ Show a sparse tree for ~QUERY~ in ~BUFFER~ and return number of results. The tr
~QUERY~ is an ~org-ql~ query sexp (quoted, since this is a function). ~BUFFER~ defaults to the current buffer. When ~KEEP-PREVIOUS~ is non-nil (interactively, with prefix), the outline is not reset to the overview state before finding matches, which allows stacking calls to this command. Runs ~org-occur-hook~ after making the sparse tree. ~QUERY~ is an ~org-ql~ query sexp (quoted, since this is a function). ~BUFFER~ defaults to the current buffer. When ~KEEP-PREVIOUS~ is non-nil (interactively, with prefix), the outline is not reset to the overview state before finding matches, which allows stacking calls to this command. Runs ~org-occur-hook~ after making the sparse tree.
** Queries ** Queries
:CONTENTS:
- [[#non-sexp-query-syntax][Non-sexp query syntax]]
- [[#predicates][Predicates]]
- [[#datetime-predicates][Date/time predicates]]
:END:
An =org-ql= query is a lisp form which may contain arbitrary lisp forms, as well as certain built-in predicates. It is byte-compiled into a predicate function which is tested with point on each heading in an Org buffer; when it returns non-nil, the heading matches the query. An =org-ql= query is a lisp form which may contain arbitrary lisp forms, as well as certain built-in predicates. It is byte-compiled into a predicate function which is tested with point on each heading in an Org buffer; when it returns non-nil, the heading matches the query.
@ -147,9 +156,6 @@ An =org-ql= query is a lisp form which may contain arbitrary lisp forms, as well
+ Standard numeric comparator function symbols (~<~, ~<=~, ~>~, ~>=~, ~=~ ) need not be quoted when passed as an argument to predicates which accept them. The resemblance to infix notation is coincidental. + Standard numeric comparator function symbols (~<~, ~<=~, ~>~, ~>=~, ~=~ ) need not be quoted when passed as an argument to predicates which accept them. The resemblance to infix notation is coincidental.
*** Non-sexp query syntax *** Non-sexp query syntax
:PROPERTIES:
:TOC: ignore
:END:
The command =org-ql-search= also accepts, and the command =helm-org-ql= only accepts, an alternative, non-sexp query syntax. The syntax is simple, and a few examples of queries in both syntaxes should suffice. By default, when multiple predicates are used, they are combined with boolean =and=. The command =org-ql-search= also accepts, and the command =helm-org-ql= only accepts, an alternative, non-sexp query syntax. The syntax is simple, and a few examples of queries in both syntaxes should suffice. By default, when multiple predicates are used, they are combined with boolean =and=.
@ -170,9 +176,6 @@ The command =org-ql-search= also accepts, and the command =helm-org-ql= only acc
Note that the =priority= predicate does not support comparators in the non-sexp syntax, so multiple priorities should be passed instead, as seen in the last example. Note that the =priority= predicate does not support comparators in the non-sexp syntax, so multiple priorities should be passed instead, as seen in the last example.
*** Predicates *** Predicates
:PROPERTIES:
:TOC: ignore
:END:
Arguments are listed next to predicate names, where applicable. Arguments are listed next to predicate names, where applicable.
@ -204,9 +207,6 @@ Arguments are listed next to predicate names, where applicable.
+ =todo (&optional keywords)= :: Return non-nil if current heading is a ~TODO~ item. With ~KEYWORDS~, return non-nil if its keyword is one of ~KEYWORDS~ (a list of strings). When called without arguments, only matches non-done tasks (i.e. does not match keywords in ~org-done-keywords~). + =todo (&optional keywords)= :: Return non-nil if current heading is a ~TODO~ item. With ~KEYWORDS~, return non-nil if its keyword is one of ~KEYWORDS~ (a list of strings). When called without arguments, only matches non-done tasks (i.e. does not match keywords in ~org-done-keywords~).
*** Date/time predicates *** Date/time predicates
:PROPERTIES:
:TOC: ignore
:END:
All of these predicates take optional keyword arguments ~:from~, ~:to:~, and ~:on~: All of these predicates take optional keyword arguments ~:from~, ~:to:~, and ~:on~:
@ -237,6 +237,13 @@ The following predicates, in addition to the keyword arguments, can also take a
:TOC: ignore-children :TOC: ignore-children
:END: :END:
- [[#agenda-like-views][Agenda-like views]]
- [[#function-org-ql-block][Function: org-ql-block]]
- [[#listing--acting-on-results][Listing / acting-on results]]
- [[#function-org-ql-select][Function: org-ql-select]]
- [[#function-org-ql-query][Function: org-ql-query]]
- [[#macro-org-ql][Macro: org-ql]]
*** Agenda-like views *** Agenda-like views
**** Function: ~org-ql-block~ **** Function: ~org-ql-block~

106
org-ql.info
View file

@ -93,7 +93,8 @@ File: README.info, Node: Contents, Next: Screenshots, Prev: Top, Up: Top
********** **********
• • • • • •
• • • • • • •
• • • • • •
 
File: README.info, Node: Screenshots, Next: Installation, Prev: Contents, Up: Top File: README.info, Node: Screenshots, Next: Installation, Prev: Contents, Up: Top
@ -145,22 +146,7 @@ File: README.info, Node: Usage, Next: Changelog, Prev: Installation, Up: Top
4 Usage 4 Usage
******* *******
These commands and functions are included: • • •
• *Showing an agenda-like view:*
• ‘org-ql-search’ (command)
• ‘org-ql-view’ (command)
• ‘org-ql-view-sidebar’ (command)
• ‘org-ql-block’ (agenda block function)
• *Showing a tree in a buffer:*
• ‘org-ql-sparse-tree’ (command)
• *Showing results with Helm*:
• ‘helm-org-ql’ (command)
• *Returning a list of matches or acting on them:*
• ‘org-ql’ (macro)
• ‘org-ql-select’ (function)
• ‘org-ql-query’ (function)
Feedback on these APIs is welcome. Eventually, after being tested Feedback on these APIs is welcome. Eventually, after being tested
and polished, they will be considered stable. and polished, they will be considered stable.
@ -178,6 +164,16 @@ File: README.info, Node: Commands, Next: Queries, Up: Usage
4.1 Commands 4.1 Commands
============ ============
• *Showing an agenda-like view:*
• (command)
• (command)
• (command)
• (command)
• *Showing a tree in a buffer:*
• (command)
• *Showing results with Helm*:
• (command)
* Menu: * Menu:
* org-ql-search:: * org-ql-search::
@ -298,10 +294,11 @@ File: README.info, Node: Queries, Next: Functions / Macros, Prev: Commands,
4.2 Queries 4.2 Queries
=========== ===========
An org-ql query is a lisp form which may contain arbitrary lisp forms, • • •
as well as certain built-in predicates. It is byte-compiled into a An org-ql query is a lisp form which may contain arbitrary lisp
predicate function which is tested with point on each heading in an Org forms, as well as certain built-in predicates. It is byte-compiled into
buffer; when it returns non-nil, the heading matches the query. a predicate function which is tested with point on each heading in an
Org buffer; when it returns non-nil, the heading matches the query.
*Notes:* *Notes:*
• Bare strings like ‘"string"’ are automatically converted to • Bare strings like ‘"string"’ are automatically converted to
@ -511,6 +508,9 @@ File: README.info, Node: Functions / Macros, Prev: Queries, Up: Usage
4.3 Functions / Macros 4.3 Functions / Macros
====================== ======================
•
• •
• • •
* Menu: * Menu:
* Agenda-like views:: * Agenda-like views::
@ -1006,38 +1006,38 @@ GPLv3
Tag Table: Tag Table:
Node: Top225 Node: Top225
Node: Contents1367 Node: Contents1367
Node: Screenshots1515 Node: Screenshots1541
Node: Installation1633 Node: Installation1659
Node: Quelpa2271 Node: Quelpa2297
Node: Usage2714 Node: Usage2740
Node: Commands3624 Node: Commands3064
Node: org-ql-search3853 Node: org-ql-search3537
Node: helm-org-ql5501 Node: helm-org-ql5185
Node: org-ql-view5913 Node: org-ql-view5597
Node: org-ql-view-sidebar6111 Node: org-ql-view-sidebar5795
Node: org-ql-view-recent-items6467 Node: org-ql-view-recent-items6151
Node: org-ql-sparse-tree6951 Node: org-ql-sparse-tree6635
Node: Queries7751 Node: Queries7435
Node: Non-sexp query syntax8593 Node: Non-sexp query syntax8296
Node: Predicates10292 Node: Predicates9995
Node: Date/time predicates15454 Node: Date/time predicates15157
Node: Functions / Macros18089 Node: Functions / Macros17792
Node: Agenda-like views18276 Node: Agenda-like views18025
Node: Listing / acting-on results19681 Node: Listing / acting-on results19430
Node: Changelog24283 Node: Changelog24032
Node: 04-pre24820 Node: 04-pre24569
Node: 03226835 Node: 03226584
Node: 03127216 Node: 03126965
Node: 0327411 Node: 0327160
Node: 02330384 Node: 02330133
Node: 02230610 Node: 02230359
Node: 02130876 Node: 02130625
Node: 0231073 Node: 0230822
Node: 0135106 Node: 0134855
Node: Notes35205 Node: Notes34954
Node: Comparison with Org Agenda searches35367 Node: Comparison with Org Agenda searches35116
Node: org-sidebar36238 Node: org-sidebar35987
Node: License36517 Node: License36266
 
End Tag Table End Tag Table