;doc: bin/README: updates

bin/README.md

@@ -9,16 +9,11 @@ This document is the README in the hledger repo's [bin] directory,
 and is also published as [Scripts] on hledger.org.
 
 [Add-on commands](hledger.html#add-on-commands) are executable script files or compiled programs
-named `hledger-*` and installed in $PATH, which show up in hledger's [commands list](hledger.html#commands).
+named `hledger-*`, which show up in hledger's commands list.
+Some notable add-ons are listed [in the hledger manual](https://hledger.org/dev/hledger.html#add-ons). <!--  > PART 4. COMMANDS > ADD-ONS -->
 
-Some larger / separately-maintained add-on commands are listed
+The rest of this page lists smaller scripts and add-ons which are collected in bin/,
-at [hledger manual > PART 4. COMMANDS > ADD-ONS](https://hledger.org/dev/hledger.html#add-ons).
+grouped by how closely they work with hledger:
-
-The rest of this page lists smaller scripts and add-on commands which are collected in bin/.
-These are mostly ready to use, but some are just examples/inspiration for making your own.
-<!-- Below is more about [installing the bin scripts](#installing-the-bin-scripts) and creating your own scripts. Contributions welcome! -->
-
-Scripts vary in how closely they work with hledger; they can be classed as hledger-related, hledger-running and hledger-integrated.
 
 <!-- This page can be viewed on github or hledger.org, so use absolute urls. -->
 [bin]:                https://github.com/simonmichael/hledger/tree/master/bin
@@ -28,7 +23,7 @@ Scripts vary in how closely they work with hledger; they can be classed as hledg
 ## HLEDGER-RELATED
 
 These scripts don't use hledger directly, but are complementary and might be useful to hledger users.
-[plaintextaccounting.org](https://plaintextaccounting.org) has a longer list of non-hledger-specific PTA tools.
+([plaintextaccounting.org](https://plaintextaccounting.org) has a longer list of PTA tools.)
 
 ### paypaljson
 
@@ -41,15 +36,14 @@ downloads the last 30 days of Paypal transactions (requires a free developer acc
 converts `paypaljson`'s output to CSV, with format similar to Paypal's manually-downloaded CSV.
 
 
-
 ## HLEDGER-RUNNING
 
 These scripts run hledger via its CLI,
 eg to help you produce a particular report without needing to remember a complicated command line. 
 They might also consume its text or CSV or JSON output.
-They can be:
+They can be
-- small shell aliases or functions, typically defined in shell startup files (eg ~/.bashrc)
+small shell aliases or functions (typically defined in shell startup files like ~/.bashrc)
-- or individual script files written in shell or some other language, typically kept in ~/bin/ or other directory in $PATH.
+or individual script files written in shell or another language (typically kept in ~/bin/ or elsewhere in $PATH).
 
 ### bashrc
 
@@ -177,19 +171,17 @@ $ hledger plot -- bal -DH ^Assets -2
 
 ## HLEDGER-INTEGRATED
 
-These are Haskell scripts or programs using the hledger-lib API, for maximum power/robustness.
+These Haskell scripts use the hledger-lib API for maximum power and robustness;
-They can use hledger's internal data types and do anything hledger's built-in commands can do.
+they can do anything hledger's built-in commands can do.
 
-### hledger-addon-example
+### hledger-script-example
 
-[`hledger-addon-example.hs`](https://github.com/simonmichael/hledger/blob/master/bin/hledger-addon-example.hs)
+[`hledger-script-example.hs`](https://github.com/simonmichael/hledger/blob/master/bin/hledger-script-example.hs)
-is a starter template for a common type of script: a hledger-integrated add-on command.
+is a template for writing your own hledger-integrated add-on command.
-It has the same structure as most of the other add-ons here:
+It has the same structure as most of the add-ons here:
-- implemented as a stack script for robustness
+- a stack script for robustness
-- provides command line help
+- providing command line help
-- accepts common hledger options
+- accepting common hledger options
-
-Further cleanup and documentation is ongoing.
 
 ### hledger-print-location
 
@@ -269,46 +261,48 @@ helps make subaccount/cost-preserving transfers.
 
 ## HOW TO
 
-### Install the bin scripts
+### Install scripts
 
-These scripts are not automatically installed along with hledger; 
+To use these bin scripts you must ensure they are in your $PATH and runnable:
-if you want them you must download them separately. Here's a suggested method:
+
+- Shell scripts: you may need [bash], or to adapt the scripts for your shell.
+- Python scripts: you'll need python 3 and pip. 
+- Haskell scripts: you'll need stack (<https://www.haskell.org/get-started>).
+Or if you know how, you can make them cabal scripts, or install their dependencies manually and use runghc/ghc.
+
+Here's a suggested install procedure:
 
 ```cli
-# go to wherever you keep financial files
+# Go to wherever you keep financial files:
 $ cd ~/finance
 
-# get the hledger repo (the fast way, without version control)
+# Get the hledger repo
+# the fast way, without version control:
 $ curl -LOJ https://github.com/simonmichael/hledger/archive/refs/heads/master.zip && unzip hledger-master.zip && mv hledger-master hledger
-
+# or the slow way, with version control for easy diffing/updating/contributing
-# (or the slow way, with version control for easy diffing/updating/contributing)
 # git clone https://github.com/simonmichael/hledger
 
-# make a more convenient symlink to the bin directory
+# Make a more convenient symlink to the bin directory:
 $ ln -s hledger/bin
 
-# add the bin directory to your PATH. Eg as a bash user:
+# Add the bin directory to your PATH. Eg as a bash user:
 $ echo "export PATH=$PATH:$PWD/bin" >>~/.bash_profile"
 $ export PATH=$PATH:$PWD/bin
 
-# check that hledger's command list now shows the hledger-* scripts
+# Optionally, compile all haskell scripts for faster startup:
-# (they will be listed with a + prefix):
+$ cd hledger; bin/compile.sh
+
+# Optionally, install the python scripts:
+$ pip install -U hledger-utils
+$ pip install -U git+https://github.com/edkedk99/hledger-fifo
+
+# Check that hledger's command list now includes the bin scripts.
+# Eg "check-fancyassertions" and "swap-dates" should be listed:
 $ hledger
 
-# optionally compile all scripts for faster startup
+
-$ cd hledger; bin/compile.sh
 ```
 
-Scripts with no file extension are mostly [bash] scripts except where noted.
-if you don't want to install bash you might have to adapt them to your shell.
-
-Scripts with a `.hs` file extension are usually [stack scripts], requiring [stack] to run. 
-If you don't want to use stack you can adapt them to be cabal scripts,
-or install their required libraries yourself and run/compile them with suitable runghc/ghc commands.
-Currently these stack scripts mostly use `stack runghc`; this is less robust than `stack script`,
-but allows them to use the latest hledger source tree they are part of.
-See the comments in hledger-check-fancyassertions.hs for more about this.
-
 [bash]: https://www.gnu.org/software/bash
 [stack]: https://haskellstack.org
 [stack]: https://www.fpcomplete.com/haskell/get-started
@@ -318,37 +312,33 @@ See the comments in hledger-check-fancyassertions.hs for more about this.
 
 ### Create a new script
 
-The example scripts follow a template that implements hledger's
+To create a new hledger-integrated script, copy hledger-script-example.hs.
-standard command line options and help, so it's a good idea to use one
+On unix, the new script should be marked executable. This should do it:
-as your starting point. The hledger- naming is not required, but it
-causes scripts to show up in the hledger commands list. On unix,
-your new script should be marked executable. This should do it:
 
-    $ cd hledger
+    $ cd bin
-    $ cp bin/hledger-swap-dates.hs bin/hledger-foo.hs  # and edit, at least the command name and help
+    $ cp hledger-script-example.hs hledger-cmd.hs   # replace cmd with your command name
-    $ stack install string-qq     # ensure any extra script deps are installed
+    # edit hledger-cmd.hs, updating at least the command name and help
-    $ bin/hledger-cmd.hs --help
+    $ stack install safe text     # ensure the script's dependencies are installed
-    foo [OPTIONS]
+    $ hledger-cmd.hs --help
-      My new foo command.
+    cmd [OPTIONS]
+      My new cmd command.
       ...
-    $ stack ghc bin/hledger-cmd.hs
+    $ stack ghc hledger-cmd.hs  # optionally compile for faster startup/durability
-    $ hledger foo -- --help
+    $ hledger cmd -- --help
-    foo [OPTIONS]
+    cmd [OPTIONS]
-      My new foo command.
+      My new cmd command.
       ...
 
 ### Run ghcid on a script
   
-    $ stack install string-qq     # ensure any extra script deps are installed
+    $ stack exec --package 'safe text' -- ghcid hledger-cmd.hs 
-    $ stack exec -- ghcid bin/hledger-foo.hs 
     ...
     Ok, one module loaded.
     All good (1 module, at 10:50:48)
 
 ### Run ghci on a script
 
-    $ stack install string-qq     # ensure any extra script deps are installed
+    $ stack ghci --package 'safe text' hledger-cmd.hs 
-    $ stack ghci bin/hledger-foo.hs 
     ...
     Ok, one module loaded.
     ...
@@ -356,4 +346,4 @@ your new script should be marked executable. This should do it:
 
 ### Learn more about scripting hledger
 
-See [Scripting hledger].
+See [Scripting hledger].