;doc: update command docs

hledger/Hledger/Cli/Commands/Repl.txt

@@ -16,9 +16,9 @@ command line.
 
 Also like run, the input file(s) specified for the repl command will be
 the default input for all interactive commands. You can override this
-temporarily by specifying an -f option in particular commands.  But
+temporarily by specifying an -f option in particular commands. But note
-commands will not see any changes made to input files (eg by add) until
+that commands will not see any changes made to input files (eg by add)
-you exit and restart the REPL.
+until you exit and restart the REPL.
 
 The command syntax is the same as with run:
 
@@ -29,11 +29,12 @@ 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: 
+can navigate in the usual ways:
 
--   Keypad or Emacs navigation keys to edit the current command line 
+-   Keypad or Emacs navigation keys to edit the current command line
--   UP/DOWN or control-P/control-N to step back/forward through history 
+-   UP/DOWN or control-P/control-N to step back/forward through history
--   control-R to search for a past command, etc.
+-   control-R to search for a past command
+-   TAB completes file paths.
 
 The commands and help commands, and the command help flags (CMD --tldr,
 CMD -h/--help, CMD --info, CMD --man), work in the usual way, and can be
@@ -45,10 +46,8 @@ typing it a second time will exit the REPL).
 And in most shells you can type control-Z to temporarily exit to the
 shell (and fg to bring it back to foreground and return to the REPL).
 
-Caveats
+You may find some differences in behaviour between repl command lines
-
+and normal hledger command lines. For example, in the REPL,
-You may find some differences in behaviour between REPL command lines and
-normal hledger command lines. For example, in the REPL,
 
 -   the command name must be written first, options afterward
 -   full command names or official abbreviations (as in the command
@@ -59,10 +58,27 @@ normal hledger command lines. For example, in the REPL,
 
 Examples
 
-Start the REPL:
+Start the REPL and enter some commands:
 
-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:
 
-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
+...

hledger/Hledger/Cli/Commands/Run.txt

@@ -46,8 +46,6 @@ 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,
 
@@ -57,7 +55,7 @@ normal hledger command lines. For example, with run,
 
 Examples
 
-Run commands specified on the command line:
+Run commands from the command line:
 
 hledger -f some.journal run -- balance assets --depth 2 -- balance liabilities -f /some/other.journal --depth 3 --transpose -- stats
 
@@ -69,8 +67,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:
 
+$ cat report
 #!/usr/bin/env -S hledger run -f some.journal
 
 echo "List of accounts in some.journal"
@@ -84,3 +83,8 @@ balance liabilities -f /some/other.journal --depth 3 --transpose
 
 echo "Commands from another.script, applied to another.journal"
 run -f another.journal another.script
+
+$ chmod +x report
+$ ./report
+List of accounts in some.journal
+...