docs update

Author: DannyBen

README.md

@@ -21,12 +21,14 @@ and back them with shell step definitions:
 
 ```bash
 @When I run '{command}'
-run "$command"
+  run "$command"
 
 @Then the output should include '{text}'
-[[ "$LAST_STDOUT" == *"$text"* ]]
+  [[ "$LAST_STDOUT" == *"$text"* ]]
 ```
 
+Indenting the step body is recommended for readability, but optional.
+
 ## Install
 
 ### Installing using the setup script
@@ -166,10 +168,10 @@ loads step definitions. You can rename it with `SHELLKIN_SUPPORT_FILE`.
 
 ```bash
 @When I run '{command}'
-run "$command"
+  run "$command"
 
 @Then the output should include '{text}'
-[[ "$LAST_STDOUT" == *"$text"* ]]
+  [[ "$LAST_STDOUT" == *"$text"* ]]
 ```
 
 Each step definition starts with a header line:
@@ -182,13 +184,14 @@ Each step definition starts with a header line:
 
 The lines that follow are the step body and are executed when the step
 matches.
+Indenting the body is recommended for readability, but optional.
 
 Definition headers can use named tokens in braces. When a step matches, each
 token becomes an exported shell variable available to the body:
 
 ```bash
 @Then the file '{path}' should exist
-[[ -f "$path" ]]
+  [[ -f "$path" ]]
 ```
 
 Token names must start with a letter or underscore, and may contain letters,
@@ -207,7 +210,7 @@ assertions.
 
 ```bash
 @When I run '{command}'
-run "$command"
+  run "$command"
 ```
 
 `run` always returns success, even if the command fails. Inspect the captured
@@ -219,7 +222,7 @@ Use `fail` to fail the current step with an optional custom message.
 
 ```bash
 @Then the output should include '{text}'
-[[ "$LAST_STDOUT" == *"$text"* ]] || fail "invalid output detected"
+  [[ "$LAST_STDOUT" == *"$text"* ]] || fail "invalid output detected"
 ```
 
 ### `defer`
@@ -229,11 +232,11 @@ finishes.
 
 ```bash
 @Given I am in a temp directory
-old_pwd=$PWD
-temp_dir=$(mktemp -d)
-cd "$temp_dir"
-defer cd "$old_pwd"
-defer rm -rf "$temp_dir"
+  old_pwd=$PWD
+  temp_dir=$(mktemp -d)
+  cd "$temp_dir"
+  defer cd "$old_pwd"
+  defer rm -rf "$temp_dir"
 ```
 
 Deferred actions are scenario-scoped, run after both passing and failing
@@ -254,9 +257,14 @@ Example:
 
 ```bash
 @Then the output should match
-[[ "$LAST_STDOUT" == "$DOC_STRING" ]]
+  [[ "$LAST_STDOUT" == "$DOC_STRING" ]]
 ```
 
