Improved documentation of compiler's module search path.
Improved documentation of compiler's module search path.

Added a description of how modules are searched for in the
CHPL_MODULE_PATH section of the man page and put some forward
references to it in the -M and --print-search-path descriptions.

For reference, one of the questions that came up in these past few
changes I did is why compiling a file name subdir/foo.chpl should
result in subdir/ getting added to the search path, so I wanted to
capture that rationale here.

In C, if you have the following files:

        subdir/testit.c   // which #includes "testit.h"
        subdir/testit.h

and you compile 'cc subdir/testit.c', testit.h will be found in spite
of the fact that you didn't add -I to the command-line.  We wanted to
support a similar capability in Chapel.  A motivating example is found
in test/release/examples/hpcc/ra.chpl which relies on other helper
modules in that same directory.  It's convenient to be able to do:

        cd test/release/examples/hpcc && chpl ra.chpl
or:
        chpl test/release/examples/hpcc/ra.chpl

without having to add an explicit module search path to the compiler's
command-line.  

Chapel differs from C, though, in that a 'use' is not the same as
'#include' in that the file isn't processed immediately at that point.
Rather it indicates a need to find a module with the given name at
some point, and moreover, for one module globally with that name
across multiple files.  Contrast this with C where each .c file could
have the same #include line and yet get different header files:

        subdir/testit.c   // which #includes "testit.h"
        subdir/testit.h
        subdir2/testit.c  // which #includes "testit.h"
        subdir2/testit.h

When compiling 'cc subdir/testit.c subdir2/testit.c', each .c file
#includes its respective .h file without any conflict.  But for the
equivalent Chapel case:

        subdir/foo.chpl  // contains 'use bar'
        subdir/bar.chpl  // defines 'module bar'
        subdir2/baz.chpl // contains 'use bar'
        subdir2/bar.chpl // defines 'module bar'

the program will only define a single 'bar module and therefore we
have to have a single, consistent, global module search path.  To that
end, we add all subdirectories named by source files to the module
search path, to get the convenience.  We add -I and $CHPL_MODULE_PATH
directories afterwards in a manner that's intended to be consistent
with the C compiler.




git-svn-id: 88467cb1fb04b8a755be7e1ee1026be4190196ef@19035 3a8e244f-b0f2-452b-bcba-4c88e055c3ca

CoryMcCartan/chapel,hildeth/chapel,hildeth/chapel,hildeth/chapel,CoryMcCartan/chapel,chizarlicious/chapel,sungeunchoi/chapel,CoryMcCartan/chapel,sungeunchoi/chapel,CoryMcCartan/chapel,chizarlicious/chapel,chizarlicious/chapel,hildeth/chapel,chizarlicious/chapel,hildeth/chapel,CoryMcCartan/chapel,CoryMcCartan/chapel,sungeunchoi/chapel,hildeth/chapel,chizarlicious/chapel,hildeth/chapel,chizarlicious/chapel,sungeunchoi/chapel,sungeunchoi/chapel,sungeunchoi/chapel,sungeunchoi/chapel,sungeunchoi/chapel,CoryMcCartan/chapel,chizarlicious/chapel