Drake's WORKSPACE uses new_local_repository with relative paths

[jwnimmer-tri]

As discovered by @stonier, per the Bazel docs on new_local_repository, the path argument "must be an absolute path to an existing file or a directory". Drake's //:WORKSPACE has several cases where it uses relative paths into the Drake tree. This currently works fine, but may stop working in the future because it is contrary to the docs. Possibly the needs of #7259 will also demand a different approach.

In any case, we should figure out whether Bazel's code or the docs is correct, and then adjust (or document) our //:WORKSPACE to match that understanding. If indeed its forbidden, then I think we can write our own version of the macro that works in a workspace-relative way. If its supported, then we should document that caveat to prevent future confusion.