[elpa] master 0194996 01/13: Added org-edna-describe-keyword function

[Ian Dunn]

branch: master
commit 0194996377c32f0bc36e5bf500e70b0b9dc3bf7f
Author: Ian Dunn <address@hidden>
Commit: Ian Dunn <address@hidden>

    Added org-edna-describe-keyword function
    
    * org-edna.el (org-edna--function-for-key): Return
      `org-edna-handle-consideration' for consideration and consider keywords.
      (org-edna-describe-keyword): New function.
    
    * org-edna.org (Getting Help): New section.
---
 org-edna.el   |  29 ++++++++++-
 org-edna.info | 164 ++++++++++++++++++++++++++++++++--------------------------
 org-edna.org  |  13 +++++
 3 files changed, 130 insertions(+), 76 deletions(-)

diff --git a/org-edna.el b/org-edna.el
index e271cb0..ee10b17 100644
--- a/org-edna.el
+++ b/org-edna.el
@@ -129,8 +129,9 @@ If KEY is an invalid Edna keyword, then return nil."
    ((or (not key)
         (not (symbolp key))))
    ((memq key '(consideration consider))
-    ;; Function is ignored here
-    (cons 'consideration 'identity))
+    ;; Function is ignored here, but `org-edna-describe-keyword' needs this
+    ;; function.
+    (cons 'consideration 'org-edna-handle-consideration))
    ((string-suffix-p "!" (symbol-name key))
     ;; Action
     (let ((func-sym (intern (format "org-edna-action/%s" key))))
@@ -2221,6 +2222,30 @@ PRED, and ACTION."
   (when-let* ((bounds (bounds-of-thing-at-point 'symbol)))
     (list (car bounds) (cdr bounds) 'org-edna-completion-table-function)))
 
+(defun org-edna-describe-keyword (keyword)
+  "Describe the Org Edna keyword KEYWORD.
+
+KEYWORD should be a string for a keyword recognized by edna.
+
+Displays help for KEYWORD in the Help buffer."
+  (interactive
+   (list
+    (completing-read
+     "Keyword: "
+     `(,@(org-edna--collect-finders)
+       ,@(org-edna--collect-actions)
+       ,@(org-edna--collect-conditions)
+       "consideration" "consider")
+     nil ;; No filter predicate
+     t))) ;; require match
+  ;; help-split-fundoc splits the usage info from the rest of the 
documentation.
+  ;; This avoids having another usage line in the keyword documentation that 
has
+  ;; nothing to do with how edna expects the function.
+  (pcase-let* ((`(,_type . ,func) (org-edna--function-for-key (intern 
keyword)))
+               (`(,_usage . ,doc) (help-split-fundoc (documentation func t) 
func)))
+    (with-help-window (help-buffer)
+      (princ doc))))
+
 
 
 (declare-function lm-report-bug "lisp-mnt" (topic))
diff --git a/org-edna.info b/org-edna.info
index 4f29ebe..07c97ff 100644
--- a/org-edna.info
+++ b/org-edna.info
@@ -36,6 +36,7 @@ Basic Features
 
 * Finders::                      How to find targets
 * Actions::                      Next steps
+* Getting Help::                 Getting some help
 
 Finders
 
@@ -314,6 +315,7 @@ The most basic features of Edna are *finders* and *actions*.
 
 * Finders::                      How to find targets
 * Actions::                      Next steps
+* Getting Help::                 Getting some help
 
 
 File: org-edna.info,  Node: Finders,  Next: Actions,  Up: Basic Features
@@ -758,7 +760,7 @@ when it reaches the end.
    Identical to the *note rest-of-siblings-wrap:: finder.
 
 
-File: org-edna.info,  Node: Actions,  Prev: Finders,  Up: Basic Features
+File: org-edna.info,  Node: Actions,  Next: Getting Help,  Prev: Finders,  Up: 
Basic Features
 
 Actions
 =======
@@ -1055,6 +1057,19 @@ Effort
    • If VALUE is the symbol ’increment, increment effort
 
 
+File: org-edna.info,  Node: Getting Help,  Prev: Actions,  Up: Basic Features
+
+Getting Help
+============
+
+Edna provides help for any keyword with ‘M-x org-edna-describe-keyword’.
+When invoked, a list of keywords (finders, actions, etc.)  known to Edna
+will be provided.  Select any one to get its description.
+
+   This description includes the syntax and an explanation of what the
+keyword does.  Some descriptions also contain examples.
+
+
 File: org-edna.info,  Node: Advanced Features,  Next: Extending Edna,  Prev: 
Basic Features,  Up: Top
 
 Advanced Features
@@ -1760,79 +1775,80 @@ Big release here, with three new features.
 
 Tag Table:
 Node: Top225
-Node: Copying4114
-Node: Introduction4936
-Node: Installation and Setup5884
-Node: Basic Operation6608
-Node: Blockers8459
-Node: Triggers8745
-Node: Syntax9007
-Node: Basic Features9697
-Node: Finders10000
-Node: ancestors11765
-Node: children12359
-Node: descendants12769
-Node: file13291
-Node: first-child14040
-Node: ids14300
-Node: match14961
-Node: next-sibling15599
-Node: next-sibling-wrap15856
-Node: olp16170
-Node: org-file16582
-Node: parent17227
-Node: previous-sibling17425
-Node: previous-sibling-wrap17686
-Node: relatives17965
-Node: rest-of-siblings21586
-Node: rest-of-siblings-wrap21871
-Node: self22220
-Node: siblings22381
-Node: siblings-wrap22618
-Node: Actions22922
-Node: Scheduled/Deadline23664
-Node: TODO State27239
-Node: Archive27607
-Node: Chain Property27927
-Node: Clocking28210
-Node: Property28622
-Node: Priority30809
-Node: Tag31378
-Node: Effort31595
-Node: Advanced Features31984
-Node: Finder Cache32432
-Node: Conditions33471
-Node: done34107
-Node: headings34271
-Node: todo-state34647
-Node: variable-set34903
-Node: has-property35332
-Node: re-search35601
-Node: Negating Conditions35961
-Node: Consideration36348
-Node: Conditional Forms37917
-Node: Setting the Properties40573
-Node: Extending Edna41657
-Node: Naming Conventions42147
-Node: Finders 142608
-Node: Actions 142970
-Node: Conditions 143429
-Node: Contributing44315
-Node: Bugs45181
-Node: Working with EDE45538
-Node: Compiling Edna46622
-Node: Testing Edna47491
-Node: Before Sending Changes48472
-Node: Developing with Bazaar49159
-Node: Documentation49900
-Node: Changelog50356
-Node: 10beta850606
-Node: 10beta750718
-Node: 10beta651012
-Node: 10beta551288
-Node: 10beta451675
-Node: 10beta351928
-Node: 10beta252367
+Node: Copying4165
+Node: Introduction4987
+Node: Installation and Setup5935
+Node: Basic Operation6659
+Node: Blockers8510
+Node: Triggers8796
+Node: Syntax9058
+Node: Basic Features9748
+Node: Finders10102
+Node: ancestors11867
+Node: children12461
+Node: descendants12871
+Node: file13393
+Node: first-child14142
+Node: ids14402
+Node: match15063
+Node: next-sibling15701
+Node: next-sibling-wrap15958
+Node: olp16272
+Node: org-file16684
+Node: parent17329
+Node: previous-sibling17527
+Node: previous-sibling-wrap17788
+Node: relatives18067
+Node: rest-of-siblings21688
+Node: rest-of-siblings-wrap21973
+Node: self22322
+Node: siblings22483
+Node: siblings-wrap22720
+Node: Actions23024
+Node: Scheduled/Deadline23787
+Node: TODO State27362
+Node: Archive27730
+Node: Chain Property28050
+Node: Clocking28333
+Node: Property28745
+Node: Priority30932
+Node: Tag31501
+Node: Effort31718
+Node: Getting Help32107
+Node: Advanced Features32552
+Node: Finder Cache33000
+Node: Conditions34039
+Node: done34675
+Node: headings34839
+Node: todo-state35215
+Node: variable-set35471
+Node: has-property35900
+Node: re-search36169
+Node: Negating Conditions36529
+Node: Consideration36916
+Node: Conditional Forms38485
+Node: Setting the Properties41141
+Node: Extending Edna42225
+Node: Naming Conventions42715
+Node: Finders 143176
+Node: Actions 143538
+Node: Conditions 143997
+Node: Contributing44883
+Node: Bugs45749
+Node: Working with EDE46106
+Node: Compiling Edna47190
+Node: Testing Edna48059
+Node: Before Sending Changes49040
+Node: Developing with Bazaar49727
+Node: Documentation50468
+Node: Changelog50924
+Node: 10beta851174
+Node: 10beta751286
+Node: 10beta651580
+Node: 10beta551856
+Node: 10beta452243
+Node: 10beta352496
+Node: 10beta252935
 
 End Tag Table
 
diff --git a/org-edna.org b/org-edna.org
index 1f01709..c0612e2 100644
--- a/org-edna.org
+++ b/org-edna.org
@@ -869,6 +869,19 @@ Sets the effort of all targets according to VALUE:
 - If VALUE is an integer, then set the value to the VALUE'th allowed effort 
property
 - If VALUE is the symbol 'increment, increment effort
 
+** Getting Help
+:PROPERTIES:
+:CUSTOM_ID: help
+:DESCRIPTION: Getting some help
+:END:
+
+Edna provides help for any keyword with ~M-x org-edna-describe-keyword~.  When
+invoked, a list of keywords (finders, actions, etc.) known to Edna will be
+provided.  Select any one to get its description.
+
+This description includes the syntax and an explanation of what the keyword
+does.  Some descriptions also contain examples.
+
 * Advanced Features
 :PROPERTIES:
 :CUSTOM_ID: advanced