From a0cf410a802228f80106e3489d7f6172d79fc9b6 Mon Sep 17 00:00:00 2001
From: Simon Michael <simon@joyful.com>
Date: Thu, 6 Mar 2025 16:36:54 -1000
Subject: [PATCH] ;doc:run, repl: updates

---
 hledger/Hledger/Cli/Commands/Repl.md | 29 ++++++++++++++++++++++------
 hledger/Hledger/Cli/Commands/Run.md  | 13 +++++++++----
 2 files changed, 32 insertions(+), 10 deletions(-)

diff --git a/hledger/Hledger/Cli/Commands/Repl.md b/hledger/Hledger/Cli/Commands/Repl.md
index fd7ed2405..01929d68b 100644
--- a/hledger/Hledger/Cli/Commands/Repl.md
+++ b/hledger/Hledger/Cli/Commands/Repl.md
@@ -26,6 +26,7 @@ The command syntax is the same as with `run`:
 - type `exit` or `quit` or control-D to exit the REPL.
 
 While it is running, the REPL remembers your command history, and you can navigate in the usual ways:
+
 - Keypad or Emacs navigation keys to edit the current command line
 - UP/DOWN or control-P/control-N to step back/forward through history
 - control-R to search for a past command, etc.
@@ -37,8 +38,6 @@ You can type control-C to cancel a long-running command (but only once; typing i
 
 And in most shells you can type control-Z to exit temporarily to the shell (and `fg` to return to the REPL).
 
-### Caveats
-
 You may find some differences in behaviour between `run` command lines and normal hledger command lines.
 For example, in the REPL,
 
@@ -49,11 +48,29 @@ For example, in the REPL,
 
 ### Examples
 
-Start the REPL:
+Start the REPL and enter some commands:
 ```cli
-hledger repl
+$ hledger repl 
+Enter hledger commands. To exit, enter 'quit' or 'exit', or send EOF.
+% stats
+Main file           : .../2025.journal
+...
+% stats -f 2024/2024.journal 
+Main file           : .../2024.journal
+...
+% stats
+Main file           : .../2025.journal
+...
 ```
-or
+
+or:
 ```cli
-hledger repl -f some.journal
+$ hledger repl -f some.journal
+Enter hledger commands. To exit, enter 'quit' or 'exit', or send EOF.
+% bs
+...
+% print -b 'last week'
+...
+% bs -f other.journal
+...
 ```
diff --git a/hledger/Hledger/Cli/Commands/Run.md b/hledger/Hledger/Cli/Commands/Run.md
index 259224757..ff9c0e97c 100644
--- a/hledger/Hledger/Cli/Commands/Run.md
+++ b/hledger/Hledger/Cli/Commands/Run.md
@@ -38,8 +38,6 @@ If that gives an error, use `#!/usr/bin/env -S hledger run`.
 
 It's ok to use the `run` command recursively within a command script.
 
-### Caveats
-
 You may find some differences in behaviour between `run` command lines and normal hledger command lines.
 For example, with `run`,
 
@@ -48,7 +46,7 @@ For example, with `run`,
 
 ### Examples
 
-Run commands specified on the command line:
+Run commands from the command line:
 ```cli
 hledger -f some.journal run -- balance assets --depth 2 -- balance liabilities -f /some/other.journal --depth 3 --transpose -- stats
 ```
@@ -59,8 +57,9 @@ Run commands from standard input:
 (echo "files"; echo "stats") | hledger -f some.journal run
 ```
 
-Provide commands as a runnable script:
+Run commands as a script:
 ```cli
+$ cat report
 #!/usr/bin/env -S hledger run -f some.journal
 
 echo "List of accounts in some.journal"
@@ -75,3 +74,9 @@ balance liabilities -f /some/other.journal --depth 3 --transpose
 echo "Commands from another.script, applied to another.journal"
 run -f another.journal another.script
 ```
+```cli
+$ chmod +x report
+$ ./report
+List of accounts in some.journal
+...
+```