bug#11332: 24.1.50; doc of `dired-make-relative'

bug#11332: 24.1.50; doc of `dired-make-relative'

[Drew Adams]

1. The doc string does not say what happens when DIR is nil, which means
that it does not even document the default behavior!
 
The first line of the doc string should stand alone, to some extent.
Here, it says that the name is relative to DIR, which by default is
nil.  So the first line is meaningless.
 
Worse, the doc says that DIR *MUST BE* a directory name.  The default
value is nil, which is not a directory name.
 
It is so simple to say that DIR defaults to the value of
`default-directory'.
 
2. I cannot imagine what is meant by it being impossible to convert
FILE.  What is really meant here - what case are you referring to?
 
3. The doc says that arg FILE is an absolute file name, but it does not
say what happens if it is not.  Is that case treated like the case where
FILE cannot be converted - return FILE?
 
4. Argument IGNORE is not documented.  Can it be removed?  Why not?  Add a
comment to the code about that.  (Presumably it is because `dired-make-relative'
must be usable as a function parameter that accepts a second arg.)

In GNU Emacs 24.1.50.1 (i386-mingw-nt5.1.2600)
 of 2012-04-23 on MARVIN
Bzr revision: 108006
agustin.martin@hispalinux.es-20120423103325-xmra3329elgzhmpc
Windowing system distributor `Microsoft Corp.', version 5.1.2600
Configured using:
 `configure --with-gcc (4.6) --no-opt --enable-checking --cflags
 -ID:/devel/emacs/libs/libXpm-3.5.8/include
 -ID:/devel/emacs/libs/libXpm-3.5.8/src
 -ID:/devel/emacs/libs/libpng-dev_1.4.3-1/include
 -ID:/devel/emacs/libs/zlib-dev_1.2.5-2/include
 -ID:/devel/emacs/libs/giflib-4.1.4-1/include
 -ID:/devel/emacs/libs/jpeg-6b-4/include
 -ID:/devel/emacs/libs/tiff-3.8.2-1/include
 -ID:/devel/emacs/libs/gnutls-3.0.9/include
 -ID:/devel/emacs/libs/libiconv-1.13.1-1-dev/include
 -ID:/devel/emacs/libs/libxml2-2.7.8/include/libxml2'
 

bug#11332: 24.1.50; doc of `dired-make-relative'

[Chong Yidong]

> The doc string does not say what happens when DIR is nil, which means
> that it does not even document the default behavior!

Fixed in trunk.