From c4f9a58fd66c375b54befec4d6159be4135df7e6 Mon Sep 17 00:00:00 2001 From: Adam Porter Date: Fri, 10 Jan 2020 10:21:55 -0600 Subject: [PATCH] Docs: Improve ToCs --- README.org | 71 +++++++++++++++++++---------------- org-ql.info | 106 ++++++++++++++++++++++++++-------------------------- 2 files changed, 92 insertions(+), 85 deletions(-) diff --git a/README.org b/README.org index e16f59c2..1438e843 100644 --- a/README.org +++ b/README.org @@ -14,14 +14,17 @@ It includes three libraries: The =org-ql= library is flexible and may be used as :PROPERTIES: :TOC: this :END: - - [[#screenshots][Screenshots]] - - [[#installation][Installation]] - - [[#usage][Usage]] - - [[#commands][Commands]] - - [[#queries][Queries]] - - [[#functions--macros][Functions / Macros]] - - [[#changelog][Changelog]] - - [[#notes][Notes]] +- [[#screenshots][Screenshots]] +- [[#installation][Installation]] +- [[#usage][Usage]] + - [[#commands][Commands]] + - [[#queries][Queries]] + - [[#non-sexp-query-syntax][Non-sexp query syntax]] + - [[#predicates][Predicates]] + - [[#datetime-predicates][Date/time predicates]] + - [[#functions--macros][Functions / Macros]] +- [[#changelog][Changelog]] +- [[#notes][Notes]] * Screenshots @@ -57,22 +60,13 @@ Installing with [[https://framagit.org/steckerhalter/quelpa][Quelpa]] is easy: #+END_SRC * Usage +:CONTENTS: +- [[#commands][Commands]] +- [[#queries][Queries]] +- [[#functions--macros][Functions / Macros]] +:END: -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) +# These links work on GitHub's Org renderer but not in Org. 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 :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 /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. ** 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. @@ -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. *** 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=. @@ -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. *** Predicates -:PROPERTIES: -:TOC: ignore -:END: 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~). *** Date/time predicates -:PROPERTIES: -:TOC: ignore -:END: 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 :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 **** Function: ~org-ql-block~ diff --git a/org-ql.info b/org-ql.info index 67b883b5..43725a78 100644 --- a/org-ql.info +++ b/org-ql.info @@ -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 @@ -145,22 +146,7 @@ File: README.info, Node: Usage, Next: Changelog, Prev: Installation, Up: Top 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 and polished, they will be considered stable. @@ -178,6 +164,16 @@ File: README.info, Node: Commands, Next: Queries, Up: Usage 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: * org-ql-search:: @@ -298,10 +294,11 @@ File: README.info, Node: Queries, Next: Functions / Macros, Prev: Commands, 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 -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. *Notes:* • 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 ====================== + • + • • + • • • * Menu: * Agenda-like views:: @@ -1006,38 +1006,38 @@ GPLv3 Tag Table: Node: Top225 Node: Contents1367 -Node: Screenshots1515 -Node: Installation1633 -Node: Quelpa2271 -Node: Usage2714 -Node: Commands3624 -Node: org-ql-search3853 -Node: helm-org-ql5501 -Node: org-ql-view5913 -Node: org-ql-view-sidebar6111 -Node: org-ql-view-recent-items6467 -Node: org-ql-sparse-tree6951 -Node: Queries7751 -Node: Non-sexp query syntax8593 -Node: Predicates10292 -Node: Date/time predicates15454 -Node: Functions / Macros18089 -Node: Agenda-like views18276 -Node: Listing / acting-on results19681 -Node: Changelog24283 -Node: 04-pre24820 -Node: 03226835 -Node: 03127216 -Node: 0327411 -Node: 02330384 -Node: 02230610 -Node: 02130876 -Node: 0231073 -Node: 0135106 -Node: Notes35205 -Node: Comparison with Org Agenda searches35367 -Node: org-sidebar36238 -Node: License36517 +Node: Screenshots1541 +Node: Installation1659 +Node: Quelpa2297 +Node: Usage2740 +Node: Commands3064 +Node: org-ql-search3537 +Node: helm-org-ql5185 +Node: org-ql-view5597 +Node: org-ql-view-sidebar5795 +Node: org-ql-view-recent-items6151 +Node: org-ql-sparse-tree6635 +Node: Queries7435 +Node: Non-sexp query syntax8296 +Node: Predicates9995 +Node: Date/time predicates15157 +Node: Functions / Macros17792 +Node: Agenda-like views18025 +Node: Listing / acting-on results19430 +Node: Changelog24032 +Node: 04-pre24569 +Node: 03226584 +Node: 03126965 +Node: 0327160 +Node: 02330133 +Node: 02230359 +Node: 02130625 +Node: 0230822 +Node: 0134855 +Node: Notes34954 +Node: Comparison with Org Agenda searches35116 +Node: org-sidebar35987 +Node: License36266  End Tag Table