Emacs Predictive Completion Manual
**********************************

This manual documents the Emacs Predictive Completion package, version 0.20

Copyright © 2005--2008 Toby Cubitt

     Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License".

The package adds a new predictive completion minor-mode, called predictive mode, to the GNU Emacs editor. Although there are many options and customizations, the easiest way to start using it is to simply install the package (see Obtaining and Installing), turn on the minor-mode by running the predictive-mode command, and start typing. Then come back and read up on how to tailor it to your liking.

What is predictive completion?
******************************

The languages we use to communicate contain a large amount of redundancy. Given the first few letters of a word, for instance, it's not too difficult to predict what should come next. Try it! You can probably easily guess how to fill in the missing letters in the following sentence:

     Giv th fir fe lett o a wor i no diffi t predi wh shou com nex.

This is even more true of the languages used to communicate with computers, which typically have very restricted vocabularies and rigidly defined grammars. Redundancy occurs on many levels: on the level of individual characters (as illustrated above), on the level of words (we can often predict quite accurately what words are likely to come next in a sentence, based on grammar and usage), and perhaps even on higher levels. Predictive completion exploits this redundancy by attempting to complete what you are trying to type before you've finished typing it.

The predictive completion package described here is an add-on to the GNU Emacs editor, which implements a new minor-mode called predictive-mode (see Minor Modes (GNU emacs manual)). When this predictive completion minor-mode is switched on, Emacs will try to complete the word you are typing based on the characters typed so far. As you add characters, it can look up words starting with those characters in a dictionary, and offer to insert the most likely ones. How you choose which completion (if any) to insert depends on various customization settings, some more intrusive than others.

Note that by only taking into account characters belonging to the current word when predicting how to complete it, much of the redundancy in language remains unexploited. This limitation is partly for simplicity, but also because some of the benefits of predictive completion would be lost if context (i.e. the preceding words and sentences) was also taken into account.

What benefits does predictive completion bring?

 1. Saving on typing (obviously!): you don't have to type the whole word.

 2. Automatic spelling assistance: when you type the first few characters of a word, only correct spellings of the whole word are offered. This is not only useful for human languages. The predictive completion mode can be set up to complete on variable and function names in a program, helping avoid bugs due to misspelled names.

 3. Faster typing: not quite the same as point 1. As you get used to predictive completion, your fingers will start to learn the key sequences required for frequently used words. And these key sequences will usually be much shorter than typing the full word. (This is one reason for not taking context into account. If we did, the same word might require different key sequences depending on the words and sentences preceding it.)

Obtaining and Installing
************************

The current version of the predictive completion package can be obtained from http://www.dr-qubit.org/emacs.php.

If you are upgrading from a previous version of the predictive completion package, make sure you first backup dictionaries you use by dumping the words and data they contain to files (unless you want to start from scratch). To make the backups, use predictive-dump-dict-to-file. See Loading and Saving Dictionaries. It is not enough to make a copy of the dictionary file. Only the plain-text "dumped" format is guaranteed to be portable across different versions of predictive mode.

Older versions of the predictive completion package saved dictionaries in a compiled form that was not portable across different versions of Emacs. Newer versions now automatically save dictionaries in both compiled and uncompiled forms. If you are upgrading to a different version of Emacs, but continuing to use the same recent version of the predictive completion package, then it is sufficient to delete the compiled dictionary files (extension .elc, but make sure you do not delete the uncompiled files with extension .el!), and let predictive mode recompile them automatically when the dictionaries are saved.

However, backing up your dictionaries by dumping them to plain-text files, as described above, is still a very good idea (just to be on the safe side!).

To install the package, extract the files using tar -xvzf predictive.tar.gz. This will unpack the files in a new directory called predictive/. Now byte-compile all the Lisp files and create the required dictionaries by running make in the predictive/ directory. If necessary, you can specify explicitly where your Emacs resides with make EMACS=/path/to/emacs.

