   This file documents Tree Dired, the GNU Emacs Directory Browser, and
most of the extra features available as an option.

   Copyright (C) 1991, 1992 Free Software Foundation

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided also
that the section entitled "GNU General Public License" is included
exactly as in the original, and provided that the entire resulting
derived work is distributed under the terms of a permission notice
identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that the section entitled "GNU General Public License"
may be included in a translation approved by the author instead of in
the original English.

Dired Mark Internals
====================

   This is a short overview about how marking files and retrieving
marked files in Dired works.

   `ls' output is indented two spaces two make room for an optional
marker character in front of each file line.  Marking simply replaces
the first space with the marker character, usually `*' or, for
deletions, `D'.  Indenting just by one would leave the markers adjacent
to the permission bits.

`dired-mark-if'
     The macro `dired-mark-if' is used internally to mark files matching
     certain criteria. It takes two arguments, the PREDICATE, a lisp
     expression evaluating non-nil on file lines to be marked, and MSG,
     a message to be displayed while scanning the buffer.  MSG may be
     nil to suppress the message.

`dired-mark-map'
     To operate on the marked files, all internal Dired functions
     ultimately call the macro `dired-mark-map'.  It takes two
     arguments, BODY and ARG, plus an optional argument SHOW-PROGRESS:

     Perform BODY with point somewhere on each marked line (inside a
     `save-excursion') and return a list of BODY's results.  If no
     marked file could be found, execute BODY on the current line.

     If ARG is an integer, use the next ARG (or previous -ARG, if
     ARG<0) files instead of the marked files.  In that case point is
     dragged along.  This is so that commands on the next ARG (instead
     of the marked) files can be chained easily.  Note that for
     positive ARG point is left on the first file not operated upon, for
     negative on the last file operated upon

     If ARG is otherwise non-nil, use current file instead.

     If optional third argument SHOW-PROGRESS evaluates to non-nil, we
     redisplay the Dired buffer after each file is processed.  No
     guarantee is made about the position on the marked line.  BODY
     must ensure this itself if it depends on this.  Search starts at
     the beginning of the buffer, thus the `car' of the list
     corresponds to the line nearest to the buffer's bottom.  This is
     also true for (positive and negative) integer values of ARG.  The
     BODY should not be too long as it is expanded four times.

A common case is to retrieve the names of all marked files:

`dired-mark-get-files'
     Return the marked files as list of strings.  The list is in the
     same order as the buffer, that is, the car is the first marked
     file.  Values returned are normally absolute pathnames.  Optional
     argument LOCALP equal to `no-dir' means return the filename proper
     only, with no directory information; any other non-nil value means
     make them relative to default-directory.  Optional second argument
     ARG forces use of other files.  If ARG is an integer, use the next
     ARG files.  If ARG is otherwise non-nil, use the current file.

Known Problems with Dired
*************************

   There are some problems with Dired that are either not Dired's fault,
hard to fix or not worth fixing.

   * Renaming directories usually works fine (all affected Dired and
     file buffers are updated), but moving a directory between different
     filesystems (those on different hard disks or different
     partitions) does not work: it creates a plain target file
     containing the contents of the original directory (inodes and
     filenames) or fails completely.

     Unfortunately Emacs' builtin function `rename-file' does not give
     you a clear error message like `cross-device link attempted', but
     rather a spurious `(file-error "Removing old name" "not owner")',
     at least in Emacs 18.55.

     On some systems renaming a directory always fails (even within the
     same filesystem) with the spurious `not owner' error.

   * If `foo' is a symlink to a non-existing file, `(file-exists-p
     "foo")' returns nil.  Thus, Dired will overwite such (strange)
     kinds of symlinks without noticing.

     Dired could test both `file-symlink-p' and `file-exists-p', but
     this would slow down all file operations to catch a very rare case.

   * Copying a directory does not work - it results in a zero-length
     target file.

     This comes from Emacs' `copy-file' function, not from Dired.

     If you really want to copy a directory (recursively), use `!' and
     your favorite shell command to do it (e.g. cp -R or cp -r).

   * Initial spaces in a filename are not recognized.  If I could be
     sure that all `ls' programs insert exactly one space between the
     time and the filename, I could easily fix this.  But `ls' programs
     tend to vary in their amount of white space, and even with one
     `ls' program there is a difference between year and clocktime
     formats
            drwxr-xr-x 2 ab027    thp           512 Aug 13 1990  thp/
            drwxr-xr-x 4 ab027    thp           512 Feb  3 21:59 ./
     If your `ls' supports the `-b' switch and quotes spaces with that
     switch, simply add `b' to your `dired-listing-switches'.  See
     Listing Files in Dired.

     Spaces anywhere but at the beginning do work.

   * In general, only commands that may have targets outside of the
     current directory tree update other buffers (copy, move and link
     commands).

     Especially, deletions, (un)compress, chmod/chgrp/chown update only
     the current buffer.

   * Some compress programs make output even if all goes well.  Dired
     takes output as a sign of trouble and assumes that the subprocess
     failed.

     Redefine function `dired-check-process-checker' suitably to look
     closer at the generated output.  In Emacs 19, the exit status of
     compress will be checked.

   * Aliases like `rm -i' for `rm' or `ls -F' for `ls' can cause
     problems in Dired's (and Emacs') shell command.  (Aliases for `ls'
     only matter if you dired wildcards, because only then the shell is
     used to run `ls'.)  Csh expands aliases only for interactive
     shells, which is probably what you want.  In Bash, you can achieve
     this by testing `PS1' in your `~/.bashrc':
            # `.bashrc' file
            # this test fails when invoked by rsh
            if [ "${PS1-no}" != "no" ]       # is this an interactive shell?
            then
          	  . ~/.bash_alias          # if so, source aliases
            fi

   * Directory names starting with `-' (a minus) may lose when they are
     to be created or removed.  If you care about this, and your rmdir
     and mkdir understand about `--' meaning end of options, change
     `emacs-19.el' accordingly.

     In Emacs 19 the `make-directory' and `remove-directory' operations
     will be builtin, not implemented with `rmdir' and `mkdir'
     subprocesses.

   * `dired-nstd.el': This is still buggy.  For example, after you've
     compressed the last file it may not correctly return that file's
     absolute pathname (`dired-current-directory' erronously returns nil
     because of markers collapsed during redisplay), ultimately leading
     to lisp errors.

   * The regexp-using `%'-commands get into an endless loop if you
     specify a regular expression that matches the empty string.

   * Function `find-alternate-file' in Emacs 18.57 has a bug that causes
     `C-x C-v RET' (which usually re-visits the current buffer) to fail
     on Dired buffers.  This is fixed in the version in `emacs-19.el',
     automatically loaded by Dired.

   * It is not possible to resort the Dired buffer without reverting
     it. That would be hard to implement (and slow to run) given that
     ls date format would have to be parsed for `ls -t' sorting order.