* doc/lispref/minibuf.texi (Reading File Names): Clarify (Bug#8480).

doc/lispref/ChangeLog

 2011-05-28  Chong Yidong  <cyd@stupidchicken.com>
 
+	* minibuf.texi (Reading File Names): Clarify (Bug#8480).
+
 	* tips.texi (Coding Conventions): Remove antediluvian filename
 	limit recommendation (Bug#8538).
 

doc/lispref/minibuf.texi

@@ -1383,17 +1383,19 @@ Files, emacs, The GNU Emacs Manual}).  The exact behavior when using a
 graphical file dialog is platform-dependent.  Here, we simply document
 the behavior when using the minibuffer.
 
-The optional argument @var{require-match} has the same meaning as in
-@code{completing-read}.  @xref{Minibuffer Completion}.
+@code{read-file-name} does not automatically expand the returned file
+name.  You must call @code{expand-file-name} yourself if an absolute
+file name is required.
 
-@code{read-file-name} uses
-@code{minibuffer-local-filename-completion-map} as the keymap if
-@var{require-match} is @code{nil}, and uses
-@code{minibuffer-local-filename-must-match-map} if @var{require-match}
-is non-@code{nil}.  @xref{Completion Commands}.
+The optional argument @var{require-match} has the same meaning as in
+@code{completing-read}.  @xref{Minibuffer Completion}.  If
+@var{require-match} is @code{nil}, the local keymap in the minibuffer
+is @code{minibuffer-local-filename-completion-map}; otherwise, it is
+@code{minibuffer-local-filename-must-match-map}.  @xref{Completion
+Commands}.
 
 The argument @var{directory} specifies the directory to use for
-completion of relative file names.  It should be an absolute directory
+completing relative file names.  It should be an absolute directory
 name.  If @code{insert-default-directory} is non-@code{nil},
 @var{directory} is also inserted in the minibuffer as initial input.
 It defaults to the current buffer's value of @code{default-directory}.
@@ -1441,11 +1443,7 @@ argument that decides which file names are acceptable completion
 possibilities.  A file name is an acceptable value if @var{predicate}
 returns non-@code{nil} for it.
 
-@code{read-file-name} does not automatically expand file names.  You
-must call @code{expand-file-name} yourself if an absolute file name is
-required.
-
-Here is an example:
+Here is an example of using @code{read-file-name}:
 
 @example
 @group