-give to @code{ls} for listing the directory; this string @emph{must}
-contain @samp{-l}. If you use a prefix argument with the @code{dired}
-command, you can specify the @code{ls} switches with the minibuffer
-before you enter the directory specification. No matter how they are
-specified, the @code{ls} switches can include short options (that is,
-single characters) requiring no arguments, and long options (starting
-with @samp{--}) whose arguments are specified with @samp{=}.
-
- On MS-Windows and MS-DOS systems, Emacs @emph{emulates} @code{ls};
-see @ref{ls in Lisp}, for options and peculiarities of that emulation.
+give to @command{ls} for listing the directory; this string
+@emph{must} contain @samp{-l}. If you use a prefix argument with the
+@code{dired} command, you can specify the @command{ls} switches with the
+minibuffer before you enter the directory specification. No matter
+how they are specified, the @command{ls} switches can include short
+options (that is, single characters) requiring no arguments, and long
+options (starting with @samp{--}) whose arguments are specified with
+@samp{=}.
+
+@vindex dired-use-ls-dired
+ If your @command{ls} program supports the @samp{--dired} option,
+Dired automatically passes it that option; this causes @command{ls} to
+emit special escape sequences for certain unusual file names, without
+which Dired will not be able to parse those names. The first time you
+run Dired in an Emacs session, it checks whether @command{ls} supports
+the @samp{--dired} option by calling it once with that option. If the
+exit code is 0, Dired will subsequently use the @samp{--dired} option;
+otherwise it will not. You can inhibit this check by customizing the
+variable @code{dired-use-ls-dired}. The value @code{unspecified} (the
+default) means to perform the check; any other non-@code{nil} value
+means to use the @samp{--dired} option; and @code{nil} means not to
+use the @samp{--dired} option.
+
+ On MS-Windows and MS-DOS systems, Emacs emulates @command{ls}.
+@xref{ls in Lisp}, for options and peculiarities of this emulation.