[commit: packages/filepath] master: #50, document makeRelative and explain why it doesn't introduce .. paths (19ff17a)

[git at git.haskell.org]

Repository : ssh://git@git.haskell.org/filepath

On branch  : master
Link       : http://git.haskell.org/packages/filepath.git/commitdiff/19ff17aa5c9df155381381fb3d10dc835587c7ea

>---------------------------------------------------------------

commit 19ff17aa5c9df155381381fb3d10dc835587c7ea
Author: Neil Mitchell <ndmitchell at gmail.com>
Date:   Tue Dec 22 08:02:30 2015 +0000

    #50, document makeRelative and explain why it doesn't introduce .. paths


>---------------------------------------------------------------

19ff17aa5c9df155381381fb3d10dc835587c7ea
 System/FilePath/Internal.hs | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/System/FilePath/Internal.hs b/System/FilePath/Internal.hs
index 52020f6..60903cc 100644
--- a/System/FilePath/Internal.hs
+++ b/System/FilePath/Internal.hs
@@ -729,7 +729,10 @@ equalFilePath a b = f a == f b
             | otherwise = dropTrailingPathSeparator $ normalise x
 
 
--- | Contract a filename, based on a relative path.
+-- | Contract a filename, based on a relative path. Note that the resulting path
+--   will never introduce @..@ paths, as the presence of symlinks means @..\/b@
+--   may not reach @a\/b@ if it starts from @a\/c at . For a worked example see
+--   <http://neilmitchell.blogspot.co.uk/2015/10/filepaths-are-subtle-symlinks-are-hard.html this blog post>.
 --
 --   The corresponding @makeAbsolute@ function can be found in
 --   @System.Directory at .