Docs: Improve ToCs

alphapapa · Jan 10, 2020 · c4f9a58 · c4f9a58
1 parent 1f79632
commit c4f9a58
Show file tree

Hide file tree

Showing 2 changed files with 92 additions and 85 deletions.
diff --git 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
@@ -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