+## Examples
+
+For real-world examples, see this repository's [features](features) directory
+and the [rush features](https://github.com/DannyBen/rush/tree/master/features).
+
 ## Uninstalling
 
 If you used the setup script, you can run this uninstall script:

doc/shellkin-stepdefs.5

@@ -36,17 +36,19 @@ The step body is plain shell code.
 .IP
 .EX
 \(atWhen I run \(aq{command}\(aq
-run \(dq$command\(dq
+  run \(dq$command\(dq
 .EE
 .PP
+Indenting the body is recommended for readability, but optional.
+.PP
 Each definition continues until the next valid step header or the end of
 the file.
 .SS Tokens
 Patterns may contain named tokens in braces.
 .IP
 .EX
 \(atThen the file \(aq{path}\(aq should exist
-\f[B][[\f[R] \-f \(dq$path\(dq \f[B]]]\f[R]
+  \f[B][[\f[R] \-f \(dq$path\(dq \f[B]]]\f[R]
 .EE
 .PP
 When the step matches, each token is exported as a shell variable for
@@ -60,7 +62,7 @@ Run a shell command and capture its result for later assertions.
 .IP
 .EX
 \(atWhen I run \(aq{command}\(aq
-run \(dq$command\(dq
+  run \(dq$command\(dq
 .EE
 .PP
 The \f[B]run\f[R] helper always returns success, even when the command
@@ -70,18 +72,18 @@ Fail the current step with an optional custom message.
 .IP
 .EX
 \(atThen the output should include \(aq{text}\(aq
-\f[B][[\f[R] \(dq$LAST_STDOUT\(dq == *\(dq$text\(dq* \f[B]]]\f[R] \f[B]||\f[R] fail \(dqinvalid output detected\(dq
+  \f[B][[\f[R] \(dq$LAST_STDOUT\(dq == *\(dq$text\(dq* \f[B]]]\f[R] \f[B]||\f[R] fail \(dqinvalid output detected\(dq
 .EE
 .SS defer
 Register cleanup code to run when the current scenario finishes.
 .IP
 .EX
 \(atGiven I am in a temp directory
-old_pwd=$PWD
-temp_dir=$(mktemp \-d)
-cd \(dq$temp_dir\(dq
-defer cd \(dq$old_pwd\(dq
-defer rm \-rf \(dq$temp_dir\(dq
+  old_pwd=$PWD
+  temp_dir=$(mktemp \-d)
+  cd \(dq$temp_dir\(dq
+  defer cd \(dq$old_pwd\(dq
+  defer rm \-rf \(dq$temp_dir\(dq
 .EE
 .PP
 Deferred actions are scoped to the current scenario.
@@ -117,7 +119,7 @@ Then the output should match
 .IP
 .EX
 \(atThen the output should match
-\f[B][[\f[R] \(dq$LAST_STDOUT\(dq == \(dq$DOC_STRING\(dq \f[B]]]\f[R]
+  \f[B][[\f[R] \(dq$LAST_STDOUT\(dq == \(dq$DOC_STRING\(dq \f[B]]]\f[R]
 .EE
 .SH EXAMPLE
 .IP
@@ -131,16 +133,16 @@ temp_workspace() \f[B]{\f[R]
 .IP
 .EX
 \(atGiven I am in a temp directory
-old_pwd=$PWD
-temp_workspace
-defer cd \(dq$old_pwd\(dq
-defer rm \-rf \(dq$temp_dir\(dq
+  old_pwd=$PWD
+  temp_workspace
+  defer cd \(dq$old_pwd\(dq
+  defer rm \-rf \(dq$temp_dir\(dq
 
 \(atWhen I run \(aq{command}\(aq
-run \(dq$command\(dq
+  run \(dq$command\(dq
 
 \(atThen the file \(aq{path}\(aq should exist
-\f[B][[\f[R] \-f \(dq$path\(dq \f[B]]]\f[R]
+  \f[B][[\f[R] \-f \(dq$path\(dq \f[B]]]\f[R]
 .EE
 .SH SEE ALSO
 \f[B]shellkin\f[R](1), \f[B]shellkin\-test\f[R](1),

doc/shellkin-stepdefs.md

@@ -46,9 +46,11 @@ The step body is plain shell code.
 
 ```bash
 @When I run '{command}'
-run "$command"
+  run "$command"
 ```
 
+Indenting the body is recommended for readability, but optional.
+
 Each definition continues until the next valid step header or the end of the
 file.
 
@@ -59,7 +61,7 @@ Patterns may contain named tokens in braces.
 
 ```bash
 @Then the file '{path}' should exist
-[[ -f "$path" ]]
+  [[ -f "$path" ]]
 ```
 
 When the step matches, each token is exported as a shell variable for use in
@@ -78,7 +80,7 @@ Run a shell command and capture its result for later assertions.
 
 ```bash
 @When I run '{command}'
-run "$command"
+  run "$command"
 ```
 
 The **run** helper always returns success, even when the command fails.
@@ -90,7 +92,7 @@ Fail the current step with an optional custom message.
 
 ```bash
 @Then the output should include '{text}'
-[[ "$LAST_STDOUT" == *"$text"* ]] || fail "invalid output detected"
+  [[ "$LAST_STDOUT" == *"$text"* ]] || fail "invalid output detected"
 ```
 
 defer
@@ -100,11 +102,11 @@ Register cleanup code to run when the current scenario finishes.
 
 ```bash
 @Given I am in a temp directory
-old_pwd=$PWD
-temp_dir=$(mktemp -d)
-cd "$temp_dir"
-defer cd "$old_pwd"
-defer rm -rf "$temp_dir"
+  old_pwd=$PWD
+  temp_dir=$(mktemp -d)
+  cd "$temp_dir"
+  defer cd "$old_pwd"
+  defer rm -rf "$temp_dir"
 ```
 
 Deferred actions are scoped to the current scenario. They run after both
@@ -137,7 +139,7 @@ Then the output should match
 
 ```bash
 @Then the output should match
-[[ "$LAST_STDOUT" == "$DOC_STRING" ]]
+  [[ "$LAST_STDOUT" == "$DOC_STRING" ]]
 ```
 
 EXAMPLE
@@ -153,16 +155,16 @@ temp_workspace() {
 
 ```bash
 @Given I am in a temp directory
-old_pwd=$PWD
-temp_workspace
-defer cd "$old_pwd"
-defer rm -rf "$temp_dir"
+  old_pwd=$PWD
+  temp_workspace
+  defer cd "$old_pwd"
+  defer rm -rf "$temp_dir"
 
 @When I run '{command}'
-run "$command"
+  run "$command"
 
 @Then the file '{path}' should exist
-[[ -f "$path" ]]
+  [[ -f "$path" ]]
 ```
 
 SEE ALSO

features/step_definitions/core.sh

@@ -1,24 +1,26 @@
 @Given I am in a temp directory
-TEMP_DIR=$(mktemp -d)
-cd "$TEMP_DIR"
+  old_pwd="$(pwd)"
+  TEMP_DIR=$(mktemp -d)
+  cd "$TEMP_DIR"
+  defer cd "$old_pwd"
 
 @When I run '{command}'
-PATH="$(pwd):$PATH" run "$command"
+  PATH="$(pwd):$PATH" run "$command"
 
 @Then the file '{path}' should exist
-[[ -f "$path" ]]
+  [[ -f "$path" ]]
 
 @Then the output should include '{text}'
-[[ "$LAST_STDOUT" == *"$text"* ]]
+  [[ "$LAST_STDOUT" == *"$text"* ]]
 
 @Then the error output should include '{text}'
-[[ "$LAST_STDERR" == *"$text"* ]]
+  [[ "$LAST_STDERR" == *"$text"* ]]
 
 @Then the output should match
-[[ "$LAST_STDOUT" == "$DOC_STRING" ]]
+  [[ "$LAST_STDOUT" == "$DOC_STRING" ]]
 
 @Then the exit code should mean success
-[[ "$LAST_EXIT_CODE" -eq 0 ]]
+  [[ "$LAST_EXIT_CODE" -eq 0 ]]
 
 @Then the exit code should mean failure
-[[ "$LAST_EXIT_CODE" -ne 0 ]]
+  [[ "$LAST_EXIT_CODE" -ne 0 ]]