branch: master commit dcad8cc8085843ddd2f172aadf5c0456df13de37 Author: Ian Dunn <du...@gnu.org> Commit: Ian Dunn <du...@gnu.org>
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