[elpa] master aa2c021 11/62: Added info documentation for future inclusion in ELPA

[Ian Dunn]

branch: master
commit aa2c0219969a4e5fefaee1b02b46dbea6397b7f1
Author: Ian Dunn <address@hidden>
Commit: Ian Dunn <address@hidden>

    Added info documentation for future inclusion in ELPA
    
    * paced.org: Added descriptions to most headers
---
 .bzrignore |   2 +
 dir        |  19 ++
 paced.info | 668 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 paced.org  |  49 ++++-
 4 files changed, 736 insertions(+), 2 deletions(-)

diff --git a/.bzrignore b/.bzrignore
index 0d820ff..fd9ec13 100644
--- a/.bzrignore
+++ b/.bzrignore
@@ -4,3 +4,5 @@ paced-autoloads.el
 Makefile
 .deps
 test-files/paced-dictionary-case-sensitive
+paced.html
+paced.texi
\ No newline at end of file
diff --git a/dir b/dir
new file mode 100644
index 0000000..53a15fe
--- /dev/null
+++ b/dir
@@ -0,0 +1,19 @@
+This is the file .../info/dir, which contains the
+topmost node of the Info hierarchy, called (dir)Top.
+The first time you invoke Info you start off looking at this node.
+
+File: dir,     Node: Top       This is the top of the INFO tree
+
+  This (the Directory node) gives a menu of major topics.
+  Typing "q" exits, "H" lists all Info commands, "d" returns here,
+  "h" gives a primer for first-timers,
+  "mEmacs<Return>" visits the Emacs manual, etc.
+
+  In Emacs, you can click mouse button 2 on a menu item or cross reference
+  to select it.
+
+* Menu:
+
+Emacs
+* paced.                        Predictive Abbreviation Completion and 
+                                  Expansion using Dictionaries.
diff --git a/paced.info b/paced.info
new file mode 100644
index 0000000..20f0231
--- /dev/null
+++ b/paced.info
@@ -0,0 +1,668 @@
+This is paced.info, produced by makeinfo version 6.5 from paced.texi.
+
+INFO-DIR-SECTION Emacs
+START-INFO-DIR-ENTRY
+* paced.                Predictive Abbreviation Completion and Expansion using 
Dictionaries.
+END-INFO-DIR-ENTRY
+
+
+File: paced.info,  Node: Top,  Next: Copying,  Up: (dir)
+
+Paced
+*****
+
+* Menu:
+
+* Copying::
+* Introduction::                 Brief Introduction to paced
+* Dictionaries::                 Paced’s bread and butter
+* Population Commands::          The good stuff
+* Example Setups::               Some examples
+* Contributing::                 I wanna help!
+
+— The Detailed Node Listing —
+
+Introduction
+
+* Terminology::                  To avoid confusion
+* Similar Packages::             Packages with similar goals
+* Installation::                 How to install paced
+
+Similar Packages
+
+* pabbrev::
+* predictive::
+
+
+Dictionaries
+
+* Creating a Dictionary::        First steps
+* Editing a Dictionary::         How to edit your new dictionary
+* Selective Dictionaries::       Enabling certain dictionaries under certain 
conditions
+* Dictionary Files::             Loading and Saving the Dictionaries
+
+Population Commands
+
+* Built-in Commands::            Basics
+* Properties::                   Tweaking the defaults
+* Custom Commands::              Defining new population commands
+* Asynchronous Population::      Populating without blocking
+
+Example Setups
+
+* Org Agenda Files::
+* Project Files::
+
+
+
+File: paced.info,  Node: Copying,  Next: Introduction,  Prev: Top,  Up: Top
+
+Copying
+*******
+
+Copyright (C) 2017 Ian Dunn
+
+     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/>.
+
+
+File: paced.info,  Node: Introduction,  Next: Dictionaries,  Prev: Copying,  
Up: Top
+
+Introduction
+************
+
+Paced (Predictive Abbreviation Completion and Expansion using
+Dictionaries) provides a completion backend based on what a user has
+already written.
+
+   Paced scans one or more files or buffers and constructs a table of
+words, weighted by how often they’re used.
+
+   Once it’s constructed this table, it can present them to the user for
+completion, sorted by their weights.
+
+   Creating a new dictionary is easy; just use
+‘paced-create-new-dictionary’ to create a new dictionary, then set the
+population commands and sort method.
+
+   Dictionaries are persistent; they’re saved with
+‘paced-save-named-dictionary’ or ‘paced-save-all-dictionaries’.
+
+   Population commands tell a dictionary how it should refresh its usage
+table.  The different types of populators are documented in
+‘paced--populator-alist’.
+
+   No completion frontend is provided, but a function for
+‘completion-at-point-functions’ is given.
+
+* Menu:
+
+* Terminology::                  To avoid confusion
+* Similar Packages::             Packages with similar goals
+* Installation::                 How to install paced
+
+
+File: paced.info,  Node: Terminology,  Next: Similar Packages,  Up: 
Introduction
+
+Terminology
+===========
+
+Dictionary
+     A collection of words and their usage counts.
+
+Population Command
+     A method of loading data into a dictionary.
+
+
+File: paced.info,  Node: Similar Packages,  Next: Installation,  Prev: 
Terminology,  Up: Introduction
+
+Similar Packages
+================
+
+There are a few Emacs packages that have similar goals to paced, and
+provided some of the inspiration and motivation behind it.
+
+* Menu:
+
+* pabbrev::
+* predictive::
+
+
+File: paced.info,  Node: pabbrev,  Next: predictive,  Up: Similar Packages
+
+pabbrev
+-------
+
+The pabbrev (http://github.com/phillord/pabbrev) package by Phillip Lord
+scans text of the current buffer while Emacs is idle and presents the
+user with the most common completions.
+
+   One of the major downsides to pabbrev is that the data it collects
+doesn’t persist between Emacs sessions.  For a few files that are always
+open, such as org agenda files, pabbrev works great.  For files that
+aren’t always open, like prose or source files, you’ve got to retrain
+pabbrev every time you restart Emacs.
+
+   The benefit of pabbrev dies down if the suggested word isn’t the one
+you need.  Then you’ve still got to search through a list of
+suggestions, which takes away from typing.
+
+   That’s not to say that pabbrev is all bad.  It keeps up-to-date usage
+and prefix hashes of all buffers of the same mode, and scanning, or
+“scavenging”, blends seamlessly into the background.  Completion is just
+a hash table lookup, so it can handle completion in microseconds.
+
+
+File: paced.info,  Node: predictive,  Prev: pabbrev,  Up: Similar Packages
+
+predictive
+----------
+
+The predictive (http://www.dr-qubit.org/git/predictive.git) package by
+Toby Cubitt scans text of the current buffer on user command.  The usage
+data is stored in a dictionary, which can then be saved to a disk.
+Extensions are provided to ‘completion-at-point’, or predictive’s
+built-in frontend can be used.  It has a safety precaution where it only
+adds existing words to a dictionary, unless the user allows this.  This
+is to avoid adding typos to a dictionary.
+
+   Completion was also done intelligently, grouping commonly used words
+together and optionally suggesting shorter words before longer words.
+
+   While the frontend and backend are separate, the frontend is required
+to populate a dictionary.  There is no way to exclude part of the
+buffer’s text from dictionary population.  The safety precaution
+predictive has where it only adds a word to a dictionary if it already
+exists was tedious, since I didn’t need it to do that.
+
+
+File: paced.info,  Node: Installation,  Prev: Similar Packages,  Up: 
Introduction
+
+Installation
+============
+
+*Requirements*
+
+Emacs   26.1
+async   1.9.2
+
+   Right now, the only way to install paced is from source.
+
+   From Source:
+
+     bzr branch https://bzr.savannah.gnu.org/r/paced-el paced
+
+   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/paced/")
+     (require 'paced)
+
+
+File: paced.info,  Node: Dictionaries,  Next: Population Commands,  Prev: 
Introduction,  Up: Top
+
+Dictionaries
+************
+
+* Menu:
+
+* Creating a Dictionary::        First steps
+* Editing a Dictionary::         How to edit your new dictionary
+* Selective Dictionaries::       Enabling certain dictionaries under certain 
conditions
+* Dictionary Files::             Loading and Saving the Dictionaries
+
+
+File: paced.info,  Node: Creating a Dictionary,  Next: Editing a Dictionary,  
Up: Dictionaries
+
+Creating a Dictionary
+=====================
+
+Now that you’ve got paced installed, it’s time to create a new
+dictionary.
+
+     M-x paced-create-new-dictionary RET DICTIONARY_NAME RET DICTIONARY_FILE 
RET
+
+   Let’s explain those two arguments:
+
+   First, you’ve got DICTIONARY_NAME. This is a string that will be used
+to reference the new dictionary.  We recommend something short, like
+’new-dict’, ’my-dict’, ’writing’, etc.
+
+   Next is the file where the dictionary will be stored.  This is
+typically stored in ‘paced-dictionary-directory’, from which all
+dictionaries will be loaded with ‘paced-load-all-dictionaries’ (more on
+that later).  For now, it’s important to know that
+‘paced-load-all-dictionaries’ is the easiest way to load dictionaries
+when paced is loaded.
+
+   After you’ve run the above command, you will be taken to the
+customization buffer.  This is where you can set population commands.
+
+
+File: paced.info,  Node: Editing a Dictionary,  Next: Selective Dictionaries,  
Prev: Creating a Dictionary,  Up: Dictionaries
+
+Editing a Dictionary
+====================
+
+In order to edit a dictionary, paced provides
+‘paced-edit-named-dictionary’ and ‘paced-edit-current-dictionary’.
+
+   The edit buffer provides the options to change the population
+commands, case sensitivity, dictionary storage name, and sort method.
+Each of these is documented in the edit buffer.
+
+
+File: paced.info,  Node: Selective Dictionaries,  Next: Dictionary Files,  
Prev: Editing a Dictionary,  Up: Dictionaries
+
+Selective Dictionaries
+======================
+
+Paced provides a mechanism called the “enable list”, that allows a user
+to enable certain dictionaries given certain conditions.
+
+   There are two enable lists: a global and local one.  They both work
+the same, with the local one taking precedence.  Each entry in the list
+has a condition and a key.
+
+   The conditions are one of the following:
+
+   • A mode name, such as ‘org-mode’ or ‘text-mode’, indicating that the
+     named dictionary should be active in any mode derived from that
+     mode.
+
+   • A symbol, in which case the named dictionary is active whenever the
+     value of that symbol is non-nil.
+
+   • A function symbol, in which case the function is called with no
+     arguments to determine if the given dictionary should be enabled.
+     If the function returns non-nil the dictionary is enabled.
+
+   • A lambda function, in which case it is called with no arguments,
+     and if it returns non-nil, the dictionary is enabled.
+
+   • The form (or CONDITION1 CONDITION2 ...), which enables the given
+     dictionary if any of the conditions are met.
+
+   • The form (and CONDITION1 CONDITION2 ...), which enables the given
+     dictionary if all of the conditions are met.
+
+   Remember that paced-mode must be active for completion to occur.
+Neither list will activate it, just determine which dictionary is
+active.
+
+   The key is the dictionary name you set during dictionary creation.
+
+
+File: paced.info,  Node: Dictionary Files,  Prev: Selective Dictionaries,  Up: 
Dictionaries
+
+Dictionary Files
+================
+
+Paced provides ‘paced-load-all-dictionaries’ to load all dictionaries in
+‘paced-dictionary-directory’.  Paced determines which dictionaries to
+load based on two variables:
+‘paced-dictionary-directory-whitelist-regexp’ and
+‘paced-dictionary-directory-blacklist-regexp’.  Paced can also be told
+to search recursively by setting
+‘paced-load-all-dictionaries-recursively’ to t.  All four of these
+variables may be set using Emacs’s customization interface.
+
+   An individual dictionary file may also be loaded:
+
+     M-x paced-load-dictionary-from-file RET /path/to/file RET
+
+   Once a file has been modified, it may then be saved:
+
+     M-x paced-save-named-dictionary RET dictionary name RET
+
+   Or, all dictionaries may be saved:
+
+     M-x paced-save-all-dictionaries RET
+
+   Dictionaries may also be automatically saved whenever changed by
+setting ‘paced-repopulate-saves-dictionary’ to t.  Population is covered
+in the next section.
+
+
+File: paced.info,  Node: Population Commands,  Next: Example Setups,  Prev: 
Dictionaries,  Up: Top
+
+Population Commands
+*******************
+
+Part of the beauty of paced is the ease of reconstructing a dictionary.
+When you’ve got a bunch of files from which you want to populate your
+dictionary, it’d be a pain to go to each of them and say “populate from
+this one, next, populate from this one, next”.
+
+   Instead, paced provides population commands.  Each dictionary has one
+or more population commands it uses to recreate its contents, run in
+order during population.
+
+   In order to trigger population, run the following:
+
+     M-x paced-repopulate-named-dictionary RET DICTIONARY-NAME RET
+
+* Menu:
+
+* Built-in Commands::            Basics
+* Properties::                   Tweaking the defaults
+* Custom Commands::              Defining new population commands
+* Asynchronous Population::      Populating without blocking
+
+
+File: paced.info,  Node: Built-in Commands,  Next: Properties,  Up: Population 
Commands
+
+Built-in Commands
+=================
+
+There are five built-in population commands:
+
+file
+     Populates a dictionary from all words in a given file
+buffer
+     Populates a dictionary from all words in a given buffer, which must
+     exist during population
+file-function
+     Like the file command, but allows a custom setup function.  This
+     function is called with no arguments in a temporary buffer
+     containing the file’s contents, and must return non-nil if
+     population may continue.
+directory-regexp
+     Populates from all files in a directory that match the given
+     regexp.  Also optionally allows recursion.
+file-list
+     Populates from all files returned by a generator function.
+
+
+File: paced.info,  Node: Properties,  Next: Custom Commands,  Prev: Built-in 
Commands,  Up: Population Commands
+
+Properties
+==========
+
+When setting the population commands of a dictionary, one may also set
+certain properties.  Each property is a variable binding, bound while
+the population command runs.
+
+   Two variables are of note here:
+
+paced-exclude-function
+     Function of no arguments that returns non-nil if the thing at point
+     should be excluded from population.
+paced-thing-at-point-constituent
+     Symbol defining thing on which population works.  Typically set to
+     either ’symbol or ’word.
+
+
+File: paced.info,  Node: Custom Commands,  Next: Asynchronous Population,  
Prev: Properties,  Up: Population Commands
+
+Custom Commands
+===============
+
+Since the population commands all derive from paced-population-command,
+it’s possible to add additional commands.
+
+   As an example, let’s make a population command that populates a
+dictionary from a file like so:
+
+     alpha 5
+     beta 7
+     gamma 21
+     delta 54
+     epsilon 2
+
+   We want to make a population command that takes a file like this,
+with word in one column and weight in the other, and add it to a
+dictionary.
+
+   There are two ways to approach this, but we’re going to start with
+the basic one.
+
+   We need to define two functions: paced-population-command-source-list
+and paced-population-command-setup-buffer.  The first returns a list of
+sources from which to populate, and the second sets up a temporary
+buffer based on those sources.
+
+   For our command, we want to return the specified file, and replicate
+each word by the amount given.
+
+   Inheriting from ‘paced-file-population-command’ gives us the source
+list and file slot for free.
+
+     (defclass paced-weight-file-population-command 
(paced-file-population-command))
+
+   Now, we need to set up the buffer to replicate the words.
+
+     (cl-defmethod paced-population-command-setup-buffer ((cmd 
paced-weight-file-population-command) source)
+       ;; Use the built-in `paced--insert-file-contents' to insert contents.
+       (paced--insert-file-contents source)
+       ;; Jump to the start of the buffer
+       (goto-char (point-min))
+       ;; Search for lines with the form WORD WEIGHT
+       (while (re-search-forward (rx line-start ;; Start of line
+                                     (submatch (one-or-more (not (syntax 
whitespace)))) ;; Our word
+                                     (syntax whitespace) ;; Space between word 
and weight
+                                     (submatch (one-or-more (any digit))) ;; 
Weight
+                                     line-end) ;; End of line
+                                 nil t)
+         (let* ((word (match-string 1))
+                (weight (string-to-number (match-string 2)))
+                ;; Repeat WORD WEIGHT times
+                (new-text (string-join (make-list weight word) " ")))
+           ;; Replace the matched text with our repeated word
+           (replace-match new-text))))
+
+   That’s all there is to it.  When you go to edit a dictionary, the
+“weight-file” population command will automatically be added as an
+option for a population command.
+
+   The even easier way to do this would’ve been to use
+‘paced-file-function-population-command’, but it doesn’t make for a good
+example in this case.
+
+
+File: paced.info,  Node: Asynchronous Population,  Prev: Custom Commands,  Up: 
Population Commands
+
+Asynchronous Population
+=======================
+
+A common problem is that population can take a long time.  Some of us
+populate dictionaries from org agenda files, which can get pretty big.
+
+   To solve this, paced uses the async
+(https://github.com/jwiegley/emacs-async) package.  Setup should be
+seamless; just stick whatever code you need in
+‘~/.emacs.d/paced-async.el’, type M-x
+paced-repopulate-named-dictionary-async, and push enter.
+
+   A few things to note about this:
+
+  1. Dictionaries will be automatically saved by this method after
+     population
+  2. Asynchronous population doesn’t change anything until after
+     population is finished, so a user may continue to use their
+     dictionary while population is happening.
+  3. Because async runs population in a separate Emacs process, any
+     custom code required for population must be in paced-async.el.
+     This includes additional population command types, but doesn’t
+     include the following variables:
+
+        • load-path
+        • paced-thing-at-point-constituent
+        • paced-async-load-file
+
+
+File: paced.info,  Node: Example Setups,  Next: Contributing,  Prev: 
Population Commands,  Up: Top
+
+Example Setups
+**************
+
+* Menu:
+
+* Org Agenda Files::
+* Project Files::
+
+
+File: paced.info,  Node: Org Agenda Files,  Next: Project Files,  Up: Example 
Setups
+
+Org Agenda Files
+================
+
+As some of us record everything about our lives in our agenda files, it
+might be helpful to have a dictionary tuned to ourselves.
+
+   We use a file-list command that returns the agenda files, and an
+exclude command to block out all of Org’s extra features such as source
+code and drawers.
+
+   The generator for file-list is easy:
+
+     (lambda nil org-agenda-files)
+
+   Done.
+
+   Now, the exclude command, which sits inside the properties option:
+
+     (defun org-paced-exclude ()
+       (or
+        ;; Drawers
+        (org-between-regexps-p org-drawer-regexp ":END:") ;; Doesn't catch END
+        (org-in-regexp ":END:") ;; but this does
+
+        (org-at-comment-p) ;; comments
+        (org-in-regexp org-any-link-re) ;; links
+        (org-in-block-p '("src" "quote" "verse")) ;; blocks
+        (org-at-planning-p) ;; deadline, etc.
+        (org-at-table-p) ;; tables
+        ))
+
+   As explained earlier, this can be put inside properties in the
+customize buffer as such:
+
+     Properties :
+     [INS] [DEL] Variable: paced-exclude-function
+     Lisp expression: 'org-paced-exclude
+
+   And you’re done.  See how easy that was?
+
+
+File: paced.info,  Node: Project Files,  Prev: Org Agenda Files,  Up: Example 
Setups
+
+Project Files
+=============
+
+Now we get to the interesting one.  There are tons of ways to collect
+project files in Emacs, so we’re going to stick with one for now, being
+Emacs’s built-in VC package.
+
+     (defun vc-paced-find-project-files (path-to-project-root)
+       "Use VC to collect all version-controlled files."
+       (let ((file-list))
+         (vc-file-tree-walk path-to-project-root (lambda (f) (push f 
file-list)))
+         file-list))
+
+   We’d then need to use the following for our file-list generator:
+
+     Generator : (lambda nil (vc-paced-find-project-files 
"/home/me/programming/paced"))
+
+   Now, we (probably) don’t want commented code to get in our way, so
+we’ll use a small function for excluding those:
+
+     (defun paced-at-comment-p ()
+       (nth 8 (syntax-ppss)))
+
+   Use that for paced-exclude-function, and you’re done.  We can’t
+necessarily recommend this for any programming language, as there are
+dedicated solutions for almost everything, but it makes an excellent
+fallback.
+
+
+File: paced.info,  Node: Contributing,  Prev: Example Setups,  Up: Top
+
+Contributing
+************
+
+We are all happy for any help you may provide.
+
+   First, check out the source code on Savannah:
+<https://savannah.nongnu.org/projects/paced-el>
+
+     bzr branch https://bzr.savannah.gnu.org/r/paced-el/ paced
+
+   Build the Makefile with EDE:
+
+  1. Open any file from paced
+  2. Run ‘C-c . C’ or ‘M-x ede-compile-project’
+
+   *Bugs*
+
+   There are two ways to submit bug reports:
+
+  1. Using the bug tracker at Savannah
+  2. Sending an email using ‘paced-submit-bug-report’
+
+   *Development*
+
+   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.  For more information, see the info page on it
+(In Emacs, this is C-h r m Introduction to VC RET).
+
+   To contribute with bazaar, you can do the following:
+
+     # Hack away and make your changes
+     $ bzr commit -m "Changes I've made"
+     $ bzr send -o file-name.txt
+
+   Then, use ‘paced-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:
+
+   • New population commands should be named
+     paced-POPULATION-COMMAND-TYPE-population-command
+   • Run ’make check’ to verify that your mods don’t break anything
+   • Avoid additional or altered dependencies if at all possible
+
+
+
+Tag Table:
+Node: Top228
+Node: Copying1433
+Node: Introduction2225
+Node: Terminology3450
+Node: Similar Packages3691
+Node: pabbrev3997
+Node: predictive5070
+Node: Installation6120
+Node: Dictionaries6614
+Node: Creating a Dictionary7018
+Node: Editing a Dictionary8058
+Node: Selective Dictionaries8536
+Node: Dictionary Files10135
+Node: Population Commands11226
+Node: Built-in Commands12162
+Node: Properties12959
+Node: Custom Commands13581
+Node: Asynchronous Population16308
+Node: Example Setups17501
+Node: Org Agenda Files17683
+Node: Project Files18939
+Node: Contributing20052
+
+End Tag Table
+
+
+Local Variables:
+coding: utf-8
+End:
diff --git a/paced.org b/paced.org
index 7a6d31c..e03e0b0 100644
--- a/paced.org
+++ b/paced.org
@@ -31,6 +31,9 @@ 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:
+:DESCRIPTION: Brief Introduction to paced
+:END:
 Paced (Predictive Abbreviation Completion and Expansion using Dictionaries)
 provides a completion backend based on what a user has already written.
 
@@ -53,12 +56,18 @@ No completion frontend is provided, but a function for
 ~completion-at-point-functions~ is given.
 
 ** Terminology
+:PROPERTIES:
+:DESCRIPTION: To avoid confusion
+:END:
 
 - Dictionary :: A collection of words and their usage counts.
 
 - Population Command :: A method of loading data into a dictionary.
 
 ** Similar Packages
+:PROPERTIES:
+:DESCRIPTION: Packages with similar goals
+:END:
 There are a few Emacs packages that have similar goals to paced, and provided
 some of the inspiration and motivation behind it.
 *** pabbrev
@@ -96,6 +105,9 @@ from dictionary population.  The safety precaution 
predictive has where it only
 adds a word to a dictionary if it already exists was tedious, since I didn't
 need it to do that.
 ** Installation
+:PROPERTIES:
+:DESCRIPTION: How to install paced
+:END:
 
 *Requirements*
 
@@ -118,7 +130,13 @@ After that, add the following to your init file (typically 
.emacs):
 (require 'paced)
 #+END_SRC
 * Dictionaries
+:PROPERTIES:
+:DESCRIPTION: Paced's bread and butter
+:END:
 ** Creating a Dictionary
+:PROPERTIES:
+:DESCRIPTION: First steps
+:END:
 
 Now that you've got paced installed, it's time to create a new dictionary.
 
@@ -141,13 +159,19 @@ when paced is loaded.
 After you've run the above command, you will be taken to the customization
 buffer.  This is where you can set population commands.
 ** Editing a Dictionary
+:PROPERTIES:
+:DESCRIPTION: How to edit your new dictionary
+:END:
 In order to edit a dictionary, paced provides ~paced-edit-named-dictionary~ and
 ~paced-edit-current-dictionary~.
 
 The edit buffer provides the options to change the population commands, case
 sensitivity, dictionary storage name, and sort method.  Each of these is
 documented in the edit buffer.
-** Enable Certain Dictionaries in Certain Places
+** Selective Dictionaries
+:PROPERTIES:
+:DESCRIPTION: Enabling certain dictionaries under certain conditions
+:END:
 
 Paced provides a mechanism called the "enable list", that allows a user to
 enable certain dictionaries given certain conditions.
@@ -181,7 +205,10 @@ Remember that paced-mode must be active for completion to 
occur.  Neither list
 will activate it, just determine which dictionary is active.
 
 The key is the dictionary name you set during dictionary creation.
-** Loading and Saving the Dictionaries
+** Dictionary Files
+:PROPERTIES:
+:DESCRIPTION: Loading and Saving the Dictionaries
+:END:
 
 Paced provides ~paced-load-all-dictionaries~ to load all dictionaries in
 ~paced-dictionary-directory~.  Paced determines which dictionaries to load 
based
@@ -213,6 +240,9 @@ Dictionaries may also be automatically saved whenever 
changed by setting
 section.
 
 * Population Commands
+:PROPERTIES:
+:DESCRIPTION: The good stuff
+:END:
 
 Part of the beauty of paced is the ease of reconstructing a dictionary.  When
 you've got a bunch of files from which you want to populate your dictionary,
@@ -230,6 +260,9 @@ M-x paced-repopulate-named-dictionary RET DICTIONARY-NAME 
RET
 #+end_example
 
 ** Built-in Commands
+:PROPERTIES:
+:DESCRIPTION: Basics
+:END:
 
 There are five built-in population commands:
 
@@ -245,6 +278,9 @@ There are five built-in population commands:
 - file-list :: Populates from all files returned by a generator function.
 
 ** Properties
+:PROPERTIES:
+:DESCRIPTION: Tweaking the defaults
+:END:
 
 When setting the population commands of a dictionary, one may also set certain
 properties.  Each property is a variable binding, bound while the population
@@ -258,6 +294,9 @@ Two variables are of note here:
      works.  Typically set to either 'symbol or 'word.
 
 ** Custom Commands
+:PROPERTIES:
+:DESCRIPTION: Defining new population commands
+:END:
 Since the population commands all derive from paced-population-command, it's
 possible to add additional commands.
 
@@ -324,6 +363,9 @@ The even easier way to do this would've been to use
 in this case.
 
 ** Asynchronous Population
+:PROPERTIES:
+:DESCRIPTION: Populating without blocking
+:END:
 A common problem is that population can take a long time.  Some of us populate
 dictionaries from org agenda files, which can get pretty big.
 
@@ -346,6 +388,9 @@ A few things to note about this:
    - paced-async-load-file
 
 * Example Setups
+:PROPERTIES:
+:DESCRIPTION: Some examples
+:END:
 ** Org Agenda Files
 As some of us record everything about our lives in our agenda files, it might 
be
 helpful to have a dictionary tuned to ourselves.