[elpa] master 7aa71e7 06/14: Added documentation for popout editing

[Ian Dunn]

branch: master
commit 7aa71e71335171d248a60c4b61d18455e628e8e2
Author: Ian Dunn <address@hidden>
Commit: Ian Dunn <address@hidden>

    Added documentation for popout editing
    
    * org-edna.el (org-edna-edit): Added explanation of how to abort changes.
    
    * org-edna.org (Setting the Properties): New section
    
    * org-edna.info: Updated from org-edna.org
---
 org-edna.el   |   5 +-
 org-edna.info | 168 +++++++++++++++++++++++++++++++++++-----------------------
 org-edna.org  |  39 +++++++++++++-
 3 files changed, 143 insertions(+), 69 deletions(-)

diff --git a/org-edna.el b/org-edna.el
index ccee794..c8e466d 100644
--- a/org-edna.el
+++ b/org-edna.el
@@ -1111,10 +1111,9 @@ Form 3: consider the condition met if only P% of the 
targets pass."
     (setq-local org-window-configuration wc)
     (setq-local org-selected-window sel-win)
     (setq-local org-finish-function 'org-edna-edit-finish)
-    (insert (substitute-command-keys "\\<org-mode-map>\
-Edit blockers and triggers in this buffer under their respective sections 
below.
+    (insert "Edit blockers and triggers in this buffer under their respective 
sections below.
 All lines under a given section will be merged into one when saving back to
-the source buffer.  Finish with `\\[org-ctrl-c-ctrl-c]' or 
`\\[org-edit-special]'.\n\n"))
+the source buffer.  Finish with `C-c C-c' or abort with `C-c C-k'")
     (setq-local org-edna-blocker-section-marker (point-marker))
     (insert (format "BLOCKER\n%s\n\n" blocker))
     (setq-local org-edna-trigger-section-marker (point-marker))
diff --git a/org-edna.info b/org-edna.info
index bf4d14b..999d669 100644
--- a/org-edna.info
+++ b/org-edna.info
@@ -75,6 +75,7 @@ Advanced Features
 
 * Conditions::
 * Consideration::
+* Setting the properties::
 
 Conditions
 
@@ -852,6 +853,7 @@ Advanced Features
 
 * Conditions::
 * Consideration::
+* Setting the properties::
 
 
 File: org-edna.info,  Node: Conditions,  Next: Consideration,  Up: Advanced 
Features
@@ -861,7 +863,11 @@ Conditions
 
 Edna gives you he option to specify *blocking conditions*.  Each
 condition is checked for each of the specified targets; if one of the
-conditions returns true for that target, then that heading is blocked.
+conditions returns true for that target, then the source heading is
+blocked.
+
+   If no condition is specified, ‘!done?’ is used by default, which
+means block if any target heading isn’t done.
 
 * Menu:
 
@@ -881,7 +887,7 @@ done
 
    • Syntax: done?
 
-   Blocks the source heading if any target is DONE.
+   Blocks the source heading if any target heading is DONE.
 
 
 File: org-edna.info,  Node: headings,  Next: todo-state,  Prev: done,  Up: 
Conditions
@@ -892,7 +898,7 @@ headings
    • Syntax: headings?
 
    Blocks the source heading if any target belongs to a file that has an
-Org heading.
+Org heading.  This means that target does not have to be a heading.
 
      org-file("refile.org") headings?
 
@@ -906,7 +912,7 @@ todo-state
 
    • Syntax: todo-state?(STATE)
 
-   Blocks if any target has a heading with TODO state set to STATE.
+   Blocks if any target heading has TODO state set to STATE.
 
    STATE may be a string or a symbol.
 
@@ -918,11 +924,12 @@ variable-set
 
    • Syntax: variable-set?(VARIABLE VALUE)
 
-   Blocks the source heading if VARIABLE is set to VALUE.
+   Evaluate VARIABLE when visiting a target, and compare it with ‘equal’
+against VALUE. Block the source heading if VARIABLE = VALUE.
 
-   VARIABLE should be a symbol, and VALUE is any valid lisp expression
+   VARIABLE should be a symbol, and VALUE is any valid lisp expression.
 
-     self variable-set?(test-variable,12)
+     self variable-set?(test-variable 12)
 
 
 File: org-edna.info,  Node: has-property,  Next: re-search,  Prev: 
variable-set,  Up: Conditions
@@ -955,15 +962,15 @@ File: org-edna.info,  Node: Negating Conditions,  Prev: 
re-search,  Up: Conditio
 Negating Conditions
 -------------------
 
-Any condition can be negated using ’!’.
+Any condition can be negated by using ’!’ before the condition.
 
-     match("test") !has-property?("PROP","1")
+     match("test") !has-property?("PROP" "1")
 
    The above example will cause the source heading to block if any
 heading tagged “test” does *not* have the property PROP set to “1”.
 
 
-File: org-edna.info,  Node: Consideration,  Prev: Conditions,  Up: Advanced 
Features
+File: org-edna.info,  Node: Consideration,  Next: Setting the properties,  
Prev: Conditions,  Up: Advanced Features
 
 Consideration
 =============
@@ -1002,6 +1009,36 @@ are complete.
    If no consideration is given, ALL is assumed.
 
 
+File: org-edna.info,  Node: Setting the properties,  Prev: Consideration,  Up: 
Advanced Features
+
+Setting the properties
+======================
+
+There are two ways to set the BLOCKER and TRIGGER properties: by hand,
+or the easy way.  You can probably guess which way we prefer.
+
+   With point within the heading you want to edit, type ‘M-x
+org-edna-edit’.  You end up in a buffer that looks like this:
+
+     Edit blockers and triggers in this buffer under their respective sections 
below.
+     All lines under a given section will be merged into one when saving back 
to
+     the source buffer.  Finish with `C-c C-c' or abort with `C-c C-k'.
+
+     BLOCKER
+     BLOCKER STUFF HERE
+
+     TRIGGER
+     TIRGGER STUFF HERE
+
+   In here, you can edit the blocker and trigger properties for the
+original heading in a cleaner environment.  More importantly, you can
+complete the names of any valid keyword within the BLOCKER or TRIGGER
+sections using ‘completion-at-point’.
+
+   When finished, type ‘C-c C-c’ to apply the changes, or ‘C-c C-k’ to
+throw out your changes.
+
+
 File: org-edna.info,  Node: Extending Edna,  Next: Contributing,  Prev: 
Advanced Features,  Up: Top
 
 Extending Edna
@@ -1169,61 +1206,62 @@ We can then merge that into the main development branch.
 
 Tag Table:
 Node: Top225
-Node: Copying3115
-Node: Introduction3932
-Node: Installation and Setup4880
-Node: Basic Operation5673
-Node: Blockers7524
-Node: Triggers7810
-Node: Syntax8072
-Node: Basic Features8762
-Node: Finders9065
-Node: ancestors10568
-Node: chain-find11152
-Node: children12490
-Node: descendants12889
-Node: file13399
-Node: first-child14148
-Node: ids14396
-Node: match15057
-Node: next-sibling15695
-Node: next-sibling-wrap15940
-Node: olp16242
-Node: org-file16654
-Node: parent17299
-Node: previous-sibling17485
-Node: rest-of-siblings17729
-Node: self17992
-Node: siblings18148
-Node: siblings-wrap18406
-Node: Actions18639
-Node: Scheduled/Deadline19381
-Node: TODO State20971
-Node: Archive21339
-Node: Chain Property21659
-Node: Clocking21942
-Node: Property22354
-Node: Priority22676
-Node: Tag23245
-Node: Effort23462
-Node: Advanced Features23851
-Node: Conditions24036
-Node: done24524
-Node: headings24680
-Node: todo-state25001
-Node: variable-set25264
-Node: has-property25612
-Node: re-search25881
-Node: Negating Conditions26241
-Node: Consideration26604
-Node: Extending Edna27780
-Node: Naming Conventions28270
-Node: Finders (1)28733
-Node: Actions (1)29099
-Node: Conditions (1)29564
-Node: Contributing30454
-Node: Bugs30926
-Node: Development31278
+Node: Copying3142
+Node: Introduction3959
+Node: Installation and Setup4907
+Node: Basic Operation5700
+Node: Blockers7551
+Node: Triggers7837
+Node: Syntax8099
+Node: Basic Features8789
+Node: Finders9092
+Node: ancestors10595
+Node: chain-find11179
+Node: children12517
+Node: descendants12916
+Node: file13426
+Node: first-child14175
+Node: ids14423
+Node: match15084
+Node: next-sibling15722
+Node: next-sibling-wrap15967
+Node: olp16269
+Node: org-file16681
+Node: parent17326
+Node: previous-sibling17512
+Node: rest-of-siblings17756
+Node: self18019
+Node: siblings18175
+Node: siblings-wrap18433
+Node: Actions18666
+Node: Scheduled/Deadline19408
+Node: TODO State20998
+Node: Archive21366
+Node: Chain Property21686
+Node: Clocking21969
+Node: Property22381
+Node: Priority22703
+Node: Tag23272
+Node: Effort23489
+Node: Advanced Features23878
+Node: Conditions24090
+Node: done24705
+Node: headings24869
+Node: todo-state25245
+Node: variable-set25501
+Node: has-property25930
+Node: re-search26199
+Node: Negating Conditions26559
+Node: Consideration26946
+Node: Setting the properties28153
+Node: Extending Edna29233
+Node: Naming Conventions29723
+Node: Finders (1)30186
+Node: Actions (1)30552
+Node: Conditions (1)31017
+Node: Contributing31907
+Node: Bugs32379
+Node: Development32731
 
 End Tag Table
 
diff --git a/org-edna.org b/org-edna.org
index 17b394f..cd34193 100644
--- a/org-edna.org
+++ b/org-edna.org
@@ -708,6 +708,7 @@ Sets the effort of all targets according to VALUE:
 ** Conditions
 :PROPERTIES:
 :CUSTOM_ID: conditions
+:DESCRIPTION: More than just DONE headings
 :END:
 
 Edna gives you he option to specify *blocking conditions*.  Each condition is 
checked
@@ -805,7 +806,11 @@ match("test") !has-property?("PROP" "1")
 The above example will cause the source heading to block if any heading
 tagged "test" does *not* have the property PROP set to "1".
 ** Consideration
-Special keyword that's only valid for blockers.
+:PROPERTIES:
+:DESCRIPTION: Only some of them
+:END:
+
+"Consideration" is a special keyword that's only valid for blockers.
 
 This keyword can allow specifying only a portion of tasks to consider:
 
@@ -838,6 +843,38 @@ The above code will allow task completion if at least one 
of ID1, ID2, and ID3
 are complete, and at least two of ID3, ID4, ID5, and ID6 are complete.
 
 If no consideration is given, ALL is assumed.
+
+** Setting the properties
+:PROPERTIES:
+:DESCRIPTION: The easy way to set BLOCKER and TRIGGER
+:END:
+
+There are two ways to set the BLOCKER and TRIGGER properties: by hand, or the
+easy way.  You can probably guess which way we prefer.
+
+With point within the heading you want to edit, type ~M-x org-edna-edit~.  You 
end
+up in a buffer that looks like this:
+
+#+begin_example
+Edit blockers and triggers in this buffer under their respective sections 
below.
+All lines under a given section will be merged into one when saving back to
+the source buffer.  Finish with `C-c C-c' or abort with `C-c C-k'.
+
+BLOCKER
+BLOCKER STUFF HERE
+
+TRIGGER
+TIRGGER STUFF HERE
+#+end_example
+
+In here, you can edit the blocker and trigger properties for the original
+heading in a cleaner environment.  More importantly, you can complete the names
+of any valid keyword within the BLOCKER or TRIGGER sections using
+~completion-at-point~.
+
+When finished, type ~C-c C-c~ to apply the changes, or ~C-c C-k~ to throw out 
your
+changes.
+
 * Extending Edna
 :PROPERTIES:
 :DESCRIPTION: What else can it do?