refine documentation of customize variables

README.org

@@ -12,7 +12,7 @@ This package provides a system that allows you to capture incoming things into a
 
 Image courtesy of https://xebia.com/blog/peace-of-mind-in-a-state-of-overload/gtd_chart/
 ** Updating ~org-gtd~
-Please read the [[CHANGELOG.org][CHANGELOG]].
+Please read the [[./CHANGELOG.org][CHANGELOG]].
 *** 2.0.0 <- 1.1.x
 - rename CANCELED to CNCL
 ** Installing
@@ -65,13 +65,13 @@ Finally, add this to your config:
 Here is what you need to do before regular usage of ~org-gtd~:
 - read the [[*configuration options for org-gtd][configuration options for org-gtd]] section.
 - Find the ~incubate.org~ file and add some incubation categories as top-level headlines. This is intended to be helpful when opening the file during your recurring reviews. For instance, I use things like this:
-  #+begin_src org-mode
+  #+begin_quote
 * To Read
 * To Write
 * To Play
 * To Eat
 * To Visit
-  #+end_src
+  #+end_quote
 *** configuration options for org-gtd
 **** org-gtd-directory
 This is the directory where ~org-gtd~ will put the files it manages. This code includes the default value.

org-gtd-customize.el

@@ -34,16 +34,20 @@
   "Directory for org-gtd.
 
 The package will use this directory for all its functionality, whether it is
-building the agenda or refiling items."
+building the agenda or refiling items. This is the directory where you will
+find the default org-gtd file, and it is the directory where you should place
+your own files if you want multiple refile targets (projects, etc.)."
   :group 'org-gtd
   :package-version "0.1"
   :type 'directory)
 
 (defcustom org-gtd-process-item-hooks '(org-set-tags-command)
   "Enhancements to add to each item as they get processed from the inbox.
 
-This is a list of functions that modify an org element. Some built-in examples
-are provided. You can create your own functions and add them to that list"
+This is a list of functions that modify an org element. The default value has
+one function: setting org tags on the item. Some built-in examples are
+provided as options here. You can create your own functions to enhance/decorate
+the items once they have been processed and add them to that list."
   :group 'org-gtd
   :package-version "1.0.4"
   :type 'hook
@@ -55,7 +59,14 @@ are provided. You can create your own functions and add them to that list"
      (string-join `("gtd_archive_" ,year "::datetree/"))))
   "Function to generate archive location for org gtd.
 
-This function takes zero arguments. By default this generates a file
+That is to say, when items get cleaned up from the active files, they will go
+to whatever file/tree is generated by this function. See `org-archive-location'
+to learn more about the valid values generated. Note that this will only be
+the file used by the standard `org-archive' functions if you
+enable `org-gtd-mode'. If not, this will be used only by org-gtd's archive
+behavior.
+
+This function has an arity of zero. By default this generates a file
 called gtd_archive_<currentyear> in org-gtd-directory and puts the entries
 into a datetree."
   :group 'org-gtd
@@ -71,8 +82,8 @@ This is a list of lists. Each list is composed of three elements:
 
 (KEYS DESCRIPTION TEMPLATE)
 see `org-capture-templates' for the definition of each of those items.
-Make the sure the template starts with a single asterisk to denote a top-level
-heading, or the behavior of org-gtd is undefined."
+Make the sure the template string starts with a single asterisk to denote a
+top-level heading, or the behavior of org-gtd will be undefined."
   :group 'org-gtd
   :type 'sexp
   :package-version "2.0.0")
@@ -83,17 +94,26 @@ heading, or the behavior of org-gtd is undefined."
   "Agenda custom commands to be used for org-gtd.
 
 The provided default is to show the agenda for today and all TODOs marked as
-NEXT or WAIT. See documentation for `org-agenda-custom-commands' to customize this further.
+NEXT or WAIT. See documentation for `org-agenda-custom-commands' to customize
+this further.
 
 NOTE! The function `org-gtd-daily-agenda' assumes the 'g' shortcut exists.
-It's recommended you add to this list without modifying this first entry."
+It's recommended you add to this list without modifying this first entry. You
+can leverage this customization feature with `org-gtd-mode' or by wrapping your
+own custom functions with `with-org-gtd-context'."
   :group 'org-gtd
   :type 'sexp
   :package-version "2.0.0")
 
 (defcustom org-gtd-refile-to-any-target t
   "Set this to true if you do not need to choose where to refile processed items.
 
+When this is true, org-gtd will refile to the first target it finds, or creates
+if necessary, without confirmation. When this is false, it will ask for
+confirmation regardless of the number of options. Note that setting this to false
+does not mean you can safely create new targets. See the documentation to create
+new refile targets.
+
 Defaults to true to carry over pre-2.0 behavior. You will need to change this
 setting if you follow the instructions to add your own refile targets."
   :group 'org-gtd

org-gtd-mode.el

@@ -24,6 +24,8 @@
 ;;
 ;;; Code:
 
+(require 'org-agenda)
+
 ;;;###autoload
 (define-minor-mode org-gtd-mode
   "global minor mode to force org-agenda to be bounded to the org-gtd settings"
@@ -36,13 +38,21 @@
 (defun org-gtd--wrap (fun &rest r)
   (with-org-gtd-context (apply fun r)))
 
+(defconst org-gtd--agenda-functions
+  (seq-filter #'commandp (mapcar #'car (apropos "org-agenda-")))
+  "List of commands available to the user through org-agenda.
+
+Org-gtd wraps these functions with its own context when org-gtd-mode is enabled.")
+
 (defun org-gtd--override-agenda ()
-  (advice-add 'org-agenda :around #'org-gtd--wrap)
-  (advice-add 'org-agenda-list-stuck-projects :around #'org-gtd--wrap))
+  (mapc
+   (lambda (x) (advice-add x :around #'org-gtd--wrap))
+   org-gtd--agenda-functions))
 
 (defun org-gtd--restore-agenda ()
-  (advice-remove 'org-agenda #'org-gtd--wrap)
-  (advice-remove 'org-agenda-list-stuck-projects #'org-gtd--wrap))
+  (mapc
+   (lambda (x) (advice-remove x #'org-gtd--wrap))
+   org-gtd--agenda-functions))
 
 (provide 'org-gtd-mode)
 ;;; org-gtd-mode.el ends here