Docs: Improve ToCs
This commit is contained in:
Adam Porter
parent
1f79632372
commit
c4f9a58fd6
2 changed files with 92 additions and 85 deletions
65
README.org
65
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]]
|
||||
- [[#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]]
|
||||
- [[#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~
|
||||
|
|
|
|||
106
org-ql.info
106
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
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue