[elpa] master 7618794 066/135: Added in-buffer settings and new sections to Documentation

[Ian Dunn]

branch: master
commit 76187948c67e9fc63eec1d538aa5ae7b750181a8
Author: Ian D <address@hidden>
Commit: Ian D <address@hidden>

    Added in-buffer settings and new sections to Documentation
    
    * org-edna.org (Contributing): New section
    
    * .bzrignore: Ignore generated documentation files
---
 .bzrignore   |   6 ++-
 org-edna.org | 133 ++++++++++++++++++++++++++++++++++++++++++++++++++++-------
 2 files changed, 123 insertions(+), 16 deletions(-)

diff --git a/.bzrignore b/.bzrignore
index 507633b..ec97837 100644
--- a/.bzrignore
+++ b/.bzrignore
@@ -1,2 +1,6 @@
 *.elc
-local.mk
\ No newline at end of file
+local.mk
+org-edna-autoloads.el
+org-edna.info
+org-edna.texi
+org-edna.html
\ No newline at end of file
diff --git a/org-edna.org b/org-edna.org
index de72e06..da9237a 100644
--- a/org-edna.org
+++ b/org-edna.org
@@ -4,10 +4,14 @@
 #+DATE: {{{modification-time}}}
 
 #+STARTUP: overview
+#+STARTUP: indent
 #+TODO: FIXME | FIXED
-#+OPTIONS: toc:2
+#+OPTIONS: toc:2 num:nil timestamp:nil \n:nil |:t ':t email:t
+#+OPTIONS: *:t <:t d:nil todo:nil pri:nil tags:not-in-toc
 
-Extensible Dependencies 'N' Actions for Org-Mode tasks
+#+TEXINFO_DIR_CATEGORY: Emacs
+#+TEXINFO_DIR_TITLE: Org Edna: (edna)
+#+TEXINFO_DIR_DESC: Extensible Dependencies 'N' Actions for Org Mode tasks
 
 * Copying
 Copyright (C) 2017 Ian Dunn
@@ -29,9 +33,10 @@ along with this program.  If not, see 
<http://www.gnu.org/licenses/>.
 * Introduction
 :PROPERTIES:
 :CUSTOM_ID: introduction
+:DESCRIPTION: A Brief Introduction to Edna
 :END:
 
