confused about the use of the %doc directive

[rpjday <rpjday mindspring com>]

  i was reading a tutorial at ibm's developerworks web site
on simple RPM construction, and it mentioned using a %doc
directive in the %files section to add documentation files.
 
  specifically, it stated that, if you give just a simple
unqualified filename, it will look for a file of that name
in the build directory, and assume you want to install that
file (and others like it) in the directory
/usr/share/doc/%{name}-%{version}.

  so, for example, if i have the simple line

  %doc README

that file will be placed automatically in the above directory.

  but what's confusing is that the build process looks for this
file in the *build* directory which, in my case if i'm building
RPMs under my home directory, might be /home/rpjday/RPM/BUILD.

  however, i might be using this BUILD directory as the build
root of several RPMs, so i might have subdirectories such as
pkg1-root, pkg2-root and so on as subdirectories of BUILD.
i would have thought the build process would look for a README
file in the appropriate build root directory, *not* in the 
overall BUILD directory, for which there can obviously be only
one README with all packages competing for that single file.

  is this correct?  i just tested it and it seems to be the
case.  this makes no sense to me.  can someone explain this?

rday

-- 
Robert P. J. Day
Eno River Technologies, Chapel Hill NC
Unix, Linux and Open Source corporate training