;doc: update command docs

hledger/Hledger/Cli/Commands/Demo.txt

@@ -26,3 +26,5 @@ Examples:
 $ hledger demo               # list available demos
 $ hledger demo 1             # play the first demo at default speed (2x)
 $ hledger demo install -s4   # play the "install" demo at 4x speed
+
+This command is experimental: there aren't many useful demos yet.

hledger/Hledger/Cli/Commands/Register.txt

@@ -132,9 +132,8 @@ will be shown and the program exit code will be non-zero.
 
 Custom register output
 
-register uses the full terminal width by default, except on windows. You
+register normally uses the full terminal width (or 80 columns if it
-can override this by setting the COLUMNS environment variable (not a
+can't detect that). You can override this with the --width/-w option.
-bash shell variable) or by using the --width/-w option.
 
 The description and account columns normally share the space equally
 (about half of (width - 40) each). You can adjust this by adding a
@@ -149,10 +148,7 @@ and some examples:
 
 $ hledger reg                     # use terminal width (or 80 on windows)
 $ hledger reg -w 100              # use width 100
-$ COLUMNS=100 hledger reg         # set with one-time environment variable
-$ export COLUMNS=100; hledger reg # set till session end (or window resize)
 $ hledger reg -w 100,40           # set overall width 100, description width 40
-$ hledger reg -w $COLUMNS,40      # use terminal width, & description width 40
 
 This command also supports the output destination and output format
 options The output formats supported are txt, csv, tsv (Added in 1.32),

hledger/Hledger/Cli/Commands/Repl.txt

@@ -1,49 +1,67 @@
 repl
 
-Runs hledger commands interactively.
+Start an interactive prompt, where you can run any of hledger's
-
+commands. Data files are parsed just once, so the commands run faster.
-This command is EXPERIMENTAL and could change in the future.
 
 Flags:
 no command-specific flags
 
-This command starts a read-eval-print loop (REPL) where you can enter
+This command is experimental and could change in the future.
-commands interactively. To exit REPL, use "exit" or "quit", or send EOF.
 
-It could also accept commands from standard input, if you pipe commands
+hledger repl starts a read-eval-print loop (REPL) where you can enter
-into it.
+commands interactively. As with the run command, each input file (or
+each input file/input options combination) is parsed just once, so
+commands will run more quickly than if you ran them individually at the
+command line.
 
-The commands will run more quickly than if run individually, because the
+Also like run, the input file(s) specified for the repl command will be
-input files would be parsed only once.
+the default input for all interactive commands, you can override this
+temporarily by specifying an -f option in particular commands, and
+commands will not see any changes made to input files (eg by add) until
+you exit and restart the REPL.
 
-Syntax of the commands is intentionally simple: - each line is a single
+The command syntax is the same as with run:
-hledger command - empty lines are skipped - everything after # is
-considered to be a comment and will be ignored, and will not be printed
-out - echo <text> will print out <text>
 
-You can use single or double quotes to quote arguments that need it
+-   enter one hledger command at a time, without the usual hledger first
-('like this' or "like this").
+    word
+-   empty lines and comment text from # to end of line are ignored
+-   use single or double quotes to quote arguments when needed
+-   type exit or quit or control-D to exit the REPL.
 
-Caveats:
+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.
 
--   Repl, like any other command, will load the input file(s) (specified
+The commands and help commands, and the command help flags (CMD --tldr,
-    by LEDGER_FILE or by -f arguments). The contents of those files
+CMD -h/--help, CMD --info, CMD --man), work in the usual way, and can be
-    would be used by all the commands that repl runs. If you want a
+useful.
-    particular command to use a different input file, you can use -f
-    flag for that particular command. This will override (not add) the
-    input for that particular command. All the input files would be
-    cached, and would be read only once.
 
-Examples:
+You can type control-C to cancel a long-running command (but only once;
+typing it a second time will exit the REPL).
 
-To start the REPL:
+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,
+
+-   the command name must be written first, options afterward
+-   full command names or official abbreviations (as in the command
+    list) must be used
+-   options parsing with addon commands might be less flexible than the
+    CLI
+-   the stats command gives false timings, currently
+
+Examples
+
+Start the REPL:
 
 hledger repl
 
 or
 
 hledger repl -f some.journal
-
-To pipe commands into REPL:
-
-(echo "files"; echo "stats") | hledger repl -f some.journal

hledger/Hledger/Cli/Commands/Run.txt

@@ -1,74 +1,78 @@
 run
 
-Runs a sequence of hledger commands on the same input file(s), taking
+Run a sequence of hledger commands, provided as files or command line
-them from the command line or from file(s).
+arguments. Data files are parsed just once, so the commands run faster.
-
-This command is EXPERIMENTAL and syntax could change in the future.
 
 Flags:
 no command-specific flags
 
-The commands will run more quickly than if run individually, because the
+This command is experimental and could change in the future.
-input files would be parsed only once.
 
-"run" has three ways of invocation:
+You can use run in three ways:
 
--   when all positional arguments of "run" are valid file names, "run"
+-   hledger run -- CMD1 -- CMD2 -- CMD3 - read commands from the command
-    will read commands from these files, in order:
+    line, separated by --
-    run -f some.journal file1.txt file2.txt file3.txt.
+-   hledger run SCRIPTFILE1 SCRIPTFILE2 - read commands from one or more
+    files
+-   cat SCRIPTFILE1 | hledger run - read commands from standard input.
 
--   commands could be specified directly on the command line. All
+run first loads the input file(s) specified by LEDGER_FILE or by -f
-    commands (including the very first one) should be preceded by
+options, in the usual way. Then it runs each command in turn, each using
-    argument "--": run -f some.journal -- cmd1 -- cmd2 -- cmd3.
+the same input data. But if you want a particular command to use
+different input, you can specify an -f option within that command. This
+will override (not add to) the default input, just for that command.
 
--   it could also accept commands from standard input, if you don't
+Each input file (more precisely, each combination of input file and
-    provide an positional arguments and pipe commands into it.
+input options) is parsed only once. This means that commands will not
+see any changes made to these files, until the next run. But the
+commands will run more quickly than if run individually (typically about
+twice as fast).
 
-Syntax of the command is intentionally simple: - each line read from a
+Command scripts, whether in a file or written on the command line, have
-file is a single hledger command - empty lines are skipped - everything
+a simple syntax:
-after # is considered to be a comment and will be ignored, and will not
-be printed out - echo <text> will print out <text> - run is a valid
-command to use as well, so you can have run call run if you want to.
 
-You can use single or double quotes to quote arguments that need it
+-   each line may contain a single hledger command and its arguments,
-('like this' or "like this").
+    without the usual hledger first word
+-   empty lines are ignored
+-   text from # to end of line is a comment, and ignored
+-   you can use single or double quotes to quote arguments when needed,
+    as on the command line
+-   these extra commands are available: echo TEXT prints some text, and
+    exit or quit ends the run.
 
-You can use #!/usr/bin/env hledger run in the first line of the file to
+On unix systems you can use #!/usr/bin/env hledger run in the first line
-make it a runnable script. If this complains about "binary hledger run
+of a command file to make it a runnable script. If that gives an error,
-not found", use /usr/bin/env -S hledger run.
+use #!/usr/bin/env -S hledger run.
 
-Caveats:
+It's ok to use the run command recursively within a command script.
 
--   If you meant to provide file name as an argument, but made a mistake
+Caveats
-    and a gave file name that does not exist, "run" will attempt to
-    interpret it as a command.
 
--   Run, like any other command, will load the input file(s) (specified
+You may find some differences in behaviour between run command lines and
-    by LEDGER_FILE or by -f arguments). The contents of those files
+normal hledger command lines. For example, with run,
-    would be used by all the commands that run runs. If you want a
-    particular command to use a different input file, you can use -f
-    flag for that particular command. This will override (not add) the
-    input for that particular command. All the input files would be
-    cached, and would be read only once.
 
-Examples:
+-   the command name must be written first, options afterward
+-   full command names or official abbreviations (as in the command
+    list) must be used
 
-Pipe commands into run, one per line:
+Examples
 
-(echo "files"; echo "stats") | hledger repl -f some.journal
+Run commands specified on the command line:
 
-To provide commands on the command line, separate them with --
+hledger -f some.journal run -- balance assets --depth 2 -- balance liabilities -f /some/other.journal --depth 3 --transpose -- stats
-(including the first one):
-
-hledger run -f some.journal -- balance assets --depth 2 -- balance liabilities -f /some/other.journal --depth 3 --transpose -- stats
 
 This would load some.journal, run balance assets --depth 2 on it, then
 run balance liabilities --depth 3 --transpose on /some/other.journal,
-and finally will run stats on some.journal
+and finally run stats on some.journal
 
-To provide commands in the file, as a runnable scripts:
+Run commands from standard input:
+
+(echo "files"; echo "stats") | hledger -f some.journal run
+
+Provide commands as a runnable script:
 
 #!/usr/bin/env -S hledger run -f some.journal
+
 echo "List of accounts in some.journal"
 accounts