Update README.md

README.md

@@ -3,6 +3,8 @@ haskell source code formatter
 
 ![Output sample](https://github.com/lspitzner/brittany/raw/master/brittany-sample.gif)
 
+(see another demonstration in [Showcase.md](Showcase.md))
+
 This project's goals roughly are to:
 
 - Be idempotent (this also directly ensures that only valid haskell is
@@ -14,15 +16,16 @@ This project's goals roughly are to:
 - Be clever about aligning things horizontally.
 - Have linear complexity in the size of the input.
 
-At this point, these goals are completed to different degrees. It is not
+At this point, these goals are completed to different degrees.
-ensured that only syntactically valid haskell is produced (yet), and coverage
+Currently, only type-signatures and function/value bindings are processed;
-of the project's testsuite is rather limited. By using ghc-exactprint as the
+other module elements (data-decls, classes, instances, imports/exports etc.) are not
-parser, brittany supports full ghc syntax including extensions, but many of the
-more obscure cases are not handled yet. More importantly, only type-signatures
-and function/value bindings are processed; other module elements (data-decls,
-classes, instances, imports/exports etc.) are not
 transformed in any way; this extends to e.g. bindings inside class instance
 definitions - they won't be touched (yet).
+By using ghc-exactprint as the parser, brittany supports full ghc syntax including
+extensions, but many of the less common syntactic elements (even of 2010 haskell) are
+not handled.
+There are cases where comments are not re-inserted properly (leading to an error or
+to affected comments being placed at a different location than in the input).
 
 The current algorithm is rather clever about horizontal space while still being
 linear in the size of the input (although the constant factor is not small).
@@ -33,18 +36,34 @@ linear in the size of the input (although the constant factor is not small).
 - `-XCPP` is not officially supported (yet).
 - ~~Some commandline flags mentioned in the help don't work yet (and won't even
   be parsed correctly.)~~ (fixed in 0.4.0.0)
-- ~~Creates a `brittany.yaml` config file _in the current directory_. I am aware
+- ~~Creates a `brittany.yaml` config file _in the current directory_.~~
-  that this behaviour is not optimal.~~ (fixed in 0.5.0.0; now creates user
+  (fixed in 0.5.0.0; now creates user config file in `~/.brittany`;
-  config file in `~/.brittany`; still reads `brittany.conf` in current dir if
+  still reads `brittany.yaml` in current dir if present.)
-  present.)
+- ~~Currently some unhandled syntactical constructs don't raise errors~~
-- Currently some unhandled syntactical constructs don't raise errors; in such
+  (fixed in 0.6.0.0)
-  cases the output will contain ghc-exactprint'ed code and some debugging
-  comment. This could easily make the output invalid haskell.
 - There are cases where comments are not copied to the output (this will
   be detected and the user will get an error); there are other cases where
   comments are moved slightly; there are also cases where comments result in
   wonky newline insertion (although this should be a purely aesthetic issue.)
 
+# Building
+
+(This does not cover _installation_. TODO)
+
+~~~~
+mkdir brittany-project
+cd brittany-project/
+git clone https://github.com/lspitzner/butcher.git
+git clone https://github.com/lspitzner/data-tree-print.git
+git clone https://github.com/lspitzner/ghc-exactprint.git
+git clone https://github.com/lspitzner/brittany.git
+cat > cabal.project <<EOF
+packages: data-tree-print butcher ghc-exactprint brittany
+EOF
+# cabal new-configure -w $PATH_TO_GHC_8
+cabal new-build brittany/
+~~~~
+
 # Usage
 
 - Currently one mode of operation: Transform a single module. By default read