Update gulp API doc with info on file base

Expand on what file base is and how it affects the relative path calculation. Provide some examples to clarify situations similar to #699.