Improve explanation of `api` vs `implementation` in manual
I've reordered a one or two things and attempted to bring a little more clarity
to this topic in the Java Library Plugin chapter of the user manual. I have
also linked directly to this particular section from the main Building Java
projects chapter so that it gets more attention.