-If the input is null, `completing-read' returns an empty string,
- regardless of the value of REQUIRE-MATCH.
-
-If INITIAL-INPUT is non-nil, insert it in the minibuffer initially.
- If it is (STRING . POSITION), the initial input
- is STRING, but point is placed POSITION characters into the string.
- This feature is deprecated--it is best to pass nil for INITIAL-INPUT
- and supply the default value DEF instead. The user can yank the
- default value into the minibuffer easily using \\[next-history-element].
-
-HIST, if non-nil, specifies a history list
- and optionally the initial position in the list.
- It can be a symbol, which is the history list variable to use,
- or it can be a cons cell (HISTVAR . HISTPOS).
- In that case, HISTVAR is the history list variable to use,
- and HISTPOS is the initial position (the position in the list
- which INITIAL-INPUT corresponds to).
- Positions are counted starting from 1 at the beginning of the list.
- The variable `history-length' controls the maximum length of a
- history list.
+If the input is null, `completing-read' returns DEF, or an empty string
+ if DEF is nil, regardless of the value of REQUIRE-MATCH.
+
+If INITIAL-INPUT is non-nil, insert it in the minibuffer initially,
+ with point positioned at the end.
+ If it is (STRING . POSITION), the initial input is STRING, but point
+ is placed at _zero-indexed_ position POSITION in STRING. (*Note*
+ that this is different from `read-from-minibuffer' and related
+ functions, which use one-indexing for POSITION.) This feature is
+ deprecated--it is best to pass nil for INITIAL-INPUT and supply the
+ default value DEF instead. The user can yank the default value into
+ the minibuffer easily using \\[next-history-element].
+
+HIST, if non-nil, specifies a history list and optionally the initial
+ position in the list. It can be a symbol, which is the history list
+ variable to use, or it can be a cons cell (HISTVAR . HISTPOS). In
+ that case, HISTVAR is the history list variable to use, and HISTPOS
+ is the initial position (the position in the list used by the
+ minibuffer history commands). For consistency, you should also
+ specify that element of the history as the value of
+ INITIAL-INPUT. (This is the only case in which you should use
+ INITIAL-INPUT instead of DEF.) Positions are counted starting from
+ 1 at the beginning of the list. The variable `history-length'
+ controls the maximum length of a history list.