[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[elpa] master 7294b59 7/7: Merge commit '26b0a6e6fb03fe4b895bb03972bbb0d
|
From: |
Ian Dunn |
|
Subject: |
[elpa] master 7294b59 7/7: Merge commit '26b0a6e6fb03fe4b895bb03972bbb0d80ce2e8e3' |
|
Date: |
Sun, 11 Nov 2018 15:04:52 -0500 (EST) |
branch: master
commit 7294b5971588676b80319d3086679f0341e8fb7a
Merge: 4ce0ed8 26b0a6e
Author: Ian Dunn <address@hidden>
Commit: Ian Dunn <address@hidden>
Merge commit '26b0a6e6fb03fe4b895bb03972bbb0d80ce2e8e3'
---
packages/org-edna/org-edna-tests.el | 95 ++++++++++-
packages/org-edna/org-edna.el | 97 ++++++++++-
packages/org-edna/org-edna.info | 322 ++++++++++++++++++++++++++----------
packages/org-edna/org-edna.org | 154 +++++++++++++++--
4 files changed, 557 insertions(+), 111 deletions(-)
diff --git a/packages/org-edna/org-edna-tests.el
b/packages/org-edna/org-edna-tests.el
index 0a9ddca..890ddd9 100644
--- a/packages/org-edna/org-edna-tests.el
+++ b/packages/org-edna/org-edna-tests.el
@@ -270,7 +270,7 @@
'(let ((targets1 nil)
(consideration1 nil)
(blocking-entry1 nil))
- (setq targets1 (org-edna--add-targets targets1
(org-edna-finder/self)))
+ (setq targets1 (org-edna--add-targets targets1
(org-edna--handle-finder 'org-edna-finder/self (quote))))
(setq blocking-entry1
(or blocking-entry1
(org-edna--handle-condition 'org-edna-condition/done?
@@ -303,7 +303,7 @@
(blocking-entry2 blocking-entry1))
(setq targets2
(org-edna--add-targets targets2
- (org-edna-finder/match
"checklist")))
+ (org-edna--handle-finder
'org-edna-finder/match '"checklist")))
(org-edna--handle-action 'org-edna-action/todo!
targets2
(point-marker)
@@ -313,7 +313,7 @@
(blocking-entry5 blocking-entry1))
(setq targets5
(org-edna--add-targets targets5
- (org-edna-finder/siblings)))
+ (org-edna--handle-finder
'org-edna-finder/siblings (quote))))
(org-edna--handle-action 'org-edna-action/todo!
targets5
(point-marker)
@@ -355,7 +355,7 @@
;; Add targets for checklist match
(setq targets3
(org-edna--add-targets targets3
- (org-edna-finder/match
"checklist")))
+ (org-edna--handle-finder
'org-edna-finder/match '"checklist")))
;; Handle condition
(setq blocking-entry3
(or blocking-entry3
@@ -365,7 +365,7 @@
;; Add targets for self finder
(setq targets1
(org-edna--add-targets targets1
- (org-edna-finder/self)))
+ (org-edna--handle-finder
'org-edna-finder/self (quote))))
;; Mark as TODO
(org-edna--handle-action 'org-edna-action/todo! targets1
(point-marker)
@@ -375,7 +375,7 @@
;; Find siblings
(setq targets1
(org-edna--add-targets targets1
- (org-edna-finder/siblings)))
+ (org-edna--handle-finder
'org-edna-finder/siblings (quote))))
;; Mark as DONE
(org-edna--handle-action 'org-edna-action/todo! targets1
(point-marker)
@@ -416,7 +416,7 @@
;; Add targets for checklist match
(setq targets3
(org-edna--add-targets targets3
- (org-edna-finder/match
"checklist")))
+ (org-edna--handle-finder
'org-edna-finder/match '"checklist")))
;; Handle condition
(setq blocking-entry3
(or blocking-entry3
@@ -426,7 +426,7 @@
;; Add targets for self finder
(setq targets1
(org-edna--add-targets targets1
- (org-edna-finder/self)))
+ (org-edna--handle-finder
'org-edna-finder/self (quote))))
;; Mark as TODO
(org-edna--handle-action 'org-edna-action/todo! targets1
(point-marker)
@@ -1073,6 +1073,61 @@
(org-with-point-at current
(org-edna-finder/relatives arg 'deadline-down size))))))
+(ert-deftest org-edna-cache/no-entry ()
+ (let* ((org-edna-finder-use-cache t)
+ (org-edna--finder-cache (make-hash-table :test 'equal)))
+ ;; Empty, so `org-edna--get-cache-entry' should return nil.
+ (should (not (org-edna--get-cache-entry 'org-edna-finder/match
'("test&1"))))))
+
+(ert-deftest org-edna-cache/added-new-entry ()
+ (let* ((org-edna-finder-use-cache t)
+ (org-edna--finder-cache (make-hash-table :test 'equal))
+ (org-agenda-files `(,org-edna-test-file))
+ (targets (org-edna--handle-finder 'org-edna-finder/match "test&1")))
+ (should (= (length targets) 2))
+ (should (string-equal (org-edna-heading (nth 0 targets)) "Tagged Heading
1"))
+ (should (string-equal (org-edna-heading (nth 1 targets)) "Tagged Heading
2"))
+ (should (= (hash-table-count org-edna--finder-cache) 1))
+ ;; Verify that we've got a valid cache entry.
+ (should (org-edna--get-cache-entry 'org-edna-finder/match '("test&1")))
+ ;; Verify that any other signature returns nil.
+ (should (not (org-edna--get-cache-entry 'org-edna-finder/match
'("test&2"))))
+ (let ((cache-entry (gethash (make-org-edna--finder-input :func-sym
'org-edna-finder/match
+ :args '("test&1"))
+ org-edna--finder-cache)))
+ (should cache-entry)
+ (should (equal (org-edna--finder-cache-entry-input cache-entry)
+ (make-org-edna--finder-input :func-sym
'org-edna-finder/match
+ :args '("test&1"))))
+ (should (equal (org-edna--finder-cache-entry-results cache-entry)
+ targets)))))
+
+(ert-deftest org-edna-cache/timed-out ()
+ (let* ((org-edna-finder-use-cache t)
+ (org-edna--finder-cache (make-hash-table :test 'equal))
+ (org-edna-finder-cache-timeout 1) ;; Set timeout to 1 second
+ (org-agenda-files `(,org-edna-test-file))
+ (targets (org-edna--handle-finder 'org-edna-finder/match "test&1"))
+ ;; Time increment required to invalidate a cache entry
+ (time-increment `(0 ,org-edna-finder-cache-timeout)))
+ (should (org-edna--get-cache-entry 'org-edna-finder/match '("test&1")))
+ ;; Validate the cache entry
+ (let ((cache-entry (gethash (make-org-edna--finder-input :func-sym
'org-edna-finder/match
+ :args '("test&1"))
+ org-edna--finder-cache)))
+ (should cache-entry)
+ (should (equal (org-edna--finder-cache-entry-input cache-entry)
+ (make-org-edna--finder-input :func-sym
'org-edna-finder/match
+ :args '("test&1"))))
+ (should (equal (org-edna--finder-cache-entry-results cache-entry)
+ targets))
+ ;; Override `current-time' so we can get a deterministic value
+ ;; The value invalidates the cache entry
+ (cl-letf* (((symbol-function 'current-time)
+ (lambda () (time-add
(org-edna--finder-cache-entry-last-run-time cache-entry)
+ time-increment))))
+ (should (not (org-edna--get-cache-entry 'org-edna-finder/match
'("test&1"))))))))
+
;; Actions
@@ -1198,6 +1253,30 @@
(should (string-equal (org-entry-get nil "SCHEDULED")
"<2000-01-15 Sat 00:00>")))))
+(ert-deftest org-edna-action-scheduled/landing-no-hour ()
+ "Test landing arguments to scheduled increment, without hour."
+ ;; Override `current-time' so we can get a deterministic value
+ (cl-letf* (((symbol-function 'current-time) (lambda () org-edna-test-time))
+ (org-agenda-files `(,org-edna-test-file))
+ (target (org-id-find "caf27724-0887-4565-9765-ed2f1edcfb16" t)))
+ (org-with-point-at target
+ ;; Time starts at Jan 1, 2017
+ (org-edna-action/scheduled! nil "2017-01-01 Sun")
+ (should (string-equal (org-entry-get nil "SCHEDULED")
+ "<2017-01-01 Sun>"))
+ ;; Move forward 10 days, then backward until we find a weekend
+ (org-edna-action/scheduled! nil "+10d -wknd")
+ (should (string-equal (org-entry-get nil "SCHEDULED")
+ "<2017-01-08 Sun>"))
+ ;; Move forward one week, then forward until we find a weekday
+ (org-edna-action/scheduled! nil "+1w +wkdy")
+ (should (string-equal (org-entry-get nil "SCHEDULED")
+ "<2017-01-16 Mon>"))
+ ;; Back to Saturday for other tests
+ (org-edna-action/scheduled! nil "2017-01-01 Sun")
+ (should (string-equal (org-entry-get nil "SCHEDULED")
+ "<2017-01-01 Sun>")))))
+
(ert-deftest org-edna-action-scheduled/float ()
(cl-letf* (((symbol-function 'current-time) (lambda () org-edna-test-time))
(org-agenda-files `(,org-edna-test-file))
diff --git a/packages/org-edna/org-edna.el b/packages/org-edna/org-edna.el
index 9974e3a..37c9849 100644
--- a/packages/org-edna/org-edna.el
+++ b/packages/org-edna/org-edna.el
@@ -7,7 +7,7 @@
;; Keywords: convenience, text, org
;; URL: https://savannah.nongnu.org/projects/org-edna-el/
;; Package-Requires: ((emacs "25.1") (seq "2.19") (org "9.0.5"))
-;; Version: 1.0beta6
+;; Version: 1.0beta7
;; This file is part of GNU Emacs.
@@ -387,7 +387,7 @@ correspond to internal variables."
(`(,type . ,func) (org-edna--function-for-key key)))
(pcase type
('finder
- `(setq ,target-var (org-edna--add-targets ,target-var (,func ,@args))))
+ `(setq ,target-var (org-edna--add-targets ,target-var
(org-edna--handle-finder ',func ',@args))))
('action
`(org-edna--handle-action ',func ,target-var (point-marker) ',args))
('condition
@@ -464,6 +464,99 @@ which of the two types is allowed in STRING-FORM."
(org-edna-eval-sexp-form
(org-edna-string-form-to-sexp-form string-form action-or-condition)))
+;;; Cache
+
+;; Cache works because the returned values of finders are all markers. Markers
+;; will automatically update themselves when a buffer is edited.
+
+;; We use a timeout for cache because it's expected that the Org files
+;; themselves will change. Thus, there's no assured way to determine if we
need
+;; to update the cache without actually running again. Therefore, we assume
+;; most operations that the user wants to expedite will be performed in bulk.
+
+(cl-defstruct org-edna--finder-input
+ func-sym args)
+
+(cl-defstruct org-edna--finder-cache-entry
+ input results last-run-time)
+
+(defvar org-edna--finder-cache (make-hash-table :test 'equal))
+
+(defcustom org-edna-finder-use-cache nil
+ "Whether to use cache for improved performance with finders.
+
+When cache is used for a finder, each finder call will store its
+results for up to `org-edna-finder-cache-timeout' seconds. The
+results and input are both stored, so the same form for a given
+finder will yield the results of the previous call.
+
+If enough time has passed since the results in cache for a
+specific form were generated, the results will be regenerated and
+stored in cache.
+
+Minor changes to an Org file, such as setting properties or
+adding unrelated headlines, will be taken into account."
+ :group 'org-edna
+ :type 'boolean)
+
+(defcustom org-edna-finder-cache-timeout 300
+ "Maximum age to keep entries in cache, in seconds."
+ :group 'org-edna
+ :type 'number)
+
+(defun org-edna--add-to-finder-cache (func-sym args)
+ (let* ((results (apply func-sym args))
+ (input (make-org-edna--finder-input :func-sym func-sym
+ :args args))
+ (entry (make-org-edna--finder-cache-entry :input input
+ :results results
+ :last-run-time
(current-time))))
+ (puthash input entry org-edna--finder-cache)
+ ;; Returning the results here passes them to the calling function. It's
the
+ ;; only part of the entry we care about here.
+ results))
+
+(defun org-edna--finder-cache-timeout (_func-sym)
+ ;; In the future, we may want to support configurable timeouts on a
per-finder
+ ;; basis.
+ org-edna-finder-cache-timeout)
+
+(defun org-edna--get-cache-entry (func-sym args)
+ "Find a valid entry in the cache.
+
+If none exists, return nil. An entry is invalid for any of the
+following reasons:
+
+- It doesn't exist
+- It has timed out
+- It contains an invalid marker"
+ (let* ((input (make-org-edna--finder-input :func-sym func-sym
+ :args args))
+ (entry (gethash input org-edna--finder-cache)))
+ (cond
+ ;; If we don't have an entry, rerun and make a new one.
+ ((not entry) nil)
+ ;; If we do have an entry, but it's timed out, then create a new one.
+ ((>= (float-time (time-subtract (current-time)
+
(org-edna--finder-cache-entry-last-run-time entry)))
+ (org-edna--finder-cache-timeout func-sym))
+ nil)
+ ;; If any element of the results is an invalid marker, then rerun.
+ ((seq-find (lambda (x) (not (markerp x)))
(org-edna--finder-cache-entry-results entry) nil)
+ nil)
+ ;; We have an entry created within the allowed interval.
+ (t entry))))
+
+(defun org-edna--handle-finder (func-sym &rest args)
+ (if (not org-edna-finder-use-cache)
+ ;; Not using cache, so use the function directly.
+ (apply func-sym args)
+ (let* ((entry (org-edna--get-cache-entry func-sym args)))
+ (if entry
+ (org-edna--finder-cache-entry-results entry)
+ ;; Adds the entry to the cache, and returns the results.
+ (org-edna--add-to-finder-cache func-sym args)))))
+
(defmacro org-edna-run (change-plist &rest body)
diff --git a/packages/org-edna/org-edna.info b/packages/org-edna/org-edna.info
index 33b6708..fde1e6e 100644
--- a/packages/org-edna/org-edna.info
+++ b/packages/org-edna/org-edna.info
@@ -76,6 +76,7 @@ Actions
Advanced Features
+* Finder Cache:: Making the finders work faster
* Conditions:: More than just DONE headings
* Consideration:: Only some of them
* Conditional Forms:: If/Then/Else
@@ -102,11 +103,16 @@ Extending Edna
Contributing
* Bugs::
-* Development::
+* Working with EDE:: And all its quirks
+* Compiling Edna:: How to compile Edna
+* Testing Edna:: Ensuring Edna works the way we think she will
+* Before Sending Changes:: Follow these instructions before sending us
anything
+* Developing with Bazaar:: How to use this strange VCS
* Documentation:: Improving the documentation
Changelog
+* 1.0beta7: 10beta7.
* 1.0beta6: 10beta6.
* 1.0beta5: 10beta5.
* 1.0beta4: 10beta4.
@@ -184,13 +190,12 @@ org 9.0.5
From Source:
bzr branch https://bzr.savannah.gnu.org/r/org-edna-el/ org-edna
- make -C org-edna compile autoloads
After that, add the following to your init file (typically .emacs):
;; Only necessary if installing from source
(add-to-list 'load-path "/full/path/to/org-edna/")
- (load "/path/to/org-edna/org-edna-autoloads.el")
+ (require 'org-edna)
;; Always necessary
(org-edna-load)
@@ -1056,13 +1061,39 @@ Advanced Features
* Menu:
+* Finder Cache:: Making the finders work faster
* Conditions:: More than just DONE headings
* Consideration:: Only some of them
* Conditional Forms:: If/Then/Else
* Setting the Properties:: The easy way to set BLOCKER and TRIGGER
-File: org-edna.info, Node: Conditions, Next: Consideration, Up: Advanced
Features
+File: org-edna.info, Node: Finder Cache, Next: Conditions, Up: Advanced
Features
+
+Finder Cache
+============
+
+Some finders, ‘match’ in particular, can take a long time to run.
+Oftentimes, this can make it unappealing to use Edna at all, especially
+with long checklists.
+
+ The finder cache is one solution to this. To enable it, set
+‘org-edna-finder-use-cache’ to non-nil. This can be done through the
+customization interface, or manually with ‘setq’.
+
+ When enabled, the cache will store the results of every finder form
+for a configurable amount of time. This timeout is controlled by
+‘org-edna-finder-cache-timeout’. The cache is also invalidated if any
+of the results are invalid, which can happen if their target files have
+been closed.
+
+ For example, if there are several entries in a checklist that all use
+the form ‘match("daily")’ as part of their trigger, the results of that
+form will be cached. When the next item is marked as DONE, the results
+will be searched for in cache, not recomputed.
+
+
+File: org-edna.info, Node: Conditions, Next: Consideration, Prev: Finder
Cache, Up: Advanced Features
Conditions
==========
@@ -1441,11 +1472,15 @@ We are all happy for any help you may provide.
* Menu:
* Bugs::
-* Development::
+* Working with EDE:: And all its quirks
+* Compiling Edna:: How to compile Edna
+* Testing Edna:: Ensuring Edna works the way we think she will
+* Before Sending Changes:: Follow these instructions before sending us
anything
+* Developing with Bazaar:: How to use this strange VCS
* Documentation:: Improving the documentation
-File: org-edna.info, Node: Bugs, Next: Development, Up: Contributing
+File: org-edna.info, Node: Bugs, Next: Working with EDE, Up: Contributing
Bugs
====
@@ -1459,10 +1494,111 @@ There are two ways to submit bug reports:
caused the bug, with as much context as possible.
-File: org-edna.info, Node: Development, Next: Documentation, Prev: Bugs,
Up: Contributing
+File: org-edna.info, Node: Working with EDE, Next: Compiling Edna, Prev:
Bugs, Up: Contributing
+
+Working with EDE
+================
+
+Our build system uses EDE. EDE can be a little finicky at times, but we
+feel the benefits, namely package dependency handling and Makefile
+generation, outweigh the costs.
+
+ One of the issues that many will likely encounter is the error
+“Corrupt file on disk”. This is most often due to EDE not loading all
+its subprojects as needed. If you find yourself dealing with this error
+often, place the following in your .emacs file:
+
+ ;; Target types needed for working with edna
+ (require 'ede/proj-elisp)
+ (require 'ede/proj-aux)
+ (require 'ede/proj-misc)
+
+ These are the three target types that edna uses: elisp for
+compilation and autoloads; aux for auxiliary files such as
+documentation; and misc for tests.
+
+ When creating a new file, EDE will ask if you want to add it to a
+target. Consult with one of the edna devs for guidance, but usually
+selecting “none” and letting one of us handle it is a good way to go.
+
+
+File: org-edna.info, Node: Compiling Edna, Next: Testing Edna, Prev:
Working with EDE, Up: Contributing
+
+Compiling Edna
+==============
+
+To compile Edna, you’ve got to have EDE create the Makefile first. Run
+the following in your Emacs instance to generate the Makefile:
+
+ M-x ede-proj-regenerate
+
+ This will create the Makefile and point it to the correct version of
+Org. The targets are as follows:
+
+compile
+ Compiles the code. This should be done to verify that everything
+ will compile, as ELPA requires this.
+autoloads
+ Creates the autoloads file. This should also run without problems,
+ so it’s a good idea to check this one as well.
+check
+ Runs the tests in ‘org-edna-tests.el’.
+
+ To run any target, call ‘make’:
+
+ make compile autoloads
+
+ The above command compiles Edna and generates the autoloads file.
+
+
+File: org-edna.info, Node: Testing Edna, Next: Before Sending Changes,
Prev: Compiling Edna, Up: Contributing
+
+Testing Edna
+============
+
+There are two ways to test Edna: the command-line and through Emacs.
+
+ The command-line version is simple, and we ask that you do any final
+testing using this method. This is how we periodically check to verify
+that new versions of Org mode haven’t broken Edna. It uses the
+Makefile, which is generated with EDE. See *note Compiling Edna:: for
+how to do that. Once you have, run ‘make check’ on the command line.
+
+ Edna tests are written using ‘ERT’, the Emacs Regression Testing
+framework. In order to use it interactively in Emacs, the following
+must be done:
+
+ 1. Load ‘org-edna-tests.el’
+ 2. Run ‘M-x ert-run-tests-interactively’
+ 3. Select which tests to run, or just the letter “t” to run all of
+ them.
+
+ Results are printed in their own buffer. See the ERT documentation
+for more details.
+
+
+File: org-edna.info, Node: Before Sending Changes, Next: Developing with
Bazaar, Prev: Testing Edna, Up: Contributing
+
+Before Sending Changes
+======================
+
+There are a few rules to follow:
+
+ • Verify that any new Edna keywords follow the appropriate naming
+ conventions
+ • Any new keywords should be documented
+ • We operate on headings, not headlines
+ • Use one word in documentation to avoid confusion
+ • Make sure your changes compile
+ • 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
+
+
+File: org-edna.info, Node: Developing with Bazaar, Next: Documentation,
Prev: Before Sending Changes, Up: Contributing
-Development
-===========
+Developing with Bazaar
+======================
If you’re new to bazaar, we recommend using Emacs’s built-in VC package.
It eases the overhead of dealing with a brand new VCS with a few
@@ -1478,19 +1614,8 @@ Emacs, this is C-h r m Introduction to VC RET).
Then, use ‘org-edna-submit-bug-report’ and attach “file-name.txt”.
We can then merge that into the main development branch.
- There are a few rules to follow:
-
- • Verify that any new Edna keywords follow the appropriate naming
- conventions
- • Any new keywords should be documented
- • We operate on headings, not headlines
- • Use one word to avoid confusion
- • 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
-
-File: org-edna.info, Node: Documentation, Prev: Development, Up:
Contributing
+File: org-edna.info, Node: Documentation, Prev: Developing with Bazaar, Up:
Contributing
Documentation
=============
@@ -1511,6 +1636,7 @@ Changelog
* Menu:
+* 1.0beta7: 10beta7.
* 1.0beta6: 10beta6.
* 1.0beta5: 10beta5.
* 1.0beta4: 10beta4.
@@ -1518,7 +1644,21 @@ Changelog
* 1.0beta2: 10beta2.
-File: org-edna.info, Node: 10beta6, Next: 10beta5, Up: Changelog
+File: org-edna.info, Node: 10beta7, Next: 10beta6, Up: Changelog
+
+1.0beta7
+========
+
+Biggest change here is the cache.
+
+ • Added cache to the finders to improve performance
+
+ • Updated documentation to include EDE
+
+ • Added testing and compiling documentation
+
+
+File: org-edna.info, Node: 10beta6, Next: 10beta5, Prev: 10beta7, Up:
Changelog
1.0beta6
========
@@ -1610,72 +1750,78 @@ Big release here, with three new features.
Tag Table:
Node: Top225
-Node: Copying3693
-Node: Introduction4515
-Node: Installation and Setup5463
-Node: Basic Operation6256
-Node: Blockers8107
-Node: Triggers8393
-Node: Syntax8655
-Node: Basic Features9345
-Node: Finders9648
-Node: ancestors11413
-Node: children12007
-Node: descendants12417
-Node: file12939
-Node: first-child13688
-Node: ids13948
-Node: match14609
-Node: next-sibling15247
-Node: next-sibling-wrap15504
-Node: olp15818
-Node: org-file16230
-Node: parent16875
-Node: previous-sibling17073
-Node: previous-sibling-wrap17334
-Node: relatives17613
-Node: rest-of-siblings21234
-Node: rest-of-siblings-wrap21519
-Node: self21868
-Node: siblings22029
-Node: siblings-wrap22266
-Node: Actions22570
-Node: Scheduled/Deadline23312
-Node: TODO State26887
-Node: Archive27255
-Node: Chain Property27575
-Node: Clocking27858
-Node: Property28270
-Node: Priority30457
-Node: Tag31026
-Node: Effort31243
-Node: Advanced Features31632
-Node: Conditions32016
-Node: done32631
-Node: headings32795
-Node: todo-state33171
-Node: variable-set33427
-Node: has-property33856
-Node: re-search34125
-Node: Negating Conditions34485
-Node: Consideration34872
-Node: Conditional Forms36441
-Node: Setting the Properties39097
-Node: Extending Edna40181
-Node: Naming Conventions40671
-Node: Finders 141132
-Node: Actions 141494
-Node: Conditions 141953
-Node: Contributing42839
-Node: Bugs43390
-Node: Development43742
-Node: Documentation44895
-Node: Changelog45340
-Node: 10beta645548
-Node: 10beta545808
-Node: 10beta446195
-Node: 10beta346448
-Node: 10beta246887
+Node: Copying4093
+Node: Introduction4915
+Node: Installation and Setup5863
+Node: Basic Operation6587
+Node: Blockers8438
+Node: Triggers8724
+Node: Syntax8986
+Node: Basic Features9676
+Node: Finders9979
+Node: ancestors11744
+Node: children12338
+Node: descendants12748
+Node: file13270
+Node: first-child14019
+Node: ids14279
+Node: match14940
+Node: next-sibling15578
+Node: next-sibling-wrap15835
+Node: olp16149
+Node: org-file16561
+Node: parent17206
+Node: previous-sibling17404
+Node: previous-sibling-wrap17665
+Node: relatives17944
+Node: rest-of-siblings21565
+Node: rest-of-siblings-wrap21850
+Node: self22199
+Node: siblings22360
+Node: siblings-wrap22597
+Node: Actions22901
+Node: Scheduled/Deadline23643
+Node: TODO State27218
+Node: Archive27586
+Node: Chain Property27906
+Node: Clocking28189
+Node: Property28601
+Node: Priority30788
+Node: Tag31357
+Node: Effort31574
+Node: Advanced Features31963
+Node: Finder Cache32411
+Node: Conditions33450
+Node: done34086
+Node: headings34250
+Node: todo-state34626
+Node: variable-set34882
+Node: has-property35311
+Node: re-search35580
+Node: Negating Conditions35940
+Node: Consideration36327
+Node: Conditional Forms37896
+Node: Setting the Properties40552
+Node: Extending Edna41636
+Node: Naming Conventions42126
+Node: Finders 142587
+Node: Actions 142949
+Node: Conditions 143408
+Node: Contributing44294
+Node: Bugs45160
+Node: Working with EDE45517
+Node: Compiling Edna46601
+Node: Testing Edna47470
+Node: Before Sending Changes48451
+Node: Developing with Bazaar49138
+Node: Documentation49879
+Node: Changelog50335
+Node: 10beta750564
+Node: 10beta650842
+Node: 10beta551118
+Node: 10beta451505
+Node: 10beta351758
+Node: 10beta252197
End Tag Table
diff --git a/packages/org-edna/org-edna.org b/packages/org-edna/org-edna.org
index e3422de..6e6c35f 100644
--- a/packages/org-edna/org-edna.org
+++ b/packages/org-edna/org-edna.org
@@ -70,7 +70,6 @@ From Source:
#+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):
@@ -78,7 +77,7 @@ After that, add the following to your init file (typically
.emacs):
#+BEGIN_SRC emacs-lisp
;; Only necessary if installing from source
(add-to-list 'load-path "/full/path/to/org-edna/")
-(load "/path/to/org-edna/org-edna-autoloads.el")
+(require 'org-edna)
;; Always necessary
(org-edna-load)
@@ -874,6 +873,30 @@ Sets the effort of all targets according to VALUE:
:PROPERTIES:
:CUSTOM_ID: advanced
:END:
+** Finder Cache
+:PROPERTIES:
+:CUSTOM_ID: cache
+:DESCRIPTION: Making the finders work faster
+:END:
+
+Some finders, ~match~ in particular, can take a long time to run. Oftentimes,
+this can make it unappealing to use Edna at all, especially with long
+checklists.
+
+The finder cache is one solution to this. To enable it, set
+~org-edna-finder-use-cache~ to non-nil. This can be done through the
+customization interface, or manually with ~setq~.
+
+When enabled, the cache will store the results of every finder form for a
+configurable amount of time. This timeout is controlled by
+~org-edna-finder-cache-timeout~. The cache is also invalidated if any of the
+results are invalid, which can happen if their target files have been closed.
+
+For example, if there are several entries in a checklist that all use the form
+~match("daily")~ as part of their trigger, the results of that form will be
+cached. When the next item is marked as DONE, the results will be searched for
+in cache, not recomputed.
+
** Conditions
:PROPERTIES:
:CUSTOM_ID: conditions
@@ -1238,6 +1261,9 @@ git clone git://orgmode.org/org-mode.git
#+END_SRC
** Bugs
+:PROPERTIES:
+:CUSTOM_ID: bugs
+:END:
There are two ways to submit bug reports:
@@ -1247,7 +1273,110 @@ There are two ways to submit bug reports:
When submitting a bug report, be sure to include the Edna form that caused the
bug, with as much context as possible.
-** Development
+** Working with EDE
+:PROPERTIES:
+:CUSTOM_ID: ede
+:DESCRIPTION: And all its quirks
+:END:
+
+Our build system uses EDE. EDE can be a little finicky at times, but we feel
+the benefits, namely package dependency handling and Makefile generation,
+outweigh the costs.
+
+One of the issues that many will likely encounter is the error "Corrupt file on
+disk". This is most often due to EDE not loading all its subprojects as
needed.
+If you find yourself dealing with this error often, place the following in your
+.emacs file:
+
+#+begin_src emacs-lisp
+;; Target types needed for working with edna
+(require 'ede/proj-elisp)
+(require 'ede/proj-aux)
+(require 'ede/proj-misc)
+#+end_src
+
+These are the three target types that edna uses: elisp for compilation and
+autoloads; aux for auxiliary files such as documentation; and misc for tests.
+
+When creating a new file, EDE will ask if you want to add it to a target.
+Consult with one of the edna devs for guidance, but usually selecting "none"
+and letting one of us handle it is a good way to go.
+
+** Compiling Edna
+:PROPERTIES:
+:CUSTOM_ID: compiling
+:DESCRIPTION: How to compile Edna
+:END:
+To compile Edna, you've got to have EDE create the Makefile first. Run the
+following in your Emacs instance to generate the Makefile:
+
+#+begin_example
+M-x ede-proj-regenerate
+#+end_example
+
+This will create the Makefile and point it to the correct version of Org. The
+targets are as follows:
+
+- compile :: Compiles the code. This should be done to verify that everything
+ will compile, as ELPA requires this.
+- autoloads :: Creates the autoloads file. This should also run without
+ problems, so it's a good idea to check this one as well.
+- check :: Runs the tests in ~org-edna-tests.el~.
+
+To run any target, call ~make~:
+
+#+begin_src shell
+make compile autoloads
+#+end_src
+
+The above command compiles Edna and generates the autoloads file.
+
+** Testing Edna
+:PROPERTIES:
+:CUSTOM_ID: testing
+:DESCRIPTION: Ensuring Edna works the way we think she will
+:END:
+
+There are two ways to test Edna: the command-line and through Emacs.
+
+The command-line version is simple, and we ask that you do any final testing
+using this method. This is how we periodically check to verify that new
+versions of Org mode haven't broken Edna. It uses the Makefile, which is
+generated with EDE. See [[#compiling][Compiling Edna]] for how to do that.
Once you have, run
+~make check~ on the command line.
+
+Edna tests are written using ~ERT~, the Emacs Regression Testing framework. In
+order to use it interactively in Emacs, the following must be done:
+
+1. Load ~org-edna-tests.el~
+2. Run ~M-x ert-run-tests-interactively~
+3. Select which tests to run, or just the letter "t" to run all of them.
+
+Results are printed in their own buffer. See the ERT documentation for more
+details.
+
+** Before Sending Changes
+:PROPERTIES:
+:CUSTOM_ID: commit_checklist
+:DESCRIPTION: Follow these instructions before sending us anything
+:END:
+
+There are a few rules to follow:
+
+- Verify that any new Edna keywords follow the appropriate naming conventions
+- Any new keywords should be documented
+- We operate on headings, not headlines
+ - Use one word in documentation to avoid confusion
+- Make sure your changes compile
+- 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
+
+** Developing with Bazaar
+:PROPERTIES:
+:CUSTOM_ID: bzr_dev
+:DESCRIPTION: How to use this strange VCS
+:END:
If you're new to bazaar, we recommend using Emacs's built-in VC package. It
eases the overhead of dealing with a brand new VCS with a few standard
commands.
@@ -1265,16 +1394,6 @@ $ bzr send -o file-name.txt
Then, use ~org-edna-submit-bug-report~ and attach "file-name.txt". We can then
merge that into the main development branch.
-There are a few rules to follow:
-
-- Verify that any new Edna keywords follow the appropriate naming conventions
-- Any new keywords should be documented
-- We operate on headings, not headlines
- - Use one word to avoid confusion
-- 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
-
** Documentation
:PROPERTIES:
:CUSTOM_ID: docs
@@ -1291,6 +1410,15 @@ making any changes:
:PROPERTIES:
:DESCRIPTION: List of changes by version
:END:
+** 1.0beta7
+Biggest change here is the cache.
+
+- Added cache to the finders to improve performance
+
+- Updated documentation to include EDE
+
+- Added testing and compiling documentation
+
** 1.0beta6
Lots of parsing fixes.
- [elpa] master updated (4ce0ed8 -> 7294b59), Ian Dunn, 2018/11/11
- [elpa] master de3f6fa 2/7: Bumped version, Ian Dunn, 2018/11/11
- [elpa] master e7ec6a8 1/7: Implemented finder cache, Ian Dunn, 2018/11/11
- [elpa] master 9c48be8 3/7: Updated tests for new form expansion, Ian Dunn, 2018/11/11
- [elpa] master 26b0a6e 6/7: Added documentation about using a timeout for cache, Ian Dunn, 2018/11/11
- [elpa] master 71ee9f6 5/7: Added tests for cache, Ian Dunn, 2018/11/11
- [elpa] master e875a03 4/7: Improved contributing section in documentation, Ian Dunn, 2018/11/11
- [elpa] master 7294b59 7/7: Merge commit '26b0a6e6fb03fe4b895bb03972bbb0d80ce2e8e3',
Ian Dunn <=