+File: lispref.info, Node: Changing File Attributes, Next: File Names, Prev: Information about Files, Up: Files
+
+Changing File Names and Attributes
+==================================
+
+ The functions in this section rename, copy, delete, link, and set the
+modes of files.
+
+ In the functions that have arguments NEWNAME and
+OK-IF-ALREADY-EXISTS, if a file by the name of NEWNAME already exists,
+the actions taken depend on the value of OK-IF-ALREADY-EXISTS:
+
+ * Signal a `file-already-exists' error if OK-IF-ALREADY-EXISTS is
+ `nil'.
+
+ * Request confirmation if OK-IF-ALREADY-EXISTS is a number. This is
+ what happens when the function is invoked interactively.
+
+ * Replace the old file without confirmation if OK-IF-ALREADY-EXISTS
+ is any other value.
+
+ - Command: add-name-to-file filename newname &optional
+ ok-if-already-exists
+ This function gives the file named FILENAME the additional name
+ NEWNAME. This means that NEWNAME becomes a new "hard link" to
+ FILENAME. Both these arguments must be strings.
+
+ In the first part of the following example, we list two files,
+ `foo' and `foo3'.
+
+ % ls -l fo*
+ -rw-rw-rw- 1 rms 29 Aug 18 20:32 foo
+ -rw-rw-rw- 1 rms 24 Aug 18 20:31 foo3
+
+ Then we evaluate the form `(add-name-to-file "~/lewis/foo"
+ "~/lewis/foo2")'. Again we list the files. This shows two names,
+ `foo' and `foo2'.
+
+ (add-name-to-file "~/lewis/foo1" "~/lewis/foo2")
+ => nil
+
+ % ls -l fo*
+ -rw-rw-rw- 2 rms 29 Aug 18 20:32 foo
+ -rw-rw-rw- 2 rms 29 Aug 18 20:32 foo2
+ -rw-rw-rw- 1 rms 24 Aug 18 20:31 foo3
+
+ Finally, we evaluate the following:
+
+ (add-name-to-file "~/lewis/foo" "~/lewis/foo3" t)
+
+ and list the files again. Now there are three names for one file:
+ `foo', `foo2', and `foo3'. The old contents of `foo3' are lost.
+
+ (add-name-to-file "~/lewis/foo1" "~/lewis/foo3")
+ => nil
+
+ % ls -l fo*
+ -rw-rw-rw- 3 rms 29 Aug 18 20:32 foo
+ -rw-rw-rw- 3 rms 29 Aug 18 20:32 foo2
+ -rw-rw-rw- 3 rms 29 Aug 18 20:32 foo3
+
+ This function is meaningless on non-Unix systems, where multiple
+ names for one file are not allowed.
+
+ See also `file-nlinks' in *Note File Attributes::.
+
+ - Command: rename-file filename newname &optional ok-if-already-exists
+ This command renames the file FILENAME as NEWNAME.
+
+ If FILENAME has additional names aside from FILENAME, it continues
+ to have those names. In fact, adding the name NEWNAME with
+ `add-name-to-file' and then deleting FILENAME has the same effect
+ as renaming, aside from momentary intermediate states.
+
+ In an interactive call, this function prompts for FILENAME and
+ NEWNAME in the minibuffer; also, it requests confirmation if
+ NEWNAME already exists.
+
+ - Command: copy-file filename newname &optional ok-if-already-exists
+ time
+ This command copies the file FILENAME to NEWNAME. An error is
+ signaled if FILENAME does not exist.
+
+ If TIME is non-`nil', then this functions gives the new file the
+ same last-modified time that the old one has. (This works on only
+ some operating systems.)
+
+ In an interactive call, this function prompts for FILENAME and
+ NEWNAME in the minibuffer; also, it requests confirmation if
+ NEWNAME already exists.
+
+ - Command: delete-file filename
+ This command deletes the file FILENAME, like the shell command `rm
+ FILENAME'. If the file has multiple names, it continues to exist
+ under the other names.
+
+ A suitable kind of `file-error' error is signaled if the file does
+ not exist, or is not deletable. (On Unix, a file is deletable if
+ its directory is writable.)
+
+ See also `delete-directory' in *Note Create/Delete Dirs::.
+
+ - Command: make-symbolic-link filename newname &optional
+ ok-if-already-exists
+ This command makes a symbolic link to FILENAME, named NEWNAME.
+ This is like the shell command `ln -s FILENAME NEWNAME'.
+
+ In an interactive call, this function prompts for FILENAME and
+ NEWNAME in the minibuffer; also, it requests confirmation if
+ NEWNAME already exists.
+
+ - Function: set-file-modes filename mode
+ This function sets mode bits of FILENAME to MODE (which must be an
+ integer). Only the low 12 bits of MODE are used.
+
+ - Function: set-default-file-modes mode
+ This function sets the default file protection for new files
+ created by XEmacs and its subprocesses. Every file created with
+ XEmacs initially has this protection. On Unix, the default
+ protection is the bitwise complement of the "umask" value.
+
+ The argument MODE must be an integer. Only the low 9 bits of MODE
+ are used.
+
+ Saving a modified version of an existing file does not count as
+ creating the file; it does not change the file's mode, and does
+ not use the default file protection.
+
+ - Function: default-file-modes
+ This function returns the current default protection value.
+
+ On MS-DOS, there is no such thing as an "executable" file mode bit.
+So Emacs considers a file executable if its name ends in `.com', `.bat'
+or `.exe'. This is reflected in the values returned by `file-modes'
+and `file-attributes'.
+
+\1f
+File: lispref.info, Node: File Names, Next: Contents of Directories, Prev: Changing File Attributes, Up: Files
+
+File Names
+==========
+
+ Files are generally referred to by their names, in XEmacs as
+elsewhere. File names in XEmacs are represented as strings. The
+functions that operate on a file all expect a file name argument.
+
+ In addition to operating on files themselves, XEmacs Lisp programs
+often need to operate on the names; i.e., to take them apart and to use
+part of a name to construct related file names. This section describes
+how to manipulate file names.
+
+ The functions in this section do not actually access files, so they
+can operate on file names that do not refer to an existing file or
+directory.
+
+ On MS-DOS, these functions understand MS-DOS file-name syntax as
+well as Unix syntax. This is so that all the standard Lisp libraries
+can specify file names in Unix syntax and work properly on all systems
+without change. Similarly for other operating systems.
+
+* Menu:
+
+* File Name Components:: The directory part of a file name, and the rest.
+* Directory Names:: A directory's name as a directory
+ is different from its name as a file.
+* Relative File Names:: Some file names are relative to a current directory.
+* File Name Expansion:: Converting relative file names to absolute ones.
+* Unique File Names:: Generating names for temporary files.
+* File Name Completion:: Finding the completions for a given file name.
+* User Name Completion:: Finding the completions for a given user name.
+
+\1f
+File: lispref.info, Node: File Name Components, Next: Directory Names, Up: File Names
+
+File Name Components
+--------------------
+
+ The operating system groups files into directories. To specify a
+file, you must specify the directory and the file's name within that
+directory. Therefore, XEmacs considers a file name as having two main
+parts: the "directory name" part, and the "nondirectory" part (or "file
+name within the directory"). Either part may be empty. Concatenating
+these two parts reproduces the original file name.
+
+ On Unix, the directory part is everything up to and including the
+last slash; the nondirectory part is the rest.
+
+ For some purposes, the nondirectory part is further subdivided into
+the name proper and the "version number". On Unix, only backup files
+have version numbers in their names.
+
+ - Function: file-name-directory filename
+ This function returns the directory part of FILENAME (or `nil' if
+ FILENAME does not include a directory part). On Unix, the
+ function returns a string ending in a slash.
+
+ (file-name-directory "lewis/foo") ; Unix example
+ => "lewis/"
+ (file-name-directory "foo") ; Unix example
+ => nil
+
+ - Function: file-name-nondirectory filename
+ This function returns the nondirectory part of FILENAME.
+
+ (file-name-nondirectory "lewis/foo")
+ => "foo"
+ (file-name-nondirectory "foo")
+ => "foo"
+
+ - Function: file-name-sans-versions filename &optional
+ keep-backup-version
+ This function returns FILENAME without any file version numbers,
+ backup version numbers, or trailing tildes.
+
+ If KEEP-BACKUP-VERSION is non-`nil', we do not remove backup
+ version numbers, only true file version numbers.
+
+ (file-name-sans-versions "~rms/foo.~1~")
+ => "~rms/foo"
+ (file-name-sans-versions "~rms/foo~")
+ => "~rms/foo"
+ (file-name-sans-versions "~rms/foo")
+ => "~rms/foo"
+
+ - Function: file-name-sans-extension filename
+ This function returns FILENAME minus its "extension," if any. The
+ extension, in a file name, is the part that starts with the last
+ `.' in the last name component. For example,
+
+ (file-name-sans-extension "foo.lose.c")
+ => "foo.lose"
+ (file-name-sans-extension "big.hack/foo")
+ => "big.hack/foo"
+
+\1f
+File: lispref.info, Node: Directory Names, Next: Relative File Names, Prev: File Name Components, Up: File Names
+
+Directory Names
+---------------
+
+ A "directory name" is the name of a directory. A directory is a
+kind of file, and it has a file name, which is related to the directory
+name but not identical to it. (This is not quite the same as the usual
+Unix terminology.) These two different names for the same entity are
+related by a syntactic transformation. On Unix, this is simple: a
+directory name ends in a slash, whereas the directory's name as a file
+lacks that slash.
+
+ The difference between a directory name and its name as a file is
+subtle but crucial. When an XEmacs variable or function argument is
+described as being a directory name, a file name of a directory is not
+acceptable.
+
+ The following two functions convert between directory names and file
+names. They do nothing special with environment variable substitutions
+such as `$HOME', and the constructs `~', and `..'.
+
+ - Function: file-name-as-directory filename
+ This function returns a string representing FILENAME in a form
+ that the operating system will interpret as the name of a
+ directory. In Unix, this means appending a slash to the string.
+
+ (file-name-as-directory "~rms/lewis")
+ => "~rms/lewis/"
+
+ - Function: directory-file-name dirname
+ This function returns a string representing DIRNAME in a form that
+ the operating system will interpret as the name of a file. On
+ Unix, this means removing a final slash from the string.
+
+ (directory-file-name "~lewis/")
+ => "~lewis"
+
+ Directory name abbreviations are useful for directories that are
+normally accessed through symbolic links. Sometimes the users recognize
+primarily the link's name as "the name" of the directory, and find it
+annoying to see the directory's "real" name. If you define the link
+name as an abbreviation for the "real" name, XEmacs shows users the
+abbreviation instead.
+
+ If you wish to convert a directory name to its abbreviation, use this
+function:
+
+ - Function: abbreviate-file-name filename &optional hack-homedir
+ This function applies abbreviations from `directory-abbrev-alist'
+ to its argument, and substitutes `~' for the user's home directory.
+
+ If HACK-HOMEDIR is non-`nil', then this also substitutes `~' for
+ the user's home directory.
+
+
+ - Variable: directory-abbrev-alist
+ The variable `directory-abbrev-alist' contains an alist of
+ abbreviations to use for file directories. Each element has the
+ form `(FROM . TO)', and says to replace FROM with TO when it
+ appears in a directory name. The FROM string is actually a
+ regular expression; it should always start with `^'. The function
+ `abbreviate-file-name' performs these substitutions.
+
+ You can set this variable in `site-init.el' to describe the
+ abbreviations appropriate for your site.
+
+ Here's an example, from a system on which file system `/home/fsf'
+ and so on are normally accessed through symbolic links named `/fsf'
+ and so on.
+
+ (("^/home/fsf" . "/fsf")
+ ("^/home/gp" . "/gp")
+ ("^/home/gd" . "/gd"))
+
+\1f
+File: lispref.info, Node: Relative File Names, Next: File Name Expansion, Prev: Directory Names, Up: File Names
+
+Absolute and Relative File Names
+--------------------------------
+
+ All the directories in the file system form a tree starting at the
+root directory. A file name can specify all the directory names
+starting from the root of the tree; then it is called an "absolute"
+file name. Or it can specify the position of the file in the tree
+relative to a default directory; then it is called a "relative" file
+name. On Unix, an absolute file name starts with a slash or a tilde
+(`~'), and a relative one does not.
+
+ - Function: file-name-absolute-p filename
+ This function returns `t' if file FILENAME is an absolute file
+ name, `nil' otherwise.
+
+ (file-name-absolute-p "~rms/foo")
+ => t
+ (file-name-absolute-p "rms/foo")
+ => nil
+ (file-name-absolute-p "/user/rms/foo")
+ => t
+
+\1f
+File: lispref.info, Node: File Name Expansion, Next: Unique File Names, Prev: Relative File Names, Up: File Names
+
+Functions that Expand Filenames
+-------------------------------
+
+ "Expansion" of a file name means converting a relative file name to
+an absolute one. Since this is done relative to a default directory,
+you must specify the default directory name as well as the file name to
+be expanded. Expansion also simplifies file names by eliminating
+redundancies such as `./' and `NAME/../'.
+
+ - Function: expand-file-name filename &optional directory
+ This function converts FILENAME to an absolute file name. If
+ DIRECTORY is supplied, it is the directory to start with if
+ FILENAME is relative. (The value of DIRECTORY should itself be an
+ absolute directory name; it may start with `~'.) Otherwise, the
+ current buffer's value of `default-directory' is used. For
+ example:
+
+ (expand-file-name "foo")
+ => "/xcssun/users/rms/lewis/foo"
+ (expand-file-name "../foo")
+ => "/xcssun/users/rms/foo"
+ (expand-file-name "foo" "/usr/spool/")
+ => "/usr/spool/foo"
+ (expand-file-name "$HOME/foo")
+ => "/xcssun/users/rms/lewis/$HOME/foo"
+
+ Filenames containing `.' or `..' are simplified to their canonical
+ form:
+
+ (expand-file-name "bar/../foo")
+ => "/xcssun/users/rms/lewis/foo"
+
+ `~/' at the beginning is expanded into the user's home directory.
+ A `/' or `~' following a `/'.
+
+ Note that `expand-file-name' does _not_ expand environment
+ variables; only `substitute-in-file-name' does that.
+
+ - Function: file-relative-name filename &optional directory
+ This function does the inverse of expansion--it tries to return a
+ relative name that is equivalent to FILENAME when interpreted
+ relative to DIRECTORY.
+
+ If DIRECTORY is `nil' or omitted, the value of `default-directory'
+ is used.
+
+ (file-relative-name "/foo/bar" "/foo/")
+ => "bar")
+ (file-relative-name "/foo/bar" "/hack/")
+ => "../foo/bar")
+
+ - Variable: default-directory
+ The value of this buffer-local variable is the default directory
+ for the current buffer. It should be an absolute directory name;
+ it may start with `~'. This variable is local in every buffer.
+
+ `expand-file-name' uses the default directory when its second
+ argument is `nil'.
+
+ On Unix systems, the value is always a string ending with a slash.
+
+ default-directory
+ => "/user/lewis/manual/"
+
+ - Function: substitute-in-file-name filename
+ This function replaces environment variable references in FILENAME
+ with the environment variable values. Following standard Unix
+ shell syntax, `$' is the prefix to substitute an environment
+ variable value.
+
+ The environment variable name is the series of alphanumeric
+ characters (including underscores) that follow the `$'. If the
+ character following the `$' is a `{', then the variable name is
+ everything up to the matching `}'.
+
+ Here we assume that the environment variable `HOME', which holds
+ the user's home directory name, has value `/xcssun/users/rms'.
+
+ (substitute-in-file-name "$HOME/foo")
+ => "/xcssun/users/rms/foo"
+
+ After substitution, a `/' or `~' following a `/' is taken to be
+ the start of an absolute file name that overrides what precedes
+ it, so everything before that `/' or `~' is deleted. For example:
+
+ (substitute-in-file-name "bar/~/foo")
+ => "~/foo"
+ (substitute-in-file-name "/usr/local/$HOME/foo")
+ => "/xcssun/users/rms/foo"
+
+\1f
+File: lispref.info, Node: Unique File Names, Next: File Name Completion, Prev: File Name Expansion, Up: File Names
+
+Generating Unique File Names
+----------------------------
+
+ Some programs need to write temporary files. Here is the usual way
+to construct a name for such a file:
+
+ (make-temp-name (expand-file-name NAME-OF-APPLICATION (temp-directory)))
+
+Here we use `(temp-directory)' to specify a directory for temporary
+files--under Unix, it will normally evaluate to `"/tmp/"'. The job of
+`make-temp-name' is to prevent two different users or two different
+processes from trying to use the same name.
+
+ - Function: temp-directory
+ This function returns the name of the directory to use for
+ temporary files. Under Unix, this will be the value of `TMPDIR',
+ defaulting to `/tmp'. On Windows, this will be obtained from the
+ `TEMP' or `TMP' environment variables, defaulting to `/'.
+
+ Note that the `temp-directory' function does not exist under FSF
+ Emacs.
+
+ - Function: make-temp-name prefix
+ This function generates a temporary file name starting with
+ PREFIX. The Emacs process number forms part of the result, so
+ there is no danger of generating a name being used by another
+ process.
+
+ (make-temp-name "/tmp/foo")
+ => "/tmp/fooGaAQjC"
+
+ In addition, this function makes an attempt to choose a name that
+ does not specify an existing file. To make this work, PREFIX
+ should be an absolute file name.
+
+ To avoid confusion, each Lisp application should preferably use a
+ unique PREFIX to `make-temp-name'.
+
+\1f
+File: lispref.info, Node: File Name Completion, Next: User Name Completion, Prev: Unique File Names, Up: File Names
+
+File Name Completion
+--------------------
+
+ This section describes low-level subroutines for completing a file
+name. For other completion functions, see *Note Completion::.
+
+ - Function: file-name-all-completions partial-filename directory
+ This function returns a list of all possible completions for files
+ whose name starts with PARTIAL-FILENAME in directory DIRECTORY.
+ The order of the completions is the order of the files in the
+ directory, which is unpredictable and conveys no useful
+ information.
+
+ The argument PARTIAL-FILENAME must be a file name containing no
+ directory part and no slash. The current buffer's default
+ directory is prepended to DIRECTORY, if DIRECTORY is not absolute.
+
+ File names which end with any member of
+ `completion-ignored-extensions' are not considered as possible
+ completions for PARTIAL-FILENAME unless there is no other possible
+ completion. `completion-ignored-extensions' is not applied to the
+ names of directories.
+
+ In the following example, suppose that the current default
+ directory, `~rms/lewis', has five files whose names begin with `f':
+ `foo', `file~', `file.c', `file.c.~1~', and `file.c.~2~'.
+
+ (file-name-all-completions "f" "")
+ => ("foo" "file~" "file.c.~2~"
+ "file.c.~1~" "file.c")
+
+ (file-name-all-completions "fo" "")
+ => ("foo")
+
+ - Function: file-name-completion partial-filename directory
+ This function completes the file name PARTIAL-FILENAME in directory
+ DIRECTORY. It returns the longest prefix common to all file names
+ in directory DIRECTORY that start with PARTIAL-FILENAME.
+
+ If only one match exists and PARTIAL-FILENAME matches it exactly,
+ the function returns `t'. The function returns `nil' if directory
+ DIRECTORY contains no name starting with PARTIAL-FILENAME.
+
+ File names which end with any member of
+ `completion-ignored-extensions' are not considered as possible
+ completions for PARTIAL-FILENAME unless there is no other possible
+ completion. `completion-ignored-extensions' is not applied to the
+ names of directories.
+
+ In the following example, suppose that the current default
+ directory has five files whose names begin with `f': `foo',
+ `file~', `file.c', `file.c.~1~', and `file.c.~2~'.
+
+ (file-name-completion "fi" "")
+ => "file"
+
+ (file-name-completion "file.c.~1" "")
+ => "file.c.~1~"
+
+ (file-name-completion "file.c.~1~" "")
+ => t
+
+ (file-name-completion "file.c.~3" "")
+ => nil
+
+ - User Option: completion-ignored-extensions
+ `file-name-completion' usually ignores file names that end in any
+ string in this list. It does not ignore them when all the possible
+ completions end in one of these suffixes or when a buffer showing
+ all possible completions is displayed.
+
+ A typical value might look like this:
+
+ completion-ignored-extensions
+ => (".o" ".elc" "~" ".dvi")
+
+\1f
+File: lispref.info, Node: User Name Completion, Prev: File Name Completion, Up: File Names
+
+User Name Completion
+--------------------
+
+ This section describes low-level subroutines for completing a user
+name. For other completion functions, see *Note Completion::.
+
+ - Function: user-name-all-completions partial-username
+ This function returns a list of all possible completions for a
+ user name starting with PARTIAL-USERNAME. The order of the
+ completions is unpredictable and conveys no useful information.
+
+ The argument PARTIAL-USERNAME must be a partial user name
+ containing no tilde character and no slash.
+
+ - Function: user-name-completion partial-username
+ This function completes a user name from PARTIAL-USERNAME. It
+ returns the longest prefix common to all user names that start with
+ PARTIAL-USERNAME.
+
+ If only one match exists and PARTIAL-USERNAME matches it exactly,
+ the function returns `t'. The function returns `nil' if no user
+ name starting with PARTIAL-USERNAME exists.
+
+ - Function: user-name-completion-1 partial-username
+ This function completes the partial user name PARTIAL-USERNAME,
+ like `user-name-completion', differing only in the return value.
+ This function returns the cons of the completion returned by
+ `user-name-completion', and a boolean indicating whether that
+ completion was unique.
+
+\1f
+File: lispref.info, Node: Contents of Directories, Next: Create/Delete Dirs, Prev: File Names, Up: Files
+
+Contents of Directories
+=======================
+
+ A directory is a kind of file that contains other files entered under
+various names. Directories are a feature of the file system.
+
+ XEmacs can list the names of the files in a directory as a Lisp list,
+or display the names in a buffer using the `ls' shell command. In the
+latter case, it can optionally display information about each file,
+depending on the value of switches passed to the `ls' command.
+
+ - Function: directory-files directory &optional full-name match-regexp
+ nosort files-only
+ This function returns a list of the names of the files in the
+ directory DIRECTORY. By default, the list is in alphabetical
+ order.
+
+ If FULL-NAME is non-`nil', the function returns the files'
+ absolute file names. Otherwise, it returns just the names
+ relative to the specified directory.
+
+ If MATCH-REGEXP is non-`nil', this function returns only those
+ file names that contain that regular expression--the other file
+ names are discarded from the list.
+
+ If NOSORT is non-`nil', `directory-files' does not sort the list,
+ so you get the file names in no particular order. Use this if you
+ want the utmost possible speed and don't care what order the files
+ are processed in. If the order of processing is visible to the
+ user, then the user will probably be happier if you do sort the
+ names.
+
+ If FILES-ONLY is the symbol `t', then only the "files" in the
+ directory will be returned; subdirectories will be excluded. If
+ FILES-ONLY is not `nil' and not `t', then only the subdirectories
+ will be returned. Otherwise, if FILES-ONLY is `nil' (the default)
+ then both files and subdirectories will be returned.
+
+ (directory-files "~lewis")
+ => ("#foo#" "#foo.el#" "." ".."
+ "dired-mods.el" "files.texi"
+ "files.texi.~1~")
+
+ An error is signaled if DIRECTORY is not the name of a directory
+ that can be read.
+
+ - Function: insert-directory file switches &optional wildcard
+ full-directory-p
+ This function inserts (in the current buffer) a directory listing
+ for directory FILE, formatted with `ls' according to SWITCHES. It
+ leaves point after the inserted text.
+
+ The argument FILE may be either a directory name or a file
+ specification including wildcard characters. If WILDCARD is
+ non-`nil', that means treat FILE as a file specification with
+ wildcards.
+
+ If FULL-DIRECTORY-P is non-`nil', that means FILE is a directory
+ and switches do not contain `-d', so that the listing should show
+ the full contents of the directory. (The `-d' option to `ls' says
+ to describe a directory itself rather than its contents.)
+
+ This function works by running a directory listing program whose
+ name is in the variable `insert-directory-program'. If WILDCARD is
+ non-`nil', it also runs the shell specified by `shell-file-name',
+ to expand the wildcards.
+
+ - Variable: insert-directory-program
+ This variable's value is the program to run to generate a
+ directory listing for the function `insert-directory'.
+
+\1f
+File: lispref.info, Node: Create/Delete Dirs, Next: Magic File Names, Prev: Contents of Directories, Up: Files
+
+Creating and Deleting Directories
+=================================
+
+ Most XEmacs Lisp file-manipulation functions get errors when used on
+files that are directories. For example, you cannot delete a directory
+with `delete-file'. These special functions exist to create and delete
+directories.
+
+ - Command: make-directory dirname &optional parents
+ This function creates a directory named DIRNAME. Interactively,
+ the default choice of directory to create is the current default
+ directory for file names. That is useful when you have visited a
+ file in a nonexistent directory.
+
+ Non-interactively, optional argument PARENTS says whether to
+ create parent directories if they don't exist. (Interactively, this
+ always happens.)
+
+ - Command: delete-directory dirname
+ This function deletes the directory named DIRNAME. The function
+ `delete-file' does not work for files that are directories; you
+ must use `delete-directory' in that case.
+
+\1f