[elpa] master 5010097 005/135: Added initial documentation

[Ian Dunn]

branch: master
commit 5010097011aee4862605d36afd31c11e9cddca62
Author: Ian D <address@hidden>
Commit: Ian D <address@hidden>

    Added initial documentation
---
 README.org | 300 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 300 insertions(+)

diff --git a/README.org b/README.org
new file mode 100644
index 0000000..246b62c
--- /dev/null
+++ b/README.org
@@ -0,0 +1,300 @@
+#+TITLE: Paced
+#+AUTHOR: Ian Dunn
+#+EMAIL: address@hidden
+
+* Copying
+Copyright (C) 2017 Ian Dunn
+
+#+BEGIN_QUOTE
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <http://www.gnu.org/licenses/>.
+#+END_QUOTE
+* Introduction
+:PROPERTIES:
+:CUSTOM_ID: introduction
+:END:
+:TODO:
+- [ ] *Explain how this will make peoples' lives easier*
+- [ ] Stick with one of heading, headline, or entry; don't keep switching 
between them
+:END:
+
+Org Blockers and Triggers (BAT) is an extensible means of specifying blocking
+conditions and trigger actions for Org headlines.
+
+Org BAT runs when either the BLOCKER or TRIGGER properties are set on a
+headline, and when it is changing from a TODO state to a DONE state.
+
+For brevity, we use TODO state to indicate any state in 
~org-not-done-keywords~,
+and DONE state to indicate any state in ~org-done-keywords~.
+
+** Basic Operation
+:PROPERTIES:
+:CUSTOM_ID: operation
+:END:
+Explain targets, actions, conditions
+** Blockers
+:PROPERTIES:
+:CUSTOM_ID: blockers
+:END:
+A blocker indicates conditions which must be met in order for a headline to be
+marked as DONE.  Typically, this will be a list of headlines that must be 
marked
+as DONE.
+** Triggers
+:PROPERTIES:
+:CUSTOM_ID: triggers
+:END:
+A trigger is an action triggered by setting a headline to DONE.
+* Basic Features
+:PROPERTIES:
+:CUSTOM_ID: basic
+:END:
+** Finders
+A finder specifies locations from which to test conditions or perform actions.
+These locations are referred to as "targets".
+*** ancestors
+:PROPERTIES:
+:DESCRIPTION: Find a list of ancestors
+:CUSTOM_ID: ancestors
+:END:
+
+The ~ancestors~ finder returns a list of the current headline's ancestors.
+
+For example:
+
+#+BEGIN_SRC org
+,* TODO Heading 1
+,** TODO Heading 2
+,** TODO Heading 3
+,*** TODO Heading 4
+,**** TODO Heading 5
+     :PROPERTIES:
+     :BLOCKER:  ancestors
+     :END:
+#+END_SRC
+
+In the above example, "Heading 5" will be blocked until "Heading 1", "Heading
+3", and "Heading 4" are marked "DONE", while "Heading 2" is ignored.
+*** children
+:PROPERTIES:
+:DESCRIPTION: Find all immediate children
+:CUSTOM_ID: children
+:END:
+The ~children~ finder returns a list of the *immediate* children of the current
+headline.
+
+In order to get all levels of children of the current headline, use the
+[[#descendants][descendants]] keyword instead.
+
+*** TODO descendants
+:PROPERTIES:
+:DESCRIPTION: Find all descendants
+:CUSTOM_ID: descendants
+:END:
+
+The ~descendants~ finder returns a list of all descendants of the current
+headline.
+
+EXAMPLE HERE
+
+*** file
+:PROPERTIES:
+:CUSTOM_ID: file
+:DESCRIPTION: Find a file by name
+:END:
+
+The ~file~ finder finds a single file.  The returned target will be the minimum
+point in the file.
+
+Note that with the default condition, ~file~ won't work.  See 
[[#conditions][conditions]] for how
+to set a different condition.  For example:
+
+#+BEGIN_SRC org
+,* TODO Test
+  :PROPERTIES:
+  :BLOCKER:  file("~/myfile.org") headings
+  :END:
+#+END_SRC
+
+Here, "Test" will block until myfile.org is clear of headings.
+
+*** first-child
+:PROPERTIES:
+:CUSTOM_ID: first-child
+:DESCRIPTION: Find the first child of a headline
+:END:
+
+The ~first-child~ finder returns the first child of a headline, if any.
+
+*** ids
+:PROPERTIES:
+:DESCRIPTION: Find a list of headlines with given IDs
+:CUSTOM_ID: ids
+:END:
+
+The ~ids~ finder will search for headlines with given IDs, using ~org-id~.  Any
+number of UUIDs may be specified.  For example:
+
+#+BEGIN_SRC org
+,* TODO Test
+  :PROPERTIES:
+  :BLOCKER:  
ids(62209a9a-c63b-45ef-b8a8-12e47a9ceed9,6dbd7921-a25c-4e20-b035-365677e00f30)
+  :END:
+#+END_SRC
+
+Here, "Test" will block until the headline with ID
+62209a9a-c63b-45ef-b8a8-12e47a9ceed9 and the headline with ID
+6dbd7921-a25c-4e20-b035-365677e00f30 are set to "DONE".
+
+*** match
+:PROPERTIES:
+:CUSTOM_ID: match
+:DESCRIPTION: Good old tag matching
+:END:
+
+The ~match~ keyword will take any arguments that ~org-map-entries~ usually 
takes.
+In fact, the arguments to ~match~ are passed straight into ~org-map-entries~.
+
+#+BEGIN_SRC org
+,* TODO Test
+  :PROPERTIES:
+  :BLOCKER:  match(test&mine,agenda)
+  :END:
+#+END_SRC
+
+"Test" will block until all entries tagged "test" and "mine" in the agenda 
files
+are marked DONE.
+
+See the documentation for ~org-map-entries~ for a full explanation of the first
+argument.
+
+*** next-sibling
+:PROPERTIES:
+:CUSTOM_ID: next-sibling
+:END:
+*** olp
+:PROPERTIES:
+:CUSTOM_ID: olp
+:END:
+*** org-file
+:PROPERTIES:
+:CUSTOM_ID: org-file
+:END:
+*** parent
+:PROPERTIES:
+:CUSTOM_ID: parent
+:END:
+*** previous-sibling
+:PROPERTIES:
+:CUSTOM_ID: previous-sibling
+:END:
+*** self
+:PROPERTIES:
+:CUSTOM_ID: self
+:END:
+*** siblings
+:PROPERTIES:
+:CUSTOM_ID: siblings
+:END:
+** Actions
+Once BAT has collected its targets for a trigger, it will perform actions on
+them.
+*** Scheduled/Deadline
+PLANNING(WKDY[ TIME]) -> Set PLANNING to following weekday WKDY at TIME
+PLANNING(rm|remove) -> Remove PLANNING info
+PLANNING([copy|cp]) -> Copy timestamp verbatim
+PLANNING([+|-][+|-]NTHING) -> Increment(+) or decrement(-) source (double) or 
current (single) PLANNING by N THINGs
+
+PLANNING is either scheduled or deadline
+
+WKDY is a weekday or weekday abbreviation (see org-read-date)
+
+TIME is a time string HH:MM, etc.
+
+N is an integer
+
+THING is one of y (years), m (months), d (days), h (hours), or M (minutes)
+
+Examples:
+
+scheduled(Mon 09:00) -> Set SCHEDULED to the following Monday at 9:00
+*** Todo State
+todo(NEW-STATE)
+
+Sets the TODO state of the target headline to NEW-STATE.
+*** archive
+*** set-property
+*** set-priority
+*** clock-in
+*** clock-out
+*** tag
+*** set-effort
+* Advanced Features
+:PROPERTIES:
+:CUSTOM_ID: advanced
+:END:
+** Conditions
+:PROPERTIES:
+:CUSTOM_ID: conditions
+:END:
+
+BAT gives you he option to specify *blocking conditions*.  Each condition is 
check
+for each of the specified targets; if one of the conditions returns true for
+that target, then
+
+*** done
+*** headings
+*** todo-state
+*** variable-set
+*** Negating Conditions
+You can also negate a condition using '!'.
+
+#+BEGIN_EXAMPLE
+match(test) !hasProperty(PROP,1)
+#+END_EXAMPLE
+
+The above example will cause the current headline to block if any headline
+tagged "test" does *not* have the property PROP set to 1.
+** Consideration
+Special keyword that's only valid for blockers.
+
+This keyword can allow specifying only a portion of tasks to consider:
+
+1. consider(PERCENT)
+2. consider(NUMBER)
+3. consider(all) (Default)
+
+(1) tells the blocker to only consider some portion of the targets.  If at 
least PERCENT of
+them are in a DONE state, allow the task to be set to DONE.  PERCENT must be a 
decimal.
+
+(2) tells the blocker to only consider NUMBER of the targets.
+
+(3) tells the blocker to consider all following targets.
+
+A consideration must be specified before the targets to which it applies:
+
+#+BEGIN_QUOTE
+consider(0.5) siblings consider(all) match(find_me)
+#+END_QUOTE
+
+The above code will allow task completion if at least half the siblings are
+complete, and all tasks tagged "find_me" are complete.
+
+#+BEGIN_QUOTE
+consider(1) ids(ID1,ID2,ID3) consider(2) ids(ID3,ID4,ID5,ID6)
+#+END_QUOTE
+
+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.
+* Extending BAT