-[[https://savannah.nongnu.org/projects/org-edna-el/][Source Code on Savannah]]
+Extensible Dependencies 'N' Actions (EDNA) for Org Mode tasks
 
 Edna provides an extensible means of specifying conditions which must be
 fulfilled before a task can be completed and actions to take once it is.
@@ -43,17 +48,28 @@ 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~.
 
 ** Installation and Setup
+:PROPERTIES:
+:DESCRIPTION: How to install Edna
+:END:
+
+*Requirements*
+
+| Emacs |  25.1 |
+| seq   |  2.19 |
+| org   | 9.0.5 |
 
 Right now, the only way to install Edna is by cloning the bazaar repo:
 
 #+BEGIN_SRC shell
 bzr branch https://bzr.savannah.gnu.org/r/org-edna-el/ org-edna
+make -C org-edna compile autoloads
 #+END_SRC
 
 After that, add the following to your init file (typically .emacs):
 
 #+BEGIN_SRC emacs-lisp
 (add-to-list 'load-path "/full/path/to/org-edna/")
+(load "/path/to/org-edna/org-edna-autoloads.el")
 (org-edna-load)
 #+END_SRC
 
@@ -62,6 +78,7 @@ If you ever want to disable Edna, run ~org-edna-unload~.
 ** Basic Operation
 :PROPERTIES:
 :CUSTOM_ID: operation
+:DESCRIPTION: How to use Edna
 :END:
 
 Let's start with an example: Say you want to do laundry, but once you've put
@@ -122,16 +139,22 @@ can help:
 ** Blockers
 :PROPERTIES:
 :CUSTOM_ID: blockers
+:DESCRIPTION: Blocking a TODO Item
 :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
+:DESCRIPTION: Triggering actions after completing a task
 :END:
+
 A trigger is an action to take when a headline is set to done.  For example,
 scheduling another task, marking another task as TODO, or renaming a file.
+
 ** Syntax
 :PROPERTIES:
 :CUSTOM_ID: syntax
@@ -157,8 +180,16 @@ The parentheses can be omitted for commands with no 
arguments.
 * Basic Features
 :PROPERTIES:
 :CUSTOM_ID: basic
+:DESCRIPTION: Finders and Actions
 :END:
+
+The most basic features of Edna are *finders* and *actions*.
+
 ** Finders
+:PROPERTIES:
+:DESCRIPTION: How to find targets
+:CUSTOM_ID: finders
+:END:
 A finder specifies locations from which to test conditions or perform actions.
 These locations are referred to as "targets".
 
@@ -180,17 +211,22 @@ For example:
 #+BEGIN_SRC org
 ,* TODO Heading 1
 ,** TODO Heading 2
-,** TODO Heading 3
-,*** TODO Heading 4
-,**** TODO Heading 5
-     :PROPERTIES:
-     :BLOCKER:  ancestors
-     :END:
+,*** 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.
+
 *** chain-find
+:PROPERTIES:
+:CUSTOM_ID: chain-find
+:DESCRIPTION: Find a target as org-depend does
+:END:
 
 Syntax: chain-find(OPTION OPTION...)
 
@@ -228,8 +264,8 @@ one is specified, the last will be used.
 
 *** children
 :PROPERTIES:
-:DESCRIPTION: Find all immediate children
 :CUSTOM_ID: children
+:DESCRIPTION: Find all immediate children
 :END:
 
 Syntax: children
@@ -242,8 +278,8 @@ In order to get all levels of children of the current 
headline, use the
 
 *** descendants
 :PROPERTIES:
-:DESCRIPTION: Find all descendants
 :CUSTOM_ID: descendants
+:DESCRIPTION: Find all descendants
 :END:
 
 Syntax: descendants
@@ -257,9 +293,9 @@ headline.
    :BLOCKER:  descendants
    :END:
 ,** TODO Heading 2
-,** TODO Heading 3
-,*** TODO Heading 4
-,**** TODO Heading 5
+,*** TODO Heading 3
+,**** TODO Heading 4
+,***** TODO Heading 5
 #+END_SRC
 
 In the above example, "Heading 1" will block until Headings 2, 3, 4, and 5 are
@@ -349,6 +385,7 @@ argument.
 *** next-sibling
 :PROPERTIES:
 :CUSTOM_ID: next-sibling
+:DESCRIPTION: Find the next sibling
 :END:
 
 Syntax: next-sibling
@@ -359,6 +396,7 @@ any.
 *** olp
 :PROPERTIES:
 :CUSTOM_ID: olp
+:DESCRIPTION: Find a headline by its outline path
 :END:
 
 Syntax: olp("FILE" "OLP")
@@ -377,6 +415,7 @@ Finds the heading given by OLP in FILE.  Both arguments are 
strings.
 *** org-file
 :PROPERTIES:
 :CUSTOM_ID: org-file
+:DESCRIPTION: Find a file in org-directory
 :END:
 
 Syntax: org-file("FILE")
@@ -395,6 +434,7 @@ Note that the file still requires an extension.
 *** parent
 :PROPERTIES:
 :CUSTOM_ID: parent
+:DESCRIPTION: Find a parent
 :END:
 
 Syntax: parent
@@ -404,6 +444,7 @@ Returns the parent of the current headline, if any.
 *** previous-sibling
 :PROPERTIES:
 :CUSTOM_ID: previous-sibling
+:DESCRIPTION: Find the previous sibling
 :END:
 
 Syntax: previous-sibling
@@ -414,11 +455,13 @@ Returns the previous sibling of the current headline on 
the same level.
 *** rest-of-siblings
 :PROPERTIES:
 :CUSTOM_ID: rest-of-siblings
+:DESCRIPTION: Find the remaining siblings
 :END:
 
 Syntax: rest-of-siblings
 
-Finds the remaining siblings on the same level as the current headline.
+Starting from the headline following the current one, all same-level siblings
+are returned.
 
 *** self
 :PROPERTIES:
@@ -432,6 +475,7 @@ Returns the current headline.
 *** siblings
 :PROPERTIES:
 :CUSTOM_ID: siblings
+:DESCRIPTION: Find all the siblings
 :END:
 
 Syntax: siblings
@@ -441,6 +485,7 @@ Returns all siblings of the source heading as targets.
 *** siblings-wrap
 :PROPERTIES:
 :CUSTOM_ID: siblings-wrap
+:DESCRIPTION: Find the siblings, but wrap around
 :END:
 
 Syntax: siblings-wrap
@@ -449,6 +494,9 @@ Finds the siblings on the same level as the current 
headline, wrapping when it
 reaches the end.
 
 ** Actions
+:PROPERTIES:
+:DESCRIPTION: Next steps
+:END:
 Once Edna has collected its targets for a trigger, it will perform actions on
 them.
 
@@ -700,12 +748,18 @@ are complete, and at least two of ID3, ID4, ID5, and ID6 
are complete.
 
 If no consideration is given, ALL is assumed.
 * Extending Edna
+:PROPERTIES:
+:DESCRIPTION: What else can it do?
+:END:
 
 Extending Edna is (relatively) simple.
 
 During operation, Edna searches for functions of the form 
org-edna-TYPE/KEYWORD.
 
 ** Naming Conventions
+:PROPERTIES:
+:DESCRIPTION: How to name new functions
+:END:
 
 In order to distinguish between actions, finders, and conditions, we add '?' to
 conditions and '!' to actions.  This is taken from the practice in Guile and
@@ -715,6 +769,9 @@ Thus, one can have an action that files a target, and a 
finder that finds a
 file.
 
 ** Finders
+:PROPERTIES:
+:DESCRIPTION: Making a new finder
+:END:
 
 Finders have the form org-edna-finder/KEYWORD, like so:
 
@@ -727,6 +784,9 @@ All finders must return a list of markers, one for each 
target found, or nil if
 no targets were found.
 
 ** Actions
+:PROPERTIES:
+:DESCRIPTION: Making a new action
+:END:
 
 Actions have the form org-edna-action/KEYWORD!:
 
@@ -741,6 +801,9 @@ current entry (not to be confused with the current target).
 The rest of the arguments are the arguments specified in the form.
 
 ** Conditions
+:PROPERTIES:
+:DESCRIPTION: Making a new condition
+:END:
 
 #+BEGIN_SRC emacs-lisp
 (defun org-edna-condition/test-cond? (neg))
@@ -772,3 +835,43 @@ This is an XOR table, so we pass CONDITION and NEG into 
~org-xor~ to get our
 result.
 
 A condition must return a string if the current entry should be blocked.
+* Contributing
+:PROPERTIES:
+:DESCRIPTION: I wanna help!
+:END:
+
+We are all happy for any help you may provide.
+
+First, check out the source code on Savannah: 
https://savannah.nongnu.org/projects/org-edna-el/
+
+#+BEGIN_SRC shell
+bzr branch https://bzr.savannah.gnu.org/r/org-edna-el/ org-edna
+#+END_SRC
+
+You'll also want a copy of the most recent Org Mode source:
+
+#+BEGIN_SRC shell
+git clone git://orgmode.org/org-mode.git
+#+END_SRC
+
+*Bugs*
+
+There are two ways to submit bug reports:
+
+1. Using the bug tracker at Savannah
+2. Sending an email using ~org-edna-submit-bug-report~
+
+When submitting a bug report, be sure to include the Edna form that caused the
+bug, with as much context as possible.
+
+*Development*
+
+Submitting patches along with a bug report is the easiest way.
+
+There are a few rules to follow:
+
+- Verify that any new Edna keywords follow the appropriate naming conventions
+- Any new keywords should be documented
+- Run 'make check' to verify that your mods don't break anything
+- Avoid additional or altered dependencies if at all possible
+  - Exception: New versions of Org mode are allowed