From 9101845eb0277d4fc9fd2f04bdbd262ea327e18c Mon Sep 17 00:00:00 2001
From: Gabriel Gonzalez <Gabriel439@gmail.com>
Date: Sat, 24 Jan 2015 14:04:05 -0800
Subject: [PATCH] Updated documentation

---
 src/Turtle/Format.hs   |  5 +++--
 src/Turtle/Tutorial.hs | 30 ++++++++++++++++++++++++++++++
 2 files changed, 33 insertions(+), 2 deletions(-)

diff --git a/src/Turtle/Format.hs b/src/Turtle/Format.hs
index b29ffeb..518849b 100644
--- a/src/Turtle/Format.hs
+++ b/src/Turtle/Format.hs
@@ -3,7 +3,8 @@
 {-| Minimalist implementation of type-safe formatted strings, borrowing heavily
     from the implementation of the @formatting@ package.
 
-    This module also provides `repr` for rendering values as `Text`
+    This module also provides `repr` for rendering values as `Text`, as a
+    short-hand for @(format w)@
 
     Example use of this module:
 
@@ -184,4 +185,4 @@ s = makeFormat id
 "(1,2)"
 -}
 repr :: Show a => a -> Text
-repr = pack . show
+repr = format w
diff --git a/src/Turtle/Tutorial.hs b/src/Turtle/Tutorial.hs
index e3fc2b0..577cc05 100644
--- a/src/Turtle/Tutorial.hs
+++ b/src/Turtle/Tutorial.hs
@@ -38,6 +38,9 @@ module Turtle.Tutorial (
 
     -- * System
     -- $system
+
+    -- * String formatting
+    -- $format
     ) where
 
 import Turtle
@@ -609,3 +612,30 @@ import Turtle
 -- Most of the commands in this library do not actually invoke an external
 -- shell.  Instead, they indirectly wrap multiple libraries that provide foreign
 -- bindings to C code for greater performance and portability.
+
+-- $format
+--
+-- This library provides type-safe string formatting utilities, too.  For
+-- example, instead of writing this:
+--
+-- > cmd <> " failed with exit code: " <> repr n
+--
+-- ... you might prefer to write this in @printf@-style:
+--
+-- > format (s%" failed with exit code: "%d) cmd n
+--
+-- Even neater, the compiler will automatically infer the number of arguments
+-- and their types from the format string:
+--
+-- >$ ghci
+-- >Prelude> :set -XOverloadedStrings
+-- >Prelude> import Turtle
+-- >Prelude Turtle> :type format (s%" failed with exit code: "%d)
+-- >format (s%" failed with exit code: "%d) :: Text -> Int -> Text
+--
+-- The compiler correctly infers that this requires on argument of type `Text`
+-- to satisfy the `s` at the beginning of the format string and another
+-- argument of type `Int` to satisfy the `d` at the end of the format string.
+--
+-- See the "Turtle.Format" module for more details if you are interested in this
+-- feature.