branch: master
commit 342f3dd7207ca934002f982bb8a7f5c516e8a684
Author: Ian Dunn <du...@gnu.org>
Commit: Ian Dunn <du...@gnu.org>
Improved contributing section in documentation
* org-edna.org (Installation and Setup): Removed compilation instructions.
(Finder Cache): New section documenting cache setup.
(Working with EDE): New section about EDE.
(Compiling Edna): New section about compiling Edna.
(Testing Edna): New section on how to test Edna.
(Before Sending Changes): Moved out of "development"
(Developing with Bazaar): Moved out of "development"
(Development): Removed.
(Changelog): Updated.
---
org-edna.info | 322 ++++++++++++++++++++++++++++++++++++++++++----------------
org-edna.org | 152 ++++++++++++++++++++++++---
2 files changed, 373 insertions(+), 101 deletions(-)
diff --git a/org-edna.info b/org-edna.info
index 33b6708..fde1e6e 100644
--- a/org-edna.info
+++ b/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/org-edna.org b/org-edna.org
index 31240c9..6e6c35f 100644
--- a/org-edna.org
+++ b/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
@@ -1292,7 +1411,14 @@ making any changes:
: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.
