Reorganize README

README.md

@@ -11,12 +11,13 @@ Get it from MELPA: http://melpa.org/#/ido-ubiquitous
 
 ## Version 3.0 changes ##
 
-ido-ubiquitous version 3.0 is a major update, including a split into
-two packages, and some of the configuration options have changed in
-non-backwards-compatible ways. If you have customized ido-ubiquitous,
-be sure to check out `M-x customize-group ido-ubiquitous` and `M-x
-customize-group ido-completing-read+` after updating to 3.0 and make
-sure the new settings are to your liking.
+Long-time users should know that ido-ubiquitous version 3.0 is a major
+update, including a split into two packages, and some of the
+configuration options have changed in non-backwards-compatible ways.
+If you have customized any options ido-ubiquitous, be sure to check
+out `M-x customize-group ido-ubiquitous` and `M-x customize-group
+ido-completing-read+` after updating to 3.0 and make sure the new
+settings are to your liking.
 
 # How to enable ido in as many places as possible #
 
@@ -34,7 +35,8 @@ First, enable `ido-mode` and `ido-everywhere`.
 
 ## ido-ubiquitous (this package) ##
 
-Install this package and then turn on `ido-ubiquitous-mode`:
+Install this package [from MELPA](http://melpa.org/#/ido-ubiquitous)
+and then turn on `ido-ubiquitous-mode`:
 
     (require 'ido-ubiquitous)
     (ido-ubiquitous-mode 1)
@@ -49,9 +51,10 @@ package, then follow the directions to set up key-bindings for it.
 ## ido-yes-or-no ##
 
 If you want to use ido for yes-or-no questions, even though it's
-massive overkill, install the ido-yes-or-no package (soon to be
-available from MELPA):
-https://github.com/DarwinAwardWinner/ido-yes-or-no
+massive overkill, install my [ido-yes-or-no package from MELPA](http://melpa.org/#/ido-yes-or-no), and then enable the mode:
+
+    (require 'ido-yes-or-no)
+    (ido-yes-or-no-mode 1)
 
 ## ido for `describe-face` and certain other commands ##
 
@@ -61,13 +64,13 @@ commands with `crm-custom-mode`, which replaces
 `completing-read-multiple` with repeated calls to `completing-read`,
 which would then use ido thanks to ido-ubiquitous-mode. First, install
 the [crm-custom](https://github.com/DarwinAwardWinner/crm-custom)
-package from MELPA: http://melpa.org/#/crm-custom
-
-Then enable the mode:
+package [from MELPA](http://melpa.org/#/crm-custom), then enable the
+mode:
 
+    (require 'crm-custom)
     (crm-custom-mode 1)
 
-Rememebr that when using this mode, completion for affected commands
+Remember that when using this mode, completion for affected commands
 will continue to read additional items until you use C-j to enter an
 empty input, which terminates the completion. (Due to this quirk, I do
 not find this mode to be very useful in conjunction with ido, but it
@@ -75,9 +78,10 @@ does work.)
 
 ## Packages with built-in ido support ##
 
-Finally, some packages implement their own completion customizations,
-and ido-ubiquitous specifically avoids interfering with these, so you
-need to enable them separately.
+Lastly, some packages already provide their own interfaces to ido, so
+ido-ubiquitous specifically avoids interfering with these. If you use
+any of the following packages, you need to enable ido for each of them
+separately.
 
 * Org Mode: `(setq org-completion-use-ido t)`
 * Magit: `(setq magit-completing-read-function 'magit-ido-completing-read)`
@@ -86,45 +90,47 @@ need to enable them separately.
 (You can also use `M-x customize-variable` to set all of these
 options.)
 
-## "But some commands still aren't using ido! What gives?" ##
+# Frequently asked questions #
 
-There are some features of `completing-read` that ido cannot handle,
-and by default ido-ubiquitous tries to get out of the way whenever it
-detects that these features might be used. But the detection is not
-perfect and errs on the side of caution, so ido may be disabled for
-commands where it is actually perfectly safe. If you find a command
-that you think should be using ido but isn't, you can try customizing
-`ido-ubiquitous-command-overrides` to tell ido-ubiquitous that certain
-commands are safe for ido completion, or you can customize
-`ido-ubiquitous-allow-on-functional-collection` and
-`ido-ubiquitous-max-items` to turn off the saveguards and always force
-ido in ambiguous cases. Be aware, this could cause certain commands
-not to work correctly or at all.
-
-# How ido-ubiquitous decides when to replace `completing-read` #
+## How does ido-ubiquitous decide when to replace `completing-read`? <br/>  Why don't some commands use ido completion? ##
 
 Emacs' `completing-read` is a complex function with many advanced
 features and some quirks that are only maintained for backwards
 compatibility. Not all of these features are supported by ido, so it
 is impossible to always replace `completing-read` with ido completion.
-Furthermore, it's not always possible to detect based on the arguments
-to `completing-read` whether such ido-incompatible features are being
-used or not. ido-ubiquitous uses a series of heuristics to determine
-whether unsupported features *might* be used, and also supports an
-override feature to correct it when the heuristics get things wrong.
-
-Each time `completing-read` is invoked, ido-ubiquitous selects one of
-3 modes:
+Trying to use ido when these features are requested can completely
+break the completion system. So, by default ido-ubiquitous tries to
+get out of the way whenever it detects that these features might be
+used by a given call to `completing-read`. Furthermore, it's not
+always possible to detect based on the arguments to `completing-read`
+whether such ido-incompatible features are being used or not.
+ido-ubiquitous uses a series of heuristics to determine whether
+unsupported features *might* be used, and also supports an override
+feature to correct it when the heuristics get things wrong.
+
+Each time a function invokes `completing-read`, ido-ubiquitous selects
+one of 3 modes:
 
 * `enable`: use ido completion;
 * `enable-old`: use ido completion, but with a compatibility fix for
 old-style default selection; and
 * `disable`: no ido completion.
 
-The following describes how ido-ubiquitous selects the appropriate
-mode, and what to do when you think it is making the wrong choice.
+The following describes in detail how ido-ubiquitous selects the
+appropriate mode, and what to do when you think it is making the wrong
+choice.
+
+### Disabling ido completion when the collection is very large ###
+
+Ido can get slow on very large collections, so by default
+ido-ubiquitous disables itself for collections with more than 30,000
+items in them. This rule takes precedence over anything else, even
+overrides that explicitly enable ido completion for a command.
+
+You can change the large collection threshold by customizing
+`ido-cr+-max-items`.
 
-## When the collection is a function ##
+### Disabling ido completion when the collection is a function ###
 
 One feature of `completing-read` is that the collection argument can
 be a function. This function could simply return a list of all
@@ -142,30 +148,32 @@ command that uses this feature to implement non-standard completion.
 
 If you run across a command that unexpectedly uses normal Emacs
 completion instead of ido completion, it's likely that either this or
-the following option is to blame.
+the previous option is to blame.
 
-## When the collection is very large ##
+### Disabling or enabling ido completion by overrides ###
 
-Ido can get slow on very large collections, so by default
-ido-ubiquitous disables itself for collections with more than 30,000
-items in them. You can change this threshold by customizing
-`ido-cr+-max-items`.
+If ido-ubiquitous is not running for a command where is should be due
+to the functional collection rule, you can add an override for that
+command by using `M-x customize-variable
+ido-ubiquitous-command-overrides`. Conversely, if ido completion
+causes problems for a command, you can also use this to disable
+ido-ubiquitous for that command.
 
-## Old-style default selection ##
+## What is old-style default selection? ##
 
 The `enable-old` mode of operation is required because the old way for
 `completing-read` to indicate that the user simply pressed RET and
 selected the default option was to return an empty string. When this
 old-style mode is used, `completing-read` doesn't even know what the
-default is supposed to be -- the calling code handles all of that. But
-in ido, simply pressing RET will return the first item of the list,
-not an empty string. The way to enter an empty string in ido is C-j.
-The `enable-old` mode enables ido completion, but swaps the meaning of
-C-j and RET if you haven't entered any text or cycled the options yet
-(once you do either of those, C-j and RET regain their standard
-meanings). This allows you to select the default by pressing RET as
-soon as the completion prompt appears, as intended (C-j would select
-the first item).
+default is *supposed* to be -- the calling code handles all of that.
+But in ido, simply pressing RET will return the first item of the
+list, not an empty string. The way to enter an empty string in ido is
+C-j. The `enable-old` mode enables ido completion, but swaps the
+meaning of C-j and RET if you haven't entered any text or cycled the
+options yet (once you do either of those, C-j and RET regain their
+standard meanings). This allows you to select the default by pressing
+RET as soon as the completion prompt appears, as intended (C-j would
+select the first item).
 
 Unfortuantely, there is no way for ido-ubiquitous to detect when a
 command is using this old-style default selection, so instead it uses
@@ -173,31 +181,57 @@ a built-in set of overrides telling it about commands that are known
 to use old-style defaults. If you discover a command where pressing
 RET or C-j at an empty prompt is not doing what you expect it to,
 there's a good chance that you need to add an `enable-old` override
-for that command. Luckily, since this is an obsolete usage pattern, it
-is unlikely that any Elisp functions written since 1990 or so will
-need to be added to this list.
+for that command to `ido-ubiquitous-command-overrides`. Luckily, since
+this is an obsolete usage pattern, it is unlikely that any Elisp
+functions written since 1990 or so will need to be added to this list.
+Hopefully all uses of old-style completion will eventually be
+eliminated, and with them, the need for this feature of
+ido-ubiquitous.
 
-## "A command is not working the way I expect it to! What should I do?" ##
+## How can I troubleshoot when ido-ubiquitous isn't doing what I want? ##
 
 First, invoke the `ido-ubiquitous-debug-mode` and `ido-cr+-debug-mode`
-commands (ido-cr+ is a lower-level package underlying ido-ubiquitous
-and implementing generic improvements to `ido-completing-read`). Then,
-with these two modes active, run the offending command. Then examine
-the Messages buffer, where ido-ubiquitous will explain which mode of
-operation it selected and why. Based on this, you can add an override
-to `ido-ubiquitous-command-overrides`. If you are not familiar with
-the structure of this variable, I recommend using `M-x
-customize-variable` to edit it, which will help you get it right. If
-ido completion was skipped ido completion because the collection was
-too large, try giving `ico-cr+-max-items` a larger value, or set it to
-nil if your computer is fast enough to handle any size of collection.
-
-New versions often include new overrides, but Emacs will not edit your
-override variables if you have already customized them. So, if you
-have recently upgraded ido-ubiquitous, remember to invoke
+commands. Then, with these two modes active, run the command(s) that
+you are having trouble with, and when the completion prompt appears,
+make a selection to complete the process. Then, examine the Messages
+buffer, where ido-ubiquitous will explain which mode of operation it
+selected and why. Based on this, you can add an override to
+`ido-ubiquitous-command-overrides`. If you are not familiar with the
+structure of this variable, I recommend using `M-x customize-variable`
+to edit it, which will help you get it right. If ido completion was
+skipped ido completion because the collection was too large, try
+giving `ico-cr+-max-items` a larger value, or set it to nil if your
+computer is fast enough to handle any size of collection.
+
+Updates to ido-ubiquitous often include new overrides, but Emacs will
+not edit your override variables if you have already customized them.
+So, if you have recently upgraded ido-ubiquitous, remember to invoke
 `ido-ubiquitous-restore-default-overrides` to add in any new
-overrides.
+overrides. (In the future, this process may become automatic:
+https://github.com/DarwinAwardWinner/ido-ubiquitous/issues/90)
+
+## Where can I report bugs or suggest new overrides? ##
 
-If you do add any overrides yourself, please also report them at
+If you end up adding any overrides, please also report them at
 https://github.com/DarwinAwardWinner/ido-ubiquitous/issues so I can
-add them to the default set for future versions.
+incorporate them into the defaults for future versions. You can also
+report any bugs you find in ido-ubiquitous.
+
+# ido-completing-read+ #
+
+As of version 3.0, most of the core functionality of ido-ubiquitous
+has been spun off into a separate library called ido-completing-read+,
+or "ido-cr+" for short. ido-cr+ incorporates all the features of
+ido-ubiquitous that are actually just generic improvements to ido that
+should probably always be anabled. It implements these fixes in a
+single function `ido-completing-read+`, which should be suitable as a
+drop-in replacement for either `ido-completing-read` or
+`completing-read`. Notably, unlike the original `ido-completing-read`,
+`ido-completing-read+` should always do something useful, by falling
+back to normal completion when ido completion won't work.
+Additionally, it allows you to manually fall back using C-f and C-b,
+in the same way you can use those keys to switch between file and
+buffer completion in ido. As a user, you don't really need to know
+anything about ido-cr+. However, if you are writing an Emacs package
+and would like to incorpoarte ido completion, you may wish to use
+ido-cr+ to get more robust completion with fewer weird edge cases.