From 32e77c6d987fec607df2cdbb3cc031503b3c89df Mon Sep 17 00:00:00 2001
From: Waldir Pimenta <waldyrious@gmail.com>
Date: Sat, 6 Mar 2021 14:28:11 +0000
Subject: [PATCH] README improvements

- Add a simpler introductory example
- Rename "Example" section to "Usage"
  and make the two next sections into subsections of it
- Normalize headings to sentence case
- Reword a couple sentences to adjust to the package rename
  (from `PipelessPipes.jl` to `Chain.jl`)
- Add a link to DataFrames.jl
---
 README.md | 31 ++++++++++++++++++++++---------
 1 file changed, 22 insertions(+), 9 deletions(-)

diff --git a/README.md b/README.md
index ddf1c26..b486578 100644
--- a/README.md
+++ b/README.md
@@ -61,7 +61,7 @@ end
 </tr>
 </table>
 
-## Build Status
+## Build status
 
 ![Run tests](https://github.com/jkrumbiegel/Chain.jl/workflows/Run%20tests/badge.svg)
 
@@ -88,11 +88,24 @@ This is very useful to inspect pipeline state during debugging, for example.
 - The state of the pipeline can easily be checked with the `@aside` macro
 - The `begin ... end` block marks very clearly where the macro is applied and works well with auto-indentation
 - Because everything is just lines with separate expressions and not one huge function call, IDEs can show exactly in which line errors happened
-- Pipe is a name defined by Base Julia which can lead to conflicts
+- Pipe (as used in [Pipe.jl](https://github.com/oxinabox/Pipe.jl)) is a name defined by Base Julia, which can lead to conflicts
 
-## Example
+## Usage
 
-An example with a DataFrame:
+A simple example that adds one and squares all elements of a range:
+
+```julia
+julia> @chain 1:3 begin
+         _ .+ 1
+         _ .^ 2
+       end
+3-element Array{Int64,1}:
+  4
+  9
+ 16
+```
+
+An example with a [DataFrame](https://github.com/JuliaData/DataFrames.jl):
 
 ```julia
 using DataFrames, Chain
@@ -107,7 +120,7 @@ result = @chain df begin
 end
 ```
 
-The pipeless block is equivalent to this:
+The equivalent native Julia syntax for the above `@chain` block would be:
 
 ```julia
 result = let
@@ -118,7 +131,7 @@ result = let
 end
 ```
 
-## Alternative one-argument syntax
+### Alternative one-argument syntax
 
 If your initial argument name is long and / or the chain's result is assigned to a long variable, it can look cleaner if the initial value is moved into the chain.
 Here is such a long expression:
@@ -142,7 +155,7 @@ a_long_result_variable_name = @chain begin
 end
 ```
 
-## The `@aside` macro
+### The `@aside` macro
 
 For debugging, it's often useful to look at values in the middle of a pipeline.
 You can use the `@aside` macro to mark expressions that should not pass on their result.
@@ -172,7 +185,7 @@ result = let
 end
 ```
 
-## Nested Chains
+## Nested chains
 
 The `@chain` macro replaces all underscores in the following block, unless it encounters another `@chain` macrocall.
 In that case, the only underscore that is still replaced by the outer macro is the first argument of the inner `@chain`.
@@ -191,7 +204,7 @@ You can use this, for example, in combination with the `@aside` macro if you nee
 end
 ```
 
-## Rewriting Rules
+## Rewriting rules
 
 Here is a list of equivalent expressions, where `_` is replaced by `prev` and the new variable is `next`.
 In reality, each new variable simply gets a new name via `gensym`, which is guaranteed not to conflict with anything else.