Then run make install to copy the package files to ~/.emacs.d/predictive/ (the ~/.emacs.d/ directory will be created if it doesn't already exist). If you want to install the files elsewhere, you can change the default install location using make install DESTDIR=/PATH/TO/INSTALL/ and the package files will be copied to the /path/to/install/ directory.

The dictionaries are intended to be user-specific, and must be writable by your user. If you're performing a site-wide installation of the predictive package, the dictionary files (all files starting with the prefix dict- and ending in .elc or .el) need to be copied to a separate writable directory for each user. For this reason, the dictionaries will still be installed under ~/.emacs.d/predictive/ even if DESTDIR is specified (you will have to copy them manually for any other users who want to use predictive). If you want to change the dictionary install location, use make install DICTDIR=/path/to/dictionaries/. This can of course be combined with the DESTDIR option: make install DESTDIR=/path/to/install/ DICTDIR=/path/to/dictionaries/.

Finally, put the following lines in your .emacs file (replace the paths as appropriate if you're not using the default install locations):

     ;; predictive install location
     (add-to-list 'load-path "~/.emacs.d/predictive/")
     ;; dictionary locations
     (add-to-list 'load-path "~/.emacs.d/predictive/latex/")
     (add-to-list 'load-path "~/.emacs.d/predictive/html/")
     ;; load predictive package
     (require 'predictive)

Alternatively, you can save memory and only load the lisp libraries when they're needed (i.e. when you first run the predictive-mode command), by replacing the final line as follows:

     ;; predictive install location
     (add-to-list 'load-path "~/.emacs.d/predictive/")
     ;; dictionary locations
     (add-to-list 'load-path "~/.emacs.d/predictive/latex/")
     (add-to-list 'load-path "~/.emacs.d/predictive/html/")
     ;; load predictive package
     (autoload 'predictive-mode "~/.emacs.d/predictive/predictive"
               "Turn on Predictive Completion Mode." t)

If you want to install the info documentation into your local info system, you should run the following command as root: make info-install. If your info dir file is not located in /usr/share/info/, then you can specify its location using make info-install INFODIR=/path/to/info/.

For more details, and for alternative installation options, you should consult the INSTALL file included in the predictive package.

Quick-Start
***********

Use the predictive-mode command to switch the predictive minor-mode on. The same command will also switch it off again. This section only covers (some of) the default behaviour of predictive-mode. The way that predictive-mode works can be radically changed via numerous customization options, which are described in detail in the rest of this user-guide.

As you add characters to a word, predictive mode searches in a dictionary for words starting with those characters. There are a number of different ways to choose which word (if any) should be used to complete what you've typed.

The most likely completion is provisionally inserted in the buffer after the point, and highlighted to indicate that it has not yet been accepted. The most likely completion is updated as you add more characters to the word. Use C-RET to accept a completion. See Dynamic Completion, for details.

What if you don't want to use the most likely completion? As you type, a list of the ten most likely completions is displayed in the echo area and, after a short delay, in a tooltip. They are ranked according to likelihood. Typing a number 0--9 will insert the corresponding completion. See Completion Hotkeys, Displaying Completions in the Echo Area, and Completion Tooltip for details.

You can also display the completion tooltip manually, using S-down. When the tooltip is displayed, the up and down keys can be used to select a completion from the list in tooltip.

You can cycle forwards and backwards through the available completions even when the tooltip isn't displayed, using M-TAB or M-/ and M-SHIFT-TAB or M-?. As you cycle, the next completion is provisionally inserted after the point and highlighted. C-RET accepts the completion, as usual.

Hitting TAB whilst completing will perform traditional ``tab-completion'' on the word: the word will be completed up to the longest common prefix of the available completions.

Another useful command is C-TAB. This accepts all the characters from the current provisional completion as though you typed them yourself, and re-completes the resulting, longer string --- useful if a word just needs a suffix adding, for instance.

See Basic Completion Commands, for details of cycling and tab-completion.

M-Down will display a menu from which you can select a completion (see Completion Menu and Browser). There is also a Browser menu item, which brings up the completion browser. This hierarchically lists all possible completions, not just the most likely ones. (It can sometimes take a while to construct the completion browser, but you can always hit C-g to cancel it). See Completion Menu and Browser, for details.

C-Down displays a pop-up frame, in which you can use the usual Emacs motion keys to select a completion. M-Tab or M-/ in the pop-up frame toggles between displaying the most likely completions and displaying all possible completions. To get rid of the pop-up frame, use C-Up.

This ``Quick-Start'' describes the default behaviour. However, predictive completion mode can be heavily customized, allowing its behaviour to be radically changed. The many and various predictive completion mode customization options can be found in the predictive and completion-ui customization groups. If you like the idea of predictive completion, but don't like the way it works ``out-of-the-box'' the rest of this guide explains all the options and features in detail.

The predictive completion package comes with an English dictionary, which is used by default. However, this is only really included to make sure everything works ``out of the box''. This default dictionary has already been trained on a large body of English text, which means it will take a very long time to adapt to your individual writing style. Don't expect predictive completion mode to display particularly good predictive powers if you stick to the default dictionary! For much better results, you should create your own dictionary (possible based on the supplied one), and train it on your own writing. See Dictionaries.

Completing Words
****************

The minor-mode command predictive-mode toggles the mode on and off. With a positive prefix argument it switches the mode on, whilst a negative prefix argument turns it off and a zero prefix argument toggles. The turn-on-predictive-mode is also provided as a convenience for use in hooks.

Overview
========

Predictive mode is extremely flexible, and how you interact with it depends heavily on how you customize it. Broadly, there are two ways to use predictive mode: it can either do nothing until you ask it to complete a word, or it can automatically search for the most likely completions as you type. (You may have seen something similar to the latter on certain models of mobile phone, though predictive mode is far more powerful.)  This behaviour is controlled by enabling or disabling auto-completion-mode (see Auto-Completion Mode). It is enabled for you automatically if the predictive-auto-complete customization option is enabled (the default).

If you are using auto-completion-mode, you can (by default) continue to type normally. The completion candidates will be displayed, but will not be accepted unless you do so explicitly using completion-accept, bound to C-RET. However, since it learns as you type, predictive mode can become very good at predicting the word you want, and it can become tedious to have to hit C-RET all the time. In that case, you can customize auto-completion-syntax-alist so that typing a punctuation or white-space character automatically accepts the current completion, before inserting the character. This lets you skip typing the rest of the characters in a word as soon as predictive mode has found the completion you want. However, the down side is that you have to slightly change the way you type, and it can take a little while until your fingers ``get used to it''. If you need to reject a completion candidate when auto-completion-mode is enabled, you can do so using C-SPC.

If aren't using auto-completion-mode, you will need to call the complete-word-at-point command whenever you want to complete the word at or next to the point. This is bound to M-TAB, M-SHIFT-TAB, M-/ and M-?. There are then two ``styles'' of behaviour: completions can either be ephemeral, acting purely as a visual indicator, and disappearing unless you explicitly accept them using completion-accept, bound to C-RET. (You may be used to this style of behaviour from word processing software such as OpenOffice Writer). Or alternatively, completions can be permanent, so that completing a word really does insert those characters into the buffer unless you explicitly reject it using completion-reject, bound to C-DEL. (This the more traditional Emacs-style behaviour, that you may be used to from using dabbrevs, for example.) The choice is yours, and is controlled by the completion-resolve-behaviour customization option (see Miscellaneous Options). (Note that these two different ``styles'' of behaviour are mainly relevant when Dynamic Completion is enabled, as it is by default. This is described below.)

Whether you are using auto-completion-mode or not, there are various ways to display and select completions. All of them can be enabled or disabled indepentently, and many of them can be extensively customized.

Perhaps the simplest is to display the most likely completion in the buffer (see Dynamic Completion). You can then cycle through the other completion candidates using the completion-cycle command. M-TAB and M-/ cycle forwards, whereas M-SHIFT-TAB and M-? cycle backwards. (These are the same key bindings used to manually complete the word at point. Hitting them for the first time will bring up the possible completions, hitting them again will cycle.)

You can also insert a completion candidate directly, without having to cycle through them until you get to the one you want, by using a completion hot-key (see Completion Hotkeys). By default, the hot-keys are the number keys 0--9, which insert the first through to the tenth candidate, respectively.

Of course, you won't know which completion candidate you want unless you can see which candidates are available! The candidates can be displayed in the echo area, and/or in a tooltip below the point (see Displaying Completions in the Echo Area, and see Completion Tooltip). When completion hot-keys are enabled, both of these also indicate which completion candidate corresponds to which hot-key.

The completion tooltip is more than just a visual reminder of which completions are available. When it is displayed, you can select a completion from the list using the up and down arrow keys. When completing a word, you can display the tooltip at any time using completion-show-tooltip, bound to S-down. See Completion Tooltip.

A slightly more powerful alternative to the completion tooltip is a pop-up frame, displayed using completion-popup-frame, bound to C-down (see Pop-Up Frame. This lists the completion candidates in a separate Emacs frame positioned below the point, and you can use the usual Emacs motion keys to move through the list and select a candidate. However, you can also toggle between displaying just the most likely completion candidates and displaying all possible completions, using completion-popup-frame-toggle-all, bound to M-Tab and M-/. To get rid of a pop-up frame, use completion-popup-frame-cancel, bound to C-up and M-up. Note that all of these key bindings are only active when the pop-up frame has the focus. If you manually switch the focus back to the original frame, the pop-up frame will disappear as soon as you type anything.

The completion menu is the most flexible way of selecting completions, and can be displayed using completion-show-menu, bound to M-down. Again, it displays the completion candidates and lets you select them, and like the pop-up frame, it also allows you to see all possible completions, rather than just displaying the most likely ones, by bringing up the completion browser. But selecting the Browser menu item doesn't just display all possible completions in a big list. Instead, it organises them hierarchically, making it easy to browse through them until you find the one you want.

The completion tooltip, pop-up frame, and menu all display a list of completion candidates, but each has its own advantages and disadvantages. The tooltip is visually and functionally least intrusive, but also gives you fewer ways to find the completion you want. The pop-up frame is encumbered by your window manager's frame decoration (though some window managers allow you to disable this for specific windows, which are called frames in Emacs). But it can display large numbers of completion candidates far more effectively than a tooltip. The completion menu and completion browser make finding the desired completion much easier, especially when you're not sure precisely what it is you're looking for. But menus steal the keyboard focus in Emacs, so you can no longer type in the buffer until you dismiss the menu.

You can select one of these three, tooltip, pop-up frame or menu, to be displayed automatically when you complete a word, by setting the completion-auto-show customization option. You can optionally leave a short delay before it is displayed, by setting completion-auto-show-delay (Although you can choose to display the completion menu automatically, because it steals the keyboard focus this probably isn't all that useful, at least not without a long delay.).

Basic Completion Commands
=========================

Inserting Completions
---------------------

complete-word-at-point
     (M-TAB, M-SHIFT-TAB, M-/, M-?) Find completions for the word at or next to the point.

completion-cycle
     (M-TAB, M-SHIFT-TAB, M-/, M-?) Cycle through available completion candidates. When supplied with a prefix argument, it will jump that many completions forwards (or backwards if the prefix argument is negative). M-/ and M-? cycle backwards (so a negative argument will cause them to jump forwards that number of completions).

completion-accept
     (C-RET) Accept the current completion, and move the point just beyond it. If predictive-auto-learn and/or predictive-auto-add are enabled, predictive mode will also learn the word (see Dictionary Learning).

completion-reject
     (C-Backspace, C-SPC) Abandon the current completion, removing the provisionally inserted (i.e. highlighted) characters. If a prefix argument is supplied, predictive mode will also learn the resulting word, i.e. the prefix with the provisional completion removed (see Dictionary Learning). The C-SPC binding is only active in auto-completion-mode (see Auto-Completion Mode).

completion-tab-complete
     (TAB) Do ``traditional'' tab-completion, i.e. insert the longest common prefix of all candidate completions, and re-complete the resulting longer string.

completion-scoot-ahead
     (C-TAB) Insert the characters from the current completion as though typed manually, and look for completions of the resulting, longer string.

Note that, apart from the complete-word-at-point bindings, none of the other key bindings are active until you have started completing a word, either using complete-word-at-point or automatically if you are using auto-completion-mode (see Auto-Completion Mode).

Deleting Characters
-------------------

completion-delete-char
     (<delete>) Delete forwards and, after deleting, reject any completion at the point. A prefix argument sets the number of characters to delete.

completion-backward-delete-char
     Reject current completion, if there is one, and delete backwards. A prefix argument sets the number of characters to delete. If this deletes into a word and auto-completion-mode is enabled, complete what remains of that word.

completion-backward-delete-char-untabify
     (DEL) Similar to completion-backward-delete-char, but changes tabs to spaces as it deletes.

completion-kill-word (C-<delete>)

completion-kill-sentence

completion-kill-sexp

completion-kill-paragraph
     Similar to completion-delete-char, but kill forward until the end of the word/sentence/sexp/paragraph, instead of deleting individual characters.

completion-backward-kill-word (C-DEL)

completion-backward-kill-sentence

completion-backward-kill-sexp

completion-backward-kill-paragraph
     Similar to completion-backward-delete-char, but kill backward until the end of the word/sentence/sexp/paragraph, instead of deleting individual characters.

These commands replace the standard Emacs deletion and kill commands, so that they deal sensibly with any provisional completion that might be present in the region being deleted. If auto completion mode is enabled, the backwards deletion commands also re-complete any remaining prefix when they delete backwards into part of a word (see Auto-Completion Mode). In all other respects, these commands are identical to the equivalent standard deletion commands with corresponding names.

Auto-Completion Mode
====================

When the auto-completion minor mode is enabled by calling the auto-completion-mode command, predictive mode will automatically look for completions of words as you type. This is especially useful when used in conjunction with dynamic completion (see Dynamic Completion). If you would like auto-completion-mode to be enabled automatically whenever predictive mode is enabled, set the predictive-auto-complete variable (set by default).

auto-completion-mode
     Enable auto-completion Mode. In this minor mode, completions are found automatically as words are typed.

predictive-auto-complete
     When non-nil (the default), enabling and disabling predictive mode will also automatically enable or disable auto-completion-mode, without needing to run the auto-completion-mode command manually.

Word-constituent characters are added to the current word before finding new completions. The current syntax table (see Syntax (GNU Emacs Manual)) determines which characters are word-constituents and which are not (although the behaviour of individual characters can be overridden).

By customizing auto-completion-syntax-alist, you can make punctuation and white-space characters automatically accept the current completion. If you want to exceptionally insert a punctuation character as though it were a word-constituent (such as the . in e.g.), you can often prefix the character key with M-. The bindings M-. and M-- are already set up by default, but you can easily add more using the completion-define-word-constituent-binding convenience function in your .emacs file. See Character Syntax and Key Bindings, for more details about the syntax and key binding features.

The following variables affect the behaviour of auto-completion-mode:

auto-completion-syntax-alist
     Whether auto-completion-mode allows you to type normally, ignoring the provisional completions until you want to use one (select type normally in the customization buffer), or whether punctuation characters automatically accept the current provisional completion before the character is inserted (select punctuation accepts in the customization buffer). For full details, see Character Syntax and Key Bindings.

auto-completion-min-chars
     Minimum number of characters that must be typed before the various completion mechanisms are activated when using auto-completion-mode. Note that you can still explicitly invoke completion on a shorter prefix using the complete-word-at-point command (see Inserting Completions).

auto-completion-delay
     Number of seconds Emacs must be idle before the various completion mechanisms are activated when using auto-completion-mode (see Auto-Completion Mode).

auto-completion-backward-delete-delay
     Number of seconds Emacs must be idle after a backwards deletion (see Deleting Characters) before the various completion mechanisms are activated when using auto-completion-mode (see Auto-Completion Mode). Having a small delay is useful when the delete key is held down continuously. Default is 0.1 seconds.

Dynamic Completion
==================

Dynamic completion is controlled by the completion-use-dynamic customisation variable. When it is non-nil, the most likely completion is provisionally inserted in the buffer after the point and highlighted. If auto-completion-mode is enabled, typing more word-constituent characters will add them to the word, updating the most likely completion (see Auto-Completion Mode).

Note that since the completion-reject command ends the completion process, if you want to find completions for the same prefix again you have to do it manually with complete-word-at-point even when auto-completion-mode is enabled. See Inserting Completions, and Auto-Completion Mode.

completion-use-dynamic
     When non-nil, enable dynamic completion, which provisionally inserts the most likely conpletion in the buffer.

completion-dynamic-highlight-common-prefix
     When non-nil, the longest common prefix is highlighted ina different colour in the dynamic completion.

completion-dynamic-face
     The face used to highlight the provisional dynamic completion.

completion-dynamic-common-prefix-face
     The face used to highlight the longest common prefix in a dynamic completion.

Completion Hotkeys
==================

When the customisation variable completion-use-hotkeys is non-nil, you will be able to select a completion by typing a single character (the numerical characters 0--9 are used by default).

You will probably also want to display a list of the possible completions, so that you know which completion will be selected by each of these ``hotkeys'' (see Displaying Completions in the Echo Area, and Completion Tooltip).

The following variables affect the behaviour of the completion hotkeys:

completion-use-hotkeys
     When non-nil, enable completion hotkeys, allowing completion candidates to be selected by hitting a single key.

completion-hotkey-list
     List of keys to use for selecting completions. Default is numerical characters 0 to 9. Note that this variable must be set before loading the predictive mode libraries, e.g. in your .emacs file. See Keymaps and Key Bindings.

Of course, however many characters are in completion-hotkey-list, there cannot be more completions available than the number actually found! The maximum number to find is limited by completion-max-candidates, Miscellaneous Options.

Displaying Completions in the Echo Area
=======================================

If the customisation variable completion-use-help-echo is non-nil, a list of completion candidates is displayed in the echo area. If completion-use-hotkeys is also enabled (see Completion Hotkeys, the hot-key characters will be displayed next to the completions they select.

completion-use-help-echo
     When non-nil, a list of completion candidates (along with the hotkeys that select them, if enabled) is displayed in the echo area.

Completion Tooltip
==================

Calling completion-show-tooltip when completing, bound to S-Down, displays a list of available completions in a tooltip. The up and down arrow keys can then be used to select a completion from the list. The following variables affect the completion tooltip:

The tooltip can also be displayed automatically when completing, optionally after a time-delay. See Auto-Show a List of Completions.

completion-tooltip-timeout
     The number of seconds to display the tooltip. The tooltip is hidden automatically when it is no longer needed, but it is impossible to display a tooltip indefinitely in Emacs. The work-around is to set this to a very large value. Default is 86400.

completion-tooltip-offset
     A cons cell containing the number of pixels (an integer) by which to offset the tooltip by in the x and y directions (car and cdr, respectively).

completion-tooltip-face
     The face to use in the tooltip. Only the :foreground and :background attributes are actually used.

Pop-Up Frame
============

Calling completion-popup-frame when completing, bound to C-Down, displays the available completions in a separate Emacs frame positioned below the point. You can then use the usual Emacs motion keys to select a completion candidate and provisionally insert it in the buffer (up, down, M-p, M-n, C-p, C-n, pageup, C-v, M-v, pagedown, home, M-<, end and M->; you can also supply numerical optional arguments to these, as usual).

You can also toggle between displaying just the most likely completions or displaying all possible completions using completion-popup-toggle-all, bound to M-tab and M-/. If there are a lot of possible completions, it can take a while before they're displayed. If it's taking too long, use C-g to cancel. To dismiss the pop-up frame, use completion-popup-frame-dismiss, bound to C-up and M-up.

The pop-up frame can also be displayed automatically when completing, optionally after a time-delay. See Auto-Show a List of Completions.

completion-popup-frame
     (C-down) Display completion candidates in a pop-up frame.

completion-popup-frame-toggle-all
     (M-tab, M-/) Toggle between displaying the most likely completion candidates and displaying all possible completions.

completion-popup-frame-dismiss
     (C-up, M-up) Dismiss the pop-up frame.

The following variables affect the pop-up frame:

completion-popup-frame-max-height
     An integer specifying the maximum height (in rows) of pop-up frames.

completion-popup-frame-offset
     A cons cell containing the number of pixels (an integer) by which to offset the pop-up frame by in the x and y directions (car and cdr, respectively).

Completion Menu and Browser
===========================

Calling completion-show-menu when completing, bound to M-Down, will bring up the completion menu, from which you can select a completion to insert. If completion-use-hotkeys is enabled, the menu will also display the hotkeys next to the completions they select, although you will have to exit the menu before you can use them (see Completion Hotkeys).

The completion menu also contains a Browser entry, which replaces the completion menu with the completion browser. This hierarchically lists all possible completions, irrespective of the setting of completion-max-candidates (see Miscellaneous Options). If it's taking too long to construct the browser, you can hit C-g to cancel it. You can also display the browser directly using completion-show-browser-menu (not bound to any key by default).

The completion menu can be displayed automatically when completing, optionally after a time-delay, though because it steals the keyboard focus this is less useful than auto-displaying the tooltip or pop-up frame. See Auto-Show a List of Completions.

The following variables affect the behaviour of the completion menu and browser:

completion-menu-offset
     A cons cell containing the number of pixels (an integer) by which to offset the menu by in the x and y directions (car and cdr, respectively).

completion-browser-max-items
     Maximum number of completions to display in a completion browser menu. If there are more completions than this in a menu, the menu will be divided into submenus, and if necessary the submenus will be further divided into subsubmenus, and so on ad infinitum. Default is to 25.

completion-browser-buckets
     Chooses the algorithm used to subdivide browser menus into submenus. The symbol balance causes the number of entries in all menus, submenus, subsubmenus etc. to be made as equal as possible. The symbol max maximizes the number of entries in higher level menus (and hence minimizes the number of entries in lower level submenus), whereas minimize does the opposite. Note that none of these options affect the number of levels of submenu required in a given browser instance.

Auto-Show a List of Completions
===============================

One out of the completion tooltip, pop-up frame, or menu can be displayed automatically when you start completing (it makes no sense to display more than one of them at a time; they would simply mask each other). It can either be displayed immediately, or only after Emacs has been idle for a number of seconds. The following variables control this feature:

completion-auto-show
     When set to 'tooltip, 'pop-up or 'menu, the corresponding list of completions is displayed automatically when completing. When nil, nothing is displayed automatically (they can still be displayed manually when required).

completion-auto-show-delay
     Number of seconds (integer) that Emacs must be idle before the list of completions is displayed.

Miscellaneous Options
=====================

The following variables affect the overall behaviour of predictive mode:

completion-resolve-behaviour
     Determines what to do with dynamics completions that have not explicitly been accepted or rejected. The options are: 'leave, which just leaves the old provisional completion in place to return to later if you so desire, 'accept and 'reject, which accept or reject the completion, and 'ask, which asks you whether you want to accept or reject.

completion-resolve-behaviour controls what happens when you move the point away from a provisional dynamic completion (see Dynamic Completion) and start typing elsewhere in the buffer. When auto-completion-mode is disabled, it also determines how the current dynamic completion behaves. If completion-resolve-behaviour is set to 'reject, the current dynamic completion only serves as a visual indicator; it disappears unless you explicitly accept it. If completion-resolve-behaviour is set to anything else, dynamic completions really are part of the buffer, and you must explicitly reject them to get rid of the inserted characters.

There is one exception to this behaviour: whether or not auto-completion-mode is enabled, if you move the point to somewhere within a dynamic completion and start typing, that completion is always accepted. This is almost always what you intended, and leads to less surprises.

completion-overwrite
     When non-nil, completions overwrite the rest of the word after point, both when you manually call complete-word-at-point with the point positioned in the middle of a word, and when auto-completion-mode is enabled and you type a new character in the middle of a word. Enabled by default.

Predictive mode doesn't play all that well with overwrite-mode. The completion-overwrite option implements an intelligent, partial over-write behaviour for completions. This only has an effect if you try to start completing with the point in the middle of a word. When completion-overwrite is enabled, the part of the word at point that comes after the point will be over-written by the completion. When disabled, the completion is simply inserted in the middle of the word, without deleting the rest of it.

completion-max-candidates
     Maximum number of completions to find. Default is 10.

Setting completion-max-candidates to a large number is probably not useful, and will slow predictive mode down. It is easier to type a few extra characters than cycle through lots of completions, and the number available directly via hotkeys is limited by the number of keys you are prepared to set aside for selecting completions (see Completion Hotkeys).

predictive-ignore-initial-caps
     Controls whether predictive mode should ignore initial capital letters when searching for completions. If non-nil (the default), completions for the uncapitalised string are also found.

Only the first capital letter of a string is ignored. Thus typing A would find and (which would complete to And), Alaska and ANSI, but typing AN would only find ANSI, whilst typing a would only find and.

predictive-auxiliary-file-location
     Controls where any auxiliary files generated by predictive mode should be saved. It can either be a relative path, or an absolute path, but the former is strongly recommended. If it is a relative path, it is taken to be relative to the file that a predictive-mode buffer is visiting.

     If an absolute path is used, all auxiliary files for all predictive-mode buffers will be saved to the same location. In this case, there are no safe-guards to prevent two different auxiliary files that happen to have the same name from clobbering one another. That said, only identically named files in different directories pose a risk.

Depending on the settings you have chosen, predictive mode may not create any auxiliary files at all. The only one created in standard predictive mode buffers is the buffer-local dictionary (see Automatic Learning). However, the predictive mode support for a number of major-modes makes extensive use of auxiliary files. See Major Modes.

Dictionaries
************

Predictive completion is only as good as the dictionary it uses. The dictionary doesn't only list the words themselves, it also ranks them according to how likely they are, so that predictive mode can offer the most likely completions first.

As you type, predictive mode learns which words you use more frequently, so that the predictions improve. It can automatically ensure certain words are always ranked higher than others (useful when one word is a prefix for another).

Predictive mode is not restricted to using one dictionary at a time; it can use many dictionaries in parallel, and can automatically switch dictionaries in different regions of text, the regions being defined by regular expressions.

And predictive mode attempts to do all of that faster than you type, so that your typing is not slowed down even when using very large dictionaries. (As soon as Emacs becomes sentient -- surely not far off -- it will probably go on strike through being forced to work too fast!)

Creating Dictionaries
=====================

Predictive mode dictionaries store words along with their associated weights, used to rank the words in order of likelihood. The weight is just an integer value, which can be thought of as the relative frequency of a word (relative to the other words in the dictionary). A dictionary can also store prefix relationships between words, see Relationships Between Words.

The following commands are used to manually create and modify dictionaries:

predictive-create-dict
     Create a new dictionary. The dictionary name is read from the mini-buffer. You can optionally supply a filename to associate with the dictionary. The dictionary will be saved to this file by default (just as a buffer is saved to its associated file). You may also supply a file containing a list of words with which to populate the new dictionary. The predictive-completion-speed and predictive-dict-autosave variables set the new dictionary's completion speed and autosave flag (see below).

predictive-create-meta-dict
     Create a new meta-dictionary. A meta-dictionary is a wrapper around two or more dictionaries that behaves as if it was a single, combined dictionary. The weight of a word is the sum of it's weights in the constituent dictionaries, and the prefix relationships from all constituent dictionaries are merged (see Relationships Between Words). Apart from supplying a list of constituent dictionaries, the other options are identical to those for predictive-create-dict.

predictive-add-to-dict
     Insert a word into a dictionary. The dictionary name and word are read from the mini-buffer (defaults to the word at the point). An optional prefix argument specifies the weight. If the word is not already in the dictionary, it will be added to it with that initial weight (or 0 if none is supplied). If the word is already in the dictionary, its weight will be incremented by the weight value (or by 1 if none is supplied).

predictive-remove-from-dict
     Completely remove a word from a dictionary. The dictionary name and word are read from the mini-buffer (defaults to the word at the point).

predictive-reset-weight
     Reset the weight of a word in a dictionary to 0. The dictionary name and word are read from the mini-buffer. If no word is supplied, reset the weights of all words in the dictionary. If a prefix argument is supplied, reset weight(s) to that value, rather than 0.

dictree-size
     Display the number of words in a dictionary.

The file containing the list of words used to populate a dictionary has to conform to a specific format. Each line contains one word, delimited by "", optionally followed by an integer separated by white-space from the word itself, which specifies the word's weight. Any characters before the first " are ignored. Note that the `words' in a dictionary do not have to be words in the usual sense. They can be arbitrary sequences of characters, including white-space and punctuation characters. The quote character " can be included by escaping it: \". (see Known Bugs, however.)

To ensure it is as efficiently structured as possible, it is best to create a dictionary from a list of words using predictive-create-dict, rather than creating a blank dictionary and adding the words manually using predictive-add-to-dict. Also, deleting many words using predictive-remove-from-dict will eventually result in inefficient dictionary structures. For small dictionaries it won't make much difference, but for larger ones it can be significant. You can rebuild an inefficient dictionary by dumping the words to a buffer, creating a new dictionary, and populating it from the dumped words. See Loading and Saving Dictionaries.

The following variables set defaults for other dictionary properties:

predictive-completion-speed
     Sets the default completion speed of dictionaries created with predictive-create-dict. This is the desired upper limit on the time it takes to find completions; there is no guarantee it will be achieved! If it takes longer than this to find a particular completion, the results are cached so that they can be retrieved faster next time. Thus lower values result in faster completion, at the expense of dictionaries taking up more memory.

predictive-dict-autosave
     Sets the default autosave property for dictionaries created with predictive-create-dict. If non-nil, modified dictionaries will automatically be saved when they are unloaded (either with the predictive-dict-unload command, or when exiting emacs). If nil, any unsaved modifications will be lost unless the dictionary is saved manually. See Loading and Saving Dictionaries.

Loading and Saving Dictionaries
===============================

predictive-load-dict
     Load a dictionary by name, and add it to the list of dictionaries used by the current buffer. The dictionary will be included when learning from the buffer, see Learning from Buffers and Files, and if its autosave flag is set (see Creating Dictionaries), it will automatically be saved when the buffer is killed. The dictionary file must be in your load-path.

dictree-load
     Load a dictionary from file. The name of the loaded dictionary is the same as the file name, with the extension removed. This will not add it to the list of dictionaries used by the current buffer (see predictive-load-dict, above).

predictive-unload-dict
     Remove a dictionary from the list of dictionaries used by the current buffer. The dictionary will no longer be included when learning from the buffer, see Learning from Buffers and Files, and it will not be saved when the buffer is killed. Note that this doesn't actually unload the dictionary from Emacs (see dictree-unload, below).

dictree-unload
     Unload a dictionary. If the dictionary's autosave flag is set, this will also save it (see Creating Dictionaries), unless overridden by supplying a prefix argument.

predictive-save-dict
     Save a dictionary to its associated file. Prompt for a file name if there is none associated with the dictionary.

predictive-write-dict
     Write a dictionary to a file specified via the mini-buffer. This also associates the dictionary with that file. If a prefix argument is supplied, you will not be asked to confirm if over-writing an existing file.

predictive-save-modified-dicts
     Save all modified dictionaries that have a non-nil autosave flag. If a prefix argument is supplied, prompt for confirmation before saving each dictionary.

predictive-dump-dict-to-buffer
     Dump all words, weights and prefix relationships in the dictionary to a buffer, in the same format as that used to populate dictionaries (see Creating Dictionaries).

predictive-dump-dict-to-file
     Dump words, weights and prefix relationships to a text file rather than a buffer. If a prefix argument is supplied, you will not be asked to confirm if over-writing an existing file.

predictive-dict-autosave
     Sets the default autosave property for dictionaries created with predictive-create-dict. If non-nil, modified dictionaries will automatically be saved when they are unloaded (either with the predictive-dict-unload command, or when exiting emacs). If nil, any unsaved modifications will be lost unless the dictionary is saved manually. See Loading and Saving Dictionaries.

predictive-dict-compilation-mode
     Determines whether dictionaries are saved in compiled or uncompiled form, or both. If set to the symbol 'compiled, dictionaries are saved in compiled form, if set to 'uncompiled they are saved in uncompiled form, and if set to anything else they are saved in both forms (the default). A compiled dictionary can be loaded a lot faster, and is always used in preference to the uncompiled form if it exists. However, compiled dictionaries are not portable between different Emacs versions, whereas uncompiled ones are.

To use a dictionary, it must be loaded into memory. If the dictionary is in your load path, this can be done manually using the load-library or predictive-load-dict commands. The predictive-load-dict command additionally adds it to the list of dictionaries used by the current buffer. This has two implications: the dictionary will automatically be saved when the buffer is killed (assuming its autosave flag is non-nil, see Creating Dictionaries), and it will be included when learning from the buffer (see Learning from Buffers and Files). Alternatively, you can manually load a dictionary from file using the dictree-load command (you should avoid loading a dictionary using the load-file command, as it will not necessarily ensure that the dictionary is correctly associated with the file it was loaded from).

If you want a dictionary to be loaded every time you run Emacs, you can add the following line to your .emacs file:

     (require 'DICTIONARY-NAME)

The major-mode setup functions load the dictionaries they need automatically. See Major Modes.

A buffer is usually associated with a file, and saving the buffer with the Emacs save-buffer command writes any changes back to that file. Similarly, dictionaries are usually associated with a dictionary file. The predictive-save-dict command saves any changes back to that file. The predictive-write-dict command is analogous to the Emacs write-file command.

Dictionaries can be modified by adding words to them with the predictive-add-to-dict command (see Creating Dictionaries). If the auto-learn features are used, dictionaries are modified whenever a completion is accepted (see Automatic Learning). The predictive-save-modified-dicts saves all modified dictionaries whose autosave flag is set. Modified dictionaries used in a buffer are automatically saved when that buffer is killed if they have their autosave flag set. All modified autosave dictionaries are saved when you exit Emacs.

Basic Dictionary Usage
======================

The name of the main dictionary used by a buffer is stored in the buffer-local predictive-main-dict variable. Note that the variable usually contains the name of the dictionary (a symbol), not the dictionary itself. This is the dictionary predictive mode will normally search in when looking for completions.

predictive-main-dict can also hold a list of dictionary names. They are then treated as though they form one combined dictionary. However, when predictive-auto-add-to-dict is used, words are always added to the first dictionary in the list. See Automatic Learning.

predictive-set-main-dict
     This function can be used as a convenience to set the main dictionary for the current buffer. You will only be able to select dictionaries that are already loaded (see Loading and Saving Dictionaries). If you want to set the default main dictionary permanently, customize predictive-main-dict instead.

Region-Local Dictionaries
=========================

Using overlays, it is possible to set up dictionaries that are local to specific regions of text. The predictive mode support for a number of major modes (notably the LaTeX support) makes use of this feature (see Major Modes). Configuring region-local dictionaries is, however, beyond the scope of this user-guide. See Region-Local Dictionaries (Predictive Programmer Guide).

predictive-which-dict-mode
     Auxilliary minor-mode that displays the currently active dictionary in the mode-line.

Predictive mode provides an auxilliary minor-mode, predictive-which-dict-mode, which displays the name of the currently active dictionary in the mode-line, i.e. the dictionary that is active at the point. If the active dictionary is in fact a list of dictionaries, the name of the first dictionary in the list is displayed, followed by .... Positioning the mouse over the dictionary name displays the names of the other dictionaries, either in the echo-area (if tooltip-mode is disabled, or in a terminal) or in a tooltip. However, for this to work, you have to customize part of the mode-line-modes variable, as the default setting clobbers this functionality. Find the part that refers to the minor-mode-alist variable, and delete the help-echo property, i.e. change that part to:

     (:propertize ("" minor-mode-alist)
      mouse-face mode-line-highlight local-map
      (keymap (header-line keymap (down-mouse-3 . mode-line-mode-menu-1))
              (mode-line keymap (down-mouse-3 . mode-line-mode-menu-1)
                                (mouse-2 . mode-line-minor-mode-help)
                                (down-mouse-1 . mouse-minor-mode-menu))))

Dictionary Learning
===================

The better the weights in a dictionary match the frequency with which you use words, the more useful predictive mode will be. Some of the standard dictionaries already include word weights, which match average word frequencies taken from a large sample of texts. Some don't include any word weights. In any case, your personal word usage might be very different from the average.

Ideally, the weights in a dictionary should match your personal style of writing. In fact, since your writing style might change significantly depending on whether you're writing, say, a scientific article or an email, it may even be worth having different dictionaries for different circumstances.

The easiest way to teach a dictionary about your writing style is to supply it with samples of your writing, and have it learn the word weights from them. Predictive mode provides two ways to do this: learning from existing files, and automatic learning as you type.

Learning from Buffers and Files
-------------------------------

Predictive mode can learn word weights from existing text. The following commands can be used to do this. Note that they will not add new words to a dictionary; they only update weights of words that are already in the dictionary. The learning commands take account of region-local dictionaries, and will ensure words are learnt in the correct dictionaries (see Region-Local Dictionaries).

Usually, you want to accumulate knowledge from each new piece of text. But sometimes, you may want to start from scratch, and reset the word weights to zero before starting to train a dictionary (for example, to erase the predefined weights from the supplied English dictionary, so that you can train it on your own writing style). You can use the predictive-reset-weight command for this purpose (see Creating Dictionaries).

Note that all the learning commands (even the ``fast'' ones!) can take a long time to run.

predictive-learn-from-buffer
     Learns weights for words in a dictionary from text in a buffer. If no explicit dictionary is specified, this learns word weights for all dictionaries used by the current buffer (see Loading and Saving Dictionaries). Each occurrence of a word increments its weight in the dictionary. By default, only occurrences that occur in a region where the dictionary is active are taken into account (see Region-Local Dictionaries). When an explicit dictionary is specified, this can be overridden by supplying a prefix argument, in which case all occurrences are taken into account.

predictive-learn-from-file
     Like predictive-learn-from-buffer, but learns from a file instead of a buffer.

predictive-fast-learn-from-buffer
     Similar to predictive-learn-from-buffer. It runs faster for large dictionaries, at the expense of missing some words. Specifically, only words consisting entirely of word- or symbol-constituent characters (according to the buffer's syntax table) will be taken into account. Also, unlike predictive-learn-from-buffer, this command takes into account the setting of the predictive-auto-add-to-dict option. If an explicit dictionary is specified, words that are not already in the dictionary will be added to it if predictive-auto-add-to-dict has any non-nil value. Otherwise, predictive-auto-add-to-dict has the usual effect, as do the other auto-add-related options (see Automatic Learning).

predictive-fast-learn-from-file
     Like predictive-fast-learn-from-buffer, but learns from a file instead of a buffer.

Automatic Learning
------------------

Predictive mode can automatically learn which words you use most often as you type, in order to make better predictions. This feature is especially useful when you first start using a dictionary, to adapt it to your writing style. Once a dictionary has been trained and is making good predictions, it can be turned off to fix the order in which completions are offered (see What is predictive completion?), though leaving it on usually doesn't cause the order to change that much.

The following variables control automatic learning:

predictive-auto-learn
     Controls automatic word frequency learning. When non-nil (the default), the weight for a word in is incremented each time it is accepted as a completion, making the word more likely to be offered higher up the list of completions in the future. Words that are not already in the dictionary are ignored unless predictive-auto-add-to-dict is set.

predictive-auto-add-to-dict
     Controls automatic adding of new words to dictionaries. If nil (the default), new words are never automatically added to a dictionary. If t, new words are automatically added to the active dictionary. If set to a dictionary name, new words are automatically added to that dictionary instead of the active one.

predictive-add-to-dict-ask
     If non-nil, predictive mode will ask for confirmation before automatically adding any word to a dictionary. Enabled by default. This has no effect unless predictive-auto-add-to-dict is also set.

predictive-use-buffer-local-dict
     If non-nil, a special, buffer-local dictionary will be created for each predictive mode buffer. The buffer-local dictionary is used in conjunction with the predictive-main-dict, and the two act as a single, combined main dictionary for the buffer.

     The buffer-local dictionary is initially empty, but whenever a word is learnt (auto-learnt, auto-added, learnt from a buffer or file, or added manually), it is added to the buffer-local dictionary, and its weight there is incremented by a value predictive-buffer-local-learn-multiplier times higher than for normal dictionaries. Thus the buffer-local dictionary will help predictive mode adapt much faster to the vocabulary used in a specific buffer than global dictionaries alone can.

     If predictive-dict-autosave is enabled and the buffer is associated with a file, the buffer-local dictionary will automatically be saved to the directory containing the file (In fact, two dictionaries will be saved in the directory, since the buffer-local dictionary is composed of a meta-dictionary and a normal dictionary, see Creating Dictionaries.). When you load the file in the future, predictive mode will look for the buffer-local dictionary in the same directory; there is no need to add the directory to your load path. If the buffer is not associated with a file, the buffer-local dictionary will be discarded when you end the Emacs session.

predictive-buffer-local-learn-multiplier
     Sets the learning speed for buffer-local dictionaries. Whenever a word is added to a buffer-local dictionary, the weight increment is multiplied by this value before being added to any existing word weight. The default is 50.

predictive-use-auto-learn-cache
     If non-nil (the default), auto-learnt and auto-added words are cached, and only actually added to the dictionary when Emacs has been idle for predictive-flush-auto-learn-delay seconds or the buffer is killed (it has no effect unless at least one of predictive-auto-learn or predictive-auto-add-to-dict is also set). This avoids small but sometimes noticeable delays when typing. New words or word weights will not be taken into account until the cache is fully flushed.

predictive-auto-add-min-chars
     Minimum length of words auto-added to the dictionary. When enabled, words shorter than this will be ignored when auto-add is used.

predictive-auto-add-filter
     When this variable is set to a function, and when predictive-auto-add-to-dict is enabled, the function will called whenever a word is going to be auto-added to the dictionary, passing the word (a string) and the dictionary as arguments. The word will only be added if the function returns non-nil. If predictive-use-auto-learn-cache is enabled, the filter function will be called when cached entries are flushed, not when they're added to the cache, allowing even time-consuming filter functions to be used.

Note that if predictive-main-dict contains a list of dictionary names (see Basic Dictionary Usage), an automatically learnt or added word may not end up where you want it. The weight of a word is incremented in the first dictionary it is found in, and words are added to the first dictionary in the list (assuming predictive-auto-add-to-dict is set to t). It is best to ensure that dictionaries in the list do not duplicate any words.

The predictive-auto-add-filter is not a customization option, so it can only be set from Lisp code (e.g. a setup function, see Major Modes). One example of its use would be to filter out words that contain non-letter characters (though it may be better to customize completion-dynamic-syntax-alist and completion-dynamic-override-syntax-alist instead, see Syntax). The following will accomplish this:

     (setq predictive-auto-add-filter
           (lambda (word dict) (string-match "^[[:alpha:]]$" word)))

Note that the function must accept both the word and dictionary arguments, even if it doesn't make use of the dictionary.

Another example would be to check that words are spelled correctly before auto-adding them to a dictionary, either using ispell or using the English dictionary that comes with predictive mode. This sounds tautological, but it does make sense: the dictionary you use for predictive completion will only contain words you've used at least once, but typos and spelling mistakes won't make it into the dictionary (see Getting the Most out of Dictionaries).

     (setq predictive-auto-add-filter (lambda (word dict) (lookup-words word)))

Using the supplied predictive English dictionary will be faster than ispell, since it is optimised for looking up words, though this isn't such an issue if predictive-use-auto-learn-cache is enabled (the following assumes dict-english is already loaded, see Loading and Saving Dictionaries).

     (setq predictive-auto-add-filter
           (lambda (word) (dictree-member-p dict-english word)))

Other possible uses for predictive-auto-add-filter are limited only by your imagination!

Relationships Between Words
---------------------------

As well as word frequencies, predictive mode dictionaries can store certain relationships between words, to make learning more effective. With each word in a dictionary, a list of other words can be associated. Predictive mode automatically ensures that the weights of the words in this list are always at least as large as that of the word they are associated with.

This is most useful when one word is a prefix for another. For example, you may want to ensure that, however frequently the word learning is used, the weight of the word learn is always kept at least as big, so that it always takes precedence when completing.

The following functions allow you to define and undefine such prefix relationships (note that despite the command names and descriptions, predictive-define-prefix and predictive-undefine-prefix can be used to define relationships between any two words, not just prefixes; however, predictive-define-all-prefixes and the predictive-auto-define-prefixes feature can only define actual prefix relationships):

predictive-define-prefix
     Define one word to be a prefix of another. Predictive mode will ensure that the weight of the ``prefix'' word is always at least as large as that of the other. (Note that the word does not actually have to be a prefix of the other; this can be used to define a relationship between any two words, so that the weight of one is always larger than the other.)

predictive-undefine-prefix
     Remove a ``prefix'' definition. (As for predictive-define-prefix, the word does not actually have to be a prefix of the other.)

predictive-define-all-prefixes
     Add the given prefix to the prefix definitions of all words that for which it is a prefix, or define all possible prefix relationships in the dictionary if no explicit prefix is supplied. In the latter case, a numerical prefix argument sets a minimum word length for which to define a prefix relationship; relationships are only defined for words that are at least this long (the prefixes defined for those words can still be any length).

predictive-undefine-all-prefixes
     The analogue of predictive-define-all-prefixes. Remove the given prefix from the prefix definitions of all words, or remove all prefix definitions in the dictionary if no explicit prefix is supplied. In the latter case, a numerical prefix argument sets a minimum word length for which to undefine prefix relationships (the length of the prefixes that are undefined is still not restricted in any way).

The following variable is used to help guess a likely prefix as a default for predictive-define-prefix and predictive-undefine-prefix. It's default value is only appropriate for English.

predictive-guess-prefix-suffixes
     List of suffixes to use when guessing a likely prefix for a word. The suffixes a tried in the order they appear in the list, and the first one that matches the end of the word is used: the guessed prefix is the original word with the suffix removed.

Ensuring that prefixes take precedence when completing words is almost always a good idea. It makes predictive completion much more convenient (especially dynamic completion, see Dynamic Completion). Therefore, predictive mode includes a feature that, when enabled (the default), automatically defines all the prefix relationships whenever a word is added to a dictionary.

predictive-auto-define-prefixes
     When non-nil, predictive mode will automatically update all prefix relationships for a word in a dictionary when the word is added. The new word will always take precedence over any word that is an extension of it, and in their turn any words that are prefixes of the new word will take precedence over it.

Getting the Most out of Dictionaries
====================================

As it says at the beginning of this chapter, predictive completion is only as good as the dictionary it uses. The English dictionary supplied with the predictive package is trained on a large body of (British) English text, so the words and word weights it contains accurately reflect average English usage. But you are very unlikely to write ``average'' English (whatever that is!). To get the most out of predictive completion, it is better to train your dictionary on your own writing style, rather than someone else's.

There are two approaches to this. The first is to create a copy of the supplied English dictionary containing the all same words, but with all their weights reset to zero. You can then either use the auto-learn feature to slowly train the dictionary as you write (see Automatic Learning, or better still, kick-start things by training it on text you have already written by learning from existing files (see Learning from Buffers and Files). You can of course still leave auto-learn enabled in order to refine the dictionary, or even use the auto-add feature to automatically add missing words as you type them (see below).

A variant of this approach, if you don't like the supplied English dictionary, is to create the initial dictionary from some other list of words, e.g. the /usr/dict/words file on Unix systems. You will first need to massage the list into the format required by predictive-create-dict (see Creating Dictionaries), which is the same as the format produced by the dump commands (see Loading and Saving Dictionaries), but this should be easy for even a moderately savvy Emacs user (Keyboard macros may help here...)!

The second approach is to start from a completely empty dictionary, and use the auto-add feature to automatically add words as you type them (see Automatic Learning). The auto-add feature adds words when you ``accept'' them. In this case, since the words aren't already in the dictionary, the only way to accept words while typing is to ensure dynamic completion is enabled, and type an end-of-word character (such as a space or punctuation character) at the end of the word (see Dynamic Completion). Alternatively, you can use the fast learning commands predictive-fast-learn-from-buffer and predictive-fast-learn-from-file to add words from existing text (note that you must use the fast learning commands for this; the normal ones will only increment the weights of words that are already in the dictionary).

However you auto-add the words, there is a risk that some words that you don't want will make their way into the dictionary, for example typos and misspellings, or possibly words containing non-letter characters. The latter are best dealt with by appropriate entries in completion-dynamic-syntax-alist and completion-dynamic-override-syntax-alist (see Syntax). The former are best dealt with by setting a predictive-auto-add-filter function (see Automatic Learning). It's still a good idea to occasionally check which words are in the dictionary by dumping it to a buffer and scanning through it by hand or with ispell (see Loading and Saving Dictionaries).

So which approach is better? Each has advantages and disadvantages, and it comes down to personal preference. Training a reset copy of the supplied English dictionary (or one built from another word list) ensures that all the words in the dictionary are spelled correctly (assuming the words in the list were correct in the first place). It also means that predictive mode will provide spelling assistance even when you type an obscure word that you've never used before. On the other hand, the dictionary will contain many words that you will never use, and may lack words that you do use, which will have to be added by hand (unless you enable auto-add).

If you write different types of text (e.g. your novel, academic papers, and emails), the vocabulary you use will differ significantly between the different types of text. You will get more out of predictive completion by creating separate dictionaries for each. You can then set up predictive mode to select the appropriate dictionary automatically, either based on the major mode (see Major Modes) or, in the case of LaTeX documents, based on the document class (see LaTeX Support).

Once you've created your dictionaries, you can use the many features of predictive mode to tweak the dictionary training and behaviour to suit your every desire. Using buffer-local dictionaries can help predictive mode adapt faster to the specific vocabulary you are using in an individual document, especially if you set a large predictive-buffer-local-learn-multiplier (see Automatic Learning). Defining sensible prefix relationships between words makes sure predictive completion doesn't ``get in your way'' when you're typing fast (see Relationships Between Words). The predictive-auto-define-prefixes option and the predictive-define-all-prefixes command make defining prefix relationships very easy.

Finally, having gone to all this effort to create the perfect dictionary, it would be tragic to lose it all! Make sure you occasionally backup your dictionaries by dumping them to a plain text file using predictive-dump-dict-to-file (see Loading and Saving Dictionaries). This is vital before upgrading to a new version of Emacs, since there's no guarantee that the dictionary will be readable in the new version (The dictionaries are saved as compiled Elisp code for efficiency reasons, and the byte-code format can change even between minor Emacs versions.).

Advanced Customisation
**********************

This chapter describes the more advanced customisation features provided by predictive mode. Many of these are on the borderline between user-customisations and features to be used by Lisp packages that enhanced predictive completion for specific major modes, though describing all the features available to Lisp packages is beyond the scope of this user guide.

Character Syntax and Key Bindings
=================================

Predictive mode significantly changes what happens when normal, printable characters are typed. Different characters cause different behaviour. For example, letter characters will usually be added to the current word, updating the completions, whereas punctuation characters end the completion process.

This chapter describes the mechanisms that determine the behaviour of different characters, and how to customize them.

Keymaps and Key Bindings
------------------------

The following keymaps are defined by predictive mode:

predictive-map
     Main keymap, enabled whenever predictive mode is.

completion-map
     Keymap enabled whenever a completion minor mode (including predictive mode) is enabled.

auto-completion-map
     Keymap enabled whenever auto-completion-mode is.

completion-hotkey-map
     Keymap used when hotkey completion is enabled. Constructed from completion-hotkey-list. Warning: setting this directly will cause errors! Set completion-hotkey-list instead. See Completion Hotkeys.

completion-hotkey-list
     List of hotkey characters to use for selecting completions. Default is numerical characters 0 to 9. This must be set before predictive mode is loaded, so can not be customized, and must instead be set manually in your .emacs file before the (require 'predictive) line (see Obtaining and Installing. See Completion Hotkeys.

completion-dynamic-map auto-completion-dynamic-map
     Keymaps assigned to the overlay used to highlight the provisional completions inserted when dynamic completion is enabled. Not currently used (Minor mode keymaps override overlay keymaps in the older versions (21.x) of Emacs, limiting their use. For these versions, these overlay keymaps are simulated by bindings in completion-map and completion-dynamic-map using the completion-run-if-within-overlay function as a work-around (a.k.a. hack!).). See Dynamic Completion.

The various keymaps define key bindings for different situations that arise in predictive mode. The main predictive-map keymap is enabled whenever predictive mode is enabled, as is completion-map. The difference between them is that completion-map is used by all in-buffer completion modes that use the completion-UI library, whereas predictive-map is specific to predictive mode. The auto-completion-map keymap is enabled whenever auto-completion-mode is enabled. Note: if you find yourself thinking of re-binding printable characters in any of these keymaps to something other than completion-self-insert, don't! (at least not until you've read on a bit). What you probably want to change are the completion-dynamic-syntax-alist and completion-dynamic-override-syntax-alist variables. See Syntax.

completion-dynamic-map and auto-completion-dynamic-map are active within the provisional completions displayed by dynamic completion (see Dynamic Completion). The former is used when auto-completion-mode is disabled, the latter when it is enabled. They are used to provide key bindings for most of the completion features.

The completion-hotkey-map is is constructed automatically from the characters listed in completion-hotkey-list, and binds all those characters to predictive-select-completion. It should not be set directly; you may get strange results if the keymap and key list do not correspond!

If the keymaps are not defined when predictive mode is first loaded (see Obtaining and Installing), it creates the default keymaps and loads them into Emacs. Therefore, to completely re-define predictive mode key bindings, it is simpler to re-define the keymap variables before loading predictive mode (e.g. before the (require 'predictive) line in your .emacs file, see Obtaining and Installing). But if you simply want to modify a few key bindings, as will usually be the case, you can do it in the usual Emacs way, after loading predictive mode in your .emacs file.

Syntax
------

auto-completion-syntax-alist
     Alist associating character syntax descriptors with completion functions. Used by the completion-self-insert function to decide what to do based on a typed character's syntax.

auto-completion-override-syntax-alist
     Alist associating characters with completion functions. Overrides the default function for a typed character's syntax. Used by completion-self-insert.

completion-define-word-constituent-binding
     Convenience command for use in your .emacs file. It is used to define key bindings that insert a character as though it had a different syntax. Usually used to allow punctuation characters to be inserted one-off as word-constituents. To define KEY as a binding to insert character CHAR as though its were a word-constituent, use:

          (completion-define-word-constituent-binding key char)

     To define KEY as a binding to insert character CHAR as though its syntax class were SYNTAX, use:

          (completion-define-word-constituent-binding key char syntax)

     To ignore auto-completion-override-syntax-alist for this key binding, so that the behaviour is determined only by SYNTAX, supply a non-nil third argument:

          (completion-define-word-constituent-binding key char syntax t)

When a character is typed, predictive mode decides what to do based on that character's syntax, as defined by the current syntax table (see Syntax (GNU Emacs Manual)). All printable characters are bound by default to the function completion-self-insert, which inserts the character, looks up the character's syntax descriptor in auto-completion-syntax-alist, and carries out the associated actions.

By default, all word-constituent characters (syntax descriptor w) insert the character and complete the new prefix, all white-space and punctuation characters (descriptors SPACE and .) accept any provisional completion and insert the character, and anything else rejects any provisional completion and inserts the character.

Occasionally, the syntax-derived behaviour needs to be overridden for individual characters. The auto-completion-override-syntax-alist associates characters with completion behaviour and takes precedence over auto-completion-syntax-alist.

Each association in auto-completion-syntax-alist and auto-completion-override-syntax-alist is a two-element list of the form (Lisp packages can additionally set a third element that controls whether the typed character is inserted, and can replace any element in the list with a function that returns one of the values described here or nil, but these features are beyond the scope of this user-guide.):

     (<accept|reject|add> <string|word|none>)

The first element determines what happens if there is a provisional completion at the point: accept accepts it, reject rejects it, and add adds the typed character to the completion's prefix. The last element determines what kind of completion is done (if any) after the typed character is inserted: string and word complete the current prefix, whereas none doesn't do any completion. The string and word options differ in how they decide what prefix should be completed when no completion is in progress. string takes the prefix to be the prefix built up by typing sequential characters. word takes the prefix to be the part of the current word appearing before point (The value of completion-word-thing determines what is considered a word. Logically enough, it defaults to word. Lisp packages can redefine it, or even override the whole prefix-finding mechanism with their own function, but this is again beyond the scope of this user-guide.).. The difference is only evident when typing a character in the middle or at the end of an existing word, in which case string completes the newly typed character whereas word completes the existing word plus the new character.

Finally, it is occasionally useful to be able to manually override a character's syntax, and have it treated one-off as though it had a different syntax class. A key binding to do this can be created using the completion-define-word-constituent-binding function in your .emacs file (after the line loading the predictive package, see Obtaining and Installing). This is most commonly used to allow punctuation characters to be inserted one-off as word-constituents. The bindings M-., M--, M-/ and M-S-<SPC> are defined by default in predictive mode to do precisely this for the punctuation characters ., - and /.

Major Modes
===========

The many features of predictive mode allow you to set things up appropriately for whatever language you are typing, whether it be plain text, markup languages such as LaTeX or HTML, programming languages such as C or Lisp, etc. Predictive mode will work happily alongside the appropriate major-mode. However, since each language makes different demands of predictive completion, you may find yourself changing a large number of settings when switching major modes.

To facilitate using predictive completion alongside different major-modes, predictive mode can run a setup function determined by the current major-mode whenever it is switched on in a buffer. Of course, you can also use major mode hooks, but hooks are less convenient if you don't want to always switch on predictive mode in that major mode, or if you want to switch it on and off whilst within the mode.

predictive-major-mode-alist
     Alist associating a major-mode symbol with a function, which should take one argument. The alist is checked whenever predictive mode is enabled or disabled in a buffer using the predictive-mode or turn-on-predictive-mode commands (see Basic Completion Commands). If the buffer's major-mode matches one in the alist, the associated function is called with a positive argument if predictive mode is being enabled or a negative one if it is being disabled. This makes it easier to customize predictive mode for different major modes.

Since the setup function is determined by the current major-mode, predictive mode should be switched on after switching to the appropriate major-mode. If you always want to use predictive mode with a particular major-mode, the easiest way to do this is to add the predictive-mode command to the major-mode hook in your .emacs file, using a line something like this:

     (add-hook 'MAJOR-MODE-hook 'turn-on-predictive-mode)

The predictive package itself includes comprehensive support for LaTeX (predictive-setup-latex), Texinfo (predictive-setup-texinfo) and HTML (predictive-setup-html). More contributions are always welcome!. You must ensure that the dictionaries required in order to support these major-modes (which are also included in the package, see Obtaining and Installing) can be found in your load-path. The LaTeX, Texinfo, and HTML support goes far beyond simply changing a few configuration variables. See LaTeX Support, Texinfo Support, and HTML Support.

LaTeX Support
-------------

Predictive mode comes with comprehensive support for the LaTeX type-setting language. With the default settings, LaTeX support is enabled automatically when predictive completion mode is turned on in a LaTeX buffer, via an entry in predictive-major-mode-alist (see Major Modes).

predictive-latex-docclass-alist
     Alist associating LaTeX document classes (the docclass appearing inside \documentclass{<docclass>} with dictionaries.

predictive-latex-electric-environments
     When non-nil, environment names appearing inside \begin{<environment>} and \end{<environment>} are automatically synchronised.

By default, predictive mode will use the usual main dictionary in LaTeX mode, determined by predictive-main-dict (see Basic Dictionary Usage). However, by customizing predictive-latex-docclass-alist, the main dictionary can be selected automatically based on the document class.

In addition to the main dictionary, a number of LaTeX dictionaries are also used, grouped into four main categories: text-mode LaTeX commands, maths-mode LaTeX commands, preamble LaTeX commands, and LaTeX environments. The dictionaries in the different categories are used to look for completions in different contexts in the LaTeX document. The main LaTeX dictionaries in these categories are, respectively, dict-latex, dict-latex-math, dict-latex-preamble and dict-latex-env. In addition, there are dictionaries for LaTeX document classes (dict-latex-docclass), bibliography styles (dict-latex-bibstyle). Finally, a dictionary of cross-reference labels and dictionaries of locally defined LaTeX commands and environments, unique to each LaTeX file, are generated automatically (see Automatically Created Files for LaTeX).

Predictive mode will automatically complete words from the correct dictionary in different regions of your LaTeX document (The automatic dictionary switching is implemented using the auto-overlays Elisp package.). In the main body of the document it will complete from the main dictionary, as usual, and also from the dictionaries of text-mode LaTeX commands. Inside equation or other display-mode environments, between $'s, or between \[ and \], it will use the dictionaries of maths commands. Inside \begin{...} it will use the dictionaries of LaTeX environments. Inside \ref{...} it will use the dictionary of cross-reference labels, which is created and updated automatically for each LaTeX document. Inside \documentclass{...} and \bibliographystyle{...}, it will use the document class and bibliography style dictionaries, respectively.

When predictive-latex-electric-environments is enabled, the environment name appearing inside a LaTeX \end{<environment>} command is automatically synchronised with its matching \begin{<environment>} command. The synchronisation doesn't just occur when the \end command is first typed; it is kept synchronised at all times, even when the \begin command that it originally matched is deleted, causing it to match a different \begin somewhere else in the document. Also, when the environment name within either a \begin or an \end command is modified, the environment name within its matching partner is also modified accordingly. WARNING: this feature is known to have bugs, and should probably now be used at the moment (see Known Bugs).

The behaviour of different character syntax classes, and the behaviour of certain individual characters, is set up appropriately for LaTeX (see Character Syntax and Key Bindings). Also, a special LaTeX completion browser menu, more appropriate for browsing LaTeX commands, is used instead of the default one.

Predictive LaTeX mode honours the TeX-master variable. If it is turned on in a buffer whose TeX-master variable is set to the name of another LaTeX file, the TeX-master file will be visited, predictive mode will be enabled in its buffer, and all buffers with the same TeX-master will share various predictive mode settings.

LaTeX Packages
..............

Many LaTeX commands and features only become available when the appropriate package is included in the document using the \usepackage command. Predictive LaTeX mode supports this by automatically trying to load package dictionaries and configuration functions when a \usepackage command is typed, and unloading them again if it is modified or deleted.

When a \usepackage{PACKAGE} command is typed, predictive LaTeX mode looks for four dictionaries based on the PACKAGE name: dict-latex-PACKAGE, dict-latex-math-PACKAGE, dict-latex-preamblePACKAGE, and dict-latex-env-PACKAGE. These correspond to the four categories of LaTeX dictionary (see LaTeX Support). If any of these dictionaries are found, they are added to the list of dictionaries for the corresponding category, and will be active in the appropriate regions of the document. If the text of the \usepackage{PACKAGE} command is modified or deleted, the dictionaries are removed again.

In addition, when a \usepackage command is typed, modified or deleted, predictive LaTeX mode will try to load an Elisp file called predictive-latex-PACKAGE.el[c], and run package-specific load or unload functions, as appropriate. The variable predictive-latex-usepackage-functions is used to determine which function (if any) to call when loading or unloading a LaTeX package (see below). This allows arbitrary configuration changes to be made when packages are included in or removed from the document. (A common use of this is to add or remove auto-overlay regexps, see LaTeX Automatic Overlays (Predictive Programmer Guide).)

predictive-latex-usepackage-functions
     Alist associating LaTeX PACKAGE names (strings) with a list containing two functions: a function to be called when loading the package with that name (i.e. when \usepackage{PACKAGE} is typed), and a function to be called when unloading the package (i.e. when the \usepackage{PACKAGE} is modified or deleted). Entries should be added to this variable by the corresponding Elisp file, predictive-latex-PACKAGE.el[c].

The predictive completion package already comes with support for some LaTeX packages, though by no means all or even the most important (Dictionaries and Elisp code welcome!).

Automatically Created Files
...........................

The predictive completion LaTeX support automatically creates and updates dictionaries of cross-reference labels, dictionaries of locally-defined text-mode and math-mode LaTeX commands (defined using \newcommand), and a dictionary of locally-defined environments (defined using \newenvironment and \newtheorem) for each LaTeX buffer.

All these dictionaries are saved to the directory specified by predictive-auxiliary-file-location (see Miscellaneous Options), so by default they will be saved to a .predictive/ subdirectory of the directory containing the LaTeX file. They are given a filename of the form dict-latex-TYPE-FILENAME.elc, where TYPE is the type of dictionary (label, local-latex, local-math or local-env), and FILENAME is the name of the LaTeX file. Note that these dictionaries are shared across all buffers with the same TeX-master, and the location they are saved to will be based on the TeX-master file's name and directory.

To speed up loading of predictive mode's LaTeX support, a file containing information about the location of different regions within the document is saved to auto-overlays-FILENAME also located in predictive-auxiliary-file-location. (Separate files are created even for buffers that share the same TeX-master.)

Texinfo Support
---------------

The predictive mode Texinfo support shares much in common with the LaTeX support, but Texinfo is a somewhat simpler markup language than LaTeX (TeXnically they're both TeX, of course!). With the default settings, Texinfo support is enabled automatically when predictive completion mode is turned on in a Texinfo buffer, via an entry in predictive-major-mode-alist (see Major Modes).

Four Texinfo dictionaries are provided: dict-texinfo containing the main Texinfo @-commands, dict-texinfo-env containing the environment names (things that are ended by @end), dict-texinfo-indicating containing just the Texinfo ``indicating'' commands (see Indicating (GNU Texinfo Manual)), and dict-texinfo-math containing Texinfo @-commands that are specific to math-mode (@\ is the only one!). In addition, dict-latex-math is used in math-mode (It ought to be dict-tex-math, but that will have to await TeX support. See Known Bugs.) (see LaTeX Support). Finally, a dictionary of node names, a dictionary of locally defined Texinfo commands, add a dictionary of Texinfo flags, unique to each Texinfo file, are generated automatically (see Automatically Created Files for Texinfo).

Predictive mode will automatically complete words from the correct dictionary in different regions of your Texinfo document (The automatic dictionary switching is implemented using the auto-overlays Elisp package.). In the main body of the document it will complete from the main dictionary, as usual, and also from the dictionaries of Texinfo @-commands. After @end, it will offer environment names as completions, whereas after @table, @vtable, and @ftable it will offer Texinfo ``indicating'' commands. Inside @xref{...}, @pxref{...} and @ref{...}, it will use the dictionary of node names, which is created and updated automatically for each Texinfo document. Inside @clear{...}, @ifset{...} and @ifcler{...}, it will use the automatically-generated dictionary of flag names. Inside @math{...} it will offer standard TeX maths commands as completions (Currently, it actually offers LaTeX maths commands, see Known Bugs.).

The behaviour of different character syntax classes, and the behaviour of certain individual characters, is set up appropriately for Texinfo (see Character Syntax and Key Bindings). Also, a special Texinfo completion browser menu, more appropriate for browsing Texinfo commands, is used instead of the default one.

Automatically Created Files
...........................

The predictive completion Texinfo support automatically creates and updates dictionaries of node names, dictionaries of locally-defined Texinfo commands (defined using @macro, @rmacro or @alias), and a dictionary of flags (defined using @set), for each buffer.

All these dictionaries are saved to the directory specified by predictive-auxiliary-file-location (see Miscellaneous Options), so by default they will be saved to a .predictive/ subdirectory of the directory containing the Texinfo file. They are given a filename of the form dict-texinfo-TYPE-FILENAME.elc, where TYPE is the type of dictionary (node, local-texinfo, or flag), and FILENAME is the name of the Texinfo file.

To speed up loading of predictive mode's Texinfo support, a file containing information about the location of different regions within the document is saved to auto-overlays-FILENAME also located in predictive-auxiliary-file-location.

HTML Support
------------

HTML is a simpler markup language than LaTeX, and the predictive mode support for it is correspondingly simpler. It includes a dictionary of HTML tags, dict-html, and dictionaries of valid attributes for different tags, dict-html-TAG. Completion is context-sensitive: typing a < character will start completing an HTML tag, whereas within a tag predictive mode will complete from the appropriate tag attribute dictionaries. With the default settings, HTML support is enabled automatically when predictive completion mode is turned on in an HTML buffer, via an entry in predictive-major-mode-alist (see Major Modes).

To speed up loading of predictive mode's HTML support, a file containing information about the location of different regions within the document is saved to auto-overlays-FILENAME located in predictive-auxiliary-file-location (see Miscellaneous Options), which by default is a .predictive/ subdirectory of the directory containing the HTML file.

Bugs and Future Improvements
****************************

The predictive completion package has been tested on Emacs versions 21.3 and the multi-tty CVS branch, and is known to work reasonably well. It will not work under older versions, and currently doesn't work under any version of XEmacs.

Report bugs and feature requests to toby-predictive@dr-qubit.org. Even reports of which versions of Emacs it runs under are useful at this stage (though check the web-site http://www.dr-qubit.org/emacs.php first to make sure your version is not already listed).

Known Bugs
==========

Known bugs (in no particular order):

 1. Predictive mode does not work under XEmacs. Making it work will take some compatibility work, but should be possible.

 2. The predictive-latex-electric-environments feature is very flaky, and should probably not be used at the moment. It has occasionally been known to completely mess up LaTeX files by randomly deleting parts of them!

 3. There are probably still bugs remaining in the auto-overlay code, used in some major modes to set up region-local dictionaries. If you find one, please report it, along with precise instructions on how to reproduce it. They're fiendishly difficult to track down!

 4. The predictive mode Texinfo support uses dict-latex-math inside @math{...}, when it should only use TeX maths commands.

Future Improvements
===================

Possible future improvements to predictive completion (in no particular order):

 1. Allow the learning rate (i.e. increment added each time a word is learnt) to be set buffer-locally and/or separately for each dictionary?

 2. Support for more major modes. (This one will probably be here for ever. I suspect new major modes are being created faster than predictive mode setup functions!)

 3. More predictive mode configuration variables could be allowed to have ``overlay-local'' bindings, not just the active dictionary, completion-menu function, and completion-word-thing.

 4. Predictive mode should be integrated with the semantic or similar package, to make it more useful for programming languages. At the moment, it works best with plain text and markup languages.

Credits
*******

Much inspiration for the Emacs predictive completion package came from a similar package written for the nedit editor by Christian Merkwirth. Most significantly, it provided the clue that ternary search trees are the best data structure to use for the dictionaries.

Ternary search trees are described in a very readable article by Jon Bentley and Robert Sedgewick in Dr. Dobb's Journal, among other places. The article can be found via http://www.ddj.com/articles/1998/9804/.

Finally, the English dictionary supplied with the predictive completion package was originally based on the British National Corpus frequency tables, available from http://www.itri.brighton.ac.uk/~Adam.Kilgarriff/bnc-readme.html.

Copying this Manual
*******************

     [file fdl.texi not included]