branch: master
commit aa2c0219969a4e5fefaee1b02b46dbea6397b7f1
Author: Ian Dunn <du...@gnu.org>
Commit: Ian Dunn <du...@gnu.org>
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.
