Update the README
authorNeil Mitchell <ndmitchell@gmail.com>
Sat, 18 Oct 2014 19:34:04 +0000 (20:34 +0100)
committerNeil Mitchell <ndmitchell@gmail.com>
Sat, 18 Oct 2014 19:34:04 +0000 (20:34 +0100)
README.md

index da7eb55..0063212 100644 (file)
--- a/README.md
+++ b/README.md
@@ -1,62 +1,9 @@
-System.FilePath  [![Build Status](https://travis-ci.org/haskell/filepath.svg)](https://travis-ci.org/haskell/filepath)
-===============
+# FilePath [![Hackage version](https://img.shields.io/hackage/v/filepath.svg?style=flat)](http://hackage.haskell.org/package/filepath) [![Build Status](http://img.shields.io/travis/haskell/filepath.svg?style=flat)](https://travis-ci.org/haskell/filepath)
 
-I have written a `System.FilePath` module in part based on the one in
-Yhc, and in part based on the one in Cabal (thanks to Lemmih). The aim
-is to try and get this module into the base package, as `FilePath`s
-are something many programs use, but its all too easy to hack up a
-little function that gets it right most of the time on most platforms,
-and there lies a source of bugs.
+This package provides functionality for manipulating `FilePath` values. It provides three modules:
 
-This module is Posix (Linux) and Windows capable - just import
-`System.FilePath` and it will pick the right one. Of course, if you
-demand Windows paths on all OSes, then `System.FilePath.Windows` will
-give you that (same with Posix). Written in Haskell 98 with
-Hierarchical Modules.
+* [`System.FilePath.Posix`](http://hackage.haskell.org/package/filepath/docs/System-FilePath-Posix.html) manipulates POSIX/Linux style `FilePath` values (with `/` as the path separator).
+* [`System.FilePath.Windows`](http://hackage.haskell.org/package/filepath/docs/System-FilePath-Windows.html) manipulates Windows style `FilePath` values (with either `/` or `\` as the path separator, and dealing with drives).
+* [`System.FilePath`](http://hackage.haskell.org/package/filepath/docs/System-FilePath.html) which is an alias for the module appropriate to your platform.
 
-If you go to the 
-[Haddock](http://hackage.haskell.org/package/filepath/docs/System-FilePath.html)
-page, there are a few little examples at the top of the re-exported module.
-
-
-Acknowledgments
----------------
-
-Thanks to Marc Webber, shapr, David House, Lemmih, others...
-
-
-Competitors
------------
-
-`System.FilePath` from Cabal, by Lemmih `FilePath.hs` and
-`NameManip.hs` from MissingH
-
-The one from Cabal and `FilePath.hs` in MissingH are both very
-similar, I stole lots of good ideas from those two.
-
-`NameManip.hs` seems to be more unix specific, but all functions in
-that module have equivalents in this new `System.FilePath` module.
-
-Hopefully this new module can be used without noticing any lost
-functions, and certainly adds new features/functions to the table.
-
-
-Should `FilePath` be an abstract data type?
--------------------------------------------
-
-The answer for this library is no. This is a deliberate design decision.
-
-In Haskell 98 the definition is `type FilePath = String`, and all
-functions operating on `FilePath`s, i.e. `readFile`/`writeFile` etc
-take `FilePath`s. The only way to introduce an abstract type is to
-provide wrappers for these functions or casts between `String`s and
-`FilePathAbstract`s.
-
-There are also additional questions as to what constitutes a
-`FilePath`, and what is just a pure `String`. For example,
-"/path/file.ext" is a `FilePath`. Is "/" ? "/path" ? "path" ?
-"file.ext" ? ".ext" ? "file" ?
-
-With that being accepted, it should be trivial to write
-`System.FilePath.ByteString` which has the same interface as
-`System.FilePath` yet operates on `ByteString`s.
+All modules provide the same API, and the same documentation (calling out differences on different platforms).