diff --git a/CHANGES.md b/CHANGES.md
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -23,8 +23,126 @@
 User-visible changes in the hledger command line tool and library.
 
 
-# 2024-12-09 1.41
+# 2025-03-07 1.42
 
+Fixes
+
+- hledger's default options for the `less` pager no longer include --use-color,
+  which caused older less versions (eg 551) to break. [#2335]
+
+- In balance --budget reports, costs no longer prevent display of percentages. [#2327]
+
+- In the balance command's HTML output, -H/--historical now suppresses the total heading.
+
+- print --help now shows the right default for --round. [#2318]
+
+- close --infer-costs no longer implies the -x/--explicit flag. [#1826]
+
+- add: Account names provided on the command line are no longer ignored. [#2305]
+
+- bs/bse/cf/is no longer show the unsupported --budget option in their help. [#2302]
+
+- The print command now ignores --depth entirely. Previously, a depth
+  limit caused it to show only transactions referencing accounts as
+  deep or deeper than that.
+
+- Week periods beginning in the previous year are now shown correctly.
+  Eg the week beginning 2024-12-30 (which is week 1 of 2025 because the
+  thursday falls in 2025) was previously shown as 2024-W01, and is now shown as 2025-W01.
+  [#2304]
+
+Features
+
+- `run` and `repl` are new commands which run a multiple commands,
+  without re-parsing data, so they run faster.
+  `run` runs a commands from files or provided on the command line,
+  and `repl` provides an interactive prompt with readline-style history.
+  (Dmitry Astapov, Simon Michael, [#2323], [#2328])
+
+- `commands` is a new explicit command for showing the commands list; it's useful in the REPL.
+  With --builtin, it shows only the builtin commands.
+
+- hledger can now read CSV/SSV/TSV data in encodings other than UTF8,
+  using the new `encoding` CSV rule. (Joschua Kesper,  [#2319])
+
+- `if` matchers in CSV rules now allow multiple matchers to be combined on the same line,
+  separated by `&&` (AND) or `&& !` (AND NOT).  This makes `if` tables more expressive.
+  Examples:
+
+  	if %description amazon && %date 2025-02-22
+  	    account2 expenses:books
+
+  	if,account2
+  	%description amazon && %date 2025-02-22, expenses:books
+
+  For consistency, the next-line `&` operator may now also be written as `&&`.
+  (Thomas Miedema, [#2333])
+
+Improvements
+
+- Two more file extensions are now recognised as possible hledger addon
+  commands: `.osh` and `.ysh`.
+
+- Terminal width is now detected more robustly by using the POSIX API.
+  This means eg that register commands use the proper terminal width in more environments,
+  eg when $TERM or $COLUMNS do not have a correct/up-to-date value, and on Windows.
+  hledger no longer uses COLUMNS.
+  (gesh, [#2332, #2340])
+
+- The print command now supports the --invert flag. [#2314]
+
+- --pivot can now also pivot on amount quantity (`amt`),
+  amount cost (`cost`), and/or commodity symbol (`comm` or `cur`).
+
+- imp:close: omit file extension from tag value
+
+- close --migrate has been renamed to close --clopen.
+
+- The close command's start: tag has been renamed to `clopen:`.
+  And its default value now excludes the file extension.
+
+- close --assign's tag has been renamed to `assign:`.
+
+- The roi command is now faster:
+  it no longer checks every day with P directive,
+  and the "one period per report interval" case has been optimised.
+  (Dmitry Astapov)
+
+- Error messages (first line) in the terminal are now shown in red (and bold),
+  and warning messages are shown in yellow,
+  when ANSI codes are supported and permitted.
+
+Docs
+
+- aregister: Drop an inconsistent newline from options help.
+- balance: improve --layout option help.
+- close: doc rewrites
+- shell completions: mention zsh; cleanups
+- cost/lot notations: clarify
+- cost, value reporting: edits
+- Directive effects: fix account types link [#126]
+- commodity styles: fix typo [hledger_site#123]
+- commodity directive: clarify
+- close: mention the balance assertions
+- pager: mention --pager=no
+- Aliases and account types: better troubleshooting command
+- Beancount output: mention limitations: P and balance assignments
+- Balance report output: drop outdated note about --tree and HTML [#1846]
+
+Scripts/addons
+
+API
+
+- Reader's rReadFn has changed type (for the new CSV text encoding feature);
+  it now takes a `Handle` rather than a `Text`, allowing more flexibility.
+
+- lib: add dropRawOpt, cliOptsDropArgs
+
+- lib: showAmountCost(B): drop leading whitespace
+
+
+# 1.41 2024-12-09
+
 Breaking changes
 
 - Accounts named "equity:conversion", "equity:trading", or "equity:trade(s)",
@@ -83,7 +201,7 @@
 
 - In a multi-line comment generated by CSV rules, tags on all lines now work (ie, can be matched).
   Posting dates in comments generated from CSV also now [work](https://hledger.org/hledger.html#comment-field).
-  (#2241)
+  [#2241]
 
 - hledger's bash shell completions are now up to date with the latest CLI.
   [#986]
@@ -228,7 +346,6 @@
 - FODS output: describe the advantages over CSV (Henning Thielemann)
 - Debug output: note that the --debug option doesn't work in config files.
 - bal: improve --layout doc
-- bal: note that tree mode doesn't work in html output [#1846]
 - bal: also mention hledger.css and text encoding in balance doc
 - html: note safari text encoding issue
 - timedot: mention the common journal+timedot file setup [#2238]
diff --git a/Hledger/Cli.hs b/Hledger/Cli.hs
--- a/Hledger/Cli.hs
+++ b/Hledger/Cli.hs
@@ -108,7 +108,6 @@
 import System.Console.CmdArgs.Explicit as CmdArgsWithoutName hiding (Name)
 import System.Environment
 import System.Exit
-import System.FilePath
 import System.Process
 import Text.Megaparsec (optional, takeWhile1P, eof)
 import Text.Megaparsec.Char (char)
@@ -118,6 +117,7 @@
 import Hledger.Cli.CliOptions
 import Hledger.Cli.Conf
 import Hledger.Cli.Commands
+import Hledger.Cli.Commands.Run
 import Hledger.Cli.DocFiles
 import Hledger.Cli.Utils
 import Hledger.Cli.Version
@@ -224,7 +224,7 @@
   usecolor <- useColorOnStdout
   when usecolor setupPager
   -- Search PATH for addon commands. Exclude any that match builtin command names.
-  addons <- hledgerAddons <&> filter (not . (`elem` builtinCommandNames) . dropExtension)
+  addons <- addonCommandNames
 
   ---------------------------------------------------------------
   dbgIO "\n1. Preliminary command line parsing" ()
@@ -239,12 +239,13 @@
   cliargs <- getArgs
     >>= expandArgsAt         -- interpolate @ARGFILEs
     <&> replaceNumericFlags  -- convert -NUM to --depth=NUM
+    <&> argsAddDoubleDash    -- repeat the first -- arg, as a cmdargs workaround
   let
     (clicmdarg, cliargswithoutcmd, cliargswithcmdfirst) = moveFlagsAfterCommand cliargs
     cliargswithcmdfirstwithoutclispecific = dropCliSpecificOpts cliargswithcmdfirst
     (cliargsbeforecmd, cliargsaftercmd) = second (drop 1) $ break (==clicmdarg) cliargs
-  dbgIO "cli args" cliargs
-  dbg1IO "cli args with options moved after command, if any" cliargswithcmdfirst
+  dbgIO  "cli args with preprocessing" cliargs
+  dbg1IO "cli args with preprocessing and options moved after command" cliargswithcmdfirst
   dbgIO "cli command argument found" clicmdarg
   dbgIO "cli args before command"    cliargsbeforecmd
   dbgIO "cli args after command"     cliargsaftercmd
@@ -365,7 +366,16 @@
     infoFlag    = boolopt "info"    rawopts
     manFlag     = boolopt "man"     rawopts
     versionFlag = boolopt "version" rawopts
+    -- ignoredopts    cmd = error' $ cmd ++ " tried to read options but is not supposed to"
+    ignoredjournal cmd = error' $ cmd ++ " tried to read the journal but is not supposed to"
 
+  -- validate opts/args more and convert to CliOpts
+  opts <- rawOptsToCliOpts rawopts >>= \opts0 -> return opts0{progstarttime_=starttime}
+  dbgIO2 "processed opts" opts
+  dbgIO "period from opts" (period_ . _rsReportOpts $ reportspec_ opts)
+  dbgIO "interval from opts" (interval_ . _rsReportOpts $ reportspec_ opts)
+  dbgIO "query from opts & args" (_rsQuery $ reportspec_ opts)
+
   -- Ensure that anything calling getArgs later will see all args, including config file args.
   -- Some things (--color, --debug, some checks in journalFinalise) are detected by unsafePerformIO,
   -- eg in Hledger.Utils.IO.progArgs, which means they aren't be seen in a config file
@@ -385,39 +395,37 @@
     | badcmdprovided -> error' $ "command "++clicmdarg++" is not recognized, run with no command to see a list"
 
     -- 6.4. no command found, nothing else to do - show the commands list
-    | nocmdprovided -> dbgIO1 "no command, showing commands list" () >> printCommandsList prognameandversion addons
+    | nocmdprovided -> do
+        dbgIO1 "no command, showing commands list" ()
+        commands opts (ignoredjournal "commands")
 
     -- 6.5. builtin command found
     | Just (cmdmode, cmdaction) <- mbuiltincmdaction -> do
       let mmodecmdname = headMay $ modeNames cmdmode
       dbgIO1 "running builtin command mode" $ fromMaybe "" mmodecmdname
 
-      -- validate opts/args more and convert to CliOpts
-      opts <- rawOptsToCliOpts rawopts >>= \opts0 -> return opts0{progstarttime_=starttime}
-      dbgIO2 "processed opts" opts
-      dbgIO "period from opts" (period_ . _rsReportOpts $ reportspec_ opts)
-      dbgIO "interval from opts" (interval_ . _rsReportOpts $ reportspec_ opts)
-      dbgIO "query from opts & args" (_rsQuery $ reportspec_ opts)
-      let tldrpagename = maybe "hledger" (("hledger-"<>)) mmodecmdname
-
       -- run the builtin command according to its type
       if
         -- 6.5.1. help/doc flag - show command help/docs
         | helpFlag  -> runPager $ showModeUsage cmdmode ++ "\n"
-        | tldrFlag  -> runTldrForPage tldrpagename
+        | tldrFlag  -> runTldrForPage $ maybe "hledger" (("hledger-"<>)) mmodecmdname
         | infoFlag  -> runInfoForTopic "hledger" mmodecmdname
         | manFlag   -> runManForTopic "hledger"  mmodecmdname
 
         -- 6.5.2. builtin command which should not require or read the journal - run it
-        | cmdname `elem` ["demo","help","test"] ->
-          cmdaction opts $ error' $ cmdname++" tried to read the journal but is not supposed to"
+        | cmdname `elem` ["commands","demo","help","test"] ->
+          cmdaction opts (ignoredjournal cmdname)
 
         -- 6.5.3. builtin command which should create the journal if missing - do that and run it
         | cmdname `elem` ["add","import"] -> do
           ensureJournalFileExists . NE.head =<< journalFilePathFromOpts opts
           withJournalDo opts (cmdaction opts)
 
-        -- 6.5.4. all other builtin commands - read the journal and if successful run the command with it
+        -- 6.5.4. "run" and "repl" need findBuiltinCommands passed to it to avoid circular dependency in the code
+        | cmdname == "run"  -> Hledger.Cli.Commands.Run.run Nothing findBuiltinCommand addons opts
+        | cmdname == "repl" -> Hledger.Cli.Commands.Run.repl findBuiltinCommand addons opts
+
+        -- 6.5.5. all other builtin commands - read the journal and if successful run the command with it
         | otherwise -> withJournalDo opts $ cmdaction opts
 
     -- 6.6. external addon command found - run it,
@@ -481,12 +489,24 @@
     (traceOrLogAt verboseDebugLevel ("cmdargs: parsing " <> desc <> ": " <> show args0))
   -- XXX better error message when cmdargs fails (eg spaced/quoted/malformed flag values) ?
 
--- | cmdargs does not allow flags (options) to appear before the subcommand argument.
--- We prefer to hide this restriction from the user, making the CLI more forgiving.
--- So this tries to move flags, and their values if any, after the command argument.
--- It also returns the (possibly empty) command argument and the other arguments,
--- separately for convenience.
+-- | cmdargs does not allow options to appear before the subcommand argument.
+-- We prefer to hide this restriction from the user, providing a more forgiving CLI.
+-- So this helper tries to move any pre-command flags/options, and their values if any, after the command argument.
+-- If there is a "--"" argument, only the preceding args are rearranged.
+-- To be precise: pre-command options will be moved to the end of the part of the command line preceding the first -- argument.
+-- The pre-command options' relative order will be preserved, but since they may be moved after post-command options,
+-- the overall order of options may change.
+-- XXX moving them right after the command would probably be better.
 --
+-- For convenience of the caller, this currently returns a triple:
+-- (
+--  the command, if one was found (or ""),
+--  the rearranged args without the command,
+--  the command followed by the rearranged args
+-- )
+--
+-- Notes:
+--
 -- Detecting the command argument is tricky because of the flexibility of traditional flag syntax.
 -- Short flags can be joined together, some flags can have a value or no value,
 -- flags and values can be separated by =, a space, or nothing, etc.
@@ -503,31 +523,27 @@
 -- - it begins with a long requires-value flag followed by =; likewise
 -- - it begins with a long optional-value flag followed by =; likewise
 --
--- Notes:
---
--- - This hackery increases the risk of misleading errors, bugs, and confusion.
---   It should be fairly robust now, being aware of all builtin flags.
---   The main tests are in hledger/test/cli/cli.test, but they are not exhaustive.
---
--- - All general and builtin command flags (and their values) will be moved. It's clearer to
---   write command flags after the command, but if not we'll handle it (for greater robustness).
+-- This hackery increases the risk of misleading errors, bugs, and confusion.
+-- It should be fairly robust now, being aware of all builtin flags.
+-- The main tests are in hledger/test/cli/cli.test, but they are not exhaustive.
 --
--- - Long flags should be spelled in full; abbreviated long flags might not get moved.
+-- All general and builtin command flags (and their values) will be moved. It's clearer to
+-- write command flags after the command, but if not we'll handle it (for greater robustness).
 --
--- - Unknown flags (from addons) are assumed to be valueless or have a joined value,
---   and will be moved - but later rejected by cmdargs.
---   Instead these should be written to the right of a "--" argument, which hides them.
+-- Long flags should be spelled in full; abbreviated long flags might not get moved.
 --
--- - XXX Relative order of flags is mostly but not entirely preserved, currently:
---   pre-command flags get moved to the end, after post-command flags. 
+-- Unknown flags (from addons) are assumed to be valueless or have a joined value,
+-- and will be moved - but later rejected by cmdargs.
+-- Instead these should be written to the right of a "--" argument, which hides them.
 --
 moveFlagsAfterCommand :: [String] -> (String, [String], [String])
 moveFlagsAfterCommand args =
-  case moveFlagAndVal (args, []) of
-    ([],as)                      -> ("", as, as)
-    (unmoved@(('-':_):_), moved) -> ("", as, as) where as = unmoved<>moved
-    (cmdarg:unmoved, moved)      -> (cmdarg, as, cmdarg:as) where as = unmoved<>moved
+  case moveFlagAndVal (as1, []) of
+    ([],as1')                    -> ("", as, as) where as = as1' <> as2
+    (unmoved@(('-':_):_), moved) -> ("", as, as) where as = unmoved <> moved <> as2
+    (cmdarg:unmoved, moved)      -> (cmdarg, as, cmdarg:as) where as = unmoved <> moved <> as2
   where
+    (as1, as2) = break (== "--") args
     -- Move the next argument to the end if it is a movable flag, along with its subsequent value argument if any.
     moveFlagAndVal :: ([String], [String]) -> ([String], [String])
     moveFlagAndVal ((a:b:cs), moved) =
diff --git a/Hledger/Cli/CliOptions.hs b/Hledger/Cli/CliOptions.hs
--- a/Hledger/Cli/CliOptions.hs
+++ b/Hledger/Cli/CliOptions.hs
@@ -49,7 +49,6 @@
   showModeUsage,
   withAliases,
   likelyExecutablesInPath,
-  hledgerExecutablesInPath,
 
   -- * CLI options
   CliOpts(..),
@@ -58,6 +57,8 @@
   getHledgerCliOpts,
   getHledgerCliOpts',
   rawOptsToCliOpts,
+  cliOptsDropArgs,
+  argsAddDoubleDash,
   outputFormats,
   defaultOutputFormat,
   CommandHelpStr,
@@ -67,18 +68,17 @@
   -- * CLI option accessors
   -- | These do the extra processing required for some options.
   journalFilePathFromOpts,
+  journalFilePathFromOptsNoDefault,
   rulesFilePathFromOpts,
   outputFileFromOpts,
   outputFormatFromOpts,
   defaultWidth,
-  -- widthFromOpts,
   replaceNumericFlags,
   ensureDebugFlagHasVal,
   -- | For register:
   registerWidthsFromOpts,
 
   -- * Other utils
-  hledgerAddons,
   topicForMode,
 
 --  -- * Convenience re-exports
@@ -91,9 +91,8 @@
 import Control.Monad (when)
 import Data.Char
 import Data.Default
-import Data.Either (isRight)
-import Data.List.Extra (groupSortOn, intercalate, isInfixOf, nubSort)
-import qualified Data.List.NonEmpty as NE (NonEmpty, fromList, head, nonEmpty)
+import Data.List.Extra (intercalate, isInfixOf, nubSort)
+import qualified Data.List.NonEmpty as NE (NonEmpty, fromList, nonEmpty)
 import Data.List.Split (splitOn)
 import Data.Maybe
 --import Data.String.Here
@@ -106,9 +105,6 @@
 import System.Console.CmdArgs hiding (Default,def)
 import System.Console.CmdArgs.Explicit
 import System.Console.CmdArgs.Text
-#ifndef mingw32_HOST_OS
-import System.Console.Terminfo
-#endif
 import System.Directory
 import System.Environment
 import System.Exit (exitSuccess)
@@ -551,9 +547,8 @@
     ,no_new_accounts_ :: Bool           -- add
     ,width_           :: Maybe String   -- ^ the --width value provided, if any
     ,available_width_ :: Int            -- ^ estimated usable screen width, based on
-                                        -- 1. the COLUMNS env var, if set
-                                        -- 2. the width reported by the terminal, if supported
-                                        -- 3. the default (80)
+                                        -- 1. the width reported by the terminal, if supported
+                                        -- 2. the default (80)
     ,progstarttime_   :: POSIXTime      -- system POSIX time at start
  } deriving (Show)
 
@@ -616,15 +611,8 @@
   usecolor <- useColorOnStdout
   let iopts = rawOptsToInputOpts day usecolor postingaccttags rawopts
   rspec <- either error' pure $ rawOptsToReportSpec day usecolor rawopts  -- PARTIAL:
-  mcolumns <- readMay <$> getEnvSafe "COLUMNS"
-  mtermwidth <-
-#ifdef mingw32_HOST_OS
-    return Nothing
-#else
-    (`getCapability` termColumns) <$> setupTermFromEnv
-    -- XXX Throws a SetupTermError if the terminfo database could not be read, should catch
-#endif
-  let availablewidth = NE.head $ NE.fromList $ catMaybes [mcolumns, mtermwidth, Just defaultWidth]  -- PARTIAL: fromList won't fail because non-null list
+  mtermwidth <- getTerminalWidth
+  let availablewidth = fromMaybe defaultWidth mtermwidth
   return defcliopts {
               rawopts_         = rawopts
              ,command_         = command
@@ -641,6 +629,18 @@
              ,available_width_ = availablewidth
              }
 
+-- | Drop the arguments ("args") from this CliOpts' rawopts field.
+cliOptsDropArgs :: CliOpts -> CliOpts
+cliOptsDropArgs copts@CliOpts{rawopts_} = copts{rawopts_ = dropRawOpt "args" rawopts_}
+
+-- | cmdargs eats the first double-dash (--) argument when parsing a command line,
+-- which causes problems for the run and repl commands.
+-- Sometimes we work around this by duplicating that first -- argument.
+-- This doesn't break anything that we know of yet.
+argsAddDoubleDash args'
+  | "--" `elem` args' = let (as,bs) = break (=="--") args' in as <> ["--"] <> bs
+  | otherwise = args'
+
 -- | A helper for addon commands: this parses options and arguments from
 -- the current command line using the given hledger-style cmdargs mode,
 -- and returns a CliOpts. Or, with --help or -h present, it prints
@@ -706,12 +706,20 @@
 -- File paths can have a READER: prefix naming a reader/data format.
 journalFilePathFromOpts :: CliOpts -> IO (NE.NonEmpty String)
 journalFilePathFromOpts opts = do
-  f <- defaultJournalPath
+  mbpaths <- journalFilePathFromOptsNoDefault opts
+  case mbpaths of
+    Just paths -> return paths
+    Nothing -> do
+      f <- defaultJournalPath
+      return $ NE.fromList [f]
+
+-- | Like journalFilePathFromOpts, but does not use defaultJournalPath
+journalFilePathFromOptsNoDefault :: CliOpts -> IO (Maybe (NE.NonEmpty String))
+journalFilePathFromOptsNoDefault opts = do
   d <- getCurrentDirectory
-  maybe
-    (return $ NE.fromList [f])
-    (mapM (expandPathPreservingPrefix d))
-    $ NE.nonEmpty $ file_ opts
+  case NE.nonEmpty $ file_ opts of
+    Nothing -> return Nothing
+    Just paths -> Just <$> mapM (expandPathPreservingPrefix d) paths
 
 expandPathPreservingPrefix :: FilePath -> PrefixedFilePath -> IO PrefixedFilePath
 expandPathPreservingPrefix d prefixedf = do
@@ -765,24 +773,11 @@
   d <- getCurrentDirectory
   maybe (return Nothing) (fmap Just . expandPath d) $ mrules_file_ $ inputopts_ opts
 
--- -- | Get the width in characters to use for console output.
--- -- This comes from the --width option, or the COLUMNS environment
--- -- variable, or (on posix platforms) the current terminal width, or 80.
--- -- Will raise a parse error for a malformed --width argument.
--- widthFromOpts :: CliOpts -> Int
--- widthFromOpts CliOpts{width_=Nothing, available_width_=w} = w
--- widthFromOpts CliOpts{width_=Just s}  =
---     case runParser (read `fmap` some digitChar <* eof :: ParsecT Void String Identity Int) "(unknown)" s of
---         Left e   -> usageError $ "could not parse width option: "++errorBundlePretty e
---         Right w  -> w
-
--- for register:
-
 -- | Get the width in characters to use for the register command's console output,
 -- and also the description column width if specified (following the main width, comma-separated).
 -- The widths will be as follows:
 -- @
--- no --width flag - overall width is the available width (COLUMNS, or posix terminal width, or 80); description width is unspecified (auto)
+-- no --width flag - overall width is the available width (or terminal width, or 80); description width is unspecified (auto)
 -- --width W       - overall width is W, description width is auto
 -- --width W,D     - overall width is W, description width is D
 -- @
@@ -803,48 +798,6 @@
 
 -- Other utils
 
--- | Get the sorted unique canonical names of hledger addon commands
--- found in the current user's PATH. These are used in command line
--- parsing and to display the commands list.
---
--- Canonical addon names are the filenames of hledger-* executables in
--- PATH, without the "hledger-" prefix, and without the file extension
--- except when it's needed for disambiguation (see below).
---
--- When there are exactly two versions of an executable (same base
--- name, different extensions) that look like a source and compiled
--- pair (one has .exe, .com, or no extension), the source version will
--- be excluded (even if it happens to be newer). When there are three
--- or more versions (or two versions that don't look like a
--- source/compiled pair), they are all included, with file extensions
--- intact.
---
-hledgerAddons :: IO [String]
-hledgerAddons = do
-  -- past bug generator
-  as1 <- hledgerExecutablesInPath                     -- ["hledger-check","hledger-check-dates","hledger-check-dates.hs","hledger-check.hs","hledger-check.py"]
-  let as2 = map stripPrognamePrefix as1               -- ["check","check-dates","check-dates.hs","check.hs","check.py"]
-  let as3 = groupSortOn takeBaseName as2              -- [["check","check.hs","check.py"],["check-dates","check-dates.hs"]]
-  let as4 = concatMap dropRedundantSourceVersion as3  -- ["check","check.hs","check.py","check-dates"]
-  return as4
-
-stripPrognamePrefix = drop (length progname + 1)
-
-dropRedundantSourceVersion [f,g]
-  | map toLower (takeExtension f) `elem` compiledExts = [f]
-  | map toLower (takeExtension g) `elem` compiledExts = [g]
-dropRedundantSourceVersion fs = fs
-
-compiledExts = ["",".com",".exe"]
-
--- | Get the sorted unique filenames of all hledger-* executables in
--- the current user's PATH. These are files in any of the PATH directories,
--- named hledger-*, with either no extension (and no periods in the name)
--- or one of the addonExtensions.
--- We do not currently filter out non-file objects or files without execute permission.
-hledgerExecutablesInPath :: IO [String]
-hledgerExecutablesInPath = filter isHledgerExeName <$> likelyExecutablesInPath
-
 -- None of https://hackage.haskell.org/package/directory-1.3.8.1/docs/System-Directory.html#g:5
 -- do quite what we need (find all the executables in PATH with a filename prefix).
 -- | Get all sorted unique filenames in the current user's PATH.
@@ -865,55 +818,12 @@
 -- return exes''
 -- where isExecutable f = getPermissions f >>= (return . executable)
 
-isHledgerExeName :: String -> Bool
-isHledgerExeName = isRight . parsewith hledgerexenamep . T.pack
-    where
-      hledgerexenamep = do
-        _ <- string $ T.pack progname
-        _ <- char '-'
-        _ <- some $ noneOf ['.']
-        optional (string "." >> choice' (map (string . T.pack) addonExtensions))
-        eof
-
--- stripAddonExtension :: String -> String
--- stripAddonExtension = regexReplace re "" where re = "\\.(" ++ intercalate "|" addonExtensions ++ ")$"
-
-addonExtensions :: [String]
-addonExtensions =
-  ["bat"
-  ,"com"
-  ,"exe"
-  ,"hs"
-  ,"js"
-  ,"lhs"
-  ,"lua"
-  ,"php"
-  ,"pl"
-  ,"py"
-  ,"rb"
-  ,"rkt"
-  ,"sh"
-  -- ,""
-  ]
-
 getEnvSafe :: String -> IO String
 getEnvSafe v = getEnv v `C.catch` (\(_::C.IOException) -> return "") -- XXX should catch only isDoesNotExistError e
 
 getDirectoryContentsSafe :: FilePath -> IO [String]
 getDirectoryContentsSafe d =
     (filter (not . (`elem` [".",".."])) `fmap` getDirectoryContents d) `C.catch` (\(_::C.IOException) -> return [])
-
--- not used:
--- -- | Print debug info about arguments and options if --debug is present.
--- debugArgs :: [String] -> CliOpts -> IO ()
--- debugArgs args opts =
---   when ("--debug" `elem` args) $ do
---     progname <- getProgName
---     putStrLn $ "running: " ++ progname
---     putStrLn $ "raw args: " ++ show args
---     putStrLn $ "processed opts:\n" ++ show opts
---     d <- getCurrentDay
---     putStrLn $ "search query: " ++ (show $ queryFromOpts d $ reportopts_ opts)
 
 -- ** Lenses
 
diff --git a/Hledger/Cli/Commands.hs b/Hledger/Cli/Commands.hs
--- a/Hledger/Cli/Commands.hs
+++ b/Hledger/Cli/Commands.hs
@@ -15,11 +15,13 @@
 {-# LANGUAGE TemplateHaskell #-}
 
 module Hledger.Cli.Commands (
-   testcmd
+   commands
+  ,testcmd
   ,builtinCommands
   ,builtinCommandNames
+  ,addonCommandNames
+  ,knownAddonCommandNames
   ,findBuiltinCommand
-  ,knownAddonCommands
   ,knownCommands
   ,printCommandsList
   ,tests_Hledger_Cli
@@ -46,22 +48,27 @@
   ,module Hledger.Cli.Commands.Print
   ,module Hledger.Cli.Commands.Register
   ,module Hledger.Cli.Commands.Rewrite
+  ,module Hledger.Cli.Commands.Run
   ,module Hledger.Cli.Commands.Stats
   ,module Hledger.Cli.Commands.Tags
 ) 
 where
 
-import Data.Char (isAlphaNum, isSpace)
+import Data.Char (isAlphaNum, isSpace, toLower)
+import Data.Either (isRight)
 import Data.List
-import Data.List.Extra (nubSort)
+import Data.List.Extra (groupSortOn, nubSort)
 import Data.Text (Text)
 import qualified Data.Text as T
 import Data.Time.Calendar
 import Safe (headErr)
 import String.ANSI
-import System.Environment (withArgs)
 import System.Console.CmdArgs.Explicit as C
+import System.Environment (withArgs)
+import System.FilePath (dropExtension, takeBaseName, takeExtension)
 import Test.Tasty (defaultMain)
+import Text.Megaparsec
+import Text.Megaparsec.Char
 
 import Hledger
 import Hledger.Cli.CliOptions
@@ -91,9 +98,11 @@
 import Hledger.Cli.Commands.Register
 import Hledger.Cli.Commands.Rewrite
 import Hledger.Cli.Commands.Roi
+import Hledger.Cli.Commands.Run
 import Hledger.Cli.Commands.Stats
 import Hledger.Cli.Commands.Tags
 import Hledger.Cli.Utils (tests_Cli_Utils)
+import Data.Functor ((<&>))
 
 -- | The cmdargs subcommand mode (for command-line parsing)
 -- and IO action (for doing the command's work) for each builtin command.
@@ -111,6 +120,7 @@
   ,(checkmode              , check)
   ,(closemode              , close)
   ,(codesmode              , codes)
+  ,(commandsmode           , commands)
   ,(commoditiesmode        , commodities)
   ,(demomode               , demo)
   ,(descriptionsmode       , descriptions)
@@ -126,6 +136,8 @@
   ,(registermode           , register)
   ,(rewritemode            , rewrite)
   ,(roimode                , roi)
+  ,(runmode                , runOrReplStub)
+  ,(replmode               , runOrReplStub)
   ,(statsmode              , stats)
   ,(tagsmode               , tags)
   ,(testmode               , testcmd)
@@ -188,7 +200,7 @@
 -- 
 commandsList :: String -> [String] -> [String]
 commandsList progversion othercmds =
-  map (bold'.accent) _banner_smslant ++ 
+  map (bold'.accent) _banner_smslant ++   -- XXX not showing bold, why ?
   [
   -- Keep the following synced with:
   --  commands.m4
@@ -199,31 +211,34 @@
    "-------------------------------------------------------------------------------"
   ,progversion
   ,"Usage: hledger COMMAND [OPTIONS] [-- ADDONOPTIONS]"
-  ,"Commands (builtins + addons):"
+  -- ,"Commands (builtins + addons):"  -- XXX adapt for commands --builtin
+  ,"Commands:"
   ,""
     -----------------------------------------80-------------------------------------
   ,bold' "HELP (docs, demos..)"
-  ," (no arguments)           show this commands list"
-  ," -h [COMMAND]             show command line help"
-  ," --tldr [COMMAND]         show command examples with tldr"
-  ," --info [COMMAND]         show the hledger manual with info"
-  ," --man  [COMMAND]         show the hledger manual with man"
-  ," help [-i|-m|-p] [TOPIC]  show any topic in the hledger manual"
+  ," commands                 show the commands list (default)"
   ," demo [DEMO]              show brief demos in the terminal"
+  ," help [-i|-m|-p] [TOPIC]  show the hledger manual with info/man/pager"
+  ," --tldr    [COMMAND]      show command examples   [for command] with tldr"
+  ," --help/-h [COMMAND]      show command line help  [for command]"
+  ," --info    [COMMAND]      show the hledger manual [for command] with info"
+  ," --man     [COMMAND]      show the hledger manual [for command] with man"
   ,"                          more help: https://hledger.org"
   ,""
     -----------------------------------------80-------------------------------------
   ,bold' "USER INTERFACES (alternate UIs)"
-  ,"+ui                       run terminal UI"                                       -- hledger-ui
-  ,"+web                      run web UI"                                            -- hledger-web
+  ," repl                     run commands from an interactive prompt"
+  ," run                      run command scripts from files or arguments"
+  ,"+ui                       run a terminal UI (hledger-ui)"
+  ,"+web                      run a web UI (hledger-web)"
                                                                                      -- see also: MoLe, https://hledger.org/mobile.html
   ,""
     -----------------------------------------80-------------------------------------
   ,bold' "ENTERING DATA (add or edit transactions)"
   ," add                      add transactions using interactive prompts"
-  ,"+iadd                     add transactions using a TUI"                          -- hledger-iadd
+  ,"+iadd                     add transactions using a TUI (hledger-iadd)"
   ," import                   add new transactions from other files, eg CSV files"
-  ,"+edit                     edit existing transactions with $EDITOR"               -- hledger-utils
+  ,"+edit                     edit specific transactions with $EDITOR"               -- hledger-utils
   ,""
     -----------------------------------------80-------------------------------------
   ,bold' "BASIC REPORTS (simple lists)"
@@ -297,54 +312,157 @@
   , not $ "https://" `isInfixOf` line
   , let cmdname:_ = words line
   ]
-  -- KEEP SYNCED WITH commandsList.
+  -- Keep synced with commandsList.
 
+commandsmode =
+  hledgerCommandMode
+    $(embedFileRelative "Hledger/Cli/Commands/Commands.txt")
+    [flagNone ["builtin"] (setboolopt "builtin")  "show only builtin commands, not addons"
+    ]
+    [(helpflagstitle, helpflags)]
+    []
+    -- flagReq  ["debug"]    (\s opts -> Right $ setopt "debug" s opts) "[N]" "show debug output (levels 1-9, default: 1)"
+
+    ([], Nothing)
+
+-- | Display the commands list.
+commands :: CliOpts -> Journal -> IO ()
+commands opts _ = do
+  addons <- if boolopt "builtin" (rawopts_ opts) then return [] else addonCommandNames
+  printCommandsList prognameandversion addons
+
+{- | Print the commands list, with a pager if appropriate, customising the
+commandsList template above with the given version string and the installed addons.
+Uninstalled known addons will be removed from the list,
+installed known addons will have the + prefix removed,
+and installed unknown addons will be added under Misc.
+-}
+printCommandsList :: String -> [String] -> IO ()
+printCommandsList progversion installedaddons =
+  seq (length $ dbg8 "uninstalledknownaddons" uninstalledknownaddons) $ -- for debug output
+    seq (length $ dbg8 "installedknownaddons" installedknownaddons) $
+      seq (length $ dbg8 "installedunknownaddons" installedunknownaddons) $
+        runPager $
+          unlines $
+            map unplus $
+              filter (not . isuninstalledaddon) $
+                commandsList progversion installedunknownaddons
+ where
+  knownaddons = knownAddonCommandNames
+  uninstalledknownaddons = knownaddons \\ installedaddons
+  installedknownaddons = knownaddons `intersect` installedaddons
+  installedunknownaddons = installedaddons \\ knownaddons
+  unplus ('+' : cs) = ' ' : cs
+  unplus s = s
+  isuninstalledaddon =
+    \case
+      ('+' : l)
+        | cmd `notElem` installedaddons ->
+            dbg9With (const $ "hiding uninstalled addon: " <> cmd) $
+              True
+       where
+        cmd = takeWhile (not . isSpace) l
+      _ -> False
+
 -- | Canonical names of all commands which have a slot in the commands list, in alphabetical order.
 -- These include the builtin commands and the known addon commands.
 knownCommands :: [String]
 knownCommands = nubSort . commandsListExtractCommands False $ commandsList progname []
 
--- | Canonical names of the known addon commands which have a slot in the commands list,
--- in alphabetical order.
-knownAddonCommands :: [String]
-knownAddonCommands = nubSort . commandsListExtractCommands True $ commandsList progname []
-
 -- | All names and aliases of the builtin commands.
 builtinCommandNames :: [String]
 builtinCommandNames = concatMap (modeNames . fst) builtinCommands
 
--- | Look up a builtin command's mode and action by exact command name or alias. 
+-- | Look up a builtin command's mode and action by exact command name or alias.
 findBuiltinCommand :: String -> Maybe (Mode RawOpts, CliOpts -> Journal -> IO ()) 
 findBuiltinCommand cmdname = find (elem cmdname . modeNames . fst) builtinCommands 
 
--- | Print the commands list, with a pager if appropriate, customising the
--- commandsList template above with the given version string and the installed addons.
--- Uninstalled known addons will be removed from the list,
--- installed known addons will have the + prefix removed,
--- and installed unknown addons will be added under Misc.
-printCommandsList :: String -> [String] -> IO ()
-printCommandsList progversion installedaddons =
-  seq (length $ dbg8 "uninstalledknownaddons" uninstalledknownaddons) $  -- for debug output
-  seq (length $ dbg8 "installedknownaddons"   installedknownaddons)   $
-  seq (length $ dbg8 "installedunknownaddons" installedunknownaddons) $
-  runPager $ unlines $ map unplus $ filter (not.isuninstalledaddon) $
-    commandsList progversion installedunknownaddons
-  where
-    knownaddons = knownAddonCommands
-    uninstalledknownaddons  = knownaddons \\ installedaddons
-    installedknownaddons    = knownaddons `intersect` installedaddons
-    installedunknownaddons  = installedaddons \\ knownaddons
-    unplus ('+':cs) = ' ':cs
-    unplus s = s
-    isuninstalledaddon =
-      \case
-        ('+':l) | cmd `notElem` installedaddons ->
-                  dbg9With (const $ "hiding uninstalled addon: "<>cmd) $
-                  True where cmd = takeWhile (not . isSpace) l
-        _ -> False
+{- | Canonical names of the known addon commands which have a slot in the commands list,
+in alphabetical order.
+-}
+knownAddonCommandNames :: [String]
+knownAddonCommandNames = nubSort . commandsListExtractCommands True $ commandsList progname []
 
--- The test command is defined here for easy access to other modules' tests.
+-- Search PATH for names of addon commands, that aren't shadowed by builtin commands.
+addonCommandNames :: IO [String]
+addonCommandNames = installedAddonCommandNames <&> filter (not . (`elem` builtinCommandNames) . dropExtension)
 
+-- | Get the sorted unique canonical names of hledger addon commands
+-- found in the current user's PATH. These are used in command line
+-- parsing and to display the commands list.
+--
+-- Canonical addon names are the filenames of hledger-* executables in
+-- PATH, without the "hledger-" prefix, and without the file extension
+-- except when it's needed for disambiguation (see below).
+--
+-- When there are exactly two versions of an executable (same base
+-- name, different extensions) that look like a source and compiled
+-- pair (one has .exe, .com, or no extension), the source version will
+-- be excluded (even if it happens to be newer). When there are three
+-- or more versions (or two versions that don't look like a
+-- source/compiled pair), they are all included, with file extensions
+-- intact.
+--
+installedAddonCommandNames :: IO [String]
+installedAddonCommandNames = do
+  -- past bug generator
+  as1 <- hledgerExecutablesInPath                     -- ["hledger-check","hledger-check-dates","hledger-check-dates.hs","hledger-check.hs","hledger-check.py"]
+  let as2 = map stripPrognamePrefix as1               -- ["check","check-dates","check-dates.hs","check.hs","check.py"]
+  let as3 = groupSortOn takeBaseName as2              -- [["check","check.hs","check.py"],["check-dates","check-dates.hs"]]
+  let as4 = concatMap dropRedundantSourceVersion as3  -- ["check","check.hs","check.py","check-dates"]
+  return as4
+
+stripPrognamePrefix = drop (length progname + 1)
+
+dropRedundantSourceVersion [f,g]
+  | map toLower (takeExtension f) `elem` compiledExts = [f]
+  | map toLower (takeExtension g) `elem` compiledExts = [g]
+dropRedundantSourceVersion fs = fs
+
+compiledExts = ["",".com",".exe"]
+
+-- | Get the sorted unique filenames of all hledger-* executables in
+-- the current user's PATH. These are files in any of the PATH directories,
+-- named hledger-*, with either no extension (and no periods in the name)
+-- or one of the addonExtensions.
+-- We do not currently filter out non-file objects or files without execute permission.
+hledgerExecutablesInPath :: IO [String]
+hledgerExecutablesInPath = filter isHledgerExeName <$> likelyExecutablesInPath
+
+isHledgerExeName :: String -> Bool
+isHledgerExeName = isRight . parsewith hledgerexenamep . T.pack
+ where
+  hledgerexenamep = do
+    _ <- string $ T.pack progname
+    _ <- char '-'
+    _ <- some $ noneOf ['.']
+    optional (string "." >> choice' (map (string . T.pack) addonExtensions))
+    eof
+
+-- stripAddonExtension :: String -> String
+-- stripAddonExtension = regexReplace re "" where re = "\\.(" ++ intercalate "|" addonExtensions ++ ")$"
+
+addonExtensions :: [String]
+addonExtensions =
+  ["bat"
+  ,"com"
+  ,"exe"
+  ,"hs"
+  ,"js"
+  ,"lhs"
+  ,"lua"
+  ,"php"
+  ,"pl"
+  ,"py"
+  ,"rb"
+  ,"rkt"
+  ,"sh"
+  ,"osh"
+  ,"ysh"
+  ]
+
+-- The test command is also defined here for easy access to other modules' tests.
+
 testmode = hledgerCommandMode
   $(embedFileRelative "Hledger/Cli/Commands/Test.txt")
   []
@@ -387,8 +505,8 @@
         let
           ignoresourcepos j = j{jtxns=map (\t -> t{tsourcepos=nullsourcepospair}) (jtxns j)}
           sameParse str1 str2 = do
-            j1 <- ignoresourcepos <$> readJournal' str1  -- PARTIAL:
-            j2 <- ignoresourcepos <$> readJournal' str2  -- PARTIAL:
+            j1 <- ignoresourcepos <$> readJournal'' str1  -- PARTIAL:
+            j2 <- ignoresourcepos <$> readJournal'' str2  -- PARTIAL:
             j1 @?= j2{jlastreadtime=jlastreadtime j1, jfiles=jfiles j1} --, jparsestate=jparsestate j1}
         sameParse
            ("2008/12/07 One\n  alpha  $-1\n  beta  $1\n" <>
@@ -405,19 +523,19 @@
            )
 
     ,testCase "preserves \"virtual\" posting type" $ do
-      j <- readJournal' "apply account test\n2008/12/07 One\n  (from)  $-1\n  (to)  $1\n"  -- PARTIAL:
+      j <- readJournal'' "apply account test\n2008/12/07 One\n  (from)  $-1\n  (to)  $1\n"  -- PARTIAL:
       let p = headErr $ tpostings $ headErr $ jtxns j  -- PARTIAL headErrs succeed because txns & postings provided
       paccount p @?= "test:from"
       ptype p @?= VirtualPosting
     ]
 
   ,testCase "alias directive" $ do
-    j <- readJournal' "!alias expenses = equity:draw:personal\n1/1\n (expenses:food)  1\n"  -- PARTIAL:
+    j <- readJournal'' "!alias expenses = equity:draw:personal\n1/1\n (expenses:food)  1\n"  -- PARTIAL:
     let p = headErr $ tpostings $ headErr $ jtxns j  -- PARTIAL headErrs succeed because txns & postings provided
     paccount p @?= "equity:draw:personal:food"
 
   ,testCase "Y default year directive" $ do
-    j <- readJournal' defaultyear_journal_txt  -- PARTIAL:
+    j <- readJournal'' defaultyear_journal_txt  -- PARTIAL:
     tdate (headErr $ jtxns j) @?= fromGregorian 2009 1 1  -- PARTIAL headErr succeeds because defaultyear_journal_txt has a txn
 
   ,testCase "ledgerAccountNames" $
@@ -450,7 +568,7 @@
 -- t1 = LocalTime date1 midday
 
 {-
-samplejournal = readJournal' sample_journal_str
+samplejournal = readJournal'' sample_journal_str
 
 sample_journal_str = unlines
  ["; A sample journal file."
diff --git a/Hledger/Cli/Commands/Add.hs b/Hledger/Cli/Commands/Add.hs
--- a/Hledger/Cli/Commands/Add.hs
+++ b/Hledger/Cli/Commands/Add.hs
@@ -161,7 +161,7 @@
 confirmedTransactionWizard prevInput es@EntryState{..} stack@(currentStage : _) = case currentStage of
   EnterDateAndCode -> dateAndCodeWizard prevInput es >>= \case
     Just (efd, code) -> do
-      let 
+      let
         date = fromEFDay efd
         es' = es{ esArgs = drop 1 esArgs
                 , esDefDate = date
@@ -239,7 +239,7 @@
                           }
           amountAndCommentString = showAmount amt ++ T.unpack (if T.null comment then "" else "  ;" <> comment)
           prevAmountAndCmnt' = replaceNthOrAppend (length esPostings) amountAndCommentString (prevAmountAndCmnt prevInput)
-          es' = es{esPostings=esPostings++[p], esArgs=drop 2 esArgs}
+          es' = es{esPostings=esPostings++[p], esArgs=drop 1 esArgs}
       confirmedTransactionWizard prevInput{prevAmountAndCmnt=prevAmountAndCmnt'} es' (EnterNewPosting txnParams (Just posting) : stack)
     Nothing -> confirmedTransactionWizard prevInput es (drop 1 stack)
 
@@ -459,7 +459,7 @@
 -- | Convert a string of journal data into a register report.
 registerFromString :: T.Text -> IO TL.Text
 registerFromString s = do
-  j <- readJournal' s
+  j <- readJournal'' s
   return . postingsReportAsText opts $ postingsReport rspec j
       where
         ropts = defreportopts{empty_=True}
diff --git a/Hledger/Cli/Commands/Aregister.hs b/Hledger/Cli/Commands/Aregister.hs
--- a/Hledger/Cli/Commands/Aregister.hs
+++ b/Hledger/Cli/Commands/Aregister.hs
@@ -29,19 +29,18 @@
 import qualified Data.Text.Lazy as TL
 import qualified Data.Text.Lazy.Builder as TB
 import Control.Monad (when)
-import Lucid (toHtml)
-import qualified Lucid as L
+import qualified Lucid as L hiding (Html)
 import System.Console.CmdArgs.Explicit (flagNone, flagReq)
+import qualified System.IO as IO
+import Text.Tabular.AsciiWide hiding (render)
 
 import Hledger
+import Hledger.Cli.CliOptions
+import Hledger.Cli.Utils
 import Hledger.Write.Csv (CSV, printCSV, printTSV)
+import Hledger.Write.Html (formatRow, htmlAsLazyText, toHtml)
 import Hledger.Write.Ods (printFods)
 import qualified Hledger.Write.Spreadsheet as Spr
-import qualified Hledger.Write.Html.Lucid as Html
-import Hledger.Cli.CliOptions
-import Hledger.Cli.Utils
-import Text.Tabular.AsciiWide hiding (render)
-import qualified System.IO as IO
 
 aregistermode = hledgerCommandMode
   $(embedFileRelative "Hledger/Cli/Commands/Aregister.txt")
@@ -52,7 +51,7 @@
   ,flagNone ["cumulative"] (setboolopt "cumulative")
      "show running total from report start date"
   ,flagNone ["historical","H"] (setboolopt "historical")
-     "show historical running total/balance (includes postings before report start date) (default)\n "
+     "show historical running total/balance (includes postings before report start date) (default)"
   -- ,flagNone ["average","A"] (setboolopt "average")
   --    "show running average of posting amounts instead of total (implies --empty)"
   -- ,flagNone ["related","r"] (setboolopt "related") "show postings' siblings instead"
@@ -66,7 +65,7 @@
 #else
       "terminal width"
 #endif
-      ++ " or $COLUMNS). -wN,M sets description width as well."
+      ++ "). -wN,M sets description width as well."
      )
   ,flagNone ["align-all"] (setboolopt "align-all") "guarantee alignment across all lines (slower)"
   ,outputFormatFlag ["txt","html","csv","tsv","json"]
@@ -176,7 +175,7 @@
 -- | Render a register report as a HTML snippet.
 accountTransactionsReportAsHTML :: CliOpts -> Query -> Query -> AccountTransactionsReport -> TL.Text
 accountTransactionsReportAsHTML copts reportq thisacctq items =
-  L.renderText $ do
+  htmlAsLazyText $ do
     L.link_ [L.rel_ "stylesheet", L.href_ "hledger.css"]
     L.table_ $ do
       when (headingopt copts) $ L.thead_ $ L.tr_ $ do
@@ -186,7 +185,7 @@
         L.th_ "change"
         L.th_ "balance"
       L.tbody_ $ for_ items $
-        Html.formatRow . map (fmap toHtml) .
+        formatRow . map (fmap toHtml) .
         accountTransactionsReportItemAsRecord
           oneLineNoCostFmt False
           (whichDate $ _rsReportOpts $ reportspec_ copts)
diff --git a/Hledger/Cli/Commands/Aregister.txt b/Hledger/Cli/Commands/Aregister.txt
--- a/Hledger/Cli/Commands/Aregister.txt
+++ b/Hledger/Cli/Commands/Aregister.txt
@@ -13,11 +13,10 @@
      --cumulative           show running total from report start date
   -H --historical           show historical running total/balance (includes
                             postings before report start date) (default)
-                            
      --invert               display all amounts with reversed sign
      --heading=YN           show heading row above table: yes (default) or no
-  -w --width=N              set output width (default: terminal width or
-                            $COLUMNS). -wN,M sets description width as well.
+  -w --width=N              set output width (default: terminal width). -wN,M
+                            sets description width as well.
      --align-all            guarantee alignment across all lines (slower)
   -O --output-format=FMT    select the output format. Supported formats:
                             txt, html, csv, tsv, json.
diff --git a/Hledger/Cli/Commands/Balance.hs b/Hledger/Cli/Commands/Balance.hs
--- a/Hledger/Cli/Commands/Balance.hs
+++ b/Hledger/Cli/Commands/Balance.hs
@@ -291,7 +291,6 @@
 import qualified Data.Text.Lazy.Builder as TB
 import Data.Time (addDays, fromGregorian)
 import System.Console.CmdArgs.Explicit as C (flagNone, flagReq, flagOpt)
-import Lucid as L hiding (value_)
 import Safe (headMay, maximumMay)
 import Text.Tabular.AsciiWide
     (Header(..), Align(..), Properties(..), Cell(..), Table(..), TableOpts(..),
@@ -305,7 +304,7 @@
 import Hledger.Cli.Anchor (setAccountAnchor, dateSpanCell, headerDateSpanCell)
 import Hledger.Write.Csv (CSV, printCSV, printTSV)
 import Hledger.Write.Ods (printFods)
-import Hledger.Write.Html.Lucid (printHtml)
+import Hledger.Write.Html (Html, styledTableHtml, htmlAsLazyText, toHtml)
 import Hledger.Write.Spreadsheet (rawTableContent, headerCell,
             addHeaderBorders, addRowSpanHeader,
             cellFromMixedAmount, cellsFromMixedAmount)
@@ -360,10 +359,10 @@
     ,flagReq  ["layout"] (\s opts -> Right $ setopt "layout" s opts) "ARG"
       (unlines
         ["how to lay out multi-commodity amounts and the overall table:"
-        ,"'wide[,WIDTH]': commodities on one line"
-        ,"'tall'        : commodities on separate lines"
-        ,"'bare'        : commodity symbols in one column"
-        ,"'tidy'        : every attribute in its own column"
+        ,"'wide[,W]': commodities on same line, up to W wide"
+        ,"'tall'    : commodities on separate lines"
+        ,"'bare'    : commodity symbols in a separate column"
+        ,"'tidy'    : each data field in its own column"
         ])
      ,flagReq  ["base-url"] (\s opts -> Right $ setopt "base-url" s opts) "URLPREFIX" "in html output, generate links to hledger-web, with this prefix. (Usually the base url shown by hledger-web; can also be relative.)"
 
@@ -391,8 +390,8 @@
             "json" -> (<>"\n") . toJsonText
             "csv"  -> printCSV . budgetReportAsCsv ropts
             "tsv"  -> printTSV . budgetReportAsCsv ropts
-            "html" -> (<>"\n") . L.renderText .
-                      printHtml . map (map (fmap L.toHtml)) . budgetReportAsSpreadsheet ropts
+            "html" -> (<>"\n") . htmlAsLazyText .
+                      styledTableHtml . map (map (fmap toHtml)) . budgetReportAsSpreadsheet ropts
             "fods" -> printFods IO.localeEncoding .
                       Map.singleton "Budget Report" . (,) (1,0) . budgetReportAsSpreadsheet ropts
             _      -> error' $ unsupportedOutputFormatError fmt
@@ -404,7 +403,7 @@
               "txt"  -> multiBalanceReportAsText ropts
               "csv"  -> printCSV . multiBalanceReportAsCsv ropts
               "tsv"  -> printTSV . multiBalanceReportAsCsv ropts
-              "html" -> (<>"\n") . L.renderText . multiBalanceReportAsHtml ropts
+              "html" -> (<>"\n") . htmlAsLazyText . multiBalanceReportAsHtml ropts
               "json" -> (<>"\n") . toJsonText
               "fods" -> printFods IO.localeEncoding .
                         Map.singleton "Multi-period Balance Report" . multiBalanceReportAsSpreadsheet ropts
@@ -417,8 +416,8 @@
               "txt"  -> TB.toLazyText . balanceReportAsText ropts
               "csv"  -> printCSV . balanceReportAsCsv ropts
               "tsv"  -> printTSV . balanceReportAsCsv ropts
-              "html" -> (<>"\n") . L.renderText .
-                                   printHtml . map (map (fmap L.toHtml)) . balanceReportAsSpreadsheet ropts
+              "html" -> (<>"\n") . htmlAsLazyText .
+                                   styledTableHtml . map (map (fmap toHtml)) . balanceReportAsSpreadsheet ropts
               "json" -> (<>"\n") . toJsonText
               "fods" -> printFods IO.localeEncoding . Map.singleton "Balance Report" . (,) (1,0) . balanceReportAsSpreadsheet ropts
               _      -> error' $ unsupportedOutputFormatError fmt  -- PARTIAL:
@@ -685,7 +684,7 @@
       _          -> dateHeaders
     dateHeaders =
       map (headerDateSpanCell balance_base_url_ querystring_) colspans ++
-      [hCell "rowtotal" "total" | row_total_] ++
+      [hCell "rowtotal" "total" | multiBalanceHasTotalsColumn opts] ++
       [hCell "rowaverage" "average" | average_]
     fullRowAsTexts row =
         addRowSpanHeader anchorCell $
@@ -709,9 +708,9 @@
 
 
 -- | Render a multi-column balance report as HTML.
-multiBalanceReportAsHtml :: ReportOpts -> MultiBalanceReport -> Html ()
+multiBalanceReportAsHtml :: ReportOpts -> MultiBalanceReport -> Html
 multiBalanceReportAsHtml ropts mbr =
-  printHtml . map (map (fmap L.toHtml)) $
+  styledTableHtml . map (map (fmap toHtml)) $
     snd $ multiBalanceReportAsSpreadsheet ropts mbr
 
 -- | Render the ODS table rows for a MultiBalanceReport.
@@ -1120,7 +1119,7 @@
               where
                 costedAmounts = case conversionop_ of
                     Just ToCost -> amounts . mixedAmountCost
-                    _           -> amounts
+                    _           -> amounts . mixedAmountStripCosts  -- strip any lingering cost info that would prevent unification
 
             -- | Like percentage, but accept multicommodity actual and budget amounts,
             -- and extract the specified commodity from both.
@@ -1227,7 +1226,7 @@
 
    testGroup "balanceReportAsText" [
     testCase "unicode in balance layout" $ do
-      j <- readJournal' "2009/01/01 * медвежья шкура\n  расходы:покупки  100\n  актив:наличные\n"
+      j <- readJournal'' "2009/01/01 * медвежья шкура\n  расходы:покупки  100\n  актив:наличные\n"
       let rspec = defreportspec{_rsReportOpts=defreportopts{no_total_=True}}
       TB.toLazyText (balanceReportAsText (_rsReportOpts rspec) (balanceReport rspec{_rsDay=fromGregorian 2008 11 26} j))
         @?=
diff --git a/Hledger/Cli/Commands/Balance.txt b/Hledger/Cli/Commands/Balance.txt
--- a/Hledger/Cli/Commands/Balance.txt
+++ b/Hledger/Cli/Commands/Balance.txt
@@ -54,10 +54,10 @@
      --transpose            switch rows and columns (use vertical time axis)
      --layout=ARG           how to lay out multi-commodity amounts and the
                             overall table:
-                            'wide[,WIDTH]': commodities on one line
-                            'tall'        : commodities on separate lines
-                            'bare'        : commodity symbols in one column
-                            'tidy'        : every attribute in its own column
+                            'wide[,W]': commodities on same line, up to W wide
+                            'tall'    : commodities on separate lines
+                            'bare'    : commodity symbols in a separate column
+                            'tidy'    : each data field in its own column
      --base-url=URLPREFIX   in html output, generate links to hledger-web,
                             with this prefix. (Usually the base url shown by
                             hledger-web; can also be relative.)
@@ -908,10 +908,6 @@
 run the balance command with the extra option
 --base-url=http://localhost:5000. You can also produce relative links,
 like --base-url="some/path" or --base-url="".)
-
-The balance reports' HTML output currently does not indent tree mode
-reports properly (#1846). So in HTML balance reports, use list mode for
-now (it is the default).
 
 Some useful balance reports
 
diff --git a/Hledger/Cli/Commands/Balancesheet.txt b/Hledger/Cli/Commands/Balancesheet.txt
--- a/Hledger/Cli/Commands/Balancesheet.txt
+++ b/Hledger/Cli/Commands/Balancesheet.txt
@@ -12,8 +12,6 @@
                             market price fluctuations)
      --gain                 show unrealised capital gain/loss (historical
                             balance value minus cost basis)
-     --budget               show sum of posting amounts compared to budget
-                            goals defined by periodic transactions
      --count                show the count of postings
      --change               accumulate amounts from column start to column
                             end (in multicolumn reports)
diff --git a/Hledger/Cli/Commands/Balancesheetequity.txt b/Hledger/Cli/Commands/Balancesheetequity.txt
--- a/Hledger/Cli/Commands/Balancesheetequity.txt
+++ b/Hledger/Cli/Commands/Balancesheetequity.txt
@@ -13,8 +13,6 @@
                             market price fluctuations)
      --gain                 show unrealised capital gain/loss (historical
                             balance value minus cost basis)
-     --budget               show sum of posting amounts compared to budget
-                            goals defined by periodic transactions
      --count                show the count of postings
      --change               accumulate amounts from column start to column
                             end (in multicolumn reports)
diff --git a/Hledger/Cli/Commands/Cashflow.txt b/Hledger/Cli/Commands/Cashflow.txt
--- a/Hledger/Cli/Commands/Cashflow.txt
+++ b/Hledger/Cli/Commands/Cashflow.txt
@@ -14,8 +14,6 @@
                             market price fluctuations)
      --gain                 show unrealised capital gain/loss (historical
                             balance value minus cost basis)
-     --budget               show sum of posting amounts compared to budget
-                            goals defined by periodic transactions
      --count                show the count of postings
      --change               accumulate amounts from column start to column
                             end (in multicolumn reports) (default)
diff --git a/Hledger/Cli/Commands/Close.hs b/Hledger/Cli/Commands/Close.hs
--- a/Hledger/Cli/Commands/Close.hs
+++ b/Hledger/Cli/Commands/Close.hs
@@ -14,13 +14,12 @@
 import qualified Data.Text as T
 import qualified Data.Text.IO as T
 import Data.Time.Calendar (addDays)
-import Lens.Micro ((^.))
 import System.Console.CmdArgs.Explicit as C
 
 import Hledger
 import Hledger.Cli.CliOptions
 import Safe (lastDef, readMay, readDef)
-import System.FilePath (takeFileName)
+import System.FilePath (takeBaseName)
 import Data.Char (isDigit)
 import Hledger.Read.RulesReader (parseBalanceAssertionType)
 import Hledger.Cli.Commands.Print (roundFlag, amountStylesSetRoundingFromRawOpts)
@@ -34,18 +33,15 @@
 
 closemode = hledgerCommandMode
   $(embedFileRelative "Hledger/Cli/Commands/Close.txt")
-  [flagOpt "" ["migrate"]    (\s opts -> Right $ setopt "migrate" s opts) "NEW" ("show closing and opening transactions,"
-    <> " for Asset and Liability accounts by default, tagged for easy matching."
-    <> " The tag's default value can be overridden by providing NEW."
-    )
-  ,flagOpt "" ["close"]      (\s opts -> Right $ setopt "close" s opts)  "NEW" "(default) show a closing transaction"
-  ,flagOpt "" ["open"]       (\s opts -> Right $ setopt "open" s opts)   "NEW" "show an opening transaction"
-  ,flagOpt "" ["assign"]     (\s opts -> Right $ setopt "assign" s opts) "NEW" "show opening balance assignments"
-  ,flagOpt "" ["assert"]     (\s opts -> Right $ setopt "assert" s opts) "NEW" "show closing balance assertions"
-  ,flagOpt "" ["retain"]     (\s opts -> Right $ setopt "retain" s opts) "NEW" "show a retain earnings transaction, for Revenue and Expense accounts by default"
-  ,flagNone ["explicit","x"] (setboolopt "explicit") "show all amounts explicitly"
-  ,flagNone ["show-costs"]   (setboolopt "show-costs") "show amounts with different costs separately"
-  ,flagNone ["interleaved"]  (setboolopt "interleaved") "show source and destination postings together"
+  [flagOpt "" ["clopen"]     (\s opts -> Right $ setopt "clopen" s opts) "TAGVAL" "show closing and opening balances transactions, for AL accounts by default"
+  ,flagOpt "" ["close"]      (\s opts -> Right $ setopt "close" s opts)  "TAGVAL" "show just a closing balances transaction"
+  ,flagOpt "" ["open"]       (\s opts -> Right $ setopt "open" s opts)   "TAGVAL" "show just an opening balances transaction"
+  ,flagOpt "" ["assert"]     (\s opts -> Right $ setopt "assert" s opts) "TAGVAL" "show a balance assertions transaction"
+  ,flagOpt "" ["assign"]     (\s opts -> Right $ setopt "assign" s opts) "TAGVAL" "show a balance assignments transaction"
+  ,flagOpt "" ["retain"]     (\s opts -> Right $ setopt "retain" s opts) "TAGVAL" "show a retain earnings transaction, for RX accounts by default"
+  ,flagNone ["explicit","x"] (setboolopt "explicit")                              "show all amounts explicitly"
+  ,flagNone ["show-costs"]   (setboolopt "show-costs")                            "show amounts with different costs separately"
+  ,flagNone ["interleaved"]  (setboolopt "interleaved")                           "show source and destination postings together"
   ,flagReq  ["assertion-type"]  (\s opts -> Right $ setopt "assertion-type" s opts) "TYPE" "=, ==, =* or ==*"
   ,flagReq  ["close-desc"]   (\s opts -> Right $ setopt "close-desc" s opts) "DESC" "set closing transaction's description"
   ,flagReq  ["close-acct"]   (\s opts -> Right $ setopt "close-acct" s opts) "ACCT" "set closing transaction's destination account"
@@ -58,23 +54,24 @@
     ++  -- keep supporting old flag names for compatibility
     [flagNone ["closing"]   (setboolopt "close")                                   "old spelling of --close"
     ,flagNone ["opening"]   (setboolopt "open")                                    "old spelling of --open"
+    ,flagNone ["migrate"]   (setboolopt "clopen")                                  "old spelling of --clopen"
     ,flagReq  ["close-to"]  (\s opts -> Right $ setopt "close-acct" s opts) "ACCT" "old spelling of --close-acct"
     ,flagReq  ["open-from"] (\s opts -> Right $ setopt "open-acct"  s opts) "ACCT" "old spelling of --open-acct"
     ]
   )
-  ([], Just $ argsFlag "[--migrate|--close|--open|--assign|--assert|--retain] [ACCTQUERY]")
+  ([], Just $ argsFlag "[--close|--open|--clopen|--assign|--assert|--retain] [ACCTQUERY]")
 
 -- | The close command's mode (subcommand).
 -- The code depends on these spellings.
-data CloseMode = Migrate | Close | Open | Assign | Assert | Retain deriving (Eq,Show,Read)
+data CloseMode = Clopen | Close | Open | Assign | Assert | Retain deriving (Eq,Show,Read)
 
--- | Pick the rightmost flag spelled like a CloseMode (--migrate, --close, --open, etc), or default to Close.
+-- | Pick the rightmost flag spelled like a CloseMode (--clopen, --close, --open, etc), or default to Close.
 closeModeFromRawOpts :: RawOpts -> CloseMode
 closeModeFromRawOpts rawopts = lastDef Close $ collectopts (\(name,_) -> readMay (capitalise name)) rawopts
 
 -- Debugger, beware: close is incredibly devious; simple rules combine to make a horrid maze.
 -- Tests are in hledger/test/close.test.
-close copts@CliOpts{rawopts_=rawopts, reportspec_=rspec0} j = do
+close CliOpts{rawopts_=rawopts, reportspec_=rspec0} j = do
   let
     mode_ = closeModeFromRawOpts rawopts
     defacctsq_    = if mode_ == Retain then Type [Revenue, Expense] else Type [Asset, Liability]
@@ -86,15 +83,16 @@
     tagval = fromMaybe "" $ maybestringopt modeflag rawopts where modeflag = lowercase $ show mode_
     comment = T.pack $ if
       | mode_ == Assert -> "assert:" <> tagval
+      | mode_ == Assign -> "assign:" <> tagval
       | mode_ == Retain -> "retain:" <> tagval
-      | otherwise       -> "start:"  <> if null tagval then inferredval else tagval
+      | otherwise       -> "clopen:" <> if null tagval then inferredval else tagval
       where
-        inferredval = newfilename
+        inferredval = newfilebasename
           where
-            oldfilename = takeFileName $ journalFilePath j
-            (nonnum, rest) = break isDigit $ reverse oldfilename
+            oldfilebasename = takeBaseName $ journalFilePath j
+            (nonnum, rest) = break isDigit $ reverse oldfilebasename
             (oldnum, rest2) = span isDigit rest
-            newfilename = case oldnum of
+            newfilebasename = case oldnum of
               [] -> ""
               _  -> reverse rest2 <> newnum <> reverse nonnum
                 where
@@ -119,7 +117,7 @@
     opendate = addDays 1 closedate
 
     -- should we show the amount(s) on the equity posting(s) ?
-    explicit = boolopt "explicit" rawopts || copts ^. infer_costs
+    explicit = boolopt "explicit" rawopts
 
     -- the accounts to close
     argsacctq = filterQuery (\q -> queryIsAcct q || queryIsType q) argsq
@@ -147,7 +145,7 @@
 
     -- the closing (balance-asserting or balance-zeroing) transaction
     mclosetxn
-      | mode_ `notElem` [Migrate, Close, Assert, Retain] = Nothing
+      | mode_ `notElem` [Clopen, Close, Assert, Retain] = Nothing
       | otherwise = Just nulltransaction{
           tdate=closedate, tdescription=closedesc, tcomment=comment, tpostings=closeps
           }
@@ -162,7 +160,7 @@
           -- XXX some duplication
           | mode_ == Assert =
             [ posting{
-                  paccount          = a
+                   paccount          = a
                   ,pamount           = mixedAmount $ precise b{aquantity=0, acost=Nothing}
                   -- after each commodity's last posting, assert 0 balance (#1035)
                   -- balance assertion amounts are unpriced (#824)
@@ -210,7 +208,7 @@
 
     -- the opening (balance-assigning or balance-unzeroing) transaction
     mopentxn
-      | mode_ `notElem` [Migrate, Open, Assign] = Nothing
+      | mode_ `notElem` [Clopen, Open, Assign] = Nothing
       | otherwise = Just nulltransaction{
           tdate=opendate, tdescription=opendesc, tcomment=comment, tpostings=openps
           }
diff --git a/Hledger/Cli/Commands/Close.txt b/Hledger/Cli/Commands/Close.txt
--- a/Hledger/Cli/Commands/Close.txt
+++ b/Hledger/Cli/Commands/Close.txt
@@ -2,24 +2,21 @@
 
 (equity)
 
-close generates several kinds of "closing" and/or "opening"
-transactions, useful in certain situations, including migrating balances
-to a new journal file, retaining earnings into equity, consolidating
-balances, or viewing lots. Like print, it prints valid journal entries.
-You can append or copy these to your journal file(s) when you are happy
-with how they look.
+close prints several kinds of "closing" and/or "opening" transactions,
+useful in various situations: migrating balances to a new journal file,
+retaining earnings into equity, consolidating balances, viewing lot
+costs.. Like print, it prints valid journal entries. You can copy these
+into your journal file(s) when you are happy with how they look.
 
 Flags:
-     --migrate[=NEW]        show closing and opening transactions, for Asset
-                            and Liability accounts by default, tagged for easy
-                            matching. The tag's default value can be overridden
-                            by providing NEW.
-     --close[=NEW]          (default) show a closing transaction
-     --open[=NEW]           show an opening transaction
-     --assign[=NEW]         show opening balance assignments
-     --assert[=NEW]         show closing balance assertions
-     --retain[=NEW]         show a retain earnings transaction, for Revenue
-                            and Expense accounts by default
+     --clopen[=TAGVAL]      show closing and opening balances transactions,
+                            for AL accounts by default
+     --close[=TAGVAL]       show just a closing balances transaction
+     --open[=TAGVAL]        show just an opening balances transaction
+     --assert[=TAGVAL]      show a balance assertions transaction
+     --assign[=TAGVAL]      show a balance assignments transaction
+     --retain[=TAGVAL]      show a retain earnings transaction, for RX
+                            accounts by default
   -x --explicit             show all amounts explicitly
      --show-costs           show amounts with different costs separately
      --interleaved          show source and destination postings together
@@ -31,94 +28,109 @@
      --round=TYPE           how much rounding or padding should be done when
                             displaying amounts ?
                             none - show original decimal digits,
-                                   as in journal
+                                   as in journal (default)
                             soft - just add or remove decimal zeros
-                                   to match precision (default)
+                                   to match precision
                             hard - round posting amounts to precision
                                    (can unbalance transactions)
                             all  - also round cost amounts to precision
                                    (can unbalance transactions)
 
-close currently has six modes, selected by a single mode flag:
+close has six modes, selected by choosing one of the mode flags (--close
+is the default). They all do much the same operation, but with different
+defaults, useful in different situations.
 
-close --migrate
+close --clopen
 
-This is the most common mode. It prints a "closing balances" transaction
-that zeroes out all asset and liability balances (by default), and an
-opposite "opening balances" transaction that restores them again. The
-balancing account will be equity:opening/closing balances (or another
-specified by --close-acct or --open-acct).
+This is useful if migrating balances to a new journal file at the start
+of a new year. It prints a "closing balances" transaction that zeroes
+out account balances (Asset and Liability accounts, by default), and an
+opposite "opening balances" transaction that restores them again.
+Typically, you would run
 
-This is useful when migrating balances to a new journal file at the
-start of a new year. Essentially, you run
-hledger close --migrate=NEWYEAR -e NEWYEAR and then copy the closing
-transaction to the end of the old file and the opening transaction to
-the start of the new file. The opening transaction sets correct starting
-balances in the new file when it is used alone, and the closing
-transaction keeps balances correct when you use both old and new files
-together, by cancelling out the following opening transaction and
-preventing buildup of duplicated opening balances. Think of the
-closing/opening pair as "moving the balances into the next file".
+hledger close --clopen -e NEWYEAR >> $LEDGER_FILE
 
-You can close a different set of accounts by providing a query. Eg if
-you want to include equity, you can add assets liabilities equity or
-type:ALE arguments. (The balancing account is always excluded.) Revenues
-and expenses usually are not migrated to a new file directly; see
---retain below.
+and then move the opening transaction from the old file to the new file
+(and probably also update your LEDGER_FILE environment variable).
 
-The generated transactions will have a start: tag, with its value set to
---migrate's NEW argument if any, for easier matching or exclusion. When
-NEW is not specified, it will be inferred if possible by incrementing a
-number (eg a year number) within the default journal's main file name.
-The other modes behave similarly.
+Why might you do this ? If your reports are fast, you may not need it.
+But at some point you will probably want to partition your data by time,
+for performance or data integrity or regulatory reasons. A new file or
+set of files per year is common. Then, having each file/fileset
+"bookended" with opening and closing balance transactions will allow you
+to freely pick and choose which files to read - just the current year,
+any past year, any sequence of years, or all of them - while showing
+correct account balances in each case. The earliest opening balances
+transaction sets correct starting balances, and any later
+closing/opening pairs will harmlessly cancel each other out.
 
+The balances will be transferred to and from
+equity:opening/closing balances by default. You can override this by
+using --close-acct and/or --open-acct.
+
+You can select a different set of accounts to close/open by providing an
+account query. Eg to add Equity accounts, provide arguments like
+assets liabilities equity or type:ALE. When migrating to a new file,
+you'll usually want to bring along the AL or ALE accounts, but not the
+RX accounts (Revenue, Expense).
+
+Assertions will be added indicating and checking the new balances of the
+closed/opened accounts.
+
+The generated transactions will have a clopen: tag. If the main
+journal's base file name contains a number (eg a year number), the tag's
+value will be that base file name with the number incremented. Or you
+can choose the tag value yourself, by using --clopen=TAGVAL.
+
 close --close
 
-This prints just the closing balances transaction of --migrate. It is
-the default behaviour if you specify no mode flag. Using the
-customisation options below, you can move balances from any set of
-accounts to a different account.
+This prints just the closing balances transaction of --clopen. It is the
+default if you don't specify a mode.
 
+More customisation options are described below. Among other things, you
+can use close --close to generate a transaction moving the balances from
+any set of accounts, to a different account. (If you need to move just a
+portion of the balance, see hledger-move.)
+
 close --open
 
-This prints just the opening balances transaction of --migrate. It is
-similar to Ledger's equity command.
+This prints just the opening balances transaction of --clopen. (It is
+similar to Ledger's equity command.)
 
 close --assert
 
-This prints a "closing balances" transaction (with balances: tag), that
-just declares balance assertions for the current balances without
-changing them. It could be useful as documention and to guard against
-changes.
+This prints a transaction that asserts the account balances as they are
+on the end date (and adds an assert: tag). It could be useful as
+documention and to guard against changes.
 
 close --assign
 
-This prints an "opening balances" transaction that restores the account
-balances using balance assignments. Balance assignments work regardless
-of any previous balance, so a preceding closing balances transaction is
-not needed.
+This prints a transaction that assigns the account balances as they are
+on the end date (and adds an "assign:" tag). Unlike balance assertions,
+assignments will post changes to balances as needed to reach the
+specified amounts.
 
-However, omitting the closing balances transaction would unbalance
-equity. This is relatively harmless for personal reports, but it
-disturbs the accounting equation, removing a source of error detection.
-So --migrate is generally the best way to set to set balances in new
-files, for now.
+This is another way to set starting balances when migrating to a new
+file, and it will set them correctly even in the presence of earlier
+files which do not have a closing balances transaction. However, it can
+hide errors, and disturb the accounting equation, so --clopen is usually
+recommended.
 
 close --retain
 
-This is like --close with different defaults: it prints a "retain
-earnings" transaction (with retain: tag), that transfers revenue and
-expense balances to equity:retained earnings.
+This is like --close, but it closes Revenue and Expense account balances
+by default. They will be transferred to equity:retained earnings, or
+another account specified with --close-acct.
 
-This is a different kind of closing, called "retaining earnings" or
-"closing the books"; it is traditionally performed by businesses at the
-end of each accounting period, to consolidate revenues and expenses into
-the main equity balance. ("Revenues" and "expenses" are actually equity
-by another name, kept separate temporarily for reporting purposes.)
+Revenues and expenses correspond to changes in equity. They are
+categorised separately for reporting purposes, but traditionally at the
+end of each accounting period, businesses consolidate them into equity,
+This is called "retaining earnings", or "closing the books".
 
-In personal accounting you generally don't need to do this, unless you
-want the balancesheetequity report to show a zero total, demonstrating
-that the accounting equation (A-L=E) is satisfied.
+In personal accounting, there's not much reason to do this, and most
+people don't. (One reason to do it is to help the balancesheetequity
+report show a zero total, demonstrating that the accounting equation
+(A-L=E) is satisfied.)
 
 close customisation
 
@@ -207,7 +219,7 @@
 
 Close assets/liabilities on 2022-12-31 and re-open them on 2023-01-01:
 
-$ hledger close --migrate -f 2022.journal -p 2022
+$ hledger close --clopen -f 2022.journal -p 2022
 # copy/paste the closing transaction to the end of 2022.journal
 # copy/paste the opening transaction to the start of 2023.journal
 
@@ -217,14 +229,14 @@
 $ hledger -f 2022.journal bs not:desc:'closing balances'
 
 For more flexibility, it helps to tag closing and opening transactions
-with eg start:NEWYEAR, then you can ensure correct balances by excluding
-all opening/closing transactions except the first, like so:
+with eg clopen:NEWYEAR, then you can ensure correct balances by
+excluding all opening/closing transactions except the first, like so:
 
-$ hledger bs -Y -f 2021.j -f 2022.j -f 2023.j expr:'tag:start=2021 or not tag:start'
-$ hledger bs -Y -f 2021.j -f 2022.j           expr:'tag:start=2021 or not tag:start'
-$ hledger bs -Y -f 2022.j -f 2023.j           expr:'tag:start=2022 or not tag:start'
-$ hledger bs -Y -f 2021.j                     expr:'tag:start=2021 or not tag:start'
-$ hledger bs -Y -f 2022.j                     expr:'tag:start=2022 or not tag:start'
+$ hledger bs -Y -f 2021.j -f 2022.j -f 2023.j expr:'tag:clopen=2021 or not tag:clopen'
+$ hledger bs -Y -f 2021.j -f 2022.j           expr:'tag:clopen=2021 or not tag:clopen'
+$ hledger bs -Y -f 2022.j -f 2023.j           expr:'tag:clopen=2022 or not tag:clopen'
+$ hledger bs -Y -f 2021.j                     expr:'tag:clopen=2021 or not tag:clopen'
+$ hledger bs -Y -f 2022.j                     expr:'tag:clopen=2022 or not tag:clopen'
 $ hledger bs -Y -f 2023.j                     # unclosed file, no query needed
 
 More detailed close examples
diff --git a/Hledger/Cli/Commands/Commands.txt b/Hledger/Cli/Commands/Commands.txt
new file mode 100644
--- /dev/null
+++ b/Hledger/Cli/Commands/Commands.txt
@@ -0,0 +1,6 @@
+commands
+
+Show the hledger commands list.
+
+Flags:
+     --builtin             show only builtin commands, not addons
diff --git a/Hledger/Cli/Commands/Demo.txt b/Hledger/Cli/Commands/Demo.txt
--- a/Hledger/Cli/Commands/Demo.txt
+++ b/Hledger/Cli/Commands/Demo.txt
@@ -26,3 +26,5 @@
 $ 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.
diff --git a/Hledger/Cli/Commands/Incomestatement.txt b/Hledger/Cli/Commands/Incomestatement.txt
--- a/Hledger/Cli/Commands/Incomestatement.txt
+++ b/Hledger/Cli/Commands/Incomestatement.txt
@@ -13,8 +13,6 @@
                             market price fluctuations)
      --gain                 show unrealised capital gain/loss (historical
                             balance value minus cost basis)
-     --budget               show sum of posting amounts compared to budget
-                            goals defined by periodic transactions
      --count                show the count of postings
      --change               accumulate amounts from column start to column
                             end (in multicolumn reports) (default)
diff --git a/Hledger/Cli/Commands/Print.hs b/Hledger/Cli/Commands/Print.hs
--- a/Hledger/Cli/Commands/Print.hs
+++ b/Hledger/Cli/Commands/Print.hs
@@ -37,7 +37,7 @@
 import Hledger.Write.Beancount (accountNameToBeancount, showTransactionBeancount, showBeancountMetadata)
 import Hledger.Write.Csv (CSV, printCSV, printTSV)
 import Hledger.Write.Ods (printFods)
-import Hledger.Write.Html.Lucid (printHtml)
+import Hledger.Write.Html.Lucid (styledTableHtml)
 import qualified Hledger.Write.Spreadsheet as Spr
 import Hledger.Cli.CliOptions
 import Hledger.Cli.Utils
@@ -54,6 +54,7 @@
   ,flagNone ["show-costs"] (setboolopt "show-costs")
     "show transaction prices even with conversion postings"
   ,roundFlag
+  ,flagNone ["invert"] (setboolopt "invert") "display all amounts with reversed sign"
   ,flagNone ["new"] (setboolopt "new")
     "show only newer-dated transactions added in each file since last run"
   ,let arg = "DESC" in
@@ -71,9 +72,9 @@
   intercalate "\n"
   ["how much rounding or padding should be done when displaying amounts ?"
   ,"none - show original decimal digits,"
-  ,"       as in journal"
+  ,"       as in journal (default)"
   ,"soft - just add or remove decimal zeros"
-  ,"       to match precision (default)"
+  ,"       to match precision"
   ,"hard - round posting amounts to precision"
   ,"       (can unbalance transactions)"
   ,"all  - also round cost amounts to precision"
@@ -142,7 +143,7 @@
            | fmt=="json"      = toJsonText                    . styleAmounts styles
            | fmt=="sql"       = entriesReportAsSql            . styleAmounts styles
            | fmt=="html" =
-                (<>"\n") . Lucid.renderText . printHtml .
+                (<>"\n") . Lucid.renderText . styledTableHtml .
                 map (map (fmap Lucid.toHtml)) .
                 entriesReportAsSpreadsheet oneLineNoCostFmt baseUrl query .
                 styleAmounts styles
@@ -158,6 +159,7 @@
           -- with -x/--explicit:
           | boolopt "explicit" (rawopts_ opts) = id
           -- with --show-costs:
+          -- XXX infer_costs is --infer-costs not --show-costs. And where is show-costs used anyway ?
           | opts ^. infer_costs = id
           -- with -B/-V/-X/--value ("because of #551, and because of print -V valuing only one posting when there's an implicit txn price.")
           | has (value . _Just) opts = id
diff --git a/Hledger/Cli/Commands/Print.txt b/Hledger/Cli/Commands/Print.txt
--- a/Hledger/Cli/Commands/Print.txt
+++ b/Hledger/Cli/Commands/Print.txt
@@ -9,13 +9,14 @@
      --round=TYPE           how much rounding or padding should be done when
                             displaying amounts ?
                             none - show original decimal digits,
-                                   as in journal
+                                   as in journal (default)
                             soft - just add or remove decimal zeros
-                                   to match precision (default)
+                                   to match precision
                             hard - round posting amounts to precision
                                    (can unbalance transactions)
                             all  - also round cost amounts to precision
                                    (can unbalance transactions)
+     --invert               display all amounts with reversed sign
      --new                  show only newer-dated transactions added in each
                             file since last run
   -m --match=DESC           fuzzy search for one recent transaction with
@@ -117,6 +118,10 @@
 print, other features
 
 With -B/--cost, amounts with costs are shown converted to cost.
+
+With --invert, posting amounts are shown with their sign flipped. It
+could be useful if you have accidentally recorded some transactions with
+the wrong signs.
 
 With --new, print shows only transactions it has not seen on a previous
 run. This uses the same deduplication system as the import command. (See
diff --git a/Hledger/Cli/Commands/Register.hs b/Hledger/Cli/Commands/Register.hs
--- a/Hledger/Cli/Commands/Register.hs
+++ b/Hledger/Cli/Commands/Register.hs
@@ -31,7 +31,7 @@
 import Hledger hiding (per)
 import Hledger.Write.Csv (CSV, printCSV, printTSV)
 import Hledger.Write.Ods (printFods)
-import Hledger.Write.Html.Lucid (printHtml)
+import Hledger.Write.Html.Lucid (styledTableHtml)
 import qualified Hledger.Write.Spreadsheet as Spr
 import Hledger.Cli.CliOptions
 import Hledger.Cli.Utils
@@ -67,7 +67,7 @@
 #else
       "terminal width"
 #endif
-      ++ " or $COLUMNS). -wN,M sets description width as well."
+      ++ "). -wN,M sets description width as well."
      )
   ,flagNone ["align-all"] (setboolopt "align-all") "guarantee alignment across all lines (slower)"
   ,flagReq  ["base-url"] (\s opts -> Right $ setopt "base-url" s opts) "URLPREFIX" "in html output, generate links to hledger-web, with this prefix. (Usually the base url shown by hledger-web; can also be relative.)"
@@ -103,7 +103,7 @@
            | fmt=="csv"  = printCSV . postingsReportAsCsv
            | fmt=="tsv"  = printTSV . postingsReportAsCsv
            | fmt=="html" =
-                (<>"\n") . Lucid.renderText . printHtml .
+                (<>"\n") . Lucid.renderText . styledTableHtml .
                 map (map (fmap Lucid.toHtml)) .
                 postingsReportAsSpreadsheet oneLineNoCostFmt baseUrl query
            | fmt=="fods" =
@@ -304,7 +304,7 @@
 
    testGroup "postingsReportAsText" [
     testCase "unicode in register layout" $ do
-      j <- readJournal' "2009/01/01 * медвежья шкура\n  расходы:покупки  100\n  актив:наличные\n"
+      j <- readJournal'' "2009/01/01 * медвежья шкура\n  расходы:покупки  100\n  актив:наличные\n"
       let rspec = defreportspec
       (TL.unpack . postingsReportAsText defcliopts $ postingsReport rspec j)
         @?=
diff --git a/Hledger/Cli/Commands/Register.txt b/Hledger/Cli/Commands/Register.txt
--- a/Hledger/Cli/Commands/Register.txt
+++ b/Hledger/Cli/Commands/Register.txt
@@ -18,8 +18,8 @@
      --sort=FIELDS          sort by: date, desc, account, amount, absamount,
                             or a comma-separated combination of these. For a
                             descending sort, prefix with -. (Default: date)
-  -w --width=N              set output width (default: terminal width or
-                            $COLUMNS). -wN,M sets description width as well.
+  -w --width=N              set output width (default: terminal width). -wN,M
+                            sets description width as well.
      --align-all            guarantee alignment across all lines (slower)
      --base-url=URLPREFIX   in html output, generate links to hledger-web,
                             with this prefix. (Usually the base url shown by
@@ -132,9 +132,8 @@
 
 Custom register output
 
-register uses the full terminal width by default, except on windows. You
-can override this by setting the COLUMNS environment variable (not a
-bash shell variable) or by using the --width/-w option.
+register normally uses the full terminal width (or 80 columns if it
+can't detect that). You can override this with 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 @@
 
 $ 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),
diff --git a/Hledger/Cli/Commands/Repl.txt b/Hledger/Cli/Commands/Repl.txt
new file mode 100644
--- /dev/null
+++ b/Hledger/Cli/Commands/Repl.txt
@@ -0,0 +1,67 @@
+repl
+
+Start an interactive prompt, where you can run any of hledger's
+commands. Data files are parsed just once, so the commands run faster.
+
+Flags:
+no command-specific flags
+
+This command is experimental and could change in the future.
+
+hledger repl starts a read-eval-print loop (REPL) where you can enter
+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.
+
+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, and
+commands will not see any changes made to input files (eg by add) until
+you exit and restart the REPL.
+
+The command syntax is the same as with run:
+
+-   enter one hledger command at a time, without the usual hledger first
+    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.
+
+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.
+
+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
+useful.
+
+You can type control-C to cancel a long-running command (but only once;
+typing it a second time will exit 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
diff --git a/Hledger/Cli/Commands/Roi.hs b/Hledger/Cli/Commands/Roi.hs
--- a/Hledger/Cli/Commands/Roi.hs
+++ b/Hledger/Cli/Commands/Roi.hs
@@ -20,14 +20,13 @@
 import Data.Time.Calendar
 import Text.Printf
 import Data.Bifunctor (second)
-import Data.Either (fromLeft, fromRight, isLeft)
 import Data.Function (on)
 import Data.List
 import Numeric.RootFinding
 import Data.Decimal
 import qualified Data.Text as T
 import qualified Data.Text.Lazy.IO as TL
-import Safe (headDef, tailDef)
+import Safe (headDef, lastMay)
 import System.Console.CmdArgs.Explicit as CmdArgs
 
 import Text.Tabular.AsciiWide as Tab
@@ -99,8 +98,6 @@
 
   let (fullPeriod, spans) = reportSpan filteredj rspec
 
-  let priceDirectiveDates = dbg3 "priceDirectiveDates" $ map pddate $ jpricedirectives j
-
   let processSpan (DateSpan Nothing _) = error "Undefined start of the period - will be unable to compute the rates of return"
       processSpan (DateSpan _ Nothing) = error "Undefined end of the period - will be unable to compute the rates of return"
       processSpan spn@(DateSpan (Just begin) (Just end)) = do
@@ -120,9 +117,7 @@
             total trans (And [investmentsQuery
                              , Date (DateSpan Nothing (Just end))])
 
-          priceDates = dbg3 "priceDates" $ nub $ filter (spanContainsDate spn) priceDirectiveDates
-          cashFlow =
-            ((map (,nullmixedamt) priceDates)++) $
+          cashFlow = dbg3 "cashFlow" $
             cashFlowApplyCostValue $
             calculateCashFlow wd trans (And [ Not investmentsQuery
                                             , Not pnlQuery
@@ -159,7 +154,9 @@
                , T.pack $ printf "%0.2f%%" $ smallIsZero annualizedTwr ]
 
   periodRows <- forM spans processSpan
-  totalRow <- processSpan fullPeriod
+  totalRow <- case periodRows of
+    [singleRow] -> return singleRow
+    _           -> processSpan fullPeriod
 
   let rowTitles = Tab.Group Tab.NoLine (map (Header . T.pack . show) (take (length periodRows) [1..]))
 
@@ -179,116 +176,116 @@
 
   TL.putStrLn $ Tab.render prettyTables id id id table
 
-timeWeightedReturn styles showCashFlow prettyTables investmentsQuery trans mixedAmountValue (OneSpan begin end valueBeforeAmt valueAfter cashFlow pnl) = do
-  let valueBefore = unMix valueBeforeAmt
-  let initialUnitCost = 100 :: Decimal
-  let initialUnits = valueBefore / initialUnitCost
-  let changes =
-        -- If cash flow and PnL changes happen on the same day, this
-        -- will sort PnL changes to come before cash flows (on any
-        -- given day), so that we will have better unit price computed
-        -- first for processing cash flow. This is why pnl changes are Left
-        -- and cashflows are Right.
-        -- However, if the very first date in the changes list has both
-        -- PnL and CashFlow, we would not be able to apply pnl change to 0 unit,
-        -- which would lead to an error. We make sure that we have at least one
-        -- cashflow entry at the front, and we know that there would be at most
-        -- one for the given date, by construction. Empty CashFlows added
-        -- because of a begin date before the first transaction are not seen as
-        -- a valid cashflow entry at the front.
-        zeroUnitsNeedsCashflowAtTheFront
+-- Entry for TWR computation, capturing all cashflows that are potentially accompanied by pnl change on the same day (if not, it is zero)
+data TwrEntry = TwrEntry { twrDate :: Day, twrCashflow :: Decimal, twrValueAfter :: Decimal, twrPnl :: Decimal } deriving (Eq, Show)
+
+timeWeightedReturn _styles showCashFlow prettyTables investmentsQuery trans mixedAmountValue (OneSpan begin end valueBeforeAmt valueAfterAmt cashflows pnls) = do
+  let datedCashflows =
+        -- Aggregate all entries for a single day, assuming that intraday interest is negligible
+        dbg3 "datedCashflows"
         $ sort
-        $ datedCashflows ++ datedPnls
-        where
-          zeroUnitsNeedsCashflowAtTheFront changes1 =
-            if initialUnits > 0 then changes1
-            else
-              let (leadingEmptyCashFlows, rest) = span isEmptyCashflow changes1
-                  (leadingPnls, rest') = span (isLeft . snd) rest
-                  (firstCashflow, rest'') = splitAt 1 rest'
-              in leadingEmptyCashFlows ++ firstCashflow ++ leadingPnls ++ rest''
+        $ map (\datecashes -> let (dates, cash) = unzip datecashes in (headDef (error' "Roi.hs: datecashes was null, please report a bug") dates, maSum cash))
+        $ groupBy ((==) `on` fst)
+        $ sortOn fst
+        $ map (second maNegate)
+        $ cashflows
 
-          isEmptyCashflow (_date, amt) = case amt of
-            Right amt' -> mixedAmountIsZero amt'
-            Left _     -> False
+      valueBefore = unMix valueBeforeAmt
+      valueAfter = unMix valueAfterAmt
+      
+      investmentPostings = concatMap (filter (matchesPosting investmentsQuery) . realPostings) trans
 
-          datedPnls = map (second Left) $ aggregateByDate pnl
+      totalInvestmentPostingsTill date = sumPostings $ filter (matchesPosting (Date (DateSpan Nothing (Just $ Exact date)))) investmentPostings
 
-          datedCashflows = map (second Right) $ aggregateByDate cashFlow
+      -- filter span is (-infinity, date+1), which gives us effectively (-infinity, date]
+      valueAfterDate date = unMix $ mixedAmountValue end date $ totalInvestmentPostingsTill (addDays 1 date)
 
-          aggregateByDate datedAmounts =
-            -- Aggregate all entries for a single day, assuming that intraday interest is negligible
-            sort
-            $ map (\datecashes -> let (dates, cash) = unzip datecashes in (headDef (error' "Roi.hs: datecashes was null, please report a bug") dates, maSum cash))
-            $ groupBy ((==) `on` fst)
-            $ sortOn fst
-            $ map (second maNegate)
-            $ datedAmounts
+      -- We are dividing the period [begin, end) into subperiods on each cashflow, and then compute
+      -- the rate of return for each subperiod. For this we need to know the value of the investment
+      -- at the beginning and end of each subperiod, adjusted for cashflow.
+      -- 
+      -- Subperiods are going to be [valueBefore ... (c_0,v_0)][... (c_1, v_1)][... (c_2,v_2)] ... [... (c_n,v_n)][... valueAfter]
+      -- , where v_i is the value of investment computed immediately after cashflow c_i
+      addEnd cflows =
+        case lastMay cflows of
+          Nothing -> cflows
+          Just entry ->
+            let end_ = addDays (-1) end in
+              if twrDate entry < end_ then cflows++[TwrEntry end_ 0 valueAfter (pnlOn end_)] else cflows
 
-  let units =
-        tailDef (error' "Roi.hs units was null, please report a bug") $
-        scanl
-          (\(_, _, unitCost, unitBalance) (date, amt) ->
-             let valueOnDate = unMix $ mixedAmountValue end date $ total trans (And [investmentsQuery, Date (DateSpan Nothing (Just $ Exact date))])
-             in
-             case amt of
-               Right amt' ->
-                 -- we are buying or selling
-                 let unitsBoughtOrSold = unMix amt' / unitCost
-                 in (valueOnDate, unitsBoughtOrSold, unitCost, unitBalance + unitsBoughtOrSold)
-               Left pnl' ->
-                 -- PnL change
-                 let valueAfterDate = valueOnDate + unMix pnl'
-                     unitCost' =
-                       if unitBalance == 0 then initialUnitCost -- everything was sold, let's reset the cost to initial cost
-                       else valueAfterDate/unitBalance
-                 in (valueOnDate, 0, unitCost', unitBalance))
-          (0, 0, initialUnitCost, initialUnits)
-          $ dbg3 "changes" changes
+      pnlOn date = unMix $ maNegate $ sum $ map snd $ filter ((==date).fst) pnls
 
-  let finalUnitBalance = if null units then initialUnits else let (_,_,_,u) = last units in u
-      finalUnitCost = if finalUnitBalance == 0 then
-                         if null units then initialUnitCost
-                         else let (_,_,lastUnitCost,_) = last units in lastUnitCost
-                       else (unMix valueAfter) / finalUnitBalance
-      -- Technically, totalTWR should be (100*(finalUnitCost - initialUnitCost) / initialUnitCost), but initalUnitCost is 100, so 100/100 == 1
-      totalTWR = roundTo 2 $ (finalUnitCost - initialUnitCost)
+      twrEntries =
+        dbg3 "twrEntries"
+        $ addEnd
+        $ concatMap (\(date,cashflow) ->
+                        let pnl = pnlOn date
+                            cash = unMix cashflow
+                            value_ = valueAfterDate date - pnl - cash -- valueAfterDate includes both cashflow and pnl on date, if any
+                        in
+                        -- if we had PnL postings on the same day as cashflow,
+                        -- we want to account for them separately. If pnl is positive, we apply pnl first, and if pnl was negative
+                        -- we apply cashflow first, in an attempt to avoid having negative valuations and ugly debug output (and
+                        -- computations as well)
+                        if pnl == 0 then [TwrEntry date cash (value_ + cash) 0]
+                        else if pnl > 0  
+                             then [TwrEntry date 0 (value_ + pnl)   pnl, TwrEntry date cash (value_ + cash + pnl) 0]
+                             else [TwrEntry date cash (value_ + cash) 0, TwrEntry date 0    (value_ + cash + pnl) pnl]
+                    ) datedCashflows
+
+  -- Calculate interest for each subperiod, adjusting the value at the start of the period by the cashflow
+  -- For subperiods [valueBefore ... (c_0,v_0)][... (c_1, v_1)][... (c_2,v_2)] ... [... (c_n,v_n)][... valueAfter], the computation is going to be
+  -- 1 + twr = (v_0 - c_0)/valueBefore + (v_1 - c_1) / v_0 +  ... + valueAfter/v_n
+  -- See https://en.wikipedia.org/wiki/Time-weighted_return#Time-weighted_return_compensating_for_external_flows
+  let calculateSubPeriods _ [] = []
+      calculateSubPeriods  prev (curr:rest) =
+        let adjustedEnd = twrValueAfter curr - twrCashflow curr in
+          let subPeriodReturn =
+                if twrValueAfter prev == 0 || adjustedEnd == 0
+                then 1
+                else adjustedEnd / (twrValueAfter prev)
+          in (subPeriodReturn, (prev, curr)) : calculateSubPeriods curr rest
+
+  let subPeriods = dbg3 "subPeriods" $ calculateSubPeriods (TwrEntry begin 0 valueBefore (pnlOn begin)) twrEntries
+
+  -- Compute overall time-weighted rate of return
+  let twr =
+        dbg3 "twr" $
+        if subPeriods == []
+        then if valueBefore == 0 then 0 else (valueAfter - valueBefore)/valueBefore
+        else (product $ map fst subPeriods) - 1
       (startYear, _, _) = toGregorian begin
       years = fromIntegral (diffDays end begin) / (if isLeapYear startYear then 366 else 365) :: Double
-      annualizedTWR = 100*((1+(realToFrac totalTWR/100))**(1/years)-1) :: Double
+      periodTWR = roundTo 2 $ 100 * twr
+      annualizedTWR = 100*((1+(realToFrac twr))**(1/years)-1) :: Double
 
   when showCashFlow $ do
-    printf "\nTWR cash flow for %s - %s\n" (showDate begin) (showDate (addDays (-1) end))
-    let (dates', amts) = unzip changes
-        cashflows' = map (fromRight nullmixedamt) amts
-        pnls = map (fromLeft nullmixedamt) amts
-        (valuesOnDate,unitsBoughtOrSold', unitPrices', unitBalances') = unzip4 units
-        add x lst = if valueBefore/=0 then x:lst else lst
-        dates = add begin dates'
-        cashflows = add valueBeforeAmt cashflows'
-        unitsBoughtOrSold = add initialUnits unitsBoughtOrSold'
-        unitPrices = add initialUnitCost unitPrices'
-        unitBalances = add initialUnits unitBalances'
-
-    TL.putStr $ Tab.render prettyTables id id T.pack
+    printf "\nTWR cash flow entries and subperiod rates for period %s - %s\n" (showDate begin) (showDate (addDays (-1) end))
+    let showDecimalT = T.pack . showDecimal
+    let dates = map twrDate twrEntries
+    TL.putStrLn $ Tab.render prettyTables id id id
       (Table
-       (Tab.Group NoLine (map (Header . showDate) dates))
-       (Tab.Group DoubleLine [ Tab.Group Tab.SingleLine [Tab.Header "Portfolio value", Tab.Header "Unit balance"]
-                         , Tab.Group Tab.SingleLine [Tab.Header "Pnl", Tab.Header "Cashflow", Tab.Header "Unit price", Tab.Header "Units"]
-                         , Tab.Group Tab.SingleLine [Tab.Header "New Unit Balance"]])
-       [ [val, oldBalance, pnl', cashflow, prc, udelta, balance]
-       | val <- map showDecimal valuesOnDate
-       | oldBalance <- map showDecimal (0:unitBalances)
-       | balance <- map showDecimal unitBalances
-       | pnl' <- map (showMixedAmountOneLineWithoutCost False . styleAmounts styles) pnls
-       | cashflow <- map (showMixedAmountOneLineWithoutCost False . styleAmounts styles) cashflows
-       | prc <- map showDecimal unitPrices
-       | udelta <- map showDecimal unitsBoughtOrSold ])
+       (Tab.Group Tab.NoLine (map (Header . showDate) dates))
+       (Tab.Group Tab.SingleLine [Header "Amount", Header "PnL on this day", Header "Value afterwards" ])
+       ( [ [ showDecimalT (twrCashflow e), showDecimalT (twrPnl e), showDecimalT (twrValueAfter e) ]
+         | e <- twrEntries ]))
+    
+    TL.putStr $ Tab.render prettyTables T.pack id id
+      (Table
+       (Tab.Group Tab.NoLine [ Header (show n) | n <-[1..length subPeriods]])
+       (Tab.Group DoubleLine [ Tab.Group Tab.SingleLine [Tab.Header "Subperiod start", Tab.Header "Subperiod end"]
+                             , Tab.Group Tab.SingleLine [Tab.Header "Value at start", Tab.Header "Cashflow", Tab.Header "PnL postings", Tab.Header "Value at end"]
+                             , Tab.Group Tab.SingleLine [Tab.Header "Subperiod return rate"]])
+       [ [ showDate (twrDate prev), showDate (twrDate curr)
+         , showDecimalT (twrValueAfter prev - twrCashflow prev), showDecimalT (twrCashflow prev), showDecimalT (twrPnl prev), showDecimalT (twrValueAfter curr - twrCashflow curr)
+         , showDecimalT rate ]
+       | (rate, (prev, curr)) <-  subPeriods
+       ])
 
-    printf "Final unit price: %s/%s units = %s\nTotal TWR: %s%%.\nPeriod: %.2f years.\nAnnualized TWR: %.2f%%\n\n"
-      (showMixedAmountOneLineWithoutCost False $ styleAmounts styles valueAfter) (showDecimal finalUnitBalance) (showDecimal finalUnitCost) (showDecimal totalTWR) years annualizedTWR
+    printf "Total period TWR: %s%%.\nPeriod: %.2f years.\nAnnualized TWR: %.2f%%\n\n"
+      (showDecimal periodTWR) years annualizedTWR
 
-  return ((realToFrac totalTWR) :: Double, annualizedTWR)
+  return ((realToFrac periodTWR) :: Double, annualizedTWR)
 
 internalRateOfReturn styles showCashFlow prettyTables (OneSpan begin end valueBefore valueAfter cashFlow _pnl) = do
   let prefix = (begin, maNegate valueBefore)
diff --git a/Hledger/Cli/Commands/Run.hs b/Hledger/Cli/Commands/Run.hs
new file mode 100644
--- /dev/null
+++ b/Hledger/Cli/Commands/Run.hs
@@ -0,0 +1,260 @@
+{-|
+
+The @run@ command allows you to run multiple commands via REPL or from the supplied file(s).
+
+-}
+
+{-# LANGUAGE MultiWayIf #-}
+{-# LANGUAGE OverloadedStrings #-}
+{-# LANGUAGE ScopedTypeVariables #-}
+{-# LANGUAGE TemplateHaskell #-}
+
+module Hledger.Cli.Commands.Run (
+  runmode
+ ,run
+ ,replmode
+ ,repl
+ ,runOrReplStub
+) where
+
+import qualified Data.List.NonEmpty as NE
+import qualified Data.Map.Strict as Map
+import Data.Semigroup (sconcat)
+import qualified Data.Text as T
+import qualified Data.Text.IO as T
+import System.Console.CmdArgs.Explicit as C ( Mode )
+import Hledger
+import Hledger.Cli.CliOptions
+
+import Control.Exception
+import Control.Concurrent.MVar
+import Control.Monad (forM_)
+import Control.Monad.IO.Class (liftIO)
+import Control.Monad.Extra (concatMapM)
+
+import System.Exit (ExitCode, exitWith)
+import System.Console.CmdArgs.Explicit (expandArgsAt, modeNames)
+import System.IO (stdin, hIsTerminalDevice, hIsOpen)
+import System.IO.Unsafe (unsafePerformIO)
+import System.Console.Haskeline
+
+import Safe (headMay)
+import Hledger.Cli.DocFiles (runTldrForPage, runInfoForTopic, runManForTopic)
+import Hledger.Cli.Utils (journalTransform)
+import Text.Printf (printf)
+import System.Process (system)
+
+-- | Command line options for this command.
+runmode = hledgerCommandMode
+  $(embedFileRelative "Hledger/Cli/Commands/Run.txt")
+  (
+  []
+  )
+  cligeneralflagsgroups1
+  hiddenflags
+  ([], Just $ argsFlag "[COMMANDS_FILE1 COMMANDS_FILE2 ...] OR [-- command1 args... -- command2 args... -- command3 args...]")
+
+replmode = hledgerCommandMode
+  $(embedFileRelative "Hledger/Cli/Commands/Repl.txt")
+  (
+  []
+  )
+  cligeneralflagsgroups1
+  hiddenflags
+  ([], Nothing)
+
+-- | The fake run/repl command introduced to break circular dependency.
+-- This module needs access to `findBuiltinCommand`, which is defined in Hledger.Cli.Commands
+-- However, Hledger.Cli.Commands imports this module, which creates circular dependency.
+-- We expose this do-nothing function so that it could be included in the list of all commands inside
+-- Hledger.Cli.Commands and ensure that "run" is recognized as a valid command by the Hledger.Cli top-level
+-- command line parser. That parser, however, would not call run'. It has a special case for "run", and
+-- will call "run" (see below), passing it `findBuiltinCommand`, thus breaking circular dependency.
+runOrReplStub :: CliOpts -> Journal -> IO ()
+runOrReplStub _opts _j = return ()
+
+-- | Default input files that would be used by commands if
+--   there is no explicit alternative given
+newtype DefaultRunJournal = DefaultRunJournal (NE.NonEmpty String) deriving (Show)
+
+-- | The actual run command.
+run :: Maybe DefaultRunJournal -> (String -> Maybe (Mode RawOpts, CliOpts -> Journal -> IO ())) -> [String] -> CliOpts -> IO ()
+run defaultJournalOverride findBuiltinCommand addons cliopts@CliOpts{rawopts_=rawopts} = do
+  withJournalCached defaultJournalOverride cliopts $ \(_,key) -> do
+    let args = dbg1 "args" $ listofstringopt "args" rawopts
+    isTerminal <- isStdinTerminal
+    if args == [] && not isTerminal
+      then do
+        inputFiles <- journalFilePathFromOpts cliopts
+        let journalFromStdin = any (== "-") $ map (snd . splitReaderPrefix) $ NE.toList inputFiles
+        if journalFromStdin
+        then error' "'run' can't read commands from stdin, as one of the input files was stdin as well"
+        else runREPL key findBuiltinCommand addons
+      else do
+        -- Check if arguments start with "--".
+        -- If not, assume that they are files with commands
+          case args of
+            "--":_ -> runFromArgs  key findBuiltinCommand addons args
+            _      -> runFromFiles key findBuiltinCommand addons args
+
+-- | The actual repl command.
+repl :: (String -> Maybe (Mode RawOpts, CliOpts -> Journal -> IO ())) -> [String] -> CliOpts -> IO ()
+repl findBuiltinCommand addons cliopts = do
+  withJournalCached Nothing cliopts $ \(_,key) -> do
+    runREPL key findBuiltinCommand addons
+
+-- | Run commands from files given to "run".
+runFromFiles :: DefaultRunJournal -> (String -> Maybe (Mode RawOpts, CliOpts -> Journal -> IO ())) -> [String] -> [String] -> IO ()
+runFromFiles defaultJournalOverride findBuiltinCommand addons inputfiles = do
+  dbg1IO "inputfiles" inputfiles
+  -- read commands from all the inputfiles
+  commands <- (flip concatMapM) inputfiles $ \f -> do
+    dbg1IO "reading commands" f
+    lines . T.unpack <$> T.readFile f
+
+  forM_ commands (runCommand defaultJournalOverride findBuiltinCommand addons . parseCommand)
+
+-- | Run commands from command line arguments given to "run".
+runFromArgs :: DefaultRunJournal -> (String -> Maybe (Mode RawOpts, CliOpts -> Journal -> IO ())) -> [String] -> [String] -> IO ()
+runFromArgs defaultJournalOverride findBuiltinCommand addons args = do
+  -- read commands from all the inputfiles
+  let commands = dbg1 "commands from args" $ splitAtElement "--" args
+  forM_ commands (runCommand defaultJournalOverride findBuiltinCommand addons)
+
+-- When commands are passed on the command line, shell will parse them for us
+-- When commands are read from file, we need to split the line into command and arguments
+parseCommand :: String -> [String]
+parseCommand line =
+  -- # begins a comment, ignore everything after #
+  takeWhile (not. ((Just '#')==) . headMay) $  words' (strip line)
+
+-- | Take a single command line (from file, or REPL, or "--"-surrounded block of the args), and run it.
+runCommand :: DefaultRunJournal -> (String -> Maybe (Mode RawOpts, CliOpts -> Journal -> IO ())) -> [String] -> [String] -> IO ()
+runCommand defaultJournalOverride findBuiltinCommand addons cmdline = do
+  dbg1IO "runCommand for" cmdline
+  case cmdline of
+    "echo":args -> putStrLn $ unwords $ args
+    cmdname:args ->
+      case findBuiltinCommand cmdname of
+        Just (cmdmode,cmdaction) -> do
+              -- Even though expandArgsAt is done by the Cli.hs, it stops at the first '--', so we need
+              -- to do it here as well to make sure that each command can use @ARGFILEs
+              args' <- replaceNumericFlags <$> expandArgsAt args
+              dbg1IO "runCommand final args" (cmdname,args')
+              opts <- getHledgerCliOpts' cmdmode args'
+              let
+                rawopts      = rawopts_ opts
+                mmodecmdname = headMay $ modeNames cmdmode
+                helpFlag     = boolopt "help"    rawopts
+                tldrFlag     = boolopt "tldr"    rawopts
+                infoFlag     = boolopt "info"    rawopts
+                manFlag      = boolopt "man"     rawopts
+              if
+                | helpFlag  -> runPager $ showModeUsage cmdmode ++ "\n"
+                | tldrFlag  -> runTldrForPage $ maybe "hledger" (("hledger-"<>)) mmodecmdname
+                | infoFlag  -> runInfoForTopic "hledger" mmodecmdname
+                | manFlag   -> runManForTopic "hledger"  mmodecmdname
+                | otherwise -> do
+                  withJournalCached (Just defaultJournalOverride) opts $ \(j,key) -> do
+                    if cmdname == "run" -- allow "run" to call "run"
+                      then run (Just key) findBuiltinCommand addons opts
+                      else cmdaction opts j
+        Nothing | cmdname `elem` addons ->
+          system (printf "%s-%s %s" progname cmdname (unwords' args)) >>= exitWith
+        Nothing ->
+          error' $ "Unrecognized command: " ++ unwords (cmdname:args)
+    [] -> return ()
+
+-- | Run an interactive REPL.
+runREPL :: DefaultRunJournal -> (String -> Maybe (Mode RawOpts, CliOpts -> Journal -> IO ())) -> [String] -> IO ()
+runREPL defaultJournalOverride findBuiltinCommand addons = do
+  isTerminal <- isStdinTerminal
+  if not isTerminal
+    then runInputT defaultSettings (loop "")
+    else do
+      putStrLn "Enter hledger commands. To exit, enter 'quit' or 'exit', or send EOF."
+      runInputT defaultSettings (loop "% ")
+  where
+  loop :: String -> InputT IO ()
+  loop prompt = do
+    minput <- getInputLine prompt
+    case minput of
+      Nothing -> return ()
+      Just "quit" -> return ()
+      Just "exit" -> return ()
+      Just input -> do
+        liftIO $ (runCommand defaultJournalOverride findBuiltinCommand addons $ argsAddDoubleDash $ parseCommand input)
+                  `catches`
+                  [Handler (\(e::ErrorCall) -> putStrLn $ rstrip $ show e)
+                  ,Handler (\(e::IOError)   -> putStrLn $ rstrip $ show e)
+                  ,Handler (\(_::ExitCode)  -> return ())
+                  ,Handler (\UserInterrupt  -> return ())
+                  ]
+        loop prompt
+
+isStdinTerminal = do
+  op <- hIsOpen stdin
+  if op then hIsTerminalDevice stdin else return False
+
+-- | Cache of all journals that have been read by commands given to "run",
+-- keyed by the fully-expanded filename.
+journalCache :: MVar (Map.Map (InputOpts,PrefixedFilePath) Journal)
+journalCache = unsafePerformIO $ newMVar Map.empty
+{-# NOINLINE journalCache #-}
+
+-- | Cache of stdin contents, so that we can re-read it if InputOptions change
+stdinCache :: MVar (Maybe T.Text)
+stdinCache = unsafePerformIO $ newMVar Nothing
+{-# NOINLINE stdinCache #-}
+
+-- | Similar to `withJournal`, but uses caches all the journals it reads.
+-- When reading from stdin, caches the stdin contents so that we could reprocess
+-- it if a read with different InputOptions is requested.
+withJournalCached :: Maybe DefaultRunJournal -> CliOpts -> ((Journal, DefaultRunJournal) -> IO ()) -> IO ()
+withJournalCached defaultJournalOverride cliopts cmd = do
+  (j,key) <- case defaultJournalOverride of
+    Nothing -> journalFilePathFromOpts cliopts >>= readFiles
+    Just (DefaultRunJournal defaultFiles) -> do
+      mbjournalpaths <- journalFilePathFromOptsNoDefault cliopts
+      case mbjournalpaths of
+        Nothing -> readFiles defaultFiles -- use the journal(s) given to the "run" itself
+        Just journalpaths -> readFiles journalpaths
+  cmd (j,key)
+  where
+    readFiles journalpaths = do
+      j <- journalTransform cliopts . sconcat <$> mapM (readAndCacheJournalFile (inputopts_ cliopts)) journalpaths
+      return (j, DefaultRunJournal journalpaths)
+    -- | Read a journal file, caching it (and InputOptions used to read it) if it has not been seen before.
+    -- If the same file is requested with different InputOptions, we read it anew and cache
+    -- it separately.
+    readAndCacheJournalFile :: InputOpts -> PrefixedFilePath -> IO Journal
+    readAndCacheJournalFile iopts fp = do
+      modifyMVar journalCache $ \cache ->
+        case Map.lookup (ioptsWithoutReportSpan,fp) cache of
+          Just journal -> do
+            dbg1IO ("readAndCacheJournalFile using cache for "++fp) iopts
+            return (cache, journal)
+          Nothing -> do
+            dbg1IO ("readAndCacheJournalFile reading and caching "++fp) iopts
+            journal <- runExceptT $ if snd (splitReaderPrefix fp) == "-" then readStdin else readJournalFile iopts fp
+            either error' (\j -> return (Map.insert (ioptsWithoutReportSpan,fp) j cache, j)) journal
+      where
+        -- InputOptions contain reportspan_ that is used to calculare forecast period,
+        -- that is used by journalFinalise to insert forecast transactions.addHeaderBorders
+        -- For the purposes of caching, we want to ignore this, as it is only used for forecast
+        -- and it is sufficient to include forecast_ in the InputOptions that we use as a key.
+        ioptsWithoutReportSpan = iopts { reportspan_ = emptydatespan }
+        -- Read stdin, or if we read it alread, use a cache
+        -- readStdin :: InputOpts -> ExceptT String IO Journal
+        readStdin = do
+          stdinContent <- liftIO $ modifyMVar stdinCache $ \cache ->
+            case cache of
+              Just cached -> do
+                dbg1IO "readStdin using cached stdin" "-"
+                return (cache, cached)
+              Nothing -> do
+                dbg1IO "readStdin reading and caching stdin" "-"
+                stdinContent <- readFileOrStdinPortably "-"
+                return (Just stdinContent, stdinContent)
+          hndl <- liftIO $ inputToHandle stdinContent
+          readJournal iopts Nothing hndl
diff --git a/Hledger/Cli/Commands/Run.txt b/Hledger/Cli/Commands/Run.txt
new file mode 100644
--- /dev/null
+++ b/Hledger/Cli/Commands/Run.txt
@@ -0,0 +1,86 @@
+run
+
+Run a sequence of hledger commands, provided as files or command line
+arguments. Data files are parsed just once, so the commands run faster.
+
+Flags:
+no command-specific flags
+
+This command is experimental and could change in the future.
+
+You can use run in three ways:
+
+-   hledger run -- CMD1 -- CMD2 -- CMD3 - read commands from the command
+    line, separated by --
+-   hledger run SCRIPTFILE1 SCRIPTFILE2 - read commands from one or more
+    files
+-   cat SCRIPTFILE1 | hledger run - read commands from standard input.
+
+run first loads the input file(s) specified by LEDGER_FILE or by -f
+options, in the usual way. Then it runs each command in turn, each using
+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.
+
+Each input file (more precisely, each combination of input file and
+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).
+
+Command scripts, whether in a file or written on the command line, have
+a simple syntax:
+
+-   each line may contain a single hledger command and its arguments,
+    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.
+
+On unix systems you can use #!/usr/bin/env hledger run in the first line
+of a command file to make it a runnable script. 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,
+
+-   the command name must be written first, options afterward
+-   full command names or official abbreviations (as in the command
+    list) must be used
+
+Examples
+
+Run commands specified on the command line:
+
+hledger -f some.journal run -- 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 run stats on some.journal
+
+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
+
+echo "Assets of some.journal"
+balance assets --depth 2
+
+echo "Liabilities from /some/other.journal"
+balance liabilities -f /some/other.journal --depth 3 --transpose
+
+echo "Commands from another.script, applied to another.journal"
+run -f another.journal another.script
diff --git a/Hledger/Cli/CompoundBalanceCommand.hs b/Hledger/Cli/CompoundBalanceCommand.hs
--- a/Hledger/Cli/CompoundBalanceCommand.hs
+++ b/Hledger/Cli/CompoundBalanceCommand.hs
@@ -14,9 +14,11 @@
  ,compoundBalanceCommand
 ) where
 
-import Data.Maybe (fromMaybe, mapMaybe, maybeToList)
-import Data.List.NonEmpty (NonEmpty((:|)))
+import Control.Monad (guard)
 import Data.Bifunctor (second)
+import Data.Function ((&))
+import Data.List.NonEmpty (NonEmpty((:|)))
+import Data.Maybe (fromMaybe, mapMaybe, maybeToList)
 import qualified Data.Map as Map
 import qualified Data.List as List
 import qualified Data.List.NonEmpty as NonEmpty
@@ -24,22 +26,20 @@
 import qualified Data.Text.Lazy as TL
 import qualified Data.Text.Lazy.Builder as TB
 import Data.Time.Calendar (Day, addDays)
+import Lucid as L hiding (Html, value_)
 import System.Console.CmdArgs.Explicit as C (Mode, flagNone, flagReq)
 import qualified System.IO as IO
-import Hledger.Write.Ods (printFods)
-import Hledger.Write.Csv (CSV, printCSV, printTSV)
-import Hledger.Write.Html.Lucid (printHtml)
-import Hledger.Write.Html.Attribute (stylesheet, tableStyle, alignleft)
-import qualified Hledger.Write.Spreadsheet as Spr
-import Lucid as L hiding (value_)
 import Text.Tabular.AsciiWide as Tabular hiding (render)
 
 import Hledger
 import Hledger.Cli.Commands.Balance
 import Hledger.Cli.CliOptions
 import Hledger.Cli.Utils (unsupportedOutputFormatError, writeOutputLazyText)
-import Data.Function ((&))
-import Control.Monad (guard)
+import Hledger.Write.Csv (CSV, printCSV, printTSV)
+import Hledger.Write.Html (htmlAsLazyText, styledTableHtml, Html)
+import Hledger.Write.Html.Attribute (stylesheet, tableStyle, alignleft)
+import Hledger.Write.Ods (printFods)
+import qualified Hledger.Write.Spreadsheet as Spr
 
 -- | Description of a compound balance report command,
 -- from which we generate the command's cmdargs mode and IO action.
@@ -76,8 +76,9 @@
       "show total change of period-end historical balance value (caused by deposits, withdrawals, market price fluctuations)"
     ,flagNone ["gain"] (setboolopt "gain")
       "show unrealised capital gain/loss (historical balance value minus cost basis)"
-   ,flagNone ["budget"] (setboolopt "budget")
-      "show sum of posting amounts compared to budget goals defined by periodic transactions"
+  -- currently not supported by compound balance commands:
+  --  ,flagNone ["budget"] (setboolopt "budget")
+  --     "show sum of posting amounts compared to budget goals defined by periodic transactions"
    ,flagNone ["count"] (setboolopt "count") "show the count of postings"
 
    ,flagNone ["change"] (setboolopt "change")
@@ -201,7 +202,7 @@
       "txt"  -> compoundBalanceReportAsText ropts'
       "csv"  -> printCSV . compoundBalanceReportAsCsv ropts'
       "tsv"  -> printTSV . compoundBalanceReportAsCsv ropts'
-      "html" -> L.renderText . compoundBalanceReportAsHtml ropts'
+      "html" -> htmlAsLazyText . compoundBalanceReportAsHtml ropts'
       "fods" -> printFods IO.localeEncoding .
                 fmap (second NonEmpty.toList) . uncurry Map.singleton .
                 compoundBalanceReportAsSpreadsheet
@@ -322,7 +323,7 @@
         NonEmpty.toList spreadsheet
 
 -- | Render a compound balance report as HTML.
-compoundBalanceReportAsHtml :: ReportOpts -> CompoundPeriodicReport DisplayName MixedAmount -> Html ()
+compoundBalanceReportAsHtml :: ReportOpts -> CompoundPeriodicReport DisplayName MixedAmount -> Html
 compoundBalanceReportAsHtml ropts cbr =
   let (title, (_fixed, cells)) =
           compoundBalanceReportAsSpreadsheet
@@ -337,7 +338,7 @@
       ]
     table_ $ do
       tr_ $ th_ [colspanattr, style_ alignleft] $ h2_ $ toHtml title
-      printHtml $ NonEmpty.toList $ fmap (map (fmap L.toHtml)) cells
+      styledTableHtml $ NonEmpty.toList $ fmap (map (fmap L.toHtml)) cells
 
 -- | Render a compound balance report as Spreadsheet.
 compoundBalanceReportAsSpreadsheet ::
diff --git a/bench/bench.hs b/bench/bench.hs
--- a/bench/bench.hs
+++ b/bench/bench.hs
@@ -4,12 +4,11 @@
 
 import Criterion.Main     (defaultMainWith, defaultConfig, bench, nfIO)
 -- import QuickBench        (defaultMain)
-import Data.Default
 import System.Directory   (getCurrentDirectory)
 import System.Environment (getArgs, withArgs)
 import System.TimeIt      (timeItT)
 import Text.Printf
-import Hledger.Cli
+import Hledger.Cli hiding (main)
 
 -- sample journal file to use for benchmarks
 inputfile = "bench/10000x1000x10.journal"
@@ -34,7 +33,7 @@
 benchWithTimeit = do
   getCurrentDirectory >>= printf "Benchmarking hledger in %s with timeit\n"
   let opts = defcliopts{output_file_=Just outputfile}
-  (t0,j) <- timeit ("read "++inputfile) $ either error id <$> readJournalFile def inputfile  -- PARTIAL:
+  (t0,j) <- timeit ("read "++inputfile) $ readJournalFile' inputfile  -- PARTIAL:
   (t1,_) <- timeit ("print") $ print' opts j
   (t2,_) <- timeit ("register") $ register opts j
   (t3,_) <- timeit ("balance") $ balance  opts j
@@ -50,9 +49,9 @@
 benchWithCriterion = do
   getCurrentDirectory >>= printf "Benchmarking hledger in %s with criterion\n"
   let opts = defcliopts{output_file_=Just "/dev/null"}
-  j <- either error id <$> readJournalFile def inputfile  -- PARTIAL:
+  j <- readJournalFile' inputfile  -- PARTIAL:
   Criterion.Main.defaultMainWith defaultConfig $ [
-    bench ("read "++inputfile) $ nfIO $ (either error const <$> readJournalFile def inputfile),  -- PARTIAL:
+    bench ("read "++inputfile) $ nfIO $ const <$> readJournalFile' inputfile,  -- PARTIAL:
     bench ("print")            $ nfIO $ print'   opts j,
     bench ("register")         $ nfIO $ register opts j,
     bench ("balance")          $ nfIO $ balance  opts j,
diff --git a/embeddedfiles/hledger-ui.1 b/embeddedfiles/hledger-ui.1
--- a/embeddedfiles/hledger-ui.1
+++ b/embeddedfiles/hledger-ui.1
@@ -1,5 +1,5 @@
 
-.TH "HLEDGER\-UI" "1" "October 2024" "hledger-ui-1.41 " "hledger User Manuals"
+.TH "HLEDGER\-UI" "1" "March 2025" "hledger-ui-1.42 " "hledger User Manuals"
 
 
 
@@ -17,7 +17,7 @@
 .PD
 \f[CR]hledger ui \-\- [OPTS] [QUERYARGS]\f[R]
 .SH DESCRIPTION
-This manual is for hledger\[aq]s terminal interface, version 1.41.
+This manual is for hledger\[aq]s terminal interface, version 1.42.
 See also the hledger manual for common concepts and file formats.
 .PP
 hledger is a robust, user\-friendly, cross\-platform set of programs for
@@ -458,9 +458,6 @@
 If you are viewing files mounted from another machine, the system clocks
 on both machines should be roughly in agreement.
 .SH ENVIRONMENT
-\f[B]COLUMNS\f[R] The screen width to use.
-Default: the full terminal width.
-.PP
 \f[B]LEDGER_FILE\f[R] The main journal file to use when not specified
 with \f[CR]\-f/\-\-file\f[R].
 Default: \f[CR]$HOME/.hledger.journal\f[R].
diff --git a/embeddedfiles/hledger-ui.info b/embeddedfiles/hledger-ui.info
--- a/embeddedfiles/hledger-ui.info
+++ b/embeddedfiles/hledger-ui.info
@@ -1,4 +1,4 @@
-This is hledger-ui.info, produced by makeinfo version 7.1.1 from stdin.
+This is hledger-ui.info, produced by makeinfo version 7.2 from stdin.
 
 INFO-DIR-SECTION User Applications
 START-INFO-DIR-ENTRY
@@ -18,7 +18,7 @@
 or
 'hledger ui -- [OPTS] [QUERYARGS]'
 
-   This manual is for hledger's terminal interface, version 1.41.  See
+   This manual is for hledger's terminal interface, version 1.42.  See
 also the hledger manual for common concepts and file formats.
 
    hledger is a robust, user-friendly, cross-platform set of programs
@@ -514,9 +514,7 @@
 6 ENVIRONMENT
 *************
 
-*COLUMNS* The screen width to use.  Default: the full terminal width.
-
-   *LEDGER_FILE* The main journal file to use when not specified with
+*LEDGER_FILE* The main journal file to use when not specified with
 '-f/--file'.  Default: '$HOME/.hledger.journal'.
 
 
@@ -543,22 +541,22 @@
 
 
 Tag Table:
-Node: Top223
-Node: OPTIONS1872
-Node: MOUSE8546
-Node: KEYS8878
-Node: SCREENS13882
-Node: Menu screen14622
-Node: Cash accounts screen14938
-Node: Balance sheet accounts screen15299
-Node: Income statement accounts screen15635
-Node: All accounts screen16020
-Node: Register screen16383
-Node: Transaction screen18826
-Node: Error screen20401
-Node: WATCH MODE20767
-Node: ENVIRONMENT22343
-Node: BUGS22650
+Node: Top221
+Node: OPTIONS1870
+Node: MOUSE8544
+Node: KEYS8876
+Node: SCREENS13880
+Node: Menu screen14620
+Node: Cash accounts screen14936
+Node: Balance sheet accounts screen15297
+Node: Income statement accounts screen15633
+Node: All accounts screen16018
+Node: Register screen16381
+Node: Transaction screen18824
+Node: Error screen20399
+Node: WATCH MODE20765
+Node: ENVIRONMENT22341
+Node: BUGS22574
 
 End Tag Table
 
diff --git a/embeddedfiles/hledger-ui.txt b/embeddedfiles/hledger-ui.txt
--- a/embeddedfiles/hledger-ui.txt
+++ b/embeddedfiles/hledger-ui.txt
@@ -11,7 +11,7 @@
        hledger ui -- [OPTS] [QUERYARGS]
 
 DESCRIPTION
-       This manual is for hledger's terminal  interface,  version  1.41.   See
+       This manual is for hledger's terminal  interface,  version  1.42.   See
        also the hledger manual for common concepts and file formats.
 
        hledger  is a robust, user-friendly, cross-platform set of programs for
@@ -412,8 +412,6 @@
        clocks on both machines should be roughly in agreement.
 
 ENVIRONMENT
-       COLUMNS The screen width to use.  Default: the full terminal width.
-
        LEDGER_FILE The main journal  file  to  use  when  not  specified  with
        -f/--file.  Default: $HOME/.hledger.journal.
 
@@ -452,4 +450,4 @@
 SEE ALSO
        hledger(1), hledger-ui(1), hledger-web(1), ledger(1)
 
-hledger-ui-1.41                  October 2024                    HLEDGER-UI(1)
+hledger-ui-1.42                   March 2025                     HLEDGER-UI(1)
diff --git a/embeddedfiles/hledger-web.1 b/embeddedfiles/hledger-web.1
--- a/embeddedfiles/hledger-web.1
+++ b/embeddedfiles/hledger-web.1
@@ -1,5 +1,5 @@
 
-.TH "HLEDGER\-WEB" "1" "October 2024" "hledger-web-1.41 " "hledger User Manuals"
+.TH "HLEDGER\-WEB" "1" "March 2025" "hledger-web-1.42 " "hledger User Manuals"
 
 
 
@@ -17,7 +17,7 @@
 .PD
 \f[CR]hledger web \-\- [OPTS] [QUERY]\f[R]
 .SH DESCRIPTION
-This manual is for hledger\[aq]s web interface, version 1.41.
+This manual is for hledger\[aq]s web interface, version 1.42.
 See also the hledger manual for common concepts and file formats.
 .PP
 hledger is a robust, user\-friendly, cross\-platform set of programs for
diff --git a/embeddedfiles/hledger-web.info b/embeddedfiles/hledger-web.info
--- a/embeddedfiles/hledger-web.info
+++ b/embeddedfiles/hledger-web.info
@@ -1,4 +1,4 @@
-This is hledger-web.info, produced by makeinfo version 7.1.1 from stdin.
+This is hledger-web.info, produced by makeinfo version 7.2 from stdin.
 
 INFO-DIR-SECTION User Applications
 START-INFO-DIR-ENTRY
@@ -18,7 +18,7 @@
 or
 'hledger web -- [OPTS] [QUERY]'
 
-   This manual is for hledger's web interface, version 1.41.  See also
+   This manual is for hledger's web interface, version 1.42.  See also
 the hledger manual for common concepts and file formats.
 
    hledger is a robust, user-friendly, cross-platform set of programs
@@ -528,16 +528,16 @@
 
 
 Tag Table:
-Node: Top225
-Node: OPTIONS2568
-Node: PERMISSIONS11257
-Node: EDITING UPLOADING DOWNLOADING12608
-Node: RELOADING13623
-Node: JSON API14190
-Node: DEBUG OUTPUT19839
-Node: Debug output19991
-Node: ENVIRONMENT20509
-Node: BUGS20745
+Node: Top223
+Node: OPTIONS2566
+Node: PERMISSIONS11255
+Node: EDITING UPLOADING DOWNLOADING12606
+Node: RELOADING13621
+Node: JSON API14188
+Node: DEBUG OUTPUT19837
+Node: Debug output19989
+Node: ENVIRONMENT20507
+Node: BUGS20743
 
 End Tag Table
 
diff --git a/embeddedfiles/hledger-web.txt b/embeddedfiles/hledger-web.txt
--- a/embeddedfiles/hledger-web.txt
+++ b/embeddedfiles/hledger-web.txt
@@ -11,7 +11,7 @@
        hledger web -- [OPTS] [QUERY]
 
 DESCRIPTION
-       This manual is for hledger's web interface, version 1.41.  See also the
+       This manual is for hledger's web interface, version 1.42.  See also the
        hledger manual for common concepts and file formats.
 
        hledger is a robust, user-friendly, cross-platform set of programs  for
@@ -480,4 +480,4 @@
 SEE ALSO
        hledger(1), hledger-ui(1), hledger-web(1), ledger(1)
 
-hledger-web-1.41                 October 2024                   HLEDGER-WEB(1)
+hledger-web-1.42                  March 2025                    HLEDGER-WEB(1)
diff --git a/embeddedfiles/hledger.1 b/embeddedfiles/hledger.1
--- a/embeddedfiles/hledger.1
+++ b/embeddedfiles/hledger.1
@@ -1,6 +1,6 @@
 .\"t
 
-.TH "HLEDGER" "1" "October 2024" "hledger-1.41 " "hledger User Manuals"
+.TH "HLEDGER" "1" "March 2025" "hledger-1.42 " "hledger User Manuals"
 
 
 
@@ -32,7 +32,7 @@
 hledger is inspired by and largely compatible with ledger(1), and
 largely interconvertible with beancount(1).
 .PP
-This manual is for hledger\[aq]s command line interface, version 1.41.
+This manual is for hledger\[aq]s command line interface, version 1.42.
 It also describes the common options, file formats and concepts used by
 all hledger programs.
 It might accidentally teach you some bookkeeping/accounting as well!
@@ -132,20 +132,26 @@
 For more about how to do that on your system, see Common tasks > Setting
 LEDGER_FILE.
 .SS Text encoding
-Data files containing non\-ascii characters must use UTF\-8 encoding.
-An optional byte order mark (BOM) is allowed, at the beginning of the
-file (only).
+hledger input files containing non\-ascii characters must use UTF\-8
+encoding, with the exception of CSV (SSV, TSV..)
+files, which can be read from other encodings (see \f[CR]encoding\f[R]
+CSV rule).
 .PP
-Also, your system should be configured with a locale that can decode
-UTF\-8 text.
-On some unix systems, you may need set the \f[CR]LANG\f[R] environment
-variable, eg.
+In UTF\-8 input files, an optional byte order mark (BOM) at the
+beginning of the file is allowed.
+.PP
+Your system may need to be configured with a locale that understands the
+input file\[aq]s encoding.
+Eg on some unix systems, you may need set the \f[CR]LANG\f[R]
+environment variable.
 You can read more about this in Unicode characters, below.
 .PP
-On unix systems you can check a file\[aq]s encoding with the
-\f[CR]file\f[R] command.
-If you need to import from a UTF\-16\-encoded CSV file, say, you can
-convert it to UTF\-8 with the \f[CR]iconv\f[R] command.
+On some unix systems you can use the \f[CR]file\f[R] command to show a
+file\[aq]s text encoding.
+On mac, you\[aq]ll need the version from homebrew:
+\f[CR]brew install file\-formula\f[R].
+.PP
+hledger\[aq]s text output is always UTF\-8 encoded.
 .SS Data formats
 Usually the data file is in hledger\[aq]s journal format, but it can be
 in any of the supported file formats, which currently are:
@@ -903,12 +909,11 @@
 The config file feature was added in hledger 1.40 and is considered
 \f[I]experimental\f[R].
 .SS Shell completions
-If you use the bash shell, you can optionally set up context\-sensitive
-autocompletions when you press TAB in a hledger command line.
-At a bash shell prompt, try pressing \f[CR]hledger<SPACE><TAB><TAB>\f[R]
-(should list all hledger commands) or
-\f[CR]hledger reg acct:<TAB><TAB>\f[R] (should list your top\-level
-account names).
+If you use the bash or zsh shells, you can optionally set up
+context\-sensitive autocompletion for hledger command lines.
+Try pressing \f[CR]hledger<SPACE><TAB><TAB>\f[R] (should list all
+hledger commands) or \f[CR]hledger reg acct:<TAB><TAB>\f[R] (should list
+your top\-level account names).
 If completions aren\[aq]t working, or for more details, see Install >
 Shell completions.
 .SH Output
@@ -1112,13 +1117,10 @@
 terminal and font that render those correctly.
 (This can be challenging on MS Windows.)
 .PP
-Some reports (\f[CR]register\f[R], \f[CR]aregister\f[R]) will use the
-width indicated by the \f[CR]COLUMNS\f[R] environment variable.
-If your shell and terminal are working well, they will keep COLUMNS
-updated as you resize the window.
-So register reports normally will use the full window width.
-When this isn\[aq]t working or you want to override it, you can manually
-set COLUMNS, or use the \f[CR]\-w\f[R]/\f[CR]\-\-width\f[R] option.
+Some reports (\f[CR]register\f[R], \f[CR]aregister\f[R]) will normally
+use the full window width.
+If this isn\[aq]t working or you want to override it, you can use the
+\f[CR]\-w\f[R]/\f[CR]\-\-width\f[R] option.
 .PP
 Balance reports (\f[CR]balance\f[R], \f[CR]balancesheet\f[R],
 \f[CR]incomestatement\f[R]...)
@@ -1151,6 +1153,9 @@
 .SS Paging
 In unix\-like environments, when displaying large output (in any output
 format) in the terminal, hledger tries to use a pager when appropriate.
+(You can disable this with the \f[CR]\-\-pager=no\f[R] option, perhaps
+in your config file.)
+.PP
 The pager shows one page of text at a time, and lets you scroll around
 to see more.
 While it is active, usually \f[CR]SPACE\f[R] shows the next page,
@@ -1176,7 +1181,7 @@
 (At the time of writing: \-\-chop\-long\-lines \-\-hilite\-unread
 \-\-ignore\-case \-\-mouse \-\-no\-init \-\-quit\-at\-eof
 \-\-quit\-if\-one\-screen \-\-RAW\-CONTROL\-CHARS \-\-shift=8
-\-\-squeeze\-blank\-lines \-\-use\-backslash \-\-use\-color ).
+\-\-squeeze\-blank\-lines \-\-use\-backslash ).
 If these don\[aq]t work well, you can set your preferred options in the
 \f[CR]HLEDGER_LESS\f[R] variable, which will be used instead.
 .SS HTML output
@@ -1230,6 +1235,13 @@
 \f[CR]Expenses\f[R].
 You can use account aliases to rewrite your account names temporarily,
 if needed, as in this hledger2beancount.conf config file.
+.PP
+2024\-12\-20: Some more things not yet handled for you:
+.IP \[bu] 2
+P directives are not converted automatically \- convert those yourself
+.IP \[bu] 2
+Balance assignments are not converted (Beancount doesnt support them) \-
+replace those with explicit amounts
 .SS Beancount account names
 Aside from the top\-level names, hledger will adjust your account names
 to make valid Beancount account names, by capitalising each part,
@@ -1328,7 +1340,7 @@
 $ hledger print \-c \[aq]$1.000,0\[aq]
 .EE
 .PP
-This option can repeated to set the display style for multiple
+This option can be repeated to set the display style for multiple
 commodities/currencies.
 Its argument is as described in the commodity directive.
 .PP
@@ -1358,10 +1370,6 @@
 .SH Environment
 These environment variables affect hledger:
 .PP
-\f[B]COLUMNS\f[R] This is normally set by your terminal; some hledger
-commands (\f[CR]register\f[R]) will format their output to this width.
-If not set, they will try to use the available terminal width.
-.PP
 \f[B]HLEDGER_LESS\f[R] If \f[CR]less\f[R] is your pager, this variable
 specifies the \f[CR]less\f[R] options hledger should use.
 (Otherwise, \f[CR]LESS\f[R] + custom options are used.)
@@ -3105,7 +3113,7 @@
 command, eg something like:
 .IP
 .EX
-$ hledger accounts \-\-alias assets=bassetts type:a
+$ hledger accounts \-\-types \-1 \-\-alias assets=bassetts
 .EE
 .SS \f[CR]commodity\f[R] directive
 The \f[CR]commodity\f[R] directive performs several functions:
@@ -3143,7 +3151,7 @@
 .SS Commodity directive syntax
 A commodity directive is normally the word \f[CR]commodity\f[R] followed
 by a sample amount (and optionally a comment).
-Only the amount\[aq]s symbol and format is significant.
+Only the amount\[aq]s symbol and the number\[aq]s format is significant.
 Eg:
 .IP
 .EX
@@ -3872,14 +3880,15 @@
 syntax comparison.
 .SS Other cost/lot notations
 A slight digression for Ledger and Beancount users.
-Ledger has a number of cost/lot\-related notations:
+.PP
+\f[B]Ledger\f[R] has a number of cost/lot\-related notations:
 .IP \[bu] 2
 \f[CR]\[at] UNITCOST\f[R] and \f[CR]\[at]\[at] TOTALCOST\f[R]
 .RS 2
 .IP \[bu] 2
 expresses a conversion rate, as in hledger
 .IP \[bu] 2
-when buying, also creates a lot than can be selected at selling time
+when buying, also creates a lot that can be selected at selling time
 .RE
 .IP \[bu] 2
 \f[CR](\[at]) UNITCOST\f[R] and \f[CR](\[at]\[at]) TOTALCOST\f[R]
@@ -3889,15 +3898,11 @@
 like the above, but also means \[dq]this cost was exceptional, don\[aq]t
 use it when inferring market prices\[dq].
 .RE
-.PP
-Currently, hledger treats the above like \f[CR]\[at]\f[R] and
-\f[CR]\[at]\[at]\f[R]; the parentheses are ignored.
 .IP \[bu] 2
-\f[CR]{=FIXEDUNITCOST}\f[R] and \f[CR]{{=FIXEDTOTALCOST}}\f[R] (fixed
-price)
+\f[CR]{=UNITCOST}\f[R] and \f[CR]{{=TOTALCOST}}\f[R] (fixed price)
 .RS 2
 .IP \[bu] 2
-when buying, means \[dq]this cost is also the fixed price, don\[aq]t let
+when buying, means \[dq]this cost is also the fixed value, don\[aq]t let
 it fluctuate in value reports\[dq]
 .RE
 .IP \[bu] 2
@@ -3907,11 +3912,12 @@
 can be used identically to \f[CR]\[at] UNITCOST\f[R] and
 \f[CR]\[at]\[at] TOTALCOST\f[R], also creates a lot
 .IP \[bu] 2
-when selling, combined with \f[CR]\[at] ...\f[R], specifies an
-investment lot by its cost basis; does not check if that lot is present
+when selling, combined with \f[CR]\[at] ...\f[R], selects an existing
+lot by its cost basis.
+Does not check if that lot is present.
 .RE
 .IP \[bu] 2
-and related: \f[CR][YYYY/MM/DD]\f[R] (lot date)
+\f[CR][YYYY/MM/DD]\f[R] (lot date)
 .RS 2
 .IP \[bu] 2
 when buying, attaches this acquisition date to the lot
@@ -3927,29 +3933,37 @@
 when selling, selects a lot by its note
 .RE
 .PP
-Currently, hledger accepts any or all of the above in any order after
-the posting amount, but ignores them.
+Currently, hledger
+.IP \[bu] 2
+accepts any or all of the above in any order after the posting amount
+.IP \[bu] 2
+supports \f[CR]\[at]\f[R] and \f[CR]\[at]\[at]\f[R]
+.IP \[bu] 2
+treats \f[CR](\[at])\f[R] and \f[CR](\[at]\[at])\f[R] as synonyms for
+\f[CR]\[at]\f[R] and \f[CR]\[at]\[at]\f[R]
+.IP \[bu] 2
+and ignores the rest.
 (This can break transaction balancing.)
 .PP
-For Beancount users, the notation and behaviour is different:
+\f[B]Beancount\f[R] has simpler notation and different behaviour:
 .IP \[bu] 2
 \f[CR]\[at] UNITCOST\f[R] and \f[CR]\[at]\[at] TOTALCOST\f[R]
 .RS 2
 .IP \[bu] 2
 expresses a cost without creating a lot, as in hledger
 .IP \[bu] 2
-when buying (augmenting) or selling (reducing) a lot, combined with
-\f[CR]{...}\f[R]: documents the cost/selling price (not used for
-transaction balancing)
+when buying (acquiring) or selling (disposing of) a lot, and combined
+with \f[CR]{...}\f[R]: is not used except to document the cost/selling
+price
 .RE
 .IP \[bu] 2
 \f[CR]{UNITCOST}\f[R] and \f[CR]{{TOTALCOST}}\f[R]
 .RS 2
 .IP \[bu] 2
-when buying (augmenting), expresses the cost for transaction balancing,
-and also creates a lot with this cost basis attached
+when buying, expresses the cost for transaction balancing, and also
+creates a lot with this cost basis attached
 .IP \[bu] 2
-when selling (reducing),
+when selling,
 .RS 2
 .IP \[bu] 2
 selects a lot by its cost basis
@@ -3960,15 +3974,24 @@
 expresses the selling price for transaction balancing
 .RE
 .RE
-.PP
-Currently, hledger accepts the
-\f[CR]{UNITCOST}\f[R]/\f[CR]{{TOTALCOST}}\f[R] notation but ignores it.
 .IP \[bu] 2
-variations: \f[CR]{}\f[R], \f[CR]{YYYY\-MM\-DD}\f[R],
-\f[CR]{\[dq]LABEL\[dq]}\f[R], \f[CR]{UNITCOST, \[dq]LABEL\[dq]}\f[R],
-\f[CR]{UNITCOST, YYYY\-MM\-DD, \[dq]LABEL\[dq]}\f[R] etc.
+\f[CR]{}\f[R], \f[CR]{YYYY\-MM\-DD}\f[R], \f[CR]{\[dq]LABEL\[dq]}\f[R],
+\f[CR]{UNITCOST, \[dq]LABEL\[dq]}\f[R],
+\f[CR]{UNITCOST, YYYY\-MM\-DD, \[dq]LABEL\[dq]}\f[R]
+.RS 2
+.IP \[bu] 2
+when selling, other combinations of date/cost/label, like the above, are
+accepted for selecting the lot.
+.RE
 .PP
-Currently, hledger rejects these.
+Currently, hledger
+.IP \[bu] 2
+supports \f[CR]\[at]\f[R] and \f[CR]\[at]\[at]\f[R]
+.IP \[bu] 2
+accepts the \f[CR]{UNITCOST}\f[R]/\f[CR]{{TOTALCOST}}\f[R] notation, but
+ignores it
+.IP \[bu] 2
+and rejects the rest.
 .PP
 .SH CSV
 hledger can read CSV files (Character Separated Value \- usually comma,
@@ -4038,6 +4061,11 @@
 optionally declare which file to read data from
 T}
 T{
+\f[B]\f[CB]encoding\f[B]\f[R]
+T}@T{
+optionally declare which text encoding the data has
+T}
+T{
 \f[B]\f[CB]separator\f[B]\f[R]
 T}@T{
 declare the field separator, instead of relying on file extension
@@ -4144,6 +4172,26 @@
 .EE
 .PP
 See also \[dq]Working with CSV > Reading files specified by rule\[dq].
+.SS \f[CR]encoding\f[R]
+.IP
+.EX
+encoding ENCODING
+.EE
+.PP
+hledger normally expects non\-ascii text to be UTF8\-encoded.
+If you need to read CSV files which have some other encoding, you can do
+it by adding \f[CR]encoding ENCODING\f[R] to your CSV rules.
+Eg: \f[CR]encoding ISO88591\f[R].
+.PP
+The following encodings are supported (these names are
+case\-insensitive, and can be written with inner spaces or hyphens if
+you prefer): ASCII, UTF8, UTF16, UTF32, ISO88591, ISO88592, ISO88593,
+ISO88594, ISO88595, ISO88596, ISO88597, ISO88598, ISO88599, ISO885910,
+ISO885911, ISO885913, ISO885914, ISO885915, ISO885916, CP1250, CP1251,
+CP1252, CP1253, CP1254, CP1255, CP1256, CP1257, CP1258, KOI8R, KOI8U,
+GB18030, MacOSRoman, JISX0201, JISX0208, ISO2022JP, ShiftJIS, CP437,
+CP737, CP775, CP850, CP852, CP855, CP857, CP860, CP861, CP862, CP863,
+CP864, CP865, CP866, CP869, CP874, CP932.
 .SS \f[CR]separator\f[R]
 You can use the \f[CR]separator\f[R] rule to read other kinds of
 character\-separated data.
@@ -4689,12 +4737,20 @@
 .IP \[bu] 2
 By default they are OR\[aq]d (any of them can match).
 .IP \[bu] 2
-Matcher lines beginning with \f[CR]&\f[R] (and optional space) are
-AND\[aq]ed with the matcher above (all in the AND\[aq]ed group must
-match).
+Matcher lines beginning with \f[CR]&\f[R] (or \f[CR]&&\f[R], \f[I]since
+1.42\f[R]) are AND\[aq]ed with the matcher above (all in the AND\[aq]ed
+group must match).
+.IP \[bu] 2
+Matcher lines beginning with \f[CR]& !\f[R] (\f[I]since 1.41\f[R], or
+\f[CR]&& !\f[R], \f[I]since 1.42\f[R]) are first negated and then
+AND\[aq]ed with the matcher above.
 .PP
-\f[I](Since 1.41:)\f[R] You can use a negated \f[CR]!\f[R] matcher on a
-\f[CR]&\f[R] line, meaning AND NOT.
+You can also combine multiple matchers one the same line separated by
+\f[CR]&&\f[R] (AND) or \f[CR]&& !\f[R] (AND NOT).
+Eg \f[CR]%description amazon && %date 2025\-01\-01\f[R] will match only
+when the description field contains \[dq]amazon\[dq] and the date field
+contains \[dq]2025\-01\-01\[dq].
+\f[I]Added in 1.42.\f[R]
 .SS Match groups
 \f[I]Added in 1.32\f[R]
 .PP
@@ -4731,9 +4787,9 @@
 .EX
 if,HLEDGERFIELD1,HLEDGERFIELD2,...
 MATCHERA,VALUE1,VALUE2,...
-MATCHERB,VALUE1,VALUE2,...
-; Comment line that explains MATCHERC
-MATCHERC,VALUE1,VALUE2,...
+MATCHERB && MATCHERC,VALUE1,VALUE2,...  (*since 1.42*)
+; Comment line that explains MATCHERD
+MATCHERD,VALUE1,VALUE2,...
 <empty line>
 .EE
 .PP
@@ -4753,10 +4809,11 @@
 The table must be terminated by an empty line (or end of file).
 .PP
 An if table like the above is interpreted as follows: try all of the
-matchers; whenever a matcher succeeds, assign all of the values on that
-line to the corresponding hledger fields; If multiple lines match, later
-lines will override fields assigned by the earlier ones \- just like the
-sequence of \f[CR]if\f[R] blocks would behave.
+lines with matchers; whenever a line with matchers succeeds, assign all
+of the values on that line to the corresponding hledger fields; If
+multiple lines match, later lines will override fields assigned by the
+earlier ones \- just like the sequence of \f[CR]if\f[R] blocks would
+behave.
 .PP
 If table presented above is equivalent to this sequence of if blocks:
 .IP
@@ -4766,13 +4823,13 @@
   HLEDGERFIELD2 VALUE2
   ...
 
-if MATCHERB
+if MATCHERB && MATCHERC
   HLEDGERFIELD1 VALUE1
   HLEDGERFIELD2 VALUE2
   ...
 
-; Comment line which explains MATCHERC
-if MATCHERC
+; Comment line which explains MATCHERD
+if MATCHERD
   HLEDGERFIELD1 VALUE1
   HLEDGERFIELD2 VALUE2
   ...
@@ -6759,21 +6816,38 @@
 symbol and the old amount quantity, not the new ones.
 (Except in hledger 1.22, #1625.)
 .SH Pivoting
-Normally, hledger groups and sums amounts within each account.
-The \f[CR]\-\-pivot FIELD\f[R] option substitutes some other transaction
-field for account names, causing amounts to be grouped and summed by
-that field\[aq]s value instead.
-FIELD can be any of the transaction fields \f[CR]acct\f[R],
-\f[CR]status\f[R], \f[CR]code\f[R], \f[CR]desc\f[R], \f[CR]payee\f[R],
-\f[CR]note\f[R], or a tag name.
-When pivoting on a tag and a posting has multiple values of that tag,
-only the first value is displayed.
-Values containing \f[CR]colon:separated:parts\f[R] will be displayed
-hierarchically, like account names.
-Multiple, colon\-delimited fields can be pivoted simultaneously,
-generating a hierarchical account name.
+Normally, hledger groups amounts and displays their totals by account
+(name).
+With \f[CR]\-\-pivot PIVOTEXPR\f[R], some other field\[aq]s (or multiple
+fields\[aq]) value is used as a synthetic account name, causing
+different grouping and display.
+PIVOTEXPR can be
+.IP \[bu] 2
+any of these standard transaction or posting fields (their value is
+substituted): \f[CR]status\f[R], \f[CR]code\f[R], \f[CR]desc\f[R],
+\f[CR]payee\f[R], \f[CR]note\f[R], \f[CR]acct\f[R],
+\f[CR]comm\f[R]/\f[CR]cur\f[R], \f[CR]amt\f[R], \f[CR]cost\f[R]
+.IP \[bu] 2
+or a tag name
+.IP \[bu] 2
+or any combination of these, colon\-separated.
 .PP
-Some examples:
+Some special cases:
+.IP \[bu] 2
+Colons appearing in PIVOTEXPR or in a pivoted tag value will generate
+account hierarchy.
+.IP \[bu] 2
+When pivoting a posting has multiple values for a tag, the pivoted value
+of that tag will be the first value.
+.IP \[bu] 2
+When a posting has multiple commodities, the pivoted value of
+\[dq]comm\[dq]/\[dq]cur\[dq] will be \[dq]\[dq].
+Also when an unrecognised tag name or field is provided, its pivoted
+value will be \[dq]\[dq].
+(If this causes confusing output, consider excluding those postings from
+the report.)
+.PP
+Examples:
 .IP
 .EX
 2016/02/16 Yearly Dues Payment
@@ -6820,7 +6894,7 @@
               \-2 EUR
 .EE
 .PP
-Hierarchical reports can be generated with multiple pivots:
+Hierarchical reports can be generated with multiple pivot values:
 .IP
 .EX
 $ hledger balance Income:Dues \-\-pivot kind:member
@@ -7209,9 +7283,10 @@
 or sale of stock \- one commodity is exchanged for another.
 In these transactions there is a conversion rate, also called the cost
 (when buying) or selling price (when selling).
-In hledger docs we just say \[dq]cost\[dq], for convenience; feel free
-to mentally translate to \[dq]conversion rate\[dq] or \[dq]selling
-price\[dq] if helpful.
+(In hledger docs we just say \[dq]cost\[dq] generically for
+convenience.)
+With the \f[CR]\-B/\-\-cost\f[R] flag, hledger can show amounts \[dq]at
+cost\[dq], converted to the cost\[aq]s commodity.
 .SS Recording costs
 We\[aq]ll explore several ways of recording transactions involving
 costs.
@@ -7455,14 +7530,16 @@
 and let us know what problems you find.
 .PP
 .SH Value reporting
-Instead of reporting amounts in their original commodity, hledger can
-convert them to cost/sale amount (using the conversion rate recorded in
-the transaction), and/or to market value (using some market price on a
-certain date).
-This is controlled by the \f[CR]\-\-value=TYPE[,COMMODITY]\f[R] option,
-which will be described below.
-We also provide the simpler \f[CR]\-V\f[R] and \f[CR]\-X COMMODITY\f[R]
-options, and often one of these is all you need:
+hledger can also show amounts \[dq]at market value\[dq], converted to
+some other commodity using the market price or conversion rate on a
+certain date.
+.PP
+This is controlled by the \f[CR]\-\-value=TYPE[,COMMODITY]\f[R] option.
+We also provide simpler \f[CR]\-V\f[R] and \f[CR]\-X COMMODITY\f[R]
+aliases for this, which are often sufficient.
+The market prices are declared with a special \f[CR]P\f[R] directive,
+and/or they can be inferred from the costs recorded in transactions, by
+using the \f[CR]\-\-infer\-market\-prices\f[R] flag.
 .SS \-V: Value
 The \f[CR]\-V/\-\-market\f[R] flag converts amounts to market value in
 their default \f[I]valuation commodity\f[R], using the market prices in
@@ -8271,6 +8348,49 @@
 .PP
 Next, these commands are described in detail.
 .SH Help commands
+.SS commands
+Show the hledger commands list.
+.IP
+.EX
+Flags:
+     \-\-builtin             show only builtin commands, not addons
+.EE
+.SS demo
+Play demos of hledger usage in the terminal, if asciinema is installed.
+.IP
+.EX
+Flags:
+  \-s \-\-speed=SPEED         playback speed (1 is original speed, .5 is half, 2
+                           is double, etc (default: 2))
+.EE
+.PP
+Run this command with no argument to list the demos.
+To play a demo, write its number or a prefix or substring of its title.
+Tips:
+.PP
+Make your terminal window large enough to see the demo clearly.
+.PP
+Use the \-s/\-\-speed SPEED option to set your preferred playback speed,
+eg \f[CR]\-s4\f[R] to play at 4x original speed or \f[CR]\-s.5\f[R] to
+play at half speed.
+The default speed is 2x.
+.PP
+Other asciinema options can be added following a double dash, eg
+\f[CR]\-\- \-i.1\f[R] to limit pauses or \f[CR]\-\- \-h\f[R] to list
+asciinema\[aq]s other options.
+.PP
+During playback, several keys are available: SPACE to pause/unpause, .
+to step forward (while paused), CTRL\-c quit.
+.PP
+Examples:
+.IP
+.EX
+$ hledger demo               # list available demos
+$ hledger demo 1             # play the first demo at default speed (2x)
+$ hledger demo install \-s4   # play the \[dq]install\[dq] demo at 4x speed
+.EE
+.PP
+This command is experimental: there aren\[aq]t many useful demos yet.
 .SS help
 Show the hledger user manual with \f[CR]info\f[R], \f[CR]man\f[R], or a
 pager.
@@ -8318,41 +8438,220 @@
 $ hledger help \[aq]time periods\[aq]     # show the manual\[aq]s \[dq]Time periods\[dq] topic
 $ hledger help \[aq]time periods\[aq] \-m  # use man, even if info is installed
 .EE
-.SS demo
-Play demos of hledger usage in the terminal, if asciinema is installed.
+.SH User interface commands
+.SS repl
+Start an interactive prompt, where you can run any of hledger\[aq]s
+commands.
+Data files are parsed just once, so the commands run faster.
 .IP
 .EX
 Flags:
-  \-s \-\-speed=SPEED         playback speed (1 is original speed, .5 is half, 2
-                           is double, etc (default: 2))
+no command\-specific flags
 .EE
 .PP
-Run this command with no argument to list the demos.
-To play a demo, write its number or a prefix or substring of its title.
-Tips:
+This command is experimental and could change in the future.
 .PP
-Make your terminal window large enough to see the demo clearly.
+\f[CR]hledger repl\f[R] starts a read\-eval\-print loop (REPL) where you
+can enter commands interactively.
+As with the \f[CR]run\f[R] 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.
 .PP
-Use the \-s/\-\-speed SPEED option to set your preferred playback speed,
-eg \f[CR]\-s4\f[R] to play at 4x original speed or \f[CR]\-s.5\f[R] to
-play at half speed.
-The default speed is 2x.
+Also like \f[CR]run\f[R], the input file(s) specified for the
+\f[CR]repl\f[R] command will be the default input for all interactive
+commands, you can override this temporarily by specifying an
+\f[CR]\-f\f[R] option in particular commands, and commands will not see
+any changes made to input files (eg by \f[CR]add\f[R]) until you exit
+and restart the REPL.
 .PP
-Other asciinema options can be added following a double dash, eg
-\f[CR]\-\- \-i.1\f[R] to limit pauses or \f[CR]\-\- \-h\f[R] to list
-asciinema\[aq]s other options.
+The command syntax is the same as with \f[CR]run\f[R]:
+.IP \[bu] 2
+enter one hledger command at a time, without the usual
+\f[CR]hledger\f[R] first word
+.IP \[bu] 2
+empty lines and comment text from \f[CR]#\f[R] to end of line are
+ignored
+.IP \[bu] 2
+use single or double quotes to quote arguments when needed
+.IP \[bu] 2
+type \f[CR]exit\f[R] or \f[CR]quit\f[R] or control\-D to exit the REPL.
 .PP
-During playback, several keys are available: SPACE to pause/unpause, .
-to step forward (while paused), CTRL\-c quit.
+While it is running, the REPL remembers your command history, and you
+can navigate in the usual ways:
+.IP \[bu] 2
+Keypad or Emacs navigation keys to edit the current command line
+.IP \[bu] 2
+UP/DOWN or control\-P/control\-N to step back/forward through history
+.IP \[bu] 2
+control\-R to search for a past command
+.IP \[bu] 2
+TAB completes file paths.
 .PP
-Examples:
+The \f[CR]commands\f[R] and \f[CR]help\f[R]\ commands, and the command
+help flags (\f[CR]CMD \-\-tldr\f[R], \f[CR]CMD \-h/\-\-help\f[R],
+\f[CR]CMD \-\-info\f[R], \f[CR]CMD \-\-man\f[R]), work in the usual way,
+and can be useful.
+.PP
+You can type control\-C to cancel a long\-running command (but only
+once; typing it a second time will exit the REPL).
+.PP
+And in most shells you can type control\-Z to exit temporarily to the
+shell (and \f[CR]fg\f[R] to return to the REPL).
+.PP
+You may find some differences in behaviour between \f[CR]run\f[R]
+command lines and normal hledger command lines.
+For example, in the REPL,
+.IP \[bu] 2
+the command name must be written first, options afterward
+.IP \[bu] 2
+full command names or official abbreviations (as in the command list)
+must be used
+.IP \[bu] 2
+options parsing with addon commands might be less flexible than the CLI
+.IP \[bu] 2
+the \f[CR]stats\f[R] command gives false timings, currently
+.SS Examples
+Start the REPL and enter some commands:
 .IP
 .EX
-$ hledger demo               # list available demos
-$ hledger demo 1             # play the first demo at default speed (2x)
-$ hledger demo install \-s4   # play the \[dq]install\[dq] demo at 4x speed
+$ hledger repl 
+Enter hledger commands. To exit, enter \[aq]quit\[aq] or \[aq]exit\[aq], or send EOF.
+% stats
+Main file           : .../2025.journal
+\&...
+% stats \-f 2024/2024.journal 
+Main file           : .../2024.journal
+\&...
+% stats
+Main file           : .../2025.journal
+\&...
 .EE
-.SH User interface commands
+.PP
+or:
+.IP
+.EX
+$ hledger repl \-f some.journal
+Enter hledger commands. To exit, enter \[aq]quit\[aq] or \[aq]exit\[aq], or send EOF.
+% bs
+\&...
+% print \-b \[aq]last week\[aq]
+\&...
+% bs \-f other.journal
+\&...
+.EE
+.SS run
+Run a sequence of hledger commands, provided as files or command line
+arguments.
+Data files are parsed just once, so the commands run faster.
+.IP
+.EX
+Flags:
+no command\-specific flags
+.EE
+.PP
+This command is experimental and could change in the future.
+.PP
+You can use \f[CR]run\f[R] in three ways:
+.IP \[bu] 2
+\f[CR]hledger run \-\- CMD1 \-\- CMD2 \-\- CMD3\f[R] \- read commands
+from the command line, separated by \f[CR]\-\-\f[R]
+.IP \[bu] 2
+\f[CR]hledger run SCRIPTFILE1 SCRIPTFILE2\f[R] \- read commands from one
+or more files
+.IP \[bu] 2
+\f[CR]cat SCRIPTFILE1 | hledger run\f[R] \- read commands from standard
+input.
+.PP
+\f[CR]run\f[R] first loads the input file(s) specified by
+\f[CR]LEDGER_FILE\f[R] or by \f[CR]\-f\f[R] options, in the usual way.
+Then it runs each command in turn, each using the same input data.
+But if you want a particular command to use different input, you can
+specify an \f[CR]\-f\f[R] option within that command.
+This will override (not add to) the default input, just for that
+command.
+.PP
+Each input file (more precisely, each combination of input file and
+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).
+.PP
+Command scripts, whether in a file or written on the command line, have
+a simple syntax:
+.IP \[bu] 2
+each line may contain a single hledger command and its arguments,
+without the usual \f[CR]hledger\f[R] first word
+.IP \[bu] 2
+empty lines are ignored
+.IP \[bu] 2
+text from \f[CR]#\f[R] to end of line is a comment, and ignored
+.IP \[bu] 2
+you can use single or double quotes to quote arguments when needed, as
+on the command line
+.IP \[bu] 2
+these extra commands are available: \f[CR]echo TEXT\f[R] prints some
+text, and \f[CR]exit\f[R] or \f[CR]quit\f[R] ends the run.
+.PP
+On unix systems you can use \f[CR]#!/usr/bin/env hledger run\f[R] in the
+first line of a command file to make it a runnable script.
+If that gives an error, use \f[CR]#!/usr/bin/env \-S hledger run\f[R].
+.PP
+It\[aq]s ok to use the \f[CR]run\f[R] command recursively within a
+command script.
+.PP
+You may find some differences in behaviour between \f[CR]run\f[R]
+command lines and normal hledger command lines.
+For example, with \f[CR]run\f[R],
+.IP \[bu] 2
+the command name must be written first, options afterward
+.IP \[bu] 2
+full command names or official abbreviations (as in the command list)
+must be used
+.SS Examples
+Run commands from the command line:
+.IP
+.EX
+hledger \-f some.journal run \-\- balance assets \-\-depth 2 \-\- balance liabilities \-f /some/other.journal \-\-depth 3 \-\-transpose \-\- stats
+.EE
+.PP
+This would load \f[CR]some.journal\f[R], run
+\f[CR]balance assets \-\-depth 2\f[R] on it, then run
+\f[CR]balance liabilities \-\-depth 3 \-\-transpose\f[R] on
+\f[CR]/some/other.journal\f[R], and finally run \f[CR]stats\f[R] on
+\f[CR]some.journal\f[R]
+.PP
+Run commands from standard input:
+.IP
+.EX
+(echo \[dq]files\[dq]; echo \[dq]stats\[dq]) | hledger \-f some.journal run
+.EE
+.PP
+Run commands as a script:
+.IP
+.EX
+$ cat report
+#!/usr/bin/env \-S hledger run \-f some.journal
+
+echo \[dq]List of accounts in some.journal\[dq]
+accounts
+
+echo \[dq]Assets of some.journal\[dq]
+balance assets \-\-depth 2
+
+echo \[dq]Liabilities from /some/other.journal\[dq]
+balance liabilities \-f /some/other.journal \-\-depth 3 \-\-transpose
+
+echo \[dq]Commands from another.script, applied to another.journal\[dq]
+run \-f another.journal another.script
+.EE
+.IP
+.EX
+$ chmod +x report
+$ ./report
+List of accounts in some.journal
+\&...
+.EE
 .SS ui
 Runs hledger\-ui (if installed).
 .SS web
@@ -9011,13 +9310,14 @@
      \-\-round=TYPE           how much rounding or padding should be done when
                             displaying amounts ?
                             none \- show original decimal digits,
-                                   as in journal
+                                   as in journal (default)
                             soft \- just add or remove decimal zeros
-                                   to match precision (default)
+                                   to match precision
                             hard \- round posting amounts to precision
                                    (can unbalance transactions)
                             all  \- also round cost amounts to precision
                                    (can unbalance transactions)
+     \-\-invert               display all amounts with reversed sign
      \-\-new                  show only newer\-dated transactions added in each
                             file since last run
   \-m \-\-match=DESC           fuzzy search for one recent transaction with
@@ -9131,6 +9431,11 @@
 With \f[CR]\-B\f[R]/\f[CR]\-\-cost\f[R], amounts with costs are shown
 converted to cost.
 .PP
+With \f[CR]\-\-invert\f[R], posting amounts are shown with their sign
+flipped.
+It could be useful if you have accidentally recorded some transactions
+with the wrong signs.
+.PP
 With \f[CR]\-\-new\f[R], print shows only transactions it has not seen
 on a previous run.
 This uses the same deduplication system as the \f[CR]import\f[R]
@@ -9233,11 +9538,10 @@
      \-\-cumulative           show running total from report start date
   \-H \-\-historical           show historical running total/balance (includes
                             postings before report start date) (default)
-                            
      \-\-invert               display all amounts with reversed sign
      \-\-heading=YN           show heading row above table: yes (default) or no
-  \-w \-\-width=N              set output width (default: terminal width or
-                            $COLUMNS). \-wN,M sets description width as well.
+  \-w \-\-width=N              set output width (default: terminal width). \-wN,M
+                            sets description width as well.
      \-\-align\-all            guarantee alignment across all lines (slower)
   \-O \-\-output\-format=FMT    select the output format. Supported formats:
                             txt, html, csv, tsv, json.
@@ -9357,8 +9661,8 @@
      \-\-sort=FIELDS          sort by: date, desc, account, amount, absamount,
                             or a comma\-separated combination of these. For a
                             descending sort, prefix with \-. (Default: date)
-  \-w \-\-width=N              set output width (default: terminal width or
-                            $COLUMNS). \-wN,M sets description width as well.
+  \-w \-\-width=N              set output width (default: terminal width). \-wN,M
+                            sets description width as well.
      \-\-align\-all            guarantee alignment across all lines (slower)
      \-\-base\-url=URLPREFIX   in html output, generate links to hledger\-web,
                             with this prefix. (Usually the base url shown by
@@ -9495,10 +9799,10 @@
 If there is no similar\-enough match, no posting will be shown and the
 program exit code will be non\-zero.
 .SS Custom register output
-register uses the full terminal width by default, except on windows.
-You can override this by setting the \f[CR]COLUMNS\f[R] environment
-variable (not a bash shell variable) or by using the
-\f[CR]\-\-width\f[R]/\f[CR]\-w\f[R] option.
+register normally uses the full terminal width (or 80 columns if it
+can\[aq]t detect that).
+You can override this with the \f[CR]\-\-width\f[R]/\f[CR]\-w\f[R]
+option.
 .PP
 The description and account columns normally share the space equally
 (about half of (width \- 40) each).
@@ -9517,10 +9821,7 @@
 .EX
 $ 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
 .EE
 .PP
 This command also supports the output destination and output format
@@ -9541,8 +9842,6 @@
                             market price fluctuations)
      \-\-gain                 show unrealised capital gain/loss (historical
                             balance value minus cost basis)
-     \-\-budget               show sum of posting amounts compared to budget
-                            goals defined by periodic transactions
      \-\-count                show the count of postings
      \-\-change               accumulate amounts from column start to column
                             end (in multicolumn reports)
@@ -9645,8 +9944,6 @@
                             market price fluctuations)
      \-\-gain                 show unrealised capital gain/loss (historical
                             balance value minus cost basis)
-     \-\-budget               show sum of posting amounts compared to budget
-                            goals defined by periodic transactions
      \-\-count                show the count of postings
      \-\-change               accumulate amounts from column start to column
                             end (in multicolumn reports)
@@ -9757,8 +10054,6 @@
                             market price fluctuations)
      \-\-gain                 show unrealised capital gain/loss (historical
                             balance value minus cost basis)
-     \-\-budget               show sum of posting amounts compared to budget
-                            goals defined by periodic transactions
      \-\-count                show the count of postings
      \-\-change               accumulate amounts from column start to column
                             end (in multicolumn reports) (default)
@@ -9858,8 +10153,6 @@
                             market price fluctuations)
      \-\-gain                 show unrealised capital gain/loss (historical
                             balance value minus cost basis)
-     \-\-budget               show sum of posting amounts compared to budget
-                            goals defined by periodic transactions
      \-\-count                show the count of postings
      \-\-change               accumulate amounts from column start to column
                             end (in multicolumn reports) (default)
@@ -10004,10 +10297,10 @@
      \-\-transpose            switch rows and columns (use vertical time axis)
      \-\-layout=ARG           how to lay out multi\-commodity amounts and the
                             overall table:
-                            \[aq]wide[,WIDTH]\[aq]: commodities on one line
-                            \[aq]tall\[aq]        : commodities on separate lines
-                            \[aq]bare\[aq]        : commodity symbols in one column
-                            \[aq]tidy\[aq]        : every attribute in its own column
+                            \[aq]wide[,W]\[aq]: commodities on same line, up to W wide
+                            \[aq]tall\[aq]    : commodities on separate lines
+                            \[aq]bare\[aq]    : commodity symbols in a separate column
+                            \[aq]tidy\[aq]    : each data field in its own column
      \-\-base\-url=URLPREFIX   in html output, generate links to hledger\-web,
                             with this prefix. (Usually the base url shown by
                             hledger\-web; can also be relative.)
@@ -11068,10 +11361,6 @@
 You can also produce relative links, like
 \f[CR]\-\-base\-url=\[dq]some/path\[dq]\f[R] or
 \f[CR]\-\-base\-url=\[dq]\[dq]\f[R].)
-.PP
-The balance reports\[aq] HTML output currently does not indent tree mode
-reports properly (#1846).
-So in HTML balance reports, use list mode for now (it is the default).
 .SS Some useful balance reports
 Some frequently used \f[CR]balance\f[R] options/reports are:
 .IP \[bu] 2
@@ -11359,26 +11648,24 @@
 .SS close
 (equity)
 .PP
-\f[CR]close\f[R] generates several kinds of \[dq]closing\[dq] and/or
-\[dq]opening\[dq] transactions, useful in certain situations, including
-migrating balances to a new journal file, retaining earnings into
-equity, consolidating balances, or viewing lots.
+\f[CR]close\f[R] prints several kinds of \[dq]closing\[dq] and/or
+\[dq]opening\[dq] transactions, useful in various situations: migrating
+balances to a new journal file, retaining earnings into equity,
+consolidating balances, viewing lot costs..
 Like \f[CR]print\f[R], it prints valid journal entries.
-You can append or copy these to your journal file(s) when you are happy
-with how they look.
+You can copy these into your journal file(s) when you are happy with how
+they look.
 .IP
 .EX
 Flags:
-     \-\-migrate[=NEW]        show closing and opening transactions, for Asset
-                            and Liability accounts by default, tagged for easy
-                            matching. The tag\[aq]s default value can be overridden
-                            by providing NEW.
-     \-\-close[=NEW]          (default) show a closing transaction
-     \-\-open[=NEW]           show an opening transaction
-     \-\-assign[=NEW]         show opening balance assignments
-     \-\-assert[=NEW]         show closing balance assertions
-     \-\-retain[=NEW]         show a retain earnings transaction, for Revenue
-                            and Expense accounts by default
+     \-\-clopen[=TAGVAL]      show closing and opening balances transactions,
+                            for AL accounts by default
+     \-\-close[=TAGVAL]       show just a closing balances transaction
+     \-\-open[=TAGVAL]        show just an opening balances transaction
+     \-\-assert[=TAGVAL]      show a balance assertions transaction
+     \-\-assign[=TAGVAL]      show a balance assignments transaction
+     \-\-retain[=TAGVAL]      show a retain earnings transaction, for RX
+                            accounts by default
   \-x \-\-explicit             show all amounts explicitly
      \-\-show\-costs           show amounts with different costs separately
      \-\-interleaved          show source and destination postings together
@@ -11390,97 +11677,116 @@
      \-\-round=TYPE           how much rounding or padding should be done when
                             displaying amounts ?
                             none \- show original decimal digits,
-                                   as in journal
+                                   as in journal (default)
                             soft \- just add or remove decimal zeros
-                                   to match precision (default)
+                                   to match precision
                             hard \- round posting amounts to precision
                                    (can unbalance transactions)
                             all  \- also round cost amounts to precision
                                    (can unbalance transactions)
 .EE
 .PP
-\f[CR]close\f[R] currently has six modes, selected by a single mode
-flag:
-.SS close \-\-migrate
-This is the most common mode.
-It prints a \[dq]closing balances\[dq] transaction that zeroes out all
-asset and liability balances (by default), and an opposite \[dq]opening
-balances\[dq] transaction that restores them again.
-The balancing account will be \f[CR]equity:opening/closing balances\f[R]
-(or another specified by \f[CR]\-\-close\-acct\f[R] or
-\f[CR]\-\-open\-acct\f[R]).
+\f[CR]close\f[R] has six modes, selected by choosing one of the mode
+flags (\f[CR]\-\-close\f[R] is the default).
+They all do much the same operation, but with different defaults, useful
+in different situations.
+.SS close \-\-clopen
+This is useful if migrating balances to a new journal file at the start
+of a new year.
+It prints a \[dq]closing balances\[dq] transaction that zeroes out
+account balances (Asset and Liability accounts, by default), and an
+opposite \[dq]opening balances\[dq] transaction that restores them
+again.
+Typically, you would run
+.IP
+.EX
+hledger close \-\-clopen \-e NEWYEAR >> $LEDGER_FILE
+.EE
 .PP
-This is useful when migrating balances to a new journal file at the
-start of a new year.
-Essentially, you run
-\f[CR]hledger close \-\-migrate=NEWYEAR \-e NEWYEAR\f[R] and then copy
-the closing transaction to the end of the old file and the opening
-transaction to the start of the new file.
-The opening transaction sets correct starting balances in the new file
-when it is used alone, and the closing transaction keeps balances
-correct when you use both old and new files together, by cancelling out
-the following opening transaction and preventing buildup of duplicated
-opening balances.
-Think of the closing/opening pair as \[dq]moving the balances into the
-next file\[dq].
+and then move the opening transaction from the old file to the new file
+(and probably also update your LEDGER_FILE environment variable).
 .PP
-You can close a different set of accounts by providing a query.
-Eg if you want to include equity, you can add
-\f[CR]assets liabilities equity\f[R] or \f[CR]type:ALE\f[R] arguments.
-(The balancing account is always excluded.)
-Revenues and expenses usually are not migrated to a new file directly;
-see \f[CR]\-\-retain\f[R] below.
+Why might you do this ?
+If your reports are fast, you may not need it.
+But at some point you will probably want to partition your data by time,
+for performance or data integrity or regulatory reasons.
+A new file or set of files per year is common.
+Then, having each file/fileset \[dq]bookended\[dq] with opening and
+closing balance transactions will allow you to freely pick and choose
+which files to read \- just the current year, any past year, any
+sequence of years, or all of them \- while showing correct account
+balances in each case.
+The earliest opening balances transaction sets correct starting
+balances, and any later closing/opening pairs will harmlessly cancel
+each other out.
 .PP
-The generated transactions will have a \f[CR]start:\f[R] tag, with its
-value set to \f[CR]\-\-migrate\f[R]\[aq]s \f[CR]NEW\f[R] argument if
-any, for easier matching or exclusion.
-When \f[CR]NEW\f[R] is not specified, it will be inferred if possible by
-incrementing a number (eg a year number) within the default
-journal\[aq]s main file name.
-The other modes behave similarly.
+The balances will be transferred to and from
+\f[CR]equity:opening/closing balances\f[R] by default.
+You can override this by using \f[CR]\-\-close\-acct\f[R] and/or
+\f[CR]\-\-open\-acct\f[R].
+.PP
+You can select a different set of accounts to close/open by providing an
+account query.
+Eg to add Equity accounts, provide arguments like
+\f[CR]assets liabilities equity\f[R] or \f[CR]type:ALE\f[R].
+When migrating to a new file, you\[aq]ll usually want to bring along the
+AL or ALE accounts, but not the RX accounts (Revenue, Expense).
+.PP
+Assertions will be added indicating and checking the new balances of the
+closed/opened accounts.
+.PP
+The generated transactions will have a \f[CR]clopen:\f[R] tag.
+If the main journal\[aq]s base file name contains a number (eg a year
+number), the tag\[aq]s value will be that base file name with the number
+incremented.
+Or you can choose the tag value yourself, by using
+\f[CR]\-\-clopen=TAGVAL\f[R].
 .SS close \-\-close
 This prints just the closing balances transaction of
-\f[CR]\-\-migrate\f[R].
-It is the default behaviour if you specify no mode flag.
-Using the customisation options below, you can move balances from any
-set of accounts to a different account.
+\f[CR]\-\-clopen\f[R].
+It is the default if you don\[aq]t specify a mode.
+.PP
+More customisation options are described below.
+Among other things, you can use \f[CR]close \-\-close\f[R] to generate a
+transaction moving the balances from any set of accounts, to a different
+account.
+(If you need to move just a portion of the balance, see hledger\-move.)
 .SS close \-\-open
 This prints just the opening balances transaction of
-\f[CR]\-\-migrate\f[R].
-It is similar to Ledger\[aq]s equity command.
+\f[CR]\-\-clopen\f[R].
+(It is similar to Ledger\[aq]s equity command.)
 .SS close \-\-assert
-This prints a \[dq]closing balances\[dq] transaction (with
-\f[CR]balances:\f[R] tag), that just declares balance assertions for the
-current balances without changing them.
+This prints a transaction that asserts the account balances as they are
+on the end date (and adds an \f[CR]assert:\f[R] tag).
 It could be useful as documention and to guard against changes.
 .SS close \-\-assign
-This prints an \[dq]opening balances\[dq] transaction that restores the
-account balances using balance assignments.
-Balance assignments work regardless of any previous balance, so a
-preceding closing balances transaction is not needed.
+This prints a transaction that assigns the account balances as they are
+on the end date (and adds an \[dq]assign:\[dq] tag).
+Unlike balance assertions, assignments will post changes to balances as
+needed to reach the specified amounts.
 .PP
-However, omitting the closing balances transaction would unbalance
-equity.
-This is relatively harmless for personal reports, but it disturbs the
-accounting equation, removing a source of error detection.
-So \f[CR]\-\-migrate\f[R] is generally the best way to set to set
-balances in new files, for now.
+This is another way to set starting balances when migrating to a new
+file, and it will set them correctly even in the presence of earlier
+files which do not have a closing balances transaction.
+However, it can hide errors, and disturb the accounting equation, so
+\f[CR]\-\-clopen\f[R] is usually recommended.
 .SS close \-\-retain
-This is like \f[CR]\-\-close\f[R] with different defaults: it prints a
-\[dq]retain earnings\[dq] transaction (with \f[CR]retain:\f[R] tag),
-that transfers revenue and expense balances to
-\f[CR]equity:retained earnings\f[R].
+This is like \f[CR]\-\-close\f[R], but it closes Revenue and Expense
+account balances by default.
+They will be transferred to \f[CR]equity:retained earnings\f[R], or
+another account specified with \f[CR]\-\-close\-acct\f[R].
 .PP
-This is a different kind of closing, called \[dq]retaining earnings\[dq]
-or \[dq]closing the books\[dq]; it is traditionally performed by
-businesses at the end of each accounting period, to consolidate revenues
-and expenses into the main equity balance.
-(\[dq]Revenues\[dq] and \[dq]expenses\[dq] are actually equity by
-another name, kept separate temporarily for reporting purposes.)
+Revenues and expenses correspond to changes in equity.
+They are categorised separately for reporting purposes, but
+traditionally at the end of each accounting period, businesses
+consolidate them into equity, This is called \[dq]retaining
+earnings\[dq], or \[dq]closing the books\[dq].
 .PP
-In personal accounting you generally don\[aq]t need to do this, unless
-you want the \f[CR]balancesheetequity\f[R] report to show a zero total,
-demonstrating that the accounting equation (A\-L=E) is satisfied.
+In personal accounting, there\[aq]s not much reason to do this, and most
+people don\[aq]t.
+(One reason to do it is to help the \f[CR]balancesheetequity\f[R] report
+show a zero total, demonstrating that the accounting equation (A\-L=E)
+is satisfied.)
 .SS close customisation
 In all modes, the following things can be overridden:
 .IP \[bu] 2
@@ -11582,7 +11888,7 @@
 2023\-01\-01:
 .IP
 .EX
-$ hledger close \-\-migrate \-f 2022.journal \-p 2022
+$ hledger close \-\-clopen \-f 2022.journal \-p 2022
 # copy/paste the closing transaction to the end of 2022.journal
 # copy/paste the opening transaction to the start of 2023.journal
 .EE
@@ -11595,15 +11901,15 @@
 .EE
 .PP
 For more flexibility, it helps to tag closing and opening transactions
-with eg \f[CR]start:NEWYEAR\f[R], then you can ensure correct balances
+with eg \f[CR]clopen:NEWYEAR\f[R], then you can ensure correct balances
 by excluding all opening/closing transactions except the first, like so:
 .IP
 .EX
-$ hledger bs \-Y \-f 2021.j \-f 2022.j \-f 2023.j expr:\[aq]tag:start=2021 or not tag:start\[aq]
-$ hledger bs \-Y \-f 2021.j \-f 2022.j           expr:\[aq]tag:start=2021 or not tag:start\[aq]
-$ hledger bs \-Y \-f 2022.j \-f 2023.j           expr:\[aq]tag:start=2022 or not tag:start\[aq]
-$ hledger bs \-Y \-f 2021.j                     expr:\[aq]tag:start=2021 or not tag:start\[aq]
-$ hledger bs \-Y \-f 2022.j                     expr:\[aq]tag:start=2022 or not tag:start\[aq]
+$ hledger bs \-Y \-f 2021.j \-f 2022.j \-f 2023.j expr:\[aq]tag:clopen=2021 or not tag:clopen\[aq]
+$ hledger bs \-Y \-f 2021.j \-f 2022.j           expr:\[aq]tag:clopen=2021 or not tag:clopen\[aq]
+$ hledger bs \-Y \-f 2022.j \-f 2023.j           expr:\[aq]tag:clopen=2022 or not tag:clopen\[aq]
+$ hledger bs \-Y \-f 2021.j                     expr:\[aq]tag:clopen=2021 or not tag:clopen\[aq]
+$ hledger bs \-Y \-f 2022.j                     expr:\[aq]tag:clopen=2022 or not tag:clopen\[aq]
 $ hledger bs \-Y \-f 2023.j                     # unclosed file, no query needed
 .EE
 .SS More detailed close examples
diff --git a/embeddedfiles/hledger.info b/embeddedfiles/hledger.info
--- a/embeddedfiles/hledger.info
+++ b/embeddedfiles/hledger.info
@@ -1,12703 +1,12983 @@
-This is hledger.info, produced by makeinfo version 7.1.1 from stdin.
-
-INFO-DIR-SECTION User Applications
-START-INFO-DIR-ENTRY
-* hledger: (hledger).  Command-line plain text accounting tool.
-END-INFO-DIR-ENTRY
-
-
-File: hledger.info,  Node: Top,  Next: PART 1 USER INTERFACE,  Up: (dir)
-
-hledger(1)
-**********
-
-hledger - a robust, friendly plain text accounting app (command line
-version).
-
-   'hledger'
-or
-'hledger COMMAND [OPTS] [ARGS]'
-or
-'hledger ADDONCMD [OPTS] -- [ADDONOPTS] [ADDONARGS]'
-
-   hledger is a robust, user-friendly, cross-platform set of programs
-for tracking money, time, or any other commodity, using double-entry
-accounting and a simple, editable file format.  hledger is inspired by
-and largely compatible with ledger(1), and largely interconvertible with
-beancount(1).
-
-   This manual is for hledger's command line interface, version 1.41.
-It also describes the common options, file formats and concepts used by
-all hledger programs.  It might accidentally teach you some
-bookkeeping/accounting as well!  You don't need to know everything in
-here to use hledger productively, but when you have a question about
-functionality, this doc should answer it.  It is detailed, so do skip
-ahead or skim when needed.  You can read it on hledger.org, or as an
-info manual or man page on your system.  You can also open a built-in
-copy, at a point of interest, by running
-'hledger --man [CMD]', 'hledger --info [CMD]' or 'hledger help [TOPIC]'.
-
-   (And for shorter help, try 'hledger --tldr [CMD]'.)
-
-   The main function of the hledger CLI is to read plain text files
-describing financial transactions, crunch the numbers, and print a
-useful report on the terminal (or save it as HTML, CSV, JSON or SQL).
-Many reports are available, as subcommands.  hledger will also detect
-other 'hledger-*' executables as extra subcommands.
-
-   hledger usually reads from (and appends to) a journal file specified
-by the 'LEDGER_FILE' environment variable (defaulting to
-'$HOME/.hledger.journal'); or you can specify files with '-f' options.
-It can also read timeclock files, timedot files, or any CSV/SSV/TSV file
-with a date field.
-
-   Here is a small journal file describing one transaction:
-
-2015-10-16 bought food
-  expenses:food          $10
-  assets:cash
-
-   Transactions are dated movements of money (etc.)  between two or more
-_accounts_: bank accounts, your wallet, revenue/expense categories,
-people, etc.  You can choose any account names you wish, using ':' to
-indicate subaccounts.  There must be at least two spaces between account
-name and amount.  Positive amounts are inflow to that account (_debit_),
-negatives are outflow from it (_credit_).  (Some reports show revenue,
-liability and equity account balances as negative numbers as a result;
-this is normal.)
-
-   hledger's add command can help you add transactions, or you can
-install other data entry UIs like hledger-web or hledger-iadd.  For more
-extensive/efficient changes, use a text editor: Emacs + ledger-mode, VIM
-+ vim-ledger, or VS Code + hledger-vscode are some good choices (see
-https://hledger.org/editors.html).
-
-   To get started, run 'hledger add' and follow the prompts, or save
-some entries like the above in '$HOME/.hledger.journal', then try
-commands like:
-
-$ hledger print -x
-$ hledger aregister assets
-$ hledger balance
-$ hledger balancesheet
-$ hledger incomestatement
-
-   Run 'hledger' to list the commands.  See also the "Starting a journal
-file" and "Setting opening balances" sections in PART 5: COMMON TASKS.
-
-* Menu:
-
-* PART 1 USER INTERFACE::
-* Input::
-* Commands::
-* Options::
-* Output::
-* Environment::
-* PART 2 DATA FORMATS::
-* Journal::
-* CSV::
-* Timeclock::
-* Timedot::
-* PART 3 REPORTING CONCEPTS::
-* Time periods::
-* Depth::
-* Queries::
-* Pivoting::
-* Generating data::
-* Forecasting::
-* Budgeting::
-* Amount formatting::
-* Cost reporting::
-* Value reporting::
-* PART 4 COMMANDS::
-* Help commands::
-* User interface commands::
-* Data entry commands::
-* Basic report commands::
-* Standard report commands::
-* Advanced report commands::
-* Chart commands::
-* Data generation commands::
-* Maintenance commands::
-* PART 5 COMMON TASKS::
-* Getting help::
-* Constructing command lines::
-* Starting a journal file::
-* Setting LEDGER_FILE::
-* Setting opening balances::
-* Recording transactions::
-* Reconciling::
-* Reporting::
-* Migrating to a new file::
-* BUGS::
-
-
-File: hledger.info,  Node: PART 1 USER INTERFACE,  Next: Input,  Prev: Top,  Up: Top
-
-1 PART 1: USER INTERFACE
-************************
-
-
-File: hledger.info,  Node: Input,  Next: Commands,  Prev: PART 1 USER INTERFACE,  Up: Top
-
-2 Input
-*******
-
-hledger reads one or more data files, each time you run it.  You can
-specify a file with '-f', like so
-
-$ hledger -f FILE [-f FILE2 ...] print
-
-   Files are most often in hledger's journal format, with the '.journal'
-file extension ('.hledger' or '.j' also work); these files describe
-transactions, like an accounting general journal.
-
-   When no file is specified, hledger looks for '.hledger.journal' in
-your home directory.
-
-   But most people prefer to keep financial files in a dedicated folder,
-perhaps with version control.  Also, starting a new journal file each
-year is common (it's not required, but helps keep things fast and
-organised).  So we usually configure a different journal file, by
-setting the 'LEDGER_FILE' environment variable, to something like
-'~/finance/2023.journal'.  For more about how to do that on your system,
-see Common tasks > Setting LEDGER_FILE.
-
-* Menu:
-
-* Text encoding::
-* Data formats::
-* Standard input::
-* Multiple files::
-* Strict mode::
-
-
-File: hledger.info,  Node: Text encoding,  Next: Data formats,  Up: Input
-
-2.1 Text encoding
-=================
-
-Data files containing non-ascii characters must use UTF-8 encoding.  An
-optional byte order mark (BOM) is allowed, at the beginning of the file
-(only).
-
-   Also, your system should be configured with a locale that can decode
-UTF-8 text.  On some unix systems, you may need set the 'LANG'
-environment variable, eg.  You can read more about this in Unicode
-characters, below.
-
-   On unix systems you can check a file's encoding with the 'file'
-command.  If you need to import from a UTF-16-encoded CSV file, say, you
-can convert it to UTF-8 with the 'iconv' command.
-
-
-File: hledger.info,  Node: Data formats,  Next: Standard input,  Prev: Text encoding,  Up: Input
-
-2.2 Data formats
-================
-
-Usually the data file is in hledger's journal format, but it can be in
-any of the supported file formats, which currently are:
-
-Reader:        Reads:                             Automatically used for
-                                                  files with extensions:
----------------------------------------------------------------------------
-'journal'      hledger journal files and some     '.journal' '.j'
-               Ledger journals, for               '.hledger' '.ledger'
-               transactions
-'timeclock'    timeclock files, for precise       '.timeclock'
-               time logging
-'timedot'      timedot files, for approximate     '.timedot'
-               time logging
-'csv'          Comma or other character           '.csv'
-               separated values, for data
-               import
-'ssv'          Semicolon separated values         '.ssv'
-'tsv'          Tab separated values               '.tsv'
-'rules'        CSV/SSV/TSV/other separated        '.rules'
-               values, alternate way
-
-   These formats are described in more detail below.
-
-   hledger detects the format automatically based on the file extensions
-shown above.  If it can't recognise the file extension, it assumes
-'journal' format.  So for non-journal files, it's important to use a
-recognised file extension, so as to either read successfully or to show
-relevant error messages.
-
-   You can also force a specific reader/format by prefixing the file
-path with the format and a colon.  Eg, to read a .dat file containing
-tab separated values:
-
-$ hledger -f tsv:/some/file.dat stats
-
-
-File: hledger.info,  Node: Standard input,  Next: Multiple files,  Prev: Data formats,  Up: Input
-
-2.3 Standard input
-==================
-
-The file name '-' means standard input:
-
-$ cat FILE | hledger -f- print
-
-   If reading non-journal data in this way, you'll need to write the
-format as a prefix, like 'timeclock:' here:
-
-$ echo 'i 2009/13/1 08:00:00' | hledger print -f timeclock:-
-
-
-File: hledger.info,  Node: Multiple files,  Next: Strict mode,  Prev: Standard input,  Up: Input
-
-2.4 Multiple files
-==================
-
-You can specify multiple '-f' options, to read multiple files as one big
-journal.  When doing this, note that certain features (described below)
-will be affected:
-
-   * Balance assertions will not see the effect of transactions in
-     previous files.  (Usually this doesn't matter as each file will set
-     the corresponding opening balances.)
-   * Some directives will not affect previous or subsequent files.
-
-   If needed, you can work around these by using a single parent file
-which includes the others, or concatenating the files into one, eg: 'cat
-a.journal b.journal | hledger -f- CMD'.
-
-
-File: hledger.info,  Node: Strict mode,  Prev: Multiple files,  Up: Input
-
-2.5 Strict mode
-===============
-
-hledger checks input files for valid data.  By default, the most
-important errors are detected, while still accepting easy journal files
-without a lot of declarations:
-
-   * Are the input files parseable, with valid syntax ?
-   * Are all transactions balanced ?
-   * Do all balance assertions pass ?
-
-   With the '-s'/'--strict' flag, additional checks are performed:
-
-   * Are all accounts posted to, declared with an 'account' directive ?
-     (Account error checking)
-   * Are all commodities declared with a 'commodity' directive ?
-     (Commodity error checking)
-   * Are all commodity conversions declared explicitly ?
-
-   You can use the check command to run individual checks - the ones
-listed above and some more.
-
-
-File: hledger.info,  Node: Commands,  Next: Options,  Prev: Input,  Up: Top
-
-3 Commands
-**********
-
-hledger provides various subcommands for getting things done.  Most of
-these commands do not change the journal file; they just read it and
-output a report.  A few commands assist with adding data and file
-management.
-
-   To show a summary of commands, run 'hledger' with no arguments.  You
-can see the same commands summary at the start of PART 4: COMMANDS
-below.
-
-   To use a particular command, run 'hledger CMD [CMDOPTS] [CMDARGS]',
-
-   * CMD is the full command name, or its standard abbreviation shown in
-     the commands list, or any unambiguous prefix of the name.
-
-   * CMDOPTS are command-specific options, if any.  Command-specific
-     options must be written after the command name.  Eg: 'hledger print
-     -x'.
-
-   * CMDARGS are additional arguments to the command, if any.  Most
-     hledger commands accept arguments representing a query, to limit
-     the data in some way.  Eg: 'hledger reg assets:checking'.
-
-   To list a command's options, arguments, and documentation in the
-terminal, run 'hledger CMD -h'.  Eg: 'hledger bal -h'.
-
-* Menu:
-
-* Add-on commands::
-
-
-File: hledger.info,  Node: Add-on commands,  Up: Commands
-
-3.1 Add-on commands
-===================
-
-In addition to the built-in commands, you can install _add-on commands_:
-programs or scripts named "hledger-SOMETHING", which will also appear in
-hledger's commands list.  If you used the hledger-install script, you
-will have several add-ons installed already.  Some more can be found in
-hledger's bin/ directory, documented at
-https://hledger.org/scripts.html.
-
-   More precisely, add-on commands are programs or scripts in your
-shell's PATH, whose name starts with "hledger-" and ends with no
-extension or a recognised extension (".bat", ".com", ".exe", ".hs",
-".js", ".lhs", ".lua", ".php", ".pl", ".py", ".rb", ".rkt", or ".sh"),
-and (on unix and mac) which has executable permission for the current
-user.
-
-   You can run add-on commands using hledger, much like built-in
-commands: 'hledger ADDONCMD [-- ADDONCMDOPTS] [ADDONCMDARGS]'.  But note
-the double hyphen argument, required before add-on-specific options.
-Eg: 'hledger ui -- --watch' or 'hledger web -- --serve'.  If this causes
-difficulty, you can always run the add-on directly, without using
-'hledger': 'hledger-ui --watch' or 'hledger-web --serve'.
-
-
-File: hledger.info,  Node: Options,  Next: Output,  Prev: Commands,  Up: Top
-
-4 Options
-*********
-
-Run 'hledger -h' to see general command line help.  Options can be
-written either before or after the command name.  These options are
-specific to the 'hledger' CLI:
-
-Flags:
-     --conf=CONFFILE        Use extra options defined in this config file. If
-                            not specified, searches upward and in XDG config
-                            dir for hledger.conf (or .hledger.conf in $HOME).
-  -n --no-conf              ignore any config file
-
-   And the following general options are common to most hledger
-commands:
-
-General input/data transformation flags:
-  -f --file=[FMT:]FILE      Read data from FILE, or from stdin if FILE is -,
-                            inferring format from extension or a FMT: prefix.
-                            Can be specified more than once. If not specified,
-                            reads from $LEDGER_FILE or $HOME/.hledger.journal.
-     --rules=RULESFILE      Use rules defined in this rules file for
-                            converting subsequent CSV/SSV/TSV files. If not
-                            specified, uses FILE.csv.rules for each FILE.csv.
-     --alias=A=B|/RGX/=RPL  transform account names from A to B, or by
-                            replacing regular expression matches
-     --auto                 generate extra postings by applying auto posting
-                            rules ("=") to all transactions
-     --forecast[=PERIOD]    Generate extra transactions from periodic rules
-                            ("~"), from after the latest ordinary transaction
-                            until 6 months from now. Or, during the specified
-                            PERIOD (the equals is required). Auto posting rules
-                            will also be applied to these transactions. In
-                            hledger-ui, also make future-dated transactions
-                            visible at startup.
-  -I --ignore-assertions    don't check balance assertions by default
-     --infer-costs          infer conversion equity postings from costs
-     --infer-equity         infer costs from conversion equity postings
-     --infer-market-prices  infer market prices from costs
-     --pivot=TAGNAME        use a different field or tag as account names
-  -s --strict               do extra error checks (and override -I)
-     --verbose-tags         add tags indicating generated/modified data
-
-General output/reporting flags (supported by some commands):
-  -b --begin=DATE           include postings/transactions on/after this date
-  -e --end=DATE             include postings/transactions before this date
-                            (with a report interval, will be adjusted to
-                            following subperiod end)
-  -D --daily                multiperiod report with 1 day interval
-  -W --weekly               multiperiod report with 1 week interval
-  -M --monthly              multiperiod report with 1 month interval
-  -Q --quarterly            multiperiod report with 1 quarter interval
-  -Y --yearly               multiperiod report with 1 year interval
-  -p --period=PERIODEXP     set begin date, end date, and/or report interval,
-                            with more flexibility
-     --today=DATE           override today's date (affects relative dates)
-     --date2                match/use secondary dates instead (deprecated)
-  -U --unmarked             include only unmarked postings/transactions
-  -P --pending              include only pending postings/transactions
-  -C --cleared              include only cleared postings/transactions
-                            (-U/-P/-C can be combined)
-  -R --real                 include only non-virtual postings
-  -E --empty                Show zero items, which are normally hidden.
-                            In hledger-ui & hledger-web, do the opposite.
-     --depth=DEPTHEXP       if a number (or -NUM): show only top NUM levels
-                            of accounts. If REGEXP=NUM, only apply limiting to
-                            accounts matching the regular expression.
-  -B --cost                 show amounts converted to their cost/sale amount
-  -V --market               Show amounts converted to their value at period
-                            end(s) in their default valuation commodity.
-                            Equivalent to --value=end.
-  -X --exchange=COMM        Show amounts converted to their value at period
-                            end(s) in the specified commodity.
-                            Equivalent to --value=end,COMM.
-     --value=WHEN[,COMM]    show amounts converted to their value on the
-                            specified date(s) in their default valuation
-                            commodity or a specified commodity. WHEN can be:
-                            'then':     value on transaction dates
-                            'end':      value at period end(s)
-                            'now':      value today
-                            YYYY-MM-DD: value on given date
-  -c --commodity-style=S    Override a commodity's display style.
-                            Eg: -c '.' or -c '1.000,00 EUR'
-     --pretty[=YN]          Use box-drawing characters in text output? Can be
-                            'y'/'yes' or 'n'/'no'.
-                            If YN is specified, the equals is required.
-
-General help flags:
-  -h --help                 show command line help
-     --tldr                 show command examples with tldr
-     --info                 show the manual with info
-     --man                  show the manual with man
-     --version              show version information
-     --debug=[1-9]          show this much debug output (default: 1)
-     --pager=YN             use a pager when needed ? y/yes (default) or n/no
-     --color=YNA --colour   use ANSI color ? y/yes, n/no, or auto (default)
-
-   Usually hledger accepts any unambiguous flag prefix, eg you can write
-'--tl' instead of '--tldr' or '--dry' instead of '--dry-run'.
-
-   If the same option appears more than once in a command, usually the
-last (right-most) wins.
-
-   With most commands, arguments are interpreted as a hledger query
-which filter the data.  Some queries can be expressed either with
-options or with arguments.
-
-   Below are more tips for using the command line interface - feel free
-to skip these until you need them.
-
-* Menu:
-
-* Special characters::
-* Unicode characters::
-* Regular expressions::
-* Argument files::
-* Config files::
-* Shell completions::
-
-
-File: hledger.info,  Node: Special characters,  Next: Unicode characters,  Up: Options
-
-4.1 Special characters
-======================
-
-Here we touch on shell escaping/quoting rules, and give some examples.
-This is a slightly complicated topic which you may not need at first,
-but you should be aware of it, so you can return here when needed.
-
-   If you are able to minimise the use of special characters in your
-data, you won't need escaping as much, and your command lines will be
-simpler.  For example, avoiding spaces in account names, and using an
-ISO-4217 currency code like 'USD' instead of the '$' currency symbol,
-can be helpful.
-
-   But if you want to use spaced account names and '$', go right ahead;
-escaping isn't a big deal.
-
-* Menu:
-
-* Escaping shell special characters::
-* Escaping on Windows::
-* Escaping regular expression special characters::
-* Escaping add-on arguments::
-* Escaping in other situations::
-* Using a wild card::
-
-
-File: hledger.info,  Node: Escaping shell special characters,  Next: Escaping on Windows,  Up: Special characters
-
-4.1.1 Escaping shell special characters
----------------------------------------
-
-At the command line, characters which have special meaning for your
-shell must be "shell-escaped" (AKA "quoted") if you want hledger to see
-them.  Often these include space, '<', '>', '(', ')', '|', '\', '$'
-and/or '%'.
-
-   For example, to match an account name containing the phrase "credit
-card", don't write this:
-
-$ hledger register credit card
-
-   In that command, "credit" and "card" are treated as separate query
-arguments (described below), so this would match accounts containing
-either word.  Instead, enclose the phrase in double or single quotes:
-
-$ hledger register "credit card"
-
-   In Unix shells, writing a backslash before the character can also
-work.  Eg:
-
-$ hledger register credit\ card
-
-   Some shell characters still have a special meaning inside double
-quotes, such as the dollar sign ('$').  Eg in '"assets:$account"', the
-bash shell would replace '$account' with the value of a shell variable
-with that name.  When you don't want that, use single quotes, which
-escape more strongly:
-
-$ hledger balance 'assets:$account'
-
-
-File: hledger.info,  Node: Escaping on Windows,  Next: Escaping regular expression special characters,  Prev: Escaping shell special characters,  Up: Special characters
-
-4.1.2 Escaping on Windows
--------------------------
-
-If you are using hledger in a Powershell or Command window on Microsoft
-Windows, the escaping rules are different:
-
-   * In a Powershell window ('powershell', blue background), you must
-     use double quotes or single quotes (not backslash).
-   * In a Command window ('cmd', black background), you must use double
-     quotes (not single quotes or backslash).
-
-   The next two sections were written for Unix-like shells, so might
-need to be adapted if you're using 'cmd' or 'powershell'.  (Edits
-welcome.)
-
-
-File: hledger.info,  Node: Escaping regular expression special characters,  Next: Escaping add-on arguments,  Prev: Escaping on Windows,  Up: Special characters
-
-4.1.3 Escaping regular expression special characters
-----------------------------------------------------
-
-Many hledger arguments are regular expressions (described below), and
-these too have characters which cause special effects.  Some of those
-characters are '.', '^', '$', '[', ']', '(', ')', '|', and '\'.  When
-you don't want these to cause special effects, you can "regex-escape"
-them by writing '\' (a backslash) before them.  But since backslash is
-also special to the shell, you may need to also shell-escape the
-backslashes.
-
-   Eg, in the bash shell, to match a literal '$' sign, you could write:
-
-$ hledger balance cur:\\$
-
-   or:
-
-$ hledger balance 'cur:\$'
-
-   (The dollar sign is regex-escaped by the backslash preceding it.
-Then that backslash is shell-escaped by another backslash, or by single
-quotes.)
-
-
-File: hledger.info,  Node: Escaping add-on arguments,  Next: Escaping in other situations,  Prev: Escaping regular expression special characters,  Up: Special characters
-
-4.1.4 Escaping add-on arguments
--------------------------------
-
-When you run an external add-on command with 'hledger' (described
-below), any options or arguments being passed through to the add-on
-executable lose one level of shell-escaping, so you must add an extra
-level of shell-escaping to compensate.
-
-   Eg, in the bash shell, to run the 'ui' add-on and match a literal '$'
-sign, you need to write:
-
-$ hledger ui cur:'\\$'
-
-   or:
-
-$ hledger ui cur:\\\\$
-
-   If you are wondering why _four_ backslashes:
-
-   * '$' is unescaped
-   * '\$' is regex-escaped
-   * '\\$' is regex-escaped, then shell-escaped
-   * '\\\\$' is regex-escaped, then shell-escaped, then both slashes are
-     shell-escaped once more for hledger argument pass-through.
-
-   Or you can avoid such triple-escaping, by running the add-on
-executable directly:
-
-$ hledger-ui cur:\\$
-
-
-File: hledger.info,  Node: Escaping in other situations,  Next: Using a wild card,  Prev: Escaping add-on arguments,  Up: Special characters
-
-4.1.5 Escaping in other situations
-----------------------------------
-
-hledger options and arguments are sometimes used in places other than
-the command line, with different escaping rules.  For example,
-backslash-quoting generally does not work there.  Here are some more
-tips.
-
-In Windows 'cmd'   Use double quotes
-In Windows         Use single or double quotes
-'powershell'
-In hledger-ui's    Use single or double quotes
-filter prompt
-In hledger-web's   Use single or double quotes
-search form
-In an argument     Don't use spaces, don't shell-escape, do
-file               regex-escape when needed
-In a config file   Use single or double quotes, and enclose the whole
-                   argument ('"desc:a b"' not 'desc:"a b"')
-In 'ghci' (the     Use double quotes, and enclose the whole argument
-Haskell REPL)
-
-
-File: hledger.info,  Node: Using a wild card,  Prev: Escaping in other situations,  Up: Special characters
-
-4.1.6 Using a wild card
------------------------
-
-When escaping a special character is too much hassle (or impossible),
-you can often just write '.' (period) instead.  In regular expressions,
-this means "accept any character here".  Eg:
-
-$ hledger register credit.card
-
-
-File: hledger.info,  Node: Unicode characters,  Next: Regular expressions,  Prev: Special characters,  Up: Options
-
-4.2 Unicode characters
-======================
-
-hledger is expected to handle non-ascii characters correctly:
-
-   * they should be parsed correctly in input files and on the command
-     line, by all hledger tools (add, iadd, hledger-web's
-     search/add/edit forms, etc.)
-
-   * they should be displayed correctly by all hledger tools, and
-     on-screen alignment should be preserved.
-
-   This requires a well-configured environment.  Here are some tips:
-
-   * A system locale must be configured, and it must be one that can
-     decode the characters being used.  In bash, you can set a locale
-     like this: 'export LANG=en_US.UTF-8'.  There are some more details
-     in Troubleshooting.  This step is essential - without it, hledger
-     will quit on encountering a non-ascii character (as with all
-     GHC-compiled programs).
-
-   * Your terminal software (eg Terminal.app, iTerm, CMD.exe, xterm..)
-     must support unicode.  On Windows, you may need to use Windows
-     Terminal and/or enable UTF-8 support.
-
-   * The terminal must be using a font which includes the required
-     unicode glyphs.
-
-   * The terminal should be configured to display wide characters as
-     double width (for report alignment).
-
-   * On Windows, for best results you should run hledger in the same
-     kind of environment in which it was built.  Eg hledger built in the
-     standard CMD.EXE environment (like the binaries on our download
-     page) might show display problems when run in a cygwin or msys
-     terminal, and vice versa.  (See eg #961).
-
-
-File: hledger.info,  Node: Regular expressions,  Next: Argument files,  Prev: Unicode characters,  Up: Options
-
-4.3 Regular expressions
-=======================
-
-A regular expression (regexp) is a small piece of text where certain
-characters (like '.', '^', '$', '+', '*', '()', '|', '[]', '\') have
-special meanings, forming a tiny language for matching text precisely -
-very useful in hledger and elsewhere.  To learn all about them, visit
-regular-expressions.info.
-
-   hledger supports regexps whenever you are entering a pattern to match
-something, eg in query arguments, account aliases, CSV if rules,
-hledger-web's search form, hledger-ui's '/' search, etc.  You may need
-to wrap them in quotes, especially at the command line (see Special
-characters above).  Here are some examples:
-
-   Account name queries (quoted for command line use):
-
-Regular expression:  Matches:
--------------------  ------------------------------------------------------------
-bank                 assets:bank, assets:bank:savings, expenses:art:banksy, ...
-:bank                assets:bank:savings, expenses:art:banksy
-:bank:               assets:bank:savings
-'^bank'              none of those ( ^ matches beginning of text )
-'bank$'              assets:bank   ( $ matches end of text )
-'big \$ bank'        big $ bank    ( \ disables following character's special meaning )
-'\bbank\b'           assets:bank, assets:bank:savings  ( \b matches word boundaries )
-'(sav|check)ing'     saving or checking  ( (|) matches either alternative )
-'saving|checking'    saving or checking  ( outer parentheses are not needed )
-'savings?'           saving or savings   ( ? matches 0 or 1 of the preceding thing )
-'my +bank'           my bank, my  bank, ... ( + matches 1 or more of the preceding thing )
-'my *bank'           mybank, my bank, my  bank, ... ( * matches 0 or more of the preceding thing )
-'b.nk'               bank, bonk, b nk, ... ( . matches any character )
-
-   Some other queries:
-
-desc:'amazon|amzn|audible'  Amazon transactions
-cur:EUR              amounts with commodity symbol containing EUR
-cur:'\$'             amounts with commodity symbol containing $
-cur:'^\$$'           only $ amounts, not eg AU$ or CA$
-cur:....?            amounts with 4-or-more-character symbols
-tag:.=202[1-3]       things with any tag whose value contains 2021, 2022 or 2023
-
-   Account name aliases: accept '.' instead of ':' as account separator:
-
-alias /\./=:         replaces all periods in account names with colons
-
-   Show multiple top-level accounts combined as one:
-
---alias='/^[^:]+/=combined'  ( [^:] matches any character other than : )
-
-   Show accounts with the second-level part removed:
-
---alias '/^([^:]+):[^:]+/ = \1'
-                     match a top-level account and a second-level account
-                     and replace those with just the top-level account
-                     ( \1 in the replacement text means "whatever was matched
-                     by the first parenthesised part of the regexp"
-
-   CSV rules: match CSV records containing dining-related MCC codes:
-
-if \?MCC581[124]
-
-   Match CSV records with a specific amount around the end/start of
-month:
-
-if %amount \b3\.99
-&  %date   (29|30|31|01|02|03)$
-
-* Menu:
-
-* hledger's regular expressions::
-
-
-File: hledger.info,  Node: hledger's regular expressions,  Up: Regular expressions
-
-4.3.1 hledger's regular expressions
------------------------------------
-
-hledger's regular expressions come from the regex-tdfa library.  If
-they're not doing what you expect, it's important to know exactly what
-they support:
-
-  1. they are case insensitive
-  2. they are infix matching (they do not need to match the entire thing
-     being matched)
-  3. they are POSIX ERE (extended regular expressions)
-  4. they also support GNU word boundaries ('\b', '\B', '\<', '\>')
-  5. backreferences are supported when doing text replacement in account
-     aliases or CSV rules, where backreferences can be used in the
-     replacement string to reference capturing groups in the search
-     regexp.  Otherwise, if you write '\1', it will match the digit '1'.
-  6. they do not support mode modifiers ('(?s)'), character classes
-     ('\w', '\d'), or anything else not mentioned above.
-  7. they may not (I'm guessing not) properly support right-to-left or
-     bidirectional text.
-
-   Some things to note:
-
-   * In the 'alias' directive and '--alias' option, regular expressions
-     must be enclosed in forward slashes ('/REGEX/').  Elsewhere in
-     hledger, these are not required.
-
-   * In queries, to match a regular expression metacharacter like '$' as
-     a literal character, prepend a backslash.  Eg to search for amounts
-     with the dollar sign in hledger-web, write 'cur:\$'.
-
-   * On the command line, some metacharacters like '$' have a special
-     meaning to the shell and so must be escaped at least once more.
-     See Special characters.
-
-
-File: hledger.info,  Node: Argument files,  Next: Config files,  Prev: Regular expressions,  Up: Options
-
-4.4 Argument files
-==================
-
-You can save a set of command line options and arguments in a file, and
-then reuse them by writing '@FILENAME' as a command line argument.  Eg:
-'hledger bal @foo.args'.
-
-   An argument file's format is more restrictive than the command line.
-Each line should contain just one option or argument.  Don't use spaces
-except inside quotes; write '=' or nothing between a flag and its
-argument.  If you use quotes, they must enclose the whole line.  For the
-special characters mentioned above, use one less level of quoting than
-you would at the command line.
-
-
-File: hledger.info,  Node: Config files,  Next: Shell completions,  Prev: Argument files,  Up: Options
-
-4.5 Config files
-================
-
-With hledger 1.40+, you can save extra command line options and
-arguments in a more featureful hledger config file.  Here's a small
-example:
-
-# General options are listed first, and used with hledger commands that support them.
---pretty
-
-# Options following a `[COMMAND]` heading are used with that hledger command only.
-[print]
---explicit --show-costs
-
-   To use a config file, specify it with the '--conf' option.  Its
-options will be inserted near the start of your command line, so you can
-override them with command line options if needed.
-
-   Or, you can set up an automatic config file that is used whenever you
-run hledger, by creating 'hledger.conf' in the current directory or
-above, or '.hledger.conf' in your home directory ('~/.hledger.conf'), or
-'hledger.conf' in your XDG config directory
-('~/.config/hledger/hledger.conf').
-
-   Here is another example config you could start with:
-https://github.com/simonmichael/hledger/blob/master/hledger.conf.sample
-
-   You can put not only options, but also arguments in a config file.
-If the first word in a config file's top (general) section does not
-begin with a dash (eg: 'print'), it is treated as the command argument
-(overriding any argument on the command line).
-
-   On unix machines, you can add a shebang line at the top of a config
-file, set executable permission on the file, and use it like a script.
-Eg (the '-S' is needed on some operating systems):
-
-#!/usr/bin/env -S hledger --conf
-
-   You can ignore config files by adding the '-n'/'--no-conf' flag to
-the command line.  This is useful when using hledger in scripts, or when
-troubleshooting.  When both '--conf' and '--no-conf' options are used,
-the right-most wins.
-
-   To inspect the processing of config files, use '--debug' or
-'--debug=8'.
-
-   *Warning!*
-
-   There aren't many hledger features that need a warning, but this is
-one!
-
-   Automatic config files, while convenient, also make hledger less
-predictable and dependable.  It's easy to make a config file that
-changes a report's behaviour, or breaks your hledger-using
-scripts/applications, in ways that will surprise you later.
-
-   If you don't want this,
-
-  1. Just don't create a hledger.conf file on your machine.
-  2. Also be alert to downloaded directories which may contain a
-     hledger.conf file.
-  3. Also if you are sharing scripts or examples or support, consider
-     that others may have a hledger.conf file.
-
-   Conversely, once you decide to use this feature, try to remember:
-
-  1. Whenever a hledger command does not work as expected, try it again
-     with '-n' ('--no-conf') to see if a config file was to blame.
-  2. Whenever you call hledger from a script, consider whether that call
-     should use '-n' or not.
-  3. Be conservative about what you put in your config file; try to
-     consider the effect on all your reports.
-  4. To troubleshoot the effect of config files, run with '--debug' or
-     '--debug 8'.
-
-   The config file feature was added in hledger 1.40 and is considered
-_experimental_.
-
-
-File: hledger.info,  Node: Shell completions,  Prev: Config files,  Up: Options
-
-4.6 Shell completions
-=====================
-
-If you use the bash shell, you can optionally set up context-sensitive
-autocompletions when you press TAB in a hledger command line.  At a bash
-shell prompt, try pressing 'hledger<SPACE><TAB><TAB>' (should list all
-hledger commands) or 'hledger reg acct:<TAB><TAB>' (should list your
-top-level account names).  If completions aren't working, or for more
-details, see Install > Shell completions.
-
-
-File: hledger.info,  Node: Output,  Next: Environment,  Prev: Options,  Up: Top
-
-5 Output
-********
-
-* Menu:
-
-* Output destination::
-* Output format::
-* Commodity styles::
-* Debug output::
-
-
-File: hledger.info,  Node: Output destination,  Next: Output format,  Up: Output
-
-5.1 Output destination
-======================
-
-hledger commands send their output to the terminal by default.  You can
-of course redirect this, eg into a file, using standard shell syntax:
-
-$ hledger print > foo.txt
-
-   Some commands (print, register, stats, the balance commands) also
-provide the '-o'/'--output-file' option, which does the same thing
-without needing the shell.  Eg:
-
-$ hledger print -o foo.txt
-$ hledger print -o -        # write to stdout (the default)
-
-
-File: hledger.info,  Node: Output format,  Next: Commodity styles,  Prev: Output destination,  Up: Output
-
-5.2 Output format
-=================
-
-Some commands offer other kinds of output, not just text on the
-terminal.  Here are those commands and the formats currently supported:
-
-command               txt   html   csv/tsv   fods   beancount    sql   json
-------------------------------------------------------------------------------
-aregister             Y     Y      Y         Y                         Y
-balance               Y     Y      Y         Y                         Y
-balancesheet          Y     Y      Y         Y                         Y
-balancesheetequity    Y     Y      Y         Y                         Y
-cashflow              Y     Y      Y         Y                         Y
-incomestatement       Y     Y      Y         Y                         Y
-print                 Y     Y      Y         Y      Y            Y     Y
-register              Y     Y      Y         Y                         Y
-
-   You can also see which output formats a command supports by running
-'hledger CMD -h' and looking for the '-O'/'--output-format=FMT' option,
-
-   You can select the output format by using that option:
-
-$ hledger print -O csv    # print CSV to standard output
-
-   or by choosing a suitable filename extension with the
-'-o'/'--output-file=FILE.FMT' option:
-
-$ hledger balancesheet -o foo.csv    # write CSV to foo.csv
-
-   The '-O' option can be combined with '-o' to override the file
-extension if needed:
-
-$ hledger balancesheet -o foo.txt -O csv    # write CSV to foo.txt
-
-   Here are some notes about the various output formats.
-
-* Menu:
-
-* Text output::
-* HTML output::
-* CSV / TSV output::
-* FODS output::
-* Beancount output::
-* SQL output::
-* JSON output::
-
-
-File: hledger.info,  Node: Text output,  Next: HTML output,  Up: Output format
-
-5.2.1 Text output
------------------
-
-This is the default: human readable, plain text report output, suitable
-for viewing with a monospace font in a terminal.  If your data contains
-unicode or wide characters, you'll need a terminal and font that render
-those correctly.  (This can be challenging on MS Windows.)
-
-   Some reports ('register', 'aregister') will use the width indicated
-by the 'COLUMNS' environment variable.  If your shell and terminal are
-working well, they will keep COLUMNS updated as you resize the window.
-So register reports normally will use the full window width.  When this
-isn't working or you want to override it, you can manually set COLUMNS,
-or use the '-w'/'--width' option.
-
-   Balance reports ('balance', 'balancesheet', 'incomestatement'...)
-use whatever width they need.  Multi-period multi-currency reports can
-often be wider than the window.  Besides using a pager, helpful
-techniques for this situation include '--layout=bare', '-V', 'cur:',
-'--transpose', '--tree', '--depth', '--drop', switching to html output,
-etc.
-
-* Menu:
-
-* Box-drawing characters::
-* Colour::
-* Paging::
-
-
-File: hledger.info,  Node: Box-drawing characters,  Next: Colour,  Up: Text output
-
-5.2.1.1 Box-drawing characters
-..............................
-
-hledger draws simple table borders by default, to minimise the risk of
-display problems caused by a terminal/font not supporting box-drawing
-characters.
-
-   But your terminal and font probably do support them, so we recommend
-using the '--pretty' flag to show prettier tables in the terminal.  This
-is a good flag to add to your hledger config file.
-
-
-File: hledger.info,  Node: Colour,  Next: Paging,  Prev: Box-drawing characters,  Up: Text output
-
-5.2.1.2 Colour
-..............
-
-hledger tries to automatically detect ANSI colour and text styling
-support and use it when appropriate.  (Currently, it is used rather
-minimally: some reports show negative numbers in red, and help output
-uses bold text for emphasis.)
-
-   You can override this by setting the 'NO_COLOR' environment variable
-to disable it, or by using the '--color/--colour' option, perhaps in
-your config file, with a 'y'/'yes' or 'n'/'no' value to force it on or
-off.
-
-
-File: hledger.info,  Node: Paging,  Prev: Colour,  Up: Text output
-
-5.2.1.3 Paging
-..............
-
-In unix-like environments, when displaying large output (in any output
-format) in the terminal, hledger tries to use a pager when appropriate.
-The pager shows one page of text at a time, and lets you scroll around
-to see more.  While it is active, usually 'SPACE' shows the next page,
-'h' shows help, and 'q' quits.  The home/end/page up/page down/cursor
-keys, and mouse scrolling, may also work.
-
-   hledger will use the pager specified by the 'PAGER' environment
-variable, otherwise 'less' if available, otherwise 'more' if available.
-(With one exception: 'hledger help -p TOPIC' will always use 'less', so
-that it can scroll to the topic.)
-
-   The pager is expected to display hledger's ANSI colour and text
-styling.  If you see junk characters, you might need to configure your
-pager to handle ANSI codes.  Or you could disable colour as described
-above.
-
-   If you are using the 'less' pager, hledger automatically appends a
-number of options to the 'LESS' variable to enable ANSI colour and a
-number of other conveniences.  (At the time of writing: -chop-long-lines
--hilite-unread -ignore-case -mouse -no-init -quit-at-eof
--quit-if-one-screen -RAW-CONTROL-CHARS -shift=8 -squeeze-blank-lines
--use-backslash -use-color ).  If these don't work well, you can set your
-preferred options in the 'HLEDGER_LESS' variable, which will be used
-instead.
-
-
-File: hledger.info,  Node: HTML output,  Next: CSV / TSV output,  Prev: Text output,  Up: Output format
-
-5.2.2 HTML output
------------------
-
-HTML output can be styled by an optional 'hledger.css' file in the same
-directory.
-
-   HTML output will be UTF-8 encoded.  If your web browser is showing
-junk characters, you may need to change its text encoding to UTF-8.  Eg
-in Safari, see View -> Text Encoding and Settings -> Advanced -> Default
-Encoding.
-
-
-File: hledger.info,  Node: CSV / TSV output,  Next: FODS output,  Prev: HTML output,  Up: Output format
-
-5.2.3 CSV / TSV output
-----------------------
-
-In CSV or TSV output, digit group marks (such as thousands separators)
-are disabled automatically.
-
-
-File: hledger.info,  Node: FODS output,  Next: Beancount output,  Prev: CSV / TSV output,  Up: Output format
-
-5.2.4 FODS output
------------------
-
-FODS is the OpenDocument Spreadsheet format as plain XML, as accepted by
-LibreOffice and OpenOffice.  If you use their spreadsheet applications,
-this is better than CSV because it works across locales (decimal point
-vs.  decimal comma, character encoding stored in XML header, thus no
-problems with umlauts), it supports fixed header rows and columns, cell
-types (string vs.  number vs.  date), separation of number and currency
-(currency is displayed but the cell type is still a number accessible
-for computation), styles (bold), borders.  Btw.  you can still extract
-CSV from FODS/ODS using various utilities like 'libreoffice --headless'
-or ods2csv.
-
-
-File: hledger.info,  Node: Beancount output,  Next: SQL output,  Prev: FODS output,  Up: Output format
-
-5.2.5 Beancount output
-----------------------
-
-This is Beancount's journal format.  You can use this to export your
-hledger data to Beancount, eg to use the Fava web app.
-
-   hledger will try to adjust your data to suit Beancount,
-automatically.  Be cautious and check the conversion until you are
-confident it is good.  If you plan to export to Beancount often, you may
-want to follow its conventions, for a cleaner conversion:
-
-   * use Beancount-friendly account names
-   * use currency codes instead of currency symbols
-   * use cost notation instead of equity conversion postings
-   * avoid virtual postings
-
-   There is one big adjustment you must handle yourself: for Beancount,
-the top level account names must be 'Assets', 'Liabilities', 'Equity',
-'Income', and/or 'Expenses'.  You can use account aliases to rewrite
-your account names temporarily, if needed, as in this
-hledger2beancount.conf config file.
-
-* Menu:
-
-* Beancount account names::
-* Beancount commodity names::
-* Beancount virtual postings::
-* Beancount metadata::
-* Beancount costs::
-* Beancount operating currency::
-
-
-File: hledger.info,  Node: Beancount account names,  Next: Beancount commodity names,  Up: Beancount output
-
-5.2.5.1 Beancount account names
-...............................
-
-Aside from the top-level names, hledger will adjust your account names
-to make valid Beancount account names, by capitalising each part,
-replacing spaces with '-', replacing other unsupported characters with
-'C<HEXBYTES>', prepending 'A' to account name parts which don't begin
-with a letter or digit, and appending ':A' to account names which have
-only one part.
-
-
-File: hledger.info,  Node: Beancount commodity names,  Next: Beancount virtual postings,  Prev: Beancount account names,  Up: Beancount output
-
-5.2.5.2 Beancount commodity names
-.................................
-
-hledger will adjust your commodity names to make valid Beancount
-commodity/currency names, which must be 2-24 uppercase letters, digits,
-or ''', '.', '_', '-', beginning with a letter and ending with a letter
-or digit.  hledger will convert known currency symbols to ISO 4217
-currency codes, capitalise letters, replace spaces with '-', replace
-other unsupported characters with 'C<HEXBYTES>', and prepend or append
-'C' if needed.
-
-
-File: hledger.info,  Node: Beancount virtual postings,  Next: Beancount metadata,  Prev: Beancount commodity names,  Up: Beancount output
-
-5.2.5.3 Beancount virtual postings
-..................................
-
-Beancount doesn't allow virtual postings; if you have any, they will be
-omitted from beancount output.
-
-
-File: hledger.info,  Node: Beancount metadata,  Next: Beancount costs,  Prev: Beancount virtual postings,  Up: Beancount output
-
-5.2.5.4 Beancount metadata
-..........................
-
-hledger tags will be converted to Beancount metadata (except for tags
-whose name begins with '_').  Metadata names will be adjusted to be
-Beancount-compatible: beginning with a lowercase letter, at least two
-characters long, and with unsupported characters encoded.  Metadata
-values will use Beancount's string type.
-
-   In hledger, objects can have the same tag repeated with multiple
-values.  Eg an 'assets:cash' account might have both 'type:Asset' and
-'type:Cash' tags.  For Beancount these will be combined into one, with
-the values combined, comma separated.  Eg: 'type: "Asset, Cash"'.
-
-
-File: hledger.info,  Node: Beancount costs,  Next: Beancount operating currency,  Prev: Beancount metadata,  Up: Beancount output
-
-5.2.5.5 Beancount costs
-.......................
-
-Beancount doesn't allow redundant costs and conversion postings as
-hledger does.  If you have any of these, the conversion postings will be
-omitted.  Currently we support at most one cost + conversion postings
-group per transaction.
-
-
-File: hledger.info,  Node: Beancount operating currency,  Prev: Beancount costs,  Up: Beancount output
-
-5.2.5.6 Beancount operating currency
-....................................
-
-Declaring an operating currency (or several) improves Beancount and Fava
-reports.  Currently hledger will declare each currency used in cost
-amounts as an operating currency.  If needed, replace these with your
-own declaration, like
-
-option "operating_currency" "USD"
-
-
-File: hledger.info,  Node: SQL output,  Next: JSON output,  Prev: Beancount output,  Up: Output format
-
-5.2.6 SQL output
-----------------
-
-SQL output is expected to work at least with SQLite, MySQL and Postgres.
-
-   The SQL statements are expected to be executed in the empty database.
-If you already have tables created via SQL output of hledger, you would
-probably want to either clear data from these (via 'delete' or
-'truncate' SQL statements) or 'drop' the tables completely before
-import; otherwise your postings would be duplicated.
-
-   For SQLite, it is more useful if you modify the generated 'id' field
-to be a PRIMARY KEY. Eg:
-
-$ hledger print -O sql | sed 's/id serial/id INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL/g' | ...
-
-   This is not yet much used; feedback is welcome.
-
-
-File: hledger.info,  Node: JSON output,  Prev: SQL output,  Up: Output format
-
-5.2.7 JSON output
------------------
-
-Our JSON is rather large and verbose, since it is a faithful
-representation of hledger's internal data types.  To understand its
-structure, read the Haskell type definitions, which are mostly in
-https://github.com/simonmichael/hledger/blob/master/hledger-lib/Hledger/Data/Types.hs.
-hledger-web's OpenAPI specification may also be relevant.
-
-   hledger stores numbers with sometimes up to 255 significant digits.
-This is too many digits for most JSON consumers, so in JSON output we
-round numbers to at most 10 decimal places.  (We don't limit the number
-of integer digits.)  If you find this causing problems, please let us
-know.  Related: #1195
-
-   This is not yet much used; feedback is welcome.
-
-
-File: hledger.info,  Node: Commodity styles,  Next: Debug output,  Prev: Output format,  Up: Output
-
-5.3 Commodity styles
-====================
-
-When displaying amounts, hledger infers a standard display style for
-each commodity/currency, as described below in Commodity display style.
-
-   If needed, this can be overridden by a '-c/--commodity-style' option
-(except for cost amounts and amounts displayed by the 'print' command,
-which are always displayed with all decimal digits).  For example, the
-following will force dollar amounts to be displayed as shown:
-
-$ hledger print -c '$1.000,0'
-
-   This option can repeated to set the display style for multiple
-commodities/currencies.  Its argument is as described in the commodity
-directive.
-
-   In some cases hledger will adjust number formatting to improve their
-parseability (such as adding trailing decimal marks when needed).
-
-
-File: hledger.info,  Node: Debug output,  Prev: Commodity styles,  Up: Output
-
-5.4 Debug output
-================
-
-We intend hledger to be relatively easy to troubleshoot, introspect and
-develop.  You can add '--debug[=N]' to any hledger command line to see
-additional debug output.  N ranges from 1 (least output, the default) to
-9 (maximum output).  Typically you would start with 1 and increase until
-you are seeing enough.  Debug output goes to stderr, and is not affected
-by '-o/--output-file' (unless you redirect stderr to stdout, eg:
-'2>&1').  It will be interleaved with normal output, which can help
-reveal when parts of the code are evaluated.  To capture debug output in
-a log file instead, you can usually redirect stderr, eg:
-
-hledger bal --debug=3 2>hledger.log
-
-   (This option doesn't work in a config file yet.)
-
-
-File: hledger.info,  Node: Environment,  Next: PART 2 DATA FORMATS,  Prev: Output,  Up: Top
-
-6 Environment
-*************
-
-These environment variables affect hledger:
-
-   *COLUMNS* This is normally set by your terminal; some hledger
-commands ('register') will format their output to this width.  If not
-set, they will try to use the available terminal width.
-
-   *HLEDGER_LESS* If 'less' is your pager, this variable specifies the
-'less' options hledger should use.  (Otherwise, 'LESS' + custom options
-are used.)
-
-   *LEDGER_FILE* The main journal file to use when not specified with
-'-f/--file'.  Default: '$HOME/.hledger.journal'.
-
-   *NO_COLOR* If this environment variable exists (with any value,
-including empty), hledger will not use ANSI color codes in terminal
-output, unless overridden by an explicit '--color=y' or '--colour=y'
-option.
-
-
-File: hledger.info,  Node: PART 2 DATA FORMATS,  Next: Journal,  Prev: Environment,  Up: Top
-
-7 PART 2: DATA FORMATS
-**********************
-
-
-File: hledger.info,  Node: Journal,  Next: CSV,  Prev: PART 2 DATA FORMATS,  Up: Top
-
-8 Journal
-*********
-
-hledger's usual data source is a plain text file containing journal
-entries in hledger 'journal' format.  If you're looking for a quick
-reference, jump ahead to the journal cheatsheet (or use the table of
-contents at https://hledger.org/hledger.html).
-
-   This file represents an accounting General Journal.  The '.journal'
-file extension is most often used, though not strictly required.  The
-journal file contains a number of transaction entries, each describing a
-transfer of money (or any commodity) between two or more named accounts,
-in a simple format readable by both hledger and humans.
-
-   hledger's journal format is compatible with most of Ledger's journal
-format, but not all of it.  The differences and interoperation tips are
-described at hledger and Ledger.  With some care, and by avoiding
-incompatible features, you can keep your hledger journal readable by
-Ledger and vice versa.  This can useful eg for comparing the behaviour
-of one app against the other.
-
-   You can use hledger without learning any more about this file; just
-use the add or web or import commands to create and update it.
-
-   Many users, though, edit the journal file with a text editor, and
-track changes with a version control system such as git.  Editor add-ons
-such as ledger-mode or hledger-mode for Emacs, vim-ledger for Vim, and
-hledger-vscode for Visual Studio Code, make this easier, adding colour,
-formatting, tab completion, and useful commands.  See Editor
-configuration at hledger.org for the full list.
-
-   A hledger journal file can contain three kinds of thing: comment
-lines, transactions, and/or directives (including periodic transaction
-rules and auto posting rules).  Understanding the journal file format
-will also give you a good understanding of hledger's data model.  Here's
-a quick cheatsheet/overview, followed by detailed descriptions of each
-part.
-
-* Menu:
-
-* Journal cheatsheet::
-* Comments::
-* Transactions::
-* Dates::
-* Status::
-* Code::
-* Description::
-* Transaction comments::
-* Postings::
-* Account names::
-* Amounts::
-* Balance assertions::
-* Posting comments::
-* Transaction balancing::
-* Tags::
-* Directives::
-* account directive::
-* alias directive::
-* commodity directive::
-* decimal-mark directive::
-* include directive::
-* P directive::
-* payee directive::
-* tag directive::
-* Periodic transactions::
-* Auto postings::
-* Other syntax::
-
-
-File: hledger.info,  Node: Journal cheatsheet,  Next: Comments,  Up: Journal
-
-8.1 Journal cheatsheet
-======================
-
-# Here is the main syntax of hledger's journal format
-# (omitting extra Ledger compatibility syntax).
-
-###############################################################################
-
-# 1. These are comment lines, for notes or temporarily disabling things.
-; They begin with # or ;
-
-comment
-Or, lines can be enclosed within "comment" / "end comment".
-This is a block of 
-commented lines.
-end comment
-
-# Some journal entries can have semicolon comments at end of line  ; like this
-# Some of them require 2 or more spaces before the semicolon.
-
-###############################################################################
-
-# 2. Directives customise processing or output in some way.
-# You don't need any directives to get started.
-# But they can add more error checking, or change how things are displayed.
-# They begin with a word, letter, or symbol. 
-# They are most often placed at the top, before transactions.
-
-account assets             ; Declare valid account names and display order.
-account assets:savings     ; A subaccount. This one represents a bank account.
-account assets:checking    ; Another. Note, 2+ spaces after the account name.
-account assets:receivable  ; Accounting type is inferred from english names,
-account passifs            ; or declared with a "type" tag, type:L
-account expenses           ; type:X
-                           ; A follow-on comment line, indented.
-account expenses:rent      ; Expense and revenue categories are also accounts.
-                           ; Subaccounts inherit their parent's type.
-
-commodity $0.00         ; Declare valid commodities and their display styles.
-commodity 1.000,00 EUR
-
-decimal-mark .          ; The decimal mark used in this file (if ambiguous).
-
-payee Whole Foods       ; Declare a valid payee name.
-
-tag trip                ; Declare a valid tag name.
-
-P 2024-03-01 AAPL $179  ; Declare a market price for AAPL in $ on this date.
-
-include other.journal   ; Include another journal file here.
-
-# Declare a recurring "periodic transaction", for budget/forecast reports
-~ monthly  set budget goals  ; <- Note, 2+ spaces before the description.
-    (expenses:rent)      $1000
-    (expenses:food)       $500
-
-# Declare an auto posting rule, to modify existing transactions in reports
-= revenues:consulting
-    liabilities:tax:2024:us          *0.25  ; Add a tax liability & expense
-    expenses:tax:2024:us            *-0.25  ; for 25% of the revenue.
-
-###############################################################################
-
-# 3. Transactions are what it's all about.
-# They are dated events, usually movements of money between 2 or more accounts.
-# They begin with a numeric date.
-# Here is their basic shape:
-#
-# DATE DESCRIPTION    ; The transaction's date and optional description.
-#   ACCOUNT1  AMOUNT  ; A posting of an amount to/from this account, indented.
-#   ACCOUNT2  AMOUNT  ; A second posting, balancing the first.
-#   ...               ; More if needed. Amounts must sum to zero.
-#                     ; Note, 2+ spaces between account names and amounts.
-
-2024-01-01 opening balances         ; At the start, declare pre-existing balances this way.
-    assets:savings          $10000  ; Account names can be anything. lower case is easy to type.
-    assets:checking          $1000  ; assets, liabilities, equity, revenues, expenses are common.
-    liabilities:credit card  $-500  ; liabilities, equity, revenues balances are usually negative.
-    equity:start                    ; One amount can be left blank. $-10500 is inferred here.
-                                    ; Some of these accounts we didn't declare above,
-                                    ; so -s/--strict would complain.
-
-2024-01-03 ! (12345) pay rent
-    ; Additional transaction comment lines, indented.
-    ; There can be a ! or * after the date meaning "pending" or "cleared".
-    ; There can be a parenthesised (code) after the date/status.
-                                    ; Amounts' sign shows direction of flow.
-    assets:checking          $-500  ; Minus means removed from this account (credit).
-    expenses:rent             $500  ; Plus means added to this account (debit).
-
-; Keeping transactions in date order is optional (but helps error checking).
-
-2024-01-02 Gringott's Bank | withdrawal  ; Description can be PAYEE | NOTE
-    assets:bank:gold       -10 gold
-    assets:pouch            10 gold
-
-2024-01-02 shopping
-    expenses:clothing        1 gold
-    expenses:wands           5 gold
-    assets:pouch            -6 gold
-
-2024-01-02 receive gift
-    revenues:gifts          -3 "Chocolate Frogs"  ; Complex commodity symbols
-    assets:pouch             3 "Chocolate Frogs"  ; must be in double quotes.
-
-2024-01-15 buy some shares, in two lots                 ; Cost can be noted.
-    assets:investments:2024-01-15     2.0 AAAA @ $1.50  ; @  means per-unit cost
-    assets:investments:2024-01-15-02  3.0 AAAA @@ $4    ; @@ means total cost
-                      ; ^ Per-lot subaccounts are sometimes useful.
-    assets:checking                 $-7
-
-2024-01-15 assert some account balances on this date
-    ; Balances can be asserted in any transaction, with =, for extra error checking.
-    ; Assertion txns like this one can be made with hledger close --assert --show-costs
-    ;
-    assets:savings                    $0                   = $10000
-    assets:checking                   $0                   =   $493
-    assets:bank:gold                   0 gold              =    -10 gold
-    assets:pouch                       0 gold              =      4 gold
-    assets:pouch                       0 "Chocolate Frogs" =      3 "Chocolate Frogs"
-    assets:investments:2024-01-15      0.0 AAAA            =      2.0 AAAA @  $1.50
-    assets:investments:2024-01-15-02   0.0 AAAA            =      3.0 AAAA @@ $4
-    liabilities:credit card           $0                   =  $-500
-
-2024-02-01 note some event, or a transaction not yet fully entered, on this date
-    ; Postings are not required.
-
-; Some other date formats are allowed (but, consistent YYYY-MM-DD is useful).
-2024.01.01
-2024/1/1
-
-
-File: hledger.info,  Node: Comments,  Next: Transactions,  Prev: Journal cheatsheet,  Up: Journal
-
-8.2 Comments
-============
-
-Lines in the journal will be ignored if they begin with a hash ('#') or
-a semicolon (';').  (See also Other syntax.)  hledger will also ignore
-regions beginning with a 'comment' line and ending with an 'end comment'
-line (or file end).  Here's a suggestion for choosing between them:
-
-   * '#' for top-level notes
-   * ';' for commenting out things temporarily
-   * 'comment' for quickly commenting large regions (remember it's
-     there, or you might get confused)
-
-   Eg:
-
-# a comment line
-; another commentline
-comment
-A multi-line comment block,
-continuing until "end comment" directive
-or the end of the current file.
-end comment
-
-   Some hledger entries can have same-line comments attached to them,
-from ; (semicolon) to end of line.  See Transaction comments, Posting
-comments, and Account comments below.
-
-
-File: hledger.info,  Node: Transactions,  Next: Dates,  Prev: Comments,  Up: Journal
-
-8.3 Transactions
-================
-
-Transactions are the main unit of information in a journal file.  They
-represent events, typically a movement of some quantity of commodities
-between two or more named accounts.
-
-   Each transaction is recorded as a journal entry, beginning with a
-simple date in column 0.  This can be followed by any of the following
-optional fields, separated by spaces:
-
-   * a status character (empty, '!', or '*')
-   * a code (any short number or text, enclosed in parentheses)
-   * a description (any remaining text until end of line or a semicolon)
-   * a comment (any remaining text following a semicolon until end of
-     line, and any following indented lines beginning with a semicolon)
-   * 0 or more indented _posting_ lines, describing what was transferred
-     and the accounts involved (indented comment lines are also allowed,
-     but not blank lines or non-indented lines).
-
-   Here's a simple journal file containing one transaction:
-
-2008/01/01 income
-  assets:bank:checking   $1
-  income:salary         $-1
-
-
-File: hledger.info,  Node: Dates,  Next: Status,  Prev: Transactions,  Up: Journal
-
-8.4 Dates
-=========
-
-* Menu:
-
-* Simple dates::
-* Posting dates::
-
-
-File: hledger.info,  Node: Simple dates,  Next: Posting dates,  Up: Dates
-
-8.4.1 Simple dates
-------------------
-
-Dates in the journal file use _simple dates_ format: 'YYYY-MM-DD' or
-'YYYY/MM/DD' or 'YYYY.MM.DD', with leading zeros optional.  The year may
-be omitted, in which case it will be inferred from the context: the
-current transaction, the default year set with a 'Y' directive, or the
-current date when the command is run.  Some examples: '2010-01-31',
-'2010/01/31', '2010.1.31', '1/31'.
-
-   (The UI also accepts simple dates, as well as the more flexible smart
-dates documented in the hledger manual.)
-
-
-File: hledger.info,  Node: Posting dates,  Prev: Simple dates,  Up: Dates
-
-8.4.2 Posting dates
--------------------
-
-You can give individual postings a different date from their parent
-transaction, by adding a posting comment containing a tag (see below)
-like 'date:DATE'.  This is probably the best way to control posting
-dates precisely.  Eg in this example the expense should appear in May
-reports, and the deduction from checking should be reported on 6/1 for
-easy bank reconciliation:
-
-2015/5/30
-    expenses:food     $10  ; food purchased on saturday 5/30
-    assets:checking        ; bank cleared it on monday, date:6/1
-
-$ hledger -f t.j register food
-2015-05-30                      expenses:food                  $10           $10
-
-$ hledger -f t.j register checking
-2015-06-01                      assets:checking               $-10          $-10
-
-   DATE should be a simple date; if the year is not specified it will
-use the year of the transaction's date.
-The 'date:' tag must have a valid simple date value if it is present, eg
-a 'date:' tag with no value is not allowed.
-
-
-File: hledger.info,  Node: Status,  Next: Code,  Prev: Dates,  Up: Journal
-
-8.5 Status
-==========
-
-Transactions (or individual postings within a transaction) can have a
-status mark, which is a single character before the transaction
-description (or posting account name), separated from it by a space,
-indicating one of three statuses:
-
-mark  status
- 
------------------
-      unmarked
-'!'   pending
-'*'   cleared
-
-   When reporting, you can filter by status with the '-U/--unmarked',
-'-P/--pending', and '-C/--cleared' flags (and you can combine these, eg
-'-UP' to match all except cleared things).  Or you can use the
-'status:', 'status:!', and 'status:*' queries, or the U, P, C keys in
-hledger-ui.
-
-   (Note: in Ledger the "unmarked" state is called "uncleared"; in
-hledger we renamed it to "unmarked" for semantic clarity.)
-
-   Status marks are optional, but can be helpful eg for reconciling with
-real-world accounts.  Some editor modes provide highlighting and
-shortcuts for working with status.  Eg in Emacs ledger-mode, you can
-toggle transaction status with C-c C-e, or posting status with C-c C-c.
-
-   What "uncleared", "pending", and "cleared" actually mean is up to
-you.  Here's one suggestion:
-
-status     meaning
---------------------------------------------------------------------------
-uncleared  recorded but not yet reconciled; needs review
-pending    tentatively reconciled (if needed, eg during a big
-           reconciliation)
-cleared    complete, reconciled as far as possible, and considered
-           correct
-
-   With this scheme, you would use '-PC' to see the current balance at
-your bank, '-U' to see things which will probably hit your bank soon
-(like uncashed checks), and no flags to see the most up-to-date state of
-your finances.
-
-
-File: hledger.info,  Node: Code,  Next: Description,  Prev: Status,  Up: Journal
-
-8.6 Code
-========
-
-After the status mark, but before the description, you can optionally
-write a transaction "code", enclosed in parentheses.  This is a good
-place to record a check number, or some other important transaction id
-or reference number.
-
-
-File: hledger.info,  Node: Description,  Next: Transaction comments,  Prev: Code,  Up: Journal
-
-8.7 Description
-===============
-
-After the date, status mark and/or code fields, the rest of the line (or
-until a comment is begun with ';') is the transaction's description.
-Here you can describe the transaction (called the "narration" in
-traditional bookkeeping), or you can record a payee/payer name, or you
-can leave it empty.
-
-   Transaction descriptions show up in print output and in register
-reports, and can be listed with the descriptions command.
-
-   You can query by description with 'desc:DESCREGEX', or pivot on
-description with '--pivot desc'.
-
-* Menu:
-
-* Payee and note::
-
-
-File: hledger.info,  Node: Payee and note,  Up: Description
-
-8.7.1 Payee and note
---------------------
-
-Sometimes people want a dedicated payee/payer field that can be queried
-and checked more strictly.  If you want that, you can write a '|' (pipe)
-character in the description.  This divides it into a "payee" field on
-the left, and a "note" field on the right.  (Either can be empty.)
-
-   You can query these with 'payee:PAYEEREGEX' and 'note:NOTEREGEX',
-list their values with the payees and notes commands, or pivot on
-'payee' or 'note'.
-
-   Note: in transactions with no '|' character, description, payee, and
-note all have the same value.  Once a '|' is added, they become
-distinct.  (If you'd like to change this behaviour, please propose it on
-the mail list.)
-
-   If you want more strict error checking, you can declare the valid
-payee names with payee directives, and then enforce these with hledger
-check payees.  (Note: because of the above, for this you'll need to
-ensure every transaction description contains a '|' and therefore a
-checkable payee name, even if it's empty.)
-
-
-File: hledger.info,  Node: Transaction comments,  Next: Postings,  Prev: Description,  Up: Journal
-
-8.8 Transaction comments
-========================
-
-Text following ';', after a transaction description, and/or on indented
-lines immediately below it, form comments for that transaction.  They
-are reproduced by 'print' but otherwise ignored, except they may contain
-tags, which are not ignored.
-
-2012-01-01 something  ; a transaction comment
-    ; a second line of transaction comment
-    expenses   1
-    assets
-
-
-File: hledger.info,  Node: Postings,  Next: Account names,  Prev: Transaction comments,  Up: Journal
-
-8.9 Postings
-============
-
-A posting is an addition of some amount to, or removal of some amount
-from, an account.  Each posting line begins with at least one space or
-tab (2 or 4 spaces is common), followed by:
-
-   * (optional) a status character (empty, '!', or '*'), followed by a
-     space
-   * (required) an account name (any text, optionally containing *single
-     spaces*, until end of line or a double space)
-   * (optional) *two or more spaces* (or tabs) followed by an amount.
-
-   If the amount is positive, it is being added to the account; if
-negative, it is being removed from the account.
-
-   The posting amounts in a transaction must sum up to zero, indicating
-that the inflows and outflows are equal.  We call this a balanced
-transaction.  (You can read more about the nitty-gritty details of "sum
-up to zero" in Transaction balancing below.)
-
-   As a convenience, you can optionally leave one amount blank; hledger
-will infer what it should be so as to balance the transaction.
-
-* Menu:
-
-* Debits and credits::
-* The two space delimiter::
-
-
-File: hledger.info,  Node: Debits and credits,  Next: The two space delimiter,  Up: Postings
-
-8.9.1 Debits and credits
-------------------------
-
-The traditional accounting concepts of debit and credit of course exist
-in hledger, but we represent them with numeric sign, as described above.
-Positive and negative posting amounts represent debits and credits
-respectively.
-
-   You don't need to remember that, but if you would like to - eg for
-helping newcomers or for talking with your accountant - here's a handy
-mnemonic:
-
-   _'debit / plus / left / short words'_
-_'credit / minus / right / longer words'_
-
-
-File: hledger.info,  Node: The two space delimiter,  Prev: Debits and credits,  Up: Postings
-
-8.9.2 The two space delimiter
------------------------------
-
-Be sure to notice the unusual separator between the account name and the
-following amount.  Because hledger allows account names with spaces in
-them, you must separate the account name and amount (if any) by *two or
-more spaces* (or tabs).  It's easy to forget at first.  If you ever see
-the amount being treated as part of the account name, you'll know you
-probably need to add another space between them.
-
-
-File: hledger.info,  Node: Account names,  Next: Amounts,  Prev: Postings,  Up: Journal
-
-8.10 Account names
-==================
-
-Accounts are the main way of categorising things in hledger.  As in
-Double Entry Bookkeeping, they can represent real world accounts (such
-as a bank account), or more abstract categories such as "money borrowed
-from Frank" or "money spent on electricity".
-
-   You can use any account names you like, but we usually start with the
-traditional accounting categories, which in english are 'assets',
-'liabilities', 'equity', 'revenues', 'expenses'.  (You might see these
-referred to as A, L, E, R, X for short.)
-
-   For more precise reporting, we usually divide the top level accounts
-into more detailed subaccounts, by writing a full colon between account
-name parts.  For example, from the account names 'assets:bank:checking'
-and 'expenses:food', hledger will infer this hierarchy of five accounts:
-
-assets
-assets:bank
-assets:bank:checking
-expenses
-expenses:food
-
-   Shown as an outline, the hierarchical tree structure is more clear:
-
-assets
- bank
-  checking
-expenses
- food
-
-   hledger reports can summarise the account tree to any depth, so you
-can go as deep as you like with subcategories, but keeping your account
-names relatively simple may be best when starting out.
-
-   Account names may be capitalised or not; they may contain letters,
-numbers, symbols, or single spaces.  Note, when an account name and an
-amount are written on the same line, they must be separated by *two or
-more spaces* (or tabs).
-
-   Parentheses or brackets enclosing the full account name indicate
-virtual postings, described below.  Parentheses or brackets internal to
-the account name have no special meaning.
-
-   Account names can be altered temporarily or permanently by account
-aliases.
-
-
-File: hledger.info,  Node: Amounts,  Next: Balance assertions,  Prev: Account names,  Up: Journal
-
-8.11 Amounts
-============
-
-After the account name, there is usually an amount.  (Remember: between
-account name and amount, there must be two or more spaces.)
-
-   hledger's amount format is flexible, supporting several international
-formats.  Here are some examples.  Amounts have a number (the
-"quantity"):
-
-1
-
-   ..and usually a currency symbol or commodity name (more on this
-below), to the left or right of the quantity, with or without a
-separating space:
-
-$1
-4000 AAPL
-3 "green apples"
-
-   Amounts can be preceded by a minus sign (or a plus sign, though plus
-is the default), The sign can be written before or after a left-side
-commodity symbol:
-
--$1
-$-1
-
-   One or more spaces between the sign and the number are acceptable
-when parsing (but they won't be displayed in output):
-
-+ $1
-$-      1
-
-   Scientific E notation is allowed:
-
-1E-6
-EUR 1E3
-
-* Menu:
-
-* Decimal marks::
-* Digit group marks::
-* Commodity::
-* Costs::
-
-
-File: hledger.info,  Node: Decimal marks,  Next: Digit group marks,  Up: Amounts
-
-8.11.1 Decimal marks
---------------------
-
-A _decimal mark_ can be written as a period or a comma:
-
-1.23
-1,23
-
-   Both of these are common in international number formats, so hledger
-is not biased towards one or the other.  Because hledger also supports
-digit group marks (eg thousands separators), this means that a number
-like '1,000' or '1.000' containing just one period or comma is
-ambiguous.  In such cases, hledger by default assumes it is a decimal
-mark, and will parse both of those as 1.
-
-   To help hledger parse such ambiguous numbers more accurately, if you
-use digit group marks, we recommend declaring the decimal mark
-explicitly.  The best way is to add a 'decimal-mark' directive at the
-top of each data file, like this:
-
-decimal-mark .
-
-   Or you can declare it per commodity with 'commodity' directives,
-described below.
-
-   hledger also accepts numbers like '10.' with no digits after the
-decimal mark (and will sometimes display numbers that way to
-disambiguate them - see Trailing decimal marks).
-
-
-File: hledger.info,  Node: Digit group marks,  Next: Commodity,  Prev: Decimal marks,  Up: Amounts
-
-8.11.2 Digit group marks
-------------------------
-
-In the integer part of the amount quantity (left of the decimal mark),
-groups of digits can optionally be separated by a _digit group mark_ - a
-comma or period (whichever is not used as decimal mark), or a space
-(several Unicode space variants, like no-break space, are also
-accepted).  So these are all valid amounts in a journal file:
-
-     $1,000,000.00
-  EUR 2.000.000,00
-INR 9,99,99,999.00
-      1 000 000.00   ; <- ordinary space  
-      1 000 000.00   ; <- no-break space
-
-
-File: hledger.info,  Node: Commodity,  Next: Costs,  Prev: Digit group marks,  Up: Amounts
-
-8.11.3 Commodity
-----------------
-
-Amounts in hledger have both a "quantity", which is a signed decimal
-number, and a "commodity", which is a currency symbol, stock ticker, or
-any word or phrase describing something you are tracking.
-
-   If the commodity name contains non-letters (spaces, numbers, or
-punctuation), you must always write it inside double quotes ('"green
-apples"', '"ABC123"').
-
-   If you write just a bare number, that too will have a commodity, with
-name '""'; we call that the "no-symbol commodity".
-
-   Actually, hledger combines these single-commodity amounts into more
-powerful multi-commodity amounts, which are what it works with most of
-the time.  A multi-commodity amount could be, eg: '1 USD, 2 EUR, 3.456
-TSLA'.  In practice, you will only see multi-commodity amounts in
-hledger's output; you can't write them directly in the journal file.
-
-   By default, the format of amounts in the journal influences how
-hledger displays them in output.  This is explained in Commodity display
-style below.
-
-
-File: hledger.info,  Node: Costs,  Prev: Commodity,  Up: Amounts
-
-8.11.4 Costs
-------------
-
-After a posting amount, you can note its cost (when buying) or selling
-price (when selling) in another commodity, by writing either '@
-UNITPRICE' or '@@ TOTALPRICE' after it.  This indicates a conversion
-transaction, where one commodity is exchanged for another.
-
-   (You might also see this called "transaction price" in hledger docs,
-discussions, or code; that term was directionally neutral and reminded
-that it is a price specific to a transaction, but we now just call it
-"cost", with the understanding that the transaction could be a purchase
-or a sale.)
-
-   Costs are usually written explicitly with '@' or '@@', but can also
-be inferred automatically for simple multi-commodity transactions.
-Note, if costs are inferred, the order of postings is significant; the
-first posting will have a cost attached, in the commodity of the second.
-
-   As an example, here are several ways to record purchases of a foreign
-currency in hledger, using the cost notation either explicitly or
-implicitly:
-
-  1. Write the price per unit, as '@ UNITPRICE' after the amount:
-
-     2009/1/1
-       assets:euros     €100 @ $1.35  ; one hundred euros purchased at $1.35 each
-       assets:dollars                 ; balancing amount is -$135.00
-
-  2. Write the total price, as '@@ TOTALPRICE' after the amount:
-
-     2009/1/1
-       assets:euros     €100 @@ $135  ; one hundred euros purchased at $135 for the lot
-       assets:dollars
-
-  3. Specify amounts for all postings, using exactly two commodities,
-     and let hledger infer the price that balances the transaction.
-     Note the effect of posting order: the price is added to first
-     posting, making it '€100 @@ $135', as in example 2:
-
-     2009/1/1
-       assets:euros     €100          ; one hundred euros purchased
-       assets:dollars  $-135          ; for $135
-
-   Amounts can be converted to cost at report time using the '-B/--cost'
-flag; this is discussed more in the Cost reporting section.
-
-   Note that the cost normally should be a positive amount, though it's
-not required to be.  This can be a little confusing, see discussion at
--infer-market-prices: market prices from transactions.
-
-
-File: hledger.info,  Node: Balance assertions,  Next: Posting comments,  Prev: Amounts,  Up: Journal
-
-8.12 Balance assertions
-=======================
-
-hledger supports Ledger-style balance assertions in journal files.
-These look like, for example, '= EXPECTEDBALANCE' following a posting's
-amount.  Eg here we assert the expected dollar balance in accounts a and
-b after each posting:
-
-2013/1/1
-  a   $1 =  $1
-  b      = $-1
-
-2013/1/2
-  a   $1 =  $2
-  b  $-1 = $-2
-
-   After reading a journal file, hledger will check all balance
-assertions and report an error if any of them fail.  Balance assertions
-can protect you from, eg, inadvertently disrupting reconciled balances
-while cleaning up old entries.  You can disable them temporarily with
-the '-I/--ignore-assertions' flag, which can be useful for
-troubleshooting or for reading Ledger files.  (Note: this flag currently
-does not disable balance assignments, described below).
-
-* Menu:
-
-* Assertions and ordering::
-* Assertions and multiple included files::
-* Assertions and multiple -f files::
-* Assertions and costs::
-* Assertions and commodities::
-* Assertions and subaccounts::
-* Assertions and status::
-* Assertions and virtual postings::
-* Assertions and auto postings::
-* Assertions and precision::
-
-
-File: hledger.info,  Node: Assertions and ordering,  Next: Assertions and multiple included files,  Up: Balance assertions
-
-8.12.1 Assertions and ordering
-------------------------------
-
-hledger calculates and checks an account's balance assertions in date
-order (and when there are multiple assertions on the same day, in parse
-order).  Note this is different from Ledger, which checks assertions
-always in parse order, ignoring dates.
-
-   This means in hledger you can freely reorder transactions, postings,
-or files, and balance assertions will usually keep working.  The
-exception is when you reorder multiple postings on the same day, to the
-same account, which have balance assertions; those will likely need
-updating.
-
-
-File: hledger.info,  Node: Assertions and multiple included files,  Next: Assertions and multiple -f files,  Prev: Assertions and ordering,  Up: Balance assertions
-
-8.12.2 Assertions and multiple included files
----------------------------------------------
-
-Multiple files included with the 'include' directive are processed as if
-concatenated into one file, preserving their order and the posting order
-within each file.  It means that balance assertions in later files will
-see balance from earlier files.
-
-   And if you have multiple postings to an account on the same day,
-split across multiple files, and you want to assert the account's
-balance on that day, you'll need to put the assertion in the right file
-- the last one in the sequence, probably.
-
-
-File: hledger.info,  Node: Assertions and multiple -f files,  Next: Assertions and costs,  Prev: Assertions and multiple included files,  Up: Balance assertions
-
-8.12.3 Assertions and multiple -f files
----------------------------------------
-
-Unlike 'include', when multiple files are specified on the command line
-with multiple '-f/--file' options, balance assertions will not see
-balance from earlier files.  This can be useful when you do not want
-problems in earlier files to disrupt valid assertions in later files.
-
-   If you do want assertions to see balance from earlier files, use
-'include', or concatenate the files temporarily.
-
-
-File: hledger.info,  Node: Assertions and costs,  Next: Assertions and commodities,  Prev: Assertions and multiple -f files,  Up: Balance assertions
-
-8.12.4 Assertions and costs
----------------------------
-
-Balance assertions ignore costs, and should normally be written without
-one:
-
-2019/1/1
-  (a)     $1 @ €1 = $1
-
-   We do allow costs to be written in balance assertion amounts,
-however, and print shows them, but they don't affect whether the
-assertion passes or fails.  This is for backward compatibility
-(hledger's close command used to generate balance assertions with
-costs), and because balance _assignments_ do use costs (see below).
-
-
-File: hledger.info,  Node: Assertions and commodities,  Next: Assertions and subaccounts,  Prev: Assertions and costs,  Up: Balance assertions
-
-8.12.5 Assertions and commodities
----------------------------------
-
-The balance assertions described so far are "*single commodity balance
-assertions*": they assert and check the balance in one commodity,
-ignoring any others that may be present.  This is how balance assertions
-work in Ledger also.
-
-   If an account contains multiple commodities, you can assert their
-balances by writing multiple postings with balance assertions, one for
-each commodity:
-
-2013/1/1
-  usd   $-1
-  eur   €-1
-  both
-
-2013/1/2
-  both    0 = $1
-  both    0 = €1
-
-   In hledger you can make a stronger "*sole commodity balance
-assertion*" by writing two equals signs ('== EXPECTEDBALANCE').  This
-also asserts that there are no other commodities in the account besides
-the asserted one (or at least, that their current balance is zero):
-
-2013/1/1
-  usd   $-1  == $-1  ; these sole commodity assertions succeed
-  eur   €-1  == €-1
-  both      ;==  $1  ; this one would fail because 'both' contains $ and €
-
-   It's less easy to make a "*sole commodities balance assertion*" (note
-the plural) - ie, asserting that an account contains two or more
-specified commodities and no others.  It can be done by
-
-  1. isolating each commodity in a subaccount, and asserting those
-  2. and also asserting there are no commodities in the parent account
-     itself:
-
-2013/1/1
-  usd       $-1
-  eur       €-1
-  both        0 == 0   ; nothing up my sleeve
-  both:usd   $1 == $1  ; a dollar here
-  both:eur   €1 == €1  ; a euro there
-
-
-File: hledger.info,  Node: Assertions and subaccounts,  Next: Assertions and status,  Prev: Assertions and commodities,  Up: Balance assertions
-
-8.12.6 Assertions and subaccounts
----------------------------------
-
-All of the balance assertions above (both '=' and '==') are
-"*subaccount-exclusive balance assertions*"; they ignore any balances
-that exist in deeper subaccounts.
-
-   In hledger you can make "*subaccount-inclusive balance assertions*"
-by adding a star after the equals ('=*' or '==*'):
-
-2019/1/1
-  equity:start
-  assets:checking  $10
-  assets:savings   $10
-  assets            $0 ==* $20  ; assets + subaccounts contains $20 and nothing else
-
-
-File: hledger.info,  Node: Assertions and status,  Next: Assertions and virtual postings,  Prev: Assertions and subaccounts,  Up: Balance assertions
-
-8.12.7 Assertions and status
-----------------------------
-
-Balance assertions always consider postings of all statuses (unmarked,
-pending, or cleared); they are not affected by the '-U'/'--unmarked' /
-'-P'/'--pending' / '-C'/'--cleared' flags or the 'status:' query.
-
-
-File: hledger.info,  Node: Assertions and virtual postings,  Next: Assertions and auto postings,  Prev: Assertions and status,  Up: Balance assertions
-
-8.12.8 Assertions and virtual postings
---------------------------------------
-
-Balance assertions always consider both real and virtual postings; they
-are not affected by the '--real/-R' flag or 'real:' query.
-
-
-File: hledger.info,  Node: Assertions and auto postings,  Next: Assertions and precision,  Prev: Assertions and virtual postings,  Up: Balance assertions
-
-8.12.9 Assertions and auto postings
------------------------------------
-
-Balance assertions _are_ affected by the '--auto' flag, which generates
-auto postings, which can alter account balances.  Because auto postings
-are optional in hledger, accounts affected by them effectively have two
-balances.  But balance assertions can only test one or the other of
-these.  So to avoid making fragile assertions, either:
-
-   * assert the balance calculated with '--auto', and always use
-     '--auto' with that file
-   * or assert the balance calculated without '--auto', and never use
-     '--auto' with that file
-   * or avoid balance assertions on accounts affected by auto postings
-     (or avoid auto postings entirely).
-
-
-File: hledger.info,  Node: Assertions and precision,  Prev: Assertions and auto postings,  Up: Balance assertions
-
-8.12.10 Assertions and precision
---------------------------------
-
-Balance assertions compare the exactly calculated amounts, which are not
-always what is shown by reports.  Eg a commodity directive may limit the
-display precision, but this will not affect balance assertions.  Balance
-assertion failure messages show exact amounts.
-
-
-File: hledger.info,  Node: Posting comments,  Next: Transaction balancing,  Prev: Balance assertions,  Up: Journal
-
-8.13 Posting comments
-=====================
-
-Text following ';', at the end of a posting line, and/or on indented
-lines immediately below it, form comments for that posting.  They are
-reproduced by 'print' but otherwise ignored, except they may contain
-tags, which are not ignored.
-
-2012-01-01
-    expenses   1  ; a comment for posting 1
-    assets
-    ; a comment for posting 2
-    ; a second comment line for posting 2
-
-
-File: hledger.info,  Node: Transaction balancing,  Next: Tags,  Prev: Posting comments,  Up: Journal
-
-8.14 Transaction balancing
-==========================
-
-How exactly does hledger decide when a transaction is balanced ?  The
-general goal is that if you look at the journal entry and calculate the
-amounts' sum perfectly with pencil and paper, hledger should agree with
-you.
-
-   Real world transactions, especially for investments or
-cryptocurrencies, often involve imprecise costs, complex decimals,
-and/or infinitely-recurring decimals, which are difficult or
-inconvenient to handle on a computer.  So to be a practical accounting
-system, hledger allows some imprecision when checking transaction
-balancedness.  The question is, how much imprecision should be allowed ?
-
-   hledger currently decides it based on the commodity display styles:
-if the postings' sum would appear to be zero when displayed with the
-standard display precisions, the transaction is considered balanced.
-
-   Or equivalently: if the journal entry is displayed with amounts
-rounded to the standard display precisions (with 'hledger print
---round=hard'), and a human with pencil and paper would agree that those
-displayed amounts add up to zero, the transaction is considered
-balanced.
-
-   This has some advantages: it is fairly intuitive, general not
-hard-coded, yet configurable when needed.  On the downside it means that
-transaction balancedness is related to commodity display precisions, so
-eg when using '-c/--commodity-style' to display things with more than
-usual precision, you might need to fix some of your journal entries (ie,
-add decimal digits to make them balance more precisely).
-
-   Other PTA tools (Ledger, Beancount..)  have their own ways of doing
-it.  Possible improvements are discussed at #1964.
-
-   Note: if you have multiple journal files, and are relying on
-commodity directives to make imprecise journal entries balance, the
-directives' placement might be important - see 'commodity' directive.
-
-
-File: hledger.info,  Node: Tags,  Next: Directives,  Prev: Transaction balancing,  Up: Journal
-
-8.15 Tags
-=========
-
-Tags are a way to add extra labels or data fields to transactions,
-postings, or accounts.  They are usually a word or hyphenated word,
-immediately followed by a full colon, written within the comment of a
-transaction, a posting, or an 'account' directive.  (Yes, storing data
-in comments is slightly weird!)
-
-   You can write each tag on its own comment line, or multiple tags on
-one line, separated by commas.  Tags can also have a value, which is any
-text after the colon until the next comma or end of line, excluding
-surrounding whitespace.  (hledger tag values can't contain commas.)  If
-the same tag name appears multiple times in a comment, each name:value
-pair is preserved.
-
-   An example: in this journal there are six tags, one of them with a
-value:
-
-account assets:checking         ; accounttag:
-account expenses:food
-
-2017/1/16 bought groceries      ; transactiontag:
-    ; transactiontag2:
-    assets:checking        $-1
-     ; posting-tag-1:, (belongs to the posting above)
-    expenses:food           $1  ; posting-tag-2:, posting-tag-3: with a value
-
-* Menu:
-
-* Querying with tags::
-* Displaying tags::
-* When to use tags ?::
-* Tag names::
-* Special tags::
-
-
-File: hledger.info,  Node: Querying with tags,  Next: Displaying tags,  Up: Tags
-
-8.15.1 Querying with tags
--------------------------
-
-Tags are most often used to select a subset of data; you can match
-tagged things by tag name and or tag value with a 'tag:' query.  (See
-queries below.)
-
-   When querying for tag names or values, note that postings inherit
-tags from their transaction and from their account, and transactions
-acquire tags from their postings.  So in the example above, - the
-assets:checking posting effectively has four tags (one of its own, one
-from the account, two from the transaction) - the expenses:food posting
-effectively has four tags (two of its own, two from the transaction) -
-the transaction effectively has all six tags (two of its own, and two
-from each posting)
-
-
-File: hledger.info,  Node: Displaying tags,  Next: When to use tags ?,  Prev: Querying with tags,  Up: Tags
-
-8.15.2 Displaying tags
-----------------------
-
-You can use the 'tags' command to list tag names or values.
-
-   The 'print' command also shows tags.
-
-   You can use -pivot to display tag values in other reports, in various
-ways (eg appended to account names, like pseudo subaccounts).
-
-
-File: hledger.info,  Node: When to use tags ?,  Next: Tag names,  Prev: Displaying tags,  Up: Tags
-
-8.15.3 When to use tags ?
--------------------------
-
-Tags provide more dimensions of categorisation, complementing accounts
-and transaction descriptions.  When to use each of these is somewhat a
-matter of taste.  Accounts have the most built-in support, and regex
-queries on descriptions are also quite powerful.  So you may not need
-tags at all.  But if you want to track multiple cross-cutting
-categories, they can be a good fit.  For example, you could tag
-trip-related transactions with 'trip: YEAR:PLACE', without disturbing
-your usual account categories.
-
-
-File: hledger.info,  Node: Tag names,  Next: Special tags,  Prev: When to use tags ?,  Up: Tags
-
-8.15.4 Tag names
-----------------
-
-What is allowed in a tag name ?  Currently, most non-whitespace
-characters.  Eg '😀:' is a valid tag.
-
-   For extra error checking, you can declare valid tag names with the
-'tag' directive, and then enforce these with the 'check' command.
-
-   But note that tags are detected quite loosely at present, sometimes
-where you didn't intend them.  Eg '; see https://foo.com' contains a
-'https' tag with value '//foo.com'.
-
-
-File: hledger.info,  Node: Special tags,  Prev: Tag names,  Up: Tags
-
-8.15.5 Special tags
--------------------
-
-Some tag names have special significance to hledger.  They are explained
-elsewhere, but here's a quick reference:
-
- type                   -- declares an account's type
- date                   -- overrides a posting's date
- date2                  -- overrides a posting's secondary date
- assert                 -- appears on txns generated by close --assert
- retain                 -- appears on txns generated by close --retain
- start                  -- appears on txns generated by close --migrate/--close/--open/--assign
- t                      -- appears on postings generated from timedot letters
-
- generated-transaction  -- appears on txns generated by a periodic rule
- modified-transaction   -- appears on txns which have had auto postings added
- generated-posting      -- appears on generated postings
- cost-posting           -- appears on postings which have (or could have) a cost,
-                           and which have equivalent conversion postings in the transaction
- conversion-posting     -- appears on postings which are to a V/Conversion account
-                           and which have an equivalent cost posting in the transaction
-
-   The second group above (generated-transaction, etc.)  are normally
-hidden, with a '_' prefix added.  This means 'print' doesn't show them
-by default; but you can still use them in queries.  You can add the
-'--verbose-tags' flag to make them visible, which can be useful for
-troubleshooting.
-
-
-File: hledger.info,  Node: Directives,  Next: account directive,  Prev: Tags,  Up: Journal
-
-8.16 Directives
-===============
-
-Besides transactions, there is something else you can put in a 'journal'
-file: directives.  These are declarations, beginning with a keyword,
-that modify hledger's behaviour.  Some directives can have more specific
-subdirectives, indented below them.  hledger's directives are similar to
-Ledger's in many cases, but there are also many differences.  Directives
-are not required, but can be useful.  Here are the main directives:
-
-purpose                                   directive
---------------------------------------------------------------------------
-*READING DATA:*
-Rewrite account names                     'alias'
-Comment out sections of the file          'comment'
-Declare file's decimal mark, to help      'decimal-mark'
-parse amounts accurately
-Include other data files                  'include'
-*GENERATING DATA:*
-Generate recurring transactions or        '~'
-budget goals
-Generate extra postings on existing       '='
-transactions
-*CHECKING FOR ERRORS:*
-Define valid entities to provide more     'account', 'commodity',
-error checking                            'payee', 'tag'
-*REPORTING:*
-Declare accounts' type and display        'account'
-order
-Declare commodity display styles          'commodity'
-Declare market prices                     'P'
-
-* Menu:
-
-* Directives and multiple files::
-* Directive effects::
-
-
-File: hledger.info,  Node: Directives and multiple files,  Next: Directive effects,  Up: Directives
-
-8.16.1 Directives and multiple files
-------------------------------------
-
-Directives vary in their scope, ie which journal entries and which input
-files they affect.  Most often, a directive will affect the following
-entries and included files if any, until the end of the current file -
-and no further.  You might find this inconvenient!  For example, 'alias'
-directives do not affect parent or sibling files.  But there are usually
-workarounds; for example, put 'alias' directives in your top-most file,
-before including other files.
-
-   The restriction, though it may be annoying at first, is in a good
-cause; it allows reports to be stable and deterministic, independent of
-the order of input.  Without it, reports could show different numbers
-depending on the order of -f options, or the positions of include
-directives in your files.
-
-
-File: hledger.info,  Node: Directive effects,  Prev: Directives and multiple files,  Up: Directives
-
-8.16.2 Directive effects
-------------------------
-
-Here are all hledger's directives, with their effects and scope
-summarised - nine main directives, plus four others which we consider
-non-essential:
-
-directivewhat it does                                                   ends
-                                                                        at
-                                                                        file
-                                                                        end?
----------------------------------------------------------------------------
-*'account'*Declares an account, for checking all entries in all files; andN
-     its display order and type.  Subdirectives: any text, ignored.
-*'alias'*Rewrites account names, in following entries until end of      Y
-     current file or 'end aliases'.  Command line equivalent:
-     '--alias'
-*'comment'*Ignores part of the journal file, until end of current file orY
-     'end comment'.
-*'commodity'*Declares up to four things: 1.  a commodity symbol, for checkingN,N,Y,Y
-     all amounts in all files 2.  the display style for all amounts
-     of this commodity 3.  the decimal mark for parsing amounts of
-     this commodity, in the rest of this file and its children, if
-     there is no 'decimal-mark' directive 4.  the precision to use
-     for balanced-transaction checking in this commodity, in this
-     file and its children.  Takes precedence over 'D'.
-     Subdirectives: 'format' (ignored).  Command line equivalent:
-     '-c/--commodity-style'
-*'decimal-mark'*Declares the decimal mark, for parsing amounts of all   Y
-     commodities in following entries until next 'decimal-mark' or
-     end of current file.  Included files can override.  Takes
-     precedence over 'commodity' and 'D'.
-*'include'*Includes entries and directives from another file, as if theyN
-     were written inline.  Command line alternative: multiple
-     '-f/--file'
-*'payee'*Declares a payee name, for checking all entries in all files.  N
-*'P'*Declares the market price of a commodity on some date, for value   N
-     reports.
-*'~'*Declares a periodic transaction rule that generates future         N
-(tilde)transactions with '--forecast' and budget goals with 'balance
-     --budget'.
-Other
-syntax:
-*'applyPrepends a common parent account to all account names, in        Y
-account'*following entries until end of current file or 'end apply
-     account'.
-*'D'*Sets a default commodity to use for no-symbol amounts;and, if      Y,Y,N,N
-     there is no 'commodity' directive for this commodity: its
-     decimal mark, balancing precision, and display style, as above.
-*'Y'*Sets a default year to use for any yearless dates, in following    Y
-     entries until end of current file.
-*'='*Declares an auto posting rule that generates extra postings on     partly
-(equals)matched transactions with '--auto', in current, parent, and
-     child files (but not sibling files, see #1212).
-*OtherOther directives from Ledger's file format are accepted but
-Ledgerignored.
-directives*
-
-
-File: hledger.info,  Node: account directive,  Next: alias directive,  Prev: Directives,  Up: Journal
-
-8.17 'account' directive
-========================
-
-'account' directives can be used to declare accounts (ie, the places
-that amounts are transferred from and to).  Though not required, these
-declarations can provide several benefits:
-
-   * They can document your intended chart of accounts, providing a
-     reference.
-   * They can store additional account information as comments, or as
-     tags which can be used to filter or pivot reports.
-   * They can restrict which accounts may be posted to by transactions,
-     eg in strict mode, which helps prevent errors.
-   * They influence account display order in reports, allowing
-     non-alphabetic sorting (eg Revenues to appear above Expenses).
-   * They can help hledger know your accounts' types (asset, liability,
-     equity, revenue, expense), enabling reports like balancesheet and
-     incomestatement.
-   * They help with account name completion (in hledger add,
-     hledger-web, hledger-iadd, ledger-mode, etc.)
-
-   They are written as the word 'account' followed by a hledger-style
-account name.  Eg:
-
-account assets:bank:checking
-
-   Ledger-style indented subdirectives are also accepted, but ignored:
-
-account assets:bank:checking
-  format subdirective  ; currently ignored
-
-* Menu:
-
-* Account comments::
-* Account error checking::
-* Account display order::
-* Account types::
-
-
-File: hledger.info,  Node: Account comments,  Next: Account error checking,  Up: account directive
-
-8.17.1 Account comments
------------------------
-
-Text following *two or more spaces* and ';' at the end of an account
-directive line, and/or following ';' on indented lines immediately below
-it, form comments for that account.  They are ignored except they may
-contain tags, which are not ignored.
-
-   The two-space requirement for same-line account comments is because
-';' is allowed in account names.
-
-account assets:bank:checking    ; same-line comment, at least 2 spaces before the semicolon
-  ; next-line comment
-  ; some tags - type:A, acctnum:12345
-
-
-File: hledger.info,  Node: Account error checking,  Next: Account display order,  Prev: Account comments,  Up: account directive
-
-8.17.2 Account error checking
------------------------------
-
-By default, accounts need not be declared; they come into existence when
-a posting references them.  This is convenient, but it means hledger
-can't warn you when you mis-spell an account name in the journal.
-Usually you'll find that error later, as an extra account in balance
-reports, or an incorrect balance when reconciling.
-
-   In strict mode, enabled with the '-s'/'--strict' flag, or when you
-run 'hledger check accounts', hledger will report an error if any
-transaction uses an account name that has not been declared by an
-account directive.  Some notes:
-
-   * The declaration is case-sensitive; transactions must use the
-     correct account name capitalisation.
-   * The account directive's scope is "whole file and below" (see
-     directives).  This means it affects all of the current file, and
-     any files it includes, but not parent or sibling files.  The
-     position of account directives within the file does not matter,
-     though it's usual to put them at the top.
-   * Accounts can only be declared in 'journal' files, but will affect
-     included files of all types.
-   * It's currently not possible to declare "all possible subaccounts"
-     with a wildcard; every account posted to must be declared.
-   * If you use the -infer-equity flag, you will also need declarations
-     for the account names it generates.
-
-
-File: hledger.info,  Node: Account display order,  Next: Account types,  Prev: Account error checking,  Up: account directive
-
-8.17.3 Account display order
-----------------------------
-
-Account directives also cause hledger to display accounts in a
-particular order, not just alphabetically.  Eg, here is a conventional
-ordering for the top-level accounts:
-
-account assets
-account liabilities
-account equity
-account revenues
-account expenses
-
-   Now hledger displays them in that order:
-
-$ hledger accounts
-assets
-liabilities
-equity
-revenues
-expenses
-
-   If there are undeclared accounts, those will be displayed last, in
-alphabetical order.
-
-   Sorting is done within each group of sibling accounts, at each level
-of the account tree.  Eg, a declaration like 'account parent:child'
-influences 'child''s position among its siblings.
-
-   Note, it does not affect 'parent''s position; for that, you need an
-'account parent' declaration.
-
-   Sibling accounts are always displayed together; hledger won't display
-'x:y' in between 'a:b' and 'a:c'.
-
-   An account directive both declares an account as a valid posting
-target, and declares its display order; you can't easily do one without
-the other.
-
-
-File: hledger.info,  Node: Account types,  Prev: Account display order,  Up: account directive
-
-8.17.4 Account types
---------------------
-
-hledger knows that accounts come in several types: assets, liabilities,
-expenses and so on.  This enables easy reports like balancesheet and
-incomestatement, and filtering by account type with the 'type:' query.
-
-   As a convenience, hledger will detect these account types
-automatically if you are using common english-language top-level account
-names (described below).  But it's more robust to declare accounts'
-types explicitly, by adding 'type:' tags to their account directives.
-The tag's value should be one of the five main account types:
-
-   * 'A' or 'Asset' (things you own)
-   * 'L' or 'Liability' (things you owe)
-   * 'E' or 'Equity' (investment/ownership; balanced counterpart of
-     assets & liabilities)
-   * 'R' or 'Revenue' (what you received money from, AKA income;
-     technically part of Equity)
-   * 'X' or 'Expense' (what you spend money on; technically part of
-     Equity)
-
-   or, it can be (these are used less often):
-
-   * 'C' or 'Cash' (a subtype of Asset, indicating liquid assets for the
-     cashflow report)
-   * 'V' or 'Conversion' (a subtype of Equity, for conversions (see Cost
-     reporting).)
-
-   Subaccounts inherit their parent's type, or they can override it.
-Here is a typical set of account type declarations:
-
-account assets             ; type: A
-account liabilities        ; type: L
-account equity             ; type: E
-account revenues           ; type: R
-account expenses           ; type: X
-
-account assets:bank        ; type: C
-account assets:cash        ; type: C
-
-account equity:conversion  ; type: V
-
-   Here are some tips for working with account types.
-
-   * The rules for inferring types from account names are as follows.
-     These are just a convenience that sometimes help new users get
-     going; if they don't work for you, just ignore them and declare
-     your account types.  See also Regular expressions.
-
-     If account's name contains this (CI) regular expression:            | its type is:
-     --------------------------------------------------------------------|-------------
-     ^assets?(:.+)?:(cash|bank|che(ck|que?)(ing)?|savings?|current)(:|$) | Cash
-     ^assets?(:|$)                                                       | Asset
-     ^(debts?|liabilit(y|ies))(:|$)                                      | Liability
-     ^equity:(trad(e|ing)|conversion)s?(:|$)                             | Conversion
-     ^equity(:|$)                                                        | Equity
-     ^(income|revenue)s?(:|$)                                            | Revenue
-     ^expenses?(:|$)                                                     | Expense
-
-   * If you declare any account types, it's a good idea to declare an
-     account for all of the account types, because a mixture of declared
-     and name-inferred types can disrupt certain reports.
-
-   * Certain uses of account aliases can disrupt account types.  See
-     Rewriting accounts > Aliases and account types.
-
-   * As mentioned above, subaccounts will inherit a type from their
-     parent account.  More precisely, an account's type is decided by
-     the first of these that exists:
-
-       1. A 'type:' declaration for this account.
-       2. A 'type:' declaration in the parent accounts above it,
-          preferring the nearest.
-       3. An account type inferred from this account's name.
-       4. An account type inferred from a parent account's name,
-          preferring the nearest parent.
-       5. Otherwise, it will have no type.
-
-   * For troubleshooting, you can list accounts and their types with:
-
-     $ hledger accounts --types [ACCTPAT] [-DEPTH] [type:TYPECODES]
-
-
-File: hledger.info,  Node: alias directive,  Next: commodity directive,  Prev: account directive,  Up: Journal
-
-8.18 'alias' directive
-======================
-
-You can define account alias rules which rewrite your account names, or
-parts of them, before generating reports.  This can be useful for:
-
-   * expanding shorthand account names to their full form, allowing
-     easier data entry and a less verbose journal
-   * adapting old journals to your current chart of accounts
-   * experimenting with new account organisations, like a new hierarchy
-   * combining two accounts into one, eg to see their sum or difference
-     on one line
-   * customising reports
-
-   Account aliases also rewrite account names in account directives.
-They do not affect account names being entered via hledger add or
-hledger-web.
-
-   Account aliases are very powerful.  They are generally easy to use
-correctly, but you can also generate invalid account names with them;
-more on this below.
-
-   See also Rewrite account names.
-
-* Menu:
-
-* Basic aliases::
-* Regex aliases::
-* Combining aliases::
-* Aliases and multiple files::
-* end aliases directive::
-* Aliases can generate bad account names::
-* Aliases and account types::
-
-
-File: hledger.info,  Node: Basic aliases,  Next: Regex aliases,  Up: alias directive
-
-8.18.1 Basic aliases
---------------------
-
-To set an account alias, use the 'alias' directive in your journal file.
-This affects all subsequent journal entries in the current file or its
-included files (but note: not sibling or parent files).  The spaces
-around the = are optional:
-
-alias OLD = NEW
-
-   Or, you can use the '--alias 'OLD=NEW'' option on the command line.
-This affects all entries.  It's useful for trying out aliases
-interactively.
-
-   OLD and NEW are case sensitive full account names.  hledger will
-replace any occurrence of the old account name with the new one.
-Subaccounts are also affected.  Eg:
-
-alias checking = assets:bank:wells fargo:checking
-; rewrites "checking" to "assets:bank:wells fargo:checking", or "checking:a" to "assets:bank:wells fargo:checking:a"
-
-
-File: hledger.info,  Node: Regex aliases,  Next: Combining aliases,  Prev: Basic aliases,  Up: alias directive
-
-8.18.2 Regex aliases
---------------------
-
-There is also a more powerful variant that uses a regular expression,
-indicated by wrapping the pattern in forward slashes.  (This is the only
-place where hledger requires forward slashes around a regular
-expression.)
-
-   Eg:
-
-alias /REGEX/ = REPLACEMENT
-
-   or:
-
-$ hledger --alias '/REGEX/=REPLACEMENT' ...
-
-   Any part of an account name matched by REGEX will be replaced by
-REPLACEMENT. REGEX is case-insensitive as usual.
-
-   If you need to match a forward slash, escape it with a backslash, eg
-'/\/=:'.
-
-   If REGEX contains parenthesised match groups, these can be referenced
-by the usual backslash and number in REPLACEMENT:
-
-alias /^(.+):bank:([^:]+):(.*)/ = \1:\2 \3
-; rewrites "assets:bank:wells fargo:checking" to  "assets:wells fargo checking"
-
-   REPLACEMENT continues to the end of line (or on command line, to end
-of option argument), so it can contain trailing whitespace.
-
-
-File: hledger.info,  Node: Combining aliases,  Next: Aliases and multiple files,  Prev: Regex aliases,  Up: alias directive
-
-8.18.3 Combining aliases
-------------------------
-
-You can define as many aliases as you like, using journal directives
-and/or command line options.
-
-   Recursive aliases - where an account name is rewritten by one alias,
-then by another alias, and so on - are allowed.  Each alias sees the
-effect of previously applied aliases.
-
-   In such cases it can be important to understand which aliases will be
-applied and in which order.  For (each account name in) each journal
-entry, we apply:
-
-  1. 'alias' directives preceding the journal entry, most recently
-     parsed first (ie, reading upward from the journal entry, bottom to
-     top)
-  2. '--alias' options, in the order they appeared on the command line
-     (left to right).
-
-   In other words, for (an account name in) a given journal entry:
-
-   * the nearest alias declaration before/above the entry is applied
-     first
-   * the next alias before/above that will be be applied next, and so on
-   * aliases defined after/below the entry do not affect it.
-
-   This gives nearby aliases precedence over distant ones, and helps
-provide semantic stability - aliases will keep working the same way
-independent of which files are being read and in which order.
-
-   In case of trouble, adding '--debug=6' to the command line will show
-which aliases are being applied when.
-
-
-File: hledger.info,  Node: Aliases and multiple files,  Next: end aliases directive,  Prev: Combining aliases,  Up: alias directive
-
-8.18.4 Aliases and multiple files
----------------------------------
-
-As explained at Directives and multiple files, 'alias' directives do not
-affect parent or sibling files.  Eg in this command,
-
-hledger -f a.aliases -f b.journal
-
-   account aliases defined in a.aliases will not affect b.journal.
-Including the aliases doesn't work either:
-
-include a.aliases
-
-2023-01-01  ; not affected by a.aliases
-  foo  1
-  bar
-
-   This means that account aliases should usually be declared at the
-start of your top-most file, like this:
-
-alias foo=Foo
-alias bar=Bar
-
-2023-01-01  ; affected by aliases above
-  foo  1
-  bar
-
-include c.journal  ; also affected
-
-
-File: hledger.info,  Node: end aliases directive,  Next: Aliases can generate bad account names,  Prev: Aliases and multiple files,  Up: alias directive
-
-8.18.5 'end aliases' directive
-------------------------------
-
-You can clear (forget) all currently defined aliases (seen in the
-journal so far, or defined on the command line) with this directive:
-
-end aliases
-
-
-File: hledger.info,  Node: Aliases can generate bad account names,  Next: Aliases and account types,  Prev: end aliases directive,  Up: alias directive
-
-8.18.6 Aliases can generate bad account names
----------------------------------------------
-
-Be aware that account aliases can produce malformed account names, which
-could cause confusing reports or invalid 'print' output.  For example,
-you could erase all account names:
-
-2021-01-01
-  a:aa     1
-  b
-
-$ hledger print --alias '/.*/='
-2021-01-01
-                   1
-
-   The above 'print' output is not a valid journal.  Or you could insert
-an illegal double space, causing 'print' output that would give a
-different journal when reparsed:
-
-2021-01-01
-  old    1
-  other
-
-$ hledger print --alias old="new  USD" | hledger -f- print
-2021-01-01
-    new             USD 1
-    other
-
-
-File: hledger.info,  Node: Aliases and account types,  Prev: Aliases can generate bad account names,  Up: alias directive
-
-8.18.7 Aliases and account types
---------------------------------
-
-If an account with a type declaration (see Declaring accounts > Account
-types) is renamed by an alias, normally the account type remains in
-effect.
-
-   However, renaming in a way that reshapes the account tree (eg
-renaming parent accounts but not their children, or vice versa) could
-prevent child accounts from inheriting the account type of their
-parents.
-
-   Secondly, if an account's type is being inferred from its name,
-renaming it by an alias could prevent or alter that.
-
-   If you are using account aliases and the 'type:' query is not
-matching accounts as you expect, try troubleshooting with the accounts
-command, eg something like:
-
-$ hledger accounts --alias assets=bassetts type:a
-
-
-File: hledger.info,  Node: commodity directive,  Next: decimal-mark directive,  Prev: alias directive,  Up: Journal
-
-8.19 'commodity' directive
-==========================
-
-The 'commodity' directive performs several functions:
-
-  1. It declares which commodity symbols may be used in the journal,
-     enabling useful error checking with strict mode or the check
-     command.  See Commodity error checking below.
-
-  2. It declares how all amounts in this commodity should be displayed,
-     eg how many decimals to show.  See Commodity display style above.
-
-  3. (If no 'decimal-mark' directive is in effect:) It sets the decimal
-     mark to expect (period or comma) when parsing amounts in this
-     commodity, in this file and files it includes, from the directive
-     until end of current file.  See Decimal marks above.
-
-  4. It declares the precision with which this commodity's amounts
-     should be compared when checking for balanced transactions,
-     anywhere in this file and files it includes, until end of current
-     file.
-
-   Declaring commodities solves several common parsing/display problems,
-so we recommend it.
-
-   Note that effects 3 and 4 above end at the end of the directive's
-file, and will not affect sibling or parent files.  So if you are
-relying on them (especially 4) and using multiple files, placing your
-commodity directives in a top-level parent file might be important.  Or,
-keep your decimal marks unambiguous and your entries well balanced and
-precise.
-
-   (Related: #793)
-
-* Menu:
-
-* Commodity directive syntax::
-* Commodity error checking::
-
-
-File: hledger.info,  Node: Commodity directive syntax,  Next: Commodity error checking,  Up: commodity directive
-
-8.19.1 Commodity directive syntax
----------------------------------
-
-A commodity directive is normally the word 'commodity' followed by a
-sample amount (and optionally a comment).  Only the amount's symbol and
-format is significant.  Eg:
-
-commodity $1000.00
-commodity 1.000,00 EUR
-commodity 1 000 000.0000   ; the no-symbol commodity
-
-   Commodities do not have tags (tags in the comment will be ignored).
-
-   A commodity directive's sample amount must always include a period or
-comma decimal mark (this rule helps disambiguate decimal marks and digit
-group marks).  If you don't want to show any decimal digits, write the
-decimal mark at the end:
-
-commodity 1000. AAAA       ; show AAAA with no decimals
-
-   Commodity symbols containing spaces, numbers, or punctuation must be
-enclosed in double quotes, as usual:
-
-commodity 1.0000 "AAAA 2023"
-
-   Commodity directives normally include a sample amount, but can
-declare only a symbol (ie, just function 1 above):
-
-commodity $
-commodity INR
-commodity "AAAA 2023"
-commodity ""               ; the no-symbol commodity
-
-   Commodity directives may also be written with an indented 'format'
-subdirective, as in Ledger.  The symbol is repeated and must be the same
-in both places.  Other subdirectives are currently ignored:
-
-; display indian rupees with currency name on the left,
-; thousands, lakhs and crores comma-separated,
-; period as decimal point, and two decimal places.
-commodity INR
-  format INR 1,00,00,000.00
-  an unsupported subdirective  ; ignored by hledger
-
-
-File: hledger.info,  Node: Commodity error checking,  Prev: Commodity directive syntax,  Up: commodity directive
-
-8.19.2 Commodity error checking
--------------------------------
-
-In strict mode ('-s'/'--strict') (or when you run 'hledger check
-commodities'), hledger will report an error if an undeclared commodity
-symbol is used.  (With one exception: zero amounts are always allowed to
-have no commodity symbol.)  It works like account error checking
-(described above).
-
-
-File: hledger.info,  Node: decimal-mark directive,  Next: include directive,  Prev: commodity directive,  Up: Journal
-
-8.20 'decimal-mark' directive
-=============================
-
-You can use a 'decimal-mark' directive - usually one per file, at the
-top of the file - to declare which character represents a decimal mark
-when parsing amounts in this file.  It can look like
-
-decimal-mark .
-
-   or
-
-decimal-mark ,
-
-   This prevents any ambiguity when parsing numbers in the file, so we
-recommend it, especially if the file contains digit group marks (eg
-thousands separators).
-
-
-File: hledger.info,  Node: include directive,  Next: P directive,  Prev: decimal-mark directive,  Up: Journal
-
-8.21 'include' directive
-========================
-
-You can pull in the content of additional files by writing an include
-directive, like this:
-
-include FILEPATH
-
-   Only journal files can include, and only journal, timeclock or
-timedot files can be included (not CSV files, currently).
-
-   If the file path does not begin with a slash, it is relative to the
-current file's folder.
-
-   A tilde means home directory, eg: 'include ~/main.journal'.
-
-   The path may contain glob patterns to match multiple files, eg:
-'include *.journal'.
-
-   There is limited support for recursive wildcards: '**/' (the slash is
-required) matches 0 or more subdirectories.  It's not super convenient
-since you have to avoid include cycles and including directories, but
-this can be done, eg: 'include */**/*.journal'.
-
-   The path may also be prefixed to force a specific file format,
-overriding the file extension (as described in Data formats): 'include
-timedot:~/notes/2023*.md'.
-
-
-File: hledger.info,  Node: P directive,  Next: payee directive,  Prev: include directive,  Up: Journal
-
-8.22 'P' directive
-==================
-
-The 'P' directive declares a market price, which is a conversion rate
-between two commodities on a certain date.  This allows value reports to
-convert amounts of one commodity to their value in another, on or after
-that date.  These prices are often obtained from a stock exchange,
-cryptocurrency exchange, the or foreign exchange market.
-
-   The format is:
-
-P DATE COMMODITY1SYMBOL COMMODITY2AMOUNT
-
-   DATE is a simple date, COMMODITY1SYMBOL is the symbol of the
-commodity being priced, and COMMODITY2AMOUNT is the amount (symbol and
-quantity) of commodity 2 that one unit of commodity 1 is worth on this
-date.  Examples:
-
-# one euro was worth $1.35 from 2009-01-01 onward:
-P 2009-01-01 € $1.35
-
-# and $1.40 from 2010-01-01 onward:
-P 2010-01-01 € $1.40
-
-   The '-V', '-X' and '--value' flags use these market prices to show
-amount values in another commodity.  See Value reporting.
-
-
-File: hledger.info,  Node: payee directive,  Next: tag directive,  Prev: P directive,  Up: Journal
-
-8.23 'payee' directive
-======================
-
-'payee PAYEE NAME'
-
-   This directive can be used to declare a limited set of payees which
-may appear in transaction descriptions.  The "payees" check will report
-an error if any transaction refers to a payee that has not been
-declared.  Eg:
-
-payee Whole Foods    ; a comment
-
-   Payees do not have tags (tags in the comment will be ignored).
-
-   To declare the empty payee name, use '""'.
-
-payee ""
-
-   Ledger-style indented subdirectives, if any, are currently ignored.
-
-
-File: hledger.info,  Node: tag directive,  Next: Periodic transactions,  Prev: payee directive,  Up: Journal
-
-8.24 'tag' directive
-====================
-
-'tag TAGNAME'
-
-   This directive can be used to declare a limited set of tag names
-allowed in tags.  TAGNAME should be a valid tag name (no spaces).  Eg:
-
-tag  item-id
-
-   Any indented subdirectives are currently ignored.
-
-   The "tags" check will report an error if any undeclared tag name is
-used.  It is quite easy to accidentally create a tag through normal use
-of colons in comments; if you want to prevent this, you can declare and
-check your tags .
-
-
-File: hledger.info,  Node: Periodic transactions,  Next: Auto postings,  Prev: tag directive,  Up: Journal
-
-8.25 Periodic transactions
-==========================
-
-The '~' directive declares a "periodic rule" which generates temporary
-extra transactions, usually recurring at some interval, when hledger is
-run with the '--forecast' flag.  These "forecast transactions" are
-useful for forecasting future activity.  They exist only for the
-duration of the report, and only when '--forecast' is used; they are not
-saved in the journal file by hledger.
-
-   Periodic rules also have a second use: with the '--budget' flag they
-set budget goals for budgeting.
-
-   Periodic rules can be a little tricky, so before you use them, read
-this whole section, or at least the following tips:
-
-  1. Two spaces accidentally added or omitted will cause you trouble -
-     read about this below.
-  2. For troubleshooting, show the generated transactions with 'hledger
-     print --forecast tag:generated' or 'hledger register --forecast
-     tag:generated'.
-  3. Forecasted transactions will begin only after the last
-     non-forecasted transaction's date.
-  4. Forecasted transactions will end 6 months from today, by default.
-     See below for the exact start/end rules.
-  5. period expressions can be tricky.  Their documentation needs
-     improvement, but is worth studying.
-  6. Some period expressions with a repeating interval must begin on a
-     natural boundary of that interval.  Eg in 'weekly from DATE', DATE
-     must be a monday.  '~ weekly from 2019/10/1' (a tuesday) will give
-     an error.
-  7. Other period expressions with an interval are automatically
-     expanded to cover a whole number of that interval.  (This is done
-     to improve reports, but it also affects periodic transactions.
-     Yes, it's a bit inconsistent with the above.)  Eg: '~ every 10th
-     day of month from 2023/01', which is equivalent to '~ every 10th
-     day of month from 2023/01/01', will be adjusted to start on
-     2019/12/10.
-
-* Menu:
-
-* Periodic rule syntax::
-* Periodic rules and relative dates::
-* Two spaces between period expression and description!::
-
-
-File: hledger.info,  Node: Periodic rule syntax,  Next: Periodic rules and relative dates,  Up: Periodic transactions
-
-8.25.1 Periodic rule syntax
----------------------------
-
-A periodic transaction rule looks like a normal journal entry, with the
-date replaced by a tilde ('~') followed by a period expression
-(mnemonic: '~' looks like a recurring sine wave.):
-
-# every first of month
-~ monthly
-    expenses:rent          $2000
-    assets:bank:checking
-
-# every 15th of month in 2023's first quarter:
-~ monthly from 2023-04-15 to 2023-06-16
-    expenses:utilities          $400
-    assets:bank:checking
-
-   The period expression is the same syntax used for specifying
-multi-period reports, just interpreted differently; there, it specifies
-report periods; here it specifies recurrence dates (the periods' start
-dates).
-
-
-File: hledger.info,  Node: Periodic rules and relative dates,  Next: Two spaces between period expression and description!,  Prev: Periodic rule syntax,  Up: Periodic transactions
-
-8.25.2 Periodic rules and relative dates
-----------------------------------------
-
-Partial or relative dates (like '12/31', '25', 'tomorrow', 'last week',
-'next quarter') are usually not recommended in periodic rules, since the
-results will change as time passes.  If used, they will be interpreted
-relative to, in order of preference:
-
-  1. the first day of the default year specified by a recent 'Y'
-     directive
-  2. or the date specified with '--today'
-  3. or the date on which you are running the report.
-
-   They will not be affected at all by report period or forecast period
-dates.
-
-
-File: hledger.info,  Node: Two spaces between period expression and description!,  Prev: Periodic rules and relative dates,  Up: Periodic transactions
-
-8.25.3 Two spaces between period expression and description!
-------------------------------------------------------------
-
-If the period expression is followed by a transaction description, these
-must be separated by *two or more spaces*.  This helps hledger know
-where the period expression ends, so that descriptions can not
-accidentally alter their meaning, as in this example:
-
-; 2 or more spaces needed here, so the period is not understood as "every 2 months in 2023"
-;               ||
-;               vv
-~ every 2 months  in 2023, we will review
-    assets:bank:checking   $1500
-    income:acme inc
-
-   So,
-
-   * Do write two spaces between your period expression and your
-     transaction description, if any.
-   * Don't accidentally write two spaces in the middle of your period
-     expression.
-
-
-File: hledger.info,  Node: Auto postings,  Next: Other syntax,  Prev: Periodic transactions,  Up: Journal
-
-8.26 Auto postings
-==================
-
-The '=' directive declares an "auto posting rule", which adds extra
-postings to existing transactions.  (Remember, postings are the account
-name & amount lines below a transaction's date & description.)
-
-   In the journal, an auto posting rule looks quite like a transaction,
-but instead of date and description it has '=' (mnemonic: "match") and a
-query, like this:
-
-= QUERY
-    ACCOUNT    AMOUNT
-    ...
-
-   Queries are just like command line queries; an account name substring
-is most common.  Query terms containing spaces should be enclosed in
-single or double quotes.
-
-   Each '=' rule works like this: when hledger is run with the '--auto'
-flag, wherever the QUERY matches a posting in the journal, the rule's
-postings are added to that transaction, immediately below the matched
-posting.  Note these generated postings are temporary, existing only for
-the duration of the report, and only when '--auto' is used; they are not
-saved in the journal file by hledger.
-
-   Generated postings' amounts can depend on the matched posting's
-amount.  So auto postings can be useful for, eg, adding tax postings
-with a standard percentage.  AMOUNT can be:
-
-   * a number with no commodity symbol, like '2'.  The matched posting's
-     commodity symbol will be added to this.
-
-   * a normal amount with a commodity symbol, like '$2'.  This will be
-     used as-is.
-
-   * an asterisk followed by a number, like '*2'.  This will multiply
-     the matched posting's amount (and total price, if any) by the
-     number.
-
-   * an asterisk followed by an amount with commodity symbol, like
-     '*$2'.  This multiplies and also replaces the commodity symbol with
-     this new one.
-
-   Some examples:
-
-; every time I buy food, schedule a dollar donation
-= expenses:food
-    (liabilities:charity)   $-1
-
-; when I buy a gift, also deduct that amount from a budget envelope subaccount
-= expenses:gifts
-    assets:checking:gifts  *-1
-    assets:checking         *1
-
-2017/12/1
-  expenses:food    $10
-  assets:checking
-
-2017/12/14
-  expenses:gifts   $20
-  assets:checking
-
-$ hledger print --auto
-2017-12-01
-    expenses:food              $10
-    assets:checking
-    (liabilities:charity)      $-1
-
-2017-12-14
-    expenses:gifts             $20
-    assets:checking
-    assets:checking:gifts     -$20
-    assets:checking            $20
-
-   Note that depending fully on generated data such as this has some
-drawbacks - it's less portable, less future-proof, less auditable by
-others, and less robust (eg your balance assertions will depend on
-whether you use or don't use '--auto').  An alternative is to use auto
-postings in "one time" fashion - use them to help build a complex
-journal entry, view it with 'hledger print --auto', and then copy that
-output into the journal file to make it permanent.
-
-* Menu:
-
-* Auto postings and multiple files::
-* Auto postings and dates::
-* Auto postings and transaction balancing / inferred amounts / balance assertions::
-* Auto posting tags::
-* Auto postings on forecast transactions only::
-
-
-File: hledger.info,  Node: Auto postings and multiple files,  Next: Auto postings and dates,  Up: Auto postings
-
-8.26.1 Auto postings and multiple files
----------------------------------------
-
-An auto posting rule can affect any transaction in the current file, or
-in any parent file or child file.  Note, currently it will not affect
-sibling files (when multiple '-f'/'--file' are used - see #1212).
-
-
-File: hledger.info,  Node: Auto postings and dates,  Next: Auto postings and transaction balancing / inferred amounts / balance assertions,  Prev: Auto postings and multiple files,  Up: Auto postings
-
-8.26.2 Auto postings and dates
-------------------------------
-
-A posting date (or secondary date) in the matched posting, or (taking
-precedence) a posting date in the auto posting rule itself, will also be
-used in the generated posting.
-
-
-File: hledger.info,  Node: Auto postings and transaction balancing / inferred amounts / balance assertions,  Next: Auto posting tags,  Prev: Auto postings and dates,  Up: Auto postings
-
-8.26.3 Auto postings and transaction balancing / inferred amounts /
--------------------------------------------------------------------
-
-balance assertions Currently, auto postings are added:
-
-   * after missing amounts are inferred, and transactions are checked
-     for balancedness,
-   * but before balance assertions are checked.
-
-   Note this means that journal entries must be balanced both before and
-after auto postings are added.  This changed in hledger 1.12+; see #893
-for background.
-
-   This also means that you cannot have more than one auto-posting with
-a missing amount applied to a given transaction, as it will be unable to
-infer amounts.
-
-
-File: hledger.info,  Node: Auto posting tags,  Next: Auto postings on forecast transactions only,  Prev: Auto postings and transaction balancing / inferred amounts / balance assertions,  Up: Auto postings
-
-8.26.4 Auto posting tags
-------------------------
-
-Automated postings will have some extra tags:
-
-   * 'generated-posting:= QUERY' - shows this was generated by an auto
-     posting rule, and the query
-   * '_generated-posting:= QUERY' - a hidden tag, which does not appear
-     in hledger's output.  This can be used to match postings generated
-     "just now", rather than generated in the past and saved to the
-     journal.
-
-   Also, any transaction that has been changed by auto posting rules
-will have these tags added:
-
-   * 'modified:' - this transaction was modified
-   * '_modified:' - a hidden tag not appearing in the comment; this
-     transaction was modified "just now".
-
-
-File: hledger.info,  Node: Auto postings on forecast transactions only,  Prev: Auto posting tags,  Up: Auto postings
-
-8.26.5 Auto postings on forecast transactions only
---------------------------------------------------
-
-Tip: you can can make auto postings that will apply to forecast
-transactions but not recorded transactions, by adding
-'tag:_generated-transaction' to their QUERY. This can be useful when
-generating new journal entries to be saved in the journal.
-
-
-File: hledger.info,  Node: Other syntax,  Prev: Auto postings,  Up: Journal
-
-8.27 Other syntax
-=================
-
-hledger journal format supports quite a few other features, mainly to
-make interoperating with or converting from Ledger easier.  Note some of
-the features below are powerful and can be useful in special cases, but
-in general, features in this section are considered less important or
-even not recommended for most users.  Downsides are mentioned to help
-you decide if you want to use them.
-
-* Menu:
-
-* Balance assignments::
-* Bracketed posting dates::
-* D directive::
-* apply account directive::
-* Y directive::
-* Secondary dates::
-* Star comments::
-* Valuation expressions::
-* Virtual postings::
-* Other Ledger directives::
-* Other cost/lot notations::
-
-
-File: hledger.info,  Node: Balance assignments,  Next: Bracketed posting dates,  Up: Other syntax
-
-8.27.1 Balance assignments
---------------------------
-
-Ledger-style balance assignments are also supported.  These are like
-balance assertions, but with no posting amount on the left side of the
-equals sign; instead it is calculated automatically so as to satisfy the
-assertion.  This can be a convenience during data entry, eg when setting
-opening balances:
-
-; starting a new journal, set asset account balances
-2016/1/1 opening balances
-  assets:checking            = $409.32
-  assets:savings             = $735.24
-  assets:cash                 = $42
-  equity:opening balances
-
-   or when adjusting a balance to reality:
-
-; no cash left; update balance, record any untracked spending as a generic expense
-2016/1/15
-  assets:cash    = $0
-  expenses:misc
-
-   The calculated amount depends on the account's balance in the
-commodity at that point (which depends on the previously-dated postings
-of the commodity to that account since the last balance assertion or
-assignment).
-
-   Downsides: using balance assignments makes your journal less
-explicit; to know the exact amount posted, you have to run hledger or do
-the calculations yourself, instead of just reading it.  Also balance
-assignments' forcing of balances can hide errors.  These things make
-your financial data less portable, less future-proof, and less
-trustworthy in an audit.
-
-* Menu:
-
-* Balance assignments and costs::
-* Balance assignments and multiple files::
-
-
-File: hledger.info,  Node: Balance assignments and costs,  Next: Balance assignments and multiple files,  Up: Balance assignments
-
-8.27.1.1 Balance assignments and costs
-......................................
-
-A cost in a balance assignment will cause the calculated amount to have
-that cost attached:
-
-2019/1/1
-  (a)             = $1 @ €2
-
-$ hledger print --explicit
-2019-01-01
-    (a)         $1 @ €2 = $1 @ €2
-
-
-File: hledger.info,  Node: Balance assignments and multiple files,  Prev: Balance assignments and costs,  Up: Balance assignments
-
-8.27.1.2 Balance assignments and multiple files
-...............................................
-
-Balance assignments handle multiple files like balance assertions.  They
-see balance from other files previously included from the current file,
-but not from previous sibling or parent files.
-
-
-File: hledger.info,  Node: Bracketed posting dates,  Next: D directive,  Prev: Balance assignments,  Up: Other syntax
-
-8.27.2 Bracketed posting dates
-------------------------------
-
-For setting posting dates and secondary posting dates, Ledger's
-bracketed date syntax is also supported: '[DATE]', '[DATE=DATE2]' or
-'[=DATE2]' in posting comments.  hledger will attempt to parse any
-square-bracketed sequence of the '0123456789/-.=' characters in this
-way.  With this syntax, DATE infers its year from the transaction and
-DATE2 infers its year from DATE.
-
-   Downsides: another syntax to learn, redundant with hledger's
-'date:'/'date2:' tags, and confusingly similar to Ledger's lot date
-syntax.
-
-
-File: hledger.info,  Node: D directive,  Next: apply account directive,  Prev: Bracketed posting dates,  Up: Other syntax
-
-8.27.3 'D' directive
---------------------
-
-'D AMOUNT'
-
-   This directive sets a default commodity, to be used for any
-subsequent commodityless amounts (ie, plain numbers) seen while parsing
-the journal.  This effect lasts until the next 'D' directive, or the end
-of the current file.
-
-   For compatibility/historical reasons, 'D' also acts like a
-'commodity' directive (setting the commodity's decimal mark for parsing
-and display style for output).  So its argument is not just a commodity
-symbol, but a full amount demonstrating the style.  The amount must
-include a decimal mark (either period or comma).  Eg:
-
-; commodity-less amounts should be treated as dollars
-; (and displayed with the dollar sign on the left, thousands separators and two decimal places)
-D $1,000.00
-
-1/1
-  a     5  ; <- commodity-less amount, parsed as $5 and displayed as $5.00
-  b
-
-   Interactions with other directives:
-
-   For setting a commodity's display style, a 'commodity' directive has
-highest priority, then a 'D' directive.
-
-   For detecting a commodity's decimal mark during parsing,
-'decimal-mark' has highest priority, then 'commodity', then 'D'.
-
-   For checking commodity symbols with the check command, a 'commodity'
-directive is required ('hledger check commodities' ignores 'D'
-directives).
-
-   Downsides: omitting commodity symbols makes your financial data less
-explicit, less portable, and less trustworthy in an audit.  It is
-usually an unsustainable shortcut; sooner or later you will want to
-track multiple commodities.  D is overloaded with functions redundant
-with 'commodity' and 'decimal-mark'.  And it works differently from
-Ledger's 'D'.
-
-
-File: hledger.info,  Node: apply account directive,  Next: Y directive,  Prev: D directive,  Up: Other syntax
-
-8.27.4 'apply account' directive
---------------------------------
-
-This directive sets a default parent account, which will be prepended to
-all accounts in following entries, until an 'end apply account'
-directive or end of current file.  Eg:
-
-apply account home
-
-2010/1/1
-    food    $10
-    cash
-
-end apply account
-
-   is equivalent to:
-
-2010/01/01
-    home:food           $10
-    home:cash          $-10
-
-   'account' directives are also affected, and so is any 'include'd
-content.
-
-   Account names entered via hledger add or hledger-web are not
-affected.
-
-   Account aliases, if any, are applied after the parent account is
-prepended.
-
-   Downsides: this can make your financial data less explicit, less
-portable, and less trustworthy in an audit.
-
-
-File: hledger.info,  Node: Y directive,  Next: Secondary dates,  Prev: apply account directive,  Up: Other syntax
-
-8.27.5 'Y' directive
---------------------
-
-'Y YEAR'
-
-   or (deprecated backward-compatible forms):
-
-   'year YEAR' 'apply year YEAR'
-
-   The space is optional.  This sets a default year to be used for
-subsequent dates which don't specify a year.  Eg:
-
-Y2009  ; set default year to 2009
-
-12/15  ; equivalent to 2009/12/15
-  expenses  1
-  assets
-
-year 2010  ; change default year to 2010
-
-2009/1/30  ; specifies the year, not affected
-  expenses  1
-  assets
-
-1/31   ; equivalent to 2010/1/31
-  expenses  1
-  assets
-
-   Downsides: omitting the year (from primary transaction dates, at
-least) makes your financial data less explicit, less portable, and less
-trustworthy in an audit.  Such dates can get separated from their
-corresponding Y directive, eg when evaluating a region of the journal in
-your editor.  A missing Y directive makes reports dependent on today's
-date.
-
-
-File: hledger.info,  Node: Secondary dates,  Next: Star comments,  Prev: Y directive,  Up: Other syntax
-
-8.27.6 Secondary dates
-----------------------
-
-A secondary date is written after the primary date, following an equals
-sign: 'DATE1=DATE2'.  If the year is omitted, the primary date's year is
-assumed.  When running reports, the primary (left side) date is used by
-default, but with the '--date2' flag ('--aux-date' or'--effective' also
-work, for Ledger users), the secondary (right side) date will be used
-instead.
-
-   The meaning of secondary dates is up to you.  Eg it could be "primary
-is the bank's clearing date, secondary is the date the transaction was
-initiated, if different".
-
-   In practice, this feature usually adds confusion:
-
-   * You have to remember the primary and secondary dates' meaning, and
-     follow that consistently.
-   * It splits your bookkeeping into two modes, and you have to remember
-     which mode is appropriate for a given report.
-   * Usually your balance assertions will work with only one of these
-     modes.
-   * It makes your financial data more complicated, less portable, and
-     less clear in an audit.
-   * It interacts with every feature, creating an ongoing cost for
-     implementors.
-   * It distracts new users and supporters.
-   * Posting dates are simpler and work better.
-
-   So secondary dates are officially deprecated in hledger, remaining
-only as a Ledger compatibility aid; we recommend using posting dates
-instead.
-
-
-File: hledger.info,  Node: Star comments,  Next: Valuation expressions,  Prev: Secondary dates,  Up: Other syntax
-
-8.27.7 Star comments
---------------------
-
-Lines beginning with '*' (star/asterisk) are also comment lines.  This
-feature allows Emacs users to insert org headings in their journal,
-allowing them to fold/unfold/navigate it like an outline when viewed
-with org mode.
-
-   Downsides: another, unconventional comment syntax to learn.
-Decreases your journal's portability.  And switching to Emacs org mode
-just for folding/unfolding meant losing the benefits of ledger mode;
-nowadays you can add outshine mode to ledger mode to get folding without
-losing ledger mode's features.
-
-
-File: hledger.info,  Node: Valuation expressions,  Next: Virtual postings,  Prev: Star comments,  Up: Other syntax
-
-8.27.8 Valuation expressions
-----------------------------
-
-Ledger allows a valuation function or value to be written in double
-parentheses after an amount.  hledger ignores these.
-
-
-File: hledger.info,  Node: Virtual postings,  Next: Other Ledger directives,  Prev: Valuation expressions,  Up: Other syntax
-
-8.27.9 Virtual postings
------------------------
-
-A posting with parentheses around the account name, like '(some:account)
-10', is called an _unbalanced virtual posting_.  These postings do not
-participate in transaction balancing.  (And if you write them without an
-amount, a zero amount is always inferred.)  These can occasionally be
-convenient for special circumstances, but they violate double entry
-bookkeeping and make your data less portable across applications, so
-many people avoid using them at all.
-
-   A posting with brackets around the account name ('[some:account]') is
-called a _balanced virtual posting_.  The balanced virtual postings in a
-transaction must add up to zero, just like ordinary postings, but
-separately from them.  These are not part of double entry bookkeeping
-either, but they are at least balanced.  An example:
-
-2022-01-01 buy food with cash, update budget envelope subaccounts, & something else
-  assets:cash                    $-10  ; <- these balance each other
-  expenses:food                    $7  ; <-
-  expenses:food                    $3  ; <-
-  [assets:checking:budget:food]  $-10  ;   <- and these balance each other
-  [assets:checking:available]     $10  ;   <-
-  (something:else)                 $5  ;     <- this is not required to balance
-
-   Ordinary postings, whose account names are neither parenthesised nor
-bracketed, are called _real postings_.  You can exclude virtual postings
-from reports with the '-R/--real' flag or a 'real:1' query.
-
-
-File: hledger.info,  Node: Other Ledger directives,  Next: Other cost/lot notations,  Prev: Virtual postings,  Up: Other syntax
-
-8.27.10 Other Ledger directives
--------------------------------
-
-These other Ledger directives are currently accepted but ignored.  This
-allows hledger to read more Ledger files, but be aware that hledger's
-reports may differ from Ledger's if you use these.
-
-apply fixed COMM AMT
-apply tag   TAG
-assert      EXPR
-bucket / A  ACCT
-capture     ACCT REGEX
-check       EXPR
-define      VAR=EXPR
-end apply fixed
-end apply tag
-end apply year
-end tag
-eval / expr EXPR
-python
-  PYTHONCODE
-tag         NAME
-value       EXPR
---command-line-flags
-
-   See also https://hledger.org/ledger.html for a detailed
-hledger/Ledger syntax comparison.
-
-
-File: hledger.info,  Node: Other cost/lot notations,  Prev: Other Ledger directives,  Up: Other syntax
-
-8.27.11 Other cost/lot notations
---------------------------------
-
-A slight digression for Ledger and Beancount users.  Ledger has a number
-of cost/lot-related notations:
-
-   * '@ UNITCOST' and '@@ TOTALCOST'
-        * expresses a conversion rate, as in hledger
-        * when buying, also creates a lot than can be selected at
-          selling time
-
-   * '(@) UNITCOST' and '(@@) TOTALCOST' (virtual cost)
-        * like the above, but also means "this cost was exceptional,
-          don't use it when inferring market prices".
-
-   Currently, hledger treats the above like '@' and '@@'; the
-parentheses are ignored.
-
-   * '{=FIXEDUNITCOST}' and '{{=FIXEDTOTALCOST}}' (fixed price)
-        * when buying, means "this cost is also the fixed price, don't
-          let it fluctuate in value reports"
-
-   * '{UNITCOST}' and '{{TOTALCOST}}' (lot price)
-        * can be used identically to '@ UNITCOST' and '@@ TOTALCOST',
-          also creates a lot
-        * when selling, combined with '@ ...', specifies an investment
-          lot by its cost basis; does not check if that lot is present
-
-   * and related: '[YYYY/MM/DD]' (lot date)
-        * when buying, attaches this acquisition date to the lot
-        * when selling, selects a lot by its acquisition date
-
-   * '(SOME TEXT)' (lot note)
-        * when buying, attaches this note to the lot
-        * when selling, selects a lot by its note
-
-   Currently, hledger accepts any or all of the above in any order after
-the posting amount, but ignores them.  (This can break transaction
-balancing.)
-
-   For Beancount users, the notation and behaviour is different:
-
-   * '@ UNITCOST' and '@@ TOTALCOST'
-        * expresses a cost without creating a lot, as in hledger
-        * when buying (augmenting) or selling (reducing) a lot, combined
-          with '{...}': documents the cost/selling price (not used for
-          transaction balancing)
-
-   * '{UNITCOST}' and '{{TOTALCOST}}'
-        * when buying (augmenting), expresses the cost for transaction
-          balancing, and also creates a lot with this cost basis
-          attached
-        * when selling (reducing),
-             * selects a lot by its cost basis
-             * raises an error if that lot is not present or can not be
-               selected unambiguously (depending on booking method
-               configured)
-             * expresses the selling price for transaction balancing
-
-   Currently, hledger accepts the '{UNITCOST}'/'{{TOTALCOST}}' notation
-but ignores it.
-
-   * variations: '{}', '{YYYY-MM-DD}', '{"LABEL"}', '{UNITCOST,
-     "LABEL"}', '{UNITCOST, YYYY-MM-DD, "LABEL"}' etc.
-
-   Currently, hledger rejects these.
-
-
-File: hledger.info,  Node: CSV,  Next: Timeclock,  Prev: Journal,  Up: Top
-
-9 CSV
-*****
-
-hledger can read CSV files (Character Separated Value - usually comma,
-semicolon, or tab) containing dated records, automatically converting
-each record into a transaction.
-
-   (To learn about _writing_ CSV, see CSV output.)
-
-   For best error messages when reading CSV/TSV/SSV files, make sure
-they have a corresponding '.csv', '.tsv' or '.ssv' file extension or use
-a hledger file prefix (see File Extension below).
-
-   Each CSV file must be described by a corresponding _rules file_.
-This contains rules describing the CSV data (header line, fields layout,
-date format etc.), how to construct hledger transactions from it, and
-how to categorise transactions based on description or other attributes.
-
-   By default, hledger expects this rules file to be named like the CSV
-file, with an extra '.rules' extension added, in the same directory.  Eg
-when asked to read 'foo/FILE.csv', hledger looks for
-'foo/FILE.csv.rules'.  You can specify a different rules file with the
-'--rules' option.
-
-   At minimum, the rules file must identify the date and amount fields,
-and often it also specifies the date format and how many header lines
-there are.  Here's a simple CSV file and a rules file for it:
-
-Date, Description, Id, Amount
-12/11/2019, Foo, 123, 10.23
-
-# basic.csv.rules
-skip         1
-fields       date, description, , amount
-date-format  %d/%m/%Y
-
-$ hledger print -f basic.csv
-2019-11-12 Foo
-    expenses:unknown           10.23
-    income:unknown            -10.23
-
-   There's an introductory Importing CSV data tutorial on hledger.org,
-and more CSV rules examples below, and a larger collection at
-https://github.com/simonmichael/hledger/tree/master/examples/csv.
-
-* Menu:
-
-* CSV rules cheatsheet::
-* source::
-* separator::
-* skip::
-* date-format::
-* timezone::
-* newest-first::
-* intra-day-reversed::
-* decimal-mark::
-* fields list::
-* Field assignment::
-* Field names::
-* if block::
-* Matchers::
-* if table::
-* balance-type::
-* include::
-* Working with CSV::
-* CSV rules examples::
-
-
-File: hledger.info,  Node: CSV rules cheatsheet,  Next: source,  Up: CSV
-
-9.1 CSV rules cheatsheet
-========================
-
-The following kinds of rule can appear in the rules file, in any order.
-(Blank lines and lines beginning with '#' or ';' or '*' are ignored.)
-
-*'source'*               optionally declare which file to read data
-                         from
-*'separator'*            declare the field separator, instead of
-                         relying on file extension
-*'skip'*                 skip one or more header lines at start of file
-*'date-format'*          declare how to parse CSV dates/date-times
-*'timezone'*             declare the time zone of ambiguous CSV
-                         date-times
-*'newest-first'*         improve txn order when: there are multiple
-                         records, newest first, all with the same date
-*'intra-day-reversed'*   improve txn order when: same-day txns are in
-                         opposite order to the overall file
-*'decimal-mark'*         declare the decimal mark used in CSV amounts,
-                         when ambiguous
-*'fields' list*          name CSV fields for easy reference, and
-                         optionally assign their values to hledger
-                         fields
-*Field assignment*       assign a CSV value or interpolated text value
-                         to a hledger field
-*'if' block*             conditionally assign values to hledger fields,
-                         or 'skip' a record or 'end' (skip rest of
-                         file)
-*'if' table*             conditionally assign values to hledger fields,
-                         using compact syntax
-*'balance-type'*         select which type of balance
-                         assertions/assignments to generate
-*'include'*              inline another CSV rules file
-
-   Working with CSV tips can be found below, including How CSV rules are
-evaluated.
-
-
-File: hledger.info,  Node: source,  Next: separator,  Prev: CSV rules cheatsheet,  Up: CSV
-
-9.2 'source'
-============
-
-If you tell hledger to read a csv file with '-f foo.csv', it will look
-for rules in 'foo.csv.rules'.  Or, you can tell it to read the rules
-file, with '-f foo.csv.rules', and it will look for data in 'foo.csv'
-(since 1.30).
-
-   These are mostly equivalent, but the second method provides some
-extra features.  For one, the data file can be missing, without causing
-an error; it is just considered empty.  And, you can specify a different
-data file by adding a "source" rule:
-
-source ./Checking1.csv
-
-   If you specify just a file name with no path, hledger will look for
-it in your system's downloads directory ('~/Downloads', currently):
-
-source Checking1.csv
-
-   And if you specify a glob pattern, hledger will read the most recent
-of the matched files (useful with repeated downloads):
-
-source Checking1*.csv
-
-   See also "Working with CSV > Reading files specified by rule".
-
-
-File: hledger.info,  Node: separator,  Next: skip,  Prev: source,  Up: CSV
-
-9.3 'separator'
-===============
-
-You can use the 'separator' rule to read other kinds of
-character-separated data.  The argument is any single separator
-character, or the words 'tab' or 'space' (case insensitive).  Eg, for
-comma-separated values (CSV):
-
-separator ,
-
-   or for semicolon-separated values (SSV):
-
-separator ;
-
-   or for tab-separated values (TSV):
-
-separator TAB
-
-   If the input file has a '.csv', '.ssv' or '.tsv' file extension (or a
-'csv:', 'ssv:', 'tsv:' prefix), the appropriate separator will be
-inferred automatically, and you won't need this rule.
-
-
-File: hledger.info,  Node: skip,  Next: date-format,  Prev: separator,  Up: CSV
-
-9.4 'skip'
-==========
-
-skip N
-
-   The word 'skip' followed by a number (or no number, meaning 1) tells
-hledger to ignore this many non-empty lines at the start of the input
-data.  You'll need this whenever your CSV data contains header lines.
-Note, empty and blank lines are skipped automatically, so you don't need
-to count those.
-
-   'skip' has a second meaning: it can be used inside if blocks
-(described below), to skip one or more records whenever the condition is
-true.  Records skipped in this way are ignored, except they are still
-required to be valid CSV.
-
-
-File: hledger.info,  Node: date-format,  Next: timezone,  Prev: skip,  Up: CSV
-
-9.5 'date-format'
-=================
-
-date-format DATEFMT
-
-   This is a helper for the 'date' (and 'date2') fields.  If your CSV
-dates are not formatted like 'YYYY-MM-DD', 'YYYY/MM/DD' or 'YYYY.MM.DD',
-you'll need to add a date-format rule describing them with a
-strptime-style date parsing pattern - see
-https://hackage.haskell.org/package/time/docs/Data-Time-Format.html#v:formatTime.
-The pattern must parse the CSV date value completely.  Some examples:
-
-# MM/DD/YY
-date-format %m/%d/%y
-
-# D/M/YYYY
-# The - makes leading zeros optional.
-date-format %-d/%-m/%Y
-
-# YYYY-Mmm-DD
-date-format %Y-%h-%d
-
-# M/D/YYYY HH:MM AM some other junk
-# Note the time and junk must be fully parsed, though only the date is used.
-date-format %-m/%-d/%Y %l:%M %p some other junk
-
-
-File: hledger.info,  Node: timezone,  Next: newest-first,  Prev: date-format,  Up: CSV
-
-9.6 'timezone'
-==============
-
-timezone TIMEZONE
-
-   When CSV contains date-times that are implicitly in some time zone
-other than yours, but containing no explicit time zone information, you
-can use this rule to declare the CSV's native time zone, which helps
-prevent off-by-one dates.
-
-   When the CSV date-times do contain time zone information, you don't
-need this rule; instead, use '%Z' in 'date-format' (or '%z', '%EZ',
-'%Ez'; see the formatTime link above).
-
-   In either of these cases, hledger will do a time-zone-aware
-conversion, localising the CSV date-times to your current system time
-zone.  If you prefer to localise to some other time zone, eg for
-reproducibility, you can (on unix at least) set the output timezone with
-the TZ environment variable, eg:
-
-$ TZ=-1000 hledger print -f foo.csv  # or TZ=-1000 hledger import foo.csv
-
-   'timezone' currently does not understand timezone names, except
-"UTC", "GMT", "EST", "EDT", "CST", "CDT", "MST", "MDT", "PST", or "PDT".
-For others, use numeric format: +HHMM or -HHMM.
-
-
-File: hledger.info,  Node: newest-first,  Next: intra-day-reversed,  Prev: timezone,  Up: CSV
-
-9.7 'newest-first'
-==================
-
-hledger tries to ensure that the generated transactions will be ordered
-chronologically, including same-day transactions.  Usually it can
-auto-detect how the CSV records are ordered.  But if it encounters CSV
-where all records are on the same date, it assumes that the records are
-oldest first.  If in fact the CSV's records are normally newest first,
-like:
-
-2022-10-01, txn 3...
-2022-10-01, txn 2...
-2022-10-01, txn 1...
-
-   you can add the 'newest-first' rule to help hledger generate the
-transactions in correct order.
-
-# same-day CSV records are newest first
-newest-first
-
-
-File: hledger.info,  Node: intra-day-reversed,  Next: decimal-mark,  Prev: newest-first,  Up: CSV
-
-9.8 'intra-day-reversed'
-========================
-
-If CSV records within a single day are ordered opposite to the overall
-record order, you can add the 'intra-day-reversed' rule to improve the
-order of journal entries.  Eg, here the overall record order is newest
-first, but same-day records are oldest first:
-
-2022-10-02, txn 3...
-2022-10-02, txn 4...
-2022-10-01, txn 1...
-2022-10-01, txn 2...
-
-# transactions within each day are reversed with respect to the overall date order
-intra-day-reversed
-
-
-File: hledger.info,  Node: decimal-mark,  Next: fields list,  Prev: intra-day-reversed,  Up: CSV
-
-9.9 'decimal-mark'
-==================
-
-decimal-mark .
-
-   or:
-
-decimal-mark ,
-
-   hledger automatically accepts either period or comma as a decimal
-mark when parsing numbers (cf Amounts).  However if any numbers in the
-CSV contain digit group marks, such as thousand-separating commas, you
-should declare the decimal mark explicitly with this rule, to avoid
-misparsed numbers.
-
-
-File: hledger.info,  Node: fields list,  Next: Field assignment,  Prev: decimal-mark,  Up: CSV
-
-9.10 'fields' list
-==================
-
-fields FIELDNAME1, FIELDNAME2, ...
-
-   A fields list (the word 'fields' followed by comma-separated field
-names) is optional, but convenient.  It does two things:
-
-  1. It names the CSV field in each column.  This can be convenient if
-     you are referencing them in other rules, so you can say
-     '%SomeField' instead of remembering '%13'.
-
-  2. Whenever you use one of the special hledger field names (described
-     below), it assigns the CSV value in this position to that hledger
-     field.  This is the quickest way to populate hledger's fields and
-     build a transaction.
-
-   Here's an example that says "use the 1st, 2nd and 4th fields as the
-transaction's date, description and amount; name the last two fields for
-later reference; and ignore the others":
-
-fields date, description, , amount, , , somefield, anotherfield
-
-   In a fields list, the separator is always comma; it is unrelated to
-the CSV file's separator.  Also:
-
-   * There must be least two items in the list (at least one comma).
-   * Field names may not contain spaces.  Spaces before/after field
-     names are optional.
-   * Field names may contain '_' (underscore) or '-' (hyphen).
-   * Fields you don't care about can be given a dummy name or an empty
-     name.
-
-   If the CSV contains column headings, it's convenient to use these for
-your field names, suitably modified (eg lower-cased with spaces replaced
-by underscores).
-
-   Sometimes you may want to alter a CSV field name to avoid assigning
-to a hledger field with the same name.  Eg you could call the CSV's
-"balance" field 'balance_' to avoid directly setting hledger's 'balance'
-field (and generating a balance assertion).
-
-
-File: hledger.info,  Node: Field assignment,  Next: Field names,  Prev: fields list,  Up: CSV
-
-9.11 Field assignment
-=====================
-
-HLEDGERFIELD FIELDVALUE
-
-   Field assignments are the more flexible way to assign CSV values to
-hledger fields.  They can be used instead of or in addition to a fields
-list (see above).
-
-   To assign a value to a hledger field, write the field name (any of
-the standard hledger field/pseudo-field names, defined below), a space,
-followed by a text value on the same line.  This text value may
-interpolate CSV fields, referenced either by their 1-based position in
-the CSV record ('%N') or by the name they were given in the fields list
-('%CSVFIELD'), and regular expression match groups ('\N').
-
-   Some examples:
-
-# set the amount to the 4th CSV field, with " USD" appended
-amount %4 USD
-
-# combine three fields to make a comment, containing note: and date: tags
-comment note: %somefield - %anotherfield, date: %1
-
-   Tips:
-
-   * Interpolation strips outer whitespace (so a CSV value like '" 1 "'
-     becomes '1' when interpolated) (#1051).
-   * Interpolations always refer to a CSV field - you can't interpolate
-     a hledger field.  (See Referencing other fields below).
-
-
-File: hledger.info,  Node: Field names,  Next: if block,  Prev: Field assignment,  Up: CSV
-
-9.12 Field names
-================
-
-Note the two kinds of field names mentioned here, and used only in
-hledger CSV rules files:
-
-  1. *CSV field names* ('CSVFIELD' in these docs): you can optionally
-     name the CSV columns for easy reference (since hledger doesn't yet
-     automatically recognise column headings in a CSV file), by writing
-     arbitrary names in a 'fields' list, eg:
-
-     fields When, What, Some_Id, Net, Total, Foo, Bar
-
-  2. Special *hledger field names* ('HLEDGERFIELD' in these docs): you
-     must set at least some of these to generate the hledger transaction
-     from a CSV record, by writing them as the left hand side of a field
-     assignment, eg:
-
-     date        %When
-     code        %Some_Id
-     description %What
-     comment     %Foo %Bar
-     amount1     $ %Total
-
-     or directly in a 'fields' list:
-
-     fields date, description, code, , amount1, Foo, Bar
-     currency $
-     comment  %Foo %Bar
-
-   Here are all the special hledger field names available, and what
-happens when you assign values to them:
-
-* Menu:
-
-* date field::
-* date2 field::
-* status field::
-* code field::
-* description field::
-* comment field::
-* account field::
-* amount field::
-* currency field::
-* balance field::
-
-
-File: hledger.info,  Node: date field,  Next: date2 field,  Up: Field names
-
-9.12.1 date field
------------------
-
-Assigning to 'date' sets the transaction date.
-
-
-File: hledger.info,  Node: date2 field,  Next: status field,  Prev: date field,  Up: Field names
-
-9.12.2 date2 field
-------------------
-
-'date2' sets the transaction's secondary date, if any.
-
-
-File: hledger.info,  Node: status field,  Next: code field,  Prev: date2 field,  Up: Field names
-
-9.12.3 status field
--------------------
-
-'status' sets the transaction's status, if any.
-
-
-File: hledger.info,  Node: code field,  Next: description field,  Prev: status field,  Up: Field names
-
-9.12.4 code field
------------------
-
-'code' sets the transaction's code, if any.
-
-
-File: hledger.info,  Node: description field,  Next: comment field,  Prev: code field,  Up: Field names
-
-9.12.5 description field
-------------------------
-
-'description' sets the transaction's description, if any.
-
-
-File: hledger.info,  Node: comment field,  Next: account field,  Prev: description field,  Up: Field names
-
-9.12.6 comment field
---------------------
-
-'comment' sets the transaction's comment, if any.
-
-   'commentN', where N is a number, sets the Nth posting's comment.
-
-   You can assign multi-line comments by writing literal '\n' in the
-code.  A comment starting with '\n' will begin on a new line.
-
-   Comments can contain tags, as usual.
-
-   Posting comments can also contain a posting date.  A secondary date,
-or a year-less date, will be ignored.
-
-
-File: hledger.info,  Node: account field,  Next: amount field,  Prev: comment field,  Up: Field names
-
-9.12.7 account field
---------------------
-
-Assigning to 'accountN', where N is 1 to 99, sets the account name of
-the Nth posting, and causes that posting to be generated.
-
-   Most often there are two postings, so you'll want to set 'account1'
-and 'account2'.  Typically 'account1' is associated with the CSV file,
-and is set once with a top-level assignment, while 'account2' is set
-based on each transaction's description, in conditional rules.
-
-   If a posting's account name is left unset but its amount is set (see
-below), a default account name will be chosen (like "expenses:unknown"
-or "income:unknown").
-
-
-File: hledger.info,  Node: amount field,  Next: currency field,  Prev: account field,  Up: Field names
-
-9.12.8 amount field
--------------------
-
-There are several ways to set posting amounts from CSV, useful in
-different situations.
-
-  1. *'amount'* is the oldest and simplest.  Assigning to this sets the
-     amount of the first and second postings.  In the second posting,
-     the amount will be negated; also, if it has a cost attached, it
-     will be converted to cost.
-
-  2. *'amount-in'* and *'amount-out'* work exactly like the above, but
-     should be used when the CSV has two amount fields (such as "Debit"
-     and "Credit", or "Inflow" and "Outflow").  Whichever field has a
-     non-zero value will be used as the amount of the first and second
-     postings.  Here are some tips to avoid confusion:
-
-        * It's not "amount-in for posting 1 and amount-out for posting
-          2", it is "extract a single amount from the amount-in or
-          amount-out field, and use that for posting 1 and (negated) for
-          posting 2".
-        * Don't use both 'amount' and 'amount-in'/'amount-out' in the
-          same rules file; choose based on whether the amount is in a
-          single CSV field or spread across two fields.
-        * In each record, at most one of the two CSV fields should
-          contain a non-zero amount; the other field must contain a zero
-          or nothing.
-        * hledger assumes both CSV fields contain unsigned numbers, and
-          it automatically negates the amount-out values.
-        * If the data doesn't fit these requirements, you'll probably
-          need an if rule (see below).
-
-  3. *'amountN'* (where N is a number from 1 to 99) sets the amount of
-     only a single posting: the Nth posting in the transaction.  You'll
-     usually need at least two such assignments to make a balanced
-     transaction.  You can also generate more than two postings, to
-     represent more complex transactions.  The posting numbers don't
-     have to be consecutive; with if rules, higher posting numbers can
-     be useful to ensure a certain order of postings.
-
-  4. *'amountN-in'* and *'amountN-out'* work exactly like the above, but
-     should be used when the CSV has two amount fields.  This is
-     analogous to 'amount-in' and 'amount-out', and those tips also
-     apply here.
-
-  5. Remember that a 'fields' list can also do assignments.  So in a
-     fields list if you name a CSV field "amount", that counts as
-     assigning to 'amount'.  (If you don't want that, call it something
-     else in the fields list, like "amount_".)
-
-  6. The above don't handle every situation; if you need more
-     flexibility, use an 'if' rule to set amounts conditionally.  See
-     "Working with CSV > Setting amounts" below for more on this and on
-     amount-setting generally.
-
-
-File: hledger.info,  Node: currency field,  Next: balance field,  Prev: amount field,  Up: Field names
-
-9.12.9 currency field
----------------------
-
-'currency' sets a currency symbol, to be prepended to all postings'
-amounts.  You can use this if the CSV amounts do not have a currency
-symbol, eg if it is in a separate column.
-
-   'currencyN' prepends a currency symbol to just the Nth posting's
-amount.
-
-
-File: hledger.info,  Node: balance field,  Prev: currency field,  Up: Field names
-
-9.12.10 balance field
----------------------
-
-'balanceN' sets a balance assertion amount (or if the posting amount is
-left empty, a balance assignment) on posting N.
-
-   'balance' is a compatibility spelling for hledger <1.17; it is
-equivalent to 'balance1'.
-
-   You can adjust the type of assertion/assignment with the
-'balance-type' rule (see below).
-
-   See the Working with CSV tips below for more about setting amounts
-and currency.
-
-
-File: hledger.info,  Node: if block,  Next: Matchers,  Prev: Field names,  Up: CSV
-
-9.13 'if' block
-===============
-
-Rules can be applied conditionally, depending on patterns in the CSV
-data.  This allows flexibility; in particular, it is how you can
-categorise transactions, selecting an appropriate account name based on
-their description (for example).  There are two ways to write
-conditional rules: "if blocks", described here, and "if tables",
-described below.
-
-   An if block is the word 'if' and one or more "matcher" expressions
-(can be a word or phrase), one per line, starting either on the same or
-next line; followed by one or more indented rules.  Eg,
-
-if MATCHER
- RULE
-
-   or
-
-if
-MATCHER
-MATCHER
-MATCHER
- RULE
- RULE
-
-   If any of the matchers succeeds, all of the indented rules will be
-applied.  They are usually field assignments, but the following special
-rules may also be used within an if block:
-
-   * 'skip' - skips the matched CSV record (generating no transaction
-     from it)
-   * 'end' - skips the rest of the current CSV file.
-
-   Some examples:
-
-# if the record contains "groceries", set account2 to "expenses:groceries"
-if groceries
- account2 expenses:groceries
-
-# if the record contains any of these phrases, set account2 and a transaction comment as shown
-if
-monthly service fee
-atm transaction fee
-banking thru software
- account2 expenses:business:banking
- comment  XXX deductible ? check it
-
-# if an empty record is seen (assuming five fields), ignore the rest of the CSV file
-if ,,,,
- end
-
-
-File: hledger.info,  Node: Matchers,  Next: if table,  Prev: if block,  Up: CSV
-
-9.14 Matchers
-=============
-
-There are two kinds of matcher:
-
-  1. A whole record matcher is simplest: it is just a word, single-line
-     text fragment, or other regular expression, which hledger will try
-     to match case-insensitively anywhere within the CSV record.
-     Eg: 'whole foods'.
-
-  2. A field matcher has a percent-prefixed CSV field number or name
-     before the pattern.
-     Eg: '%3 whole foods' or '%description whole foods'.
-     hledger will try to match the pattern just within the named CSV
-     field.
-
-   When using these, there's two things to be aware of:
-
-  1. Whole record matchers don't see the exact original record; they see
-     a reconstruction of it, in which values are comma-separated, and
-     quotes enclosing values and whitespace outside those quotes are
-     removed.
-     Eg when reading an SSV record like: '2023-01-01 ; "Acme, Inc. " ;
-     1,000'
-     the whole record matcher sees instead: '2023-01-01,Acme, Inc.
-     ,1,000'
-
-  2. Field matchers expect either a CSV field number, or a CSV field
-     name declared with 'fields'.  (Don't use a hledger field name here,
-     unless it is also a CSV field name.)  A non-CSV field name will
-     cause the matcher to match against '""' (the empty string), and
-     does not raise an error, allowing easier reuse of common rules with
-     different CSV files.
-
-   You can also prefix a matcher with '!' (and optional space) to negate
-it.  Eg '! whole foods', '! %3 whole foods', '!%description whole foods'
-will match if "whole foods" is NOT present.  _Added in 1.32._
-
-   The pattern is, as usual in hledger, a POSIX extended regular
-expression that also supports GNU word boundaries ('\b', '\B', '\<',
-'\>') and nothing else.  If you have trouble with it, see "Regular
-expressions" in the hledger manual
-(https://hledger.org/hledger.html#regular-expressions).
-
-* Menu:
-
-* Multiple matchers::
-* Match groups::
-
-
-File: hledger.info,  Node: Multiple matchers,  Next: Match groups,  Up: Matchers
-
-9.14.1 Multiple matchers
-------------------------
-
-When an if block has multiple matchers, each on its own line,
-
-   * By default they are OR'd (any of them can match).
-   * Matcher lines beginning with '&' (and optional space) are AND'ed
-     with the matcher above (all in the AND'ed group must match).
-
-   _(Since 1.41:)_ You can use a negated '!' matcher on a '&' line,
-meaning AND NOT.
-
-
-File: hledger.info,  Node: Match groups,  Prev: Multiple matchers,  Up: Matchers
-
-9.14.2 Match groups
--------------------
-
-_Added in 1.32_
-
-   Matchers can define match groups: parenthesised portions of the
-regular expression which are available for reference in field
-assignments.  Groups are enclosed in regular parentheses ('(' and ')')
-and can be nested.  Each group is available in field assignments using
-the token '\N', where N is an index into the match groups for this
-conditional block (e.g.  '\1', '\2', etc.).
-
-   Example: Warp credit card payment postings to the beginning of the
-billing period (Month start), to match how they are presented in
-statements, using posting dates:
-
-if %date (....-..)-..
-  comment2 date:\1-01
-
-   Another example: Read the expense account from the CSV field, but
-throw away a prefix:
-
-if %account1 liabilities:family:(expenses:.*)
-    account1 \1
-
-
-File: hledger.info,  Node: if table,  Next: balance-type,  Prev: Matchers,  Up: CSV
-
-9.15 'if' table
-===============
-
-"if tables" are an alternative to if blocks; they can express many
-matchers and field assignments in a more compact tabular format, like
-this:
-
-if,HLEDGERFIELD1,HLEDGERFIELD2,...
-MATCHERA,VALUE1,VALUE2,...
-MATCHERB,VALUE1,VALUE2,...
-; Comment line that explains MATCHERC
-MATCHERC,VALUE1,VALUE2,...
-<empty line>
-
-   The first character after 'if' is taken to be this if table's field
-separator.  It is unrelated to the separator used in the CSV file.  It
-should be a non-alphanumeric character like ',' or '|' that does not
-appear anywhere else in the table (it should not be used in field names
-or matchers or values, and it cannot be escaped with a backslash).
-
-   Each line must contain the same number of separators; empty values
-are allowed.  Whitespace can be used in the matcher lines for
-readability (but not in the if line, currently).  You can use the
-comment lines in the table body.  The table must be terminated by an
-empty line (or end of file).
-
-   An if table like the above is interpreted as follows: try all of the
-matchers; whenever a matcher succeeds, assign all of the values on that
-line to the corresponding hledger fields; If multiple lines match, later
-lines will override fields assigned by the earlier ones - just like the
-sequence of 'if' blocks would behave.
-
-   If table presented above is equivalent to this sequence of if blocks:
-
-if MATCHERA
-  HLEDGERFIELD1 VALUE1
-  HLEDGERFIELD2 VALUE2
-  ...
-
-if MATCHERB
-  HLEDGERFIELD1 VALUE1
-  HLEDGERFIELD2 VALUE2
-  ...
-
-; Comment line which explains MATCHERC
-if MATCHERC
-  HLEDGERFIELD1 VALUE1
-  HLEDGERFIELD2 VALUE2
-  ...
-
-   Example:
-
-if,account2,comment
-atm transaction fee,expenses:business:banking,deductible? check it
-%description groceries,expenses:groceries,
-;; Comment line that desribes why this particular date is special
-2023/01/12.*Plumbing LLC,expenses:house:upkeep,emergency plumbing call-out
-
-
-File: hledger.info,  Node: balance-type,  Next: include,  Prev: if table,  Up: CSV
-
-9.16 'balance-type'
-===================
-
-Balance assertions generated by assigning to balanceN are of the simple
-'=' type by default, which is a single-commodity, subaccount-excluding
-assertion.  You may find the subaccount-including variants more useful,
-eg if you have created some virtual subaccounts of checking to help with
-budgeting.  You can select a different type of assertion with the
-'balance-type' rule:
-
-# balance assertions will consider all commodities and all subaccounts
-balance-type ==*
-
-   Here are the balance assertion types for quick reference:
-
-=    single commodity, exclude subaccounts
-=*   single commodity, include subaccounts
-==   multi commodity,  exclude subaccounts
-==*  multi commodity,  include subaccounts
-
-
-File: hledger.info,  Node: include,  Next: Working with CSV,  Prev: balance-type,  Up: CSV
-
-9.17 'include'
-==============
-
-include RULESFILE
-
-   This includes the contents of another CSV rules file at this point.
-'RULESFILE' is an absolute file path or a path relative to the current
-file's directory.  This can be useful for sharing common rules between
-several rules files, eg:
-
-# someaccount.csv.rules
-
-## someaccount-specific rules
-fields   date,description,amount
-account1 assets:someaccount
-account2 expenses:misc
-
-## common rules
-include categorisation.rules
-
-
-File: hledger.info,  Node: Working with CSV,  Next: CSV rules examples,  Prev: include,  Up: CSV
-
-9.18 Working with CSV
-=====================
-
-Some tips:
-
-* Menu:
-
-* Rapid feedback::
-* Valid CSV::
-* File Extension::
-* Reading CSV from standard input::
-* Reading multiple CSV files::
-* Reading files specified by rule::
-* Valid transactions::
-* Deduplicating importing::
-* Setting amounts::
-* Amount signs::
-* Setting currency/commodity::
-* Amount decimal places::
-* Referencing other fields::
-* How CSV rules are evaluated::
-* Well factored rules::
-
-
-File: hledger.info,  Node: Rapid feedback,  Next: Valid CSV,  Up: Working with CSV
-
-9.18.1 Rapid feedback
----------------------
-
-It's a good idea to get rapid feedback while creating/troubleshooting
-CSV rules.  Here's a good way, using entr from eradman.com/entrproject:
-
-$ ls foo.csv* | entr bash -c 'echo ----; hledger -f foo.csv print desc:SOMEDESC'
-
-   A desc: query (eg) is used to select just one, or a few, transactions
-of interest.  "bash -c" is used to run multiple commands, so we can echo
-a separator each time the command re-runs, making it easier to read the
-output.
-
-
-File: hledger.info,  Node: Valid CSV,  Next: File Extension,  Prev: Rapid feedback,  Up: Working with CSV
-
-9.18.2 Valid CSV
-----------------
-
-Note that hledger will only accept valid CSV conforming to RFC 4180, and
-equivalent SSV and TSV formats (like RFC 4180 but with semicolon or tab
-as separators).  This means, eg:
-
-   * Values may be enclosed in double quotes, or not.  Enclosing in
-     single quotes is not allowed.  (Eg ''A','B'' is rejected.)
-   * When values are enclosed in double quotes, spaces outside the
-     quotes are not allowed.  (Eg '"A", "B"' is rejected.)
-   * When values are not enclosed in quotes, they may not contain double
-     quotes.  (Eg 'A"A, B' is rejected.)
-
-   If your CSV/SSV/TSV is not valid in this sense, you'll need to
-transform it before reading with hledger.  Try using sed, or a more
-permissive CSV parser like python's csv lib.
-
-
-File: hledger.info,  Node: File Extension,  Next: Reading CSV from standard input,  Prev: Valid CSV,  Up: Working with CSV
-
-9.18.3 File Extension
----------------------
-
-To help hledger choose the CSV file reader and show the right error
-messages (and choose the right field separator character by default),
-it's best if CSV/SSV/TSV files are named with a '.csv', '.ssv' or '.tsv'
-filename extension.  (More about this at Data formats.)
-
-   When reading files with the "wrong" extension, you can ensure the CSV
-reader (and the default field separator) by prefixing the file path with
-'csv:', 'ssv:' or 'tsv:': Eg:
-
-$ hledger -f ssv:foo.dat print
-
-   You can also override the default field separator with a separator
-rule if needed.
-
-
-File: hledger.info,  Node: Reading CSV from standard input,  Next: Reading multiple CSV files,  Prev: File Extension,  Up: Working with CSV
-
-9.18.4 Reading CSV from standard input
---------------------------------------
-
-You'll need the file format prefix when reading CSV from stdin also,
-since hledger assumes journal format by default.  Eg:
-
-$ cat foo.dat | hledger -f ssv:- print
-
-
-File: hledger.info,  Node: Reading multiple CSV files,  Next: Reading files specified by rule,  Prev: Reading CSV from standard input,  Up: Working with CSV
-
-9.18.5 Reading multiple CSV files
----------------------------------
-
-If you use multiple '-f' options to read multiple CSV files at once,
-hledger will look for a correspondingly-named rules file for each CSV
-file.  But if you specify a rules file with '--rules', that rules file
-will be used for all the CSV files.
-
-
-File: hledger.info,  Node: Reading files specified by rule,  Next: Valid transactions,  Prev: Reading multiple CSV files,  Up: Working with CSV
-
-9.18.6 Reading files specified by rule
---------------------------------------
-
-Instead of specifying a CSV file in the command line, you can specify a
-rules file, as in 'hledger -f foo.csv.rules CMD'.  By default this will
-read data from foo.csv in the same directory, but you can add a source
-rule to specify a different data file, perhaps located in your web
-browser's download directory.
-
-   This feature was added in hledger 1.30, so you won't see it in most
-CSV rules examples.  But it helps remove some of the busywork of
-managing CSV downloads.  Most of your financial institutions's default
-CSV filenames are different and can be recognised by a glob pattern.  So
-you can put a rule like 'source Checking1*.csv' in
-foo-checking.csv.rules, and then periodically follow a workflow like:
-
-  1. Download CSV from Foo's website, using your browser's defaults
-  2. Run 'hledger import foo-checking.csv.rules' to import any new
-     transactions
-
-   After import, you can: discard the CSV, or leave it where it is for a
-while, or move it into your archives, as you prefer.  If you do nothing,
-next time your browser will save something like Checking1-2.csv, and
-hledger will use that because of the '*' wild card and because it is the
-most recent.
-
-
-File: hledger.info,  Node: Valid transactions,  Next: Deduplicating importing,  Prev: Reading files specified by rule,  Up: Working with CSV
-
-9.18.7 Valid transactions
--------------------------
-
-After reading a CSV file, hledger post-processes and validates the
-generated journal entries as it would for a journal file - balancing
-them, applying balance assignments, and canonicalising amount styles.
-Any errors at this stage will be reported in the usual way, displaying
-the problem entry.
-
-   There is one exception: balance assertions, if you have generated
-them, will not be checked, since normally these will work only when the
-CSV data is part of the main journal.  If you do need to check balance
-assertions generated from CSV right away, pipe into another hledger:
-
-$ hledger -f file.csv print | hledger -f- print
-
-
-File: hledger.info,  Node: Deduplicating importing,  Next: Setting amounts,  Prev: Valid transactions,  Up: Working with CSV
-
-9.18.8 Deduplicating, importing
--------------------------------
-
-When you download a CSV file periodically, eg to get your latest bank
-transactions, the new file may overlap with the old one, containing some
-of the same records.
-
-   The import command will (a) detect the new transactions, and (b)
-append just those transactions to your main journal.  It is idempotent,
-so you don't have to remember how many times you ran it or with which
-version of the CSV. (It keeps state in a hidden '.latest.FILE.csv'
-file.)  This is the easiest way to import CSV data.  Eg:
-
-# download the latest CSV files, then run this command.
-# Note, no -f flags needed here.
-$ hledger import *.csv [--dry]
-
-   This method works for most CSV files.  (Where records have a stable
-chronological order, and new records appear only at the new end.)
-
-   A number of other tools and workflows, hledger-specific and
-otherwise, exist for converting, deduplicating, classifying and managing
-CSV data.  See:
-
-   * https://hledger.org/cookbook.html#setups-and-workflows
-   * https://plaintextaccounting.org -> data import/conversion
-
-
-File: hledger.info,  Node: Setting amounts,  Next: Amount signs,  Prev: Deduplicating importing,  Up: Working with CSV
-
-9.18.9 Setting amounts
-----------------------
-
-Continuing from amount field above, here are more tips for
-amount-setting:
-
-  1. *If the amount is in a single CSV field:*
-
-       a. *If its sign indicates direction of flow:*
-          Assign it to 'amountN', to set the Nth posting's amount.  N is
-          usually 1 or 2 but can go up to 99.
-
-       b. *If another field indicates direction of flow:*
-          Use one or more conditional rules to set the appropriate
-          amount sign.  Eg:
-
-     # assume a withdrawal unless Type contains "deposit":
-     amount1  -%Amount
-     if %Type deposit
-       amount1  %Amount
-
-  2. *If the amount is in two CSV fields (such as Debit and Credit, or
-     In and Out):*
-
-       a. *If both fields are unsigned:*
-          Assign one field to 'amountN-in' and the other to
-          'amountN-out'.  hledger will automatically negate the "out"
-          field, and will use whichever field value is non-zero as
-          posting N's amount.
-
-       b. *If either field is signed:*
-          You will probably need to override hledger's sign for one or
-          the other field, as in the following example:
-
-     # Negate the -out value, but only if it is not empty:
-     fields date, description, amount1-in, amount1-out
-     if %amount1-out [1-9]
-      amount1-out -%amount1-out
-
-       c. *If both fields can contain a non-zero value (or both can be
-          empty):*
-          The -in/-out rules normally choose the value which is
-          non-zero/non-empty.  Some value pairs can be ambiguous, such
-          as '1' and 'none'.  For such cases, use conditional rules to
-          help select the amount.  Eg, to handle the above you could
-          select the value containing non-zero digits:
-
-     fields date, description, in, out
-     if %in [1-9]
-      amount1 %in
-     if %out [1-9]
-      amount1 %out
-
-  3. *If you want posting 2's amount converted to cost:*
-     Use the unnumbered 'amount' (or 'amount-in' and 'amount-out')
-     syntax.
-
-  4. *If the CSV has only balance amounts, not transaction amounts:*
-     Assign to 'balanceN', to set a balance assignment on the Nth
-     posting, causing the posting's amount to be calculated
-     automatically.  'balance' with no number is equivalent to
-     'balance1'.  In this situation hledger is more likely to guess the
-     wrong default account name, so you may need to set that explicitly.
-
-
-File: hledger.info,  Node: Amount signs,  Next: Setting currency/commodity,  Prev: Setting amounts,  Up: Working with CSV
-
-9.18.10 Amount signs
---------------------
-
-There is some special handling making it easier to parse and to reverse
-amount signs.  (This only works for whole amounts, not for cost amounts
-such as COST in 'amount1 AMT @ COST'):
-
-   * *If an amount value begins with a plus sign:*
-     that will be removed: '+AMT' becomes 'AMT'
-
-   * *If an amount value is parenthesised:*
-     it will be de-parenthesised and sign-flipped: '(AMT)' becomes
-     '-AMT'
-
-   * *If an amount value has two minus signs (or two sets of
-     parentheses, or a minus sign and parentheses):*
-     they cancel out and will be removed: '--AMT' or '-(AMT)' becomes
-     'AMT'
-
-   * *If an amount value contains just a sign (or just a set of
-     parentheses):*
-     that is removed, making it an empty value.  '"+"' or '"-"' or
-     '"()"' becomes '""'.
-
-   It's not possible (without preprocessing the CSV) to set an amount to
-its absolute value, ie discard its sign.
-
-
-File: hledger.info,  Node: Setting currency/commodity,  Next: Amount decimal places,  Prev: Amount signs,  Up: Working with CSV
-
-9.18.11 Setting currency/commodity
-----------------------------------
-
-If the currency/commodity symbol is included in the CSV's amount
-field(s):
-
-2023-01-01,foo,$123.00
-
-   you don't have to do anything special for the commodity symbol, it
-will be assigned as part of the amount.  Eg:
-
-fields date,description,amount
-
-2023-01-01 foo
-    expenses:unknown         $123.00
-    income:unknown          $-123.00
-
-   If the currency is provided as a separate CSV field:
-
-2023-01-01,foo,USD,123.00
-
-   You can assign that to the 'currency' pseudo-field, which has the
-special effect of prepending itself to every amount in the transaction
-(on the left, with no separating space):
-
-fields date,description,currency,amount
-
-2023-01-01 foo
-    expenses:unknown       USD123.00
-    income:unknown        USD-123.00
-
-   Or, you can use a field assignment to construct the amount yourself,
-with more control.  Eg to put the symbol on the right, and separated by
-a space:
-
-fields date,description,cur,amt
-amount %amt %cur
-
-2023-01-01 foo
-    expenses:unknown        123.00 USD
-    income:unknown         -123.00 USD
-
-   Note we used a temporary field name ('cur') that is not 'currency' -
-that would trigger the prepending effect, which we don't want here.
-
-
-File: hledger.info,  Node: Amount decimal places,  Next: Referencing other fields,  Prev: Setting currency/commodity,  Up: Working with CSV
-
-9.18.12 Amount decimal places
------------------------------
-
-When you are reading CSV data, eg with a command like 'hledger -f
-foo.csv print', hledger will infer each commodity's decimal precision
-(and other commodity display styles) from the amounts - much as when
-reading a journal file without 'commodity' directives (see the link).
-
-   Note, the commodity styles are not inferred from the numbers in the
-original CSV data; rather, they are inferred from the amounts generated
-by the CSV rules.
-
-   When you are importing CSV data with the 'import' command, eg
-'hledger import foo.csv', there's another step: 'import' tries to make
-the new entries conform to the journal's existing styles.  So for each
-commodity - let's say it's EUR - 'import' will choose:
-
-  1. the style declared for EUR by a 'commodity' directive in the
-     journal
-  2. otherwise, the style inferred from EUR amounts in the journal
-  3. otherwise, the style inferred from EUR amounts generated by the CSV
-     rules.
-
-   TLDR: if 'import' is not generating the precisions or styles you
-want, add a 'commodity' directive to specify them.
-
-
-File: hledger.info,  Node: Referencing other fields,  Next: How CSV rules are evaluated,  Prev: Amount decimal places,  Up: Working with CSV
-
-9.18.13 Referencing other fields
---------------------------------
-
-In field assignments, you can interpolate only CSV fields, not hledger
-fields.  In the example below, there's both a CSV field and a hledger
-field named amount1, but %amount1 always means the CSV field, not the
-hledger field:
-
-# Name the third CSV field "amount1"
-fields date,description,amount1
-
-# Set hledger's amount1 to the CSV amount1 field followed by USD
-amount1 %amount1 USD
-
-# Set comment to the CSV amount1 (not the amount1 assigned above)
-comment %amount1
-
-   Here, since there's no CSV amount1 field, %amount1 will produce a
-literal "amount1":
-
-fields date,description,csvamount
-amount1 %csvamount USD
-# Can't interpolate amount1 here
-comment %amount1
-
-   When there are multiple field assignments to the same hledger field,
-only the last one takes effect.  Here, comment's value will be be B, or
-C if "something" is matched, but never A:
-
-comment A
-comment B
-if something
- comment C
-
-
-File: hledger.info,  Node: How CSV rules are evaluated,  Next: Well factored rules,  Prev: Referencing other fields,  Up: Working with CSV
-
-9.18.14 How CSV rules are evaluated
------------------------------------
-
-Here's how to think of CSV rules being evaluated (if you really need
-to).  First,
-
-   * 'include' - all includes are inlined, from top to bottom, depth
-     first.  (At each include point the file is inlined and scanned for
-     further includes, recursively, before proceeding.)
-
-   Then "global" rules are evaluated, top to bottom.  If a rule is
-repeated, the last one wins:
-
-   * 'skip' (at top level)
-   * 'date-format'
-   * 'newest-first'
-   * 'fields' - names the CSV fields, optionally sets up initial
-     assignments to hledger fields
-
-   Then for each CSV record in turn:
-
-   * test all 'if' blocks.  If any of them contain a 'end' rule, skip
-     all remaining CSV records.  Otherwise if any of them contain a
-     'skip' rule, skip that many CSV records.  If there are multiple
-     matched 'skip' rules, the first one wins.
-   * collect all field assignments at top level and in matched 'if'
-     blocks.  When there are multiple assignments for a field, keep only
-     the last one.
-   * compute a value for each hledger field - either the one that was
-     assigned to it (and interpolate the %CSVFIELD references), or a
-     default
-   * generate a hledger transaction (journal entry) from these values.
-
-   This is all part of the CSV reader, one of several readers hledger
-can use to parse input files.  When all files have been read
-successfully, the transactions are passed as input to whichever hledger
-command the user specified.
-
-
-File: hledger.info,  Node: Well factored rules,  Prev: How CSV rules are evaluated,  Up: Working with CSV
-
-9.18.15 Well factored rules
----------------------------
-
-Some things than can help reduce duplication and complexity in rules
-files:
-
-   * Extracting common rules usable with multiple CSV files into a
-     'common.rules', and adding 'include common.rules' to each CSV's
-     rules file.
-
-   * Splitting if blocks into smaller if blocks, extracting the
-     frequently used parts.
-
-
-File: hledger.info,  Node: CSV rules examples,  Prev: Working with CSV,  Up: CSV
-
-9.19 CSV rules examples
-=======================
-
-* Menu:
-
-* Bank of Ireland::
-* Coinbase::
-* Amazon::
-* Paypal::
-
-
-File: hledger.info,  Node: Bank of Ireland,  Next: Coinbase,  Up: CSV rules examples
-
-9.19.1 Bank of Ireland
-----------------------
-
-Here's a CSV with two amount fields (Debit and Credit), and a balance
-field, which we can use to add balance assertions, which is not
-necessary but provides extra error checking:
-
-Date,Details,Debit,Credit,Balance
-07/12/2012,LODGMENT       529898,,10.0,131.21
-07/12/2012,PAYMENT,5,,126
-
-# bankofireland-checking.csv.rules
-
-# skip the header line
-skip
-
-# name the csv fields, and assign some of them as journal entry fields
-fields  date, description, amount-out, amount-in, balance
-
-# We generate balance assertions by assigning to "balance"
-# above, but you may sometimes need to remove these because:
-#
-# - the CSV balance differs from the true balance,
-#   by up to 0.0000000000005 in my experience
-#
-# - it is sometimes calculated based on non-chronological ordering,
-#   eg when multiple transactions clear on the same day
-
-# date is in UK/Ireland format
-date-format  %d/%m/%Y
-
-# set the currency
-currency  EUR
-
-# set the base account for all txns
-account1  assets:bank:boi:checking
-
-$ hledger -f bankofireland-checking.csv print
-2012-12-07 LODGMENT       529898
-    assets:bank:boi:checking         EUR10.0 = EUR131.2
-    income:unknown                  EUR-10.0
-
-2012-12-07 PAYMENT
-    assets:bank:boi:checking         EUR-5.0 = EUR126.0
-    expenses:unknown                  EUR5.0
-
-   The balance assertions don't raise an error above, because we're
-reading directly from CSV, but they will be checked if these entries are
-imported into a journal file.
-
-
-File: hledger.info,  Node: Coinbase,  Next: Amazon,  Prev: Bank of Ireland,  Up: CSV rules examples
-
-9.19.2 Coinbase
----------------
-
-A simple example with some CSV from Coinbase.  The spot price is
-recorded using cost notation.  The legacy 'amount' field name
-conveniently sets amount 2 (posting 2's amount) to the total cost.
-
-# Timestamp,Transaction Type,Asset,Quantity Transacted,Spot Price Currency,Spot Price at Transaction,Subtotal,Total (inclusive of fees and/or spread),Fees and/or Spread,Notes
-# 2021-12-30T06:57:59Z,Receive,USDC,100,GBP,0.740000,"","","","Received 100.00 USDC from an external account"
-
-# coinbase.csv.rules
-skip         1
-fields       Timestamp,Transaction_Type,Asset,Quantity_Transacted,Spot_Price_Currency,Spot_Price_at_Transaction,Subtotal,Total,Fees_Spread,Notes
-date         %Timestamp
-date-format  %Y-%m-%dT%T%Z
-description  %Notes
-account1     assets:coinbase:cc
-amount       %Quantity_Transacted %Asset @ %Spot_Price_at_Transaction %Spot_Price_Currency
-
-$ hledger print -f coinbase.csv
-2021-12-30 Received 100.00 USDC from an external account
-    assets:coinbase:cc    100 USDC @ 0.740000 GBP
-    income:unknown                 -74.000000 GBP
-
-
-File: hledger.info,  Node: Amazon,  Next: Paypal,  Prev: Coinbase,  Up: CSV rules examples
-
-9.19.3 Amazon
--------------
-
-Here we convert amazon.com order history, and use an if block to
-generate a third posting if there's a fee.  (In practice you'd probably
-get this data from your bank instead, but it's an example.)
-
-"Date","Type","To/From","Name","Status","Amount","Fees","Transaction ID"
-"Jul 29, 2012","Payment","To","Foo.","Completed","$20.00","$0.00","16000000000000DGLNJPI1P9B8DKPVHL"
-"Jul 30, 2012","Payment","To","Adapteva, Inc.","Completed","$25.00","$1.00","17LA58JSKRD4HDGLNJPI1P9B8DKPVHL"
-
-# amazon-orders.csv.rules
-
-# skip one header line
-skip 1
-
-# name the csv fields, and assign the transaction's date, amount and code.
-# Avoided the "status" and "amount" hledger field names to prevent confusion.
-fields date, _, toorfrom, name, amzstatus, amzamount, fees, code
-
-# how to parse the date
-date-format %b %-d, %Y
-
-# combine two fields to make the description
-description %toorfrom %name
-
-# save the status as a tag
-comment     status:%amzstatus
-
-# set the base account for all transactions
-account1    assets:amazon
-# leave amount1 blank so it can balance the other(s).
-# I'm assuming amzamount excludes the fees, don't remember
-
-# set a generic account2
-account2    expenses:misc
-amount2     %amzamount
-# and maybe refine it further:
-#include categorisation.rules
-
-# add a third posting for fees, but only if they are non-zero.
-if %fees [1-9]
- account3    expenses:fees
- amount3     %fees
-
-$ hledger -f amazon-orders.csv print
-2012-07-29 (16000000000000DGLNJPI1P9B8DKPVHL) To Foo.  ; status:Completed
-    assets:amazon
-    expenses:misc          $20.00
-
-2012-07-30 (17LA58JSKRD4HDGLNJPI1P9B8DKPVHL) To Adapteva, Inc.  ; status:Completed
-    assets:amazon
-    expenses:misc          $25.00
-    expenses:fees           $1.00
-
-
-File: hledger.info,  Node: Paypal,  Prev: Amazon,  Up: CSV rules examples
-
-9.19.4 Paypal
--------------
-
-Here's a real-world rules file for (customised) Paypal CSV, with some
-Paypal-specific rules, and a second rules file included:
-
-"Date","Time","TimeZone","Name","Type","Status","Currency","Gross","Fee","Net","From Email Address","To Email Address","Transaction ID","Item Title","Item ID","Reference Txn ID","Receipt ID","Balance","Note"
-"10/01/2019","03:46:20","PDT","Calm Radio","Subscription Payment","Completed","USD","-6.99","0.00","-6.99","simon@joyful.com","memberships@calmradio.com","60P57143A8206782E","MONTHLY - $1 for the first 2 Months: Me - Order 99309. Item total: $1.00 USD first 2 months, then $6.99 / Month","","I-R8YLY094FJYR","","-6.99",""
-"10/01/2019","03:46:20","PDT","","Bank Deposit to PP Account ","Pending","USD","6.99","0.00","6.99","","simon@joyful.com","0TU1544T080463733","","","60P57143A8206782E","","0.00",""
-"10/01/2019","08:57:01","PDT","Patreon","PreApproved Payment Bill User Payment","Completed","USD","-7.00","0.00","-7.00","simon@joyful.com","support@patreon.com","2722394R5F586712G","Patreon* Membership","","B-0PG93074E7M86381M","","-7.00",""
-"10/01/2019","08:57:01","PDT","","Bank Deposit to PP Account ","Pending","USD","7.00","0.00","7.00","","simon@joyful.com","71854087RG994194F","Patreon* Membership","","2722394R5F586712G","","0.00",""
-"10/19/2019","03:02:12","PDT","Wikimedia Foundation, Inc.","Subscription Payment","Completed","USD","-2.00","0.00","-2.00","simon@joyful.com","tle@wikimedia.org","K9U43044RY432050M","Monthly donation to the Wikimedia Foundation","","I-R5C3YUS3285L","","-2.00",""
-"10/19/2019","03:02:12","PDT","","Bank Deposit to PP Account ","Pending","USD","2.00","0.00","2.00","","simon@joyful.com","3XJ107139A851061F","","","K9U43044RY432050M","","0.00",""
-"10/22/2019","05:07:06","PDT","Noble Benefactor","Subscription Payment","Completed","USD","10.00","-0.59","9.41","noble@bene.fac.tor","simon@joyful.com","6L8L1662YP1334033","Joyful Systems","","I-KC9VBGY2GWDB","","9.41",""
-
-# paypal-custom.csv.rules
-
-# Tips:
-# Export from Activity -> Statements -> Custom -> Activity download
-# Suggested transaction type: "Balance affecting"
-# Paypal's default fields in 2018 were:
-# "Date","Time","TimeZone","Name","Type","Status","Currency","Gross","Fee","Net","From Email Address","To Email Address","Transaction ID","Shipping Address","Address Status","Item Title","Item ID","Shipping and Handling Amount","Insurance Amount","Sales Tax","Option 1 Name","Option 1 Value","Option 2 Name","Option 2 Value","Reference Txn ID","Invoice Number","Custom Number","Quantity","Receipt ID","Balance","Address Line 1","Address Line 2/District/Neighborhood","Town/City","State/Province/Region/County/Territory/Prefecture/Republic","Zip/Postal Code","Country","Contact Phone Number","Subject","Note","Country Code","Balance Impact"
-# This rules file assumes the following more detailed fields, configured in "Customize report fields":
-# "Date","Time","TimeZone","Name","Type","Status","Currency","Gross","Fee","Net","From Email Address","To Email Address","Transaction ID","Item Title","Item ID","Reference Txn ID","Receipt ID","Balance","Note"
-
-fields date, time, timezone, description_, type, status_, currency, grossamount, feeamount, netamount, fromemail, toemail, code, itemtitle, itemid, referencetxnid, receiptid, balance, note
-
-skip  1
-
-date-format  %-m/%-d/%Y
-
-# ignore some paypal events
-if
-In Progress
-Temporary Hold
-Update to
- skip
-
-# add more fields to the description
-description %description_ %itemtitle
-
-# save some other fields as tags
-comment  itemid:%itemid, fromemail:%fromemail, toemail:%toemail, time:%time, type:%type, status:%status_
-
-# convert to short currency symbols
-if %currency USD
- currency $
-if %currency EUR
- currency E
-if %currency GBP
- currency P
-
-# generate postings
-
-# the first posting will be the money leaving/entering my paypal account
-# (negative means leaving my account, in all amount fields)
-account1 assets:online:paypal
-amount1  %netamount
-
-# the second posting will be money sent to/received from other party
-# (account2 is set below)
-amount2  -%grossamount
-
-# if there's a fee, add a third posting for the money taken by paypal.
-if %feeamount [1-9]
- account3 expenses:banking:paypal
- amount3  -%feeamount
- comment3 business:
-
-# choose an account for the second posting
-
-# override the default account names:
-# if the amount is positive, it's income (a debit)
-if %grossamount ^[^-]
- account2 income:unknown
-# if negative, it's an expense (a credit)
-if %grossamount ^-
- account2 expenses:unknown
-
-# apply common rules for setting account2 & other tweaks
-include common.rules
-
-# apply some overrides specific to this csv
-
-# Transfers from/to bank. These are usually marked Pending,
-# which can be disregarded in this case.
-if
-Bank Account
-Bank Deposit to PP Account
- description %type for %referencetxnid %itemtitle
- account2 assets:bank:wf:pchecking
- account1 assets:online:paypal
-
-# Currency conversions
-if Currency Conversion
- account2 equity:currency conversion
-
-# common.rules
-
-if
-darcs
-noble benefactor
- account2 revenues:foss donations:darcshub
- comment2 business:
-
-if
-Calm Radio
- account2 expenses:online:apps
-
-if
-electronic frontier foundation
-Patreon
-wikimedia
-Advent of Code
- account2 expenses:dues
-
-if Google
- account2 expenses:online:apps
- description google | music
-
-$ hledger -f paypal-custom.csv  print
-2019-10-01 (60P57143A8206782E) Calm Radio MONTHLY - $1 for the first 2 Months: Me - Order 99309. Item total: $1.00 USD first 2 months, then $6.99 / Month  ; itemid:, fromemail:simon@joyful.com, toemail:memberships@calmradio.com, time:03:46:20, type:Subscription Payment, status:Completed
-    assets:online:paypal          $-6.99 = $-6.99
-    expenses:online:apps           $6.99
-
-2019-10-01 (0TU1544T080463733) Bank Deposit to PP Account for 60P57143A8206782E  ; itemid:, fromemail:, toemail:simon@joyful.com, time:03:46:20, type:Bank Deposit to PP Account, status:Pending
-    assets:online:paypal               $6.99 = $0.00
-    assets:bank:wf:pchecking          $-6.99
-
-2019-10-01 (2722394R5F586712G) Patreon Patreon* Membership  ; itemid:, fromemail:simon@joyful.com, toemail:support@patreon.com, time:08:57:01, type:PreApproved Payment Bill User Payment, status:Completed
-    assets:online:paypal          $-7.00 = $-7.00
-    expenses:dues                  $7.00
-
-2019-10-01 (71854087RG994194F) Bank Deposit to PP Account for 2722394R5F586712G Patreon* Membership  ; itemid:, fromemail:, toemail:simon@joyful.com, time:08:57:01, type:Bank Deposit to PP Account, status:Pending
-    assets:online:paypal               $7.00 = $0.00
-    assets:bank:wf:pchecking          $-7.00
-
-2019-10-19 (K9U43044RY432050M) Wikimedia Foundation, Inc. Monthly donation to the Wikimedia Foundation  ; itemid:, fromemail:simon@joyful.com, toemail:tle@wikimedia.org, time:03:02:12, type:Subscription Payment, status:Completed
-    assets:online:paypal             $-2.00 = $-2.00
-    expenses:dues                     $2.00
-    expenses:banking:paypal      ; business:
-
-2019-10-19 (3XJ107139A851061F) Bank Deposit to PP Account for K9U43044RY432050M  ; itemid:, fromemail:, toemail:simon@joyful.com, time:03:02:12, type:Bank Deposit to PP Account, status:Pending
-    assets:online:paypal               $2.00 = $0.00
-    assets:bank:wf:pchecking          $-2.00
-
-2019-10-22 (6L8L1662YP1334033) Noble Benefactor Joyful Systems  ; itemid:, fromemail:noble@bene.fac.tor, toemail:simon@joyful.com, time:05:07:06, type:Subscription Payment, status:Completed
-    assets:online:paypal                       $9.41 = $9.41
-    revenues:foss donations:darcshub         $-10.00  ; business:
-    expenses:banking:paypal                    $0.59  ; business:
-
-
-File: hledger.info,  Node: Timeclock,  Next: Timedot,  Prev: CSV,  Up: Top
-
-10 Timeclock
-************
-
-The time logging format of timeclock.el, as read by hledger.
-
-   hledger can read time logs in timeclock format.  As with Ledger,
-these are (a subset of) timeclock.el's format, containing clock-in and
-clock-out entries as in the example below.  The date is a simple date.
-The time format is HH:MM[:SS][+-ZZZZ]. Seconds and timezone are
-optional.  The timezone, if present, must be four digits and is ignored
-(currently the time is always interpreted as a local time).  Lines
-beginning with '#' or ';' or '*', and blank lines, are ignored.
-
-i 2015/03/30 09:00:00 some account  optional description after 2 spaces ; optional comment, tags:
-o 2015/03/30 09:20:00
-i 2015/03/31 22:21:45 another:account
-o 2015/04/01 02:00:34
-
-   hledger treats each clock-in/clock-out pair as a transaction posting
-some number of hours to an account.  Or if the session spans more than
-one day, it is split into several transactions, one for each day.  For
-the above time log, 'hledger print' generates these journal entries:
-
-$ hledger -f t.timeclock print
-2015-03-30 * optional description after 2 spaces   ; optional comment, tags:
-    (some account)           0.33h
-
-2015-03-31 * 22:21-23:59
-    (another:account)           1.64h
-
-2015-04-01 * 00:00-02:00
-    (another:account)           2.01h
-
-   Here is a sample.timeclock to download and some queries to try:
-
-$ hledger -f sample.timeclock balance                               # current time balances
-$ hledger -f sample.timeclock register -p 2009/3                    # sessions in march 2009
-$ hledger -f sample.timeclock register -p weekly --depth 1 --empty  # time summary by week
-
-   To generate time logs, ie to clock in and clock out, you could:
-
-   * use these shell aliases at the command line:
-
-     alias ti='echo i `date "+%Y-%m-%d %H:%M:%S"` $* >>$TIMELOG'
-     alias to='echo o `date "+%Y-%m-%d %H:%M:%S"` >>$TIMELOG'
-
-   * or Emacs's built-in timeclock.el, or the extended timeclock-x.el,
-     and perhaps the extras in ledgerutils.el
-
-   * or use the old 'ti' and 'to' scripts in the ledger 2.x repository.
-     These rely on a "timeclock" executable which I think is just the
-     ledger 2 executable renamed.
-
-
-File: hledger.info,  Node: Timedot,  Next: PART 3 REPORTING CONCEPTS,  Prev: Timeclock,  Up: Top
-
-11 Timedot
-**********
-
-'timedot' format is hledger's human-friendly time logging format.
-Compared to 'timeclock' format, it is more convenient for quick,
-approximate, and retroactive time logging, and more human-readable (you
-can see at a glance where time was spent).  A quick example:
-
-2023-05-01
-hom:errands          .... ....  ; two hours; the space is ignored
-fos:hledger:timedot  ..         ; half an hour
-per:admin:finance               ; no time spent yet
-
-   hledger reads this as a transaction on this day with three
-(unbalanced) postings, where each dot represents "0.25".  No commodity
-symbol is assumed, but we typically interpret it as hours.
-
-$ hledger -f a.timedot print   # .timedot file extension (or timedot: prefix) is required
-2023-05-01 *
-    (hom:errands)                    2.00  ; two hours
-    (fos:hledger:timedot)            0.50  ; half an hour
-    (per:admin:finance)                 0
-
-   A timedot file contains a series of transactions (usually one per
-day).  Each begins with a *simple date* (Y-M-D, Y/M/D, or Y.M.D),
-optionally be followed on the same line by a transaction description,
-and/or a transaction comment following a semicolon.
-
-   After the date line are zero or more time postings, consisting of:
-
-   * *An account name* - any hledger-style account name, optionally
-     indented.
-
-   * *Two or more spaces* - required if there is an amount (as in
-     journal format).
-
-   * *A timedot amount*, which can be
-
-        * empty (representing zero)
-
-        * a number, optionally followed by a unit 's', 'm', 'h', 'd',
-          'w', 'mo', or 'y', representing a precise number of seconds,
-          minutes, hours, days weeks, months or years (hours is assumed
-          by default), which will be converted to hours according to 60s
-          = 1m, 60m = 1h, 24h = 1d, 7d = 1w, 30d = 1mo, 365d = 1y.
-
-        * one or more dots (period characters), each representing 0.25.
-          These are the dots in "timedot".  Spaces are ignored and can
-          be used for grouping/alignment.
-
-        * _Added in 1.32_ one or more letters.  These are like dots but
-          they also generate a tag 't:' (short for "type") with the
-          letter as its value, and a separate posting for each of the
-          values.  This provides a second dimension of categorisation,
-          viewable in reports with '--pivot t'.
-
-   * *An optional comment* following a semicolon (a hledger-style
-     posting comment).
-
-   There is some flexibility to help with keeping time log data and
-notes in the same file:
-
-   * Blank lines and lines beginning with '#' or ';' are ignored.
-
-   * After the first date line, lines which do not contain a double
-     space are parsed as postings with zero amount.  (hledger's register
-     reports will show these if you add -E).
-
-   * Before the first date line, lines beginning with '*' (eg org
-     headings) are ignored.  And from the first date line onward, Emacs
-     org mode heading prefixes at the start of lines (one or more '*''s
-     followed by a space) will be ignored.  This means the time log can
-     also be a org outline.
-
-   Timedot files don't support directives like journal files.  So a
-common pattern is to have a main journal file (eg 'time.journal') that
-contains any needed directives, and then includes the timedot file
-('include time.timedot').
-
-* Menu:
-
-* Timedot examples::
-
-
-File: hledger.info,  Node: Timedot examples,  Up: Timedot
-
-11.1 Timedot examples
-=====================
-
-Numbers:
-
-2016/2/3
-inc:client1   4
-fos:hledger   3h
-biz:research  60m
-
-   Dots:
-
-# on this day, 6h was spent on client work, 1.5h on haskell FOSS work, etc.
-2016/2/1
-inc:client1   .... .... .... .... .... ....
-fos:haskell   .... ..
-biz:research  .
-
-2016/2/2
-inc:client1   .... ....
-biz:research  .
-
-$ hledger -f a.timedot print date:2016/2/2
-2016-02-02 *
-    (inc:client1)          2.00
-
-2016-02-02 *
-    (biz:research)          0.25
-
-$ hledger -f a.timedot bal --daily --tree
-Balance changes in 2016-02-01-2016-02-03:
-
-            ||  2016-02-01d  2016-02-02d  2016-02-03d 
-============++========================================
- biz        ||         0.25         0.25         1.00 
-   research ||         0.25         0.25         1.00 
- fos        ||         1.50            0         3.00 
-   haskell  ||         1.50            0            0 
-   hledger  ||            0            0         3.00 
- inc        ||         6.00         2.00         4.00 
-   client1  ||         6.00         2.00         4.00 
-------------++----------------------------------------
-            ||         7.75         2.25         8.00 
-
-   Letters:
-
-# Activity types:
-#  c cleanup/catchup/repair
-#  e enhancement
-#  s support
-#  l learning/research
-
-2023-11-01
-work:adm  ccecces
-
-$ hledger -f a.timedot print
-2023-11-01
-    (work:adm)  1     ; t:c
-    (work:adm)  0.5   ; t:e
-    (work:adm)  0.25  ; t:s
-
-$ hledger -f a.timedot bal
-                1.75  work:adm
---------------------
-                1.75  
-
-$ hledger -f a.timedot bal --pivot t
-                1.00  c
-                0.50  e
-                0.25  s
---------------------
-                1.75  
-
-   Org:
-
-* 2023 Work Diary
-** Q1
-*** 2023-02-29
-**** DONE
-0700 yoga
-**** UNPLANNED
-**** BEGUN
-hom:chores
- cleaning  ...
- water plants
-  outdoor - one full watering can
-  indoor - light watering
-**** TODO
-adm:planning: trip
-*** LATER
-
-   Using '.' as account name separator:
-
-2016/2/4
-fos.hledger.timedot  4h
-fos.ledger           ..
-
-$ hledger -f a.timedot --alias '/\./=:' bal -t
-                4.50  fos
-                4.00    hledger:timedot
-                0.50    ledger
---------------------
-                4.50
-
-
-File: hledger.info,  Node: PART 3 REPORTING CONCEPTS,  Next: Time periods,  Prev: Timedot,  Up: Top
-
-12 PART 3: REPORTING CONCEPTS
-*****************************
-
-
-File: hledger.info,  Node: Time periods,  Next: Depth,  Prev: PART 3 REPORTING CONCEPTS,  Up: Top
-
-13 Time periods
-***************
-
-* Menu:
-
-* Report start & end date::
-* Smart dates::
-* Report intervals::
-* Date adjustments::
-* Period headings::
-* Period expressions::
-
-
-File: hledger.info,  Node: Report start & end date,  Next: Smart dates,  Up: Time periods
-
-13.1 Report start & end date
-============================
-
-Most hledger reports will by default show the full time period
-represented by the journal.  The report start date will be the earliest
-transaction or posting date, and the report end date will be the latest
-transaction, posting, or market price date.
-
-   Often you will want to see a shorter period, such as the current
-month.  You can specify a start and/or end date with the '-b/--begin',
-'-e/--end', or '-p/--period' options, or a 'date:' query argument,
-described below.  All of these accept the smart date syntax, also
-described below.
-
-   End dates are exclusive; specify the day after the last day you want
-to see in the report.
-
-   When dates are specified by multiple options, the last (right-most)
-option wins.  And when 'date:' queries and date options are combined,
-the report period will be their intersection.
-
-   Examples:
-
-'-b 2016/3/17'
-
-     beginning on St.  Patrick's day 2016
-'-e 12/1'
-
-     ending at the start of December 1st in the current year
-'-p 'this month''
-
-     during the current month
-'-p thismonth'
-
-     same as above, spaces are optional
-'-b 2023'
-
-     beginning on the first day of 2023
-'date:2023..' or 'date:2023-'
-
-     same as above
-
-   '-b 2024 -e 2025 -p '2000 to 2030' date:2020-01 date:2020' :
-during January 2020 (the smallest common period, with the -p overriding
--b and -e)
-
-
-File: hledger.info,  Node: Smart dates,  Next: Report intervals,  Prev: Report start & end date,  Up: Time periods
-
-13.2 Smart dates
-================
-
-In hledger's user interfaces (though not in the journal file), you can
-optionally use "smart date" syntax.  Smart dates can be written with
-english words, can be relative, and can have parts omitted.  Missing
-parts are inferred as 1, when needed.  Smart dates can be interpreted as
-dates or periods depending on context.
-
-   Examples:
-
-   '2004-01-01', '2004/10/1', '2004.9.1', '20240504' :
-Exact dates.  The year must have at least four digits, the month must be
-1-12, the day must be 1-31, the separator can be '-' or '/' or '.' or
-nothing.
-
-'2004-10'
-
-     start of month
-'2004'
-
-     start of year
-'10/1' or 'oct' or 'october'
-
-     October 1st in current year
-'21'
-
-     21st day in current month
-'yesterday, today, tomorrow'
-
-     -1, 0, 1 days from today
-'last/this/next day/week/month/quarter/year'
-
-     -1, 0, 1 periods from the current period
-'in n days/weeks/months/quarters/years'
-
-     n periods from the current period
-'n days/weeks/months/quarters/years ahead'
-
-     n periods from the current period
-'n days/weeks/months/quarters/years ago'
-
-     -n periods from the current period
-'20181201'
-
-     8 digit YYYYMMDD with valid year month and day
-'201812'
-
-     6 digit YYYYMM with valid year and month
-
-   Dates with no separators are allowed but might give surprising
-results if mistyped:
-
-   * '20181301' (YYYYMMDD with an invalid month) is parsed as an
-     eight-digit year
-   * '20181232' (YYYYMMDD with an invalid day) gives a parse error
-   * '201801012' (a valid YYYYMMDD followed by additional digits) gives
-     a parse error
-
-   The meaning of relative dates depends on today's date.  If you need
-to test or reproduce old reports, you can use the '--today' option to
-override that.  (Except for periodic transaction rules, which are not
-affected by '--today'.)
-
-
-File: hledger.info,  Node: Report intervals,  Next: Date adjustments,  Prev: Smart dates,  Up: Time periods
-
-13.3 Report intervals
-=====================
-
-A report interval can be specified so that reports like register,
-balance or activity become multi-period, showing each subperiod as a
-separate row or column.
-
-   The following standard intervals can be enabled with command-line
-flags:
-
-   * '-D/--daily'
-   * '-W/--weekly'
-   * '-M/--monthly'
-   * '-Q/--quarterly'
-   * '-Y/--yearly'
-
-   More complex intervals can be specified using '-p/--period',
-described below.
-
-
-File: hledger.info,  Node: Date adjustments,  Next: Period headings,  Prev: Report intervals,  Up: Time periods
-
-13.4 Date adjustments
-=====================
-
-* Menu:
-
-* Start date adjustment::
-* End date adjustment::
-
-
-File: hledger.info,  Node: Start date adjustment,  Next: End date adjustment,  Up: Date adjustments
-
-13.4.1 Start date adjustment
-----------------------------
-
-If you let hledger infer a report's start date, it will adjust the date
-to the previous natural boundary of the report interval, for convenient
-periodic reports.  (If you don't want that, specify a start date.)
-
-   For example, if the journal's first transaction is on january 10th,
-
-   * 'hledger register' (no report interval) will start the report on
-     january 10th.
-   * 'hledger register --monthly' will start the report on the previous
-     month boundary, january 1st.
-   * 'hledger register --monthly --begin 1/5' will start the report on
-     january 5th [1].
-
-   Also if you are generating transactions or budget goals with periodic
-transaction rules, their start date may be adjusted in a similar way (in
-certain situations).
-
-
-File: hledger.info,  Node: End date adjustment,  Prev: Start date adjustment,  Up: Date adjustments
-
-13.4.2 End date adjustment
---------------------------
-
-A report's end date is always adjusted to include a whole number of
-intervals, so that the last subperiod has the same length as the others.
-
-   For example, if the journal's last transaction is on february 20th,
-
-   * 'hledger register' will end the report on february 20th.
-   * 'hledger register --monthly' will end the report at the end of
-     february.
-   * 'hledger register --monthly --end 2/14' also will end the report at
-     the end of february.
-   * 'hledger register --monthly --begin 1/5 --end 2/14' will end the
-     report on march 4th [1].
-
-   [1] Since hledger 1.29.
-
-
-File: hledger.info,  Node: Period headings,  Next: Period expressions,  Prev: Date adjustments,  Up: Time periods
-
-13.5 Period headings
-====================
-
-With non-standard subperiods, hledger will show "STARTDATE..ENDDATE"
-headings.  With standard subperiods (ie, starting on a natural interval
-boundary), you'll see more compact headings, which are usually
-preferable.  (Though month names will be in english, currently.)
-
-   So if you are specifying a start date and you want compact headings:
-choose a start of year for yearly reports, a start of quarter for
-quarterly reports, a start of month for monthly reports, etc.
-(Remember, you can write eg '-b 2024' or '1/1' as a shortcut for a start
-of year, or '2024-04' or '202404' or 'Apr' for a start of month or
-quarter.)
-
-   For weekly reports, choose a date that's a Monday.  (You can try
-different dates until you see the short headings, or write eg '-b '3
-weeks ago''.)
-
-
-File: hledger.info,  Node: Period expressions,  Prev: Period headings,  Up: Time periods
-
-13.6 Period expressions
-=======================
-
-The '-p/--period' option specifies a period expression, which is a
-compact way of expressing a start date, end date, and/or report
-interval.
-
-   Here's a period expression with a start and end date (specifying the
-first quarter of 2009):
-
-'-p "from 2009/1/1 to 2009/4/1"'
-
-   Several keywords like "from" and "to" are supported for readability;
-these are optional.  "to" can also be written as ".."  or "-".  The
-spaces are also optional, as long as you don't run two dates together.
-So the following are equivalent to the above:
-
-'-p "2009/1/1 2009/4/1"'
-'-p2009/1/1to2009/4/1'
-'-p2009/1/1..2009/4/1'
-
-   Dates are smart dates, so if the current year is 2009, these are also
-equivalent to the above:
-
-'-p "1/1 4/1"'
-'-p "jan-apr"'
-'-p "this year to 4/1"'
-
-   If you specify only one date, the missing start or end date will be
-the earliest or latest transaction date in the journal:
-
-'-p "from 2009/1/1"'   everything after january 1, 2009
-'-p "since 2009/1"'    the same, since is a synonym
-'-p "from 2009"'       the same
-'-p "to 2009"'         everything before january 1, 2009
-
-   You can also specify a period by writing a single partial or full
-date:
-
-'-p "2009"'     the year 2009; equivalent to “2009/1/1 to 2010/1/1”
-'-p "2009/1"'   the month of january 2009; equivalent to “2009/1/1 to
-                2009/2/1”
-'-p             the first day of 2009; equivalent to “2009/1/1 to
-"2009/1/1"'     2009/1/2”
-
-   or by using the "Q" quarter-year syntax (case insensitive):
-
-'-p "2009Q1"'    first quarter of 2009, equivalent to “2009/1/1 to
-                 2009/4/1”
-'-p "q4"'        fourth quarter of the current year
-
-* Menu:
-
-* Period expressions with a report interval::
-* More complex report intervals::
-* Multiple weekday intervals::
-
-
-File: hledger.info,  Node: Period expressions with a report interval,  Next: More complex report intervals,  Up: Period expressions
-
-13.6.1 Period expressions with a report interval
-------------------------------------------------
-
-A period expression can also begin with a report interval, separated
-from the start/end dates (if any) by a space or the word 'in':
-
-'-p "weekly from 2009/1/1 to 2009/4/1"'
-'-p "monthly in 2008"'
-'-p "quarterly"'
-
-
-File: hledger.info,  Node: More complex report intervals,  Next: Multiple weekday intervals,  Prev: Period expressions with a report interval,  Up: Period expressions
-
-13.6.2 More complex report intervals
-------------------------------------
-
-Some more complex intervals can be specified within period expressions,
-such as:
-
-   * 'biweekly' (every two weeks)
-   * 'fortnightly'
-   * 'bimonthly' (every two months)
-   * 'every day|week|month|quarter|year'
-   * 'every N days|weeks|months|quarters|years'
-
-   Weekly on a custom day:
-
-   * 'every Nth day of week' ('th', 'nd', 'rd', or 'st' are all accepted
-     after the number)
-   * 'every WEEKDAYNAME' (full or three-letter english weekday name,
-     case insensitive)
-
-   Monthly on a custom day:
-
-   * 'every Nth day [of month]' ('31st day' will be adjusted to each
-     month's last day)
-   * 'every Nth WEEKDAYNAME [of month]'
-
-   Yearly on a custom month and day:
-
-   * 'every MM/DD [of year]' (month number and day of month number)
-   * 'every MONTHNAME DDth [of year]' (full or three-letter english
-     month name, case insensitive, and day of month number)
-   * 'every DDth MONTHNAME [of year]' (equivalent to the above)
-
-   Examples:
-
-'-p "bimonthly from
-2008"'
-'-p "every 2 weeks"'
-'-p "every 5 months from
-2009/03"'
-'-p "every 2nd day of       periods will go from Tue to Tue
-week"'
-'-p "every Tue"'            same
-'-p "every 15th day"'       period boundaries will be on 15th of each
-                            month
-'-p "every 2nd Monday"'     period boundaries will be on second Monday
-                            of each month
-'-p "every 11/05"'          yearly periods with boundaries on 5th of
-                            November
-'-p "every 5th November"'   same
-'-p "every Nov 5th"'        same
-
-   Show historical balances at end of the 15th day of each month (N is
-an end date, exclusive as always):
-
-$ hledger balance -H -p "every 16th day"
-
-   Group postings from the start of wednesday to end of the following
-tuesday (N is both (inclusive) start date and (exclusive) end date):
-
-$ hledger register checking -p "every 3rd day of week"
-
-
-File: hledger.info,  Node: Multiple weekday intervals,  Prev: More complex report intervals,  Up: Period expressions
-
-13.6.3 Multiple weekday intervals
----------------------------------
-
-This special form is also supported:
-
-   * 'every WEEKDAYNAME,WEEKDAYNAME,...' (full or three-letter english
-     weekday names, case insensitive)
-
-   Also, 'weekday' and 'weekendday' are shorthand for
-'mon,tue,wed,thu,fri' and 'sat,sun'.
-
-   This is mainly intended for use with '--forecast', to generate
-periodic transactions on arbitrary days of the week.  It may be less
-useful with '-p', since it divides each week into subperiods of unequal
-length, which is unusual.  (Related: #1632)
-
-   Examples:
-
-'-p "every         dates will be Mon, Wed, Fri; periods will be
-mon,wed,fri"'      Mon-Tue, Wed-Thu, Fri-Sun
-'-p "every         dates will be Mon, Tue, Wed, Thu, Fri; periods will
-weekday"'          be Mon, Tue, Wed, Thu, Fri-Sun
-'-p "every         dates will be Sat, Sun; periods will be Sat, Sun-Fri
-weekendday"'
-
-
-File: hledger.info,  Node: Depth,  Next: Queries,  Prev: Time periods,  Up: Top
-
-14 Depth
-********
-
-With the '--depth NUM' option (short form: '-NUM'), reports will show
-accounts only to the specified depth, hiding deeper subaccounts.  Use
-this when you want a summary with less detail.  This flag has the same
-effect as a 'depth:' query argument: 'depth:2', '--depth=2' or '-2' are
-equivalent.
-
-   In place of a single number which limits the depth for all accounts,
-you can also provide separate depth limits for different accounts using
-regular expressions _(since 1.41)_.
-
-   For example, '--depth assets=2' (or, equivalently: 'depth:assets=2')
-will collapse accounts matching the regular expression 'assets' to depth
-2.  So 'assets:bank:savings' would be collapsed to 'assets:bank', while
-'liabilities:bank:credit card' would not be affected.  This can be
-combined with a flat depth to collapse other accounts not matching the
-regular expression, so '--depth assets=2 --depth 1' would collapse
-'assets:bank:savings' to 'assets:bank' and 'liabilities:bank:credit
-card' to 'liabilities'.
-
-   You can supply multiple depth arguments and they will all be applied,
-so '--depth assets=2 --depth liabilities=3 --depth 1' would collapse:
-
-   * accounts matching 'assets' to depth 2,
-   * accounts matching 'liabilities' to depth 3,
-   * all other accounts to depth 1.
-
-   If an account is matched by more than one regular expression depth
-argument then the more specific one will used.  For example, if '--depth
-assets=1 --depth assets:bank:savings=2' is provided, then
-'assets:bank:savings' will be collapsed to depth 2 rather than depth 1.
-This is because 'assets:bank:savings' matches at level 3 in the account
-name, while 'assets' matches at level 1.  The same would be true with
-the argument '--depth assets=1 --depth savings=2'.
-
-
-File: hledger.info,  Node: Queries,  Next: Pivoting,  Prev: Depth,  Up: Top
-
-15 Queries
-**********
-
-One of hledger's strengths is being able to quickly report on a precise
-subset of your data.  Most hledger commands accept query arguments, to
-restrict their scope.  Multiple query terms can be provided to build up
-a more complex query.
-
-   * By default, a query term is interpreted as a case-insensitive
-     substring pattern for matching account names:
-
-     'car:fuel'
-     'dining groceries'
-
-   * Patterns containing spaces or other special characters must be
-     enclosed in single or double quotes:
-
-     ''personal care''
-
-   * These patterns are actually regular expressions, so you can add
-     regexp metacharacters for more precision (see "Regular expressions"
-     above for details):
-
-     ''^expenses\b''
-     ''food$''
-     ''fuel|repair''
-     ''accounts (payable|receivable)''
-
-   * To match something other than account name, add one of the query
-     type prefixes described in "Query types" below:
-
-     'date:202312-'
-     'status:'
-     'desc:amazon'
-     'cur:USD'
-     'cur:\\$'
-     'amt:'>0''
-
-   * Add a 'not:' prefix to negate a term:
-
-     'not:status:'*''
-     'not:desc:'opening|closing''
-     'not:cur:USD'
-
-   * Terms with different types are AND-ed, terms with the same type are
-     OR-ed (mostly; see "Combining query terms" below).  The following
-     query:
-
-     'date:2022 desc:amazon desc:amzn'
-
-     is interpreted as:
-
-     _date is in 2022 AND ( transaction description contains "amazon" OR
-     "amzn" )_
-
-* Menu:
-
-* Query types::
-* Combining query terms::
-* Queries and command options::
-* Queries and account aliases::
-* Queries and valuation::
-
-
-File: hledger.info,  Node: Query types,  Next: Combining query terms,  Up: Queries
-
-15.1 Query types
-================
-
-Here are the types of query term available.
-
-* Menu:
-
-* acct query::
-* amt query::
-* code query::
-* cur query::
-* desc query::
-* date query::
-* date2 query::
-* depth query::
-* expr query::
-* not query::
-* note query::
-* payee query::
-* real query::
-* status query::
-* type query::
-* tag query::
-
-
-File: hledger.info,  Node: acct query,  Next: amt query,  Up: Query types
-
-15.1.1 acct: query
-------------------
-
-*'acct:REGEX'*, or just *'REGEX'*
-Match account names containing this case insensitive regular expression.
-This is the default query type, so we usually don't bother writing the
-"acct:" prefix.
-
-
-File: hledger.info,  Node: amt query,  Next: code query,  Prev: acct query,  Up: Query types
-
-15.1.2 amt: query
------------------
-
-*'amt:N, amt:'<N', amt:'<=N', amt:'>N', amt:'>=N''*
-Match postings with a single-commodity amount equal to, less than, or
-greater than N. (Postings with multi-commodity amounts are not tested
-and will always match.)  The comparison has two modes: if N is preceded
-by a + or - sign (or is 0), the two signed numbers are compared.
-Otherwise, the absolute magnitudes are compared, ignoring sign.  'amt:'
-needs quotes to hide the less than/greater than sign from the command
-line shell.
-
-
-File: hledger.info,  Node: code query,  Next: cur query,  Prev: amt query,  Up: Query types
-
-15.1.3 code: query
-------------------
-
-*'code:REGEX'*
-Match by transaction code (eg check number).
-
-
-File: hledger.info,  Node: cur query,  Next: desc query,  Prev: code query,  Up: Query types
-
-15.1.4 cur: query
------------------
-
-*'cur:REGEX'*
-Match postings or transactions including any amounts whose
-currency/commodity symbol is fully matched by REGEX. (Contrary to
-hledger's usual infix matching.  To do infix matching, write
-'.*REGEX.*'.)  Note, to match special characters which are
-regex-significant, you need to escape them with '\'.  And for characters
-which are significant to your shell you will usually need one more level
-of escaping.  Eg to match the dollar sign: 'cur:\\$' or 'cur:'\$''
-
-
-File: hledger.info,  Node: desc query,  Next: date query,  Prev: cur query,  Up: Query types
-
-15.1.5 desc: query
-------------------
-
-*'desc:REGEX'*
-Match transaction descriptions.
-
-
-File: hledger.info,  Node: date query,  Next: date2 query,  Prev: desc query,  Up: Query types
-
-15.1.6 date: query
-------------------
-
-*'date:PERIODEXPR'*
-Match dates (or with the '--date2' flag, secondary dates) within the
-specified period.  PERIODEXPR is a period expression with no report
-interval.  Examples:
-'date:2016', 'date:thismonth', 'date:2/1-2/15',
-'date:2021-07-27..nextquarter'.
-
-
-File: hledger.info,  Node: date2 query,  Next: depth query,  Prev: date query,  Up: Query types
-
-15.1.7 date2: query
--------------------
-
-*'date2:PERIODEXPR'*
-If you use secondary dates: this matches secondary dates within the
-specified period.  It is not affected by the '--date2' flag.
-
-
-File: hledger.info,  Node: depth query,  Next: expr query,  Prev: date2 query,  Up: Query types
-
-15.1.8 depth: query
--------------------
-
-*'depth:[REGEXP=]N'*
-Match (or display, depending on command) accounts at or above this
-depth, optionally only for accounts matching a provided regular
-expression.  See Depth for detailed rules.
-
-
-File: hledger.info,  Node: expr query,  Next: not query,  Prev: depth query,  Up: Query types
-
-15.1.9 expr: query
-------------------
-
-*'expr:'QUERYEXPR''*
-'expr' lets you write more complicated query expressions with AND, OR,
-NOT, and parentheses.
-Eg: 'expr:'date:lastmonth and not (food or rent)''
-The expression should be enclosed in quotes.  See Combining query terms
-below.
-
-
-File: hledger.info,  Node: not query,  Next: note query,  Prev: expr query,  Up: Query types
-
-15.1.10 not: query
-------------------
-
-*'not:QUERYTERM'*
-You can prepend *'not:'* to any other query term to negate the match.
-Eg: 'not:equity', 'not:desc:apple'
-(Also, a trick: 'not:not:...' can sometimes solve query problems
-conveniently..)
-
-
-File: hledger.info,  Node: note query,  Next: payee query,  Prev: not query,  Up: Query types
-
-15.1.11 note: query
--------------------
-
-*'note:REGEX'*
-Match transaction notes (the part of the description right of '|', or
-the whole description if there's no '|').
-
-
-File: hledger.info,  Node: payee query,  Next: real query,  Prev: note query,  Up: Query types
-
-15.1.12 payee: query
---------------------
-
-*'payee:REGEX'*
-Match transaction payee/payer names (the part of the description left of
-'|', or the whole description if there's no '|').
-
-
-File: hledger.info,  Node: real query,  Next: status query,  Prev: payee query,  Up: Query types
-
-15.1.13 real: query
--------------------
-
-*'real:, real:0'*
-Match real or virtual postings respectively.
-
-
-File: hledger.info,  Node: status query,  Next: type query,  Prev: real query,  Up: Query types
-
-15.1.14 status: query
----------------------
-
-*'status:, status:!, status:*'*
-Match unmarked, pending, or cleared transactions respectively.
-
-
-File: hledger.info,  Node: type query,  Next: tag query,  Prev: status query,  Up: Query types
-
-15.1.15 type: query
--------------------
-
-*'type:TYPECODES'*
-Match by account type (see Declaring accounts > Account types).
-'TYPECODES' is one or more of the single-letter account type codes
-'ALERXCV', case insensitive.  Note 'type:A' and 'type:E' will also match
-their respective subtypes 'C' (Cash) and 'V' (Conversion).  Certain
-kinds of account alias can disrupt account types, see Rewriting accounts
-> Aliases and account types.
-
-
-File: hledger.info,  Node: tag query,  Prev: type query,  Up: Query types
-
-15.1.16 tag: query
-------------------
-
-*'tag:NAMEREGEX[=VALREGEX]'*
-Match by tag name, and optionally also by tag value.  Note:
-
-   * Both regular expressions do infix matching.  If you need a complete
-     match, use '^' and '$'.
-     Eg: 'tag:'^fullname$'', 'tag:'^fullname$=^fullvalue$'
-   * To match values, ignoring names, do 'tag:.=VALREGEX'
-   * Accounts also inherit the tags of their parent accounts.
-   * Postings also inherit the tags of their account and their
-     transaction .
-   * Transactions also acquire the tags of their postings.
-
-
-File: hledger.info,  Node: Combining query terms,  Next: Queries and command options,  Prev: Query types,  Up: Queries
-
-15.2 Combining query terms
-==========================
-
-When given multiple space-separated query terms, most commands select
-things which match:
-
-   * any of the description terms AND
-   * any of the account terms AND
-   * any of the status terms AND
-   * all the other terms.
-
-   The print command is a little different, showing transactions which:
-
-   * match any of the description terms AND
-   * have any postings matching any of the positive account terms AND
-   * have no postings matching any of the negative account terms AND
-   * match all the other terms.
-
-   We also support more complex boolean queries with the 'expr:' prefix.
-This allows one to combine query terms using 'and', 'or', 'not' keywords
-(case insensitive), and to group them by enclosing in parentheses.
-
-   Some examples:
-
-   * Exclude account names containing 'food':
-
-     'expr:"not food"' ('not:food' is equivalent)
-
-   * Match things which have 'cool' in the description and the 'A' tag:
-
-     'expr:"desc:cool and tag:A"' ('expr:"desc:cool tag:A"' is
-     equivalent)
-
-   * Match things which either do not reference the 'expenses:food'
-     account, or do have the 'A' tag:
-
-     'expr:"not expenses:food or tag:A"'
-
-   * Match things which either do not reference the 'expenses:food'
-     account, or which reference the 'expenses:drink' account and also
-     have the 'A' tag:
-
-     'expr:"expenses:food or (expenses:drink and tag:A)"'
-
-   'expr:' has a restriction: 'date:' queries may not be used inside
-'or' expressions.  That would allow disjoint report periods or disjoint
-result sets, with unclear semantics for our reports.
-
-
-File: hledger.info,  Node: Queries and command options,  Next: Queries and account aliases,  Prev: Combining query terms,  Up: Queries
-
-15.3 Queries and command options
-================================
-
-Some queries can also be expressed as command-line options: 'depth:2' is
-equivalent to '--depth 2', 'date:2023' is equivalent to '-p 2023', etc.
-When you mix command options and query arguments, generally the
-resulting query is their intersection.
-
-
-File: hledger.info,  Node: Queries and account aliases,  Next: Queries and valuation,  Prev: Queries and command options,  Up: Queries
-
-15.4 Queries and account aliases
-================================
-
-When account names are rewritten with '--alias' or 'alias', 'acct:' will
-match either the old or the new account name.
-
-
-File: hledger.info,  Node: Queries and valuation,  Prev: Queries and account aliases,  Up: Queries
-
-15.5 Queries and valuation
-==========================
-
-When amounts are converted to other commodities in cost or value
-reports, 'cur:' and 'amt:' match the old commodity symbol and the old
-amount quantity, not the new ones.  (Except in hledger 1.22, #1625.)
-
-
-File: hledger.info,  Node: Pivoting,  Next: Generating data,  Prev: Queries,  Up: Top
-
-16 Pivoting
-***********
-
-Normally, hledger groups and sums amounts within each account.  The
-'--pivot FIELD' option substitutes some other transaction field for
-account names, causing amounts to be grouped and summed by that field's
-value instead.  FIELD can be any of the transaction fields 'acct',
-'status', 'code', 'desc', 'payee', 'note', or a tag name.  When pivoting
-on a tag and a posting has multiple values of that tag, only the first
-value is displayed.  Values containing 'colon:separated:parts' will be
-displayed hierarchically, like account names.  Multiple, colon-delimited
-fields can be pivoted simultaneously, generating a hierarchical account
-name.
-
-   Some examples:
-
-2016/02/16 Yearly Dues Payment
-    assets:bank account                 2 EUR
-    income:dues                        -2 EUR  ; member: John Doe, kind: Lifetime
-
-   Normal balance report showing account names:
-
-$ hledger balance
-               2 EUR  assets:bank account
-              -2 EUR  income:dues
---------------------
-                   0
-
-   Pivoted balance report, using member: tag values instead:
-
-$ hledger balance --pivot member
-               2 EUR
-              -2 EUR  John Doe
---------------------
-                   0
-
-   One way to show only amounts with a member: value (using a query):
-
-$ hledger balance --pivot member tag:member=.
-              -2 EUR  John Doe
---------------------
-              -2 EUR
-
-   Another way (the acct: query matches against the pivoted "account
-name"):
-
-$ hledger balance --pivot member acct:.
-              -2 EUR  John Doe
---------------------
-              -2 EUR
-
-   Hierarchical reports can be generated with multiple pivots:
-
-$ hledger balance Income:Dues --pivot kind:member
-              -2 EUR  Lifetime:John Doe
---------------------
-              -2 EUR
-
-
-File: hledger.info,  Node: Generating data,  Next: Forecasting,  Prev: Pivoting,  Up: Top
-
-17 Generating data
-******************
-
-hledger can enrich the data provided to it, or generate new data, in a
-number of ways.  Mostly, this is done only if you request it:
-
-   * Missing amounts or missing costs in transactions are inferred
-     automatically when possible.
-   * The '--infer-equity' flag infers missing conversion equity postings
-     from @/@@ costs.
-   * The '--infer-costs' flag infers missing costs from conversion
-     equity postings.
-   * The '--infer-market-prices' flag infers 'P' price directives from
-     costs.
-   * The '--auto' flag adds extra postings to transactions matched by
-     auto posting rules.
-   * The '--forecast' option generates transactions from periodic
-     transaction rules.
-   * The 'balance --budget' report infers budget goals from periodic
-     transaction rules.
-   * Commands like 'close', 'rewrite', and 'hledger-interest' generate
-     transactions or postings.
-   * CSV data is converted to transactions by applying CSV conversion
-     rules..  etc.
-
-   Such generated data is temporary, existing only at report time.  You
-can convert it to permanent recorded data by, eg, capturing the output
-of 'hledger print' and saving it in your journal file.  This can
-sometimes be useful as a data entry aid.
-
-   If you are curious what data is being generated and why, run 'hledger
-print -x --verbose-tags'.  '-x/--explicit' shows inferred amounts and
-'--verbose-tags' adds tags like 'generated-transaction' (from periodic
-rules) and 'generated-posting', 'modified' (from auto posting rules).
-Similar hidden tags (with an underscore prefix) are always present,
-also, so you can always match such data with queries like
-'tag:generated' or 'tag:modified'.
-
-
-File: hledger.info,  Node: Forecasting,  Next: Budgeting,  Prev: Generating data,  Up: Top
-
-18 Forecasting
-**************
-
-Forecasting, or speculative future reporting, can be useful for
-estimating future balances, or for exploring different future scenarios.
-
-   The simplest and most flexible way to do it with hledger is to
-manually record a bunch of future-dated transactions.  You could keep
-these in a separate 'future.journal' and include that with '-f' only
-when you want to see them.
-
-* Menu:
-
-* --forecast::
-* Inspecting forecast transactions::
-* Forecast reports::
-* Forecast tags::
-* Forecast period in detail::
-* Forecast troubleshooting::
-
-
-File: hledger.info,  Node: --forecast,  Next: Inspecting forecast transactions,  Up: Forecasting
-
-18.1 -forecast
-==============
-
-There is another way: with the '--forecast' option, hledger can generate
-temporary "forecast transactions" for reporting purposes, according to
-periodic transaction rules defined in the journal.  Each rule can
-generate multiple recurring transactions, so by changing one rule you
-can change many forecasted transactions.
-
-   Forecast transactions usually start after ordinary transactions end.
-By default, they begin after your latest-dated ordinary transaction, or
-today, whichever is later, and they end six months from today.  (The
-exact rules are a little more complicated, and are given below.)
-
-   This is the "forecast period", which need not be the same as the
-report period.  You can override it - eg to forecast farther into the
-future, or to force forecast transactions to overlap your ordinary
-transactions - by giving the -forecast option a period expression
-argument, like '--forecast=..2099' or '--forecast=2023-02-15..'.  Note
-that the '=' is required.
-
-
-File: hledger.info,  Node: Inspecting forecast transactions,  Next: Forecast reports,  Prev: --forecast,  Up: Forecasting
-
-18.2 Inspecting forecast transactions
-=====================================
-
-'print' is the best command for inspecting and troubleshooting forecast
-transactions.  Eg:
-
-~ monthly from 2022-12-20    rent
-    assets:bank:checking
-    expenses:rent           $1000
-
-$ hledger print --forecast --today=2023/4/21
-2023-05-20 rent
-    ; generated-transaction: ~ monthly from 2022-12-20
-    assets:bank:checking
-    expenses:rent                  $1000
-
-2023-06-20 rent
-    ; generated-transaction: ~ monthly from 2022-12-20
-    assets:bank:checking
-    expenses:rent                  $1000
-
-2023-07-20 rent
-    ; generated-transaction: ~ monthly from 2022-12-20
-    assets:bank:checking
-    expenses:rent                  $1000
-
-2023-08-20 rent
-    ; generated-transaction: ~ monthly from 2022-12-20
-    assets:bank:checking
-    expenses:rent                  $1000
-
-2023-09-20 rent
-    ; generated-transaction: ~ monthly from 2022-12-20
-    assets:bank:checking
-    expenses:rent                  $1000
-
-   Here there are no ordinary transactions, so the forecasted
-transactions begin on the first occurrence after today's date.  (You
-won't normally use '--today'; it's just to make these examples
-reproducible.)
-
-
-File: hledger.info,  Node: Forecast reports,  Next: Forecast tags,  Prev: Inspecting forecast transactions,  Up: Forecasting
-
-18.3 Forecast reports
-=====================
-
-Forecast transactions affect all reports, as you would expect.  Eg:
-
-$ hledger areg rent --forecast --today=2023/4/21
-Transactions in expenses:rent and subaccounts:
-2023-05-20 rent                 as:ba:checking               $1000         $1000
-2023-06-20 rent                 as:ba:checking               $1000         $2000
-2023-07-20 rent                 as:ba:checking               $1000         $3000
-2023-08-20 rent                 as:ba:checking               $1000         $4000
-2023-09-20 rent                 as:ba:checking               $1000         $5000
-
-$ hledger bal -M expenses --forecast --today=2023/4/21
-Balance changes in 2023-05-01..2023-09-30:
-
-               ||   May    Jun    Jul    Aug    Sep 
-===============++===================================
- expenses:rent || $1000  $1000  $1000  $1000  $1000 
----------------++-----------------------------------
-               || $1000  $1000  $1000  $1000  $1000 
-
-
-File: hledger.info,  Node: Forecast tags,  Next: Forecast period in detail,  Prev: Forecast reports,  Up: Forecasting
-
-18.4 Forecast tags
-==================
-
-Forecast transactions generated by -forecast have a hidden tag,
-'_generated-transaction'.  So if you ever need to match forecast
-transactions, you could use 'tag:_generated-transaction' (or just
-'tag:generated') in a query.
-
-   For troubleshooting, you can add the '--verbose-tags' flag.  Then,
-visible 'generated-transaction' tags will be added also, so you can view
-them with the 'print' command.  Their value indicates which periodic
-rule was responsible.
-
-
-File: hledger.info,  Node: Forecast period in detail,  Next: Forecast troubleshooting,  Prev: Forecast tags,  Up: Forecasting
-
-18.5 Forecast period, in detail
-===============================
-
-Forecast start/end dates are chosen so as to do something useful by
-default in almost all situations, while also being flexible.  Here are
-(with luck) the exact rules, to help with troubleshooting:
-
-   The forecast period starts on:
-
-   * the later of
-        * the start date in the periodic transaction rule
-        * the start date in '--forecast''s argument
-
-   * otherwise (if those are not available): the later of
-        * the report start date specified with '-b'/'-p'/'date:'
-        * the day after the latest ordinary transaction in the journal
-
-   * otherwise (if none of these are available): today.
-
-   The forecast period ends on:
-
-   * the earlier of
-        * the end date in the periodic transaction rule
-        * the end date in '--forecast''s argument
-
-   * otherwise: the report end date specified with '-e'/'-p'/'date:'
-   * otherwise: 180 days (~6 months) from today.
-
-
-File: hledger.info,  Node: Forecast troubleshooting,  Prev: Forecast period in detail,  Up: Forecasting
-
-18.6 Forecast troubleshooting
-=============================
-
-When -forecast is not doing what you expect, one of these tips should
-help:
-
-   * Remember to use the '--forecast' option.
-   * Remember to have at least one periodic transaction rule in your
-     journal.
-   * Test with 'print --forecast'.
-   * Check for typos or too-restrictive start/end dates in your periodic
-     transaction rule.
-   * Leave at least 2 spaces between the rule's period expression and
-     description fields.
-   * Check for future-dated ordinary transactions suppressing forecasted
-     transactions.
-   * Try setting explicit report start and/or end dates with '-b', '-e',
-     '-p' or 'date:'
-   * Try adding the '-E' flag to encourage display of empty periods/zero
-     transactions.
-   * Try setting explicit forecast start and/or end dates with
-     '--forecast=START..END'
-   * Consult Forecast period, in detail, above.
-   * Check inside the engine: add '--debug=2' (eg).
-
-
-File: hledger.info,  Node: Budgeting,  Next: Amount formatting,  Prev: Forecasting,  Up: Top
-
-19 Budgeting
-************
-
-With the balance command's '--budget' report, each periodic transaction
-rule generates recurring budget goals in specified accounts, and goals
-and actual performance can be compared.  See the balance command's doc
-below.
-
-   You can generate budget goals and forecast transactions at the same
-time, from the same or different periodic transaction rules: 'hledger
-bal -M --budget --forecast ...'
-
-   See also: Budgeting and Forecasting.
-
-
-File: hledger.info,  Node: Amount formatting,  Next: Cost reporting,  Prev: Budgeting,  Up: Top
-
-20 Amount formatting
-********************
-
-* Menu:
-
-* Commodity display style::
-* Rounding::
-* Trailing decimal marks::
-* Amount parseability::
-
-
-File: hledger.info,  Node: Commodity display style,  Next: Rounding,  Up: Amount formatting
-
-20.1 Commodity display style
-============================
-
-For the amounts in each commodity, hledger chooses a consistent display
-style (symbol placement, decimal mark and digit group marks, number of
-decimal digits) to use in most reports.  This is inferred as follows:
-
-   First, if there's a 'D' directive declaring a default commodity, that
-commodity symbol and amount format is applied to all no-symbol amounts
-in the journal.
-
-   Then each commodity's display style is determined from its
-'commodity' directive.  We recommend always declaring commodities with
-'commodity' directives, since they help ensure consistent display styles
-and precisions, and bring other benefits such as error checking for
-commodity symbols.  Here's an example:
-
-# Set display styles (and decimal marks, for parsing, if there is no decimal-mark directive)
-# for the $, EUR, INR and no-symbol commodities:
-commodity $1,000.00
-commodity EUR 1.000,00
-commodity INR 9,99,99,999.00
-commodity 1 000 000.9455
-
-   But for convenience, if a 'commodity' directive is not present,
-hledger infers a commodity's display styles from its amounts as they are
-written in the journal (excluding cost amounts and amounts in periodic
-transaction rules or auto posting rules).  It uses
-
-   * the symbol placement and decimal mark of the first amount seen
-   * the digit group marks of the first amount with digit group marks
-   * and the maximum number of decimal digits seen across all amounts.
-
-   And as fallback if no applicable amounts are found, it would use a
-default style, like '$1000.00' (symbol on the left with no space, period
-as decimal mark, and two decimal digits).
-
-   Finally, commodity styles can be overridden by the
-'-c/--commodity-style' command line option.
-
-
-File: hledger.info,  Node: Rounding,  Next: Trailing decimal marks,  Prev: Commodity display style,  Up: Amount formatting
-
-20.2 Rounding
-=============
-
-Amounts are stored internally as decimal numbers with up to 255 decimal
-places.  They are displayed with their original journal precisions by
-print and print-like reports, and rounded to their display precision
-(the number of decimal digits specified by the commodity display style)
-by other reports.  When rounding, hledger uses banker's rounding (it
-rounds to the nearest even digit).  So eg 0.5 displayed with zero
-decimal digits appears as "0".
-
-
-File: hledger.info,  Node: Trailing decimal marks,  Next: Amount parseability,  Prev: Rounding,  Up: Amount formatting
-
-20.3 Trailing decimal marks
-===========================
-
-If you're wondering why your 'print' report sometimes shows trailing
-decimal marks, with no decimal digits; it does this when showing amounts
-that have digit group marks but no decimal digits, to disambiguate them
-and allow them to be re-parsed reliably (see Decimal marks).  Eg:
-
-commodity $1,000.00
-
-2023-01-02
-    (a)      $1000
-
-$ hledger print
-2023-01-02
-    (a)        $1,000.
-
-   If this is a problem (eg when exporting to Ledger), you can avoid it
-by disabling digit group marks, eg with -c/-commodity (for each affected
-commodity):
-
-$ hledger print -c '$1000.00'
-2023-01-02
-    (a)          $1000
-
-   or by forcing print to always show decimal digits, with -round:
-
-$ hledger print -c '$1,000.00' --round=soft
-2023-01-02
-    (a)      $1,000.00
-
-
-File: hledger.info,  Node: Amount parseability,  Prev: Trailing decimal marks,  Up: Amount formatting
-
-20.4 Amount parseability
-========================
-
-More generally, hledger output falls into three rough categories, which
-format amounts a little bit differently to suit different consumers:
-
-   *1.  "hledger-readable output" - should be readable by hledger (and
-by humans)*
-
-   * This is produced by reports that show full journal entries:
-     'print', 'import', 'close', 'rewrite' etc.
-   * It shows amounts with their original journal precisions, which may
-     not be consistent.
-   * It adds a trailing decimal mark when needed to avoid showing
-     ambiguous amounts.
-   * It can be parsed reliably (by hledger and ledger2beancount at
-     least, but perhaps not by Ledger..)
-
-   *2.  "human-readable output" - usually for humans*
-
-   * This is produced by all other reports.
-   * It shows amounts with standard display precisions, which will be
-     consistent within each commodity.
-   * It shows ambiguous amounts unmodified.
-   * It can be parsed reliably in the context of a known report (when
-     you know decimals are consistently not being shown, you can assume
-     a single mark is a digit group mark).
-
-   *3.  "machine-readable output" - usually for other software*
-
-   * This is produced by all reports when an output format like 'csv',
-     'tsv', 'json', or 'sql' is selected.
-   * It shows amounts as 1 or 2 do, but without digit group marks.
-   * It can be parsed reliably (if needed, the decimal mark can be
-     changed with -c/-commodity-style).
-
-
-File: hledger.info,  Node: Cost reporting,  Next: Value reporting,  Prev: Amount formatting,  Up: Top
-
-21 Cost reporting
-*****************
-
-In some transactions - for example a currency conversion, or a purchase
-or sale of stock - one commodity is exchanged for another.  In these
-transactions there is a conversion rate, also called the cost (when
-buying) or selling price (when selling).  In hledger docs we just say
-"cost", for convenience; feel free to mentally translate to "conversion
-rate" or "selling price" if helpful.
-
-* Menu:
-
-* Recording costs::
-* Reporting at cost::
-* Equity conversion postings::
-* Inferring equity conversion postings::
-* Combining costs and equity conversion postings::
-* Requirements for detecting equity conversion postings::
-* Infer cost and equity by default ?::
-
-
-File: hledger.info,  Node: Recording costs,  Next: Reporting at cost,  Up: Cost reporting
-
-21.1 Recording costs
-====================
-
-We'll explore several ways of recording transactions involving costs.
-These are also summarised at hledger Cookbook > Cost notation.
-
-   Costs can be recorded explicitly in the journal, using the '@
-UNITCOST' or '@@ TOTALCOST' notation described in Journal > Costs:
-
-   *Variant 1*
-
-2022-01-01
-  assets:dollars    $-135
-  assets:euros       €100 @ $1.35   ; $1.35 per euro (unit cost)
-
-   *Variant 2*
-
-2022-01-01
-  assets:dollars    $-135
-  assets:euros       €100 @@ $135   ; $135 total cost
-
-   Typically, writing the unit cost (variant 1) is preferable; it can be
-more effort, requiring more attention to decimal digits; but it reveals
-the per-unit cost basis, and makes stock sales easier.
-
-   Costs can also be left implicit, and hledger will infer the cost that
-is consistent with a balanced transaction:
-
-   *Variant 3*
-
-2022-01-01
-  assets:dollars    $-135
-  assets:euros       €100
-
-   Here, hledger will attach a '@@ €100' cost to the first amount (you
-can see it with 'hledger print -x').  This form looks convenient, but
-there are downsides:
-
-   * It sacrifices some error checking.  For example, if you
-     accidentally wrote €10 instead of €100, hledger would not be able
-     to detect the mistake.
-
-   * It is sensitive to the order of postings - if they were reversed, a
-     different entry would be inferred and reports would be different.
-
-   * The per-unit cost basis is not easy to read.
-
-   So generally this kind of entry is not recommended.  You can make
-sure you have none of these by using '-s' (strict mode), or by running
-'hledger check balanced'.
-
-
-File: hledger.info,  Node: Reporting at cost,  Next: Equity conversion postings,  Prev: Recording costs,  Up: Cost reporting
-
-21.2 Reporting at cost
-======================
-
-Now when you add the '-B'/'--cost' flag to reports ("B" is from Ledger's
--B/-basis/-cost flag), any amounts which have been annotated with costs
-will be converted to their cost's commodity (in the report output).  Ie
-they will be displayed "at cost" or "at sale price".
-
-   Some things to note:
-
-   * Costs are attached to specific posting amounts in specific
-     transactions, and once recorded they do not change.  This contrasts
-     with market prices, which are ambient and fluctuating.
-
-   * Conversion to cost is performed before conversion to market value
-     (described below).
-
-
-File: hledger.info,  Node: Equity conversion postings,  Next: Inferring equity conversion postings,  Prev: Reporting at cost,  Up: Cost reporting
-
-21.3 Equity conversion postings
-===============================
-
-There is a problem with the entries above - they are not conventional
-Double Entry Bookkeeping (DEB) notation, and because of the "magical"
-transformation of one commodity into another, they cause an imbalance in
-the Accounting Equation.  This shows up as a non-zero grand total in
-balance reports like 'hledger bse'.
-
-   For most hledger users, this doesn't matter in practice and can
-safely be ignored !  But if you'd like to learn more, keep reading.
-
-   Conventional DEB uses an extra pair of equity postings to balance the
-transaction.  Of course you can do this in hledger as well:
-
-   *Variant 4*
-
-2022-01-01
-    assets:dollars      $-135
-    assets:euros         €100
-    equity:conversion    $135
-    equity:conversion   €-100
-
-   Now the transaction is perfectly balanced according to standard DEB,
-and 'hledger bse''s total will not be disrupted.
-
-   And, hledger can still infer the cost for cost reporting, but it's
-not done by default - you must add the '--infer-costs' flag like so:
-
-$ hledger print --infer-costs
-2022-01-01 one hundred euros purchased at $1.35 each
-    assets:dollars       $-135 @@ €100
-    assets:euros                  €100
-    equity:conversion             $135
-    equity:conversion            €-100
-
-$ hledger bal --infer-costs -B
-               €-100  assets:dollars                                                                                                                                              
-                €100  assets:euros                                                                                                                                                
---------------------                                                                                                                                                              
-                   0                                                                                                                                                              
-
-   Here are some downsides of this kind of entry:
-
-   * The per-unit cost basis is not easy to read.
-
-   * Instead of '-B' you must remember to type '-B --infer-costs'.
-
-   * '--infer-costs' works only where hledger can identify the two
-     equity:conversion postings and match them up with the two
-     non-equity postings.  So writing the journal entry in a particular
-     format becomes more important.  More on this below.
-
-
-File: hledger.info,  Node: Inferring equity conversion postings,  Next: Combining costs and equity conversion postings,  Prev: Equity conversion postings,  Up: Cost reporting
-
-21.4 Inferring equity conversion postings
-=========================================
-
-Can we go in the other direction ?  Yes, if you have transactions
-written with the @/@@ cost notation, hledger can infer the missing
-equity postings, if you add the '--infer-equity' flag.  Eg:
-
-2022-01-01
-  assets:dollars  -$135
-  assets:euros     €100 @ $1.35
-
-$ hledger print --infer-equity
-2022-01-01
-    assets:dollars                    $-135
-    assets:euros               €100 @ $1.35
-    equity:conversion:$-€:€           €-100
-    equity:conversion:$-€:$         $135.00
-
-   The equity account names will be "equity:conversion:A-B:A" and
-"equity:conversion:A-B:B" where A is the alphabetically first commodity
-symbol.  You can customise the "equity:conversion" part by declaring an
-account with the 'V'/'Conversion' account type.
-
-   Note you will need to add account declarations for these to your
-journal, if you use 'check accounts' or 'check --strict'.
-
-
-File: hledger.info,  Node: Combining costs and equity conversion postings,  Next: Requirements for detecting equity conversion postings,  Prev: Inferring equity conversion postings,  Up: Cost reporting
-
-21.5 Combining costs and equity conversion postings
-===================================================
-
-Finally, you can use both the @/@@ cost notation and equity postings at
-the same time.  This in theory gives the best of all worlds - preserving
-the accounting equation, revealing the per-unit cost basis, and
-providing more flexibility in how you write the entry:
-
-   *Variant 5*
-
-2022-01-01 one hundred euros purchased at $1.35 each
-    assets:dollars      $-135
-    equity:conversion    $135
-    equity:conversion   €-100
-    assets:euros         €100 @ $1.35
-
-   All the other variants above can (usually) be rewritten to this final
-form with:
-
-$ hledger print -x --infer-costs --infer-equity
-
-   Downsides:
-
-   * The precise format of the journal entry becomes more important.  If
-     hledger can't detect and match up the cost and equity postings, it
-     will give a transaction balancing error.
-
-   * The add command does not yet accept this kind of entry (#2056).
-
-   * This is the most verbose form.
-
-
-File: hledger.info,  Node: Requirements for detecting equity conversion postings,  Next: Infer cost and equity by default ?,  Prev: Combining costs and equity conversion postings,  Up: Cost reporting
-
-21.6 Requirements for detecting equity conversion postings
-==========================================================
-
-'--infer-costs' has certain requirements (unlike '--infer-equity', which
-always works).  It will infer costs only in transactions with:
-
-   * Two non-equity postings, in different commodities.  Their order is
-     significant: the cost will be added to the first of them.
-
-   * Two postings to equity conversion accounts, next to one another,
-     which balance the two non-equity postings.  This balancing is
-     checked to the same precision (number of decimal places) used in
-     the conversion posting's amount.  Equity conversion accounts are:
-
-        * any accounts declared with account type 'V'/'Conversion', or
-          their subaccounts
-        * otherwise, accounts named 'equity:conversion', 'equity:trade',
-          or 'equity:trading', or their subaccounts.
-
-   And multiple such four-posting groups can coexist within a single
-transaction.  When '--infer-costs' fails, it does not infer a cost in
-that transaction, and does not raise an error (ie, it infers costs where
-it can).
-
-   Reading variant 5 journal entries, combining cost notation and equity
-postings, has all the same requirements.  When reading such an entry
-fails, hledger raises an "unbalanced transaction" error.
-
-
-File: hledger.info,  Node: Infer cost and equity by default ?,  Prev: Requirements for detecting equity conversion postings,  Up: Cost reporting
-
-21.7 Infer cost and equity by default ?
-=======================================
-
-Should '--infer-costs' and '--infer-equity' be enabled by default ?  Try
-using them always, eg with a shell alias:
-
-alias h="hledger --infer-equity --infer-costs"
-
-   and let us know what problems you find.
-
-
-File: hledger.info,  Node: Value reporting,  Next: PART 4 COMMANDS,  Prev: Cost reporting,  Up: Top
-
-22 Value reporting
-******************
-
-Instead of reporting amounts in their original commodity, hledger can
-convert them to cost/sale amount (using the conversion rate recorded in
-the transaction), and/or to market value (using some market price on a
-certain date).  This is controlled by the '--value=TYPE[,COMMODITY]'
-option, which will be described below.  We also provide the simpler '-V'
-and '-X COMMODITY' options, and often one of these is all you need:
-
-* Menu:
-
-* -V Value::
-* -X Value in specified commodity::
-* Valuation date::
-* Finding market price::
-* --infer-market-prices market prices from transactions::
-* Valuation commodity::
-* --value Flexible valuation::
-* Valuation examples::
-* Interaction of valuation and queries::
-* Effect of valuation on reports::
-
-
-File: hledger.info,  Node: -V Value,  Next: -X Value in specified commodity,  Up: Value reporting
-
-22.1 -V: Value
-==============
-
-The '-V/--market' flag converts amounts to market value in their default
-_valuation commodity_, using the market prices in effect on the
-_valuation date(s)_, if any.  More on these in a minute.
-
-
-File: hledger.info,  Node: -X Value in specified commodity,  Next: Valuation date,  Prev: -V Value,  Up: Value reporting
-
-22.2 -X: Value in specified commodity
-=====================================
-
-The '-X/--exchange=COMM' option is like '-V', except you tell it which
-currency you want to convert to, and it tries to convert everything to
-that.
-
-
-File: hledger.info,  Node: Valuation date,  Next: Finding market price,  Prev: -X Value in specified commodity,  Up: Value reporting
-
-22.3 Valuation date
-===================
-
-Market prices can change from day to day.  hledger will use the prices
-on a particular valuation date (or on more than one date).  By default
-hledger uses "end" dates for valuation.  More specifically:
-
-   * For single period reports (including normal print and register
-     reports):
-        * If an explicit report end date is specified, that is used
-        * Otherwise the latest transaction date or P directive date is
-          used (even if it's in the future)
-
-   * For multiperiod reports, each period is valued on its last day.
-
-   This can be customised with the -value option described below, which
-can select either "then", "end", "now", or "custom" dates.  (Note, this
-has a bug in hledger-ui <=1.31: turning on valuation with the 'V' key
-always resets it to "end".)
-
-
-File: hledger.info,  Node: Finding market price,  Next: --infer-market-prices market prices from transactions,  Prev: Valuation date,  Up: Value reporting
-
-22.4 Finding market price
-=========================
-
-To convert a commodity A to its market value in another commodity B,
-hledger looks for a suitable market price (exchange rate) as follows, in
-this order of preference:
-
-  1. A _declared market price_ or _inferred market price_: A's latest
-     market price in B on or before the valuation date as declared by a
-     P directive, or (with the '--infer-market-prices' flag) inferred
-     from costs.
-
-  2. A _reverse market price_: the inverse of a declared or inferred
-     market price from B to A.
-
-  3. A _forward chain of market prices_: a synthetic price formed by
-     combining the shortest chain of "forward" (only 1 above) market
-     prices, leading from A to B.
-
-  4. _Any chain of market prices_: a chain of any market prices,
-     including both forward and reverse prices (1 and 2 above), leading
-     from A to B.
-
-   There is a limit to the length of these price chains; if hledger
-reaches that length without finding a complete chain or exhausting all
-possibilities, it will give up (with a "gave up" message visible in
-'--debug=2' output).  That limit is currently 1000.
-
-   Amounts for which no suitable market price can be found, are not
-converted.
-
-
-File: hledger.info,  Node: --infer-market-prices market prices from transactions,  Next: Valuation commodity,  Prev: Finding market price,  Up: Value reporting
-
-22.5 -infer-market-prices: market prices from transactions
-==========================================================
-
-Normally, market value in hledger is fully controlled by, and requires,
-P directives in your journal.  Since adding and updating those can be a
-chore, and since transactions usually take place at close to market
-value, why not use the recorded costs as additional market prices (as
-Ledger does) ?  Adding the '--infer-market-prices' flag to '-V', '-X' or
-'--value' enables this.
-
-   So for example, 'hledger bs -V --infer-market-prices' will get market
-prices both from P directives and from transactions.  If both occur on
-the same day, the P directive takes precedence.
-
-   There is a downside: value reports can sometimes be affected in
-confusing/undesired ways by your journal entries.  If this happens to
-you, read all of this Value reporting section carefully, and try adding
-'--debug' or '--debug=2' to troubleshoot.
-
-   '--infer-market-prices' can infer market prices from:
-
-   * multicommodity transactions with explicit prices ('@'/'@@')
-
-   * multicommodity transactions with implicit prices (no '@', two
-     commodities, unbalanced).  (With these, the order of postings
-     matters.  'hledger print -x' can be useful for troubleshooting.)
-
-   * multicommodity transactions with equity postings, if cost is
-     inferred with '--infer-costs'.
-
-   There is a limitation (bug) currently: when a valuation commodity is
-not specified, prices inferred with '--infer-market-prices' do not help
-select a default valuation commodity, as 'P' prices would.  So
-conversion might not happen because no valuation commodity was detected
-('--debug=2' will show this).  To be safe, specify the valuation
-commmodity, eg:
-
-   * '-X EUR --infer-market-prices', not '-V --infer-market-prices'
-   * '--value=then,EUR --infer-market-prices', not '--value=then
-     --infer-market-prices'
-
-   Signed costs and market prices can be confusing.  For reference, here
-is the current behaviour, since hledger 1.25.  (If you think it should
-work differently, see #1870.)
-
-2022-01-01 Positive Unit prices
-    a        A 1
-    b        B -1 @ A 1
-
-2022-01-01 Positive Total prices
-    a        A 1
-    b        B -1 @@ A 1
-
-
-2022-01-02 Negative unit prices
-    a        A 1
-    b        B 1 @ A -1
-
-2022-01-02 Negative total prices
-    a        A 1
-    b        B 1 @@ A -1
-
-
-2022-01-03 Double Negative unit prices
-    a        A -1
-    b        B -1 @ A -1
-
-2022-01-03 Double Negative total prices
-    a        A -1
-    b        B -1 @@ A -1
-
-   All of the transactions above are considered balanced (and on each
-day, the two transactions are considered equivalent).  Here are the
-market prices inferred for B:
-
-$ hledger -f- --infer-market-prices prices
-P 2022-01-01 B A 1
-P 2022-01-01 B A 1.0
-P 2022-01-02 B A -1
-P 2022-01-02 B A -1.0
-P 2022-01-03 B A -1
-P 2022-01-03 B A -1.0
-
-
-File: hledger.info,  Node: Valuation commodity,  Next: --value Flexible valuation,  Prev: --infer-market-prices market prices from transactions,  Up: Value reporting
-
-22.6 Valuation commodity
-========================
-
-*When you specify a valuation commodity ('-X COMM' or '--value
-TYPE,COMM'):*
-hledger will convert all amounts to COMM, wherever it can find a
-suitable market price (including by reversing or chaining prices).
-
-   *When you leave the valuation commodity unspecified ('-V' or '--value
-TYPE'):*
-For each commodity A, hledger picks a default valuation commodity as
-follows, in this order of preference:
-
-  1. The price commodity from the latest P-declared market price for A
-     on or before valuation date.
-
-  2. The price commodity from the latest P-declared market price for A
-     on any date.  (Allows conversion to proceed when there are inferred
-     prices before the valuation date.)
-
-  3. If there are no P directives at all (any commodity or date) and the
-     '--infer-market-prices' flag is used: the price commodity from the
-     latest transaction-inferred price for A on or before valuation
-     date.
-
-   This means:
-
-   * If you have P directives, they determine which commodities '-V'
-     will convert, and to what.
-
-   * If you have no P directives, and use the '--infer-market-prices'
-     flag, costs determine it.
-
-   Amounts for which no valuation commodity can be found are not
-converted.
-
-
-File: hledger.info,  Node: --value Flexible valuation,  Next: Valuation examples,  Prev: Valuation commodity,  Up: Value reporting
-
-22.7 -value: Flexible valuation
-===============================
-
-'-V' and '-X' are special cases of the more general '--value' option:
-
- --value=TYPE[,COMM]  TYPE is then, end, now or YYYY-MM-DD.
-                      COMM is an optional commodity symbol.
-                      Shows amounts converted to:
-                      - default valuation commodity (or COMM) using market prices at posting dates
-                      - default valuation commodity (or COMM) using market prices at period end(s)
-                      - default valuation commodity (or COMM) using current market prices
-                      - default valuation commodity (or COMM) using market prices at some date
-
-   The TYPE part selects cost or value and valuation date:
-
-'--value=then'
-
-     Convert amounts to their value in the default valuation commodity,
-     using market prices on each posting's date.
-'--value=end'
-
-     Convert amounts to their value in the default valuation commodity,
-     using market prices on the last day of the report period (or if
-     unspecified, the journal's end date); or in multiperiod reports,
-     market prices on the last day of each subperiod.
-'--value=now'
-
-     Convert amounts to their value in the default valuation commodity
-     using current market prices (as of when report is generated).
-'--value=YYYY-MM-DD'
-
-     Convert amounts to their value in the default valuation commodity
-     using market prices on this date.
-
-   To select a different valuation commodity, add the optional ',COMM'
-part: a comma, then the target commodity's symbol.  Eg:
-*'--value=now,EUR'*.  hledger will do its best to convert amounts to
-this commodity, deducing market prices as described above.
-
-
-File: hledger.info,  Node: Valuation examples,  Next: Interaction of valuation and queries,  Prev: --value Flexible valuation,  Up: Value reporting
-
-22.8 Valuation examples
-=======================
-
-Here are some quick examples of '-V':
-
-; one euro is worth this many dollars from nov 1
-P 2016/11/01 € $1.10
-
-; purchase some euros on nov 3
-2016/11/3
-    assets:euros        €100
-    assets:checking
-
-; the euro is worth fewer dollars by dec 21
-P 2016/12/21 € $1.03
-
-   How many euros do I have ?
-
-$ hledger -f t.j bal -N euros
-                €100  assets:euros
-
-   What are they worth at end of nov 3 ?
-
-$ hledger -f t.j bal -N euros -V -e 2016/11/4
-             $110.00  assets:euros
-
-   What are they worth after 2016/12/21 ?  (no report end date
-specified, defaults to today)
-
-$ hledger -f t.j bal -N euros -V
-             $103.00  assets:euros
-
-   Here are some examples showing the effect of '--value', as seen with
-'print':
-
-P 2000-01-01 A  1 B
-P 2000-02-01 A  2 B
-P 2000-03-01 A  3 B
-P 2000-04-01 A  4 B
-
-2000-01-01
-  (a)      1 A @ 5 B
-
-2000-02-01
-  (a)      1 A @ 6 B
-
-2000-03-01
-  (a)      1 A @ 7 B
-
-   Show the cost of each posting:
-
-$ hledger -f- print --cost
-2000-01-01
-    (a)             5 B
-
-2000-02-01
-    (a)             6 B
-
-2000-03-01
-    (a)             7 B
-
-   Show the value as of the last day of the report period (2000-02-29):
-
-$ hledger -f- print --value=end date:2000/01-2000/03
-2000-01-01
-    (a)             2 B
-
-2000-02-01
-    (a)             2 B
-
-   With no report period specified, that shows the value as of the last
-day of the journal (2000-03-01):
-
-$ hledger -f- print --value=end
-2000-01-01
-    (a)             3 B
-
-2000-02-01
-    (a)             3 B
-
-2000-03-01
-    (a)             3 B
-
-   Show the current value (the 2000-04-01 price is still in effect
-today):
-
-$ hledger -f- print --value=now
-2000-01-01
-    (a)             4 B
-
-2000-02-01
-    (a)             4 B
-
-2000-03-01
-    (a)             4 B
-
-   Show the value on 2000/01/15:
-
-$ hledger -f- print --value=2000-01-15
-2000-01-01
-    (a)             1 B
-
-2000-02-01
-    (a)             1 B
-
-2000-03-01
-    (a)             1 B
-
-
-File: hledger.info,  Node: Interaction of valuation and queries,  Next: Effect of valuation on reports,  Prev: Valuation examples,  Up: Value reporting
-
-22.9 Interaction of valuation and queries
-=========================================
-
-When matching postings based on queries in the presence of valuation,
-the following happens:
-
-  1. The query is separated into two parts:
-       1. the currency ('cur:') or amount ('amt:').
-       2. all other parts.
-
-  2. The postings are matched to the currency and amount queries based
-     on pre-valued amounts.
-  3. Valuation is applied to the postings.
-  4. The postings are matched to the other parts of the query based on
-     post-valued amounts.
-
-   Related: #1625
-
-
-File: hledger.info,  Node: Effect of valuation on reports,  Prev: Interaction of valuation and queries,  Up: Value reporting
-
-22.10 Effect of valuation on reports
-====================================
-
-Here is a reference for how valuation is supposed to affect each part of
-hledger's reports.  (It's wide, you may need to scroll sideways.)  It
-may be useful when troubleshooting.  If you find problems, please report
-them, ideally with a reproducible example.  Related: #329, #1083.
-
-   First, a quick glossary:
-
-_cost_
-
-     calculated using price(s) recorded in the transaction(s).
-_value_
-
-     market value using available market price declarations, or the
-     unchanged amount if no conversion rate can be found.
-_report start_
-
-     the first day of the report period specified with -b or -p or
-     date:, otherwise today.
-_report or journal start_
-
-     the first day of the report period specified with -b or -p or
-     date:, otherwise the earliest transaction date in the journal,
-     otherwise today.
-_report end_
-
-     the last day of the report period specified with -e or -p or date:,
-     otherwise today.
-_report or journal end_
-
-     the last day of the report period specified with -e or -p or date:,
-     otherwise the latest transaction date in the journal, otherwise
-     today.
-_report interval_
-
-     a flag (-D/-W/-M/-Q/-Y) or period expression that activates the
-     report's multi-period mode (whether showing one or many
-     subperiods).
-
-Report     '-B',        '-V', '-X'   '--value=then'     '--value=end''--value=DATE',
-type       '--cost'                                                  '--value=now'
-------------------------------------------------------------------------------
-*print*
-posting    cost         value at     value at posting   value at     value
-amounts                 report end   date               report or    at
-                        or today                        journal      DATE/today
-                                                        end
-balance    unchanged    unchanged    unchanged          unchanged    unchanged
-assertions/assignments
-*register*
-starting   cost         value at     valued at day      value at     value
-balance                 report or    each historical    report or    at
-(-H)                    journal      posting was made   journal      DATE/today
-                        end                             end
-starting   cost         value at     valued at day      value at     value
-balance                 day before   each historical    day before   at
-(-H)                    report or    posting was made   report or    DATE/today
-with                    journal                         journal
-report                  start                           start
-interval
-posting    cost         value at     value at posting   value at     value
-amounts                 report or    date               report or    at
-                        journal                         journal      DATE/today
-                        end                             end
-summary    summarised   value at     sum of postings    value at     value
-posting    cost         period       in interval,       period       at
-amounts                 ends         valued at          ends         DATE/today
-with                                 interval start
-report
-interval
-running    sum/average  sum/average  sum/average of     sum/average  sum/average
-total/averageof         of           displayed values   of           of
-           displayed    displayed                       displayed    displayed
-           values       values                          values       values
-*balance
-(bs,
-bse, cf,
-is)*
-balance    sums of      value at     value at posting   value at     value
-changes    costs        report end   date               report or    at
-                        or today                        journal      DATE/today
-                        of sums of                      end of       of
-                        postings                        sums of      sums
-                                                        postings     of
-                                                                     postings
-budget     like         like         like balance       like         like
-amounts    balance      balance      changes            balances     balance
-(-budget)  changes      changes                                      changes
-grand      sum of       sum of       sum of displayed   sum of       sum of
-total      displayed    displayed    valued             displayed    displayed
-           values       values                          values       values
-*balance
-(bs,
-bse, cf,
-is) with
-report
-interval*
-starting   sums of      value at     sums of values     value at     sums
-balances   costs of     report       of postings        report       of
-(-H)       postings     start of     before report      start of     postings
-           before       sums of      start at           sums of      before
-           report       all          respective         all          report
-           start        postings     posting dates      postings     start
-                        before                          before
-                        report                          report
-                        start                           start
-balance    sums of      same as      sums of values     balance      value
-changes    costs of     -value=end   of postings in     change in    at
-(bal,      postings                  period at          each         DATE/today
-is, bs     in period                 respective         period,      of
--change,                             posting dates      valued at    sums
-cf                                                      period       of
--change)                                                ends         postings
-end        sums of      same as      sums of values     period end   value
-balances   costs of     -value=end   of postings from   balances,    at
-(bal -H,   postings                  before period      valued at    DATE/today
-is -H,     from                      start to period    period       of
-bs, cf)    before                    end at             ends         sums
-           report                    respective                      of
-           start to                  posting dates                   postings
-           period end
-budget     like         like         like balance       like         like
-amounts    balance      balance      changes/end        balances     balance
-(-budget)  changes/end  changes/end  balances                        changes/end
-           balances     balances                                     balances
-row        sums,        sums,        sums, averages     sums,        sums,
-totals,    averages     averages     of displayed       averages     averages
-row        of           of           values             of           of
-averages   displayed    displayed                       displayed    displayed
-(-T, -A)   values       values                          values       values
-column     sums of      sums of      sums of            sums of      sums
-totals     displayed    displayed    displayed values   displayed    of
-           values       values                          values       displayed
-                                                                     values
-grand      sum,         sum,         sum, average of    sum,         sum,
-total,     average of   average of   column totals      average of   average
-grand      column       column                          column       of
-average    totals       totals                          totals       column
-                                                                     totals
-
-   '--cumulative' is omitted to save space, it works like '-H' but with
-a zero starting balance.
-
-
-File: hledger.info,  Node: PART 4 COMMANDS,  Next: Help commands,  Prev: Value reporting,  Up: Top
-
-23 PART 4: COMMANDS
-*******************
-
-Here are the standard commands, which you can list by running 'hledger'.
-If you have installed more add-on commands, they also will be listed.
-
-   *Help commands*
-
-   * help - show the hledger manual with info/man/pager
-   * demo - show small hledger demos in the terminal
-
-   *User interface commands*
-
-   * ui - (if installed) run hledger's terminal UI
-   * web - (if installed) run hledger's web UI
-
-   *Data entry commands*
-
-   * add - add transactions using terminal prompts
-   * import - add new transactions from other files, eg CSV files
-
-   *Basic report commands*
-
-   * accounts - show account names
-   * codes - show transaction codes
-   * commodities - show commodity/currency symbols
-   * descriptions - show transaction descriptions
-   * files - show input file paths
-   * notes - show note parts of transaction descriptions
-   * payees - show payee parts of transaction descriptions
-   * prices - show market prices
-   * stats - show journal statistics
-   * tags - show tag names
-
-   *Standard report commands*
-
-   * print - show transactions or export journal data
-   * aregister (areg) - show transactions in a particular account
-   * register (reg) - show postings in one or more accounts & running
-     total
-   * balancesheet (bs) - show assets, liabilities and net worth
-   * balancesheetequity (bse) - show assets, liabilities and equity
-   * cashflow (cf) - show changes in liquid assets
-   * incomestatement (is) - show revenues and expenses
-
-   *Advanced report commands*
-
-   * balance (bal) - show balance changes, end balances, budgets,
-     gains..
-   * roi - show return on investments
-
-   *Chart commands*
-
-   * activity - show bar charts of posting counts per period
-
-   *Data generation commands*
-
-   * close - generate balance-zeroing/restoring transactions
-   * rewrite - generate auto postings, like print -auto
-
-   *Maintenance commands*
-
-   * check - check for various kinds of error in the data
-   * diff - compare account transactions in two journal files
-   * test - run self tests
-
-   Next, these commands are described in detail.
-
-
-File: hledger.info,  Node: Help commands,  Next: User interface commands,  Prev: PART 4 COMMANDS,  Up: Top
-
-24 Help commands
-****************
-
-* Menu:
-
-* help::
-* demo::
-
-
-File: hledger.info,  Node: help,  Next: demo,  Up: Help commands
-
-24.1 help
-=========
-
-Show the hledger user manual with 'info', 'man', or a pager.  With a
-(case insensitive) TOPIC argument, try to open it at that section
-heading.
-
-Flags:
-  -i                       show the manual with info
-  -m                       show the manual with man
-  -p                       show the manual with $PAGER or less
-                           (less is always used if TOPIC is specified)
-
-   This command shows the hledger manual built in to your hledger
-executable.  It can be useful when offline, or when you prefer the
-terminal to a web browser, or when the appropriate hledger manual or
-viewers are not installed properly on your system.
-
-   By default it chooses the best viewer found in $PATH, trying in this
-order: 'info', 'man', '$PAGER', 'less', 'more', stdout.  (If a TOPIC is
-specified, '$PAGER' and 'more' are not tried.)  You can force the use of
-info, man, or a pager with the '-i', '-m', or '-p' flags.  If no viewer
-can be found, or if running non-interactively, it just prints the manual
-to stdout.
-
-   When using 'info', TOPIC can match either the full heading or a
-prefix.  If your 'info --version' is < 6, you'll need to upgrade it, eg
-with ''brew install texinfo'' on mac.
-
-   When using 'man' or 'less', TOPIC must match the full heading.  For a
-prefix match, you can write ''TOPIC.*''.
-
-   Examples
-
-$ hledger help -h                 # show the help command's usage
-$ hledger help                    # show the manual with info, man or $PAGER
-$ hledger help 'time periods'     # show the manual's "Time periods" topic
-$ hledger help 'time periods' -m  # use man, even if info is installed
-
-
-File: hledger.info,  Node: demo,  Prev: help,  Up: Help commands
-
-24.2 demo
-=========
-
-Play demos of hledger usage in the terminal, if asciinema is installed.
-
-Flags:
-  -s --speed=SPEED         playback speed (1 is original speed, .5 is half, 2
-                           is double, etc (default: 2))
-
-   Run this command with no argument to list the demos.  To play a demo,
-write its number or a prefix or substring of its title.  Tips:
-
-   Make your terminal window large enough to see the demo clearly.
-
-   Use the -s/-speed SPEED option to set your preferred playback speed,
-eg '-s4' to play at 4x original speed or '-s.5' to play at half speed.
-The default speed is 2x.
-
-   Other asciinema options can be added following a double dash, eg '--
--i.1' to limit pauses or '-- -h' to list asciinema's other options.
-
-   During playback, several keys are available: SPACE to pause/unpause,
-.  to step forward (while paused), CTRL-c quit.
-
-   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
-
-
-File: hledger.info,  Node: User interface commands,  Next: Data entry commands,  Prev: Help commands,  Up: Top
-
-25 User interface commands
-**************************
-
-* Menu:
-
-* ui::
-* web::
-
-
-File: hledger.info,  Node: ui,  Next: web,  Up: User interface commands
-
-25.1 ui
-=======
-
-Runs hledger-ui (if installed).
-
-
-File: hledger.info,  Node: web,  Prev: ui,  Up: User interface commands
-
-25.2 web
-========
-
-Runs hledger-web (if installed).
-
-
-File: hledger.info,  Node: Data entry commands,  Next: Basic report commands,  Prev: User interface commands,  Up: Top
-
-26 Data entry commands
-**********************
-
-* Menu:
-
-* add::
-* import::
-
-
-File: hledger.info,  Node: add,  Next: import,  Up: Data entry commands
-
-26.1 add
-========
-
-Record new transactions with interactive prompting in the console.
-
-Flags:
-     --no-new-accounts      don't allow creating new accounts
-
-   Many hledger users edit their journals directly with a text editor,
-or generate them from CSV. For more interactive data entry, there is the
-'add' command, which prompts interactively on the console for new
-transactions, and appends them to the main journal file (which should be
-in journal format).  Existing transactions are not changed.  This is one
-of the few hledger commands that writes to the journal file (see also
-'import').
-
-   To use it, just run 'hledger add' and follow the prompts.  You can
-add as many transactions as you like; when you are finished, enter '.'
-or press control-d or control-c to exit.
-
-   Features:
-
-   * add tries to provide useful defaults, using the most similar (by
-     description) recent transaction (filtered by the query, if any) as
-     a template.
-   * You can also set the initial defaults with command line arguments.
-   * Readline-style edit keys can be used during data entry.
-   * The tab key will auto-complete whenever possible - accounts,
-     payees/descriptions, dates ('yesterday', 'today', 'tomorrow').  If
-     the input area is empty, it will insert the default value.
-   * A parenthesised transaction code may be entered following a date.
-   * Comments and tags may be entered following a description or amount.
-   * If you make a mistake, enter '<' at any prompt to go one step
-     backward.
-   * Input prompts are displayed in a different colour when the terminal
-     supports it.
-
-   Notes:
-
-   * If you enter a number with no commodity symbol, and you have
-     declared a default commodity with a 'D' directive, you might expect
-     'add' to add this symbol for you.  It does not do this; we assume
-     that if you are using a 'D' directive you prefer not to see the
-     commodity symbol repeated on amounts in the journal.
-
-   Examples:
-
-   * Record new transactions, saving to the default journal file:
-
-     'hledger add'
-
-   * Add transactions to 2024.journal, but also load 2023.journal for
-     completions:
-
-     'hledger add --file 2024.journal --file 2023.journal'
-
-   * Provide answers for the first four prompts:
-
-     'hledger add today 'best buy' expenses:supplies '$20''
-
-   There is a detailed tutorial at https://hledger.org/add.html.
-
-
-File: hledger.info,  Node: import,  Prev: add,  Up: Data entry commands
-
-26.2 import
-===========
-
-Import new transactions from one or more data files to the main journal.
-
-Flags:
-     --catchup              just mark all transactions as already imported
-     --dry-run              just show the transactions to be imported
-
-   This command detects new transactions in one or more data files
-specified as arguments, and appends them to the main journal.
-
-   You can import from any input file format hledger supports, but
-CSV/SSV/TSV files, downloaded from financial institutions, are the most
-common import source.
-
-   The import destination is the default journal file, or another
-specified in the usual way with '$LEDGER_FILE' or '-f/--file'.  It
-should be in journal format.
-
-   Examples:
-
-$ hledger import bank1-checking.csv bank1-savings.csv
-
-$ hledger import *.csv
-
-* Menu:
-
-* Import preview::
-* Overlap detection::
-* First import::
-* Importing balance assignments::
-* Import and commodity styles::
-* Import special cases::
-
-
-File: hledger.info,  Node: Import preview,  Next: Overlap detection,  Up: import
-
-26.2.1 Import preview
----------------------
-
-It's useful to preview the import by running first with '--dry-run', to
-sanity check the range of dates being imported, and to check the effect
-of your conversion rules if converting from CSV. Eg:
-
-$ hledger import bank.csv --dry-run
-
-   The dry run output is valid journal format, so hledger can re-parse
-it.  If the output is large, you could show just the uncategorised
-transactions like so:
-
-$ hledger import --dry-run bank.csv | hledger -f- -I print unknown
-
-   You could also run this repeatedly to see the effect of edits to your
-conversion rules:
-
-$ watchexec -- 'hledger import --dry-run bank.csv | hledger -f- -I print unknown'
-
-   Once the conversion and dates look good enough to import to your
-journal, perhaps with some manual fixups to follow, you would do the
-actual import:
-
-$ hledger import bank.csv
-
-
-File: hledger.info,  Node: Overlap detection,  Next: First import,  Prev: Import preview,  Up: import
-
-26.2.2 Overlap detection
-------------------------
-
-Reading CSV files is built in to hledger, and not specific to 'import';
-so you could also import by doing 'hledger -f bank.csv print
->>$LEDGER_FILE'.
-
-   But 'import' is easier and provides some advantages.  The main one is
-that it avoids re-importing transactions it has seen on previous runs.
-This means you don't have to worry about overlapping data in successive
-downloads of your bank CSV; just download and 'import' as often as you
-like, and only the new transactions will be imported each time.
-
-   We don't call this "deduplication", as it's generally not possible to
-reliably detect duplicates in bank CSV. Instead, 'import' remembers the
-latest date processed previously in each CSV file (saving it in a hidden
-file), and skips any records prior to that date.  This works well for
-most real-world CSV, where:
-
-  1. the data file name is stable (does not change) across imports
-  2. the item dates are stable across imports
-  3. the order of same-date items is stable across imports
-  4. the newest items have the newest dates
-
-   (Occasional violations of 2-4 are often harmless; you can reduce the
-chance of disruption by downloading and importing more often.)
-
-   Overlap detection is automatic, and shouldn't require much attention
-from you, except perhaps at first import (see below).  But here's how it
-works:
-
-   * For each 'FILE' being imported from:
-
-       1. hledger reads a file named '.latest.FILE' file in the same
-          directory, if any.  This file contains the latest record date
-          previously imported from FILE, in YYYY-MM-DD format.  If
-          multiple records with that date were imported, the date is
-          repeated on N lines.
-
-       2. hledger reads records from FILE. If a latest date was found in
-          step 1, any records before that date, and the first N records
-          on that date, are skipped.
-
-   * After a successful import from all FILEs, without error and without
-     '--dry-run', hledger updates each FILE's '.latest.FILE' for next
-     time.
-
-   If this goes wrong, it's relatively easy to repair:
-
-   * You'll notice it before import when you preview with 'import
-     --dry-run'.
-   * Or after import when you try to reconcile your hledger account
-     balances with your bank.
-   * 'hledger print -f FILE.csv' will show all recently downloaded
-     transactions.  Compare these with your journal.  Copy/paste if
-     needed.
-   * Update your conversion rules and print again, if needed.
-   * You can manually update or remove the .latest file, or use 'import
-     --catchup FILE'.
-   * Download and import more often, eg twice a week, at least while you
-     are learning.  It's easier to review and troubleshoot when there
-     are fewer transactions.
-
-
-File: hledger.info,  Node: First import,  Next: Importing balance assignments,  Prev: Overlap detection,  Up: import
-
-26.2.3 First import
--------------------
-
-The first time you import from a file, when no corresponding .latest
-file has been created yet, all of the records will be imported.
-
-   But perhaps you have been entering the data manually, so you know
-that all of these transactions are already recorded in the journal.  In
-this case you can run 'hledger import --catchup' once.  This will create
-a .latest file containing the latest CSV record date, so that none of
-those records will be re-imported.
-
-   Or, if you know that some but not all of the transactions are in the
-journal, you can create the .latest file yourself.  Eg, let's say you
-previously recorded foobank transactions up to 2024-10-31 in the
-journal.  Then in the directory where you'll be saving 'foobank.csv',
-you would create a '.latest.foobank.csv' file containing
-
-2024-10-31
-
-   Or if you had three foobank transactions recorded with that date, you
-would repeat the date that many times:
-
-2024-10-31
-2024-10-31
-2024-10-31
-
-   Then 'hledger import foobank.csv [--dry-run]' will import only the
-newer records.
-
-
-File: hledger.info,  Node: Importing balance assignments,  Next: Import and commodity styles,  Prev: First import,  Up: import
-
-26.2.4 Importing balance assignments
-------------------------------------
-
-Journal entries added by import will have all posting amounts made
-explicit (like 'print -x').
-
-   This means that any balance assignments in the imported entries would
-need to be evaluated.  But this generally isn't possible, as the main
-file's account balances are not visible during import.  So try to avoid
-generating balance assignments with your CSV rules, or importing from a
-journal that contains balance assignments.  (Balance assignments are
-best avoided anyway.)
-
-   But if you must use them, eg because your CSV includes only balances:
-you can import with 'print', which leaves implicit amounts implicit.
-('print' can also do overlap detection like import, with the '--new'
-flag):
-
-$ hledger print --new -f bank.csv >> $LEDGER_FILE
-
-   (If you think 'import' should preserve implicit balances, please test
-that and send a pull request.)
-
-
-File: hledger.info,  Node: Import and commodity styles,  Next: Import special cases,  Prev: Importing balance assignments,  Up: import
-
-26.2.5 Import and commodity styles
-----------------------------------
-
-Amounts in entries added by import will be formatted according to the
-journal's canonical commodity styles, as declared by 'commodity'
-directives or inferred from the journal's amounts.
-
-   Related: CSV > Amount decimal places.
-
-
-File: hledger.info,  Node: Import special cases,  Prev: Import and commodity styles,  Up: import
-
-26.2.6 Import special cases
----------------------------
-
-If you have a download whose file name varies, you could rename it to a
-fixed name after each download.  Or you could use a CSV 'source' rule
-with a suitable glob pattern, and import from the .rules file instead of
-the data file.
-
-   Here's a situation where you would need to run 'import' with care:
-say you download 'bank.csv', but forget to import it or delete it.  And
-next month you download it again.  This time your web browser may save
-it as 'bank (2).csv'.  So now each of these may have data not included
-in the other.  And a 'source' rule with a glob pattern would match only
-the most recent file.  So in this case you should import from each one
-in turn, in the correct order, taking care to use the same filename each
-time:
-
-$ hledger import bank.csv
-$ mv 'bank (2).csv' bank.csv
-$ hledger import bank.csv
-
-   Here are two kinds of "deduplication" which 'import' does not handle
-(and generally should not, since these can happen legitimately in
-financial data):
-
-   * Two or more of the new CSV records are identical, and generate
-     identical new journal entries.
-   * A new CSV record generates a journal entry identical to one(s)
-     already in the journal.
-
-
-File: hledger.info,  Node: Basic report commands,  Next: Standard report commands,  Prev: Data entry commands,  Up: Top
-
-27 Basic report commands
-************************
-
-* Menu:
-
-* accounts::
-* codes::
-* commodities::
-* descriptions::
-* files::
-* notes::
-* payees::
-* prices::
-* stats::
-* tags::
-
-
-File: hledger.info,  Node: accounts,  Next: codes,  Up: Basic report commands
-
-27.1 accounts
-=============
-
-List account names.
-
-Flags:
-  -u --used                 show only accounts used by transactions
-  -d --declared             show only accounts declared by account directive
-     --unused               show only accounts declared but not used
-     --undeclared           show only accounts used but not declared
-     --types                also show account types when known
-     --positions            also show where accounts were declared
-     --directives           show as account directives, for use in journals
-     --find                 find the first account matched by the first
-                            argument (a case-insensitive infix regexp or
-                            account name)
-  -l --flat                 show accounts as a flat list (default)
-  -t --tree                 show accounts as a tree
-     --drop=N               flat mode: omit N leading account name parts
-
-   This command lists account names.  By default it shows all known
-accounts, either used in transactions or declared with account
-directives.
-
-   With query arguments, only matched account names and account names
-referenced by matched postings are shown.
-
-   Or it can show just the used accounts ('--used'/'-u'), the declared
-accounts ('--declared'/'-d'), the accounts declared but not used
-('--unused'), the accounts used but not declared ('--undeclared'), or
-the first account matched by an account name pattern, if any ('--find').
-
-   It shows a flat list by default.  With '--tree', it uses indentation
-to show the account hierarchy.  In flat mode you can add '--drop N' to
-omit the first few account name components.  Account names can be
-depth-clipped with 'depth:N' or '--depth N' or '-N'.
-
-   With '--types', it also shows each account's type, if it's known.
-(See Declaring accounts > Account types.)
-
-   With '--positions', it also shows the file and line number of each
-account's declaration, if any, and the account's overall declaration
-order; these may be useful when troubleshooting account display order.
-
-   With '--directives', it adds the 'account' keyword, showing valid
-account directives which can be pasted into a journal file.  This is
-useful together with '--undeclared' when updating your account
-declarations to satisfy 'hledger check accounts'.
-
-   The '--find' flag can be used to look up a single account name, in
-the same way that the 'aregister' command does.  It returns the
-alphanumerically-first matched account name, or if none can be found, it
-fails with a non-zero exit code.
-
-   Examples:
-
-$ hledger accounts
-assets:bank:checking
-assets:bank:saving
-assets:cash
-expenses:food
-expenses:supplies
-income:gifts
-income:salary
-liabilities:debts
-
-$ hledger accounts --undeclared --directives >> $LEDGER_FILE
-$ hledger check accounts
-
-
-File: hledger.info,  Node: codes,  Next: commodities,  Prev: accounts,  Up: Basic report commands
-
-27.2 codes
-==========
-
-List the codes seen in transactions, in the order parsed.
-
-Flags:
-no command-specific flags
-
-   This command prints the value of each transaction's code field, in
-the order transactions were parsed.  The transaction code is an optional
-value written in parentheses between the date and description, often
-used to store a cheque number, order number or similar.
-
-   Transactions aren't required to have a code, and missing or empty
-codes will not be shown by default.  With the '-E'/'--empty' flag, they
-will be printed as blank lines.
-
-   You can add a query to select a subset of transactions.
-
-   Examples:
-
-2022/1/1 (123) Supermarket   
- Food       $5.00
- Checking    
-
-2022/1/2 (124) Post Office
- Postage    $8.32
- Checking
-
-2022/1/3 Supermarket
- Food      $11.23
- Checking 
-
-2022/1/4 (126) Post Office
- Postage    $3.21
- Checking
-
-$ hledger codes
-123
-124
-126
-
-$ hledger codes -E
-123
-124
-
-126
-
-
-File: hledger.info,  Node: commodities,  Next: descriptions,  Prev: codes,  Up: Basic report commands
-
-27.3 commodities
-================
-
-List all commodity/currency symbols used or declared in the journal.
-
-Flags:
-no command-specific flags
-
-
-File: hledger.info,  Node: descriptions,  Next: files,  Prev: commodities,  Up: Basic report commands
-
-27.4 descriptions
-=================
-
-List the unique descriptions that appear in transactions.
-
-Flags:
-no command-specific flags
-
-   This command lists the unique descriptions that appear in
-transactions, in alphabetic order.  You can add a query to select a
-subset of transactions.
-
-   Example:
-
-$ hledger descriptions
-Store Name
-Gas Station | Petrol
-Person A
-
-
-File: hledger.info,  Node: files,  Next: notes,  Prev: descriptions,  Up: Basic report commands
-
-27.5 files
-==========
-
-List all files included in the journal.  With a REGEX argument, only
-file names matching the regular expression (case sensitive) are shown.
-
-Flags:
-no command-specific flags
-
-
-File: hledger.info,  Node: notes,  Next: payees,  Prev: files,  Up: Basic report commands
-
-27.6 notes
-==========
-
-List the unique notes that appear in transactions.
-
-Flags:
-no command-specific flags
-
-   This command lists the unique notes that appear in transactions, in
-alphabetic order.  You can add a query to select a subset of
-transactions.  The note is the part of the transaction description after
-a | character (or if there is no |, the whole description).
-
-   Example:
-
-$ hledger notes
-Petrol
-Snacks
-
-
-File: hledger.info,  Node: payees,  Next: prices,  Prev: notes,  Up: Basic report commands
-
-27.7 payees
-===========
-
-List the unique payee/payer names that appear in transactions.
-
-Flags:
-     --declared             show payees declared with payee directives
-     --used                 show payees referenced by transactions
-
-   This command lists unique payee/payer names which have been declared
-with payee directives (-declared), used in transaction descriptions
-(-used), or both (the default).
-
-   The payee/payer is the part of the transaction description before a |
-character (or if there is no |, the whole description).
-
-   You can add query arguments to select a subset of transactions.  This
-implies -used.
-
-   Example:
-
-$ hledger payees
-Store Name
-Gas Station
-Person A
-
-
-File: hledger.info,  Node: prices,  Next: stats,  Prev: payees,  Up: Basic report commands
-
-27.8 prices
-===========
-
-Print the market prices declared with P directives.  With
--infer-market-prices, also show any additional prices inferred from
-costs.  With -show-reverse, also show additional prices inferred by
-reversing known prices.
-
-Flags:
-     --show-reverse         also show the prices inferred by reversing known
-                            prices
-
-   Price amounts are always displayed with their full precision, except
-for reverse prices which are limited to 8 decimal digits.
-
-   Prices can be filtered by a date:, cur: or amt: query.
-
-   Generally if you run this command with -infer-market-prices
--show-reverse, it will show the same prices used internally to calculate
-value reports.  But if in doubt, you can inspect those directly by
-running the value report with -debug=2.
-
-
-File: hledger.info,  Node: stats,  Next: tags,  Prev: prices,  Up: Basic report commands
-
-27.9 stats
-==========
-
-Show journal and performance statistics.
-
-Flags:
-  -v --verbose              show more detailed output
-  -o --output-file=FILE     write output to FILE.
-
-   The stats command shows summary information for the whole journal, or
-a matched part of it.  With a reporting interval, it shows a report for
-each report period.
-
-   The default output is fairly impersonal, though it reveals the main
-file name.  With '-v/--verbose', more details are shown, like file
-paths, included files, and commodity names.
-
-   It also shows some run time statistics:
-
-   * elapsed time
-   * throughput: the number of transactions processed per second
-   * live: the peak memory in use by the program to do its work
-   * alloc: the peak memory allocation from the OS as seen by GHC.
-     Measuring this externally, eg with GNU time, is more accurate;
-     usually that will be a larger number; sometimes (with swapping?)
-     smaller.
-
-   The 'stats' command's run time is similar to that of a balance
-report.
-
-   Example:
-
-$ hledger stats -f examples/1ktxns-1kaccts.journal 
-Main file           : .../1ktxns-1kaccts.journal
-Included files      : 0
-Txns span           : 2000-01-01 to 2002-09-27 (1000 days)
-Last txn            : 2002-09-26 (7827 days ago)
-Txns                : 1000 (1.0 per day)
-Txns last 30 days   : 0 (0.0 per day)
-Txns last 7 days    : 0 (0.0 per day)
-Payees/descriptions : 1000
-Accounts            : 1000 (depth 10)
-Commodities         : 26
-Market prices       : 1000
-Runtime stats       : 0.12 s elapsed, 8266 txns/s, 4 MB live, 16 MB alloc
-
-   This command supports the -o/-output-file option (but not
--O/-output-format).
-
-
-File: hledger.info,  Node: tags,  Prev: stats,  Up: Basic report commands
-
-27.10 tags
-==========
-
-List the tags used in the journal, or their values.
-
-Flags:
-     --values               list tag values instead of tag names
-     --parsed               show tags/values in the order they were parsed,
-                            including duplicates
-
-   This command lists the tag names used in the journal, whether on
-transactions, postings, or account declarations.
-
-   With a TAGREGEX argument, only tag names matching this regular
-expression (case insensitive, infix matched) are shown.
-
-   With QUERY arguments, only transactions and accounts matching this
-query are considered.  If the query involves transaction fields (date:,
-desc:, amt:, ...), the search is restricted to the matched transactions
-and their accounts.
-
-   With the -values flag, the tags' unique non-empty values are listed
-instead.  With -E/-empty, blank/empty values are also shown.
-
-   With -parsed, tags or values are shown in the order they were parsed,
-with duplicates included.  (Except, tags from account declarations are
-always shown first.)
-
-   Tip: remember, accounts also acquire tags from their parents,
-postings also acquire tags from their account and transaction,
-transactions also acquire tags from their postings.
-
-
-File: hledger.info,  Node: Standard report commands,  Next: Advanced report commands,  Prev: Basic report commands,  Up: Top
-
-28 Standard report commands
-***************************
-
-* Menu:
-
-* print::
-* aregister::
-* register::
-* balancesheet::
-* balancesheetequity::
-* cashflow::
-* incomestatement::
-
-
-File: hledger.info,  Node: print,  Next: aregister,  Up: Standard report commands
-
-28.1 print
-==========
-
-Show full journal entries, representing transactions.
-
-Flags:
-  -x --explicit             show all amounts explicitly
-     --show-costs           show transaction prices even with conversion
-                            postings
-     --round=TYPE           how much rounding or padding should be done when
-                            displaying amounts ?
-                            none - show original decimal digits,
-                                   as in journal
-                            soft - just add or remove decimal zeros
-                                   to match precision (default)
-                            hard - round posting amounts to precision
-                                   (can unbalance transactions)
-                            all  - also round cost amounts to precision
-                                   (can unbalance transactions)
-     --new                  show only newer-dated transactions added in each
-                            file since last run
-  -m --match=DESC           fuzzy search for one recent transaction with
-                            description closest to DESC
-     --base-url=URLPREFIX   in html output, generate links to hledger-web,
-                            with this prefix. (Usually the base url shown by
-                            hledger-web; can also be relative.)
-  -O --output-format=FMT    select the output format. Supported formats:
-                            txt, beancount, csv, tsv, html, fods, json, sql.
-  -o --output-file=FILE     write output to FILE. A file extension matching
-                            one of the above formats selects that format.
-
-   The print command displays full journal entries (transactions) from
-the journal file, sorted by date (or with '--date2', by secondary date).
-
-   Directives and inter-transaction comments are not shown, currently.
-This means the print command is somewhat lossy, and if you are using it
-to reformat/regenerate your journal you should take care to also copy
-over the directives and inter-transaction comments.
-
-   Eg:
-
-$ hledger print -f examples/sample.journal date:200806
-2008/06/01 gift
-    assets:bank:checking            $1
-    income:gifts                   $-1
-
-2008/06/02 save
-    assets:bank:saving              $1
-    assets:bank:checking           $-1
-
-2008/06/03 * eat & shop
-    expenses:food                $1
-    expenses:supplies            $1
-    assets:cash                 $-2
-
-* Menu:
-
-* print explicitness::
-* print amount style::
-* print parseability::
-* print other features::
-* print output format::
-
-
-File: hledger.info,  Node: print explicitness,  Next: print amount style,  Up: print
-
-28.1.1 print explicitness
--------------------------
-
-Normally, whether posting amounts are implicit or explicit is preserved.
-For example, when an amount is omitted in the journal, it will not
-appear in the output.  Similarly, if a conversion cost is implied but
-not written, it will not appear in the output.
-
-   You can use the '-x'/'--explicit' flag to force explicit display of
-all amounts and costs.  This can be useful for troubleshooting or for
-making your journal more readable and robust against data entry errors.
-'-x' is also implied by using any of '-B','-V','-X','--value'.
-
-   The '-x'/'--explicit' flag will cause any postings with a
-multi-commodity amount (which can arise when a multi-commodity
-transaction has an implicit amount) to be split into multiple
-single-commodity postings, keeping the output parseable.
-
-
-File: hledger.info,  Node: print amount style,  Next: print parseability,  Prev: print explicitness,  Up: print
-
-28.1.2 print amount style
--------------------------
-
-Amounts are shown right-aligned within each transaction (but not aligned
-across all transactions; you can do that with ledger-mode in Emacs).
-
-   Amounts will be (mostly) normalised to their commodity display style:
-their symbol placement, decimal mark, and digit group marks will be made
-consistent.  By default, decimal digits are shown as they are written in
-the journal.
-
-   With the '--round' (_Added in 1.32_) option, 'print' will try
-increasingly hard to display decimal digits according to the commodity
-display styles:
-
-   * '--round=none' show amounts with original precisions (default)
-   * '--round=soft' add/remove decimal zeros in amounts (except costs)
-   * '--round=hard' round amounts (except costs), possibly hiding
-     significant digits
-   * '--round=all' round all amounts and costs
-
-   'soft' is good for non-lossy cleanup, formatting amounts more
-consistently where it's safe to do so.
-
-   'hard' and 'all' can cause 'print' to show invalid unbalanced journal
-entries; they may be useful eg for stronger cleanup, with manual fixups
-when needed.
-
-
-File: hledger.info,  Node: print parseability,  Next: print other features,  Prev: print amount style,  Up: print
-
-28.1.3 print parseability
--------------------------
-
-print's output is usually a valid hledger journal, and you can process
-it again with a second hledger command.  This can be useful for certain
-kinds of search (though the same can be achieved with 'expr:' queries
-now):
-
-# Show running total of food expenses paid from cash.
-# -f- reads from stdin. -I/--ignore-assertions is sometimes needed.
-$ hledger print assets:cash | hledger -f- -I reg expenses:food
-
-   There are some situations where print's output can become
-unparseable:
-
-   * Value reporting affects posting amounts but not balance assertion
-     or balance assignment amounts, potentially causing those to fail.
-   * Auto postings can generate postings with too many missing amounts.
-   * Account aliases can generate bad account names.
-
-
-File: hledger.info,  Node: print other features,  Next: print output format,  Prev: print parseability,  Up: print
-
-28.1.4 print, other features
-----------------------------
-
-With '-B'/'--cost', amounts with costs are shown converted to cost.
-
-   With '--new', print shows only transactions it has not seen on a
-previous run.  This uses the same deduplication system as the 'import'
-command.  (See import's docs for details.)
-
-   With '-m DESC'/'--match=DESC', print shows one recent transaction
-whose description is most similar to DESC. DESC should contain at least
-two characters.  If there is no similar-enough match, no transaction
-will be shown and the program exit code will be non-zero.
-
-
-File: hledger.info,  Node: print output format,  Prev: print other features,  Up: print
-
-28.1.5 print output format
---------------------------
-
-This command also supports the output destination and output format
-options The output formats supported are 'txt', 'beancount' (_Added in
-1.32_), 'csv', 'tsv' (_Added in 1.32_), 'json' and 'sql'.
-
-   The 'beancount' format tries to produce Beancount-compatible output,
-as follows:
-
-   * Transaction and postings with unmarked status are converted to
-     cleared ('*') status.
-   * Transactions' payee and note are backslash-escaped and
-     double-quote-escaped and wrapped in double quotes.
-   * Transaction tags are copied to Beancount #tag format.
-   * Commodity symbols are converted to upper case, and a small number
-     of currency symbols like '$' are converted to the corresponding
-     currency names.
-   * Account name parts are capitalised and unsupported characters are
-     replaced with '-'.  If an account name part does not begin with a
-     letter, or if the first part is not Assets, Liabilities, Equity,
-     Income, or Expenses, an error is raised.  (Use '--alias' options to
-     bring your accounts into compliance.)
-   * An 'open' directive is generated for each account used, on the
-     earliest transaction date.
-
-   Some limitations:
-
-   * Balance assertions are removed.
-   * Balance assignments become missing amounts.
-   * Virtual and balanced virtual postings become regular postings.
-   * Directives are not converted.
-
-   Here's an example of print's CSV output:
-
-$ hledger print -Ocsv
-"txnidx","date","date2","status","code","description","comment","account","amount","commodity","credit","debit","posting-status","posting-comment"
-"1","2008/01/01","","","","income","","assets:bank:checking","1","$","","1","",""
-"1","2008/01/01","","","","income","","income:salary","-1","$","1","","",""
-"2","2008/06/01","","","","gift","","assets:bank:checking","1","$","","1","",""
-"2","2008/06/01","","","","gift","","income:gifts","-1","$","1","","",""
-"3","2008/06/02","","","","save","","assets:bank:saving","1","$","","1","",""
-"3","2008/06/02","","","","save","","assets:bank:checking","-1","$","1","","",""
-"4","2008/06/03","","*","","eat & shop","","expenses:food","1","$","","1","",""
-"4","2008/06/03","","*","","eat & shop","","expenses:supplies","1","$","","1","",""
-"4","2008/06/03","","*","","eat & shop","","assets:cash","-2","$","2","","",""
-"5","2008/12/31","","*","","pay off","","liabilities:debts","1","$","","1","",""
-"5","2008/12/31","","*","","pay off","","assets:bank:checking","-1","$","1","","",""
-
-   * There is one CSV record per posting, with the parent transaction's
-     fields repeated.
-   * The "txnidx" (transaction index) field shows which postings belong
-     to the same transaction.  (This number might change if transactions
-     are reordered within the file, files are parsed/included in a
-     different order, etc.)
-   * The amount is separated into "commodity" (the symbol) and "amount"
-     (numeric quantity) fields.
-   * The numeric amount is repeated in either the "credit" or "debit"
-     column, for convenience.  (Those names are not accurate in the
-     accounting sense; it just puts negative amounts under credit and
-     zero or greater amounts under debit.)
-
-
-File: hledger.info,  Node: aregister,  Next: register,  Prev: print,  Up: Standard report commands
-
-28.2 aregister
-==============
-
-(areg)
-
-   Show the transactions and running balances in one account, with each
-transaction on one line.
-
-Flags:
-     --txn-dates            filter strictly by transaction date, not posting
-                            date. Warning: this can show a wrong running
-                            balance.
-     --no-elide             don't show only 2 commodities per amount
-     --cumulative           show running total from report start date
-  -H --historical           show historical running total/balance (includes
-                            postings before report start date) (default)
-                            
-     --invert               display all amounts with reversed sign
-     --heading=YN           show heading row above table: yes (default) or no
-  -w --width=N              set output width (default: terminal width or
-                            $COLUMNS). -wN,M sets description width as well.
-     --align-all            guarantee alignment across all lines (slower)
-  -O --output-format=FMT    select the output format. Supported formats:
-                            txt, html, csv, tsv, json.
-  -o --output-file=FILE     write output to FILE. A file extension matching
-                            one of the above formats selects that format.
-
-   'aregister' shows the overall transactions affecting a particular
-account (and any subaccounts).  Each report line represents one
-transaction in this account.  Transactions before the report start date
-are included in the running balance ('--historical' mode is the
-default).  You can suppress this behaviour using the '--cumulative'
-option.
-
-   This is a more "real world", bank-like view than the 'register'
-command (which shows individual postings, possibly from multiple
-accounts, not necessarily in historical mode).  As a quick rule of
-thumb: - use 'aregister' for reviewing and reconciling real-world
-asset/liability accounts - use 'register' for reviewing detailed
-revenues/expenses.
-
-   'aregister' requires one argument: the account to report on.  You can
-write either the full account name, or a case-insensitive regular
-expression which will select the alphabetically first matched account.
-
-   When there are multiple matches, the alphabetically-first choice can
-be surprising; eg if you have 'assets:per:checking 1' and
-'assets:biz:checking 2' accounts, 'hledger areg checking' would select
-'assets:biz:checking 2'.  It's just a convenience to save typing, so if
-in doubt, write the full account name, or a distinctive substring that
-matches uniquely.
-
-   Transactions involving subaccounts of this account will also be
-shown.  'aregister' ignores depth limits, so its final total will always
-match a balance report with similar arguments.
-
-   Any additional arguments form a query which will filter the
-transactions shown.  Note some queries will disturb the running balance,
-causing it to be different from the account's real-world running
-balance.
-
-   An example: this shows the transactions and historical running
-balance during july, in the first account whose name contains
-"checking":
-
-$ hledger areg checking date:jul
-
-   Each 'aregister' line item shows:
-
-   * the transaction's date (or the relevant posting's date if
-     different, see below)
-   * the names of all the other account(s) involved in this transaction
-     (probably abbreviated)
-   * the total change to this account's balance from this transaction
-   * the account's historical running balance after this transaction.
-
-   Transactions making a net change of zero are not shown by default;
-add the '-E/--empty' flag to show them.
-
-   For performance reasons, column widths are chosen based on the first
-1000 lines; this means unusually wide values in later lines can cause
-visual discontinuities as column widths are adjusted.  If you want to
-ensure perfect alignment, at the cost of more time and memory, use the
-'--align-all' flag.
-
-   By default, 'aregister' shows a heading above the data.  However,
-when reporting in a language different from English, it is easier to
-omit this heading and prepend your own one.  For this purpose, use the
-'--heading=no' option.
-
-   This command also supports the output destination and output format
-options.  The output formats supported are 'txt', 'csv', 'tsv' (_Added
-in 1.32_), 'html', 'fods' (_Added in 1.41_) and 'json'.
-
-* Menu:
-
-* aregister and posting dates::
-
-
-File: hledger.info,  Node: aregister and posting dates,  Up: aregister
-
-28.2.1 aregister and posting dates
-----------------------------------
-
-aregister always shows one line (and date and amount) per transaction.
-But sometimes transactions have postings with different dates.  Also,
-not all of a transaction's postings may be within the report period.  To
-resolve this, aregister shows the earliest of the transaction's date and
-posting dates that is in-period, and the sum of the in-period postings.
-In other words it will show a combined line item with just the earliest
-date, and the running balance will (temporarily, until the transaction's
-last posting) be inaccurate.  Use 'register -H' if you need to see the
-individual postings.
-
-   There is also a '--txn-dates' flag, which filters strictly by
-transaction date, ignoring posting dates.  This too can cause an
-inaccurate running balance.
-
-
-File: hledger.info,  Node: register,  Next: balancesheet,  Prev: aregister,  Up: Standard report commands
-
-28.3 register
-=============
-
-(reg)
-
-   Show postings and their running total.
-
-Flags:
-     --cumulative           show running total from report start date
-                            (default)
-  -H --historical           show historical running total/balance (includes
-                            postings before report start date)
-  -A --average              show running average of posting amounts instead
-                            of total (implies --empty)
-  -m --match=DESC           fuzzy search for one recent posting with
-                            description closest to DESC
-  -r --related              show postings' siblings instead
-     --invert               display all amounts with reversed sign
-     --sort=FIELDS          sort by: date, desc, account, amount, absamount,
-                            or a comma-separated combination of these. For a
-                            descending sort, prefix with -. (Default: date)
-  -w --width=N              set output width (default: terminal width or
-                            $COLUMNS). -wN,M sets description width as well.
-     --align-all            guarantee alignment across all lines (slower)
-     --base-url=URLPREFIX   in html output, generate links to hledger-web,
-                            with this prefix. (Usually the base url shown by
-                            hledger-web; can also be relative.)
-  -O --output-format=FMT    select the output format. Supported formats:
-                            txt, csv, tsv, html, fods, json.
-  -o --output-file=FILE     write output to FILE. A file extension matching
-                            one of the above formats selects that format.
-
-   The register command displays matched postings, across all accounts,
-in date order, with their running total or running historical balance.
-(See also the 'aregister' command, which shows matched transactions in a
-specific account.)
-
-   register normally shows line per posting, but note that
-multi-commodity amounts will occupy multiple lines (one line per
-commodity).
-
-   It is typically used with a query selecting a particular account, to
-see that account's activity:
-
-$ hledger register checking
-2008/01/01 income               assets:bank:checking            $1           $1
-2008/06/01 gift                 assets:bank:checking            $1           $2
-2008/06/02 save                 assets:bank:checking           $-1           $1
-2008/12/31 pay off              assets:bank:checking           $-1            0
-
-   With '--date2', it shows and sorts by secondary date instead.
-
-   For performance reasons, column widths are chosen based on the first
-1000 lines; this means unusually wide values in later lines can cause
-visual discontinuities as column widths are adjusted.  If you want to
-ensure perfect alignment, at the cost of more time and memory, use the
-'--align-all' flag.
-
-   The '--historical'/'-H' flag adds the balance from any undisplayed
-prior postings to the running total.  This is useful when you want to
-see only recent activity, with a historically accurate running balance:
-
-$ hledger register checking -b 2008/6 --historical
-2008/06/01 gift                 assets:bank:checking            $1           $2
-2008/06/02 save                 assets:bank:checking           $-1           $1
-2008/12/31 pay off              assets:bank:checking           $-1            0
-
-   The '--depth' option limits the amount of sub-account detail
-displayed.
-
-   The '--average'/'-A' flag shows the running average posting amount
-instead of the running total (so, the final number displayed is the
-average for the whole report period).  This flag implies '--empty' (see
-below).  It is affected by '--historical'.  It works best when showing
-just one account and one commodity.
-
-   The '--related'/'-r' flag shows the _other_ postings in the
-transactions of the postings which would normally be shown.
-
-   The '--invert' flag negates all amounts.  For example, it can be used
-on an income account where amounts are normally displayed as negative
-numbers.  It's also useful to show postings on the checking account
-together with the related account:
-
-   The '--sort=FIELDS' flag sorts by the fields given, which can be any
-of 'account', 'amount', 'absamount', 'date', or 'desc'/'description',
-optionally separated by commas.  For example, '--sort account,amount'
-will group all transactions in each account, sorted by transaction
-amount.  Each field can be negated by a preceding '-', so '--sort
--amount' will show transactions ordered from smallest amount to largest
-amount.
-
-$ hledger register --related --invert assets:checking
-
-   With a reporting interval, register shows summary postings, one per
-interval, aggregating the postings to each account:
-
-$ hledger register --monthly income
-2008/01                 income:salary                          $-1          $-1
-2008/06                 income:gifts                           $-1          $-2
-
-   Periods with no activity, and summary postings with a zero amount,
-are not shown by default; use the '--empty'/'-E' flag to see them:
-
-$ hledger register --monthly income -E
-2008/01                 income:salary                          $-1          $-1
-2008/02                                                          0          $-1
-2008/03                                                          0          $-1
-2008/04                                                          0          $-1
-2008/05                                                          0          $-1
-2008/06                 income:gifts                           $-1          $-2
-2008/07                                                          0          $-2
-2008/08                                                          0          $-2
-2008/09                                                          0          $-2
-2008/10                                                          0          $-2
-2008/11                                                          0          $-2
-2008/12                                                          0          $-2
-
-   Often, you'll want to see just one line per interval.  The '--depth'
-option helps with this, causing subaccounts to be aggregated:
-
-$ hledger register --monthly assets --depth 1h
-2008/01                 assets                                  $1           $1
-2008/06                 assets                                 $-1            0
-2008/12                 assets                                 $-1          $-1
-
-   Note when using report intervals, if you specify start/end dates
-these will be adjusted outward if necessary to contain a whole number of
-intervals.  This ensures that the first and last intervals are full
-length and comparable to the others in the report.
-
-   With '-m DESC'/'--match=DESC', register does a fuzzy search for one
-recent posting whose description is most similar to DESC. DESC should
-contain at least two characters.  If there is no similar-enough match,
-no posting will be shown and the program exit code will be non-zero.
-
-* Menu:
-
-* Custom register output::
-
-
-File: hledger.info,  Node: Custom register output,  Up: register
-
-28.3.1 Custom register output
------------------------------
-
-register uses the full terminal width by default, except on windows.
-You can override this by setting the 'COLUMNS' environment variable (not
-a 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
-description width as part of -width's argument, comma-separated:
-'--width W,D' .  Here's a diagram (won't display correctly in -help):
-
-<--------------------------------- width (W) ---------------------------------->
-date (10)  description (D)       account (W-41-D)     amount (12)   balance (12)
-DDDDDDDDDD dddddddddddddddddddd  aaaaaaaaaaaaaaaaaaa  AAAAAAAAAAAA  AAAAAAAAAAAA
-
-   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_), and 'json'.
-
-
-File: hledger.info,  Node: balancesheet,  Next: balancesheetequity,  Prev: register,  Up: Standard report commands
-
-28.4 balancesheet
-=================
-
-(bs)
-
-   Show the end balances in asset and liability accounts.  Amounts are
-shown with normal positive sign, as in conventional financial
-statements.
-
-Flags:
-     --sum                  show sum of posting amounts (default)
-     --valuechange          show total change of period-end historical
-                            balance value (caused by deposits, withdrawals,
-                            market price fluctuations)
-     --gain                 show unrealised capital gain/loss (historical
-                            balance value minus cost basis)
-     --budget               show sum of posting amounts compared to budget
-                            goals defined by periodic transactions
-     --count                show the count of postings
-     --change               accumulate amounts from column start to column
-                            end (in multicolumn reports)
-     --cumulative           accumulate amounts from report start (specified
-                            by e.g. -b/--begin) to column end
-  -H --historical           accumulate amounts from journal start to column
-                            end (includes postings before report start date)
-                            (default)
-  -l --flat                 show accounts as a flat list (default). Amounts
-                            exclude subaccount amounts, except where the
-                            account is depth-clipped.
-  -t --tree                 show accounts as a tree. Amounts include
-                            subaccount amounts.
-     --drop=N               flat mode: omit N leading account name parts
-     --declared             include non-parent declared accounts (best used
-                            with -E)
-  -A --average              show a row average column (in multicolumn
-                            reports)
-  -T --row-total            show a row total column (in multicolumn reports)
-     --summary-only         display only row summaries (e.g. row total,
-                            average) (in multicolumn reports)
-  -N --no-total             omit the final total row
-     --no-elide             don't squash boring parent accounts (in tree
-                            mode)
-     --format=FORMATSTR     use this custom line format (in simple reports)
-  -S --sort-amount          sort by amount instead of account code/name
-  -% --percent              express values in percentage of each column's
-                            total
-     --layout=ARG           how to show multi-commodity amounts:
-                            'wide[,WIDTH]': all commodities on one line
-                            'tall'        : each commodity on a new line
-                            'bare'        : bare numbers, symbols in a column
-     --base-url=URLPREFIX   in html output, generate hyperlinks to
-                            hledger-web, with this prefix. (Usually the base
-                            url shown by hledger-web; can also be relative.)
-  -O --output-format=FMT    select the output format. Supported formats:
-                            txt, html, csv, tsv, json.
-  -o --output-file=FILE     write output to FILE. A file extension matching
-                            one of the above formats selects that format.
-
-   This command displays a balance sheet, showing historical ending
-balances of asset and liability accounts.  (To see equity as well, use
-the balancesheetequity command.)
-
-   Accounts declared with the 'Asset', 'Cash' or 'Liability' type are
-shown (see account types).  Or if no such accounts are declared, it
-shows top-level accounts named 'asset' or 'liability' (case insensitive,
-plurals allowed) and their subaccounts.
-
-   Example:
-
-$ hledger balancesheet
-Balance Sheet 2008-12-31
-
-                    || 2008-12-31 
-====================++============
- Assets             ||            
---------------------++------------
- assets:bank:saving ||         $1 
- assets:cash        ||        $-2 
---------------------++------------
-                    ||        $-1 
-====================++============
- Liabilities        ||            
---------------------++------------
- liabilities:debts  ||        $-1 
---------------------++------------
-                    ||        $-1 
-====================++============
- Net:               ||          0 
-
-   This command is a higher-level variant of the 'balance' command, and
-supports many of that command's features, such as multi-period reports.
-It is similar to 'hledger balance -H assets liabilities', but with
-smarter account detection, and liabilities displayed with their sign
-flipped.
-
-   This command also supports the output destination and output format
-options The output formats supported are 'txt', 'csv', 'tsv' (_Added in
-1.32_), 'html', and 'json'.
-
-
-File: hledger.info,  Node: balancesheetequity,  Next: cashflow,  Prev: balancesheet,  Up: Standard report commands
-
-28.5 balancesheetequity
-=======================
-
-(bse)
-
-   This command displays a balance sheet, showing historical ending
-balances of asset, liability and equity accounts.  Amounts are shown
-with normal positive sign, as in conventional financial statements.
-
-Flags:
-     --sum                  show sum of posting amounts (default)
-     --valuechange          show total change of period-end historical
-                            balance value (caused by deposits, withdrawals,
-                            market price fluctuations)
-     --gain                 show unrealised capital gain/loss (historical
-                            balance value minus cost basis)
-     --budget               show sum of posting amounts compared to budget
-                            goals defined by periodic transactions
-     --count                show the count of postings
-     --change               accumulate amounts from column start to column
-                            end (in multicolumn reports)
-     --cumulative           accumulate amounts from report start (specified
-                            by e.g. -b/--begin) to column end
-  -H --historical           accumulate amounts from journal start to column
-                            end (includes postings before report start date)
-                            (default)
-  -l --flat                 show accounts as a flat list (default). Amounts
-                            exclude subaccount amounts, except where the
-                            account is depth-clipped.
-  -t --tree                 show accounts as a tree. Amounts include
-                            subaccount amounts.
-     --drop=N               flat mode: omit N leading account name parts
-     --declared             include non-parent declared accounts (best used
-                            with -E)
-  -A --average              show a row average column (in multicolumn
-                            reports)
-  -T --row-total            show a row total column (in multicolumn reports)
-     --summary-only         display only row summaries (e.g. row total,
-                            average) (in multicolumn reports)
-  -N --no-total             omit the final total row
-     --no-elide             don't squash boring parent accounts (in tree
-                            mode)
-     --format=FORMATSTR     use this custom line format (in simple reports)
-  -S --sort-amount          sort by amount instead of account code/name
-  -% --percent              express values in percentage of each column's
-                            total
-     --layout=ARG           how to show multi-commodity amounts:
-                            'wide[,WIDTH]': all commodities on one line
-                            'tall'        : each commodity on a new line
-                            'bare'        : bare numbers, symbols in a column
-     --base-url=URLPREFIX   in html output, generate hyperlinks to
-                            hledger-web, with this prefix. (Usually the base
-                            url shown by hledger-web; can also be relative.)
-  -O --output-format=FMT    select the output format. Supported formats:
-                            txt, html, csv, tsv, json.
-  -o --output-file=FILE     write output to FILE. A file extension matching
-                            one of the above formats selects that format.
-
-   This report shows accounts declared with the 'Asset', 'Cash',
-'Liability' or 'Equity' type (see account types).  Or if no such
-accounts are declared, it shows top-level accounts named 'asset',
-'liability' or 'equity' (case insensitive, plurals allowed) and their
-subaccounts.
-
-   Example:
-
-$ hledger balancesheetequity
-Balance Sheet With Equity 2008-12-31
-
-                    || 2008-12-31 
-====================++============
- Assets             ||            
---------------------++------------
- assets:bank:saving ||         $1 
- assets:cash        ||        $-2 
---------------------++------------
-                    ||        $-1 
-====================++============
- Liabilities        ||            
---------------------++------------
- liabilities:debts  ||        $-1 
---------------------++------------
-                    ||        $-1 
-====================++============
- Equity             ||            
---------------------++------------
---------------------++------------
-                    ||          0 
-====================++============
- Net:               ||          0 
-
-   This command is a higher-level variant of the 'balance' command, and
-supports many of that command's features, such as multi-period reports.
-It is similar to 'hledger balance -H assets liabilities equity', but
-with smarter account detection, and liabilities/equity displayed with
-their sign flipped.
-
-   This report is the easiest way to see if the accounting equation
-(A+L+E = 0) is satisfied (after you have done a 'close --retain' to
-merge revenues and expenses with equity, and perhaps added
-'--infer-equity' to balance your commodity conversions).
-
-   This command also supports the output destination and output format
-options The output formats supported are 'txt', 'csv', 'tsv', 'html',
-and 'json'.
-
-
-File: hledger.info,  Node: cashflow,  Next: incomestatement,  Prev: balancesheetequity,  Up: Standard report commands
-
-28.6 cashflow
-=============
-
-(cf)
-
-   This command displays a (simple) cashflow statement, showing the
-inflows and outflows affecting "cash" (ie, liquid, easily convertible)
-assets.  Amounts are shown with normal positive sign, as in conventional
-financial statements.
-
-Flags:
-     --sum                  show sum of posting amounts (default)
-     --valuechange          show total change of period-end historical
-                            balance value (caused by deposits, withdrawals,
-                            market price fluctuations)
-     --gain                 show unrealised capital gain/loss (historical
-                            balance value minus cost basis)
-     --budget               show sum of posting amounts compared to budget
-                            goals defined by periodic transactions
-     --count                show the count of postings
-     --change               accumulate amounts from column start to column
-                            end (in multicolumn reports) (default)
-     --cumulative           accumulate amounts from report start (specified
-                            by e.g. -b/--begin) to column end
-  -H --historical           accumulate amounts from journal start to column
-                            end (includes postings before report start date)
-  -l --flat                 show accounts as a flat list (default). Amounts
-                            exclude subaccount amounts, except where the
-                            account is depth-clipped.
-  -t --tree                 show accounts as a tree. Amounts include
-                            subaccount amounts.
-     --drop=N               flat mode: omit N leading account name parts
-     --declared             include non-parent declared accounts (best used
-                            with -E)
-  -A --average              show a row average column (in multicolumn
-                            reports)
-  -T --row-total            show a row total column (in multicolumn reports)
-     --summary-only         display only row summaries (e.g. row total,
-                            average) (in multicolumn reports)
-  -N --no-total             omit the final total row
-     --no-elide             don't squash boring parent accounts (in tree
-                            mode)
-     --format=FORMATSTR     use this custom line format (in simple reports)
-  -S --sort-amount          sort by amount instead of account code/name
-  -% --percent              express values in percentage of each column's
-                            total
-     --layout=ARG           how to show multi-commodity amounts:
-                            'wide[,WIDTH]': all commodities on one line
-                            'tall'        : each commodity on a new line
-                            'bare'        : bare numbers, symbols in a column
-     --base-url=URLPREFIX   in html output, generate hyperlinks to
-                            hledger-web, with this prefix. (Usually the base
-                            url shown by hledger-web; can also be relative.)
-  -O --output-format=FMT    select the output format. Supported formats:
-                            txt, html, csv, tsv, json.
-  -o --output-file=FILE     write output to FILE. A file extension matching
-                            one of the above formats selects that format.
-
-   This report shows accounts declared with the 'Cash' type (see account
-types).  Or if no such accounts are declared, it shows accounts
-
-   * under a top-level account named 'asset' (case insensitive, plural
-     allowed)
-   * whose name contains some variation of 'cash', 'bank', 'checking' or
-     'saving'.
-
-   More precisely: all accounts matching this case insensitive regular
-expression:
-
-   '^assets?(:.+)?:(cash|bank|che(ck|que?)(ing)?|savings?|currentcash)(:|$)'
-
-   and their subaccounts.
-
-   An example cashflow report:
-
-$ hledger cashflow
-Cashflow Statement 2008
-
-                    || 2008 
-====================++======
- Cash flows         ||      
---------------------++------
- assets:bank:saving ||   $1 
- assets:cash        ||  $-2 
---------------------++------
-                    ||  $-1 
-
-   This command is a higher-level variant of the 'balance' command, and
-supports many of that command's features, such as multi-period reports.
-It is similar to 'hledger balance assets not:fixed not:investment
-not:receivable', but with smarter account detection.
-
-   This command also supports the output destination and output format
-options The output formats supported are 'txt', 'csv', 'tsv' (_Added in
-1.32_), 'html', and 'json'.
-
-
-File: hledger.info,  Node: incomestatement,  Prev: cashflow,  Up: Standard report commands
-
-28.7 incomestatement
-====================
-
-(is)
-
-   Show revenue inflows and expense outflows during the report period.
-Amounts are shown with normal positive sign, as in conventional
-financial statements.
-
-Flags:
-     --sum                  show sum of posting amounts (default)
-     --valuechange          show total change of period-end historical
-                            balance value (caused by deposits, withdrawals,
-                            market price fluctuations)
-     --gain                 show unrealised capital gain/loss (historical
-                            balance value minus cost basis)
-     --budget               show sum of posting amounts compared to budget
-                            goals defined by periodic transactions
-     --count                show the count of postings
-     --change               accumulate amounts from column start to column
-                            end (in multicolumn reports) (default)
-     --cumulative           accumulate amounts from report start (specified
-                            by e.g. -b/--begin) to column end
-  -H --historical           accumulate amounts from journal start to column
-                            end (includes postings before report start date)
-  -l --flat                 show accounts as a flat list (default). Amounts
-                            exclude subaccount amounts, except where the
-                            account is depth-clipped.
-  -t --tree                 show accounts as a tree. Amounts include
-                            subaccount amounts.
-     --drop=N               flat mode: omit N leading account name parts
-     --declared             include non-parent declared accounts (best used
-                            with -E)
-  -A --average              show a row average column (in multicolumn
-                            reports)
-  -T --row-total            show a row total column (in multicolumn reports)
-     --summary-only         display only row summaries (e.g. row total,
-                            average) (in multicolumn reports)
-  -N --no-total             omit the final total row
-     --no-elide             don't squash boring parent accounts (in tree
-                            mode)
-     --format=FORMATSTR     use this custom line format (in simple reports)
-  -S --sort-amount          sort by amount instead of account code/name
-  -% --percent              express values in percentage of each column's
-                            total
-     --layout=ARG           how to show multi-commodity amounts:
-                            'wide[,WIDTH]': all commodities on one line
-                            'tall'        : each commodity on a new line
-                            'bare'        : bare numbers, symbols in a column
-     --base-url=URLPREFIX   in html output, generate hyperlinks to
-                            hledger-web, with this prefix. (Usually the base
-                            url shown by hledger-web; can also be relative.)
-  -O --output-format=FMT    select the output format. Supported formats:
-                            txt, html, csv, tsv, json.
-  -o --output-file=FILE     write output to FILE. A file extension matching
-                            one of the above formats selects that format.
-
-   This command displays an income statement, showing revenues and
-expenses during one or more periods.
-
-   It shows accounts declared with the 'Revenue' or 'Expense' type (see
-account types).  Or if no such accounts are declared, it shows top-level
-accounts named 'revenue' or 'income' or 'expense' (case insensitive,
-plurals allowed) and their subaccounts.
-
-   Example:
-
-$ hledger incomestatement
-Income Statement 2008
-
-                   || 2008 
-===================++======
- Revenues          ||      
--------------------++------
- income:gifts      ||   $1 
- income:salary     ||   $1 
--------------------++------
-                   ||   $2 
-===================++======
- Expenses          ||      
--------------------++------
- expenses:food     ||   $1 
- expenses:supplies ||   $1 
--------------------++------
-                   ||   $2 
-===================++======
- Net:              ||    0 
-
-   This command is a higher-level variant of the 'balance' command, and
-supports many of that command's features, such as multi-period reports.
-It is similar to 'hledger balance '(revenues|income)' expenses', but
-with smarter account detection, and revenues/income displayed with their
-sign flipped.
-
-   This command also supports the output destination and output format
-options The output formats supported are 'txt', 'csv', 'tsv' (_Added in
-1.32_), 'html', and 'json'.
-
-
-File: hledger.info,  Node: Advanced report commands,  Next: Chart commands,  Prev: Standard report commands,  Up: Top
-
-29 Advanced report commands
-***************************
-
-* Menu:
-
-* balance::
-* roi::
-
-
-File: hledger.info,  Node: balance,  Next: roi,  Up: Advanced report commands
-
-29.1 balance
-============
-
-(bal)
-
-   A flexible, general purpose "summing" report that shows accounts with
-some kind of numeric data.  This can be balance changes per period, end
-balances, budget performance, unrealised capital gains, etc.
-
-Flags:
-     --sum                  show sum of posting amounts (default)
-     --valuechange          show total change of value of period-end
-                            historical balances (caused by deposits,
-                            withdrawals, market price fluctuations)
-     --gain                 show unrealised capital gain/loss (historical
-                            balance value minus cost basis)
-     --budget[=DESCPAT]     show sum of posting amounts together with budget
-                            goals defined by periodic
-                            transactions. With a DESCPAT argument (must be
-                            separated by = not space),
-                            use only periodic transactions with matching
-                            description
-                            (case insensitive substring match).
-     --count                show the count of postings
-     --change               accumulate amounts from column start to column
-                            end (in multicolumn reports, default)
-     --cumulative           accumulate amounts from report start (specified
-                            by e.g. -b/--begin) to column end
-  -H --historical           accumulate amounts from journal start to column
-                            end (includes postings before report start date)
-  -l --flat                 show accounts as a flat list (default). Amounts
-                            exclude subaccount amounts, except where the
-                            account is depth-clipped.
-  -t --tree                 show accounts as a tree. Amounts include
-                            subaccount amounts.
-     --drop=N               omit N leading account name parts (in flat mode)
-     --declared             include non-parent declared accounts (best used
-                            with -E)
-  -A --average              show a row average column (in multicolumn
-                            reports)
-  -T --row-total            show a row total column (in multicolumn reports)
-     --summary-only         display only row summaries (e.g. row total,
-                            average) (in multicolumn reports)
-  -N --no-total             omit the final total row
-     --no-elide             don't squash boring parent accounts (in tree
-                            mode)
-     --format=FORMATSTR     use this custom line format (in simple reports)
-  -S --sort-amount          sort by amount instead of account code/name (in
-                            flat mode). With multiple columns, sorts by the row
-                            total, or by row average if that is displayed.
-  -% --percent              express values in percentage of each column's
-                            total
-  -r --related              show the other accounts transacted with, instead
-     --invert               display all amounts with reversed sign
-     --transpose            switch rows and columns (use vertical time axis)
-     --layout=ARG           how to lay out multi-commodity amounts and the
-                            overall table:
-                            'wide[,WIDTH]': commodities on one line
-                            'tall'        : commodities on separate lines
-                            'bare'        : commodity symbols in one column
-                            'tidy'        : every attribute in its own column
-     --base-url=URLPREFIX   in html output, generate links to hledger-web,
-                            with this prefix. (Usually the base url shown by
-                            hledger-web; can also be relative.)
-  -O --output-format=FMT    select the output format. Supported formats:
-                            txt, html, csv, tsv, json, fods.
-  -o --output-file=FILE     write output to FILE. A file extension matching
-                            one of the above formats selects that format.
-
-   'balance' is one of hledger's oldest and most versatile commands, for
-listing account balances, balance changes, values, value changes and
-more, during one time period or many.  Generally it shows a table, with
-rows representing accounts, and columns representing periods.
-
-   Note there are some higher-level variants of the 'balance' command
-with convenient defaults, which can be simpler to use: 'balancesheet',
-'balancesheetequity', 'cashflow' and 'incomestatement'.  When you need
-more control, then use 'balance'.
-
-* Menu:
-
-* balance features::
-* Simple balance report::
-* Balance report line format::
-* Filtered balance report::
-* List or tree mode::
-* Depth limiting::
-* Dropping top-level accounts::
-* Showing declared accounts::
-* Sorting by amount::
-* Percentages::
-* Multi-period balance report::
-* Balance change end balance::
-* Balance report types::
-* Budget report::
-* Balance report layout::
-* Balance report output::
-* Some useful balance reports::
-
-
-File: hledger.info,  Node: balance features,  Next: Simple balance report,  Up: balance
-
-29.1.1 balance features
------------------------
-
-Here's a quick overview of the 'balance' command's features, followed by
-more detailed descriptions and examples.  Many of these work with the
-higher-level commands as well.
-
-   'balance' can show..
-
-   * accounts as a list ('-l') or a tree ('-t')
-   * optionally depth-limited ('-[1-9]')
-   * sorted by declaration order and name, or by amount
-
-   ..and their..
-
-   * balance changes (the default)
-   * or actual and planned balance changes ('--budget')
-   * or value of balance changes ('-V')
-   * or change of balance values ('--valuechange')
-   * or unrealised capital gain/loss ('--gain')
-   * or balance changes from sibling postings ('--related'/'-r')
-   * or postings count ('--count')
-
-   ..in..
-
-   * one time period (the whole journal period by default)
-   * or multiple periods ('-D', '-W', '-M', '-Q', '-Y', '-p INTERVAL')
-
-   ..either..
-
-   * per period (the default)
-   * or accumulated since report start date ('--cumulative')
-   * or accumulated since account creation ('--historical/-H')
-
-   ..possibly converted to..
-
-   * cost ('--value=cost[,COMM]'/'--cost'/'-B')
-   * or market value, as of transaction dates ('--value=then[,COMM]')
-   * or at period ends ('--value=end[,COMM]')
-   * or now ('--value=now')
-   * or at some other date ('--value=YYYY-MM-DD')
-
-   ..with..
-
-   * totals ('-T'), averages ('-A'), percentages ('-%'), inverted sign
-     ('--invert')
-   * rows and columns swapped ('--transpose')
-   * another field used as account name ('--pivot')
-   * custom-formatted line items (single-period reports only)
-     ('--format')
-   * commodities displayed on the same line or multiple lines
-     ('--layout')
-
-   This command supports the output destination and output format
-options, with output formats 'txt', 'csv', 'tsv' (_Added in 1.32_),
-'json', and (multi-period reports only:) 'html', 'fods' (_Added in
-1.40_).  In 'txt' output in a colour-supporting terminal, negative
-amounts are shown in red.
-
-
-File: hledger.info,  Node: Simple balance report,  Next: Balance report line format,  Prev: balance features,  Up: balance
-
-29.1.2 Simple balance report
-----------------------------
-
-With no arguments, 'balance' shows a list of all accounts and their
-change of balance - ie, the sum of posting amounts, both inflows and
-outflows - during the entire period of the journal.  ("Simple" here
-means just one column of numbers, covering a single period.  You can
-also have multi-period reports, described later.)
-
-   For real-world accounts, these numbers will normally be their end
-balance at the end of the journal period; more on this below.
-
-   Accounts are sorted by declaration order if any, and then
-alphabetically by account name.  For instance (using
-examples/sample.journal):
-
-$ hledger -f examples/sample.journal bal
-                  $1  assets:bank:saving
-                 $-2  assets:cash
-                  $1  expenses:food
-                  $1  expenses:supplies
-                 $-1  income:gifts
-                 $-1  income:salary
-                  $1  liabilities:debts
---------------------
-                   0  
-
-   Accounts with a zero balance (and no non-zero subaccounts, in tree
-mode - see below) are hidden by default.  Use '-E/--empty' to show them
-(revealing 'assets:bank:checking' here):
-
-$ hledger -f examples/sample.journal bal  -E
-                   0  assets:bank:checking
-                  $1  assets:bank:saving
-                 $-2  assets:cash
-                  $1  expenses:food
-                  $1  expenses:supplies
-                 $-1  income:gifts
-                 $-1  income:salary
-                  $1  liabilities:debts
---------------------
-                   0  
-
-   The total of the amounts displayed is shown as the last line, unless
-'-N'/'--no-total' is used.
-
-
-File: hledger.info,  Node: Balance report line format,  Next: Filtered balance report,  Prev: Simple balance report,  Up: balance
-
-29.1.3 Balance report line format
----------------------------------
-
-For single-period balance reports displayed in the terminal (only), you
-can use '--format FMT' to customise the format and content of each line.
-Eg:
-
-$ hledger -f examples/sample.journal balance --format "%20(account) %12(total)"
-              assets          $-1
-         bank:saving           $1
-                cash          $-2
-            expenses           $2
-                food           $1
-            supplies           $1
-              income          $-2
-               gifts          $-1
-              salary          $-1
-   liabilities:debts           $1
----------------------------------
-                                0
-
-   The FMT format string specifies the formatting applied to each
-account/balance pair.  It may contain any suitable text, with data
-fields interpolated like so:
-
-   '%[MIN][.MAX](FIELDNAME)'
-
-   * MIN pads with spaces to at least this width (optional)
-
-   * MAX truncates at this width (optional)
-
-   * FIELDNAME must be enclosed in parentheses, and can be one of:
-
-        * 'depth_spacer' - a number of spaces equal to the account's
-          depth, or if MIN is specified, MIN * depth spaces.
-        * 'account' - the account's name
-        * 'total' - the account's balance/posted total, right justified
-
-   Also, FMT can begin with an optional prefix to control how
-multi-commodity amounts are rendered:
-
-   * '%_' - render on multiple lines, bottom-aligned (the default)
-   * '%^' - render on multiple lines, top-aligned
-   * '%,' - render on one line, comma-separated
-
-   There are some quirks.  Eg in one-line mode, '%(depth_spacer)' has no
-effect, instead '%(account)' has indentation built in.  Experimentation
-may be needed to get pleasing results.
-
-   Some example formats:
-
-   * '%(total)' - the account's total
-   * '%-20.20(account)' - the account's name, left justified, padded to
-     20 characters and clipped at 20 characters
-   * '%,%-50(account) %25(total)' - account name padded to 50
-     characters, total padded to 20 characters, with multiple
-     commodities rendered on one line
-   * '%20(total) %2(depth_spacer)%-(account)' - the default format for
-     the single-column balance report
-
-
-File: hledger.info,  Node: Filtered balance report,  Next: List or tree mode,  Prev: Balance report line format,  Up: balance
-
-29.1.4 Filtered balance report
-------------------------------
-
-You can show fewer accounts, a different time period, totals from
-cleared transactions only, etc.  by using query arguments or options to
-limit the postings being matched.  Eg:
-
-$ hledger -f examples/sample.journal bal --cleared assets date:200806
-                 $-2  assets:cash
---------------------
-                 $-2  
-
-
-File: hledger.info,  Node: List or tree mode,  Next: Depth limiting,  Prev: Filtered balance report,  Up: balance
-
-29.1.5 List or tree mode
-------------------------
-
-By default, or with '-l/--flat', accounts are shown as a flat list with
-their full names visible, as in the examples above.
-
-   With '-t/--tree', the account hierarchy is shown, with subaccounts'
-"leaf" names indented below their parent:
-
-$ hledger -f examples/sample.journal balance
-                 $-1  assets
-                  $1    bank:saving
-                 $-2    cash
-                  $2  expenses
-                  $1    food
-                  $1    supplies
-                 $-2  income
-                 $-1    gifts
-                 $-1    salary
-                  $1  liabilities:debts
---------------------
-                   0
-
-   Notes:
-
-   * "Boring" accounts are combined with their subaccount for more
-     compact output, unless '--no-elide' is used.  Boring accounts have
-     no balance of their own and just one subaccount (eg 'assets:bank'
-     and 'liabilities' above).
-
-   * All balances shown are "inclusive", ie including the balances from
-     all subaccounts.  Note this means some repetition in the output,
-     which requires explanation when sharing reports with
-     non-plaintextaccounting-users.  A tree mode report's final total is
-     the sum of the top-level balances shown, not of all the balances
-     shown.
-
-   * Each group of sibling accounts (ie, under a common parent) is
-     sorted separately.
-
-
-File: hledger.info,  Node: Depth limiting,  Next: Dropping top-level accounts,  Prev: List or tree mode,  Up: balance
-
-29.1.6 Depth limiting
----------------------
-
-With a 'depth:NUM' query, or '--depth NUM' option, or just '-NUM' (eg:
-'-3') balance reports will show accounts only to the specified depth,
-hiding the deeper subaccounts.  This can be useful for getting an
-overview without too much detail.
-
-   Account balances at the depth limit always include the balances from
-any deeper subaccounts (even in list mode).  Eg, limiting to depth 1:
-
-$ hledger -f examples/sample.journal balance -1
-                 $-1  assets
-                  $2  expenses
-                 $-2  income
-                  $1  liabilities
---------------------
-                   0  
-
-
-File: hledger.info,  Node: Dropping top-level accounts,  Next: Showing declared accounts,  Prev: Depth limiting,  Up: balance
-
-29.1.7 Dropping top-level accounts
-----------------------------------
-
-You can also hide one or more top-level account name parts, using
-'--drop NUM'.  This can be useful for hiding repetitive top-level
-account names:
-
-$ hledger -f examples/sample.journal bal expenses --drop 1
-                  $1  food
-                  $1  supplies
---------------------
-                  $2  
-
-
-File: hledger.info,  Node: Showing declared accounts,  Next: Sorting by amount,  Prev: Dropping top-level accounts,  Up: balance
-
-29.1.8 Showing declared accounts
---------------------------------
-
-With '--declared', accounts which have been declared with an account
-directive will be included in the balance report, even if they have no
-transactions.  (Since they will have a zero balance, you will also need
-'-E/--empty' to see them.)
-
-   More precisely, _leaf_ declared accounts (with no subaccounts) will
-be included, since those are usually the more useful in reports.
-
-   The idea of this is to be able to see a useful "complete" balance
-report, even when you don't have transactions in all of your declared
-accounts yet.
-
-
-File: hledger.info,  Node: Sorting by amount,  Next: Percentages,  Prev: Showing declared accounts,  Up: balance
-
-29.1.9 Sorting by amount
-------------------------
-
-With '-S/--sort-amount', accounts with the largest (most positive)
-balances are shown first.  Eg: 'hledger bal expenses -MAS' shows your
-biggest averaged monthly expenses first.  When more than one commodity
-is present, they will be sorted by the alphabetically earliest commodity
-first, and then by subsequent commodities (if an amount is missing a
-commodity, it is treated as 0).
-
-   Revenues and liability balances are typically negative, however, so
-'-S' shows these in reverse order.  To work around this, you can add
-'--invert' to flip the signs.  (Or, use one of the higher-level reports,
-which flip the sign automatically.  Eg: 'hledger incomestatement -MAS').
-
-
-File: hledger.info,  Node: Percentages,  Next: Multi-period balance report,  Prev: Sorting by amount,  Up: balance
-
-29.1.10 Percentages
--------------------
-
-With '-%/--percent', balance reports show each account's value expressed
-as a percentage of the (column) total.
-
-   Note it is not useful to calculate percentages if the amounts in a
-column have mixed signs.  In this case, make a separate report for each
-sign, eg:
-
-$ hledger bal -% amt:`>0`
-$ hledger bal -% amt:`<0`
-
-   Similarly, if the amounts in a column have mixed commodities, convert
-them to one commodity with '-B', '-V', '-X' or '--value', or make a
-separate report for each commodity:
-
-$ hledger bal -% cur:\\$
-$ hledger bal -% cur:€
-
-
-File: hledger.info,  Node: Multi-period balance report,  Next: Balance change end balance,  Prev: Percentages,  Up: balance
-
-29.1.11 Multi-period balance report
------------------------------------
-
-With a report interval (set by the '-D/--daily', '-W/--weekly',
-'-M/--monthly', '-Q/--quarterly', '-Y/--yearly', or '-p/--period' flag),
-'balance' shows a tabular report, with columns representing successive
-time periods (and a title):
-
-$ hledger -f examples/sample.journal bal --quarterly income expenses -E
-Balance changes in 2008:
-
-                   ||  2008q1  2008q2  2008q3  2008q4 
-===================++=================================
- expenses:food     ||       0      $1       0       0 
- expenses:supplies ||       0      $1       0       0 
- income:gifts      ||       0     $-1       0       0 
- income:salary     ||     $-1       0       0       0 
--------------------++---------------------------------
-                   ||     $-1      $1       0       0 
-
-   Notes:
-
-   * The report's start/end dates will be expanded, if necessary, to
-     fully encompass the displayed subperiods (so that the first and
-     last subperiods have the same duration as the others).
-   * Leading and trailing periods (columns) containing all zeroes are
-     not shown, unless '-E/--empty' is used.
-   * Accounts (rows) containing all zeroes are not shown, unless
-     '-E/--empty' is used.
-   * Amounts with many commodities are shown in abbreviated form, unless
-     '--no-elide' is used.
-   * Average and/or total columns can be added with the '-A/--average'
-     and '-T/--row-total' flags.
-   * The '--transpose' flag can be used to exchange rows and columns.
-   * The '--pivot FIELD' option causes a different transaction field to
-     be used as "account name".  See PIVOTING.
-   * The '--summary-only' flag ('--summary' also works) hides all but
-     the Total and Average columns (those should be enabled with
-     '--row-total' and '-A/--average').
-
-   Multi-period reports with many periods can be too wide for easy
-viewing in the terminal.  Here are some ways to handle that:
-
-   * Hide the totals row with '-N/--no-total'
-   * Filter to a single currency with 'cur:'
-   * Convert to a single currency with '-V [--infer-market-price]'
-   * Use a more compact layout like '--layout=bare'
-   * Maximize the terminal window
-   * Reduce the terminal's font size
-   * View with a pager like less, eg: 'hledger bal -D --color=yes | less
-     -RS'
-   * Output as CSV and use a CSV viewer like visidata ('hledger bal -D
-     -O csv | vd -f csv'), Emacs' csv-mode ('M-x csv-mode, C-c C-a'), or
-     a spreadsheet ('hledger bal -D -o a.csv && open a.csv')
-   * Output as HTML and view with a browser: 'hledger bal -D -o a.html
-     && open a.html'
-
-
-File: hledger.info,  Node: Balance change end balance,  Next: Balance report types,  Prev: Multi-period balance report,  Up: balance
-
-29.1.12 Balance change, end balance
------------------------------------
-
-It's important to be clear on the meaning of the numbers shown in
-balance reports.  Here is some terminology we use:
-
-   A *_balance change_* is the net amount added to, or removed from, an
-account during some period.
-
-   An *_end balance_* is the amount accumulated in an account as of some
-date (and some time, but hledger doesn't store that; assume end of day
-in your timezone).  It is the sum of previous balance changes.
-
-   We call it a *_historical end balance_* if it includes all balance
-changes since the account was created.  For a real world account, this
-means it will match the "historical record", eg the balances reported in
-your bank statements or bank web UI. (If they are correct!)
-
-   In general, balance changes are what you want to see when reviewing
-revenues and expenses, and historical end balances are what you want to
-see when reviewing or reconciling asset, liability and equity accounts.
-
-   'balance' shows balance changes by default.  To see accurate
-historical end balances:
-
-  1. Initialise account starting balances with an "opening balances"
-     transaction (a transfer from equity to the account), unless the
-     journal covers the account's full lifetime.
-
-  2. Include all of of the account's prior postings in the report, by
-     not specifying a report start date, or by using the
-     '-H/--historical' flag.  ('-H' causes report start date to be
-     ignored when summing postings.)
-
-
-File: hledger.info,  Node: Balance report types,  Next: Budget report,  Prev: Balance change end balance,  Up: balance
-
-29.1.13 Balance report types
-----------------------------
-
-The balance command is quite flexible; here is the full detail on how to
-control what it reports.  If the following seems complicated, don't
-worry - this is for advanced reporting, and it does take time and
-experimentation to get familiar with all the report modes.
-
-   There are three important option groups:
-
-   'hledger balance [CALCULATIONTYPE] [ACCUMULATIONTYPE] [VALUATIONTYPE]
-...'
-
-* Menu:
-
-* Calculation type::
-* Accumulation type::
-* Valuation type::
-* Combining balance report types::
-
-
-File: hledger.info,  Node: Calculation type,  Next: Accumulation type,  Up: Balance report types
-
-29.1.13.1 Calculation type
-..........................
-
-The basic calculation to perform for each table cell.  It is one of:
-
-   * '--sum' : sum the posting amounts (*default*)
-   * '--budget' : sum the amounts, but also show the budget goal amount
-     (for each account/period)
-   * '--valuechange' : show the change in period-end historical balance
-     values (caused by deposits, withdrawals, and/or market price
-     fluctuations)
-   * '--gain' : show the unrealised capital gain/loss, (the current
-     valued balance minus each amount's original cost)
-   * '--count' : show the count of postings
-
-
-File: hledger.info,  Node: Accumulation type,  Next: Valuation type,  Prev: Calculation type,  Up: Balance report types
-
-29.1.13.2 Accumulation type
-...........................
-
-How amounts should accumulate across a report's subperiods/columns.
-Another way to say it: which time period's postings should contribute to
-each cell's calculation.  It is one of:
-
-   * '--change' : calculate with postings from column start to column
-     end, ie "just this column".  Typically used to see
-     revenues/expenses.  (*default for balance, cashflow,
-     incomestatement*)
-
-   * '--cumulative' : calculate with postings from report start to
-     column end, ie "previous columns plus this column".  Typically used
-     to show changes accumulated since the report's start date.  Not
-     often used.
-
-   * '--historical/-H' : calculate with postings from journal start to
-     column end, ie "all postings from before report start date until
-     this column's end".  Typically used to see historical end balances
-     of assets/liabilities/equity.  (*default for balancesheet,
-     balancesheetequity*)
-
-
-File: hledger.info,  Node: Valuation type,  Next: Combining balance report types,  Prev: Accumulation type,  Up: Balance report types
-
-29.1.13.3 Valuation type
-........................
-
-Which kind of value or cost conversion should be applied, if any, before
-displaying the report.  It is one of:
-
-   * no valuation type : don't convert to cost or value (*default*)
-   * '--value=cost[,COMM]' : convert amounts to cost (then optionally to
-     some other commodity)
-   * '--value=then[,COMM]' : convert amounts to market value on
-     transaction dates
-   * '--value=end[,COMM]' : convert amounts to market value on period
-     end date(s)
-     (*default with '--valuechange', '--gain'*)
-   * '--value=now[,COMM]' : convert amounts to market value on today's
-     date
-   * '--value=YYYY-MM-DD[,COMM]' : convert amounts to market value on
-     another date
-
-   or one of the equivalent simpler flags:
-
-   * '-B/--cost' : like -value=cost (though, note -cost and -value are
-     independent options which can both be used at once)
-   * '-V/--market' : like -value=end
-   * '-X COMM/--exchange COMM' : like -value=end,COMM
-
-   See Cost reporting and Value reporting for more about these.
-
-
-File: hledger.info,  Node: Combining balance report types,  Prev: Valuation type,  Up: Balance report types
-
-29.1.13.4 Combining balance report types
-........................................
-
-Most combinations of these options should produce reasonable reports,
-but if you find any that seem wrong or misleading, let us know.  The
-following restrictions are applied:
-
-   * '--valuechange' implies '--value=end'
-   * '--valuechange' makes '--change' the default when used with the
-     'balancesheet'/'balancesheetequity' commands
-   * '--cumulative' or '--historical' disables '--row-total/-T'
-
-   For reference, here is what the combinations of accumulation and
-valuation show:
-
-Valuation:>no valuation    '--value= then'   '--value= end'   '--value=
-Accumulation:v                                                YYYY-MM-DD
-                                                              /now'
------------------------------------------------------------------------------
-'--change'change in        sum of            period-end       DATE-value
-         period            posting-date      value of         of change in
-                           market values     change in        period
-                           in period         period
-'--cumulative'change from  sum of            period-end       DATE-value
-         report start to   posting-date      value of         of change
-         period end        market values     change from      from report
-                           from report       report start     start to
-                           start to period   to period end    period end
-                           end
-'--historicalchange from   sum of            period-end       DATE-value
-/-H'     journal start     posting-date      value of         of change
-         to period end     market values     change from      from journal
-         (historical end   from journal      journal start    start to
-         balance)          start to period   to period end    period end
-                           end
-
-
-File: hledger.info,  Node: Budget report,  Next: Balance report layout,  Prev: Balance report types,  Up: balance
-
-29.1.14 Budget report
----------------------
-
-The '--budget' report type is like a regular balance report, but with
-two main differences:
-
-   * Budget goals and performance percentages are also shown, in
-     brackets
-   * Accounts which don't have budget goals are hidden by default.
-
-   This is useful for comparing planned and actual income, expenses,
-time usage, etc.
-
-   Periodic transaction rules are used to define budget goals.  For
-example, here's a periodic rule defining monthly goals for bus travel
-and food expenses:
-
-;; Budget
-~ monthly
-  (expenses:bus)              $30
-  (expenses:food)            $400
-
-   After recording some actual expenses,
-
-;; Two months worth of expenses
-2017-11-01
-  income                   $-1950
-  expenses:bus                $35
-  expenses:food:groceries    $310
-  expenses:food:dining        $42
-  expenses:movies             $38
-  assets:bank:checking
-
-2017-12-01
-  income                   $-2100
-  expenses:bus                $53
-  expenses:food:groceries    $380
-  expenses:food:dining        $32
-  expenses:gifts             $100
-  assets:bank:checking
-
-   we can see a budget report like this:
-
-$ hledger bal -M --budget
-Budget performance in 2017-11-01..2017-12-31:
-
-               ||                  Nov                   Dec 
-===============++============================================
- <unbudgeted>  || $-425                 $-565                
- expenses      ||  $425 [ 99% of $430]   $565 [131% of $430] 
- expenses:bus  ||   $35 [117% of  $30]    $53 [177% of  $30] 
- expenses:food ||  $352 [ 88% of $400]   $412 [103% of $400] 
----------------++--------------------------------------------
-               ||     0 [  0% of $430]      0 [  0% of $430] 
-
-   This is "goal-based budgeting"; you define goals for accounts and
-periods, often recurring, and hledger shows performance relative to the
-goals.  This contrasts with "envelope budgeting", which is more detailed
-and strict - useful when cash is tight, but also quite a bit more work.
-https://plaintextaccounting.org/Budgeting has more on this topic.
-
-* Menu:
-
-* Using the budget report::
-* Budget date surprises::
-* Selecting budget goals::
-* Budgeting vs forecasting::
-
-
-File: hledger.info,  Node: Using the budget report,  Next: Budget date surprises,  Up: Budget report
-
-29.1.14.1 Using the budget report
-.................................
-
-Historically this report has been confusing and fragile.  hledger's
-version should be relatively robust and intuitive, but you may still
-find surprises.  Here are more notes to help with learning and
-troubleshooting.
-
-   * In the above example, 'expenses:bus' and 'expenses:food' are shown
-     because they have budget goals during the report period.
-
-   * Their parent 'expenses' is also shown, with budget goals aggregated
-     from the children.
-
-   * The subaccounts 'expenses:food:groceries' and
-     'expenses:food:dining' are not shown since they have no budget goal
-     of their own, but they contribute to 'expenses:food''s actual
-     amount.
-
-   * Unbudgeted accounts 'expenses:movies' and 'expenses:gifts' are also
-     not shown, but they contribute to 'expenses''s actual amount.
-
-   * The other unbudgeted accounts 'income' and 'assets:bank:checking'
-     are grouped as '<unbudgeted>'.
-
-   * '--depth' or 'depth:' can be used to limit report depth in the
-     usual way (but will not reveal unbudgeted subaccounts).
-
-   * Amounts are always inclusive of subaccounts (even in '-l/--list'
-     mode).
-
-   * Numbers displayed in a -budget report will not always agree with
-     the totals, because of hidden unbudgeted accounts; this is normal.
-     '-E/--empty' can be used to reveal the hidden accounts.
-
-   * In the periodic rules used for setting budget goals, unbalanced
-     postings are convenient.
-
-   * You can filter budget reports with the usual queries, eg to focus
-     on particular accounts.  It's common to restrict them to just
-     expenses.  (The '<unbudgeted>' account is occasionally hard to
-     exclude; this is because of date surprises, discussed below.)
-
-   * When you have multiple currencies, you may want to convert them to
-     one ('-X COMM --infer-market-prices') and/or show just one at a
-     time ('cur:COMM').  If you do need to show multiple currencies at
-     once, '--layout bare' can be helpful.
-
-   * You can "roll over" amounts (actual and budgeted) to the next
-     period with '--cumulative'.
-
-   See also: https://hledger.org/budgeting.html.
-
-
-File: hledger.info,  Node: Budget date surprises,  Next: Selecting budget goals,  Prev: Using the budget report,  Up: Budget report
-
-29.1.14.2 Budget date surprises
-...............................
-
-With small data, or when starting out, some of the generated budget goal
-transaction dates might fall outside the report periods.  Eg with the
-following journal and report, the first period appears to have no
-'expenses:food' budget.  (Also the '<unbudgeted>' account should be
-excluded by the 'expenses' query, but isn't.):
-
-~ monthly in 2020
-  (expenses:food)  $500
-
-2020-01-15
-  expenses:food    $400
-  assets:checking
-
-$ hledger bal --budget expenses
-Budget performance in 2020-01-15:
-
-               ||         2020-01-15 
-===============++====================
- <unbudgeted>  || $400               
- expenses:food ||    0 [ 0% of $500] 
----------------++--------------------
-               || $400 [80% of $500] 
-
-   In this case, the budget goal transactions are generated on first
-days of of month (this can be seen with 'hledger print --forecast
-tag:generated expenses').  Whereas the report period defaults to just
-the 15th day of january (this can be seen from the report table's column
-headings).
-
-   To fix this kind of thing, be more explicit about the report period
-(and/or the periodic rules' dates).  In this case, adding '-b 2020' does
-the trick.
-
-
-File: hledger.info,  Node: Selecting budget goals,  Next: Budgeting vs forecasting,  Prev: Budget date surprises,  Up: Budget report
-
-29.1.14.3 Selecting budget goals
-................................
-
-By default, the budget report uses all available periodic transaction
-rules to generate goals.  This includes rules with a different report
-interval from your report.  Eg if you have daily, weekly and monthly
-periodic rules, all of these will contribute to the goals in a monthly
-budget report.
-
-   You can select a subset of periodic rules by providing an argument to
-the '--budget' flag.  '--budget=DESCPAT' will match all periodic rules
-whose description contains DESCPAT, a case-insensitive substring (not a
-regular expression or query).  This means you can give your periodic
-rules descriptions (remember that two spaces are needed between period
-expression and description), and then select from multiple budgets
-defined in your journal.
-
-
-File: hledger.info,  Node: Budgeting vs forecasting,  Prev: Selecting budget goals,  Up: Budget report
-
-29.1.14.4 Budgeting vs forecasting
-..................................
-
-'--forecast' and '--budget' both use the periodic transaction rules in
-the journal to generate temporary transactions for reporting purposes.
-However they are separate features - though you can use both at the same
-time if you want.  Here are some differences between them:
-
--forecast                                -budget
---------------------------------------------------------------------------
-is a general option; it enables          is a balance command option;
-forecasting with all reports             it selects the balance
-                                         report's budget mode
-generates visible transactions which     generates invisible
-appear in reports                        transactions which produce
-                                         goal amounts
-generates forecast transactions from     generates budget goal
-after the last regular transaction, to   transactions throughout the
-the end of the report period; or with    report period, optionally
-an argument '--forecast=PERIODEXPR'      restricted by periods
-generates them throughout the            specified in the periodic
-specified period, both optionally        transaction rules
-restricted by periods specified in the
-periodic transaction rules
-uses all periodic rules                  uses all periodic rules; or
-                                         with an argument
-                                         '--budget=DESCPAT' uses just
-                                         the rules matched by DESCPAT
-
-
-File: hledger.info,  Node: Balance report layout,  Next: Balance report output,  Prev: Budget report,  Up: balance
-
-29.1.15 Balance report layout
------------------------------
-
-The '--layout' option affects how 'balance' and the other balance-like
-commands show multi-commodity amounts and commodity symbols.  It can
-improve readability, for humans and/or machines (other software).  It
-has four possible values:
-
-   * '--layout=wide[,WIDTH]': commodities are shown on a single line,
-     optionally elided to WIDTH
-   * '--layout=tall': each commodity is shown on a separate line
-   * '--layout=bare': commodity symbols are in their own column, amounts
-     are bare numbers
-   * '--layout=tidy': data is normalised to easily-consumed "tidy" form,
-     with one row per data value.  (This one is currently supported only
-     by the 'balance' command.)
-
-   Here are the '--layout' modes supported by each output format Only
-CSV output supports all of them:
-
--      txt   csv   html   json   sql
----------------------------------------
-wide   Y     Y     Y
-tall   Y     Y     Y
-bare   Y     Y     Y
-tidy         Y
-
-   Examples:
-
-* Menu:
-
-* Wide layout::
-* Tall layout::
-* Bare layout::
-* Tidy layout::
-
-
-File: hledger.info,  Node: Wide layout,  Next: Tall layout,  Up: Balance report layout
-
-29.1.15.1 Wide layout
-.....................
-
-With many commodities, reports can be very wide:
-
-$ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=wide
-Balance changes in 2012-01-01..2014-12-31:
-
-                  ||                                          2012                                                     2013                                             2014                                                      Total 
-==================++====================================================================================================================================================================================================================
- Assets:US:ETrade || 10.00 ITOT, 337.18 USD, 12.00 VEA, 106.00 VHT  70.00 GLD, 18.00 ITOT, -98.12 USD, 10.00 VEA, 18.00 VHT  -11.00 ITOT, 4881.44 USD, 14.00 VEA, 170.00 VHT  70.00 GLD, 17.00 ITOT, 5120.50 USD, 36.00 VEA, 294.00 VHT 
-------------------++--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
-                  || 10.00 ITOT, 337.18 USD, 12.00 VEA, 106.00 VHT  70.00 GLD, 18.00 ITOT, -98.12 USD, 10.00 VEA, 18.00 VHT  -11.00 ITOT, 4881.44 USD, 14.00 VEA, 170.00 VHT  70.00 GLD, 17.00 ITOT, 5120.50 USD, 36.00 VEA, 294.00 VHT 
-
-   A width limit reduces the width, but some commodities will be hidden:
-
-$ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=wide,32
-Balance changes in 2012-01-01..2014-12-31:
-
-                  ||                             2012                             2013                   2014                            Total 
-==================++===========================================================================================================================
- Assets:US:ETrade || 10.00 ITOT, 337.18 USD, 2 more..  70.00 GLD, 18.00 ITOT, 3 more..  -11.00 ITOT, 3 more..  70.00 GLD, 17.00 ITOT, 3 more.. 
-------------------++---------------------------------------------------------------------------------------------------------------------------
-                  || 10.00 ITOT, 337.18 USD, 2 more..  70.00 GLD, 18.00 ITOT, 3 more..  -11.00 ITOT, 3 more..  70.00 GLD, 17.00 ITOT, 3 more.. 
-
-
-File: hledger.info,  Node: Tall layout,  Next: Bare layout,  Prev: Wide layout,  Up: Balance report layout
-
-29.1.15.2 Tall layout
-.....................
-
-Each commodity gets a new line (may be different in each column), and
-account names are repeated:
-
-$ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=tall
-Balance changes in 2012-01-01..2014-12-31:
-
-                  ||       2012        2013         2014        Total 
-==================++==================================================
- Assets:US:ETrade || 10.00 ITOT   70.00 GLD  -11.00 ITOT    70.00 GLD 
- Assets:US:ETrade || 337.18 USD  18.00 ITOT  4881.44 USD   17.00 ITOT 
- Assets:US:ETrade ||  12.00 VEA  -98.12 USD    14.00 VEA  5120.50 USD 
- Assets:US:ETrade || 106.00 VHT   10.00 VEA   170.00 VHT    36.00 VEA 
- Assets:US:ETrade ||              18.00 VHT                294.00 VHT 
-------------------++--------------------------------------------------
-                  || 10.00 ITOT   70.00 GLD  -11.00 ITOT    70.00 GLD 
-                  || 337.18 USD  18.00 ITOT  4881.44 USD   17.00 ITOT 
-                  ||  12.00 VEA  -98.12 USD    14.00 VEA  5120.50 USD 
-                  || 106.00 VHT   10.00 VEA   170.00 VHT    36.00 VEA 
-                  ||              18.00 VHT                294.00 VHT 
-
-
-File: hledger.info,  Node: Bare layout,  Next: Tidy layout,  Prev: Tall layout,  Up: Balance report layout
-
-29.1.15.3 Bare layout
-.....................
-
-Commodity symbols are kept in one column, each commodity has its own
-row, amounts are bare numbers, account names are repeated:
-
-$ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=bare
-Balance changes in 2012-01-01..2014-12-31:
-
-                  || Commodity    2012    2013     2014    Total 
-==================++=============================================
- Assets:US:ETrade || GLD             0   70.00        0    70.00 
- Assets:US:ETrade || ITOT        10.00   18.00   -11.00    17.00 
- Assets:US:ETrade || USD        337.18  -98.12  4881.44  5120.50 
- Assets:US:ETrade || VEA         12.00   10.00    14.00    36.00 
- Assets:US:ETrade || VHT        106.00   18.00   170.00   294.00 
-------------------++---------------------------------------------
-                  || GLD             0   70.00        0    70.00 
-                  || ITOT        10.00   18.00   -11.00    17.00 
-                  || USD        337.18  -98.12  4881.44  5120.50 
-                  || VEA         12.00   10.00    14.00    36.00 
-                  || VHT        106.00   18.00   170.00   294.00 
-
-   Bare layout also affects CSV output, which is useful for producing
-data that is easier to consume, eg for making charts:
-
-$ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -O csv --layout=bare
-"account","commodity","balance"
-"Assets:US:ETrade","GLD","70.00"
-"Assets:US:ETrade","ITOT","17.00"
-"Assets:US:ETrade","USD","5120.50"
-"Assets:US:ETrade","VEA","36.00"
-"Assets:US:ETrade","VHT","294.00"
-"Total:","GLD","70.00"
-"Total:","ITOT","17.00"
-"Total:","USD","5120.50"
-"Total:","VEA","36.00"
-"Total:","VHT","294.00"
-
-   Bare layout will sometimes display an extra row for the no-symbol
-commodity, because of zero amounts (hledger treats zeroes as
-commodity-less, usually).  This can break 'hledger-bar' confusingly
-(workaround: add a 'cur:' query to exclude the no-symbol row).
-
-
-File: hledger.info,  Node: Tidy layout,  Prev: Bare layout,  Up: Balance report layout
-
-29.1.15.4 Tidy layout
-.....................
-
-This produces normalised "tidy data" (see
-https://cran.r-project.org/web/packages/tidyr/vignettes/tidy-data.html)
-where every variable has its own column and each row represents a single
-data point.  This is the easiest kind of data for other software to
-consume:
-
-$ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -Y -O csv --layout=tidy
-"account","period","start_date","end_date","commodity","value"
-"Assets:US:ETrade","2012","2012-01-01","2012-12-31","GLD","0"
-"Assets:US:ETrade","2012","2012-01-01","2012-12-31","ITOT","10.00"
-"Assets:US:ETrade","2012","2012-01-01","2012-12-31","USD","337.18"
-"Assets:US:ETrade","2012","2012-01-01","2012-12-31","VEA","12.00"
-"Assets:US:ETrade","2012","2012-01-01","2012-12-31","VHT","106.00"
-"Assets:US:ETrade","2013","2013-01-01","2013-12-31","GLD","70.00"
-"Assets:US:ETrade","2013","2013-01-01","2013-12-31","ITOT","18.00"
-"Assets:US:ETrade","2013","2013-01-01","2013-12-31","USD","-98.12"
-"Assets:US:ETrade","2013","2013-01-01","2013-12-31","VEA","10.00"
-"Assets:US:ETrade","2013","2013-01-01","2013-12-31","VHT","18.00"
-"Assets:US:ETrade","2014","2014-01-01","2014-12-31","GLD","0"
-"Assets:US:ETrade","2014","2014-01-01","2014-12-31","ITOT","-11.00"
-"Assets:US:ETrade","2014","2014-01-01","2014-12-31","USD","4881.44"
-"Assets:US:ETrade","2014","2014-01-01","2014-12-31","VEA","14.00"
-"Assets:US:ETrade","2014","2014-01-01","2014-12-31","VHT","170.00"
-
-
-File: hledger.info,  Node: Balance report output,  Next: Some useful balance reports,  Prev: Balance report layout,  Up: balance
-
-29.1.16 Balance report output
------------------------------
-
-As noted in Output format, if you choose HTML output (by using '-O html'
-or '-o somefile.html'), it will use the UTF-8 text encoding, And you can
-create a 'hledger.css' file in the same directory to customise the
-report's appearance.
-
-   The HTML and FODS output formats can generate hyperlinks to a
-'hledger-web' register view for each account and period.  E.g.  if your
-'hledger-web' server is reachable at 'http://localhost:5000' then you
-might run the 'balance' command with the extra option
-'--base-url=http://localhost:5000'.  You can also produce relative
-links, like '--base-url="some/path"' or '--base-url=""'.)
-
-   The balance reports' HTML output currently does not indent tree mode
-reports properly (#1846).  So in HTML balance reports, use list mode for
-now (it is the default).
-
-
-File: hledger.info,  Node: Some useful balance reports,  Prev: Balance report output,  Up: balance
-
-29.1.17 Some useful balance reports
------------------------------------
-
-Some frequently used 'balance' options/reports are:
-
-   * 'bal -M revenues expenses'
-     Show revenues/expenses in each month.  Also available as the
-     'incomestatement' command.
-
-   * 'bal -M -H assets liabilities'
-     Show historical asset/liability balances at each month end.  Also
-     available as the 'balancesheet' command.
-
-   * 'bal -M -H assets liabilities equity'
-     Show historical asset/liability/equity balances at each month end.
-     Also available as the 'balancesheetequity' command.
-
-   * 'bal -M assets not:receivable'
-     Show changes to liquid assets in each month.  Also available as the
-     'cashflow' command.
-
-   Also:
-
-   * 'bal -M expenses -2 -SA'
-     Show monthly expenses summarised to depth 2 and sorted by average
-     amount.
-
-   * 'bal -M --budget expenses'
-     Show monthly expenses and budget goals.
-
-   * 'bal -M --valuechange investments'
-     Show monthly change in market value of investment assets.
-
-   * 'bal investments --valuechange -D date:lastweek amt:'>1000' -STA
-     [--invert]'
-     Show top gainers [or losers] last week
-
-
-File: hledger.info,  Node: roi,  Prev: balance,  Up: Advanced report commands
-
-29.2 roi
-========
-
-Shows the time-weighted (TWR) and money-weighted (IRR) rate of return on
-your investments.
-
-Flags:
-     --cashflow                 show all amounts that were used to compute
-                                returns
-     --investment=QUERY         query to select your investment transactions
-     --profit-loss=QUERY --pnl  query to select profit-and-loss or
-                                appreciation/valuation transactions
-
-   At a minimum, you need to supply a query (which could be just an
-account name) to select your investment(s) with '--inv', and another
-query to identify your profit and loss transactions with '--pnl'.
-
-   If you do not record changes in the value of your investment
-manually, or do not require computation of time-weighted return (TWR),
-'--pnl' could be an empty query ('--pnl ""' or '--pnl STR' where 'STR'
-does not match any of your accounts).
-
-   This command will compute and display the internalized rate of return
-(IRR, also known as money-weighted rate of return) and time-weighted
-rate of return (TWR) for your investments for the time period requested.
-IRR is always annualized due to the way it is computed, but TWR is
-reported both as a rate over the chosen reporting period and as an
-annual rate.
-
-   Price directives will be taken into account if you supply appropriate
-'--cost' or '--value' flags (see VALUATION).
-
-   Note, in some cases this report can fail, for these reasons:
-
-   * Error (NotBracketed): No solution for Internal Rate of Return
-     (IRR). Possible causes: IRR is huge (>1000000%), balance of
-     investment becomes negative at some point in time.
-   * Error (SearchFailed): Failed to find solution for Internal Rate of
-     Return (IRR). Either search does not converge to a solution, or
-     converges too slowly.
-
-   Examples:
-
-   * Using roi to compute total return of investment in stocks:
-     https://github.com/simonmichael/hledger/blob/master/examples/investing/roi-unrealised.ledger
-
-   * Cookbook > Return on Investment: https://hledger.org/roi.html
-
-* Menu:
-
-* Spaces and special characters in --inv and --pnl::
-* Semantics of --inv and --pnl::
-* IRR and TWR explained::
-
-
-File: hledger.info,  Node: Spaces and special characters in --inv and --pnl,  Next: Semantics of --inv and --pnl,  Up: roi
-
-29.2.1 Spaces and special characters in '--inv' and
----------------------------------------------------
-
-'--pnl' Note that '--inv' and '--pnl''s argument is a query, and queries
-could have several space-separated terms (see QUERIES).
-
-   To indicate that all search terms form single command-line argument,
-you will need to put them in quotes (see Special characters):
-
-$ hledger roi --inv 'term1 term2 term3 ...'
-
-   If any query terms contain spaces themselves, you will need an extra
-level of nested quoting, eg:
-
-$ hledger roi --inv="'Assets:Test 1'" --pnl="'Equity:Unrealized Profit and Loss'"
-
-
-File: hledger.info,  Node: Semantics of --inv and --pnl,  Next: IRR and TWR explained,  Prev: Spaces and special characters in --inv and --pnl,  Up: roi
-
-29.2.2 Semantics of '--inv' and '--pnl'
----------------------------------------
-
-Query supplied to '--inv' has to match all transactions that are related
-to your investment.  Transactions not matching '--inv' will be ignored.
-
-   In these transactions, ROI will conside postings that match '--inv'
-to be "investment postings" and other postings (not matching '--inv')
-will be sorted into two categories: "cash flow" and "profit and loss",
-as ROI needs to know which part of the investment value is your
-contributions and which is due to the return on investment.
-
-   * "Cash flow" is depositing or withdrawing money, buying or selling
-     assets, or otherwise converting between your investment commodity
-     and any other commodity.  Example:
-
-     2019-01-01 Investing in Snake Oil
-       assets:cash          -$100
-       investment:snake oil
-     
-     2020-01-01 Selling my Snake Oil
-       assets:cash           $10
-       investment:snake oil  = 0
-
-   * "Profit and loss" is change in the value of your investment:
-
-     2019-06-01 Snake Oil falls in value
-       investment:snake oil  = $57
-       equity:unrealized profit or loss
-
-   All non-investment postings are assumed to be "cash flow", unless
-they match '--pnl' query.  Changes in value of your investment due to
-"profit and loss" postings will be considered as part of your investment
-return.
-
-   Example: if you use '--inv snake --pnl equity:unrealized', then
-postings in the example below would be classifed as:
-
-2019-01-01 Snake Oil #1
-  assets:cash          -$100   ; cash flow posting
-  investment:snake oil         ; investment posting
-
-2019-03-01 Snake Oil #2
-  equity:unrealized pnl  -$100 ; profit and loss posting
-  snake oil                    ; investment posting
-
-2019-07-01 Snake Oil #3
-  equity:unrealized pnl        ; profit and loss posting
-  cash          -$100          ; cash flow posting
-  snake oil     $50            ; investment posting
-
-
-File: hledger.info,  Node: IRR and TWR explained,  Prev: Semantics of --inv and --pnl,  Up: roi
-
-29.2.3 IRR and TWR explained
-----------------------------
-
-"ROI" stands for "return on investment".  Traditionally this was
-computed as a difference between current value of investment and its
-initial value, expressed in percentage of the initial value.
-
-   However, this approach is only practical in simple cases, where
-investments receives no in-flows or out-flows of money, and where rate
-of growth is fixed over time.  For more complex scenarios you need
-different ways to compute rate of return, and this command implements
-two of them: IRR and TWR.
-
-   Internal rate of return, or "IRR" (also called "money-weighted rate
-of return") takes into account effects of in-flows and out-flows, and
-the time between them.  Investment at a particular fixed interest rate
-is going to give you more interest than the same amount invested at the
-same interest rate, but made later in time.  If you are withdrawing from
-your investment, your future gains would be smaller (in absolute
-numbers), and will be a smaller percentage of your initial investment,
-so your IRR will be smaller.  And if you are adding to your investment,
-you will receive bigger absolute gains, which will be a bigger
-percentage of your initial investment, so your IRR will be larger.
-
-   As mentioned before, in-flows and out-flows would be any cash that
-you personally put in or withdraw, and for the "roi" command, these are
-the postings that match the query in the'--inv' argument and NOT match
-the query in the'--pnl' argument.
-
-   If you manually record changes in the value of your investment as
-transactions that balance them against "profit and loss" (or "unrealized
-gains") account or use price directives, then in order for IRR to
-compute the precise effect of your in-flows and out-flows on the rate of
-return, you will need to record the value of your investement on or
-close to the days when in- or out-flows occur.
-
-   In technical terms, IRR uses the same approach as computation of net
-present value, and tries to find a discount rate that makes net present
-value of all the cash flows of your investment to add up to zero.  This
-could be hard to wrap your head around, especially if you haven't done
-discounted cash flow analysis before.  Implementation of IRR in hledger
-should produce results that match the '=XIRR' formula in Excel.
-
-   Second way to compute rate of return that 'roi' command implements is
-called "time-weighted rate of return" or "TWR". Like IRR, it will
-account for the effect of your in-flows and out-flows, but unlike IRR it
-will try to compute the true rate of return of the underlying asset,
-compensating for the effect that deposits and withdrawas have on the
-apparent rate of growth of your investment.
-
-   TWR represents your investment as an imaginary "unit fund" where
-in-flows/ out-flows lead to buying or selling "units" of your investment
-and changes in its value change the value of "investment unit".  Change
-in "unit price" over the reporting period gives you rate of return of
-your investment, and make TWR less sensitive than IRR to the effects of
-cash in-flows and out-flows.
-
-   References:
-
-   * Explanation of rate of return
-   * Explanation of IRR
-   * Explanation of TWR
-   * IRR vs TWR
-   * Examples of computing IRR and TWR and discussion of the limitations
-     of both metrics
-
-
-File: hledger.info,  Node: Chart commands,  Next: Data generation commands,  Prev: Advanced report commands,  Up: Top
-
-30 Chart commands
-*****************
-
-* Menu:
-
-* activity::
-
-
-File: hledger.info,  Node: activity,  Up: Chart commands
-
-30.1 activity
-=============
-
-Show an ascii barchart of posting counts per interval.
-
-Flags:
-no command-specific flags
-
-   The activity command displays an ascii histogram showing transaction
-counts by day, week, month or other reporting interval (by day is the
-default).  With query arguments, it counts only matched transactions.
-
-   Examples:
-
-$ hledger activity --quarterly
-2008-01-01 **
-2008-04-01 *******
-2008-07-01 
-2008-10-01 **
-
-
-File: hledger.info,  Node: Data generation commands,  Next: Maintenance commands,  Prev: Chart commands,  Up: Top
-
-31 Data generation commands
-***************************
-
-* Menu:
-
-* close::
-* rewrite::
-
-
-File: hledger.info,  Node: close,  Next: rewrite,  Up: Data generation commands
-
-31.1 close
-==========
-
-(equity)
-
-   'close' generates several kinds of "closing" and/or "opening"
-transactions, useful in certain situations, including migrating balances
-to a new journal file, retaining earnings into equity, consolidating
-balances, or viewing lots.  Like 'print', it prints valid journal
-entries.  You can append or copy these to your journal file(s) when you
-are happy with how they look.
-
-Flags:
-     --migrate[=NEW]        show closing and opening transactions, for Asset
-                            and Liability accounts by default, tagged for easy
-                            matching. The tag's default value can be overridden
-                            by providing NEW.
-     --close[=NEW]          (default) show a closing transaction
-     --open[=NEW]           show an opening transaction
-     --assign[=NEW]         show opening balance assignments
-     --assert[=NEW]         show closing balance assertions
-     --retain[=NEW]         show a retain earnings transaction, for Revenue
-                            and Expense accounts by default
-  -x --explicit             show all amounts explicitly
-     --show-costs           show amounts with different costs separately
-     --interleaved          show source and destination postings together
-     --assertion-type=TYPE  =, ==, =* or ==*
-     --close-desc=DESC      set closing transaction's description
-     --close-acct=ACCT      set closing transaction's destination account
-     --open-desc=DESC       set opening transaction's description
-     --open-acct=ACCT       set opening transaction's source account
-     --round=TYPE           how much rounding or padding should be done when
-                            displaying amounts ?
-                            none - show original decimal digits,
-                                   as in journal
-                            soft - just add or remove decimal zeros
-                                   to match precision (default)
-                            hard - round posting amounts to precision
-                                   (can unbalance transactions)
-                            all  - also round cost amounts to precision
-                                   (can unbalance transactions)
-
-   'close' currently has six modes, selected by a single mode flag:
-
-* Menu:
-
-* close --migrate::
-* close --close::
-* close --open::
-* close --assert::
-* close --assign::
-* close --retain::
-* close customisation::
-* close and balance assertions::
-* close examples::
-
-
-File: hledger.info,  Node: close --migrate,  Next: close --close,  Up: close
-
-31.1.1 close -migrate
----------------------
-
-This is the most common mode.  It prints a "closing balances"
-transaction that zeroes out all asset and liability balances (by
-default), and an opposite "opening balances" transaction that restores
-them again.  The balancing account will be 'equity:opening/closing
-balances' (or another specified by '--close-acct' or '--open-acct').
-
-   This is useful when migrating balances to a new journal file at the
-start of a new year.  Essentially, you run 'hledger close
---migrate=NEWYEAR -e NEWYEAR' and then copy the closing transaction to
-the end of the old file and the opening transaction to the start of the
-new file.  The opening transaction sets correct starting balances in the
-new file when it is used alone, and the closing transaction keeps
-balances correct when you use both old and new files together, by
-cancelling out the following opening transaction and preventing buildup
-of duplicated opening balances.  Think of the closing/opening pair as
-"moving the balances into the next file".
-
-   You can close a different set of accounts by providing a query.  Eg
-if you want to include equity, you can add 'assets liabilities equity'
-or 'type:ALE' arguments.  (The balancing account is always excluded.)
-Revenues and expenses usually are not migrated to a new file directly;
-see '--retain' below.
-
-   The generated transactions will have a 'start:' tag, with its value
-set to '--migrate''s 'NEW' argument if any, for easier matching or
-exclusion.  When 'NEW' is not specified, it will be inferred if possible
-by incrementing a number (eg a year number) within the default journal's
-main file name.  The other modes behave similarly.
-
-
-File: hledger.info,  Node: close --close,  Next: close --open,  Prev: close --migrate,  Up: close
-
-31.1.2 close -close
--------------------
-
-This prints just the closing balances transaction of '--migrate'.  It is
-the default behaviour if you specify no mode flag.  Using the
-customisation options below, you can move balances from any set of
-accounts to a different account.
-
-
-File: hledger.info,  Node: close --open,  Next: close --assert,  Prev: close --close,  Up: close
-
-31.1.3 close -open
-------------------
-
-This prints just the opening balances transaction of '--migrate'.  It is
-similar to Ledger's equity command.
-
-
-File: hledger.info,  Node: close --assert,  Next: close --assign,  Prev: close --open,  Up: close
-
-31.1.4 close -assert
---------------------
-
-This prints a "closing balances" transaction (with 'balances:' tag),
-that just declares balance assertions for the current balances without
-changing them.  It could be useful as documention and to guard against
-changes.
-
-
-File: hledger.info,  Node: close --assign,  Next: close --retain,  Prev: close --assert,  Up: close
-
-31.1.5 close -assign
---------------------
-
-This prints an "opening balances" transaction that restores the account
-balances using balance assignments.  Balance assignments work regardless
-of any previous balance, so a preceding closing balances transaction is
-not needed.
-
-   However, omitting the closing balances transaction would unbalance
-equity.  This is relatively harmless for personal reports, but it
-disturbs the accounting equation, removing a source of error detection.
-So '--migrate' is generally the best way to set to set balances in new
-files, for now.
-
-
-File: hledger.info,  Node: close --retain,  Next: close customisation,  Prev: close --assign,  Up: close
-
-31.1.6 close -retain
---------------------
-
-This is like '--close' with different defaults: it prints a "retain
-earnings" transaction (with 'retain:' tag), that transfers revenue and
-expense balances to 'equity:retained earnings'.
-
-   This is a different kind of closing, called "retaining earnings" or
-"closing the books"; it is traditionally performed by businesses at the
-end of each accounting period, to consolidate revenues and expenses into
-the main equity balance.  ("Revenues" and "expenses" are actually equity
-by another name, kept separate temporarily for reporting purposes.)
-
-   In personal accounting you generally don't need to do this, unless
-you want the 'balancesheetequity' report to show a zero total,
-demonstrating that the accounting equation (A-L=E) is satisfied.
-
-
-File: hledger.info,  Node: close customisation,  Next: close and balance assertions,  Prev: close --retain,  Up: close
-
-31.1.7 close customisation
---------------------------
-
-In all modes, the following things can be overridden:
-
-   * the accounts to be closed/opened, with account query arguments
-   * the balancing account, with '--close-acct=ACCT' and/or
-     '--open-acct=ACCT'
-   * the transaction descriptions, with '--close-desc=DESC' and
-     '--open-desc=DESC'
-   * the transaction's tag value, with a '--MODE=NEW' option argument
-   * the closing/opening dates, with '-e OPENDATE'
-
-   By default, the closing date is yesterday, or the journal's end date,
-whichever is later; and the opening date is always one day after the
-closing date.  You can change these by specifying a report end date; the
-closing date will be the last day of the report period.  Eg '-e 2024'
-means "close on 2023-12-31, open on 2024-01-01".
-
-   With '--x/--explicit', the balancing amount will be shown explicitly,
-and if it involves multiple commodities, a separate posting will be
-generated for each of them (similar to 'print -x').
-
-   With '--interleaved', each individual transfer is shown with source
-and destination postings next to each other (perhaps useful for
-troubleshooting).
-
-   With '--show-costs', balances' costs are also shown, with different
-costs kept separate.  This may generate very large journal entries, if
-you have many currency conversions or investment transactions.  'close
---show-costs' is currently the best way to view investment lots with
-hledger.  (To move or dispose of lots, see the more capable
-'hledger-move' script.)
-
-
-File: hledger.info,  Node: close and balance assertions,  Next: close examples,  Prev: close customisation,  Up: close
-
-31.1.8 close and balance assertions
------------------------------------
-
-'close' adds balance assertions verifying that the accounts have been
-reset to zero in a closing transaction or restored to their previous
-balances in an opening transaction.  These provide useful error
-checking, but you can ignore them temporarily with '-I', or remove them
-if you prefer.
-
-   Single-commodity, subaccount-exclusive balance assertions ('=') are
-generated by default.  This can be changed with '--assertion-type='==*''
-(eg).
-
-   When running 'close' you should probably avoid using '-C', '-R',
-'status:' (filtering by status or realness) or '--auto' (generating
-postings), since the generated balance assertions would then require
-these.
-
-   Transactions with multiple dates (eg posting dates) spanning the file
-boundary also can disrupt the balance assertions:
-
-2023-12-30 a purchase made in december, cleared in january
-    expenses:food          5
-    assets:bank:checking  -5  ; date: 2023-01-02
-
-   To solve this you can transfer the money to and from a temporary
-account, splitting the multi-day transaction into two single-day
-transactions:
-
-; in 2022.journal:
-2022-12-30 a purchase made in december, cleared in january
-    expenses:food          5
-    equity:pending        -5
-
-; in 2023.journal:
-2023-01-02 last year's transaction cleared
-    equity:pending         5 = 0
-    assets:bank:checking  -5
-
-
-File: hledger.info,  Node: close examples,  Prev: close and balance assertions,  Up: close
-
-31.1.9 close examples
----------------------
-
-* Menu:
-
-* Retain earnings::
-* Migrate balances to a new file::
-* More detailed close examples::
-
-
-File: hledger.info,  Node: Retain earnings,  Next: Migrate balances to a new file,  Up: close examples
-
-31.1.9.1 Retain earnings
-........................
-
-Record 2022's revenues/expenses as retained earnings on 2022-12-31,
-appending the generated transaction to the journal:
-
-$ hledger close --retain -f 2022.journal -p 2022 >> 2022.journal
-
-   After this, to see 2022's revenues and expenses you must exclude the
-retain earnings transaction:
-
-$ hledger -f 2022.journal is not:desc:'retain earnings'
-
-
-File: hledger.info,  Node: Migrate balances to a new file,  Next: More detailed close examples,  Prev: Retain earnings,  Up: close examples
-
-31.1.9.2 Migrate balances to a new file
-.......................................
-
-Close assets/liabilities on 2022-12-31 and re-open them on 2023-01-01:
-
-$ hledger close --migrate -f 2022.journal -p 2022
-# copy/paste the closing transaction to the end of 2022.journal
-# copy/paste the opening transaction to the start of 2023.journal
-
-   After this, to see 2022's end-of-year balances you must exclude the
-closing balances transaction:
-
-$ hledger -f 2022.journal bs not:desc:'closing balances'
-
-   For more flexibility, it helps to tag closing and opening
-transactions with eg 'start:NEWYEAR', then you can ensure correct
-balances by excluding all opening/closing transactions except the first,
-like so:
-
-$ hledger bs -Y -f 2021.j -f 2022.j -f 2023.j expr:'tag:start=2021 or not tag:start'
-$ hledger bs -Y -f 2021.j -f 2022.j           expr:'tag:start=2021 or not tag:start'
-$ hledger bs -Y -f 2022.j -f 2023.j           expr:'tag:start=2022 or not tag:start'
-$ hledger bs -Y -f 2021.j                     expr:'tag:start=2021 or not tag:start'
-$ hledger bs -Y -f 2022.j                     expr:'tag:start=2022 or not tag:start'
-$ hledger bs -Y -f 2023.j                     # unclosed file, no query needed
-
-
-File: hledger.info,  Node: More detailed close examples,  Prev: Migrate balances to a new file,  Up: close examples
-
-31.1.9.3 More detailed close examples
-.....................................
-
-See examples/multi-year.
-
-
-File: hledger.info,  Node: rewrite,  Prev: close,  Up: Data generation commands
-
-31.2 rewrite
-============
-
-Print all transactions, rewriting the postings of matched transactions.
-For now the only rewrite available is adding new postings, like print
--auto.
-
-Flags:
-     --add-posting='ACCT  AMTEXPR'  add a posting to ACCT, which may be
-                                    parenthesised. AMTEXPR is either a literal
-                                    amount, or *N which means the transaction's
-                                    first matched amount multiplied by N (a
-                                    decimal number). Two spaces separate ACCT
-                                    and AMTEXPR.
-     --diff                         generate diff suitable as an input for
-                                    patch tool
-
-   This is a start at a generic rewriter of transaction entries.  It
-reads the default journal and prints the transactions, like print, but
-adds one or more specified postings to any transactions matching QUERY.
-The posting amounts can be fixed, or a multiplier of the existing
-transaction's first posting amount.
-
-   Examples:
-
-$ hledger-rewrite.hs ^income --add-posting '(liabilities:tax)  *.33  ; income tax' --add-posting '(reserve:gifts)  $100'
-$ hledger-rewrite.hs expenses:gifts --add-posting '(reserve:gifts)  *-1"'
-$ hledger-rewrite.hs -f rewrites.hledger
-
-   rewrites.hledger may consist of entries like:
-
-= ^income amt:<0 date:2017
-  (liabilities:tax)  *0.33  ; tax on income
-  (reserve:grocery)  *0.25  ; reserve 25% for grocery
-  (reserve:)  *0.25  ; reserve 25% for grocery
-
-   Note the single quotes to protect the dollar sign from bash, and the
-two spaces between account and amount.
-
-   More:
-
-$ hledger rewrite -- [QUERY]        --add-posting "ACCT  AMTEXPR" ...
-$ hledger rewrite -- ^income        --add-posting '(liabilities:tax)  *.33'
-$ hledger rewrite -- expenses:gifts --add-posting '(budget:gifts)  *-1"'
-$ hledger rewrite -- ^income        --add-posting '(budget:foreign currency)  *0.25 JPY; diversify'
-
-   Argument for '--add-posting' option is a usual posting of transaction
-with an exception for amount specification.  More precisely, you can use
-''*'' (star symbol) before the amount to indicate that that this is a
-factor for an amount of original matched posting.  If the amount
-includes a commodity name, the new posting amount will be in the new
-commodity; otherwise, it will be in the matched posting amount's
-commodity.
-
-* Menu:
-
-* Re-write rules in a file::
-* Diff output format::
-* rewrite vs print --auto::
-
-
-File: hledger.info,  Node: Re-write rules in a file,  Next: Diff output format,  Up: rewrite
-
-31.2.1 Re-write rules in a file
--------------------------------
-
-During the run this tool will execute so called "Automated Transactions"
-found in any journal it process.  I.e instead of specifying this
-operations in command line you can put them in a journal file.
-
-$ rewrite-rules.journal
-
-   Make contents look like this:
-
-= ^income
-    (liabilities:tax)  *.33
-
-= expenses:gifts
-    budget:gifts  *-1
-    assets:budget  *1
-
-   Note that ''='' (equality symbol) that is used instead of date in
-transactions you usually write.  It indicates the query by which you
-want to match the posting to add new ones.
-
-$ hledger rewrite -- -f input.journal -f rewrite-rules.journal > rewritten-tidy-output.journal
-
-   This is something similar to the commands pipeline:
-
-$ hledger rewrite -- -f input.journal '^income' --add-posting '(liabilities:tax)  *.33' \
-  | hledger rewrite -- -f - expenses:gifts      --add-posting 'budget:gifts  *-1'       \
-                                                --add-posting 'assets:budget  *1'       \
-  > rewritten-tidy-output.journal
-
-   It is important to understand that relative order of such entries in
-journal is important.  You can re-use result of previously added
-postings.
-
-
-File: hledger.info,  Node: Diff output format,  Next: rewrite vs print --auto,  Prev: Re-write rules in a file,  Up: rewrite
-
-31.2.2 Diff output format
--------------------------
-
-To use this tool for batch modification of your journal files you may
-find useful output in form of unified diff.
-
-$ hledger rewrite -- --diff -f examples/sample.journal '^income' --add-posting '(liabilities:tax)  *.33'
-
-   Output might look like:
-
---- /tmp/examples/sample.journal
-+++ /tmp/examples/sample.journal
-@@ -18,3 +18,4 @@
- 2008/01/01 income
--    assets:bank:checking  $1
-+    assets:bank:checking            $1
-     income:salary
-+    (liabilities:tax)                0
-@@ -22,3 +23,4 @@
- 2008/06/01 gift
--    assets:bank:checking  $1
-+    assets:bank:checking            $1
-     income:gifts
-+    (liabilities:tax)                0
-
-   If you'll pass this through 'patch' tool you'll get transactions
-containing the posting that matches your query be updated.  Note that
-multiple files might be update according to list of input files
-specified via '--file' options and 'include' directives inside of these
-files.
-
-   Be careful.  Whole transaction being re-formatted in a style of
-output from 'hledger print'.
-
-   See also:
-
-   https://github.com/simonmichael/hledger/issues/99
-
-
-File: hledger.info,  Node: rewrite vs print --auto,  Prev: Diff output format,  Up: rewrite
-
-31.2.3 rewrite vs. print -auto
-------------------------------
-
-This command predates print -auto, and currently does much the same
-thing, but with these differences:
-
-   * with multiple files, rewrite lets rules in any file affect all
-     other files.  print -auto uses standard directive scoping; rules
-     affect only child files.
-
-   * rewrite's query limits which transactions can be rewritten; all are
-     printed.  print -auto's query limits which transactions are
-     printed.
-
-   * rewrite applies rules specified on command line or in the journal.
-     print -auto applies rules specified in the journal.
-
-
-File: hledger.info,  Node: Maintenance commands,  Next: PART 5 COMMON TASKS,  Prev: Data generation commands,  Up: Top
-
-32 Maintenance commands
-***********************
-
-* Menu:
-
-* check::
-* diff::
-* test::
-
-
-File: hledger.info,  Node: check,  Next: diff,  Up: Maintenance commands
-
-32.1 check
-==========
-
-Check for various kinds of errors in your data.
-
-Flags:
-no command-specific flags
-
-   hledger provides a number of built-in correctness checks to help
-validate your data and prevent errors.  Some are run automatically, some
-when you enable '--strict' mode; or you can run any of them on demand by
-providing them as arguments to the 'check' command.  'check' produces no
-output and a zero exit code if all is well.  Eg:
-
-hledger check                      # run basic checks
-hledger check -s                   # run basic and strict checks
-hledger check ordereddates payees  # run basic checks and two others
-
-   If you are an Emacs user, you can also configure flycheck-hledger to
-run these checks, providing instant feedback as you edit the journal.
-
-   Here are the checks currently available.  Generally, they are
-performed in the order they are shown here (and only the first failure
-is reported).
-
-* Menu:
-
-* Basic checks::
-* Strict checks::
-* Other checks::
-* Custom checks::
-
-
-File: hledger.info,  Node: Basic checks,  Next: Strict checks,  Up: check
-
-32.1.1 Basic checks
--------------------
-
-These important checks are performed by default, by almost all hledger
-commands:
-
-   * *parseable* - data files are in a supported format, with no syntax
-     errors and no invalid include directives.  This ensures that all
-     files exist and are readable.
-
-   * *autobalanced* - all transactions are balanced, after inferring
-     missing amounts and conversion costs where possible, and then
-     converting to cost.  This ensures that each individual transaction
-     is well formed.
-
-   * *assertions* - all balance assertions in the journal are passing.
-     Balance assertions are like canaries in your journal, they catch
-     many problems.  They can get in the way sometimes; you can disable
-     them temporarily with '-I'/'--ignore-assertions' (unless overridden
-     with '-s'/'--strict' or 'hledger check assertions').
-
-
-File: hledger.info,  Node: Strict checks,  Next: Other checks,  Prev: Basic checks,  Up: check
-
-32.1.2 Strict checks
---------------------
-
-These additional checks are performed by any command when the
-'-s'/'--strict' flag is used (strict mode).  Strict mode always enables
-the balance assertions check, also.  These provide extra error-catching
-power when you are serious about keeping your data clean and free of
-typos:
-
-   * *balanced* - like 'autobalanced', but in conversion transactions,
-     costs must be written explicitly.  This ensures some redundancy in
-     the entry, which helps prevent typos.
-
-   * *commodities* - all commodity symbols used must be declared.  This
-     guards against mistyping or omitting commodity symbols.
-
-   * *accounts* - all account names used must be declared.  This
-     prevents the use of mis-spelled or outdated account names.
-
-
-File: hledger.info,  Node: Other checks,  Next: Custom checks,  Prev: Strict checks,  Up: check
-
-32.1.3 Other checks
--------------------
-
-These other checks are not wanted by everyone, but can be run using the
-'check' command:
-
-   * *ordereddates* - within each file, transactions are ordered by
-     date.  This is a simple and effective error catcher, and you should
-     use it.  Alas!  not everyone wants it.  If you do, use 'hledger
-     check -s ordereddates'.  When enabled, this check is performed
-     early, before balance assertions (because copy-pasted dates are
-     often the root cause of balance assertion failures).
-
-   * *payees* - all payees used by transactions must be declared.  This
-     will force you to always use known/declared payee names.  For most
-     people this is a bit too restrictive.
-
-   * *tags* - all tags used by transactions must be declared.  This
-     prevents mistyped tag names.
-
-   * *recentassertions* - all accounts with balance assertions must have
-     a balance assertion within the last 7 days before their latest
-     posting.  This encourages you to add balance assertions fairly
-     regularly for your active asset/liability accounts, which in turn
-     should encourage you to check and reconcile with their real world
-     balances fairly regularly.  'close --assert' can be helpful.  (The
-     older balance assertions become redundant; you can remove them
-     periodically, or leave them in place, perhaps commented, as
-     documentation.)
-
-   * *uniqueleafnames* - no two accounts may have the same leaf name.
-     The leaf name is the last colon-separated part of an account name,
-     eg 'checking' in 'assets:bank:checking'.  This encourages you to
-     keep those unique, effectively giving each account a short name
-     which is easier to remember and to type in reporting commands.
-
-
-File: hledger.info,  Node: Custom checks,  Prev: Other checks,  Up: check
-
-32.1.4 Custom checks
---------------------
-
-You can build your own custom checks with add-on command scripts.  See
-also Cookbook > Scripting.  Here are some examples from hledger/bin/:
-
-   * *hledger-check-tagfiles* - all tag values containing / (a forward
-     slash) exist as file paths
-
-   * *hledger-check-fancyassertions* - more complex balance assertions
-     are passing
-
-
-File: hledger.info,  Node: diff,  Next: test,  Prev: check,  Up: Maintenance commands
-
-32.2 diff
-=========
-
-Compares a particular account's transactions in two input files.  It
-shows any transactions to this account which are in one file but not in
-the other.
-
-Flags:
-no command-specific flags
-
-   More precisely: for each posting affecting this account in either
-file, this command looks for a corresponding posting in the other file
-which posts the same amount to the same account (ignoring date,
-description, etc).
-
-   Since it compares postings, not transactions, this also works when
-multiple bank transactions have been combined into a single journal
-entry.
-
-   This command is useful eg if you have downloaded an account's
-transactions from your bank (eg as CSV data): when hledger and your bank
-disagree about the account balance, you can compare the bank data with
-your journal to find out the cause.
-
-   Examples:
-
-$ hledger diff -f $LEDGER_FILE -f bank.csv assets:bank:giro 
-These transactions are in the first file only:
-
-2014/01/01 Opening Balances
-    assets:bank:giro              EUR ...
-    ...
-    equity:opening balances       EUR -...
-
-These transactions are in the second file only:
-
-
-File: hledger.info,  Node: test,  Prev: diff,  Up: Maintenance commands
-
-32.3 test
-=========
-
-Run built-in unit tests.
-
-Flags:
-no command-specific flags
-
-   This command runs the unit tests built in to hledger and hledger-lib,
-printing the results on stdout.  If any test fails, the exit code will
-be non-zero.
-
-   This is mainly used by hledger developers, but you can also use it to
-sanity-check the installed hledger executable on your platform.  All
-tests are expected to pass - if you ever see a failure, please report as
-a bug!
-
-   This command also accepts tasty test runner options, written after a
-- (double hyphen).  Eg to run only the tests in Hledger.Data.Amount,
-with ANSI colour codes disabled:
-
-$ hledger test -- -pData.Amount --color=never
-
-   For help on these, see https://github.com/feuerbach/tasty#options
-('-- --help' currently doesn't show them).
-
-
-File: hledger.info,  Node: PART 5 COMMON TASKS,  Next: Getting help,  Prev: Maintenance commands,  Up: Top
-
-33 PART 5: COMMON TASKS
-***********************
-
-Here are some quick examples of how to do some basic tasks with hledger.
-
-
-File: hledger.info,  Node: Getting help,  Next: Constructing command lines,  Prev: PART 5 COMMON TASKS,  Up: Top
-
-34 Getting help
-***************
-
-Here's how to list commands and view options and command docs:
-
-$ hledger                # show available commands
-$ hledger --help         # show common options
-$ hledger CMD --help     # show CMD's options, common options and CMD's documentation
-
-   You can also view your hledger version's manual in several formats by
-using the help command.  Eg:
-
-$ hledger help           # show the hledger manual with info, man or $PAGER (best available)
-$ hledger help journal   # show the journal topic in the hledger manual
-$ hledger help --help    # find out more about the help command
-
-   To view manuals and introductory docs on the web, visit
-https://hledger.org.  Chat and mail list support and discussion archives
-can be found at https://hledger.org/support.
-
-
-File: hledger.info,  Node: Constructing command lines,  Next: Starting a journal file,  Prev: Getting help,  Up: Top
-
-35 Constructing command lines
-*****************************
-
-hledger has a flexible command line interface.  We strive to keep it
-simple and ergonomic, but if you run into one of the sharp edges
-described in OPTIONS, here are some tips that might help:
-
-   * command-specific options must go after the command (it's fine to
-     put common options there too: 'hledger CMD OPTS ARGS')
-   * running add-on executables directly simplifies command line parsing
-     ('hledger-ui OPTS ARGS')
-   * enclose "problematic" args in single quotes
-   * if needed, also add a backslash to hide regular expression
-     metacharacters from the shell
-   * to see how a misbehaving command line is being parsed, add
-     '--debug=2'.
-
-
-File: hledger.info,  Node: Starting a journal file,  Next: Setting LEDGER_FILE,  Prev: Constructing command lines,  Up: Top
-
-36 Starting a journal file
-**************************
-
-hledger looks for your accounting data in a journal file,
-'$HOME/.hledger.journal' by default:
-
-$ hledger stats
-The hledger journal file "/Users/simon/.hledger.journal" was not found.
-Please create it first, eg with "hledger add" or a text editor.
-Or, specify an existing journal file with -f or LEDGER_FILE.
-
-   You can override this by setting the 'LEDGER_FILE' environment
-variable (see below).  It's a good practice to keep this important file
-under version control, and to start a new file each year.  So you could
-do something like this:
-
-$ mkdir ~/finance
-$ cd ~/finance
-$ git init
-Initialized empty Git repository in /Users/simon/finance/.git/
-$ touch 2023.journal
-$ echo "export LEDGER_FILE=$HOME/finance/2023.journal" >> ~/.profile
-$ source ~/.profile
-$ hledger stats
-Main file                : /Users/simon/finance/2023.journal
-Included files           : 
-Transactions span        :  to  (0 days)
-Last transaction         : none
-Transactions             : 0 (0.0 per day)
-Transactions last 30 days: 0 (0.0 per day)
-Transactions last 7 days : 0 (0.0 per day)
-Payees/descriptions      : 0
-Accounts                 : 0 (depth 0)
-Commodities              : 0 ()
-Market prices            : 0 ()
-
-
-File: hledger.info,  Node: Setting LEDGER_FILE,  Next: Setting opening balances,  Prev: Starting a journal file,  Up: Top
-
-37 Setting LEDGER_FILE
-**********************
-
-How to set 'LEDGER_FILE' permanently depends on your setup:
-
-   On unix and mac, running these commands in the terminal will work for
-many people; adapt as needed:
-
-$ echo 'export LEDGER_FILE=~/finance/2023.journal' >> ~/.profile
-$ source ~/.profile
-
-   When correctly configured, in a new terminal window 'env | grep
-LEDGER_FILE' will show your file, and so will 'hledger files'.
-
-   On mac, this additional step might be helpful for GUI applications
-(like Emacs started from the dock): add an entry to
-'~/.MacOSX/environment.plist' like
-
-{
-  "LEDGER_FILE" : "~/finance/2023.journal"
-}
-
-   and then run 'killall Dock' in a terminal window (or restart the
-machine).
-
-   On Windows, see https://www.java.com/en/download/help/path.html, or
-try running these commands in a powershell window (let us know if it
-persists across a reboot, and if you need to be an Administrator):
-
-> CD
-> MKDIR finance
-> SETX LEDGER_FILE "C:\Users\USERNAME\finance\2023.journal"
-
-   When correctly configured, in a new terminal window
-'$env:LEDGER_FILE' will show the file path, and so will 'hledger files'.
-
-
-File: hledger.info,  Node: Setting opening balances,  Next: Recording transactions,  Prev: Setting LEDGER_FILE,  Up: Top
-
-38 Setting opening balances
-***************************
-
-Pick a starting date for which you can look up the balances of some
-real-world assets (bank accounts, wallet..)  and liabilities (credit
-cards..).
-
-   To avoid a lot of data entry, you may want to start with just one or
-two accounts, like your checking account or cash wallet; and pick a
-recent starting date, like today or the start of the week.  You can
-always come back later and add more accounts and older transactions, eg
-going back to january 1st.
-
-   Add an opening balances transaction to the journal, declaring the
-balances on this date.  Here are two ways to do it:
-
-   * The first way: open the journal in any text editor and save an
-     entry like this:
-
-     2023-01-01 * opening balances
-         assets:bank:checking                $1000   = $1000
-         assets:bank:savings                 $2000   = $2000
-         assets:cash                          $100   = $100
-         liabilities:creditcard               $-50   = $-50
-         equity:opening/closing balances
-
-     These are start-of-day balances, ie whatever was in the account at
-     the end of the previous day.
-
-     The * after the date is an optional status flag.  Here it means
-     "cleared & confirmed".
-
-     The currency symbols are optional, but usually a good idea as
-     you'll be dealing with multiple currencies sooner or later.
-
-     The = amounts are optional balance assertions, providing extra
-     error checking.
-
-   * The second way: run 'hledger add' and follow the prompts to record
-     a similar transaction:
-
-     $ hledger add
-     Adding transactions to journal file /Users/simon/finance/2023.journal
-     Any command line arguments will be used as defaults.
-     Use tab key to complete, readline keys to edit, enter to accept defaults.
-     An optional (CODE) may follow transaction dates.
-     An optional ; COMMENT may follow descriptions or amounts.
-     If you make a mistake, enter < at any prompt to go one step backward.
-     To end a transaction, enter . when prompted.
-     To quit, enter . at a date prompt or press control-d or control-c.
-     Date [2023-02-07]: 2023-01-01
-     Description: * opening balances
-     Account 1: assets:bank:checking
-     Amount  1: $1000
-     Account 2: assets:bank:savings
-     Amount  2 [$-1000]: $2000
-     Account 3: assets:cash
-     Amount  3 [$-3000]: $100
-     Account 4: liabilities:creditcard
-     Amount  4 [$-3100]: $-50
-     Account 5: equity:opening/closing balances
-     Amount  5 [$-3050]: 
-     Account 6 (or . or enter to finish this transaction): .
-     2023-01-01 * opening balances
-         assets:bank:checking                      $1000
-         assets:bank:savings                       $2000
-         assets:cash                                $100
-         liabilities:creditcard                     $-50
-         equity:opening/closing balances          $-3050
-     
-     Save this transaction to the journal ? [y]: 
-     Saved.
-     Starting the next transaction (. or ctrl-D/ctrl-C to quit)
-     Date [2023-01-01]: .
-
-   If you're using version control, this could be a good time to commit
-the journal.  Eg:
-
-$ git commit -m 'initial balances' 2023.journal
-
-
-File: hledger.info,  Node: Recording transactions,  Next: Reconciling,  Prev: Setting opening balances,  Up: Top
-
-39 Recording transactions
-*************************
-
-As you spend or receive money, you can record these transactions using
-one of the methods above (text editor, hledger add) or by using the
-hledger-iadd or hledger-web add-ons, or by using the import command to
-convert CSV data downloaded from your bank.
-
-   Here are some simple transactions, see the hledger_journal(5) manual
-and hledger.org for more ideas:
-
-2023/1/10 * gift received
-  assets:cash   $20
-  income:gifts
-
-2023.1.12 * farmers market
-  expenses:food    $13
-  assets:cash
-
-2023-01-15 paycheck
-  income:salary
-  assets:bank:checking    $1000
-
-
-File: hledger.info,  Node: Reconciling,  Next: Reporting,  Prev: Recording transactions,  Up: Top
-
-40 Reconciling
-**************
-
-Periodically you should reconcile - compare your hledger-reported
-balances against external sources of truth, like bank statements or your
-bank's website - to be sure that your ledger accurately represents the
-real-world balances (and, that the real-world institutions have not made
-a mistake!).  This gets easy and fast with (1) practice and (2)
-frequency.  If you do it daily, it can take 2-10 minutes.  If you let it
-pile up, expect it to take longer as you hunt down errors and
-discrepancies.
-
-   A typical workflow:
-
-  1. Reconcile cash.  Count what's in your wallet.  Compare with what
-     hledger reports ('hledger bal cash').  If they are different, try
-     to remember the missing transaction, or look for the error in the
-     already-recorded transactions.  A register report can be helpful
-     ('hledger reg cash').  If you can't find the error, add an
-     adjustment transaction.  Eg if you have $105 after the above, and
-     can't explain the missing $2, it could be:
-
-     2023-01-16 * adjust cash
-         assets:cash    $-2 = $105
-         expenses:misc
-
-  2. Reconcile checking.  Log in to your bank's website.  Compare
-     today's (cleared) balance with hledger's cleared balance ('hledger
-     bal checking -C').  If they are different, track down the error or
-     record the missing transaction(s) or add an adjustment transaction,
-     similar to the above.  Unlike the cash case, you can usually
-     compare the transaction history and running balance from your bank
-     with the one reported by 'hledger reg checking -C'.  This will be
-     easier if you generally record transaction dates quite similar to
-     your bank's clearing dates.
-
-  3. Repeat for other asset/liability accounts.
-
-   Tip: instead of the register command, use hledger-ui to see a
-live-updating register while you edit the journal: 'hledger-ui --watch
---register checking -C'
-
-   After reconciling, it could be a good time to mark the reconciled
-transactions' status as "cleared and confirmed", if you want to track
-that, by adding the '*' marker.  Eg in the paycheck transaction above,
-insert '*' between '2023-01-15' and 'paycheck'
-
-   If you're using version control, this can be another good time to
-commit:
-
-$ git commit -m 'txns' 2023.journal
-
-
-File: hledger.info,  Node: Reporting,  Next: Migrating to a new file,  Prev: Reconciling,  Up: Top
-
-41 Reporting
-************
-
-Here are some basic reports.
-
-   Show all transactions:
-
-$ hledger print
-2023-01-01 * opening balances
-    assets:bank:checking                      $1000
-    assets:bank:savings                       $2000
-    assets:cash                                $100
-    liabilities:creditcard                     $-50
-    equity:opening/closing balances          $-3050
-
-2023-01-10 * gift received
-    assets:cash              $20
-    income:gifts
-
-2023-01-12 * farmers market
-    expenses:food             $13
-    assets:cash
-
-2023-01-15 * paycheck
-    income:salary
-    assets:bank:checking           $1000
-
-2023-01-16 * adjust cash
-    assets:cash               $-2 = $105
-    expenses:misc
-
-   Show account names, and their hierarchy:
-
-$ hledger accounts --tree
-assets
-  bank
-    checking
-    savings
-  cash
-equity
-  opening/closing balances
-expenses
-  food
-  misc
-income
-  gifts
-  salary
-liabilities
-  creditcard
-
-   Show all account totals:
-
-$ hledger balance
-               $4105  assets
-               $4000    bank
-               $2000      checking
-               $2000      savings
-                $105    cash
-              $-3050  equity:opening/closing balances
-                 $15  expenses
-                 $13    food
-                  $2    misc
-              $-1020  income
-                $-20    gifts
-              $-1000    salary
-                $-50  liabilities:creditcard
---------------------
-                   0
-
-   Show only asset and liability balances, as a flat list, limited to
-depth 2:
-
-$ hledger bal assets liabilities -2
-               $4000  assets:bank
-                $105  assets:cash
-                $-50  liabilities:creditcard
---------------------
-               $4055
-
-   Show the same thing without negative numbers, formatted as a simple
-balance sheet:
-
-$ hledger bs -2
-Balance Sheet 2023-01-16
-
-                        || 2023-01-16 
-========================++============
- Assets                 ||            
-------------------------++------------
- assets:bank            ||      $4000 
- assets:cash            ||       $105 
-------------------------++------------
-                        ||      $4105 
-========================++============
- Liabilities            ||            
-------------------------++------------
- liabilities:creditcard ||        $50 
-------------------------++------------
-                        ||        $50 
-========================++============
- Net:                   ||      $4055 
-
-   The final total is your "net worth" on the end date.  (Or use 'bse'
-for a full balance sheet with equity.)
-
-   Show income and expense totals, formatted as an income statement:
-
-hledger is 
-Income Statement 2023-01-01-2023-01-16
-
-               || 2023-01-01-2023-01-16 
-===============++=======================
- Revenues      ||                       
----------------++-----------------------
- income:gifts  ||                   $20 
- income:salary ||                 $1000 
----------------++-----------------------
-               ||                 $1020 
-===============++=======================
- Expenses      ||                       
----------------++-----------------------
- expenses:food ||                   $13 
- expenses:misc ||                    $2 
----------------++-----------------------
-               ||                   $15 
-===============++=======================
- Net:          ||                 $1005 
-
-   The final total is your net income during this period.
-
-   Show transactions affecting your wallet, with running total:
-
-$ hledger register cash
-2023-01-01 opening balances     assets:cash                   $100          $100
-2023-01-10 gift received        assets:cash                    $20          $120
-2023-01-12 farmers market       assets:cash                   $-13          $107
-2023-01-16 adjust cash          assets:cash                    $-2          $105
-
-   Show weekly posting counts as a bar chart:
-
-$ hledger activity -W
-2019-12-30 *****
-2023-01-06 ****
-2023-01-13 ****
-
-
-File: hledger.info,  Node: Migrating to a new file,  Next: BUGS,  Prev: Reporting,  Up: Top
-
-42 Migrating to a new file
-**************************
-
-At the end of the year, you may want to continue your journal in a new
-file, so that old transactions don't slow down or clutter your reports,
-and to help ensure the integrity of your accounting history.  See the
-close command.
-
-   If using version control, don't forget to 'git add' the new file.
-
-
-File: hledger.info,  Node: BUGS,  Prev: Migrating to a new file,  Up: Top
-
-43 BUGS
-*******
-
-We welcome bug reports in the hledger issue tracker (shortcut:
-https://bugs.hledger.org), or on the hledger chat or mail list
-(https://hledger.org/support).
-
-   Some known issues and limitations:
-
-   The need to precede add-on command options with '--' when invoked
-from hledger is awkward.  (See Command options, Constructing command
-lines.)
-
-   A UTF-8-aware system locale must be configured to work with non-ascii
-data.  (See Unicode characters, Troubleshooting.)
-
-   On Microsoft Windows, depending whether you are running in a CMD
-window or a Cygwin/MSYS/Mintty window and how you installed hledger,
-non-ascii characters and colours may not be supported, and the tab key
-may not be supported by 'hledger add'.  (Running in a WSL window should
-resolve these.)
-
-   When processing large data files, hledger uses more memory than
-Ledger.
-
-* Menu:
-
-* Troubleshooting::
-
-
-File: hledger.info,  Node: Troubleshooting,  Up: BUGS
-
-43.1 Troubleshooting
-====================
-
-Here are some common issues you might encounter when you run hledger,
-and how to resolve them (and remember also you can usually get quick
-Support):
-
-   *PATH issues: I get an error like "No command 'hledger' found"*
-Depending how you installed hledger, the executables may not be in your
-shell's PATH. Eg on unix systems, stack installs hledger in
-'~/.local/bin' and cabal installs it in '~/.cabal/bin'.  You may need to
-add one of these directories to your shell's PATH, and/or open a new
-terminal window.
-
-   *LEDGER_FILE issues: I configured LEDGER_FILE but hledger is not
-using it*
-
-   * 'LEDGER_FILE' should be a real environment variable, not just a
-     shell variable.  Eg on unix, the command 'env | grep LEDGER_FILE'
-     should show it.  You may need to use 'export' (see
-     https://stackoverflow.com/a/7411509).  On Windows,
-     '$env:LEDGER_FILE' should show it.
-   * You may need to force your shell to see the new configuration.  A
-     simple way is to close your terminal window and open a new one.
-
-   *LANG issues: I get errors like "Illegal byte sequence" or "Invalid
-or incomplete multibyte or wide character" or "commitAndReleaseBuffer:
-invalid argument (invalid character)"*
-Programs compiled with GHC (hledger, haskell build tools, etc.)  need
-the system locale to be UTF-8-aware, or they will fail when they
-encounter non-ascii characters.  To fix it, set the LANG environment
-variable to a locale which supports UTF-8 and which is installed on your
-system.
-
-   On unix, 'locale -a' lists the installed locales.  Look for one which
-mentions 'utf8', 'UTF-8' or similar.  Some examples: 'C.UTF-8',
-'en_US.utf-8', 'fr_FR.utf8'.  If necessary, use your system package
-manager to install one.  Then select it by setting the 'LANG'
-environment variable.  Note, exact spelling and capitalisation of the
-locale name may be important: Here's one common way to configure this
-permanently for your shell:
-
-$ echo "export LANG=en_US.utf8" >>~/.profile
-# close and re-open terminal window
-
-   If you are using Nix (not NixOS) for GHC and Hledger, you might need
-to set the 'LOCALE_ARCHIVE' variable:
-
-$ echo "export LOCALE_ARCHIVE=${glibcLocales}/lib/locale/locale-archive" >>~/.profile
-# close and re-open terminal window
-
-   *COMPATIBILITY ISSUES: hledger gives an error with my Ledger file*
-Not all of Ledger's journal file syntax or feature set is supported.
-See hledger and Ledger for full details.
-
-
-Tag Table:
-Node: Top210
-Node: PART 1 USER INTERFACE4362
-Node: Input4501
-Node: Text encoding5593
-Node: Data formats6273
-Node: Standard input7997
-Node: Multiple files8386
-Node: Strict mode9123
-Node: Commands9957
-Node: Add-on commands11143
-Node: Options12361
-Node: Special characters18935
-Node: Escaping shell special characters19885
-Node: Escaping on Windows21129
-Node: Escaping regular expression special characters21862
-Node: Escaping add-on arguments22849
-Node: Escaping in other situations23878
-Node: Using a wild card24837
-Node: Unicode characters25216
-Node: Regular expressions26880
-Node: hledger's regular expressions30139
-Node: Argument files31780
-Node: Config files32483
-Node: Shell completions35636
-Node: Output36161
-Node: Output destination36352
-Node: Output format36910
-Node: Text output38696
-Node: Box-drawing characters39893
-Node: Colour40393
-Node: Paging40979
-Node: HTML output42430
-Node: CSV / TSV output42884
-Node: FODS output43138
-Node: Beancount output43942
-Node: Beancount account names45140
-Node: Beancount commodity names45681
-Node: Beancount virtual postings46328
-Node: Beancount metadata46644
-Node: Beancount costs47424
-Node: Beancount operating currency47840
-Node: SQL output48290
-Node: JSON output49081
-Node: Commodity styles49898
-Node: Debug output50782
-Node: Environment51614
-Node: PART 2 DATA FORMATS52463
-Node: Journal52606
-Node: Journal cheatsheet55084
-Node: Comments61298
-Node: Transactions62242
-Node: Dates63379
-Node: Simple dates63531
-Node: Posting dates64147
-Node: Status65234
-Node: Code67000
-Node: Description67335
-Node: Payee and note68022
-Node: Transaction comments69113
-Node: Postings69629
-Node: Debits and credits70792
-Node: The two space delimiter71402
-Node: Account names71967
-Node: Amounts73771
-Node: Decimal marks74800
-Node: Digit group marks75904
-Node: Commodity76539
-Node: Costs77656
-Node: Balance assertions79908
-Node: Assertions and ordering81171
-Node: Assertions and multiple included files81899
-Node: Assertions and multiple -f files82659
-Node: Assertions and costs83301
-Node: Assertions and commodities83951
-Node: Assertions and subaccounts85610
-Node: Assertions and status86270
-Node: Assertions and virtual postings86690
-Node: Assertions and auto postings87055
-Node: Assertions and precision87930
-Node: Posting comments88381
-Node: Transaction balancing88921
-Node: Tags90923
-Node: Querying with tags92217
-Node: Displaying tags93016
-Node: When to use tags ?93412
-Node: Tag names94076
-Node: Special tags94629
-Node: Directives96194
-Node: Directives and multiple files97651
-Node: Directive effects98596
-Node: account directive101752
-Node: Account comments103202
-Node: Account error checking103861
-Node: Account display order105398
-Node: Account types106596
-Node: alias directive110370
-Node: Basic aliases111581
-Node: Regex aliases112456
-Node: Combining aliases113503
-Node: Aliases and multiple files114957
-Node: end aliases directive115740
-Node: Aliases can generate bad account names116108
-Node: Aliases and account types116941
-Node: commodity directive117829
-Node: Commodity directive syntax119416
-Node: Commodity error checking121052
-Node: decimal-mark directive121527
-Node: include directive122106
-Node: P directive123182
-Node: payee directive124216
-Node: tag directive124838
-Node: Periodic transactions125450
-Node: Periodic rule syntax127604
-Node: Periodic rules and relative dates128427
-Node: Two spaces between period expression and description!129204
-Node: Auto postings130165
-Node: Auto postings and multiple files133325
-Node: Auto postings and dates133730
-Node: Auto postings and transaction balancing / inferred amounts / balance assertions134171
-Node: Auto posting tags135017
-Node: Auto postings on forecast transactions only135912
-Node: Other syntax136382
-Node: Balance assignments137154
-Node: Balance assignments and costs138682
-Node: Balance assignments and multiple files139104
-Node: Bracketed posting dates139527
-Node: D directive140225
-Node: apply account directive141998
-Node: Y directive142865
-Node: Secondary dates143853
-Node: Star comments145338
-Node: Valuation expressions146030
-Node: Virtual postings146329
-Node: Other Ledger directives147953
-Node: Other cost/lot notations148715
-Node: CSV151477
-Node: CSV rules cheatsheet153560
-Node: source155485
-Node: separator156486
-Node: skip157137
-Node: date-format157787
-Node: timezone158630
-Node: newest-first159756
-Node: intra-day-reversed160469
-Node: decimal-mark161069
-Node: fields list161547
-Node: Field assignment163355
-Node: Field names164574
-Node: date field165906
-Node: date2 field166070
-Node: status field166265
-Node: code field166455
-Node: description field166643
-Node: comment field166860
-Node: account field167417
-Node: amount field168135
-Node: currency field170974
-Node: balance field171382
-Node: if block171905
-Node: Matchers173432
-Node: Multiple matchers175422
-Node: Match groups175898
-Node: if table176791
-Node: balance-type178792
-Node: include179619
-Node: Working with CSV180188
-Node: Rapid feedback180740
-Node: Valid CSV181323
-Node: File Extension182199
-Node: Reading CSV from standard input182934
-Node: Reading multiple CSV files183320
-Node: Reading files specified by rule183796
-Node: Valid transactions185193
-Node: Deduplicating importing186018
-Node: Setting amounts187247
-Node: Amount signs189774
-Node: Setting currency/commodity190839
-Node: Amount decimal places192215
-Node: Referencing other fields193472
-Node: How CSV rules are evaluated194580
-Node: Well factored rules196248
-Node: CSV rules examples196738
-Node: Bank of Ireland196936
-Node: Coinbase198533
-Node: Amazon199716
-Node: Paypal201558
-Node: Timeclock209308
-Node: Timedot211577
-Node: Timedot examples215054
-Node: PART 3 REPORTING CONCEPTS217331
-Node: Time periods217495
-Node: Report start & end date217768
-Node: Smart dates219244
-Node: Report intervals221187
-Node: Date adjustments221761
-Node: Start date adjustment221981
-Node: End date adjustment222884
-Node: Period headings223629
-Node: Period expressions224562
-Node: Period expressions with a report interval226467
-Node: More complex report intervals226915
-Node: Multiple weekday intervals229031
-Node: Depth230042
-Node: Queries231877
-Node: Query types233575
-Node: acct query233992
-Node: amt query234303
-Node: code query234920
-Node: cur query235115
-Node: desc query235721
-Node: date query235904
-Node: date2 query236300
-Node: depth query236591
-Node: expr query236927
-Node: not query237308
-Node: note query237648
-Node: payee query237914
-Node: real query238195
-Node: status query238400
-Node: type query238640
-Node: tag query239173
-Node: Combining query terms239802
-Node: Queries and command options241542
-Node: Queries and account aliases241996
-Node: Queries and valuation242321
-Node: Pivoting242683
-Node: Generating data244574
-Node: Forecasting246374
-Node: --forecast247030
-Node: Inspecting forecast transactions248131
-Node: Forecast reports249464
-Node: Forecast tags250573
-Node: Forecast period in detail251193
-Node: Forecast troubleshooting252281
-Node: Budgeting253352
-Node: Amount formatting253912
-Node: Commodity display style254156
-Node: Rounding255997
-Node: Trailing decimal marks256602
-Node: Amount parseability257535
-Node: Cost reporting259116
-Node: Recording costs259919
-Node: Reporting at cost261646
-Node: Equity conversion postings262411
-Node: Inferring equity conversion postings265056
-Node: Combining costs and equity conversion postings266198
-Node: Requirements for detecting equity conversion postings267423
-Node: Infer cost and equity by default ?268945
-Node: Value reporting269382
-Node: -V Value270263
-Node: -X Value in specified commodity270590
-Node: Valuation date270940
-Node: Finding market price271900
-Node: --infer-market-prices market prices from transactions273280
-Node: Valuation commodity276324
-Node: --value Flexible valuation277757
-Node: Valuation examples279600
-Node: Interaction of valuation and queries281732
-Node: Effect of valuation on reports282449
-Node: PART 4 COMMANDS290347
-Node: Help commands292563
-Node: help292736
-Node: demo294441
-Node: User interface commands295588
-Node: ui295782
-Node: web295907
-Node: Data entry commands296035
-Node: add296233
-Node: import298688
-Node: Import preview299722
-Node: Overlap detection300670
-Node: First import303556
-Node: Importing balance assignments304751
-Node: Import and commodity styles305806
-Node: Import special cases306244
-Node: Basic report commands307579
-Node: accounts307880
-Node: codes310753
-Node: commodities311775
-Node: descriptions312019
-Node: files312486
-Node: notes312783
-Node: payees313295
-Node: prices314079
-Node: stats314971
-Node: tags316712
-Node: Standard report commands318019
-Node: print318324
-Node: print explicitness320998
-Node: print amount style321918
-Node: print parseability323156
-Node: print other features324075
-Node: print output format324773
-Node: aregister328058
-Node: aregister and posting dates332558
-Node: register333459
-Node: Custom register output340646
-Node: balancesheet342122
-Node: balancesheetequity347034
-Node: cashflow352316
-Node: incomestatement357020
-Node: Advanced report commands361760
-Node: balance361968
-Node: balance features367138
-Node: Simple balance report369214
-Node: Balance report line format371024
-Node: Filtered balance report373384
-Node: List or tree mode373903
-Node: Depth limiting375416
-Node: Dropping top-level accounts376183
-Node: Showing declared accounts376693
-Node: Sorting by amount377423
-Node: Percentages378260
-Node: Multi-period balance report378967
-Node: Balance change end balance381719
-Node: Balance report types383356
-Node: Calculation type384035
-Node: Accumulation type384739
-Node: Valuation type385840
-Node: Combining balance report types387029
-Node: Budget report389061
-Node: Using the budget report391366
-Node: Budget date surprises393642
-Node: Selecting budget goals395006
-Node: Budgeting vs forecasting395954
-Node: Balance report layout397631
-Node: Wide layout398836
-Node: Tall layout401241
-Node: Bare layout402547
-Node: Tidy layout404611
-Node: Balance report output406155
-Node: Some useful balance reports407141
-Node: roi408401
-Node: Spaces and special characters in --inv and --pnl410648
-Node: Semantics of --inv and --pnl411374
-Node: IRR and TWR explained413461
-Node: Chart commands416872
-Node: activity417053
-Node: Data generation commands417550
-Node: close417756
-Node: close --migrate420348
-Node: close --close422112
-Node: close --open422490
-Node: close --assert422739
-Node: close --assign423104
-Node: close --retain423776
-Node: close customisation424672
-Node: close and balance assertions426316
-Node: close examples427838
-Node: Retain earnings428075
-Node: Migrate balances to a new file428578
-Node: More detailed close examples429930
-Node: rewrite430152
-Node: Re-write rules in a file432724
-Node: Diff output format434034
-Node: rewrite vs print --auto435307
-Node: Maintenance commands436021
-Node: check436230
-Node: Basic checks437312
-Node: Strict checks438265
-Node: Other checks439140
-Node: Custom checks440995
-Node: diff441450
-Node: test442657
-Node: PART 5 COMMON TASKS443529
-Node: Getting help443762
-Node: Constructing command lines444671
-Node: Starting a journal file445509
-Node: Setting LEDGER_FILE446893
-Node: Setting opening balances448151
-Node: Recording transactions451473
-Node: Reconciling452198
-Node: Reporting454587
-Node: Migrating to a new file458701
-Node: BUGS459150
-Node: Troubleshooting460115
+This is hledger.info, produced by makeinfo version 7.2 from stdin.
+
+INFO-DIR-SECTION User Applications
+START-INFO-DIR-ENTRY
+* hledger: (hledger).  Command-line plain text accounting tool.
+END-INFO-DIR-ENTRY
+
+
+File: hledger.info,  Node: Top,  Next: PART 1 USER INTERFACE,  Up: (dir)
+
+hledger(1)
+**********
+
+hledger - a robust, friendly plain text accounting app (command line
+version).
+
+   'hledger'
+or
+'hledger COMMAND [OPTS] [ARGS]'
+or
+'hledger ADDONCMD [OPTS] -- [ADDONOPTS] [ADDONARGS]'
+
+   hledger is a robust, user-friendly, cross-platform set of programs
+for tracking money, time, or any other commodity, using double-entry
+accounting and a simple, editable file format.  hledger is inspired by
+and largely compatible with ledger(1), and largely interconvertible with
+beancount(1).
+
+   This manual is for hledger's command line interface, version 1.42.
+It also describes the common options, file formats and concepts used by
+all hledger programs.  It might accidentally teach you some
+bookkeeping/accounting as well!  You don't need to know everything in
+here to use hledger productively, but when you have a question about
+functionality, this doc should answer it.  It is detailed, so do skip
+ahead or skim when needed.  You can read it on hledger.org, or as an
+info manual or man page on your system.  You can also open a built-in
+copy, at a point of interest, by running
+'hledger --man [CMD]', 'hledger --info [CMD]' or 'hledger help [TOPIC]'.
+
+   (And for shorter help, try 'hledger --tldr [CMD]'.)
+
+   The main function of the hledger CLI is to read plain text files
+describing financial transactions, crunch the numbers, and print a
+useful report on the terminal (or save it as HTML, CSV, JSON or SQL).
+Many reports are available, as subcommands.  hledger will also detect
+other 'hledger-*' executables as extra subcommands.
+
+   hledger usually reads from (and appends to) a journal file specified
+by the 'LEDGER_FILE' environment variable (defaulting to
+'$HOME/.hledger.journal'); or you can specify files with '-f' options.
+It can also read timeclock files, timedot files, or any CSV/SSV/TSV file
+with a date field.
+
+   Here is a small journal file describing one transaction:
+
+2015-10-16 bought food
+  expenses:food          $10
+  assets:cash
+
+   Transactions are dated movements of money (etc.)  between two or more
+_accounts_: bank accounts, your wallet, revenue/expense categories,
+people, etc.  You can choose any account names you wish, using ':' to
+indicate subaccounts.  There must be at least two spaces between account
+name and amount.  Positive amounts are inflow to that account (_debit_),
+negatives are outflow from it (_credit_).  (Some reports show revenue,
+liability and equity account balances as negative numbers as a result;
+this is normal.)
+
+   hledger's add command can help you add transactions, or you can
+install other data entry UIs like hledger-web or hledger-iadd.  For more
+extensive/efficient changes, use a text editor: Emacs + ledger-mode, VIM
++ vim-ledger, or VS Code + hledger-vscode are some good choices (see
+https://hledger.org/editors.html).
+
+   To get started, run 'hledger add' and follow the prompts, or save
+some entries like the above in '$HOME/.hledger.journal', then try
+commands like:
+
+$ hledger print -x
+$ hledger aregister assets
+$ hledger balance
+$ hledger balancesheet
+$ hledger incomestatement
+
+   Run 'hledger' to list the commands.  See also the "Starting a journal
+file" and "Setting opening balances" sections in PART 5: COMMON TASKS.
+
+* Menu:
+
+* PART 1 USER INTERFACE::
+* Input::
+* Commands::
+* Options::
+* Output::
+* Environment::
+* PART 2 DATA FORMATS::
+* Journal::
+* CSV::
+* Timeclock::
+* Timedot::
+* PART 3 REPORTING CONCEPTS::
+* Time periods::
+* Depth::
+* Queries::
+* Pivoting::
+* Generating data::
+* Forecasting::
+* Budgeting::
+* Amount formatting::
+* Cost reporting::
+* Value reporting::
+* PART 4 COMMANDS::
+* Help commands::
+* User interface commands::
+* Data entry commands::
+* Basic report commands::
+* Standard report commands::
+* Advanced report commands::
+* Chart commands::
+* Data generation commands::
+* Maintenance commands::
+* PART 5 COMMON TASKS::
+* Getting help::
+* Constructing command lines::
+* Starting a journal file::
+* Setting LEDGER_FILE::
+* Setting opening balances::
+* Recording transactions::
+* Reconciling::
+* Reporting::
+* Migrating to a new file::
+* BUGS::
+
+
+File: hledger.info,  Node: PART 1 USER INTERFACE,  Next: Input,  Prev: Top,  Up: Top
+
+1 PART 1: USER INTERFACE
+************************
+
+
+File: hledger.info,  Node: Input,  Next: Commands,  Prev: PART 1 USER INTERFACE,  Up: Top
+
+2 Input
+*******
+
+hledger reads one or more data files, each time you run it.  You can
+specify a file with '-f', like so
+
+$ hledger -f FILE [-f FILE2 ...] print
+
+   Files are most often in hledger's journal format, with the '.journal'
+file extension ('.hledger' or '.j' also work); these files describe
+transactions, like an accounting general journal.
+
+   When no file is specified, hledger looks for '.hledger.journal' in
+your home directory.
+
+   But most people prefer to keep financial files in a dedicated folder,
+perhaps with version control.  Also, starting a new journal file each
+year is common (it's not required, but helps keep things fast and
+organised).  So we usually configure a different journal file, by
+setting the 'LEDGER_FILE' environment variable, to something like
+'~/finance/2023.journal'.  For more about how to do that on your system,
+see Common tasks > Setting LEDGER_FILE.
+
+* Menu:
+
+* Text encoding::
+* Data formats::
+* Standard input::
+* Multiple files::
+* Strict mode::
+
+
+File: hledger.info,  Node: Text encoding,  Next: Data formats,  Up: Input
+
+2.1 Text encoding
+=================
+
+hledger input files containing non-ascii characters must use UTF-8
+encoding, with the exception of CSV (SSV, TSV..) files, which can be
+read from other encodings (see 'encoding' CSV rule).
+
+   In UTF-8 input files, an optional byte order mark (BOM) at the
+beginning of the file is allowed.
+
+   Your system may need to be configured with a locale that understands
+the input file's encoding.  Eg on some unix systems, you may need set
+the 'LANG' environment variable.  You can read more about this in
+Unicode characters, below.
+
+   On some unix systems you can use the 'file' command to show a file's
+text encoding.  On mac, you'll need the version from homebrew: 'brew
+install file-formula'.
+
+   hledger's text output is always UTF-8 encoded.
+
+
+File: hledger.info,  Node: Data formats,  Next: Standard input,  Prev: Text encoding,  Up: Input
+
+2.2 Data formats
+================
+
+Usually the data file is in hledger's journal format, but it can be in
+any of the supported file formats, which currently are:
+
+Reader:        Reads:                             Automatically used for
+                                                  files with extensions:
+---------------------------------------------------------------------------
+'journal'      hledger journal files and some     '.journal' '.j'
+               Ledger journals, for               '.hledger' '.ledger'
+               transactions
+'timeclock'    timeclock files, for precise       '.timeclock'
+               time logging
+'timedot'      timedot files, for approximate     '.timedot'
+               time logging
+'csv'          Comma or other character           '.csv'
+               separated values, for data
+               import
+'ssv'          Semicolon separated values         '.ssv'
+'tsv'          Tab separated values               '.tsv'
+'rules'        CSV/SSV/TSV/other separated        '.rules'
+               values, alternate way
+
+   These formats are described in more detail below.
+
+   hledger detects the format automatically based on the file extensions
+shown above.  If it can't recognise the file extension, it assumes
+'journal' format.  So for non-journal files, it's important to use a
+recognised file extension, so as to either read successfully or to show
+relevant error messages.
+
+   You can also force a specific reader/format by prefixing the file
+path with the format and a colon.  Eg, to read a .dat file containing
+tab separated values:
+
+$ hledger -f tsv:/some/file.dat stats
+
+
+File: hledger.info,  Node: Standard input,  Next: Multiple files,  Prev: Data formats,  Up: Input
+
+2.3 Standard input
+==================
+
+The file name '-' means standard input:
+
+$ cat FILE | hledger -f- print
+
+   If reading non-journal data in this way, you'll need to write the
+format as a prefix, like 'timeclock:' here:
+
+$ echo 'i 2009/13/1 08:00:00' | hledger print -f timeclock:-
+
+
+File: hledger.info,  Node: Multiple files,  Next: Strict mode,  Prev: Standard input,  Up: Input
+
+2.4 Multiple files
+==================
+
+You can specify multiple '-f' options, to read multiple files as one big
+journal.  When doing this, note that certain features (described below)
+will be affected:
+
+   * Balance assertions will not see the effect of transactions in
+     previous files.  (Usually this doesn't matter as each file will set
+     the corresponding opening balances.)
+   * Some directives will not affect previous or subsequent files.
+
+   If needed, you can work around these by using a single parent file
+which includes the others, or concatenating the files into one, eg: 'cat
+a.journal b.journal | hledger -f- CMD'.
+
+
+File: hledger.info,  Node: Strict mode,  Prev: Multiple files,  Up: Input
+
+2.5 Strict mode
+===============
+
+hledger checks input files for valid data.  By default, the most
+important errors are detected, while still accepting easy journal files
+without a lot of declarations:
+
+   * Are the input files parseable, with valid syntax ?
+   * Are all transactions balanced ?
+   * Do all balance assertions pass ?
+
+   With the '-s'/'--strict' flag, additional checks are performed:
+
+   * Are all accounts posted to, declared with an 'account' directive ?
+     (Account error checking)
+   * Are all commodities declared with a 'commodity' directive ?
+     (Commodity error checking)
+   * Are all commodity conversions declared explicitly ?
+
+   You can use the check command to run individual checks - the ones
+listed above and some more.
+
+
+File: hledger.info,  Node: Commands,  Next: Options,  Prev: Input,  Up: Top
+
+3 Commands
+**********
+
+hledger provides various subcommands for getting things done.  Most of
+these commands do not change the journal file; they just read it and
+output a report.  A few commands assist with adding data and file
+management.
+
+   To show a summary of commands, run 'hledger' with no arguments.  You
+can see the same commands summary at the start of PART 4: COMMANDS
+below.
+
+   To use a particular command, run 'hledger CMD [CMDOPTS] [CMDARGS]',
+
+   * CMD is the full command name, or its standard abbreviation shown in
+     the commands list, or any unambiguous prefix of the name.
+
+   * CMDOPTS are command-specific options, if any.  Command-specific
+     options must be written after the command name.  Eg: 'hledger print
+     -x'.
+
+   * CMDARGS are additional arguments to the command, if any.  Most
+     hledger commands accept arguments representing a query, to limit
+     the data in some way.  Eg: 'hledger reg assets:checking'.
+
+   To list a command's options, arguments, and documentation in the
+terminal, run 'hledger CMD -h'.  Eg: 'hledger bal -h'.
+
+* Menu:
+
+* Add-on commands::
+
+
+File: hledger.info,  Node: Add-on commands,  Up: Commands
+
+3.1 Add-on commands
+===================
+
+In addition to the built-in commands, you can install _add-on commands_:
+programs or scripts named "hledger-SOMETHING", which will also appear in
+hledger's commands list.  If you used the hledger-install script, you
+will have several add-ons installed already.  Some more can be found in
+hledger's bin/ directory, documented at
+https://hledger.org/scripts.html.
+
+   More precisely, add-on commands are programs or scripts in your
+shell's PATH, whose name starts with "hledger-" and ends with no
+extension or a recognised extension (".bat", ".com", ".exe", ".hs",
+".js", ".lhs", ".lua", ".php", ".pl", ".py", ".rb", ".rkt", or ".sh"),
+and (on unix and mac) which has executable permission for the current
+user.
+
+   You can run add-on commands using hledger, much like built-in
+commands: 'hledger ADDONCMD [-- ADDONCMDOPTS] [ADDONCMDARGS]'.  But note
+the double hyphen argument, required before add-on-specific options.
+Eg: 'hledger ui -- --watch' or 'hledger web -- --serve'.  If this causes
+difficulty, you can always run the add-on directly, without using
+'hledger': 'hledger-ui --watch' or 'hledger-web --serve'.
+
+
+File: hledger.info,  Node: Options,  Next: Output,  Prev: Commands,  Up: Top
+
+4 Options
+*********
+
+Run 'hledger -h' to see general command line help.  Options can be
+written either before or after the command name.  These options are
+specific to the 'hledger' CLI:
+
+Flags:
+     --conf=CONFFILE        Use extra options defined in this config file. If
+                            not specified, searches upward and in XDG config
+                            dir for hledger.conf (or .hledger.conf in $HOME).
+  -n --no-conf              ignore any config file
+
+   And the following general options are common to most hledger
+commands:
+
+General input/data transformation flags:
+  -f --file=[FMT:]FILE      Read data from FILE, or from stdin if FILE is -,
+                            inferring format from extension or a FMT: prefix.
+                            Can be specified more than once. If not specified,
+                            reads from $LEDGER_FILE or $HOME/.hledger.journal.
+     --rules=RULESFILE      Use rules defined in this rules file for
+                            converting subsequent CSV/SSV/TSV files. If not
+                            specified, uses FILE.csv.rules for each FILE.csv.
+     --alias=A=B|/RGX/=RPL  transform account names from A to B, or by
+                            replacing regular expression matches
+     --auto                 generate extra postings by applying auto posting
+                            rules ("=") to all transactions
+     --forecast[=PERIOD]    Generate extra transactions from periodic rules
+                            ("~"), from after the latest ordinary transaction
+                            until 6 months from now. Or, during the specified
+                            PERIOD (the equals is required). Auto posting rules
+                            will also be applied to these transactions. In
+                            hledger-ui, also make future-dated transactions
+                            visible at startup.
+  -I --ignore-assertions    don't check balance assertions by default
+     --infer-costs          infer conversion equity postings from costs
+     --infer-equity         infer costs from conversion equity postings
+     --infer-market-prices  infer market prices from costs
+     --pivot=TAGNAME        use a different field or tag as account names
+  -s --strict               do extra error checks (and override -I)
+     --verbose-tags         add tags indicating generated/modified data
+
+General output/reporting flags (supported by some commands):
+  -b --begin=DATE           include postings/transactions on/after this date
+  -e --end=DATE             include postings/transactions before this date
+                            (with a report interval, will be adjusted to
+                            following subperiod end)
+  -D --daily                multiperiod report with 1 day interval
+  -W --weekly               multiperiod report with 1 week interval
+  -M --monthly              multiperiod report with 1 month interval
+  -Q --quarterly            multiperiod report with 1 quarter interval
+  -Y --yearly               multiperiod report with 1 year interval
+  -p --period=PERIODEXP     set begin date, end date, and/or report interval,
+                            with more flexibility
+     --today=DATE           override today's date (affects relative dates)
+     --date2                match/use secondary dates instead (deprecated)
+  -U --unmarked             include only unmarked postings/transactions
+  -P --pending              include only pending postings/transactions
+  -C --cleared              include only cleared postings/transactions
+                            (-U/-P/-C can be combined)
+  -R --real                 include only non-virtual postings
+  -E --empty                Show zero items, which are normally hidden.
+                            In hledger-ui & hledger-web, do the opposite.
+     --depth=DEPTHEXP       if a number (or -NUM): show only top NUM levels
+                            of accounts. If REGEXP=NUM, only apply limiting to
+                            accounts matching the regular expression.
+  -B --cost                 show amounts converted to their cost/sale amount
+  -V --market               Show amounts converted to their value at period
+                            end(s) in their default valuation commodity.
+                            Equivalent to --value=end.
+  -X --exchange=COMM        Show amounts converted to their value at period
+                            end(s) in the specified commodity.
+                            Equivalent to --value=end,COMM.
+     --value=WHEN[,COMM]    show amounts converted to their value on the
+                            specified date(s) in their default valuation
+                            commodity or a specified commodity. WHEN can be:
+                            'then':     value on transaction dates
+                            'end':      value at period end(s)
+                            'now':      value today
+                            YYYY-MM-DD: value on given date
+  -c --commodity-style=S    Override a commodity's display style.
+                            Eg: -c '.' or -c '1.000,00 EUR'
+     --pretty[=YN]          Use box-drawing characters in text output? Can be
+                            'y'/'yes' or 'n'/'no'.
+                            If YN is specified, the equals is required.
+
+General help flags:
+  -h --help                 show command line help
+     --tldr                 show command examples with tldr
+     --info                 show the manual with info
+     --man                  show the manual with man
+     --version              show version information
+     --debug=[1-9]          show this much debug output (default: 1)
+     --pager=YN             use a pager when needed ? y/yes (default) or n/no
+     --color=YNA --colour   use ANSI color ? y/yes, n/no, or auto (default)
+
+   Usually hledger accepts any unambiguous flag prefix, eg you can write
+'--tl' instead of '--tldr' or '--dry' instead of '--dry-run'.
+
+   If the same option appears more than once in a command, usually the
+last (right-most) wins.
+
+   With most commands, arguments are interpreted as a hledger query
+which filter the data.  Some queries can be expressed either with
+options or with arguments.
+
+   Below are more tips for using the command line interface - feel free
+to skip these until you need them.
+
+* Menu:
+
+* Special characters::
+* Unicode characters::
+* Regular expressions::
+* Argument files::
+* Config files::
+* Shell completions::
+
+
+File: hledger.info,  Node: Special characters,  Next: Unicode characters,  Up: Options
+
+4.1 Special characters
+======================
+
+Here we touch on shell escaping/quoting rules, and give some examples.
+This is a slightly complicated topic which you may not need at first,
+but you should be aware of it, so you can return here when needed.
+
+   If you are able to minimise the use of special characters in your
+data, you won't need escaping as much, and your command lines will be
+simpler.  For example, avoiding spaces in account names, and using an
+ISO-4217 currency code like 'USD' instead of the '$' currency symbol,
+can be helpful.
+
+   But if you want to use spaced account names and '$', go right ahead;
+escaping isn't a big deal.
+
+* Menu:
+
+* Escaping shell special characters::
+* Escaping on Windows::
+* Escaping regular expression special characters::
+* Escaping add-on arguments::
+* Escaping in other situations::
+* Using a wild card::
+
+
+File: hledger.info,  Node: Escaping shell special characters,  Next: Escaping on Windows,  Up: Special characters
+
+4.1.1 Escaping shell special characters
+---------------------------------------
+
+At the command line, characters which have special meaning for your
+shell must be "shell-escaped" (AKA "quoted") if you want hledger to see
+them.  Often these include space, '<', '>', '(', ')', '|', '\', '$'
+and/or '%'.
+
+   For example, to match an account name containing the phrase "credit
+card", don't write this:
+
+$ hledger register credit card
+
+   In that command, "credit" and "card" are treated as separate query
+arguments (described below), so this would match accounts containing
+either word.  Instead, enclose the phrase in double or single quotes:
+
+$ hledger register "credit card"
+
+   In Unix shells, writing a backslash before the character can also
+work.  Eg:
+
+$ hledger register credit\ card
+
+   Some shell characters still have a special meaning inside double
+quotes, such as the dollar sign ('$').  Eg in '"assets:$account"', the
+bash shell would replace '$account' with the value of a shell variable
+with that name.  When you don't want that, use single quotes, which
+escape more strongly:
+
+$ hledger balance 'assets:$account'
+
+
+File: hledger.info,  Node: Escaping on Windows,  Next: Escaping regular expression special characters,  Prev: Escaping shell special characters,  Up: Special characters
+
+4.1.2 Escaping on Windows
+-------------------------
+
+If you are using hledger in a Powershell or Command window on Microsoft
+Windows, the escaping rules are different:
+
+   * In a Powershell window ('powershell', blue background), you must
+     use double quotes or single quotes (not backslash).
+   * In a Command window ('cmd', black background), you must use double
+     quotes (not single quotes or backslash).
+
+   The next two sections were written for Unix-like shells, so might
+need to be adapted if you're using 'cmd' or 'powershell'.  (Edits
+welcome.)
+
+
+File: hledger.info,  Node: Escaping regular expression special characters,  Next: Escaping add-on arguments,  Prev: Escaping on Windows,  Up: Special characters
+
+4.1.3 Escaping regular expression special characters
+----------------------------------------------------
+
+Many hledger arguments are regular expressions (described below), and
+these too have characters which cause special effects.  Some of those
+characters are '.', '^', '$', '[', ']', '(', ')', '|', and '\'.  When
+you don't want these to cause special effects, you can "regex-escape"
+them by writing '\' (a backslash) before them.  But since backslash is
+also special to the shell, you may need to also shell-escape the
+backslashes.
+
+   Eg, in the bash shell, to match a literal '$' sign, you could write:
+
+$ hledger balance cur:\\$
+
+   or:
+
+$ hledger balance 'cur:\$'
+
+   (The dollar sign is regex-escaped by the backslash preceding it.
+Then that backslash is shell-escaped by another backslash, or by single
+quotes.)
+
+
+File: hledger.info,  Node: Escaping add-on arguments,  Next: Escaping in other situations,  Prev: Escaping regular expression special characters,  Up: Special characters
+
+4.1.4 Escaping add-on arguments
+-------------------------------
+
+When you run an external add-on command with 'hledger' (described
+below), any options or arguments being passed through to the add-on
+executable lose one level of shell-escaping, so you must add an extra
+level of shell-escaping to compensate.
+
+   Eg, in the bash shell, to run the 'ui' add-on and match a literal '$'
+sign, you need to write:
+
+$ hledger ui cur:'\\$'
+
+   or:
+
+$ hledger ui cur:\\\\$
+
+   If you are wondering why _four_ backslashes:
+
+   * '$' is unescaped
+   * '\$' is regex-escaped
+   * '\\$' is regex-escaped, then shell-escaped
+   * '\\\\$' is regex-escaped, then shell-escaped, then both slashes are
+     shell-escaped once more for hledger argument pass-through.
+
+   Or you can avoid such triple-escaping, by running the add-on
+executable directly:
+
+$ hledger-ui cur:\\$
+
+
+File: hledger.info,  Node: Escaping in other situations,  Next: Using a wild card,  Prev: Escaping add-on arguments,  Up: Special characters
+
+4.1.5 Escaping in other situations
+----------------------------------
+
+hledger options and arguments are sometimes used in places other than
+the command line, with different escaping rules.  For example,
+backslash-quoting generally does not work there.  Here are some more
+tips.
+
+In Windows 'cmd'   Use double quotes
+In Windows         Use single or double quotes
+'powershell'
+In hledger-ui's    Use single or double quotes
+filter prompt
+In hledger-web's   Use single or double quotes
+search form
+In an argument     Don't use spaces, don't shell-escape, do
+file               regex-escape when needed
+In a config file   Use single or double quotes, and enclose the whole
+                   argument ('"desc:a b"' not 'desc:"a b"')
+In 'ghci' (the     Use double quotes, and enclose the whole argument
+Haskell REPL)
+
+
+File: hledger.info,  Node: Using a wild card,  Prev: Escaping in other situations,  Up: Special characters
+
+4.1.6 Using a wild card
+-----------------------
+
+When escaping a special character is too much hassle (or impossible),
+you can often just write '.' (period) instead.  In regular expressions,
+this means "accept any character here".  Eg:
+
+$ hledger register credit.card
+
+
+File: hledger.info,  Node: Unicode characters,  Next: Regular expressions,  Prev: Special characters,  Up: Options
+
+4.2 Unicode characters
+======================
+
+hledger is expected to handle non-ascii characters correctly:
+
+   * they should be parsed correctly in input files and on the command
+     line, by all hledger tools (add, iadd, hledger-web's
+     search/add/edit forms, etc.)
+
+   * they should be displayed correctly by all hledger tools, and
+     on-screen alignment should be preserved.
+
+   This requires a well-configured environment.  Here are some tips:
+
+   * A system locale must be configured, and it must be one that can
+     decode the characters being used.  In bash, you can set a locale
+     like this: 'export LANG=en_US.UTF-8'.  There are some more details
+     in Troubleshooting.  This step is essential - without it, hledger
+     will quit on encountering a non-ascii character (as with all
+     GHC-compiled programs).
+
+   * Your terminal software (eg Terminal.app, iTerm, CMD.exe, xterm..)
+     must support unicode.  On Windows, you may need to use Windows
+     Terminal and/or enable UTF-8 support.
+
+   * The terminal must be using a font which includes the required
+     unicode glyphs.
+
+   * The terminal should be configured to display wide characters as
+     double width (for report alignment).
+
+   * On Windows, for best results you should run hledger in the same
+     kind of environment in which it was built.  Eg hledger built in the
+     standard CMD.EXE environment (like the binaries on our download
+     page) might show display problems when run in a cygwin or msys
+     terminal, and vice versa.  (See eg #961).
+
+
+File: hledger.info,  Node: Regular expressions,  Next: Argument files,  Prev: Unicode characters,  Up: Options
+
+4.3 Regular expressions
+=======================
+
+A regular expression (regexp) is a small piece of text where certain
+characters (like '.', '^', '$', '+', '*', '()', '|', '[]', '\') have
+special meanings, forming a tiny language for matching text precisely -
+very useful in hledger and elsewhere.  To learn all about them, visit
+regular-expressions.info.
+
+   hledger supports regexps whenever you are entering a pattern to match
+something, eg in query arguments, account aliases, CSV if rules,
+hledger-web's search form, hledger-ui's '/' search, etc.  You may need
+to wrap them in quotes, especially at the command line (see Special
+characters above).  Here are some examples:
+
+   Account name queries (quoted for command line use):
+
+Regular expression:  Matches:
+-------------------  ------------------------------------------------------------
+bank                 assets:bank, assets:bank:savings, expenses:art:banksy, ...
+:bank                assets:bank:savings, expenses:art:banksy
+:bank:               assets:bank:savings
+'^bank'              none of those ( ^ matches beginning of text )
+'bank$'              assets:bank   ( $ matches end of text )
+'big \$ bank'        big $ bank    ( \ disables following character's special meaning )
+'\bbank\b'           assets:bank, assets:bank:savings  ( \b matches word boundaries )
+'(sav|check)ing'     saving or checking  ( (|) matches either alternative )
+'saving|checking'    saving or checking  ( outer parentheses are not needed )
+'savings?'           saving or savings   ( ? matches 0 or 1 of the preceding thing )
+'my +bank'           my bank, my  bank, ... ( + matches 1 or more of the preceding thing )
+'my *bank'           mybank, my bank, my  bank, ... ( * matches 0 or more of the preceding thing )
+'b.nk'               bank, bonk, b nk, ... ( . matches any character )
+
+   Some other queries:
+
+desc:'amazon|amzn|audible'  Amazon transactions
+cur:EUR              amounts with commodity symbol containing EUR
+cur:'\$'             amounts with commodity symbol containing $
+cur:'^\$$'           only $ amounts, not eg AU$ or CA$
+cur:....?            amounts with 4-or-more-character symbols
+tag:.=202[1-3]       things with any tag whose value contains 2021, 2022 or 2023
+
+   Account name aliases: accept '.' instead of ':' as account separator:
+
+alias /\./=:         replaces all periods in account names with colons
+
+   Show multiple top-level accounts combined as one:
+
+--alias='/^[^:]+/=combined'  ( [^:] matches any character other than : )
+
+   Show accounts with the second-level part removed:
+
+--alias '/^([^:]+):[^:]+/ = \1'
+                     match a top-level account and a second-level account
+                     and replace those with just the top-level account
+                     ( \1 in the replacement text means "whatever was matched
+                     by the first parenthesised part of the regexp"
+
+   CSV rules: match CSV records containing dining-related MCC codes:
+
+if \?MCC581[124]
+
+   Match CSV records with a specific amount around the end/start of
+month:
+
+if %amount \b3\.99
+&  %date   (29|30|31|01|02|03)$
+
+* Menu:
+
+* hledger's regular expressions::
+
+
+File: hledger.info,  Node: hledger's regular expressions,  Up: Regular expressions
+
+4.3.1 hledger's regular expressions
+-----------------------------------
+
+hledger's regular expressions come from the regex-tdfa library.  If
+they're not doing what you expect, it's important to know exactly what
+they support:
+
+  1. they are case insensitive
+  2. they are infix matching (they do not need to match the entire thing
+     being matched)
+  3. they are POSIX ERE (extended regular expressions)
+  4. they also support GNU word boundaries ('\b', '\B', '\<', '\>')
+  5. backreferences are supported when doing text replacement in account
+     aliases or CSV rules, where backreferences can be used in the
+     replacement string to reference capturing groups in the search
+     regexp.  Otherwise, if you write '\1', it will match the digit '1'.
+  6. they do not support mode modifiers ('(?s)'), character classes
+     ('\w', '\d'), or anything else not mentioned above.
+  7. they may not (I'm guessing not) properly support right-to-left or
+     bidirectional text.
+
+   Some things to note:
+
+   * In the 'alias' directive and '--alias' option, regular expressions
+     must be enclosed in forward slashes ('/REGEX/').  Elsewhere in
+     hledger, these are not required.
+
+   * In queries, to match a regular expression metacharacter like '$' as
+     a literal character, prepend a backslash.  Eg to search for amounts
+     with the dollar sign in hledger-web, write 'cur:\$'.
+
+   * On the command line, some metacharacters like '$' have a special
+     meaning to the shell and so must be escaped at least once more.
+     See Special characters.
+
+
+File: hledger.info,  Node: Argument files,  Next: Config files,  Prev: Regular expressions,  Up: Options
+
+4.4 Argument files
+==================
+
+You can save a set of command line options and arguments in a file, and
+then reuse them by writing '@FILENAME' as a command line argument.  Eg:
+'hledger bal @foo.args'.
+
+   An argument file's format is more restrictive than the command line.
+Each line should contain just one option or argument.  Don't use spaces
+except inside quotes; write '=' or nothing between a flag and its
+argument.  If you use quotes, they must enclose the whole line.  For the
+special characters mentioned above, use one less level of quoting than
+you would at the command line.
+
+
+File: hledger.info,  Node: Config files,  Next: Shell completions,  Prev: Argument files,  Up: Options
+
+4.5 Config files
+================
+
+With hledger 1.40+, you can save extra command line options and
+arguments in a more featureful hledger config file.  Here's a small
+example:
+
+# General options are listed first, and used with hledger commands that support them.
+--pretty
+
+# Options following a `[COMMAND]` heading are used with that hledger command only.
+[print]
+--explicit --show-costs
+
+   To use a config file, specify it with the '--conf' option.  Its
+options will be inserted near the start of your command line, so you can
+override them with command line options if needed.
+
+   Or, you can set up an automatic config file that is used whenever you
+run hledger, by creating 'hledger.conf' in the current directory or
+above, or '.hledger.conf' in your home directory ('~/.hledger.conf'), or
+'hledger.conf' in your XDG config directory
+('~/.config/hledger/hledger.conf').
+
+   Here is another example config you could start with:
+https://github.com/simonmichael/hledger/blob/master/hledger.conf.sample
+
+   You can put not only options, but also arguments in a config file.
+If the first word in a config file's top (general) section does not
+begin with a dash (eg: 'print'), it is treated as the command argument
+(overriding any argument on the command line).
+
+   On unix machines, you can add a shebang line at the top of a config
+file, set executable permission on the file, and use it like a script.
+Eg (the '-S' is needed on some operating systems):
+
+#!/usr/bin/env -S hledger --conf
+
+   You can ignore config files by adding the '-n'/'--no-conf' flag to
+the command line.  This is useful when using hledger in scripts, or when
+troubleshooting.  When both '--conf' and '--no-conf' options are used,
+the right-most wins.
+
+   To inspect the processing of config files, use '--debug' or
+'--debug=8'.
+
+   *Warning!*
+
+   There aren't many hledger features that need a warning, but this is
+one!
+
+   Automatic config files, while convenient, also make hledger less
+predictable and dependable.  It's easy to make a config file that
+changes a report's behaviour, or breaks your hledger-using
+scripts/applications, in ways that will surprise you later.
+
+   If you don't want this,
+
+  1. Just don't create a hledger.conf file on your machine.
+  2. Also be alert to downloaded directories which may contain a
+     hledger.conf file.
+  3. Also if you are sharing scripts or examples or support, consider
+     that others may have a hledger.conf file.
+
+   Conversely, once you decide to use this feature, try to remember:
+
+  1. Whenever a hledger command does not work as expected, try it again
+     with '-n' ('--no-conf') to see if a config file was to blame.
+  2. Whenever you call hledger from a script, consider whether that call
+     should use '-n' or not.
+  3. Be conservative about what you put in your config file; try to
+     consider the effect on all your reports.
+  4. To troubleshoot the effect of config files, run with '--debug' or
+     '--debug 8'.
+
+   The config file feature was added in hledger 1.40 and is considered
+_experimental_.
+
+
+File: hledger.info,  Node: Shell completions,  Prev: Config files,  Up: Options
+
+4.6 Shell completions
+=====================
+
+If you use the bash or zsh shells, you can optionally set up
+context-sensitive autocompletion for hledger command lines.  Try
+pressing 'hledger<SPACE><TAB><TAB>' (should list all hledger commands)
+or 'hledger reg acct:<TAB><TAB>' (should list your top-level account
+names).  If completions aren't working, or for more details, see Install
+> Shell completions.
+
+
+File: hledger.info,  Node: Output,  Next: Environment,  Prev: Options,  Up: Top
+
+5 Output
+********
+
+* Menu:
+
+* Output destination::
+* Output format::
+* Commodity styles::
+* Debug output::
+
+
+File: hledger.info,  Node: Output destination,  Next: Output format,  Up: Output
+
+5.1 Output destination
+======================
+
+hledger commands send their output to the terminal by default.  You can
+of course redirect this, eg into a file, using standard shell syntax:
+
+$ hledger print > foo.txt
+
+   Some commands (print, register, stats, the balance commands) also
+provide the '-o'/'--output-file' option, which does the same thing
+without needing the shell.  Eg:
+
+$ hledger print -o foo.txt
+$ hledger print -o -        # write to stdout (the default)
+
+
+File: hledger.info,  Node: Output format,  Next: Commodity styles,  Prev: Output destination,  Up: Output
+
+5.2 Output format
+=================
+
+Some commands offer other kinds of output, not just text on the
+terminal.  Here are those commands and the formats currently supported:
+
+command               txt   html   csv/tsv   fods   beancount    sql   json
+------------------------------------------------------------------------------
+aregister             Y     Y      Y         Y                         Y
+balance               Y     Y      Y         Y                         Y
+balancesheet          Y     Y      Y         Y                         Y
+balancesheetequity    Y     Y      Y         Y                         Y
+cashflow              Y     Y      Y         Y                         Y
+incomestatement       Y     Y      Y         Y                         Y
+print                 Y     Y      Y         Y      Y            Y     Y
+register              Y     Y      Y         Y                         Y
+
+   You can also see which output formats a command supports by running
+'hledger CMD -h' and looking for the '-O'/'--output-format=FMT' option,
+
+   You can select the output format by using that option:
+
+$ hledger print -O csv    # print CSV to standard output
+
+   or by choosing a suitable filename extension with the
+'-o'/'--output-file=FILE.FMT' option:
+
+$ hledger balancesheet -o foo.csv    # write CSV to foo.csv
+
+   The '-O' option can be combined with '-o' to override the file
+extension if needed:
+
+$ hledger balancesheet -o foo.txt -O csv    # write CSV to foo.txt
+
+   Here are some notes about the various output formats.
+
+* Menu:
+
+* Text output::
+* HTML output::
+* CSV / TSV output::
+* FODS output::
+* Beancount output::
+* SQL output::
+* JSON output::
+
+
+File: hledger.info,  Node: Text output,  Next: HTML output,  Up: Output format
+
+5.2.1 Text output
+-----------------
+
+This is the default: human readable, plain text report output, suitable
+for viewing with a monospace font in a terminal.  If your data contains
+unicode or wide characters, you'll need a terminal and font that render
+those correctly.  (This can be challenging on MS Windows.)
+
+   Some reports ('register', 'aregister') will normally use the full
+window width.  If this isn't working or you want to override it, you can
+use the '-w'/'--width' option.
+
+   Balance reports ('balance', 'balancesheet', 'incomestatement'...)
+use whatever width they need.  Multi-period multi-currency reports can
+often be wider than the window.  Besides using a pager, helpful
+techniques for this situation include '--layout=bare', '-V', 'cur:',
+'--transpose', '--tree', '--depth', '--drop', switching to html output,
+etc.
+
+* Menu:
+
+* Box-drawing characters::
+* Colour::
+* Paging::
+
+
+File: hledger.info,  Node: Box-drawing characters,  Next: Colour,  Up: Text output
+
+5.2.1.1 Box-drawing characters
+..............................
+
+hledger draws simple table borders by default, to minimise the risk of
+display problems caused by a terminal/font not supporting box-drawing
+characters.
+
+   But your terminal and font probably do support them, so we recommend
+using the '--pretty' flag to show prettier tables in the terminal.  This
+is a good flag to add to your hledger config file.
+
+
+File: hledger.info,  Node: Colour,  Next: Paging,  Prev: Box-drawing characters,  Up: Text output
+
+5.2.1.2 Colour
+..............
+
+hledger tries to automatically detect ANSI colour and text styling
+support and use it when appropriate.  (Currently, it is used rather
+minimally: some reports show negative numbers in red, and help output
+uses bold text for emphasis.)
+
+   You can override this by setting the 'NO_COLOR' environment variable
+to disable it, or by using the '--color/--colour' option, perhaps in
+your config file, with a 'y'/'yes' or 'n'/'no' value to force it on or
+off.
+
+
+File: hledger.info,  Node: Paging,  Prev: Colour,  Up: Text output
+
+5.2.1.3 Paging
+..............
+
+In unix-like environments, when displaying large output (in any output
+format) in the terminal, hledger tries to use a pager when appropriate.
+(You can disable this with the '--pager=no' option, perhaps in your
+config file.)
+
+   The pager shows one page of text at a time, and lets you scroll
+around to see more.  While it is active, usually 'SPACE' shows the next
+page, 'h' shows help, and 'q' quits.  The home/end/page up/page
+down/cursor keys, and mouse scrolling, may also work.
+
+   hledger will use the pager specified by the 'PAGER' environment
+variable, otherwise 'less' if available, otherwise 'more' if available.
+(With one exception: 'hledger help -p TOPIC' will always use 'less', so
+that it can scroll to the topic.)
+
+   The pager is expected to display hledger's ANSI colour and text
+styling.  If you see junk characters, you might need to configure your
+pager to handle ANSI codes.  Or you could disable colour as described
+above.
+
+   If you are using the 'less' pager, hledger automatically appends a
+number of options to the 'LESS' variable to enable ANSI colour and a
+number of other conveniences.  (At the time of writing: -chop-long-lines
+-hilite-unread -ignore-case -mouse -no-init -quit-at-eof
+-quit-if-one-screen -RAW-CONTROL-CHARS -shift=8 -squeeze-blank-lines
+-use-backslash ).  If these don't work well, you can set your preferred
+options in the 'HLEDGER_LESS' variable, which will be used instead.
+
+
+File: hledger.info,  Node: HTML output,  Next: CSV / TSV output,  Prev: Text output,  Up: Output format
+
+5.2.2 HTML output
+-----------------
+
+HTML output can be styled by an optional 'hledger.css' file in the same
+directory.
+
+   HTML output will be UTF-8 encoded.  If your web browser is showing
+junk characters, you may need to change its text encoding to UTF-8.  Eg
+in Safari, see View -> Text Encoding and Settings -> Advanced -> Default
+Encoding.
+
+
+File: hledger.info,  Node: CSV / TSV output,  Next: FODS output,  Prev: HTML output,  Up: Output format
+
+5.2.3 CSV / TSV output
+----------------------
+
+In CSV or TSV output, digit group marks (such as thousands separators)
+are disabled automatically.
+
+
+File: hledger.info,  Node: FODS output,  Next: Beancount output,  Prev: CSV / TSV output,  Up: Output format
+
+5.2.4 FODS output
+-----------------
+
+FODS is the OpenDocument Spreadsheet format as plain XML, as accepted by
+LibreOffice and OpenOffice.  If you use their spreadsheet applications,
+this is better than CSV because it works across locales (decimal point
+vs.  decimal comma, character encoding stored in XML header, thus no
+problems with umlauts), it supports fixed header rows and columns, cell
+types (string vs.  number vs.  date), separation of number and currency
+(currency is displayed but the cell type is still a number accessible
+for computation), styles (bold), borders.  Btw.  you can still extract
+CSV from FODS/ODS using various utilities like 'libreoffice --headless'
+or ods2csv.
+
+
+File: hledger.info,  Node: Beancount output,  Next: SQL output,  Prev: FODS output,  Up: Output format
+
+5.2.5 Beancount output
+----------------------
+
+This is Beancount's journal format.  You can use this to export your
+hledger data to Beancount, eg to use the Fava web app.
+
+   hledger will try to adjust your data to suit Beancount,
+automatically.  Be cautious and check the conversion until you are
+confident it is good.  If you plan to export to Beancount often, you may
+want to follow its conventions, for a cleaner conversion:
+
+   * use Beancount-friendly account names
+   * use currency codes instead of currency symbols
+   * use cost notation instead of equity conversion postings
+   * avoid virtual postings
+
+   There is one big adjustment you must handle yourself: for Beancount,
+the top level account names must be 'Assets', 'Liabilities', 'Equity',
+'Income', and/or 'Expenses'.  You can use account aliases to rewrite
+your account names temporarily, if needed, as in this
+hledger2beancount.conf config file.
+
+   2024-12-20: Some more things not yet handled for you:
+
+   * P directives are not converted automatically - convert those
+     yourself
+   * Balance assignments are not converted (Beancount doesnt support
+     them) - replace those with explicit amounts
+
+* Menu:
+
+* Beancount account names::
+* Beancount commodity names::
+* Beancount virtual postings::
+* Beancount metadata::
+* Beancount costs::
+* Beancount operating currency::
+
+
+File: hledger.info,  Node: Beancount account names,  Next: Beancount commodity names,  Up: Beancount output
+
+5.2.5.1 Beancount account names
+...............................
+
+Aside from the top-level names, hledger will adjust your account names
+to make valid Beancount account names, by capitalising each part,
+replacing spaces with '-', replacing other unsupported characters with
+'C<HEXBYTES>', prepending 'A' to account name parts which don't begin
+with a letter or digit, and appending ':A' to account names which have
+only one part.
+
+
+File: hledger.info,  Node: Beancount commodity names,  Next: Beancount virtual postings,  Prev: Beancount account names,  Up: Beancount output
+
+5.2.5.2 Beancount commodity names
+.................................
+
+hledger will adjust your commodity names to make valid Beancount
+commodity/currency names, which must be 2-24 uppercase letters, digits,
+or ''', '.', '_', '-', beginning with a letter and ending with a letter
+or digit.  hledger will convert known currency symbols to ISO 4217
+currency codes, capitalise letters, replace spaces with '-', replace
+other unsupported characters with 'C<HEXBYTES>', and prepend or append
+'C' if needed.
+
+
+File: hledger.info,  Node: Beancount virtual postings,  Next: Beancount metadata,  Prev: Beancount commodity names,  Up: Beancount output
+
+5.2.5.3 Beancount virtual postings
+..................................
+
+Beancount doesn't allow virtual postings; if you have any, they will be
+omitted from beancount output.
+
+
+File: hledger.info,  Node: Beancount metadata,  Next: Beancount costs,  Prev: Beancount virtual postings,  Up: Beancount output
+
+5.2.5.4 Beancount metadata
+..........................
+
+hledger tags will be converted to Beancount metadata (except for tags
+whose name begins with '_').  Metadata names will be adjusted to be
+Beancount-compatible: beginning with a lowercase letter, at least two
+characters long, and with unsupported characters encoded.  Metadata
+values will use Beancount's string type.
+
+   In hledger, objects can have the same tag repeated with multiple
+values.  Eg an 'assets:cash' account might have both 'type:Asset' and
+'type:Cash' tags.  For Beancount these will be combined into one, with
+the values combined, comma separated.  Eg: 'type: "Asset, Cash"'.
+
+
+File: hledger.info,  Node: Beancount costs,  Next: Beancount operating currency,  Prev: Beancount metadata,  Up: Beancount output
+
+5.2.5.5 Beancount costs
+.......................
+
+Beancount doesn't allow redundant costs and conversion postings as
+hledger does.  If you have any of these, the conversion postings will be
+omitted.  Currently we support at most one cost + conversion postings
+group per transaction.
+
+
+File: hledger.info,  Node: Beancount operating currency,  Prev: Beancount costs,  Up: Beancount output
+
+5.2.5.6 Beancount operating currency
+....................................
+
+Declaring an operating currency (or several) improves Beancount and Fava
+reports.  Currently hledger will declare each currency used in cost
+amounts as an operating currency.  If needed, replace these with your
+own declaration, like
+
+option "operating_currency" "USD"
+
+
+File: hledger.info,  Node: SQL output,  Next: JSON output,  Prev: Beancount output,  Up: Output format
+
+5.2.6 SQL output
+----------------
+
+SQL output is expected to work at least with SQLite, MySQL and Postgres.
+
+   The SQL statements are expected to be executed in the empty database.
+If you already have tables created via SQL output of hledger, you would
+probably want to either clear data from these (via 'delete' or
+'truncate' SQL statements) or 'drop' the tables completely before
+import; otherwise your postings would be duplicated.
+
+   For SQLite, it is more useful if you modify the generated 'id' field
+to be a PRIMARY KEY. Eg:
+
+$ hledger print -O sql | sed 's/id serial/id INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL/g' | ...
+
+   This is not yet much used; feedback is welcome.
+
+
+File: hledger.info,  Node: JSON output,  Prev: SQL output,  Up: Output format
+
+5.2.7 JSON output
+-----------------
+
+Our JSON is rather large and verbose, since it is a faithful
+representation of hledger's internal data types.  To understand its
+structure, read the Haskell type definitions, which are mostly in
+https://github.com/simonmichael/hledger/blob/master/hledger-lib/Hledger/Data/Types.hs.
+hledger-web's OpenAPI specification may also be relevant.
+
+   hledger stores numbers with sometimes up to 255 significant digits.
+This is too many digits for most JSON consumers, so in JSON output we
+round numbers to at most 10 decimal places.  (We don't limit the number
+of integer digits.)  If you find this causing problems, please let us
+know.  Related: #1195
+
+   This is not yet much used; feedback is welcome.
+
+
+File: hledger.info,  Node: Commodity styles,  Next: Debug output,  Prev: Output format,  Up: Output
+
+5.3 Commodity styles
+====================
+
+When displaying amounts, hledger infers a standard display style for
+each commodity/currency, as described below in Commodity display style.
+
+   If needed, this can be overridden by a '-c/--commodity-style' option
+(except for cost amounts and amounts displayed by the 'print' command,
+which are always displayed with all decimal digits).  For example, the
+following will force dollar amounts to be displayed as shown:
+
+$ hledger print -c '$1.000,0'
+
+   This option can be repeated to set the display style for multiple
+commodities/currencies.  Its argument is as described in the commodity
+directive.
+
+   In some cases hledger will adjust number formatting to improve their
+parseability (such as adding trailing decimal marks when needed).
+
+
+File: hledger.info,  Node: Debug output,  Prev: Commodity styles,  Up: Output
+
+5.4 Debug output
+================
+
+We intend hledger to be relatively easy to troubleshoot, introspect and
+develop.  You can add '--debug[=N]' to any hledger command line to see
+additional debug output.  N ranges from 1 (least output, the default) to
+9 (maximum output).  Typically you would start with 1 and increase until
+you are seeing enough.  Debug output goes to stderr, and is not affected
+by '-o/--output-file' (unless you redirect stderr to stdout, eg:
+'2>&1').  It will be interleaved with normal output, which can help
+reveal when parts of the code are evaluated.  To capture debug output in
+a log file instead, you can usually redirect stderr, eg:
+
+hledger bal --debug=3 2>hledger.log
+
+   (This option doesn't work in a config file yet.)
+
+
+File: hledger.info,  Node: Environment,  Next: PART 2 DATA FORMATS,  Prev: Output,  Up: Top
+
+6 Environment
+*************
+
+These environment variables affect hledger:
+
+   *HLEDGER_LESS* If 'less' is your pager, this variable specifies the
+'less' options hledger should use.  (Otherwise, 'LESS' + custom options
+are used.)
+
+   *LEDGER_FILE* The main journal file to use when not specified with
+'-f/--file'.  Default: '$HOME/.hledger.journal'.
+
+   *NO_COLOR* If this environment variable exists (with any value,
+including empty), hledger will not use ANSI color codes in terminal
+output, unless overridden by an explicit '--color=y' or '--colour=y'
+option.
+
+
+File: hledger.info,  Node: PART 2 DATA FORMATS,  Next: Journal,  Prev: Environment,  Up: Top
+
+7 PART 2: DATA FORMATS
+**********************
+
+
+File: hledger.info,  Node: Journal,  Next: CSV,  Prev: PART 2 DATA FORMATS,  Up: Top
+
+8 Journal
+*********
+
+hledger's usual data source is a plain text file containing journal
+entries in hledger 'journal' format.  If you're looking for a quick
+reference, jump ahead to the journal cheatsheet (or use the table of
+contents at https://hledger.org/hledger.html).
+
+   This file represents an accounting General Journal.  The '.journal'
+file extension is most often used, though not strictly required.  The
+journal file contains a number of transaction entries, each describing a
+transfer of money (or any commodity) between two or more named accounts,
+in a simple format readable by both hledger and humans.
+
+   hledger's journal format is compatible with most of Ledger's journal
+format, but not all of it.  The differences and interoperation tips are
+described at hledger and Ledger.  With some care, and by avoiding
+incompatible features, you can keep your hledger journal readable by
+Ledger and vice versa.  This can useful eg for comparing the behaviour
+of one app against the other.
+
+   You can use hledger without learning any more about this file; just
+use the add or web or import commands to create and update it.
+
+   Many users, though, edit the journal file with a text editor, and
+track changes with a version control system such as git.  Editor add-ons
+such as ledger-mode or hledger-mode for Emacs, vim-ledger for Vim, and
+hledger-vscode for Visual Studio Code, make this easier, adding colour,
+formatting, tab completion, and useful commands.  See Editor
+configuration at hledger.org for the full list.
+
+   A hledger journal file can contain three kinds of thing: comment
+lines, transactions, and/or directives (including periodic transaction
+rules and auto posting rules).  Understanding the journal file format
+will also give you a good understanding of hledger's data model.  Here's
+a quick cheatsheet/overview, followed by detailed descriptions of each
+part.
+
+* Menu:
+
+* Journal cheatsheet::
+* Comments::
+* Transactions::
+* Dates::
+* Status::
+* Code::
+* Description::
+* Transaction comments::
+* Postings::
+* Account names::
+* Amounts::
+* Balance assertions::
+* Posting comments::
+* Transaction balancing::
+* Tags::
+* Directives::
+* account directive::
+* alias directive::
+* commodity directive::
+* decimal-mark directive::
+* include directive::
+* P directive::
+* payee directive::
+* tag directive::
+* Periodic transactions::
+* Auto postings::
+* Other syntax::
+
+
+File: hledger.info,  Node: Journal cheatsheet,  Next: Comments,  Up: Journal
+
+8.1 Journal cheatsheet
+======================
+
+# Here is the main syntax of hledger's journal format
+# (omitting extra Ledger compatibility syntax).
+
+###############################################################################
+
+# 1. These are comment lines, for notes or temporarily disabling things.
+; They begin with # or ;
+
+comment
+Or, lines can be enclosed within "comment" / "end comment".
+This is a block of 
+commented lines.
+end comment
+
+# Some journal entries can have semicolon comments at end of line  ; like this
+# Some of them require 2 or more spaces before the semicolon.
+
+###############################################################################
+
+# 2. Directives customise processing or output in some way.
+# You don't need any directives to get started.
+# But they can add more error checking, or change how things are displayed.
+# They begin with a word, letter, or symbol. 
+# They are most often placed at the top, before transactions.
+
+account assets             ; Declare valid account names and display order.
+account assets:savings     ; A subaccount. This one represents a bank account.
+account assets:checking    ; Another. Note, 2+ spaces after the account name.
+account assets:receivable  ; Accounting type is inferred from english names,
+account passifs            ; or declared with a "type" tag, type:L
+account expenses           ; type:X
+                           ; A follow-on comment line, indented.
+account expenses:rent      ; Expense and revenue categories are also accounts.
+                           ; Subaccounts inherit their parent's type.
+
+commodity $0.00         ; Declare valid commodities and their display styles.
+commodity 1.000,00 EUR
+
+decimal-mark .          ; The decimal mark used in this file (if ambiguous).
+
+payee Whole Foods       ; Declare a valid payee name.
+
+tag trip                ; Declare a valid tag name.
+
+P 2024-03-01 AAPL $179  ; Declare a market price for AAPL in $ on this date.
+
+include other.journal   ; Include another journal file here.
+
+# Declare a recurring "periodic transaction", for budget/forecast reports
+~ monthly  set budget goals  ; <- Note, 2+ spaces before the description.
+    (expenses:rent)      $1000
+    (expenses:food)       $500
+
+# Declare an auto posting rule, to modify existing transactions in reports
+= revenues:consulting
+    liabilities:tax:2024:us          *0.25  ; Add a tax liability & expense
+    expenses:tax:2024:us            *-0.25  ; for 25% of the revenue.
+
+###############################################################################
+
+# 3. Transactions are what it's all about.
+# They are dated events, usually movements of money between 2 or more accounts.
+# They begin with a numeric date.
+# Here is their basic shape:
+#
+# DATE DESCRIPTION    ; The transaction's date and optional description.
+#   ACCOUNT1  AMOUNT  ; A posting of an amount to/from this account, indented.
+#   ACCOUNT2  AMOUNT  ; A second posting, balancing the first.
+#   ...               ; More if needed. Amounts must sum to zero.
+#                     ; Note, 2+ spaces between account names and amounts.
+
+2024-01-01 opening balances         ; At the start, declare pre-existing balances this way.
+    assets:savings          $10000  ; Account names can be anything. lower case is easy to type.
+    assets:checking          $1000  ; assets, liabilities, equity, revenues, expenses are common.
+    liabilities:credit card  $-500  ; liabilities, equity, revenues balances are usually negative.
+    equity:start                    ; One amount can be left blank. $-10500 is inferred here.
+                                    ; Some of these accounts we didn't declare above,
+                                    ; so -s/--strict would complain.
+
+2024-01-03 ! (12345) pay rent
+    ; Additional transaction comment lines, indented.
+    ; There can be a ! or * after the date meaning "pending" or "cleared".
+    ; There can be a parenthesised (code) after the date/status.
+                                    ; Amounts' sign shows direction of flow.
+    assets:checking          $-500  ; Minus means removed from this account (credit).
+    expenses:rent             $500  ; Plus means added to this account (debit).
+
+; Keeping transactions in date order is optional (but helps error checking).
+
+2024-01-02 Gringott's Bank | withdrawal  ; Description can be PAYEE | NOTE
+    assets:bank:gold       -10 gold
+    assets:pouch            10 gold
+
+2024-01-02 shopping
+    expenses:clothing        1 gold
+    expenses:wands           5 gold
+    assets:pouch            -6 gold
+
+2024-01-02 receive gift
+    revenues:gifts          -3 "Chocolate Frogs"  ; Complex commodity symbols
+    assets:pouch             3 "Chocolate Frogs"  ; must be in double quotes.
+
+2024-01-15 buy some shares, in two lots                 ; Cost can be noted.
+    assets:investments:2024-01-15     2.0 AAAA @ $1.50  ; @  means per-unit cost
+    assets:investments:2024-01-15-02  3.0 AAAA @@ $4    ; @@ means total cost
+                      ; ^ Per-lot subaccounts are sometimes useful.
+    assets:checking                 $-7
+
+2024-01-15 assert some account balances on this date
+    ; Balances can be asserted in any transaction, with =, for extra error checking.
+    ; Assertion txns like this one can be made with hledger close --assert --show-costs
+    ;
+    assets:savings                    $0                   = $10000
+    assets:checking                   $0                   =   $493
+    assets:bank:gold                   0 gold              =    -10 gold
+    assets:pouch                       0 gold              =      4 gold
+    assets:pouch                       0 "Chocolate Frogs" =      3 "Chocolate Frogs"
+    assets:investments:2024-01-15      0.0 AAAA            =      2.0 AAAA @  $1.50
+    assets:investments:2024-01-15-02   0.0 AAAA            =      3.0 AAAA @@ $4
+    liabilities:credit card           $0                   =  $-500
+
+2024-02-01 note some event, or a transaction not yet fully entered, on this date
+    ; Postings are not required.
+
+; Some other date formats are allowed (but, consistent YYYY-MM-DD is useful).
+2024.01.01
+2024/1/1
+
+
+File: hledger.info,  Node: Comments,  Next: Transactions,  Prev: Journal cheatsheet,  Up: Journal
+
+8.2 Comments
+============
+
+Lines in the journal will be ignored if they begin with a hash ('#') or
+a semicolon (';').  (See also Other syntax.)  hledger will also ignore
+regions beginning with a 'comment' line and ending with an 'end comment'
+line (or file end).  Here's a suggestion for choosing between them:
+
+   * '#' for top-level notes
+   * ';' for commenting out things temporarily
+   * 'comment' for quickly commenting large regions (remember it's
+     there, or you might get confused)
+
+   Eg:
+
+# a comment line
+; another commentline
+comment
+A multi-line comment block,
+continuing until "end comment" directive
+or the end of the current file.
+end comment
+
+   Some hledger entries can have same-line comments attached to them,
+from ; (semicolon) to end of line.  See Transaction comments, Posting
+comments, and Account comments below.
+
+
+File: hledger.info,  Node: Transactions,  Next: Dates,  Prev: Comments,  Up: Journal
+
+8.3 Transactions
+================
+
+Transactions are the main unit of information in a journal file.  They
+represent events, typically a movement of some quantity of commodities
+between two or more named accounts.
+
+   Each transaction is recorded as a journal entry, beginning with a
+simple date in column 0.  This can be followed by any of the following
+optional fields, separated by spaces:
+
+   * a status character (empty, '!', or '*')
+   * a code (any short number or text, enclosed in parentheses)
+   * a description (any remaining text until end of line or a semicolon)
+   * a comment (any remaining text following a semicolon until end of
+     line, and any following indented lines beginning with a semicolon)
+   * 0 or more indented _posting_ lines, describing what was transferred
+     and the accounts involved (indented comment lines are also allowed,
+     but not blank lines or non-indented lines).
+
+   Here's a simple journal file containing one transaction:
+
+2008/01/01 income
+  assets:bank:checking   $1
+  income:salary         $-1
+
+
+File: hledger.info,  Node: Dates,  Next: Status,  Prev: Transactions,  Up: Journal
+
+8.4 Dates
+=========
+
+* Menu:
+
+* Simple dates::
+* Posting dates::
+
+
+File: hledger.info,  Node: Simple dates,  Next: Posting dates,  Up: Dates
+
+8.4.1 Simple dates
+------------------
+
+Dates in the journal file use _simple dates_ format: 'YYYY-MM-DD' or
+'YYYY/MM/DD' or 'YYYY.MM.DD', with leading zeros optional.  The year may
+be omitted, in which case it will be inferred from the context: the
+current transaction, the default year set with a 'Y' directive, or the
+current date when the command is run.  Some examples: '2010-01-31',
+'2010/01/31', '2010.1.31', '1/31'.
+
+   (The UI also accepts simple dates, as well as the more flexible smart
+dates documented in the hledger manual.)
+
+
+File: hledger.info,  Node: Posting dates,  Prev: Simple dates,  Up: Dates
+
+8.4.2 Posting dates
+-------------------
+
+You can give individual postings a different date from their parent
+transaction, by adding a posting comment containing a tag (see below)
+like 'date:DATE'.  This is probably the best way to control posting
+dates precisely.  Eg in this example the expense should appear in May
+reports, and the deduction from checking should be reported on 6/1 for
+easy bank reconciliation:
+
+2015/5/30
+    expenses:food     $10  ; food purchased on saturday 5/30
+    assets:checking        ; bank cleared it on monday, date:6/1
+
+$ hledger -f t.j register food
+2015-05-30                      expenses:food                  $10           $10
+
+$ hledger -f t.j register checking
+2015-06-01                      assets:checking               $-10          $-10
+
+   DATE should be a simple date; if the year is not specified it will
+use the year of the transaction's date.
+The 'date:' tag must have a valid simple date value if it is present, eg
+a 'date:' tag with no value is not allowed.
+
+
+File: hledger.info,  Node: Status,  Next: Code,  Prev: Dates,  Up: Journal
+
+8.5 Status
+==========
+
+Transactions (or individual postings within a transaction) can have a
+status mark, which is a single character before the transaction
+description (or posting account name), separated from it by a space,
+indicating one of three statuses:
+
+mark  status
+ 
+-----------------
+      unmarked
+'!'   pending
+'*'   cleared
+
+   When reporting, you can filter by status with the '-U/--unmarked',
+'-P/--pending', and '-C/--cleared' flags (and you can combine these, eg
+'-UP' to match all except cleared things).  Or you can use the
+'status:', 'status:!', and 'status:*' queries, or the U, P, C keys in
+hledger-ui.
+
+   (Note: in Ledger the "unmarked" state is called "uncleared"; in
+hledger we renamed it to "unmarked" for semantic clarity.)
+
+   Status marks are optional, but can be helpful eg for reconciling with
+real-world accounts.  Some editor modes provide highlighting and
+shortcuts for working with status.  Eg in Emacs ledger-mode, you can
+toggle transaction status with C-c C-e, or posting status with C-c C-c.
+
+   What "uncleared", "pending", and "cleared" actually mean is up to
+you.  Here's one suggestion:
+
+status     meaning
+--------------------------------------------------------------------------
+uncleared  recorded but not yet reconciled; needs review
+pending    tentatively reconciled (if needed, eg during a big
+           reconciliation)
+cleared    complete, reconciled as far as possible, and considered
+           correct
+
+   With this scheme, you would use '-PC' to see the current balance at
+your bank, '-U' to see things which will probably hit your bank soon
+(like uncashed checks), and no flags to see the most up-to-date state of
+your finances.
+
+
+File: hledger.info,  Node: Code,  Next: Description,  Prev: Status,  Up: Journal
+
+8.6 Code
+========
+
+After the status mark, but before the description, you can optionally
+write a transaction "code", enclosed in parentheses.  This is a good
+place to record a check number, or some other important transaction id
+or reference number.
+
+
+File: hledger.info,  Node: Description,  Next: Transaction comments,  Prev: Code,  Up: Journal
+
+8.7 Description
+===============
+
+After the date, status mark and/or code fields, the rest of the line (or
+until a comment is begun with ';') is the transaction's description.
+Here you can describe the transaction (called the "narration" in
+traditional bookkeeping), or you can record a payee/payer name, or you
+can leave it empty.
+
+   Transaction descriptions show up in print output and in register
+reports, and can be listed with the descriptions command.
+
+   You can query by description with 'desc:DESCREGEX', or pivot on
+description with '--pivot desc'.
+
+* Menu:
+
+* Payee and note::
+
+
+File: hledger.info,  Node: Payee and note,  Up: Description
+
+8.7.1 Payee and note
+--------------------
+
+Sometimes people want a dedicated payee/payer field that can be queried
+and checked more strictly.  If you want that, you can write a '|' (pipe)
+character in the description.  This divides it into a "payee" field on
+the left, and a "note" field on the right.  (Either can be empty.)
+
+   You can query these with 'payee:PAYEEREGEX' and 'note:NOTEREGEX',
+list their values with the payees and notes commands, or pivot on
+'payee' or 'note'.
+
+   Note: in transactions with no '|' character, description, payee, and
+note all have the same value.  Once a '|' is added, they become
+distinct.  (If you'd like to change this behaviour, please propose it on
+the mail list.)
+
+   If you want more strict error checking, you can declare the valid
+payee names with payee directives, and then enforce these with hledger
+check payees.  (Note: because of the above, for this you'll need to
+ensure every transaction description contains a '|' and therefore a
+checkable payee name, even if it's empty.)
+
+
+File: hledger.info,  Node: Transaction comments,  Next: Postings,  Prev: Description,  Up: Journal
+
+8.8 Transaction comments
+========================
+
+Text following ';', after a transaction description, and/or on indented
+lines immediately below it, form comments for that transaction.  They
+are reproduced by 'print' but otherwise ignored, except they may contain
+tags, which are not ignored.
+
+2012-01-01 something  ; a transaction comment
+    ; a second line of transaction comment
+    expenses   1
+    assets
+
+
+File: hledger.info,  Node: Postings,  Next: Account names,  Prev: Transaction comments,  Up: Journal
+
+8.9 Postings
+============
+
+A posting is an addition of some amount to, or removal of some amount
+from, an account.  Each posting line begins with at least one space or
+tab (2 or 4 spaces is common), followed by:
+
+   * (optional) a status character (empty, '!', or '*'), followed by a
+     space
+   * (required) an account name (any text, optionally containing *single
+     spaces*, until end of line or a double space)
+   * (optional) *two or more spaces* (or tabs) followed by an amount.
+
+   If the amount is positive, it is being added to the account; if
+negative, it is being removed from the account.
+
+   The posting amounts in a transaction must sum up to zero, indicating
+that the inflows and outflows are equal.  We call this a balanced
+transaction.  (You can read more about the nitty-gritty details of "sum
+up to zero" in Transaction balancing below.)
+
+   As a convenience, you can optionally leave one amount blank; hledger
+will infer what it should be so as to balance the transaction.
+
+* Menu:
+
+* Debits and credits::
+* The two space delimiter::
+
+
+File: hledger.info,  Node: Debits and credits,  Next: The two space delimiter,  Up: Postings
+
+8.9.1 Debits and credits
+------------------------
+
+The traditional accounting concepts of debit and credit of course exist
+in hledger, but we represent them with numeric sign, as described above.
+Positive and negative posting amounts represent debits and credits
+respectively.
+
+   You don't need to remember that, but if you would like to - eg for
+helping newcomers or for talking with your accountant - here's a handy
+mnemonic:
+
+   _'debit / plus / left / short words'_
+_'credit / minus / right / longer words'_
+
+
+File: hledger.info,  Node: The two space delimiter,  Prev: Debits and credits,  Up: Postings
+
+8.9.2 The two space delimiter
+-----------------------------
+
+Be sure to notice the unusual separator between the account name and the
+following amount.  Because hledger allows account names with spaces in
+them, you must separate the account name and amount (if any) by *two or
+more spaces* (or tabs).  It's easy to forget at first.  If you ever see
+the amount being treated as part of the account name, you'll know you
+probably need to add another space between them.
+
+
+File: hledger.info,  Node: Account names,  Next: Amounts,  Prev: Postings,  Up: Journal
+
+8.10 Account names
+==================
+
+Accounts are the main way of categorising things in hledger.  As in
+Double Entry Bookkeeping, they can represent real world accounts (such
+as a bank account), or more abstract categories such as "money borrowed
+from Frank" or "money spent on electricity".
+
+   You can use any account names you like, but we usually start with the
+traditional accounting categories, which in english are 'assets',
+'liabilities', 'equity', 'revenues', 'expenses'.  (You might see these
+referred to as A, L, E, R, X for short.)
+
+   For more precise reporting, we usually divide the top level accounts
+into more detailed subaccounts, by writing a full colon between account
+name parts.  For example, from the account names 'assets:bank:checking'
+and 'expenses:food', hledger will infer this hierarchy of five accounts:
+
+assets
+assets:bank
+assets:bank:checking
+expenses
+expenses:food
+
+   Shown as an outline, the hierarchical tree structure is more clear:
+
+assets
+ bank
+  checking
+expenses
+ food
+
+   hledger reports can summarise the account tree to any depth, so you
+can go as deep as you like with subcategories, but keeping your account
+names relatively simple may be best when starting out.
+
+   Account names may be capitalised or not; they may contain letters,
+numbers, symbols, or single spaces.  Note, when an account name and an
+amount are written on the same line, they must be separated by *two or
+more spaces* (or tabs).
+
+   Parentheses or brackets enclosing the full account name indicate
+virtual postings, described below.  Parentheses or brackets internal to
+the account name have no special meaning.
+
+   Account names can be altered temporarily or permanently by account
+aliases.
+
+
+File: hledger.info,  Node: Amounts,  Next: Balance assertions,  Prev: Account names,  Up: Journal
+
+8.11 Amounts
+============
+
+After the account name, there is usually an amount.  (Remember: between
+account name and amount, there must be two or more spaces.)
+
+   hledger's amount format is flexible, supporting several international
+formats.  Here are some examples.  Amounts have a number (the
+"quantity"):
+
+1
+
+   ..and usually a currency symbol or commodity name (more on this
+below), to the left or right of the quantity, with or without a
+separating space:
+
+$1
+4000 AAPL
+3 "green apples"
+
+   Amounts can be preceded by a minus sign (or a plus sign, though plus
+is the default), The sign can be written before or after a left-side
+commodity symbol:
+
+-$1
+$-1
+
+   One or more spaces between the sign and the number are acceptable
+when parsing (but they won't be displayed in output):
+
++ $1
+$-      1
+
+   Scientific E notation is allowed:
+
+1E-6
+EUR 1E3
+
+* Menu:
+
+* Decimal marks::
+* Digit group marks::
+* Commodity::
+* Costs::
+
+
+File: hledger.info,  Node: Decimal marks,  Next: Digit group marks,  Up: Amounts
+
+8.11.1 Decimal marks
+--------------------
+
+A _decimal mark_ can be written as a period or a comma:
+
+1.23
+1,23
+
+   Both of these are common in international number formats, so hledger
+is not biased towards one or the other.  Because hledger also supports
+digit group marks (eg thousands separators), this means that a number
+like '1,000' or '1.000' containing just one period or comma is
+ambiguous.  In such cases, hledger by default assumes it is a decimal
+mark, and will parse both of those as 1.
+
+   To help hledger parse such ambiguous numbers more accurately, if you
+use digit group marks, we recommend declaring the decimal mark
+explicitly.  The best way is to add a 'decimal-mark' directive at the
+top of each data file, like this:
+
+decimal-mark .
+
+   Or you can declare it per commodity with 'commodity' directives,
+described below.
+
+   hledger also accepts numbers like '10.' with no digits after the
+decimal mark (and will sometimes display numbers that way to
+disambiguate them - see Trailing decimal marks).
+
+
+File: hledger.info,  Node: Digit group marks,  Next: Commodity,  Prev: Decimal marks,  Up: Amounts
+
+8.11.2 Digit group marks
+------------------------
+
+In the integer part of the amount quantity (left of the decimal mark),
+groups of digits can optionally be separated by a _digit group mark_ - a
+comma or period (whichever is not used as decimal mark), or a space
+(several Unicode space variants, like no-break space, are also
+accepted).  So these are all valid amounts in a journal file:
+
+     $1,000,000.00
+  EUR 2.000.000,00
+INR 9,99,99,999.00
+      1 000 000.00   ; <- ordinary space  
+      1 000 000.00   ; <- no-break space
+
+
+File: hledger.info,  Node: Commodity,  Next: Costs,  Prev: Digit group marks,  Up: Amounts
+
+8.11.3 Commodity
+----------------
+
+Amounts in hledger have both a "quantity", which is a signed decimal
+number, and a "commodity", which is a currency symbol, stock ticker, or
+any word or phrase describing something you are tracking.
+
+   If the commodity name contains non-letters (spaces, numbers, or
+punctuation), you must always write it inside double quotes ('"green
+apples"', '"ABC123"').
+
+   If you write just a bare number, that too will have a commodity, with
+name '""'; we call that the "no-symbol commodity".
+
+   Actually, hledger combines these single-commodity amounts into more
+powerful multi-commodity amounts, which are what it works with most of
+the time.  A multi-commodity amount could be, eg: '1 USD, 2 EUR, 3.456
+TSLA'.  In practice, you will only see multi-commodity amounts in
+hledger's output; you can't write them directly in the journal file.
+
+   By default, the format of amounts in the journal influences how
+hledger displays them in output.  This is explained in Commodity display
+style below.
+
+
+File: hledger.info,  Node: Costs,  Prev: Commodity,  Up: Amounts
+
+8.11.4 Costs
+------------
+
+After a posting amount, you can note its cost (when buying) or selling
+price (when selling) in another commodity, by writing either '@
+UNITPRICE' or '@@ TOTALPRICE' after it.  This indicates a conversion
+transaction, where one commodity is exchanged for another.
+
+   (You might also see this called "transaction price" in hledger docs,
+discussions, or code; that term was directionally neutral and reminded
+that it is a price specific to a transaction, but we now just call it
+"cost", with the understanding that the transaction could be a purchase
+or a sale.)
+
+   Costs are usually written explicitly with '@' or '@@', but can also
+be inferred automatically for simple multi-commodity transactions.
+Note, if costs are inferred, the order of postings is significant; the
+first posting will have a cost attached, in the commodity of the second.
+
+   As an example, here are several ways to record purchases of a foreign
+currency in hledger, using the cost notation either explicitly or
+implicitly:
+
+  1. Write the price per unit, as '@ UNITPRICE' after the amount:
+
+     2009/1/1
+       assets:euros     €100 @ $1.35  ; one hundred euros purchased at $1.35 each
+       assets:dollars                 ; balancing amount is -$135.00
+
+  2. Write the total price, as '@@ TOTALPRICE' after the amount:
+
+     2009/1/1
+       assets:euros     €100 @@ $135  ; one hundred euros purchased at $135 for the lot
+       assets:dollars
+
+  3. Specify amounts for all postings, using exactly two commodities,
+     and let hledger infer the price that balances the transaction.
+     Note the effect of posting order: the price is added to first
+     posting, making it '€100 @@ $135', as in example 2:
+
+     2009/1/1
+       assets:euros     €100          ; one hundred euros purchased
+       assets:dollars  $-135          ; for $135
+
+   Amounts can be converted to cost at report time using the '-B/--cost'
+flag; this is discussed more in the Cost reporting section.
+
+   Note that the cost normally should be a positive amount, though it's
+not required to be.  This can be a little confusing, see discussion at
+-infer-market-prices: market prices from transactions.
+
+
+File: hledger.info,  Node: Balance assertions,  Next: Posting comments,  Prev: Amounts,  Up: Journal
+
+8.12 Balance assertions
+=======================
+
+hledger supports Ledger-style balance assertions in journal files.
+These look like, for example, '= EXPECTEDBALANCE' following a posting's
+amount.  Eg here we assert the expected dollar balance in accounts a and
+b after each posting:
+
+2013/1/1
+  a   $1 =  $1
+  b      = $-1
+
+2013/1/2
+  a   $1 =  $2
+  b  $-1 = $-2
+
+   After reading a journal file, hledger will check all balance
+assertions and report an error if any of them fail.  Balance assertions
+can protect you from, eg, inadvertently disrupting reconciled balances
+while cleaning up old entries.  You can disable them temporarily with
+the '-I/--ignore-assertions' flag, which can be useful for
+troubleshooting or for reading Ledger files.  (Note: this flag currently
+does not disable balance assignments, described below).
+
+* Menu:
+
+* Assertions and ordering::
+* Assertions and multiple included files::
+* Assertions and multiple -f files::
+* Assertions and costs::
+* Assertions and commodities::
+* Assertions and subaccounts::
+* Assertions and status::
+* Assertions and virtual postings::
+* Assertions and auto postings::
+* Assertions and precision::
+
+
+File: hledger.info,  Node: Assertions and ordering,  Next: Assertions and multiple included files,  Up: Balance assertions
+
+8.12.1 Assertions and ordering
+------------------------------
+
+hledger calculates and checks an account's balance assertions in date
+order (and when there are multiple assertions on the same day, in parse
+order).  Note this is different from Ledger, which checks assertions
+always in parse order, ignoring dates.
+
+   This means in hledger you can freely reorder transactions, postings,
+or files, and balance assertions will usually keep working.  The
+exception is when you reorder multiple postings on the same day, to the
+same account, which have balance assertions; those will likely need
+updating.
+
+
+File: hledger.info,  Node: Assertions and multiple included files,  Next: Assertions and multiple -f files,  Prev: Assertions and ordering,  Up: Balance assertions
+
+8.12.2 Assertions and multiple included files
+---------------------------------------------
+
+Multiple files included with the 'include' directive are processed as if
+concatenated into one file, preserving their order and the posting order
+within each file.  It means that balance assertions in later files will
+see balance from earlier files.
+
+   And if you have multiple postings to an account on the same day,
+split across multiple files, and you want to assert the account's
+balance on that day, you'll need to put the assertion in the right file
+- the last one in the sequence, probably.
+
+
+File: hledger.info,  Node: Assertions and multiple -f files,  Next: Assertions and costs,  Prev: Assertions and multiple included files,  Up: Balance assertions
+
+8.12.3 Assertions and multiple -f files
+---------------------------------------
+
+Unlike 'include', when multiple files are specified on the command line
+with multiple '-f/--file' options, balance assertions will not see
+balance from earlier files.  This can be useful when you do not want
+problems in earlier files to disrupt valid assertions in later files.
+
+   If you do want assertions to see balance from earlier files, use
+'include', or concatenate the files temporarily.
+
+
+File: hledger.info,  Node: Assertions and costs,  Next: Assertions and commodities,  Prev: Assertions and multiple -f files,  Up: Balance assertions
+
+8.12.4 Assertions and costs
+---------------------------
+
+Balance assertions ignore costs, and should normally be written without
+one:
+
+2019/1/1
+  (a)     $1 @ €1 = $1
+
+   We do allow costs to be written in balance assertion amounts,
+however, and print shows them, but they don't affect whether the
+assertion passes or fails.  This is for backward compatibility
+(hledger's close command used to generate balance assertions with
+costs), and because balance _assignments_ do use costs (see below).
+
+
+File: hledger.info,  Node: Assertions and commodities,  Next: Assertions and subaccounts,  Prev: Assertions and costs,  Up: Balance assertions
+
+8.12.5 Assertions and commodities
+---------------------------------
+
+The balance assertions described so far are "*single commodity balance
+assertions*": they assert and check the balance in one commodity,
+ignoring any others that may be present.  This is how balance assertions
+work in Ledger also.
+
+   If an account contains multiple commodities, you can assert their
+balances by writing multiple postings with balance assertions, one for
+each commodity:
+
+2013/1/1
+  usd   $-1
+  eur   €-1
+  both
+
+2013/1/2
+  both    0 = $1
+  both    0 = €1
+
+   In hledger you can make a stronger "*sole commodity balance
+assertion*" by writing two equals signs ('== EXPECTEDBALANCE').  This
+also asserts that there are no other commodities in the account besides
+the asserted one (or at least, that their current balance is zero):
+
+2013/1/1
+  usd   $-1  == $-1  ; these sole commodity assertions succeed
+  eur   €-1  == €-1
+  both      ;==  $1  ; this one would fail because 'both' contains $ and €
+
+   It's less easy to make a "*sole commodities balance assertion*" (note
+the plural) - ie, asserting that an account contains two or more
+specified commodities and no others.  It can be done by
+
+  1. isolating each commodity in a subaccount, and asserting those
+  2. and also asserting there are no commodities in the parent account
+     itself:
+
+2013/1/1
+  usd       $-1
+  eur       €-1
+  both        0 == 0   ; nothing up my sleeve
+  both:usd   $1 == $1  ; a dollar here
+  both:eur   €1 == €1  ; a euro there
+
+
+File: hledger.info,  Node: Assertions and subaccounts,  Next: Assertions and status,  Prev: Assertions and commodities,  Up: Balance assertions
+
+8.12.6 Assertions and subaccounts
+---------------------------------
+
+All of the balance assertions above (both '=' and '==') are
+"*subaccount-exclusive balance assertions*"; they ignore any balances
+that exist in deeper subaccounts.
+
+   In hledger you can make "*subaccount-inclusive balance assertions*"
+by adding a star after the equals ('=*' or '==*'):
+
+2019/1/1
+  equity:start
+  assets:checking  $10
+  assets:savings   $10
+  assets            $0 ==* $20  ; assets + subaccounts contains $20 and nothing else
+
+
+File: hledger.info,  Node: Assertions and status,  Next: Assertions and virtual postings,  Prev: Assertions and subaccounts,  Up: Balance assertions
+
+8.12.7 Assertions and status
+----------------------------
+
+Balance assertions always consider postings of all statuses (unmarked,
+pending, or cleared); they are not affected by the '-U'/'--unmarked' /
+'-P'/'--pending' / '-C'/'--cleared' flags or the 'status:' query.
+
+
+File: hledger.info,  Node: Assertions and virtual postings,  Next: Assertions and auto postings,  Prev: Assertions and status,  Up: Balance assertions
+
+8.12.8 Assertions and virtual postings
+--------------------------------------
+
+Balance assertions always consider both real and virtual postings; they
+are not affected by the '--real/-R' flag or 'real:' query.
+
+
+File: hledger.info,  Node: Assertions and auto postings,  Next: Assertions and precision,  Prev: Assertions and virtual postings,  Up: Balance assertions
+
+8.12.9 Assertions and auto postings
+-----------------------------------
+
+Balance assertions _are_ affected by the '--auto' flag, which generates
+auto postings, which can alter account balances.  Because auto postings
+are optional in hledger, accounts affected by them effectively have two
+balances.  But balance assertions can only test one or the other of
+these.  So to avoid making fragile assertions, either:
+
+   * assert the balance calculated with '--auto', and always use
+     '--auto' with that file
+   * or assert the balance calculated without '--auto', and never use
+     '--auto' with that file
+   * or avoid balance assertions on accounts affected by auto postings
+     (or avoid auto postings entirely).
+
+
+File: hledger.info,  Node: Assertions and precision,  Prev: Assertions and auto postings,  Up: Balance assertions
+
+8.12.10 Assertions and precision
+--------------------------------
+
+Balance assertions compare the exactly calculated amounts, which are not
+always what is shown by reports.  Eg a commodity directive may limit the
+display precision, but this will not affect balance assertions.  Balance
+assertion failure messages show exact amounts.
+
+
+File: hledger.info,  Node: Posting comments,  Next: Transaction balancing,  Prev: Balance assertions,  Up: Journal
+
+8.13 Posting comments
+=====================
+
+Text following ';', at the end of a posting line, and/or on indented
+lines immediately below it, form comments for that posting.  They are
+reproduced by 'print' but otherwise ignored, except they may contain
+tags, which are not ignored.
+
+2012-01-01
+    expenses   1  ; a comment for posting 1
+    assets
+    ; a comment for posting 2
+    ; a second comment line for posting 2
+
+
+File: hledger.info,  Node: Transaction balancing,  Next: Tags,  Prev: Posting comments,  Up: Journal
+
+8.14 Transaction balancing
+==========================
+
+How exactly does hledger decide when a transaction is balanced ?  The
+general goal is that if you look at the journal entry and calculate the
+amounts' sum perfectly with pencil and paper, hledger should agree with
+you.
+
+   Real world transactions, especially for investments or
+cryptocurrencies, often involve imprecise costs, complex decimals,
+and/or infinitely-recurring decimals, which are difficult or
+inconvenient to handle on a computer.  So to be a practical accounting
+system, hledger allows some imprecision when checking transaction
+balancedness.  The question is, how much imprecision should be allowed ?
+
+   hledger currently decides it based on the commodity display styles:
+if the postings' sum would appear to be zero when displayed with the
+standard display precisions, the transaction is considered balanced.
+
+   Or equivalently: if the journal entry is displayed with amounts
+rounded to the standard display precisions (with 'hledger print
+--round=hard'), and a human with pencil and paper would agree that those
+displayed amounts add up to zero, the transaction is considered
+balanced.
+
+   This has some advantages: it is fairly intuitive, general not
+hard-coded, yet configurable when needed.  On the downside it means that
+transaction balancedness is related to commodity display precisions, so
+eg when using '-c/--commodity-style' to display things with more than
+usual precision, you might need to fix some of your journal entries (ie,
+add decimal digits to make them balance more precisely).
+
+   Other PTA tools (Ledger, Beancount..)  have their own ways of doing
+it.  Possible improvements are discussed at #1964.
+
+   Note: if you have multiple journal files, and are relying on
+commodity directives to make imprecise journal entries balance, the
+directives' placement might be important - see 'commodity' directive.
+
+
+File: hledger.info,  Node: Tags,  Next: Directives,  Prev: Transaction balancing,  Up: Journal
+
+8.15 Tags
+=========
+
+Tags are a way to add extra labels or data fields to transactions,
+postings, or accounts.  They are usually a word or hyphenated word,
+immediately followed by a full colon, written within the comment of a
+transaction, a posting, or an 'account' directive.  (Yes, storing data
+in comments is slightly weird!)
+
+   You can write each tag on its own comment line, or multiple tags on
+one line, separated by commas.  Tags can also have a value, which is any
+text after the colon until the next comma or end of line, excluding
+surrounding whitespace.  (hledger tag values can't contain commas.)  If
+the same tag name appears multiple times in a comment, each name:value
+pair is preserved.
+
+   An example: in this journal there are six tags, one of them with a
+value:
+
+account assets:checking         ; accounttag:
+account expenses:food
+
+2017/1/16 bought groceries      ; transactiontag:
+    ; transactiontag2:
+    assets:checking        $-1
+     ; posting-tag-1:, (belongs to the posting above)
+    expenses:food           $1  ; posting-tag-2:, posting-tag-3: with a value
+
+* Menu:
+
+* Querying with tags::
+* Displaying tags::
+* When to use tags ?::
+* Tag names::
+* Special tags::
+
+
+File: hledger.info,  Node: Querying with tags,  Next: Displaying tags,  Up: Tags
+
+8.15.1 Querying with tags
+-------------------------
+
+Tags are most often used to select a subset of data; you can match
+tagged things by tag name and or tag value with a 'tag:' query.  (See
+queries below.)
+
+   When querying for tag names or values, note that postings inherit
+tags from their transaction and from their account, and transactions
+acquire tags from their postings.  So in the example above, - the
+assets:checking posting effectively has four tags (one of its own, one
+from the account, two from the transaction) - the expenses:food posting
+effectively has four tags (two of its own, two from the transaction) -
+the transaction effectively has all six tags (two of its own, and two
+from each posting)
+
+
+File: hledger.info,  Node: Displaying tags,  Next: When to use tags ?,  Prev: Querying with tags,  Up: Tags
+
+8.15.2 Displaying tags
+----------------------
+
+You can use the 'tags' command to list tag names or values.
+
+   The 'print' command also shows tags.
+
+   You can use -pivot to display tag values in other reports, in various
+ways (eg appended to account names, like pseudo subaccounts).
+
+
+File: hledger.info,  Node: When to use tags ?,  Next: Tag names,  Prev: Displaying tags,  Up: Tags
+
+8.15.3 When to use tags ?
+-------------------------
+
+Tags provide more dimensions of categorisation, complementing accounts
+and transaction descriptions.  When to use each of these is somewhat a
+matter of taste.  Accounts have the most built-in support, and regex
+queries on descriptions are also quite powerful.  So you may not need
+tags at all.  But if you want to track multiple cross-cutting
+categories, they can be a good fit.  For example, you could tag
+trip-related transactions with 'trip: YEAR:PLACE', without disturbing
+your usual account categories.
+
+
+File: hledger.info,  Node: Tag names,  Next: Special tags,  Prev: When to use tags ?,  Up: Tags
+
+8.15.4 Tag names
+----------------
+
+What is allowed in a tag name ?  Currently, most non-whitespace
+characters.  Eg '😀:' is a valid tag.
+
+   For extra error checking, you can declare valid tag names with the
+'tag' directive, and then enforce these with the 'check' command.
+
+   But note that tags are detected quite loosely at present, sometimes
+where you didn't intend them.  Eg '; see https://foo.com' contains a
+'https' tag with value '//foo.com'.
+
+
+File: hledger.info,  Node: Special tags,  Prev: Tag names,  Up: Tags
+
+8.15.5 Special tags
+-------------------
+
+Some tag names have special significance to hledger.  They are explained
+elsewhere, but here's a quick reference:
+
+ type                   -- declares an account's type
+ date                   -- overrides a posting's date
+ date2                  -- overrides a posting's secondary date
+ assert                 -- appears on txns generated by close --assert
+ retain                 -- appears on txns generated by close --retain
+ start                  -- appears on txns generated by close --migrate/--close/--open/--assign
+ t                      -- appears on postings generated from timedot letters
+
+ generated-transaction  -- appears on txns generated by a periodic rule
+ modified-transaction   -- appears on txns which have had auto postings added
+ generated-posting      -- appears on generated postings
+ cost-posting           -- appears on postings which have (or could have) a cost,
+                           and which have equivalent conversion postings in the transaction
+ conversion-posting     -- appears on postings which are to a V/Conversion account
+                           and which have an equivalent cost posting in the transaction
+
+   The second group above (generated-transaction, etc.)  are normally
+hidden, with a '_' prefix added.  This means 'print' doesn't show them
+by default; but you can still use them in queries.  You can add the
+'--verbose-tags' flag to make them visible, which can be useful for
+troubleshooting.
+
+
+File: hledger.info,  Node: Directives,  Next: account directive,  Prev: Tags,  Up: Journal
+
+8.16 Directives
+===============
+
+Besides transactions, there is something else you can put in a 'journal'
+file: directives.  These are declarations, beginning with a keyword,
+that modify hledger's behaviour.  Some directives can have more specific
+subdirectives, indented below them.  hledger's directives are similar to
+Ledger's in many cases, but there are also many differences.  Directives
+are not required, but can be useful.  Here are the main directives:
+
+purpose                                   directive
+--------------------------------------------------------------------------
+*READING DATA:*
+Rewrite account names                     'alias'
+Comment out sections of the file          'comment'
+Declare file's decimal mark, to help      'decimal-mark'
+parse amounts accurately
+Include other data files                  'include'
+*GENERATING DATA:*
+Generate recurring transactions or        '~'
+budget goals
+Generate extra postings on existing       '='
+transactions
+*CHECKING FOR ERRORS:*
+Define valid entities to provide more     'account', 'commodity',
+error checking                            'payee', 'tag'
+*REPORTING:*
+Declare accounts' type and display        'account'
+order
+Declare commodity display styles          'commodity'
+Declare market prices                     'P'
+
+* Menu:
+
+* Directives and multiple files::
+* Directive effects::
+
+
+File: hledger.info,  Node: Directives and multiple files,  Next: Directive effects,  Up: Directives
+
+8.16.1 Directives and multiple files
+------------------------------------
+
+Directives vary in their scope, ie which journal entries and which input
+files they affect.  Most often, a directive will affect the following
+entries and included files if any, until the end of the current file -
+and no further.  You might find this inconvenient!  For example, 'alias'
+directives do not affect parent or sibling files.  But there are usually
+workarounds; for example, put 'alias' directives in your top-most file,
+before including other files.
+
+   The restriction, though it may be annoying at first, is in a good
+cause; it allows reports to be stable and deterministic, independent of
+the order of input.  Without it, reports could show different numbers
+depending on the order of -f options, or the positions of include
+directives in your files.
+
+
+File: hledger.info,  Node: Directive effects,  Prev: Directives and multiple files,  Up: Directives
+
+8.16.2 Directive effects
+------------------------
+
+Here are all hledger's directives, with their effects and scope
+summarised - nine main directives, plus four others which we consider
+non-essential:
+
+directivewhat it does                                                   ends
+                                                                        at
+                                                                        file
+                                                                        end?
+---------------------------------------------------------------------------
+*'account'*Declares an account, for checking all entries in all files; andN
+     its display order and type.  Subdirectives: any text, ignored.
+*'alias'*Rewrites account names, in following entries until end of      Y
+     current file or 'end aliases'.  Command line equivalent:
+     '--alias'
+*'comment'*Ignores part of the journal file, until end of current file orY
+     'end comment'.
+*'commodity'*Declares up to four things: 1.  a commodity symbol, for checkingN,N,Y,Y
+     all amounts in all files 2.  the display style for all amounts
+     of this commodity 3.  the decimal mark for parsing amounts of
+     this commodity, in the rest of this file and its children, if
+     there is no 'decimal-mark' directive 4.  the precision to use
+     for balanced-transaction checking in this commodity, in this
+     file and its children.  Takes precedence over 'D'.
+     Subdirectives: 'format' (ignored).  Command line equivalent:
+     '-c/--commodity-style'
+*'decimal-mark'*Declares the decimal mark, for parsing amounts of all   Y
+     commodities in following entries until next 'decimal-mark' or
+     end of current file.  Included files can override.  Takes
+     precedence over 'commodity' and 'D'.
+*'include'*Includes entries and directives from another file, as if theyN
+     were written inline.  Command line alternative: multiple
+     '-f/--file'
+*'payee'*Declares a payee name, for checking all entries in all files.  N
+*'P'*Declares the market price of a commodity on some date, for value   N
+     reports.
+*'~'*Declares a periodic transaction rule that generates future         N
+(tilde)transactions with '--forecast' and budget goals with 'balance
+     --budget'.
+Other
+syntax:
+*'applyPrepends a common parent account to all account names, in        Y
+account'*following entries until end of current file or 'end apply
+     account'.
+*'D'*Sets a default commodity to use for no-symbol amounts;and, if      Y,Y,N,N
+     there is no 'commodity' directive for this commodity: its
+     decimal mark, balancing precision, and display style, as above.
+*'Y'*Sets a default year to use for any yearless dates, in following    Y
+     entries until end of current file.
+*'='*Declares an auto posting rule that generates extra postings on     partly
+(equals)matched transactions with '--auto', in current, parent, and
+     child files (but not sibling files, see #1212).
+*OtherOther directives from Ledger's file format are accepted but
+Ledgerignored.
+directives*
+
+
+File: hledger.info,  Node: account directive,  Next: alias directive,  Prev: Directives,  Up: Journal
+
+8.17 'account' directive
+========================
+
+'account' directives can be used to declare accounts (ie, the places
+that amounts are transferred from and to).  Though not required, these
+declarations can provide several benefits:
+
+   * They can document your intended chart of accounts, providing a
+     reference.
+   * They can store additional account information as comments, or as
+     tags which can be used to filter or pivot reports.
+   * They can restrict which accounts may be posted to by transactions,
+     eg in strict mode, which helps prevent errors.
+   * They influence account display order in reports, allowing
+     non-alphabetic sorting (eg Revenues to appear above Expenses).
+   * They can help hledger know your accounts' types (asset, liability,
+     equity, revenue, expense), enabling reports like balancesheet and
+     incomestatement.
+   * They help with account name completion (in hledger add,
+     hledger-web, hledger-iadd, ledger-mode, etc.)
+
+   They are written as the word 'account' followed by a hledger-style
+account name.  Eg:
+
+account assets:bank:checking
+
+   Ledger-style indented subdirectives are also accepted, but ignored:
+
+account assets:bank:checking
+  format subdirective  ; currently ignored
+
+* Menu:
+
+* Account comments::
+* Account error checking::
+* Account display order::
+* Account types::
+
+
+File: hledger.info,  Node: Account comments,  Next: Account error checking,  Up: account directive
+
+8.17.1 Account comments
+-----------------------
+
+Text following *two or more spaces* and ';' at the end of an account
+directive line, and/or following ';' on indented lines immediately below
+it, form comments for that account.  They are ignored except they may
+contain tags, which are not ignored.
+
+   The two-space requirement for same-line account comments is because
+';' is allowed in account names.
+
+account assets:bank:checking    ; same-line comment, at least 2 spaces before the semicolon
+  ; next-line comment
+  ; some tags - type:A, acctnum:12345
+
+
+File: hledger.info,  Node: Account error checking,  Next: Account display order,  Prev: Account comments,  Up: account directive
+
+8.17.2 Account error checking
+-----------------------------
+
+By default, accounts need not be declared; they come into existence when
+a posting references them.  This is convenient, but it means hledger
+can't warn you when you mis-spell an account name in the journal.
+Usually you'll find that error later, as an extra account in balance
+reports, or an incorrect balance when reconciling.
+
+   In strict mode, enabled with the '-s'/'--strict' flag, or when you
+run 'hledger check accounts', hledger will report an error if any
+transaction uses an account name that has not been declared by an
+account directive.  Some notes:
+
+   * The declaration is case-sensitive; transactions must use the
+     correct account name capitalisation.
+   * The account directive's scope is "whole file and below" (see
+     directives).  This means it affects all of the current file, and
+     any files it includes, but not parent or sibling files.  The
+     position of account directives within the file does not matter,
+     though it's usual to put them at the top.
+   * Accounts can only be declared in 'journal' files, but will affect
+     included files of all types.
+   * It's currently not possible to declare "all possible subaccounts"
+     with a wildcard; every account posted to must be declared.
+   * If you use the -infer-equity flag, you will also need declarations
+     for the account names it generates.
+
+
+File: hledger.info,  Node: Account display order,  Next: Account types,  Prev: Account error checking,  Up: account directive
+
+8.17.3 Account display order
+----------------------------
+
+Account directives also cause hledger to display accounts in a
+particular order, not just alphabetically.  Eg, here is a conventional
+ordering for the top-level accounts:
+
+account assets
+account liabilities
+account equity
+account revenues
+account expenses
+
+   Now hledger displays them in that order:
+
+$ hledger accounts
+assets
+liabilities
+equity
+revenues
+expenses
+
+   If there are undeclared accounts, those will be displayed last, in
+alphabetical order.
+
+   Sorting is done within each group of sibling accounts, at each level
+of the account tree.  Eg, a declaration like 'account parent:child'
+influences 'child''s position among its siblings.
+
+   Note, it does not affect 'parent''s position; for that, you need an
+'account parent' declaration.
+
+   Sibling accounts are always displayed together; hledger won't display
+'x:y' in between 'a:b' and 'a:c'.
+
+   An account directive both declares an account as a valid posting
+target, and declares its display order; you can't easily do one without
+the other.
+
+
+File: hledger.info,  Node: Account types,  Prev: Account display order,  Up: account directive
+
+8.17.4 Account types
+--------------------
+
+hledger knows that accounts come in several types: assets, liabilities,
+expenses and so on.  This enables easy reports like balancesheet and
+incomestatement, and filtering by account type with the 'type:' query.
+
+   As a convenience, hledger will detect these account types
+automatically if you are using common english-language top-level account
+names (described below).  But it's more robust to declare accounts'
+types explicitly, by adding 'type:' tags to their account directives.
+The tag's value should be one of the five main account types:
+
+   * 'A' or 'Asset' (things you own)
+   * 'L' or 'Liability' (things you owe)
+   * 'E' or 'Equity' (investment/ownership; balanced counterpart of
+     assets & liabilities)
+   * 'R' or 'Revenue' (what you received money from, AKA income;
+     technically part of Equity)
+   * 'X' or 'Expense' (what you spend money on; technically part of
+     Equity)
+
+   or, it can be (these are used less often):
+
+   * 'C' or 'Cash' (a subtype of Asset, indicating liquid assets for the
+     cashflow report)
+   * 'V' or 'Conversion' (a subtype of Equity, for conversions (see Cost
+     reporting).)
+
+   Subaccounts inherit their parent's type, or they can override it.
+Here is a typical set of account type declarations:
+
+account assets             ; type: A
+account liabilities        ; type: L
+account equity             ; type: E
+account revenues           ; type: R
+account expenses           ; type: X
+
+account assets:bank        ; type: C
+account assets:cash        ; type: C
+
+account equity:conversion  ; type: V
+
+   Here are some tips for working with account types.
+
+   * The rules for inferring types from account names are as follows.
+     These are just a convenience that sometimes help new users get
+     going; if they don't work for you, just ignore them and declare
+     your account types.  See also Regular expressions.
+
+     If account's name contains this (CI) regular expression:            | its type is:
+     --------------------------------------------------------------------|-------------
+     ^assets?(:.+)?:(cash|bank|che(ck|que?)(ing)?|savings?|current)(:|$) | Cash
+     ^assets?(:|$)                                                       | Asset
+     ^(debts?|liabilit(y|ies))(:|$)                                      | Liability
+     ^equity:(trad(e|ing)|conversion)s?(:|$)                             | Conversion
+     ^equity(:|$)                                                        | Equity
+     ^(income|revenue)s?(:|$)                                            | Revenue
+     ^expenses?(:|$)                                                     | Expense
+
+   * If you declare any account types, it's a good idea to declare an
+     account for all of the account types, because a mixture of declared
+     and name-inferred types can disrupt certain reports.
+
+   * Certain uses of account aliases can disrupt account types.  See
+     Rewriting accounts > Aliases and account types.
+
+   * As mentioned above, subaccounts will inherit a type from their
+     parent account.  More precisely, an account's type is decided by
+     the first of these that exists:
+
+       1. A 'type:' declaration for this account.
+       2. A 'type:' declaration in the parent accounts above it,
+          preferring the nearest.
+       3. An account type inferred from this account's name.
+       4. An account type inferred from a parent account's name,
+          preferring the nearest parent.
+       5. Otherwise, it will have no type.
+
+   * For troubleshooting, you can list accounts and their types with:
+
+     $ hledger accounts --types [ACCTPAT] [-DEPTH] [type:TYPECODES]
+
+
+File: hledger.info,  Node: alias directive,  Next: commodity directive,  Prev: account directive,  Up: Journal
+
+8.18 'alias' directive
+======================
+
+You can define account alias rules which rewrite your account names, or
+parts of them, before generating reports.  This can be useful for:
+
+   * expanding shorthand account names to their full form, allowing
+     easier data entry and a less verbose journal
+   * adapting old journals to your current chart of accounts
+   * experimenting with new account organisations, like a new hierarchy
+   * combining two accounts into one, eg to see their sum or difference
+     on one line
+   * customising reports
+
+   Account aliases also rewrite account names in account directives.
+They do not affect account names being entered via hledger add or
+hledger-web.
+
+   Account aliases are very powerful.  They are generally easy to use
+correctly, but you can also generate invalid account names with them;
+more on this below.
+
+   See also Rewrite account names.
+
+* Menu:
+
+* Basic aliases::
+* Regex aliases::
+* Combining aliases::
+* Aliases and multiple files::
+* end aliases directive::
+* Aliases can generate bad account names::
+* Aliases and account types::
+
+
+File: hledger.info,  Node: Basic aliases,  Next: Regex aliases,  Up: alias directive
+
+8.18.1 Basic aliases
+--------------------
+
+To set an account alias, use the 'alias' directive in your journal file.
+This affects all subsequent journal entries in the current file or its
+included files (but note: not sibling or parent files).  The spaces
+around the = are optional:
+
+alias OLD = NEW
+
+   Or, you can use the '--alias 'OLD=NEW'' option on the command line.
+This affects all entries.  It's useful for trying out aliases
+interactively.
+
+   OLD and NEW are case sensitive full account names.  hledger will
+replace any occurrence of the old account name with the new one.
+Subaccounts are also affected.  Eg:
+
+alias checking = assets:bank:wells fargo:checking
+; rewrites "checking" to "assets:bank:wells fargo:checking", or "checking:a" to "assets:bank:wells fargo:checking:a"
+
+
+File: hledger.info,  Node: Regex aliases,  Next: Combining aliases,  Prev: Basic aliases,  Up: alias directive
+
+8.18.2 Regex aliases
+--------------------
+
+There is also a more powerful variant that uses a regular expression,
+indicated by wrapping the pattern in forward slashes.  (This is the only
+place where hledger requires forward slashes around a regular
+expression.)
+
+   Eg:
+
+alias /REGEX/ = REPLACEMENT
+
+   or:
+
+$ hledger --alias '/REGEX/=REPLACEMENT' ...
+
+   Any part of an account name matched by REGEX will be replaced by
+REPLACEMENT. REGEX is case-insensitive as usual.
+
+   If you need to match a forward slash, escape it with a backslash, eg
+'/\/=:'.
+
+   If REGEX contains parenthesised match groups, these can be referenced
+by the usual backslash and number in REPLACEMENT:
+
+alias /^(.+):bank:([^:]+):(.*)/ = \1:\2 \3
+; rewrites "assets:bank:wells fargo:checking" to  "assets:wells fargo checking"
+
+   REPLACEMENT continues to the end of line (or on command line, to end
+of option argument), so it can contain trailing whitespace.
+
+
+File: hledger.info,  Node: Combining aliases,  Next: Aliases and multiple files,  Prev: Regex aliases,  Up: alias directive
+
+8.18.3 Combining aliases
+------------------------
+
+You can define as many aliases as you like, using journal directives
+and/or command line options.
+
+   Recursive aliases - where an account name is rewritten by one alias,
+then by another alias, and so on - are allowed.  Each alias sees the
+effect of previously applied aliases.
+
+   In such cases it can be important to understand which aliases will be
+applied and in which order.  For (each account name in) each journal
+entry, we apply:
+
+  1. 'alias' directives preceding the journal entry, most recently
+     parsed first (ie, reading upward from the journal entry, bottom to
+     top)
+  2. '--alias' options, in the order they appeared on the command line
+     (left to right).
+
+   In other words, for (an account name in) a given journal entry:
+
+   * the nearest alias declaration before/above the entry is applied
+     first
+   * the next alias before/above that will be be applied next, and so on
+   * aliases defined after/below the entry do not affect it.
+
+   This gives nearby aliases precedence over distant ones, and helps
+provide semantic stability - aliases will keep working the same way
+independent of which files are being read and in which order.
+
+   In case of trouble, adding '--debug=6' to the command line will show
+which aliases are being applied when.
+
+
+File: hledger.info,  Node: Aliases and multiple files,  Next: end aliases directive,  Prev: Combining aliases,  Up: alias directive
+
+8.18.4 Aliases and multiple files
+---------------------------------
+
+As explained at Directives and multiple files, 'alias' directives do not
+affect parent or sibling files.  Eg in this command,
+
+hledger -f a.aliases -f b.journal
+
+   account aliases defined in a.aliases will not affect b.journal.
+Including the aliases doesn't work either:
+
+include a.aliases
+
+2023-01-01  ; not affected by a.aliases
+  foo  1
+  bar
+
+   This means that account aliases should usually be declared at the
+start of your top-most file, like this:
+
+alias foo=Foo
+alias bar=Bar
+
+2023-01-01  ; affected by aliases above
+  foo  1
+  bar
+
+include c.journal  ; also affected
+
+
+File: hledger.info,  Node: end aliases directive,  Next: Aliases can generate bad account names,  Prev: Aliases and multiple files,  Up: alias directive
+
+8.18.5 'end aliases' directive
+------------------------------
+
+You can clear (forget) all currently defined aliases (seen in the
+journal so far, or defined on the command line) with this directive:
+
+end aliases
+
+
+File: hledger.info,  Node: Aliases can generate bad account names,  Next: Aliases and account types,  Prev: end aliases directive,  Up: alias directive
+
+8.18.6 Aliases can generate bad account names
+---------------------------------------------
+
+Be aware that account aliases can produce malformed account names, which
+could cause confusing reports or invalid 'print' output.  For example,
+you could erase all account names:
+
+2021-01-01
+  a:aa     1
+  b
+
+$ hledger print --alias '/.*/='
+2021-01-01
+                   1
+
+   The above 'print' output is not a valid journal.  Or you could insert
+an illegal double space, causing 'print' output that would give a
+different journal when reparsed:
+
+2021-01-01
+  old    1
+  other
+
+$ hledger print --alias old="new  USD" | hledger -f- print
+2021-01-01
+    new             USD 1
+    other
+
+
+File: hledger.info,  Node: Aliases and account types,  Prev: Aliases can generate bad account names,  Up: alias directive
+
+8.18.7 Aliases and account types
+--------------------------------
+
+If an account with a type declaration (see Declaring accounts > Account
+types) is renamed by an alias, normally the account type remains in
+effect.
+
+   However, renaming in a way that reshapes the account tree (eg
+renaming parent accounts but not their children, or vice versa) could
+prevent child accounts from inheriting the account type of their
+parents.
+
+   Secondly, if an account's type is being inferred from its name,
+renaming it by an alias could prevent or alter that.
+
+   If you are using account aliases and the 'type:' query is not
+matching accounts as you expect, try troubleshooting with the accounts
+command, eg something like:
+
+$ hledger accounts --types -1 --alias assets=bassetts
+
+
+File: hledger.info,  Node: commodity directive,  Next: decimal-mark directive,  Prev: alias directive,  Up: Journal
+
+8.19 'commodity' directive
+==========================
+
+The 'commodity' directive performs several functions:
+
+  1. It declares which commodity symbols may be used in the journal,
+     enabling useful error checking with strict mode or the check
+     command.  See Commodity error checking below.
+
+  2. It declares how all amounts in this commodity should be displayed,
+     eg how many decimals to show.  See Commodity display style above.
+
+  3. (If no 'decimal-mark' directive is in effect:) It sets the decimal
+     mark to expect (period or comma) when parsing amounts in this
+     commodity, in this file and files it includes, from the directive
+     until end of current file.  See Decimal marks above.
+
+  4. It declares the precision with which this commodity's amounts
+     should be compared when checking for balanced transactions,
+     anywhere in this file and files it includes, until end of current
+     file.
+
+   Declaring commodities solves several common parsing/display problems,
+so we recommend it.
+
+   Note that effects 3 and 4 above end at the end of the directive's
+file, and will not affect sibling or parent files.  So if you are
+relying on them (especially 4) and using multiple files, placing your
+commodity directives in a top-level parent file might be important.  Or,
+keep your decimal marks unambiguous and your entries well balanced and
+precise.
+
+   (Related: #793)
+
+* Menu:
+
+* Commodity directive syntax::
+* Commodity error checking::
+
+
+File: hledger.info,  Node: Commodity directive syntax,  Next: Commodity error checking,  Up: commodity directive
+
+8.19.1 Commodity directive syntax
+---------------------------------
+
+A commodity directive is normally the word 'commodity' followed by a
+sample amount (and optionally a comment).  Only the amount's symbol and
+the number's format is significant.  Eg:
+
+commodity $1000.00
+commodity 1.000,00 EUR
+commodity 1 000 000.0000   ; the no-symbol commodity
+
+   Commodities do not have tags (tags in the comment will be ignored).
+
+   A commodity directive's sample amount must always include a period or
+comma decimal mark (this rule helps disambiguate decimal marks and digit
+group marks).  If you don't want to show any decimal digits, write the
+decimal mark at the end:
+
+commodity 1000. AAAA       ; show AAAA with no decimals
+
+   Commodity symbols containing spaces, numbers, or punctuation must be
+enclosed in double quotes, as usual:
+
+commodity 1.0000 "AAAA 2023"
+
+   Commodity directives normally include a sample amount, but can
+declare only a symbol (ie, just function 1 above):
+
+commodity $
+commodity INR
+commodity "AAAA 2023"
+commodity ""               ; the no-symbol commodity
+
+   Commodity directives may also be written with an indented 'format'
+subdirective, as in Ledger.  The symbol is repeated and must be the same
+in both places.  Other subdirectives are currently ignored:
+
+; display indian rupees with currency name on the left,
+; thousands, lakhs and crores comma-separated,
+; period as decimal point, and two decimal places.
+commodity INR
+  format INR 1,00,00,000.00
+  an unsupported subdirective  ; ignored by hledger
+
+
+File: hledger.info,  Node: Commodity error checking,  Prev: Commodity directive syntax,  Up: commodity directive
+
+8.19.2 Commodity error checking
+-------------------------------
+
+In strict mode ('-s'/'--strict') (or when you run 'hledger check
+commodities'), hledger will report an error if an undeclared commodity
+symbol is used.  (With one exception: zero amounts are always allowed to
+have no commodity symbol.)  It works like account error checking
+(described above).
+
+
+File: hledger.info,  Node: decimal-mark directive,  Next: include directive,  Prev: commodity directive,  Up: Journal
+
+8.20 'decimal-mark' directive
+=============================
+
+You can use a 'decimal-mark' directive - usually one per file, at the
+top of the file - to declare which character represents a decimal mark
+when parsing amounts in this file.  It can look like
+
+decimal-mark .
+
+   or
+
+decimal-mark ,
+
+   This prevents any ambiguity when parsing numbers in the file, so we
+recommend it, especially if the file contains digit group marks (eg
+thousands separators).
+
+
+File: hledger.info,  Node: include directive,  Next: P directive,  Prev: decimal-mark directive,  Up: Journal
+
+8.21 'include' directive
+========================
+
+You can pull in the content of additional files by writing an include
+directive, like this:
+
+include FILEPATH
+
+   Only journal files can include, and only journal, timeclock or
+timedot files can be included (not CSV files, currently).
+
+   If the file path does not begin with a slash, it is relative to the
+current file's folder.
+
+   A tilde means home directory, eg: 'include ~/main.journal'.
+
+   The path may contain glob patterns to match multiple files, eg:
+'include *.journal'.
+
+   There is limited support for recursive wildcards: '**/' (the slash is
+required) matches 0 or more subdirectories.  It's not super convenient
+since you have to avoid include cycles and including directories, but
+this can be done, eg: 'include */**/*.journal'.
+
+   The path may also be prefixed to force a specific file format,
+overriding the file extension (as described in Data formats): 'include
+timedot:~/notes/2023*.md'.
+
+
+File: hledger.info,  Node: P directive,  Next: payee directive,  Prev: include directive,  Up: Journal
+
+8.22 'P' directive
+==================
+
+The 'P' directive declares a market price, which is a conversion rate
+between two commodities on a certain date.  This allows value reports to
+convert amounts of one commodity to their value in another, on or after
+that date.  These prices are often obtained from a stock exchange,
+cryptocurrency exchange, the or foreign exchange market.
+
+   The format is:
+
+P DATE COMMODITY1SYMBOL COMMODITY2AMOUNT
+
+   DATE is a simple date, COMMODITY1SYMBOL is the symbol of the
+commodity being priced, and COMMODITY2AMOUNT is the amount (symbol and
+quantity) of commodity 2 that one unit of commodity 1 is worth on this
+date.  Examples:
+
+# one euro was worth $1.35 from 2009-01-01 onward:
+P 2009-01-01 € $1.35
+
+# and $1.40 from 2010-01-01 onward:
+P 2010-01-01 € $1.40
+
+   The '-V', '-X' and '--value' flags use these market prices to show
+amount values in another commodity.  See Value reporting.
+
+
+File: hledger.info,  Node: payee directive,  Next: tag directive,  Prev: P directive,  Up: Journal
+
+8.23 'payee' directive
+======================
+
+'payee PAYEE NAME'
+
+   This directive can be used to declare a limited set of payees which
+may appear in transaction descriptions.  The "payees" check will report
+an error if any transaction refers to a payee that has not been
+declared.  Eg:
+
+payee Whole Foods    ; a comment
+
+   Payees do not have tags (tags in the comment will be ignored).
+
+   To declare the empty payee name, use '""'.
+
+payee ""
+
+   Ledger-style indented subdirectives, if any, are currently ignored.
+
+
+File: hledger.info,  Node: tag directive,  Next: Periodic transactions,  Prev: payee directive,  Up: Journal
+
+8.24 'tag' directive
+====================
+
+'tag TAGNAME'
+
+   This directive can be used to declare a limited set of tag names
+allowed in tags.  TAGNAME should be a valid tag name (no spaces).  Eg:
+
+tag  item-id
+
+   Any indented subdirectives are currently ignored.
+
+   The "tags" check will report an error if any undeclared tag name is
+used.  It is quite easy to accidentally create a tag through normal use
+of colons in comments; if you want to prevent this, you can declare and
+check your tags .
+
+
+File: hledger.info,  Node: Periodic transactions,  Next: Auto postings,  Prev: tag directive,  Up: Journal
+
+8.25 Periodic transactions
+==========================
+
+The '~' directive declares a "periodic rule" which generates temporary
+extra transactions, usually recurring at some interval, when hledger is
+run with the '--forecast' flag.  These "forecast transactions" are
+useful for forecasting future activity.  They exist only for the
+duration of the report, and only when '--forecast' is used; they are not
+saved in the journal file by hledger.
+
+   Periodic rules also have a second use: with the '--budget' flag they
+set budget goals for budgeting.
+
+   Periodic rules can be a little tricky, so before you use them, read
+this whole section, or at least the following tips:
+
+  1. Two spaces accidentally added or omitted will cause you trouble -
+     read about this below.
+  2. For troubleshooting, show the generated transactions with 'hledger
+     print --forecast tag:generated' or 'hledger register --forecast
+     tag:generated'.
+  3. Forecasted transactions will begin only after the last
+     non-forecasted transaction's date.
+  4. Forecasted transactions will end 6 months from today, by default.
+     See below for the exact start/end rules.
+  5. period expressions can be tricky.  Their documentation needs
+     improvement, but is worth studying.
+  6. Some period expressions with a repeating interval must begin on a
+     natural boundary of that interval.  Eg in 'weekly from DATE', DATE
+     must be a monday.  '~ weekly from 2019/10/1' (a tuesday) will give
+     an error.
+  7. Other period expressions with an interval are automatically
+     expanded to cover a whole number of that interval.  (This is done
+     to improve reports, but it also affects periodic transactions.
+     Yes, it's a bit inconsistent with the above.)  Eg: '~ every 10th
+     day of month from 2023/01', which is equivalent to '~ every 10th
+     day of month from 2023/01/01', will be adjusted to start on
+     2019/12/10.
+
+* Menu:
+
+* Periodic rule syntax::
+* Periodic rules and relative dates::
+* Two spaces between period expression and description!::
+
+
+File: hledger.info,  Node: Periodic rule syntax,  Next: Periodic rules and relative dates,  Up: Periodic transactions
+
+8.25.1 Periodic rule syntax
+---------------------------
+
+A periodic transaction rule looks like a normal journal entry, with the
+date replaced by a tilde ('~') followed by a period expression
+(mnemonic: '~' looks like a recurring sine wave.):
+
+# every first of month
+~ monthly
+    expenses:rent          $2000
+    assets:bank:checking
+
+# every 15th of month in 2023's first quarter:
+~ monthly from 2023-04-15 to 2023-06-16
+    expenses:utilities          $400
+    assets:bank:checking
+
+   The period expression is the same syntax used for specifying
+multi-period reports, just interpreted differently; there, it specifies
+report periods; here it specifies recurrence dates (the periods' start
+dates).
+
+
+File: hledger.info,  Node: Periodic rules and relative dates,  Next: Two spaces between period expression and description!,  Prev: Periodic rule syntax,  Up: Periodic transactions
+
+8.25.2 Periodic rules and relative dates
+----------------------------------------
+
+Partial or relative dates (like '12/31', '25', 'tomorrow', 'last week',
+'next quarter') are usually not recommended in periodic rules, since the
+results will change as time passes.  If used, they will be interpreted
+relative to, in order of preference:
+
+  1. the first day of the default year specified by a recent 'Y'
+     directive
+  2. or the date specified with '--today'
+  3. or the date on which you are running the report.
+
+   They will not be affected at all by report period or forecast period
+dates.
+
+
+File: hledger.info,  Node: Two spaces between period expression and description!,  Prev: Periodic rules and relative dates,  Up: Periodic transactions
+
+8.25.3 Two spaces between period expression and description!
+------------------------------------------------------------
+
+If the period expression is followed by a transaction description, these
+must be separated by *two or more spaces*.  This helps hledger know
+where the period expression ends, so that descriptions can not
+accidentally alter their meaning, as in this example:
+
+; 2 or more spaces needed here, so the period is not understood as "every 2 months in 2023"
+;               ||
+;               vv
+~ every 2 months  in 2023, we will review
+    assets:bank:checking   $1500
+    income:acme inc
+
+   So,
+
+   * Do write two spaces between your period expression and your
+     transaction description, if any.
+   * Don't accidentally write two spaces in the middle of your period
+     expression.
+
+
+File: hledger.info,  Node: Auto postings,  Next: Other syntax,  Prev: Periodic transactions,  Up: Journal
+
+8.26 Auto postings
+==================
+
+The '=' directive declares an "auto posting rule", which adds extra
+postings to existing transactions.  (Remember, postings are the account
+name & amount lines below a transaction's date & description.)
+
+   In the journal, an auto posting rule looks quite like a transaction,
+but instead of date and description it has '=' (mnemonic: "match") and a
+query, like this:
+
+= QUERY
+    ACCOUNT    AMOUNT
+    ...
+
+   Queries are just like command line queries; an account name substring
+is most common.  Query terms containing spaces should be enclosed in
+single or double quotes.
+
+   Each '=' rule works like this: when hledger is run with the '--auto'
+flag, wherever the QUERY matches a posting in the journal, the rule's
+postings are added to that transaction, immediately below the matched
+posting.  Note these generated postings are temporary, existing only for
+the duration of the report, and only when '--auto' is used; they are not
+saved in the journal file by hledger.
+
+   Generated postings' amounts can depend on the matched posting's
+amount.  So auto postings can be useful for, eg, adding tax postings
+with a standard percentage.  AMOUNT can be:
+
+   * a number with no commodity symbol, like '2'.  The matched posting's
+     commodity symbol will be added to this.
+
+   * a normal amount with a commodity symbol, like '$2'.  This will be
+     used as-is.
+
+   * an asterisk followed by a number, like '*2'.  This will multiply
+     the matched posting's amount (and total price, if any) by the
+     number.
+
+   * an asterisk followed by an amount with commodity symbol, like
+     '*$2'.  This multiplies and also replaces the commodity symbol with
+     this new one.
+
+   Some examples:
+
+; every time I buy food, schedule a dollar donation
+= expenses:food
+    (liabilities:charity)   $-1
+
+; when I buy a gift, also deduct that amount from a budget envelope subaccount
+= expenses:gifts
+    assets:checking:gifts  *-1
+    assets:checking         *1
+
+2017/12/1
+  expenses:food    $10
+  assets:checking
+
+2017/12/14
+  expenses:gifts   $20
+  assets:checking
+
+$ hledger print --auto
+2017-12-01
+    expenses:food              $10
+    assets:checking
+    (liabilities:charity)      $-1
+
+2017-12-14
+    expenses:gifts             $20
+    assets:checking
+    assets:checking:gifts     -$20
+    assets:checking            $20
+
+   Note that depending fully on generated data such as this has some
+drawbacks - it's less portable, less future-proof, less auditable by
+others, and less robust (eg your balance assertions will depend on
+whether you use or don't use '--auto').  An alternative is to use auto
+postings in "one time" fashion - use them to help build a complex
+journal entry, view it with 'hledger print --auto', and then copy that
+output into the journal file to make it permanent.
+
+* Menu:
+
+* Auto postings and multiple files::
+* Auto postings and dates::
+* Auto postings and transaction balancing / inferred amounts / balance assertions::
+* Auto posting tags::
+* Auto postings on forecast transactions only::
+
+
+File: hledger.info,  Node: Auto postings and multiple files,  Next: Auto postings and dates,  Up: Auto postings
+
+8.26.1 Auto postings and multiple files
+---------------------------------------
+
+An auto posting rule can affect any transaction in the current file, or
+in any parent file or child file.  Note, currently it will not affect
+sibling files (when multiple '-f'/'--file' are used - see #1212).
+
+
+File: hledger.info,  Node: Auto postings and dates,  Next: Auto postings and transaction balancing / inferred amounts / balance assertions,  Prev: Auto postings and multiple files,  Up: Auto postings
+
+8.26.2 Auto postings and dates
+------------------------------
+
+A posting date (or secondary date) in the matched posting, or (taking
+precedence) a posting date in the auto posting rule itself, will also be
+used in the generated posting.
+
+
+File: hledger.info,  Node: Auto postings and transaction balancing / inferred amounts / balance assertions,  Next: Auto posting tags,  Prev: Auto postings and dates,  Up: Auto postings
+
+8.26.3 Auto postings and transaction balancing / inferred amounts /
+-------------------------------------------------------------------
+
+balance assertions Currently, auto postings are added:
+
+   * after missing amounts are inferred, and transactions are checked
+     for balancedness,
+   * but before balance assertions are checked.
+
+   Note this means that journal entries must be balanced both before and
+after auto postings are added.  This changed in hledger 1.12+; see #893
+for background.
+
+   This also means that you cannot have more than one auto-posting with
+a missing amount applied to a given transaction, as it will be unable to
+infer amounts.
+
+
+File: hledger.info,  Node: Auto posting tags,  Next: Auto postings on forecast transactions only,  Prev: Auto postings and transaction balancing / inferred amounts / balance assertions,  Up: Auto postings
+
+8.26.4 Auto posting tags
+------------------------
+
+Automated postings will have some extra tags:
+
+   * 'generated-posting:= QUERY' - shows this was generated by an auto
+     posting rule, and the query
+   * '_generated-posting:= QUERY' - a hidden tag, which does not appear
+     in hledger's output.  This can be used to match postings generated
+     "just now", rather than generated in the past and saved to the
+     journal.
+
+   Also, any transaction that has been changed by auto posting rules
+will have these tags added:
+
+   * 'modified:' - this transaction was modified
+   * '_modified:' - a hidden tag not appearing in the comment; this
+     transaction was modified "just now".
+
+
+File: hledger.info,  Node: Auto postings on forecast transactions only,  Prev: Auto posting tags,  Up: Auto postings
+
+8.26.5 Auto postings on forecast transactions only
+--------------------------------------------------
+
+Tip: you can can make auto postings that will apply to forecast
+transactions but not recorded transactions, by adding
+'tag:_generated-transaction' to their QUERY. This can be useful when
+generating new journal entries to be saved in the journal.
+
+
+File: hledger.info,  Node: Other syntax,  Prev: Auto postings,  Up: Journal
+
+8.27 Other syntax
+=================
+
+hledger journal format supports quite a few other features, mainly to
+make interoperating with or converting from Ledger easier.  Note some of
+the features below are powerful and can be useful in special cases, but
+in general, features in this section are considered less important or
+even not recommended for most users.  Downsides are mentioned to help
+you decide if you want to use them.
+
+* Menu:
+
+* Balance assignments::
+* Bracketed posting dates::
+* D directive::
+* apply account directive::
+* Y directive::
+* Secondary dates::
+* Star comments::
+* Valuation expressions::
+* Virtual postings::
+* Other Ledger directives::
+* Other cost/lot notations::
+
+
+File: hledger.info,  Node: Balance assignments,  Next: Bracketed posting dates,  Up: Other syntax
+
+8.27.1 Balance assignments
+--------------------------
+
+Ledger-style balance assignments are also supported.  These are like
+balance assertions, but with no posting amount on the left side of the
+equals sign; instead it is calculated automatically so as to satisfy the
+assertion.  This can be a convenience during data entry, eg when setting
+opening balances:
+
+; starting a new journal, set asset account balances
+2016/1/1 opening balances
+  assets:checking            = $409.32
+  assets:savings             = $735.24
+  assets:cash                 = $42
+  equity:opening balances
+
+   or when adjusting a balance to reality:
+
+; no cash left; update balance, record any untracked spending as a generic expense
+2016/1/15
+  assets:cash    = $0
+  expenses:misc
+
+   The calculated amount depends on the account's balance in the
+commodity at that point (which depends on the previously-dated postings
+of the commodity to that account since the last balance assertion or
+assignment).
+
+   Downsides: using balance assignments makes your journal less
+explicit; to know the exact amount posted, you have to run hledger or do
+the calculations yourself, instead of just reading it.  Also balance
+assignments' forcing of balances can hide errors.  These things make
+your financial data less portable, less future-proof, and less
+trustworthy in an audit.
+
+* Menu:
+
+* Balance assignments and costs::
+* Balance assignments and multiple files::
+
+
+File: hledger.info,  Node: Balance assignments and costs,  Next: Balance assignments and multiple files,  Up: Balance assignments
+
+8.27.1.1 Balance assignments and costs
+......................................
+
+A cost in a balance assignment will cause the calculated amount to have
+that cost attached:
+
+2019/1/1
+  (a)             = $1 @ €2
+
+$ hledger print --explicit
+2019-01-01
+    (a)         $1 @ €2 = $1 @ €2
+
+
+File: hledger.info,  Node: Balance assignments and multiple files,  Prev: Balance assignments and costs,  Up: Balance assignments
+
+8.27.1.2 Balance assignments and multiple files
+...............................................
+
+Balance assignments handle multiple files like balance assertions.  They
+see balance from other files previously included from the current file,
+but not from previous sibling or parent files.
+
+
+File: hledger.info,  Node: Bracketed posting dates,  Next: D directive,  Prev: Balance assignments,  Up: Other syntax
+
+8.27.2 Bracketed posting dates
+------------------------------
+
+For setting posting dates and secondary posting dates, Ledger's
+bracketed date syntax is also supported: '[DATE]', '[DATE=DATE2]' or
+'[=DATE2]' in posting comments.  hledger will attempt to parse any
+square-bracketed sequence of the '0123456789/-.=' characters in this
+way.  With this syntax, DATE infers its year from the transaction and
+DATE2 infers its year from DATE.
+
+   Downsides: another syntax to learn, redundant with hledger's
+'date:'/'date2:' tags, and confusingly similar to Ledger's lot date
+syntax.
+
+
+File: hledger.info,  Node: D directive,  Next: apply account directive,  Prev: Bracketed posting dates,  Up: Other syntax
+
+8.27.3 'D' directive
+--------------------
+
+'D AMOUNT'
+
+   This directive sets a default commodity, to be used for any
+subsequent commodityless amounts (ie, plain numbers) seen while parsing
+the journal.  This effect lasts until the next 'D' directive, or the end
+of the current file.
+
+   For compatibility/historical reasons, 'D' also acts like a
+'commodity' directive (setting the commodity's decimal mark for parsing
+and display style for output).  So its argument is not just a commodity
+symbol, but a full amount demonstrating the style.  The amount must
+include a decimal mark (either period or comma).  Eg:
+
+; commodity-less amounts should be treated as dollars
+; (and displayed with the dollar sign on the left, thousands separators and two decimal places)
+D $1,000.00
+
+1/1
+  a     5  ; <- commodity-less amount, parsed as $5 and displayed as $5.00
+  b
+
+   Interactions with other directives:
+
+   For setting a commodity's display style, a 'commodity' directive has
+highest priority, then a 'D' directive.
+
+   For detecting a commodity's decimal mark during parsing,
+'decimal-mark' has highest priority, then 'commodity', then 'D'.
+
+   For checking commodity symbols with the check command, a 'commodity'
+directive is required ('hledger check commodities' ignores 'D'
+directives).
+
+   Downsides: omitting commodity symbols makes your financial data less
+explicit, less portable, and less trustworthy in an audit.  It is
+usually an unsustainable shortcut; sooner or later you will want to
+track multiple commodities.  D is overloaded with functions redundant
+with 'commodity' and 'decimal-mark'.  And it works differently from
+Ledger's 'D'.
+
+
+File: hledger.info,  Node: apply account directive,  Next: Y directive,  Prev: D directive,  Up: Other syntax
+
+8.27.4 'apply account' directive
+--------------------------------
+
+This directive sets a default parent account, which will be prepended to
+all accounts in following entries, until an 'end apply account'
+directive or end of current file.  Eg:
+
+apply account home
+
+2010/1/1
+    food    $10
+    cash
+
+end apply account
+
+   is equivalent to:
+
+2010/01/01
+    home:food           $10
+    home:cash          $-10
+
+   'account' directives are also affected, and so is any 'include'd
+content.
+
+   Account names entered via hledger add or hledger-web are not
+affected.
+
+   Account aliases, if any, are applied after the parent account is
+prepended.
+
+   Downsides: this can make your financial data less explicit, less
+portable, and less trustworthy in an audit.
+
+
+File: hledger.info,  Node: Y directive,  Next: Secondary dates,  Prev: apply account directive,  Up: Other syntax
+
+8.27.5 'Y' directive
+--------------------
+
+'Y YEAR'
+
+   or (deprecated backward-compatible forms):
+
+   'year YEAR' 'apply year YEAR'
+
+   The space is optional.  This sets a default year to be used for
+subsequent dates which don't specify a year.  Eg:
+
+Y2009  ; set default year to 2009
+
+12/15  ; equivalent to 2009/12/15
+  expenses  1
+  assets
+
+year 2010  ; change default year to 2010
+
+2009/1/30  ; specifies the year, not affected
+  expenses  1
+  assets
+
+1/31   ; equivalent to 2010/1/31
+  expenses  1
+  assets
+
+   Downsides: omitting the year (from primary transaction dates, at
+least) makes your financial data less explicit, less portable, and less
+trustworthy in an audit.  Such dates can get separated from their
+corresponding Y directive, eg when evaluating a region of the journal in
+your editor.  A missing Y directive makes reports dependent on today's
+date.
+
+
+File: hledger.info,  Node: Secondary dates,  Next: Star comments,  Prev: Y directive,  Up: Other syntax
+
+8.27.6 Secondary dates
+----------------------
+
+A secondary date is written after the primary date, following an equals
+sign: 'DATE1=DATE2'.  If the year is omitted, the primary date's year is
+assumed.  When running reports, the primary (left side) date is used by
+default, but with the '--date2' flag ('--aux-date' or'--effective' also
+work, for Ledger users), the secondary (right side) date will be used
+instead.
+
+   The meaning of secondary dates is up to you.  Eg it could be "primary
+is the bank's clearing date, secondary is the date the transaction was
+initiated, if different".
+
+   In practice, this feature usually adds confusion:
+
+   * You have to remember the primary and secondary dates' meaning, and
+     follow that consistently.
+   * It splits your bookkeeping into two modes, and you have to remember
+     which mode is appropriate for a given report.
+   * Usually your balance assertions will work with only one of these
+     modes.
+   * It makes your financial data more complicated, less portable, and
+     less clear in an audit.
+   * It interacts with every feature, creating an ongoing cost for
+     implementors.
+   * It distracts new users and supporters.
+   * Posting dates are simpler and work better.
+
+   So secondary dates are officially deprecated in hledger, remaining
+only as a Ledger compatibility aid; we recommend using posting dates
+instead.
+
+
+File: hledger.info,  Node: Star comments,  Next: Valuation expressions,  Prev: Secondary dates,  Up: Other syntax
+
+8.27.7 Star comments
+--------------------
+
+Lines beginning with '*' (star/asterisk) are also comment lines.  This
+feature allows Emacs users to insert org headings in their journal,
+allowing them to fold/unfold/navigate it like an outline when viewed
+with org mode.
+
+   Downsides: another, unconventional comment syntax to learn.
+Decreases your journal's portability.  And switching to Emacs org mode
+just for folding/unfolding meant losing the benefits of ledger mode;
+nowadays you can add outshine mode to ledger mode to get folding without
+losing ledger mode's features.
+
+
+File: hledger.info,  Node: Valuation expressions,  Next: Virtual postings,  Prev: Star comments,  Up: Other syntax
+
+8.27.8 Valuation expressions
+----------------------------
+
+Ledger allows a valuation function or value to be written in double
+parentheses after an amount.  hledger ignores these.
+
+
+File: hledger.info,  Node: Virtual postings,  Next: Other Ledger directives,  Prev: Valuation expressions,  Up: Other syntax
+
+8.27.9 Virtual postings
+-----------------------
+
+A posting with parentheses around the account name, like '(some:account)
+10', is called an _unbalanced virtual posting_.  These postings do not
+participate in transaction balancing.  (And if you write them without an
+amount, a zero amount is always inferred.)  These can occasionally be
+convenient for special circumstances, but they violate double entry
+bookkeeping and make your data less portable across applications, so
+many people avoid using them at all.
+
+   A posting with brackets around the account name ('[some:account]') is
+called a _balanced virtual posting_.  The balanced virtual postings in a
+transaction must add up to zero, just like ordinary postings, but
+separately from them.  These are not part of double entry bookkeeping
+either, but they are at least balanced.  An example:
+
+2022-01-01 buy food with cash, update budget envelope subaccounts, & something else
+  assets:cash                    $-10  ; <- these balance each other
+  expenses:food                    $7  ; <-
+  expenses:food                    $3  ; <-
+  [assets:checking:budget:food]  $-10  ;   <- and these balance each other
+  [assets:checking:available]     $10  ;   <-
+  (something:else)                 $5  ;     <- this is not required to balance
+
+   Ordinary postings, whose account names are neither parenthesised nor
+bracketed, are called _real postings_.  You can exclude virtual postings
+from reports with the '-R/--real' flag or a 'real:1' query.
+
+
+File: hledger.info,  Node: Other Ledger directives,  Next: Other cost/lot notations,  Prev: Virtual postings,  Up: Other syntax
+
+8.27.10 Other Ledger directives
+-------------------------------
+
+These other Ledger directives are currently accepted but ignored.  This
+allows hledger to read more Ledger files, but be aware that hledger's
+reports may differ from Ledger's if you use these.
+
+apply fixed COMM AMT
+apply tag   TAG
+assert      EXPR
+bucket / A  ACCT
+capture     ACCT REGEX
+check       EXPR
+define      VAR=EXPR
+end apply fixed
+end apply tag
+end apply year
+end tag
+eval / expr EXPR
+python
+  PYTHONCODE
+tag         NAME
+value       EXPR
+--command-line-flags
+
+   See also https://hledger.org/ledger.html for a detailed
+hledger/Ledger syntax comparison.
+
+
+File: hledger.info,  Node: Other cost/lot notations,  Prev: Other Ledger directives,  Up: Other syntax
+
+8.27.11 Other cost/lot notations
+--------------------------------
+
+A slight digression for Ledger and Beancount users.
+
+   *Ledger* has a number of cost/lot-related notations:
+
+   * '@ UNITCOST' and '@@ TOTALCOST'
+        * expresses a conversion rate, as in hledger
+        * when buying, also creates a lot that can be selected at
+          selling time
+
+   * '(@) UNITCOST' and '(@@) TOTALCOST' (virtual cost)
+        * like the above, but also means "this cost was exceptional,
+          don't use it when inferring market prices".
+
+   * '{=UNITCOST}' and '{{=TOTALCOST}}' (fixed price)
+        * when buying, means "this cost is also the fixed value, don't
+          let it fluctuate in value reports"
+
+   * '{UNITCOST}' and '{{TOTALCOST}}' (lot price)
+        * can be used identically to '@ UNITCOST' and '@@ TOTALCOST',
+          also creates a lot
+        * when selling, combined with '@ ...', selects an existing lot
+          by its cost basis.  Does not check if that lot is present.
+
+   * '[YYYY/MM/DD]' (lot date)
+        * when buying, attaches this acquisition date to the lot
+        * when selling, selects a lot by its acquisition date
+
+   * '(SOME TEXT)' (lot note)
+        * when buying, attaches this note to the lot
+        * when selling, selects a lot by its note
+
+   Currently, hledger
+
+   * accepts any or all of the above in any order after the posting
+     amount
+   * supports '@' and '@@'
+   * treats '(@)' and '(@@)' as synonyms for '@' and '@@'
+   * and ignores the rest.  (This can break transaction balancing.)
+
+   *Beancount* has simpler notation and different behaviour:
+
+   * '@ UNITCOST' and '@@ TOTALCOST'
+        * expresses a cost without creating a lot, as in hledger
+        * when buying (acquiring) or selling (disposing of) a lot, and
+          combined with '{...}': is not used except to document the
+          cost/selling price
+
+   * '{UNITCOST}' and '{{TOTALCOST}}'
+        * when buying, expresses the cost for transaction balancing, and
+          also creates a lot with this cost basis attached
+        * when selling,
+             * selects a lot by its cost basis
+             * raises an error if that lot is not present or can not be
+               selected unambiguously (depending on booking method
+               configured)
+             * expresses the selling price for transaction balancing
+
+   * '{}', '{YYYY-MM-DD}', '{"LABEL"}', '{UNITCOST, "LABEL"}',
+     '{UNITCOST, YYYY-MM-DD, "LABEL"}'
+        * when selling, other combinations of date/cost/label, like the
+          above, are accepted for selecting the lot.
+
+   Currently, hledger
+
+   * supports '@' and '@@'
+   * accepts the '{UNITCOST}'/'{{TOTALCOST}}' notation, but ignores it
+   * and rejects the rest.
+
+
+File: hledger.info,  Node: CSV,  Next: Timeclock,  Prev: Journal,  Up: Top
+
+9 CSV
+*****
+
+hledger can read CSV files (Character Separated Value - usually comma,
+semicolon, or tab) containing dated records, automatically converting
+each record into a transaction.
+
+   (To learn about _writing_ CSV, see CSV output.)
+
+   For best error messages when reading CSV/TSV/SSV files, make sure
+they have a corresponding '.csv', '.tsv' or '.ssv' file extension or use
+a hledger file prefix (see File Extension below).
+
+   Each CSV file must be described by a corresponding _rules file_.
+This contains rules describing the CSV data (header line, fields layout,
+date format etc.), how to construct hledger transactions from it, and
+how to categorise transactions based on description or other attributes.
+
+   By default, hledger expects this rules file to be named like the CSV
+file, with an extra '.rules' extension added, in the same directory.  Eg
+when asked to read 'foo/FILE.csv', hledger looks for
+'foo/FILE.csv.rules'.  You can specify a different rules file with the
+'--rules' option.
+
+   At minimum, the rules file must identify the date and amount fields,
+and often it also specifies the date format and how many header lines
+there are.  Here's a simple CSV file and a rules file for it:
+
+Date, Description, Id, Amount
+12/11/2019, Foo, 123, 10.23
+
+# basic.csv.rules
+skip         1
+fields       date, description, , amount
+date-format  %d/%m/%Y
+
+$ hledger print -f basic.csv
+2019-11-12 Foo
+    expenses:unknown           10.23
+    income:unknown            -10.23
+
+   There's an introductory Importing CSV data tutorial on hledger.org,
+and more CSV rules examples below, and a larger collection at
+https://github.com/simonmichael/hledger/tree/master/examples/csv.
+
+* Menu:
+
+* CSV rules cheatsheet::
+* source::
+* encoding::
+* separator::
+* skip::
+* date-format::
+* timezone::
+* newest-first::
+* intra-day-reversed::
+* decimal-mark::
+* fields list::
+* Field assignment::
+* Field names::
+* if block::
+* Matchers::
+* if table::
+* balance-type::
+* include::
+* Working with CSV::
+* CSV rules examples::
+
+
+File: hledger.info,  Node: CSV rules cheatsheet,  Next: source,  Up: CSV
+
+9.1 CSV rules cheatsheet
+========================
+
+The following kinds of rule can appear in the rules file, in any order.
+(Blank lines and lines beginning with '#' or ';' or '*' are ignored.)
+
+*'source'*               optionally declare which file to read data
+                         from
+*'encoding'*             optionally declare which text encoding the
+                         data has
+*'separator'*            declare the field separator, instead of
+                         relying on file extension
+*'skip'*                 skip one or more header lines at start of file
+*'date-format'*          declare how to parse CSV dates/date-times
+*'timezone'*             declare the time zone of ambiguous CSV
+                         date-times
+*'newest-first'*         improve txn order when: there are multiple
+                         records, newest first, all with the same date
+*'intra-day-reversed'*   improve txn order when: same-day txns are in
+                         opposite order to the overall file
+*'decimal-mark'*         declare the decimal mark used in CSV amounts,
+                         when ambiguous
+*'fields' list*          name CSV fields for easy reference, and
+                         optionally assign their values to hledger
+                         fields
+*Field assignment*       assign a CSV value or interpolated text value
+                         to a hledger field
+*'if' block*             conditionally assign values to hledger fields,
+                         or 'skip' a record or 'end' (skip rest of
+                         file)
+*'if' table*             conditionally assign values to hledger fields,
+                         using compact syntax
+*'balance-type'*         select which type of balance
+                         assertions/assignments to generate
+*'include'*              inline another CSV rules file
+
+   Working with CSV tips can be found below, including How CSV rules are
+evaluated.
+
+
+File: hledger.info,  Node: source,  Next: encoding,  Prev: CSV rules cheatsheet,  Up: CSV
+
+9.2 'source'
+============
+
+If you tell hledger to read a csv file with '-f foo.csv', it will look
+for rules in 'foo.csv.rules'.  Or, you can tell it to read the rules
+file, with '-f foo.csv.rules', and it will look for data in 'foo.csv'
+(since 1.30).
+
+   These are mostly equivalent, but the second method provides some
+extra features.  For one, the data file can be missing, without causing
+an error; it is just considered empty.  And, you can specify a different
+data file by adding a "source" rule:
+
+source ./Checking1.csv
+
+   If you specify just a file name with no path, hledger will look for
+it in your system's downloads directory ('~/Downloads', currently):
+
+source Checking1.csv
+
+   And if you specify a glob pattern, hledger will read the most recent
+of the matched files (useful with repeated downloads):
+
+source Checking1*.csv
+
+   See also "Working with CSV > Reading files specified by rule".
+
+
+File: hledger.info,  Node: encoding,  Next: separator,  Prev: source,  Up: CSV
+
+9.3 'encoding'
+==============
+
+encoding ENCODING
+
+   hledger normally expects non-ascii text to be UTF8-encoded.  If you
+need to read CSV files which have some other encoding, you can do it by
+adding 'encoding ENCODING' to your CSV rules.  Eg: 'encoding ISO88591'.
+
+   The following encodings are supported (these names are
+case-insensitive, and can be written with inner spaces or hyphens if you
+prefer): ASCII, UTF8, UTF16, UTF32, ISO88591, ISO88592, ISO88593,
+ISO88594, ISO88595, ISO88596, ISO88597, ISO88598, ISO88599, ISO885910,
+ISO885911, ISO885913, ISO885914, ISO885915, ISO885916, CP1250, CP1251,
+CP1252, CP1253, CP1254, CP1255, CP1256, CP1257, CP1258, KOI8R, KOI8U,
+GB18030, MacOSRoman, JISX0201, JISX0208, ISO2022JP, ShiftJIS, CP437,
+CP737, CP775, CP850, CP852, CP855, CP857, CP860, CP861, CP862, CP863,
+CP864, CP865, CP866, CP869, CP874, CP932.
+
+
+File: hledger.info,  Node: separator,  Next: skip,  Prev: encoding,  Up: CSV
+
+9.4 'separator'
+===============
+
+You can use the 'separator' rule to read other kinds of
+character-separated data.  The argument is any single separator
+character, or the words 'tab' or 'space' (case insensitive).  Eg, for
+comma-separated values (CSV):
+
+separator ,
+
+   or for semicolon-separated values (SSV):
+
+separator ;
+
+   or for tab-separated values (TSV):
+
+separator TAB
+
+   If the input file has a '.csv', '.ssv' or '.tsv' file extension (or a
+'csv:', 'ssv:', 'tsv:' prefix), the appropriate separator will be
+inferred automatically, and you won't need this rule.
+
+
+File: hledger.info,  Node: skip,  Next: date-format,  Prev: separator,  Up: CSV
+
+9.5 'skip'
+==========
+
+skip N
+
+   The word 'skip' followed by a number (or no number, meaning 1) tells
+hledger to ignore this many non-empty lines at the start of the input
+data.  You'll need this whenever your CSV data contains header lines.
+Note, empty and blank lines are skipped automatically, so you don't need
+to count those.
+
+   'skip' has a second meaning: it can be used inside if blocks
+(described below), to skip one or more records whenever the condition is
+true.  Records skipped in this way are ignored, except they are still
+required to be valid CSV.
+
+
+File: hledger.info,  Node: date-format,  Next: timezone,  Prev: skip,  Up: CSV
+
+9.6 'date-format'
+=================
+
+date-format DATEFMT
+
+   This is a helper for the 'date' (and 'date2') fields.  If your CSV
+dates are not formatted like 'YYYY-MM-DD', 'YYYY/MM/DD' or 'YYYY.MM.DD',
+you'll need to add a date-format rule describing them with a
+strptime-style date parsing pattern - see
+https://hackage.haskell.org/package/time/docs/Data-Time-Format.html#v:formatTime.
+The pattern must parse the CSV date value completely.  Some examples:
+
+# MM/DD/YY
+date-format %m/%d/%y
+
+# D/M/YYYY
+# The - makes leading zeros optional.
+date-format %-d/%-m/%Y
+
+# YYYY-Mmm-DD
+date-format %Y-%h-%d
+
+# M/D/YYYY HH:MM AM some other junk
+# Note the time and junk must be fully parsed, though only the date is used.
+date-format %-m/%-d/%Y %l:%M %p some other junk
+
+
+File: hledger.info,  Node: timezone,  Next: newest-first,  Prev: date-format,  Up: CSV
+
+9.7 'timezone'
+==============
+
+timezone TIMEZONE
+
+   When CSV contains date-times that are implicitly in some time zone
+other than yours, but containing no explicit time zone information, you
+can use this rule to declare the CSV's native time zone, which helps
+prevent off-by-one dates.
+
+   When the CSV date-times do contain time zone information, you don't
+need this rule; instead, use '%Z' in 'date-format' (or '%z', '%EZ',
+'%Ez'; see the formatTime link above).
+
+   In either of these cases, hledger will do a time-zone-aware
+conversion, localising the CSV date-times to your current system time
+zone.  If you prefer to localise to some other time zone, eg for
+reproducibility, you can (on unix at least) set the output timezone with
+the TZ environment variable, eg:
+
+$ TZ=-1000 hledger print -f foo.csv  # or TZ=-1000 hledger import foo.csv
+
+   'timezone' currently does not understand timezone names, except
+"UTC", "GMT", "EST", "EDT", "CST", "CDT", "MST", "MDT", "PST", or "PDT".
+For others, use numeric format: +HHMM or -HHMM.
+
+
+File: hledger.info,  Node: newest-first,  Next: intra-day-reversed,  Prev: timezone,  Up: CSV
+
+9.8 'newest-first'
+==================
+
+hledger tries to ensure that the generated transactions will be ordered
+chronologically, including same-day transactions.  Usually it can
+auto-detect how the CSV records are ordered.  But if it encounters CSV
+where all records are on the same date, it assumes that the records are
+oldest first.  If in fact the CSV's records are normally newest first,
+like:
+
+2022-10-01, txn 3...
+2022-10-01, txn 2...
+2022-10-01, txn 1...
+
+   you can add the 'newest-first' rule to help hledger generate the
+transactions in correct order.
+
+# same-day CSV records are newest first
+newest-first
+
+
+File: hledger.info,  Node: intra-day-reversed,  Next: decimal-mark,  Prev: newest-first,  Up: CSV
+
+9.9 'intra-day-reversed'
+========================
+
+If CSV records within a single day are ordered opposite to the overall
+record order, you can add the 'intra-day-reversed' rule to improve the
+order of journal entries.  Eg, here the overall record order is newest
+first, but same-day records are oldest first:
+
+2022-10-02, txn 3...
+2022-10-02, txn 4...
+2022-10-01, txn 1...
+2022-10-01, txn 2...
+
+# transactions within each day are reversed with respect to the overall date order
+intra-day-reversed
+
+
+File: hledger.info,  Node: decimal-mark,  Next: fields list,  Prev: intra-day-reversed,  Up: CSV
+
+9.10 'decimal-mark'
+===================
+
+decimal-mark .
+
+   or:
+
+decimal-mark ,
+
+   hledger automatically accepts either period or comma as a decimal
+mark when parsing numbers (cf Amounts).  However if any numbers in the
+CSV contain digit group marks, such as thousand-separating commas, you
+should declare the decimal mark explicitly with this rule, to avoid
+misparsed numbers.
+
+
+File: hledger.info,  Node: fields list,  Next: Field assignment,  Prev: decimal-mark,  Up: CSV
+
+9.11 'fields' list
+==================
+
+fields FIELDNAME1, FIELDNAME2, ...
+
+   A fields list (the word 'fields' followed by comma-separated field
+names) is optional, but convenient.  It does two things:
+
+  1. It names the CSV field in each column.  This can be convenient if
+     you are referencing them in other rules, so you can say
+     '%SomeField' instead of remembering '%13'.
+
+  2. Whenever you use one of the special hledger field names (described
+     below), it assigns the CSV value in this position to that hledger
+     field.  This is the quickest way to populate hledger's fields and
+     build a transaction.
+
+   Here's an example that says "use the 1st, 2nd and 4th fields as the
+transaction's date, description and amount; name the last two fields for
+later reference; and ignore the others":
+
+fields date, description, , amount, , , somefield, anotherfield
+
+   In a fields list, the separator is always comma; it is unrelated to
+the CSV file's separator.  Also:
+
+   * There must be least two items in the list (at least one comma).
+   * Field names may not contain spaces.  Spaces before/after field
+     names are optional.
+   * Field names may contain '_' (underscore) or '-' (hyphen).
+   * Fields you don't care about can be given a dummy name or an empty
+     name.
+
+   If the CSV contains column headings, it's convenient to use these for
+your field names, suitably modified (eg lower-cased with spaces replaced
+by underscores).
+
+   Sometimes you may want to alter a CSV field name to avoid assigning
+to a hledger field with the same name.  Eg you could call the CSV's
+"balance" field 'balance_' to avoid directly setting hledger's 'balance'
+field (and generating a balance assertion).
+
+
+File: hledger.info,  Node: Field assignment,  Next: Field names,  Prev: fields list,  Up: CSV
+
+9.12 Field assignment
+=====================
+
+HLEDGERFIELD FIELDVALUE
+
+   Field assignments are the more flexible way to assign CSV values to
+hledger fields.  They can be used instead of or in addition to a fields
+list (see above).
+
+   To assign a value to a hledger field, write the field name (any of
+the standard hledger field/pseudo-field names, defined below), a space,
+followed by a text value on the same line.  This text value may
+interpolate CSV fields, referenced either by their 1-based position in
+the CSV record ('%N') or by the name they were given in the fields list
+('%CSVFIELD'), and regular expression match groups ('\N').
+
+   Some examples:
+
+# set the amount to the 4th CSV field, with " USD" appended
+amount %4 USD
+
+# combine three fields to make a comment, containing note: and date: tags
+comment note: %somefield - %anotherfield, date: %1
+
+   Tips:
+
+   * Interpolation strips outer whitespace (so a CSV value like '" 1 "'
+     becomes '1' when interpolated) (#1051).
+   * Interpolations always refer to a CSV field - you can't interpolate
+     a hledger field.  (See Referencing other fields below).
+
+
+File: hledger.info,  Node: Field names,  Next: if block,  Prev: Field assignment,  Up: CSV
+
+9.13 Field names
+================
+
+Note the two kinds of field names mentioned here, and used only in
+hledger CSV rules files:
+
+  1. *CSV field names* ('CSVFIELD' in these docs): you can optionally
+     name the CSV columns for easy reference (since hledger doesn't yet
+     automatically recognise column headings in a CSV file), by writing
+     arbitrary names in a 'fields' list, eg:
+
+     fields When, What, Some_Id, Net, Total, Foo, Bar
+
+  2. Special *hledger field names* ('HLEDGERFIELD' in these docs): you
+     must set at least some of these to generate the hledger transaction
+     from a CSV record, by writing them as the left hand side of a field
+     assignment, eg:
+
+     date        %When
+     code        %Some_Id
+     description %What
+     comment     %Foo %Bar
+     amount1     $ %Total
+
+     or directly in a 'fields' list:
+
+     fields date, description, code, , amount1, Foo, Bar
+     currency $
+     comment  %Foo %Bar
+
+   Here are all the special hledger field names available, and what
+happens when you assign values to them:
+
+* Menu:
+
+* date field::
+* date2 field::
+* status field::
+* code field::
+* description field::
+* comment field::
+* account field::
+* amount field::
+* currency field::
+* balance field::
+
+
+File: hledger.info,  Node: date field,  Next: date2 field,  Up: Field names
+
+9.13.1 date field
+-----------------
+
+Assigning to 'date' sets the transaction date.
+
+
+File: hledger.info,  Node: date2 field,  Next: status field,  Prev: date field,  Up: Field names
+
+9.13.2 date2 field
+------------------
+
+'date2' sets the transaction's secondary date, if any.
+
+
+File: hledger.info,  Node: status field,  Next: code field,  Prev: date2 field,  Up: Field names
+
+9.13.3 status field
+-------------------
+
+'status' sets the transaction's status, if any.
+
+
+File: hledger.info,  Node: code field,  Next: description field,  Prev: status field,  Up: Field names
+
+9.13.4 code field
+-----------------
+
+'code' sets the transaction's code, if any.
+
+
+File: hledger.info,  Node: description field,  Next: comment field,  Prev: code field,  Up: Field names
+
+9.13.5 description field
+------------------------
+
+'description' sets the transaction's description, if any.
+
+
+File: hledger.info,  Node: comment field,  Next: account field,  Prev: description field,  Up: Field names
+
+9.13.6 comment field
+--------------------
+
+'comment' sets the transaction's comment, if any.
+
+   'commentN', where N is a number, sets the Nth posting's comment.
+
+   You can assign multi-line comments by writing literal '\n' in the
+code.  A comment starting with '\n' will begin on a new line.
+
+   Comments can contain tags, as usual.
+
+   Posting comments can also contain a posting date.  A secondary date,
+or a year-less date, will be ignored.
+
+
+File: hledger.info,  Node: account field,  Next: amount field,  Prev: comment field,  Up: Field names
+
+9.13.7 account field
+--------------------
+
+Assigning to 'accountN', where N is 1 to 99, sets the account name of
+the Nth posting, and causes that posting to be generated.
+
+   Most often there are two postings, so you'll want to set 'account1'
+and 'account2'.  Typically 'account1' is associated with the CSV file,
+and is set once with a top-level assignment, while 'account2' is set
+based on each transaction's description, in conditional rules.
+
+   If a posting's account name is left unset but its amount is set (see
+below), a default account name will be chosen (like "expenses:unknown"
+or "income:unknown").
+
+
+File: hledger.info,  Node: amount field,  Next: currency field,  Prev: account field,  Up: Field names
+
+9.13.8 amount field
+-------------------
+
+There are several ways to set posting amounts from CSV, useful in
+different situations.
+
+  1. *'amount'* is the oldest and simplest.  Assigning to this sets the
+     amount of the first and second postings.  In the second posting,
+     the amount will be negated; also, if it has a cost attached, it
+     will be converted to cost.
+
+  2. *'amount-in'* and *'amount-out'* work exactly like the above, but
+     should be used when the CSV has two amount fields (such as "Debit"
+     and "Credit", or "Inflow" and "Outflow").  Whichever field has a
+     non-zero value will be used as the amount of the first and second
+     postings.  Here are some tips to avoid confusion:
+
+        * It's not "amount-in for posting 1 and amount-out for posting
+          2", it is "extract a single amount from the amount-in or
+          amount-out field, and use that for posting 1 and (negated) for
+          posting 2".
+        * Don't use both 'amount' and 'amount-in'/'amount-out' in the
+          same rules file; choose based on whether the amount is in a
+          single CSV field or spread across two fields.
+        * In each record, at most one of the two CSV fields should
+          contain a non-zero amount; the other field must contain a zero
+          or nothing.
+        * hledger assumes both CSV fields contain unsigned numbers, and
+          it automatically negates the amount-out values.
+        * If the data doesn't fit these requirements, you'll probably
+          need an if rule (see below).
+
+  3. *'amountN'* (where N is a number from 1 to 99) sets the amount of
+     only a single posting: the Nth posting in the transaction.  You'll
+     usually need at least two such assignments to make a balanced
+     transaction.  You can also generate more than two postings, to
+     represent more complex transactions.  The posting numbers don't
+     have to be consecutive; with if rules, higher posting numbers can
+     be useful to ensure a certain order of postings.
+
+  4. *'amountN-in'* and *'amountN-out'* work exactly like the above, but
+     should be used when the CSV has two amount fields.  This is
+     analogous to 'amount-in' and 'amount-out', and those tips also
+     apply here.
+
+  5. Remember that a 'fields' list can also do assignments.  So in a
+     fields list if you name a CSV field "amount", that counts as
+     assigning to 'amount'.  (If you don't want that, call it something
+     else in the fields list, like "amount_".)
+
+  6. The above don't handle every situation; if you need more
+     flexibility, use an 'if' rule to set amounts conditionally.  See
+     "Working with CSV > Setting amounts" below for more on this and on
+     amount-setting generally.
+
+
+File: hledger.info,  Node: currency field,  Next: balance field,  Prev: amount field,  Up: Field names
+
+9.13.9 currency field
+---------------------
+
+'currency' sets a currency symbol, to be prepended to all postings'
+amounts.  You can use this if the CSV amounts do not have a currency
+symbol, eg if it is in a separate column.
+
+   'currencyN' prepends a currency symbol to just the Nth posting's
+amount.
+
+
+File: hledger.info,  Node: balance field,  Prev: currency field,  Up: Field names
+
+9.13.10 balance field
+---------------------
+
+'balanceN' sets a balance assertion amount (or if the posting amount is
+left empty, a balance assignment) on posting N.
+
+   'balance' is a compatibility spelling for hledger <1.17; it is
+equivalent to 'balance1'.
+
+   You can adjust the type of assertion/assignment with the
+'balance-type' rule (see below).
+
+   See the Working with CSV tips below for more about setting amounts
+and currency.
+
+
+File: hledger.info,  Node: if block,  Next: Matchers,  Prev: Field names,  Up: CSV
+
+9.14 'if' block
+===============
+
+Rules can be applied conditionally, depending on patterns in the CSV
+data.  This allows flexibility; in particular, it is how you can
+categorise transactions, selecting an appropriate account name based on
+their description (for example).  There are two ways to write
+conditional rules: "if blocks", described here, and "if tables",
+described below.
+
+   An if block is the word 'if' and one or more "matcher" expressions
+(can be a word or phrase), one per line, starting either on the same or
+next line; followed by one or more indented rules.  Eg,
+
+if MATCHER
+ RULE
+
+   or
+
+if
+MATCHER
+MATCHER
+MATCHER
+ RULE
+ RULE
+
+   If any of the matchers succeeds, all of the indented rules will be
+applied.  They are usually field assignments, but the following special
+rules may also be used within an if block:
+
+   * 'skip' - skips the matched CSV record (generating no transaction
+     from it)
+   * 'end' - skips the rest of the current CSV file.
+
+   Some examples:
+
+# if the record contains "groceries", set account2 to "expenses:groceries"
+if groceries
+ account2 expenses:groceries
+
+# if the record contains any of these phrases, set account2 and a transaction comment as shown
+if
+monthly service fee
+atm transaction fee
+banking thru software
+ account2 expenses:business:banking
+ comment  XXX deductible ? check it
+
+# if an empty record is seen (assuming five fields), ignore the rest of the CSV file
+if ,,,,
+ end
+
+
+File: hledger.info,  Node: Matchers,  Next: if table,  Prev: if block,  Up: CSV
+
+9.15 Matchers
+=============
+
+There are two kinds of matcher:
+
+  1. A whole record matcher is simplest: it is just a word, single-line
+     text fragment, or other regular expression, which hledger will try
+     to match case-insensitively anywhere within the CSV record.
+     Eg: 'whole foods'.
+
+  2. A field matcher has a percent-prefixed CSV field number or name
+     before the pattern.
+     Eg: '%3 whole foods' or '%description whole foods'.
+     hledger will try to match the pattern just within the named CSV
+     field.
+
+   When using these, there's two things to be aware of:
+
+  1. Whole record matchers don't see the exact original record; they see
+     a reconstruction of it, in which values are comma-separated, and
+     quotes enclosing values and whitespace outside those quotes are
+     removed.
+     Eg when reading an SSV record like: '2023-01-01 ; "Acme, Inc. " ;
+     1,000'
+     the whole record matcher sees instead: '2023-01-01,Acme, Inc.
+     ,1,000'
+
+  2. Field matchers expect either a CSV field number, or a CSV field
+     name declared with 'fields'.  (Don't use a hledger field name here,
+     unless it is also a CSV field name.)  A non-CSV field name will
+     cause the matcher to match against '""' (the empty string), and
+     does not raise an error, allowing easier reuse of common rules with
+     different CSV files.
+
+   You can also prefix a matcher with '!' (and optional space) to negate
+it.  Eg '! whole foods', '! %3 whole foods', '!%description whole foods'
+will match if "whole foods" is NOT present.  _Added in 1.32._
+
+   The pattern is, as usual in hledger, a POSIX extended regular
+expression that also supports GNU word boundaries ('\b', '\B', '\<',
+'\>') and nothing else.  If you have trouble with it, see "Regular
+expressions" in the hledger manual
+(https://hledger.org/hledger.html#regular-expressions).
+
+* Menu:
+
+* Multiple matchers::
+* Match groups::
+
+
+File: hledger.info,  Node: Multiple matchers,  Next: Match groups,  Up: Matchers
+
+9.15.1 Multiple matchers
+------------------------
+
+When an if block has multiple matchers, each on its own line,
+
+   * By default they are OR'd (any of them can match).
+   * Matcher lines beginning with '&' (or '&&', _since 1.42_) are AND'ed
+     with the matcher above (all in the AND'ed group must match).
+   * Matcher lines beginning with '& !' (_since 1.41_, or '&& !', _since
+     1.42_) are first negated and then AND'ed with the matcher above.
+
+   You can also combine multiple matchers one the same line separated by
+'&&' (AND) or '&& !' (AND NOT). Eg '%description amazon && %date
+2025-01-01' will match only when the description field contains "amazon"
+and the date field contains "2025-01-01".  _Added in 1.42._
+
+
+File: hledger.info,  Node: Match groups,  Prev: Multiple matchers,  Up: Matchers
+
+9.15.2 Match groups
+-------------------
+
+_Added in 1.32_
+
+   Matchers can define match groups: parenthesised portions of the
+regular expression which are available for reference in field
+assignments.  Groups are enclosed in regular parentheses ('(' and ')')
+and can be nested.  Each group is available in field assignments using
+the token '\N', where N is an index into the match groups for this
+conditional block (e.g.  '\1', '\2', etc.).
+
+   Example: Warp credit card payment postings to the beginning of the
+billing period (Month start), to match how they are presented in
+statements, using posting dates:
+
+if %date (....-..)-..
+  comment2 date:\1-01
+
+   Another example: Read the expense account from the CSV field, but
+throw away a prefix:
+
+if %account1 liabilities:family:(expenses:.*)
+    account1 \1
+
+
+File: hledger.info,  Node: if table,  Next: balance-type,  Prev: Matchers,  Up: CSV
+
+9.16 'if' table
+===============
+
+"if tables" are an alternative to if blocks; they can express many
+matchers and field assignments in a more compact tabular format, like
+this:
+
+if,HLEDGERFIELD1,HLEDGERFIELD2,...
+MATCHERA,VALUE1,VALUE2,...
+MATCHERB && MATCHERC,VALUE1,VALUE2,...  (*since 1.42*)
+; Comment line that explains MATCHERD
+MATCHERD,VALUE1,VALUE2,...
+<empty line>
+
+   The first character after 'if' is taken to be this if table's field
+separator.  It is unrelated to the separator used in the CSV file.  It
+should be a non-alphanumeric character like ',' or '|' that does not
+appear anywhere else in the table (it should not be used in field names
+or matchers or values, and it cannot be escaped with a backslash).
+
+   Each line must contain the same number of separators; empty values
+are allowed.  Whitespace can be used in the matcher lines for
+readability (but not in the if line, currently).  You can use the
+comment lines in the table body.  The table must be terminated by an
+empty line (or end of file).
+
+   An if table like the above is interpreted as follows: try all of the
+lines with matchers; whenever a line with matchers succeeds, assign all
+of the values on that line to the corresponding hledger fields; If
+multiple lines match, later lines will override fields assigned by the
+earlier ones - just like the sequence of 'if' blocks would behave.
+
+   If table presented above is equivalent to this sequence of if blocks:
+
+if MATCHERA
+  HLEDGERFIELD1 VALUE1
+  HLEDGERFIELD2 VALUE2
+  ...
+
+if MATCHERB && MATCHERC
+  HLEDGERFIELD1 VALUE1
+  HLEDGERFIELD2 VALUE2
+  ...
+
+; Comment line which explains MATCHERD
+if MATCHERD
+  HLEDGERFIELD1 VALUE1
+  HLEDGERFIELD2 VALUE2
+  ...
+
+   Example:
+
+if,account2,comment
+atm transaction fee,expenses:business:banking,deductible? check it
+%description groceries,expenses:groceries,
+;; Comment line that desribes why this particular date is special
+2023/01/12.*Plumbing LLC,expenses:house:upkeep,emergency plumbing call-out
+
+
+File: hledger.info,  Node: balance-type,  Next: include,  Prev: if table,  Up: CSV
+
+9.17 'balance-type'
+===================
+
+Balance assertions generated by assigning to balanceN are of the simple
+'=' type by default, which is a single-commodity, subaccount-excluding
+assertion.  You may find the subaccount-including variants more useful,
+eg if you have created some virtual subaccounts of checking to help with
+budgeting.  You can select a different type of assertion with the
+'balance-type' rule:
+
+# balance assertions will consider all commodities and all subaccounts
+balance-type ==*
+
+   Here are the balance assertion types for quick reference:
+
+=    single commodity, exclude subaccounts
+=*   single commodity, include subaccounts
+==   multi commodity,  exclude subaccounts
+==*  multi commodity,  include subaccounts
+
+
+File: hledger.info,  Node: include,  Next: Working with CSV,  Prev: balance-type,  Up: CSV
+
+9.18 'include'
+==============
+
+include RULESFILE
+
+   This includes the contents of another CSV rules file at this point.
+'RULESFILE' is an absolute file path or a path relative to the current
+file's directory.  This can be useful for sharing common rules between
+several rules files, eg:
+
+# someaccount.csv.rules
+
+## someaccount-specific rules
+fields   date,description,amount
+account1 assets:someaccount
+account2 expenses:misc
+
+## common rules
+include categorisation.rules
+
+
+File: hledger.info,  Node: Working with CSV,  Next: CSV rules examples,  Prev: include,  Up: CSV
+
+9.19 Working with CSV
+=====================
+
+Some tips:
+
+* Menu:
+
+* Rapid feedback::
+* Valid CSV::
+* File Extension::
+* Reading CSV from standard input::
+* Reading multiple CSV files::
+* Reading files specified by rule::
+* Valid transactions::
+* Deduplicating importing::
+* Setting amounts::
+* Amount signs::
+* Setting currency/commodity::
+* Amount decimal places::
+* Referencing other fields::
+* How CSV rules are evaluated::
+* Well factored rules::
+
+
+File: hledger.info,  Node: Rapid feedback,  Next: Valid CSV,  Up: Working with CSV
+
+9.19.1 Rapid feedback
+---------------------
+
+It's a good idea to get rapid feedback while creating/troubleshooting
+CSV rules.  Here's a good way, using entr from eradman.com/entrproject:
+
+$ ls foo.csv* | entr bash -c 'echo ----; hledger -f foo.csv print desc:SOMEDESC'
+
+   A desc: query (eg) is used to select just one, or a few, transactions
+of interest.  "bash -c" is used to run multiple commands, so we can echo
+a separator each time the command re-runs, making it easier to read the
+output.
+
+
+File: hledger.info,  Node: Valid CSV,  Next: File Extension,  Prev: Rapid feedback,  Up: Working with CSV
+
+9.19.2 Valid CSV
+----------------
+
+Note that hledger will only accept valid CSV conforming to RFC 4180, and
+equivalent SSV and TSV formats (like RFC 4180 but with semicolon or tab
+as separators).  This means, eg:
+
+   * Values may be enclosed in double quotes, or not.  Enclosing in
+     single quotes is not allowed.  (Eg ''A','B'' is rejected.)
+   * When values are enclosed in double quotes, spaces outside the
+     quotes are not allowed.  (Eg '"A", "B"' is rejected.)
+   * When values are not enclosed in quotes, they may not contain double
+     quotes.  (Eg 'A"A, B' is rejected.)
+
+   If your CSV/SSV/TSV is not valid in this sense, you'll need to
+transform it before reading with hledger.  Try using sed, or a more
+permissive CSV parser like python's csv lib.
+
+
+File: hledger.info,  Node: File Extension,  Next: Reading CSV from standard input,  Prev: Valid CSV,  Up: Working with CSV
+
+9.19.3 File Extension
+---------------------
+
+To help hledger choose the CSV file reader and show the right error
+messages (and choose the right field separator character by default),
+it's best if CSV/SSV/TSV files are named with a '.csv', '.ssv' or '.tsv'
+filename extension.  (More about this at Data formats.)
+
+   When reading files with the "wrong" extension, you can ensure the CSV
+reader (and the default field separator) by prefixing the file path with
+'csv:', 'ssv:' or 'tsv:': Eg:
+
+$ hledger -f ssv:foo.dat print
+
+   You can also override the default field separator with a separator
+rule if needed.
+
+
+File: hledger.info,  Node: Reading CSV from standard input,  Next: Reading multiple CSV files,  Prev: File Extension,  Up: Working with CSV
+
+9.19.4 Reading CSV from standard input
+--------------------------------------
+
+You'll need the file format prefix when reading CSV from stdin also,
+since hledger assumes journal format by default.  Eg:
+
+$ cat foo.dat | hledger -f ssv:- print
+
+
+File: hledger.info,  Node: Reading multiple CSV files,  Next: Reading files specified by rule,  Prev: Reading CSV from standard input,  Up: Working with CSV
+
+9.19.5 Reading multiple CSV files
+---------------------------------
+
+If you use multiple '-f' options to read multiple CSV files at once,
+hledger will look for a correspondingly-named rules file for each CSV
+file.  But if you specify a rules file with '--rules', that rules file
+will be used for all the CSV files.
+
+
+File: hledger.info,  Node: Reading files specified by rule,  Next: Valid transactions,  Prev: Reading multiple CSV files,  Up: Working with CSV
+
+9.19.6 Reading files specified by rule
+--------------------------------------
+
+Instead of specifying a CSV file in the command line, you can specify a
+rules file, as in 'hledger -f foo.csv.rules CMD'.  By default this will
+read data from foo.csv in the same directory, but you can add a source
+rule to specify a different data file, perhaps located in your web
+browser's download directory.
+
+   This feature was added in hledger 1.30, so you won't see it in most
+CSV rules examples.  But it helps remove some of the busywork of
+managing CSV downloads.  Most of your financial institutions's default
+CSV filenames are different and can be recognised by a glob pattern.  So
+you can put a rule like 'source Checking1*.csv' in
+foo-checking.csv.rules, and then periodically follow a workflow like:
+
+  1. Download CSV from Foo's website, using your browser's defaults
+  2. Run 'hledger import foo-checking.csv.rules' to import any new
+     transactions
+
+   After import, you can: discard the CSV, or leave it where it is for a
+while, or move it into your archives, as you prefer.  If you do nothing,
+next time your browser will save something like Checking1-2.csv, and
+hledger will use that because of the '*' wild card and because it is the
+most recent.
+
+
+File: hledger.info,  Node: Valid transactions,  Next: Deduplicating importing,  Prev: Reading files specified by rule,  Up: Working with CSV
+
+9.19.7 Valid transactions
+-------------------------
+
+After reading a CSV file, hledger post-processes and validates the
+generated journal entries as it would for a journal file - balancing
+them, applying balance assignments, and canonicalising amount styles.
+Any errors at this stage will be reported in the usual way, displaying
+the problem entry.
+
+   There is one exception: balance assertions, if you have generated
+them, will not be checked, since normally these will work only when the
+CSV data is part of the main journal.  If you do need to check balance
+assertions generated from CSV right away, pipe into another hledger:
+
+$ hledger -f file.csv print | hledger -f- print
+
+
+File: hledger.info,  Node: Deduplicating importing,  Next: Setting amounts,  Prev: Valid transactions,  Up: Working with CSV
+
+9.19.8 Deduplicating, importing
+-------------------------------
+
+When you download a CSV file periodically, eg to get your latest bank
+transactions, the new file may overlap with the old one, containing some
+of the same records.
+
+   The import command will (a) detect the new transactions, and (b)
+append just those transactions to your main journal.  It is idempotent,
+so you don't have to remember how many times you ran it or with which
+version of the CSV. (It keeps state in a hidden '.latest.FILE.csv'
+file.)  This is the easiest way to import CSV data.  Eg:
+
+# download the latest CSV files, then run this command.
+# Note, no -f flags needed here.
+$ hledger import *.csv [--dry]
+
+   This method works for most CSV files.  (Where records have a stable
+chronological order, and new records appear only at the new end.)
+
+   A number of other tools and workflows, hledger-specific and
+otherwise, exist for converting, deduplicating, classifying and managing
+CSV data.  See:
+
+   * https://hledger.org/cookbook.html#setups-and-workflows
+   * https://plaintextaccounting.org -> data import/conversion
+
+
+File: hledger.info,  Node: Setting amounts,  Next: Amount signs,  Prev: Deduplicating importing,  Up: Working with CSV
+
+9.19.9 Setting amounts
+----------------------
+
+Continuing from amount field above, here are more tips for
+amount-setting:
+
+  1. *If the amount is in a single CSV field:*
+
+       a. *If its sign indicates direction of flow:*
+          Assign it to 'amountN', to set the Nth posting's amount.  N is
+          usually 1 or 2 but can go up to 99.
+
+       b. *If another field indicates direction of flow:*
+          Use one or more conditional rules to set the appropriate
+          amount sign.  Eg:
+
+     # assume a withdrawal unless Type contains "deposit":
+     amount1  -%Amount
+     if %Type deposit
+       amount1  %Amount
+
+  2. *If the amount is in two CSV fields (such as Debit and Credit, or
+     In and Out):*
+
+       a. *If both fields are unsigned:*
+          Assign one field to 'amountN-in' and the other to
+          'amountN-out'.  hledger will automatically negate the "out"
+          field, and will use whichever field value is non-zero as
+          posting N's amount.
+
+       b. *If either field is signed:*
+          You will probably need to override hledger's sign for one or
+          the other field, as in the following example:
+
+     # Negate the -out value, but only if it is not empty:
+     fields date, description, amount1-in, amount1-out
+     if %amount1-out [1-9]
+      amount1-out -%amount1-out
+
+       c. *If both fields can contain a non-zero value (or both can be
+          empty):*
+          The -in/-out rules normally choose the value which is
+          non-zero/non-empty.  Some value pairs can be ambiguous, such
+          as '1' and 'none'.  For such cases, use conditional rules to
+          help select the amount.  Eg, to handle the above you could
+          select the value containing non-zero digits:
+
+     fields date, description, in, out
+     if %in [1-9]
+      amount1 %in
+     if %out [1-9]
+      amount1 %out
+
+  3. *If you want posting 2's amount converted to cost:*
+     Use the unnumbered 'amount' (or 'amount-in' and 'amount-out')
+     syntax.
+
+  4. *If the CSV has only balance amounts, not transaction amounts:*
+     Assign to 'balanceN', to set a balance assignment on the Nth
+     posting, causing the posting's amount to be calculated
+     automatically.  'balance' with no number is equivalent to
+     'balance1'.  In this situation hledger is more likely to guess the
+     wrong default account name, so you may need to set that explicitly.
+
+
+File: hledger.info,  Node: Amount signs,  Next: Setting currency/commodity,  Prev: Setting amounts,  Up: Working with CSV
+
+9.19.10 Amount signs
+--------------------
+
+There is some special handling making it easier to parse and to reverse
+amount signs.  (This only works for whole amounts, not for cost amounts
+such as COST in 'amount1 AMT @ COST'):
+
+   * *If an amount value begins with a plus sign:*
+     that will be removed: '+AMT' becomes 'AMT'
+
+   * *If an amount value is parenthesised:*
+     it will be de-parenthesised and sign-flipped: '(AMT)' becomes
+     '-AMT'
+
+   * *If an amount value has two minus signs (or two sets of
+     parentheses, or a minus sign and parentheses):*
+     they cancel out and will be removed: '--AMT' or '-(AMT)' becomes
+     'AMT'
+
+   * *If an amount value contains just a sign (or just a set of
+     parentheses):*
+     that is removed, making it an empty value.  '"+"' or '"-"' or
+     '"()"' becomes '""'.
+
+   It's not possible (without preprocessing the CSV) to set an amount to
+its absolute value, ie discard its sign.
+
+
+File: hledger.info,  Node: Setting currency/commodity,  Next: Amount decimal places,  Prev: Amount signs,  Up: Working with CSV
+
+9.19.11 Setting currency/commodity
+----------------------------------
+
+If the currency/commodity symbol is included in the CSV's amount
+field(s):
+
+2023-01-01,foo,$123.00
+
+   you don't have to do anything special for the commodity symbol, it
+will be assigned as part of the amount.  Eg:
+
+fields date,description,amount
+
+2023-01-01 foo
+    expenses:unknown         $123.00
+    income:unknown          $-123.00
+
+   If the currency is provided as a separate CSV field:
+
+2023-01-01,foo,USD,123.00
+
+   You can assign that to the 'currency' pseudo-field, which has the
+special effect of prepending itself to every amount in the transaction
+(on the left, with no separating space):
+
+fields date,description,currency,amount
+
+2023-01-01 foo
+    expenses:unknown       USD123.00
+    income:unknown        USD-123.00
+
+   Or, you can use a field assignment to construct the amount yourself,
+with more control.  Eg to put the symbol on the right, and separated by
+a space:
+
+fields date,description,cur,amt
+amount %amt %cur
+
+2023-01-01 foo
+    expenses:unknown        123.00 USD
+    income:unknown         -123.00 USD
+
+   Note we used a temporary field name ('cur') that is not 'currency' -
+that would trigger the prepending effect, which we don't want here.
+
+
+File: hledger.info,  Node: Amount decimal places,  Next: Referencing other fields,  Prev: Setting currency/commodity,  Up: Working with CSV
+
+9.19.12 Amount decimal places
+-----------------------------
+
+When you are reading CSV data, eg with a command like 'hledger -f
+foo.csv print', hledger will infer each commodity's decimal precision
+(and other commodity display styles) from the amounts - much as when
+reading a journal file without 'commodity' directives (see the link).
+
+   Note, the commodity styles are not inferred from the numbers in the
+original CSV data; rather, they are inferred from the amounts generated
+by the CSV rules.
+
+   When you are importing CSV data with the 'import' command, eg
+'hledger import foo.csv', there's another step: 'import' tries to make
+the new entries conform to the journal's existing styles.  So for each
+commodity - let's say it's EUR - 'import' will choose:
+
+  1. the style declared for EUR by a 'commodity' directive in the
+     journal
+  2. otherwise, the style inferred from EUR amounts in the journal
+  3. otherwise, the style inferred from EUR amounts generated by the CSV
+     rules.
+
+   TLDR: if 'import' is not generating the precisions or styles you
+want, add a 'commodity' directive to specify them.
+
+
+File: hledger.info,  Node: Referencing other fields,  Next: How CSV rules are evaluated,  Prev: Amount decimal places,  Up: Working with CSV
+
+9.19.13 Referencing other fields
+--------------------------------
+
+In field assignments, you can interpolate only CSV fields, not hledger
+fields.  In the example below, there's both a CSV field and a hledger
+field named amount1, but %amount1 always means the CSV field, not the
+hledger field:
+
+# Name the third CSV field "amount1"
+fields date,description,amount1
+
+# Set hledger's amount1 to the CSV amount1 field followed by USD
+amount1 %amount1 USD
+
+# Set comment to the CSV amount1 (not the amount1 assigned above)
+comment %amount1
+
+   Here, since there's no CSV amount1 field, %amount1 will produce a
+literal "amount1":
+
+fields date,description,csvamount
+amount1 %csvamount USD
+# Can't interpolate amount1 here
+comment %amount1
+
+   When there are multiple field assignments to the same hledger field,
+only the last one takes effect.  Here, comment's value will be be B, or
+C if "something" is matched, but never A:
+
+comment A
+comment B
+if something
+ comment C
+
+
+File: hledger.info,  Node: How CSV rules are evaluated,  Next: Well factored rules,  Prev: Referencing other fields,  Up: Working with CSV
+
+9.19.14 How CSV rules are evaluated
+-----------------------------------
+
+Here's how to think of CSV rules being evaluated (if you really need
+to).  First,
+
+   * 'include' - all includes are inlined, from top to bottom, depth
+     first.  (At each include point the file is inlined and scanned for
+     further includes, recursively, before proceeding.)
+
+   Then "global" rules are evaluated, top to bottom.  If a rule is
+repeated, the last one wins:
+
+   * 'skip' (at top level)
+   * 'date-format'
+   * 'newest-first'
+   * 'fields' - names the CSV fields, optionally sets up initial
+     assignments to hledger fields
+
+   Then for each CSV record in turn:
+
+   * test all 'if' blocks.  If any of them contain a 'end' rule, skip
+     all remaining CSV records.  Otherwise if any of them contain a
+     'skip' rule, skip that many CSV records.  If there are multiple
+     matched 'skip' rules, the first one wins.
+   * collect all field assignments at top level and in matched 'if'
+     blocks.  When there are multiple assignments for a field, keep only
+     the last one.
+   * compute a value for each hledger field - either the one that was
+     assigned to it (and interpolate the %CSVFIELD references), or a
+     default
+   * generate a hledger transaction (journal entry) from these values.
+
+   This is all part of the CSV reader, one of several readers hledger
+can use to parse input files.  When all files have been read
+successfully, the transactions are passed as input to whichever hledger
+command the user specified.
+
+
+File: hledger.info,  Node: Well factored rules,  Prev: How CSV rules are evaluated,  Up: Working with CSV
+
+9.19.15 Well factored rules
+---------------------------
+
+Some things than can help reduce duplication and complexity in rules
+files:
+
+   * Extracting common rules usable with multiple CSV files into a
+     'common.rules', and adding 'include common.rules' to each CSV's
+     rules file.
+
+   * Splitting if blocks into smaller if blocks, extracting the
+     frequently used parts.
+
+
+File: hledger.info,  Node: CSV rules examples,  Prev: Working with CSV,  Up: CSV
+
+9.20 CSV rules examples
+=======================
+
+* Menu:
+
+* Bank of Ireland::
+* Coinbase::
+* Amazon::
+* Paypal::
+
+
+File: hledger.info,  Node: Bank of Ireland,  Next: Coinbase,  Up: CSV rules examples
+
+9.20.1 Bank of Ireland
+----------------------
+
+Here's a CSV with two amount fields (Debit and Credit), and a balance
+field, which we can use to add balance assertions, which is not
+necessary but provides extra error checking:
+
+Date,Details,Debit,Credit,Balance
+07/12/2012,LODGMENT       529898,,10.0,131.21
+07/12/2012,PAYMENT,5,,126
+
+# bankofireland-checking.csv.rules
+
+# skip the header line
+skip
+
+# name the csv fields, and assign some of them as journal entry fields
+fields  date, description, amount-out, amount-in, balance
+
+# We generate balance assertions by assigning to "balance"
+# above, but you may sometimes need to remove these because:
+#
+# - the CSV balance differs from the true balance,
+#   by up to 0.0000000000005 in my experience
+#
+# - it is sometimes calculated based on non-chronological ordering,
+#   eg when multiple transactions clear on the same day
+
+# date is in UK/Ireland format
+date-format  %d/%m/%Y
+
+# set the currency
+currency  EUR
+
+# set the base account for all txns
+account1  assets:bank:boi:checking
+
+$ hledger -f bankofireland-checking.csv print
+2012-12-07 LODGMENT       529898
+    assets:bank:boi:checking         EUR10.0 = EUR131.2
+    income:unknown                  EUR-10.0
+
+2012-12-07 PAYMENT
+    assets:bank:boi:checking         EUR-5.0 = EUR126.0
+    expenses:unknown                  EUR5.0
+
+   The balance assertions don't raise an error above, because we're
+reading directly from CSV, but they will be checked if these entries are
+imported into a journal file.
+
+
+File: hledger.info,  Node: Coinbase,  Next: Amazon,  Prev: Bank of Ireland,  Up: CSV rules examples
+
+9.20.2 Coinbase
+---------------
+
+A simple example with some CSV from Coinbase.  The spot price is
+recorded using cost notation.  The legacy 'amount' field name
+conveniently sets amount 2 (posting 2's amount) to the total cost.
+
+# Timestamp,Transaction Type,Asset,Quantity Transacted,Spot Price Currency,Spot Price at Transaction,Subtotal,Total (inclusive of fees and/or spread),Fees and/or Spread,Notes
+# 2021-12-30T06:57:59Z,Receive,USDC,100,GBP,0.740000,"","","","Received 100.00 USDC from an external account"
+
+# coinbase.csv.rules
+skip         1
+fields       Timestamp,Transaction_Type,Asset,Quantity_Transacted,Spot_Price_Currency,Spot_Price_at_Transaction,Subtotal,Total,Fees_Spread,Notes
+date         %Timestamp
+date-format  %Y-%m-%dT%T%Z
+description  %Notes
+account1     assets:coinbase:cc
+amount       %Quantity_Transacted %Asset @ %Spot_Price_at_Transaction %Spot_Price_Currency
+
+$ hledger print -f coinbase.csv
+2021-12-30 Received 100.00 USDC from an external account
+    assets:coinbase:cc    100 USDC @ 0.740000 GBP
+    income:unknown                 -74.000000 GBP
+
+
+File: hledger.info,  Node: Amazon,  Next: Paypal,  Prev: Coinbase,  Up: CSV rules examples
+
+9.20.3 Amazon
+-------------
+
+Here we convert amazon.com order history, and use an if block to
+generate a third posting if there's a fee.  (In practice you'd probably
+get this data from your bank instead, but it's an example.)
+
+"Date","Type","To/From","Name","Status","Amount","Fees","Transaction ID"
+"Jul 29, 2012","Payment","To","Foo.","Completed","$20.00","$0.00","16000000000000DGLNJPI1P9B8DKPVHL"
+"Jul 30, 2012","Payment","To","Adapteva, Inc.","Completed","$25.00","$1.00","17LA58JSKRD4HDGLNJPI1P9B8DKPVHL"
+
+# amazon-orders.csv.rules
+
+# skip one header line
+skip 1
+
+# name the csv fields, and assign the transaction's date, amount and code.
+# Avoided the "status" and "amount" hledger field names to prevent confusion.
+fields date, _, toorfrom, name, amzstatus, amzamount, fees, code
+
+# how to parse the date
+date-format %b %-d, %Y
+
+# combine two fields to make the description
+description %toorfrom %name
+
+# save the status as a tag
+comment     status:%amzstatus
+
+# set the base account for all transactions
+account1    assets:amazon
+# leave amount1 blank so it can balance the other(s).
+# I'm assuming amzamount excludes the fees, don't remember
+
+# set a generic account2
+account2    expenses:misc
+amount2     %amzamount
+# and maybe refine it further:
+#include categorisation.rules
+
+# add a third posting for fees, but only if they are non-zero.
+if %fees [1-9]
+ account3    expenses:fees
+ amount3     %fees
+
+$ hledger -f amazon-orders.csv print
+2012-07-29 (16000000000000DGLNJPI1P9B8DKPVHL) To Foo.  ; status:Completed
+    assets:amazon
+    expenses:misc          $20.00
+
+2012-07-30 (17LA58JSKRD4HDGLNJPI1P9B8DKPVHL) To Adapteva, Inc.  ; status:Completed
+    assets:amazon
+    expenses:misc          $25.00
+    expenses:fees           $1.00
+
+
+File: hledger.info,  Node: Paypal,  Prev: Amazon,  Up: CSV rules examples
+
+9.20.4 Paypal
+-------------
+
+Here's a real-world rules file for (customised) Paypal CSV, with some
+Paypal-specific rules, and a second rules file included:
+
+"Date","Time","TimeZone","Name","Type","Status","Currency","Gross","Fee","Net","From Email Address","To Email Address","Transaction ID","Item Title","Item ID","Reference Txn ID","Receipt ID","Balance","Note"
+"10/01/2019","03:46:20","PDT","Calm Radio","Subscription Payment","Completed","USD","-6.99","0.00","-6.99","simon@joyful.com","memberships@calmradio.com","60P57143A8206782E","MONTHLY - $1 for the first 2 Months: Me - Order 99309. Item total: $1.00 USD first 2 months, then $6.99 / Month","","I-R8YLY094FJYR","","-6.99",""
+"10/01/2019","03:46:20","PDT","","Bank Deposit to PP Account ","Pending","USD","6.99","0.00","6.99","","simon@joyful.com","0TU1544T080463733","","","60P57143A8206782E","","0.00",""
+"10/01/2019","08:57:01","PDT","Patreon","PreApproved Payment Bill User Payment","Completed","USD","-7.00","0.00","-7.00","simon@joyful.com","support@patreon.com","2722394R5F586712G","Patreon* Membership","","B-0PG93074E7M86381M","","-7.00",""
+"10/01/2019","08:57:01","PDT","","Bank Deposit to PP Account ","Pending","USD","7.00","0.00","7.00","","simon@joyful.com","71854087RG994194F","Patreon* Membership","","2722394R5F586712G","","0.00",""
+"10/19/2019","03:02:12","PDT","Wikimedia Foundation, Inc.","Subscription Payment","Completed","USD","-2.00","0.00","-2.00","simon@joyful.com","tle@wikimedia.org","K9U43044RY432050M","Monthly donation to the Wikimedia Foundation","","I-R5C3YUS3285L","","-2.00",""
+"10/19/2019","03:02:12","PDT","","Bank Deposit to PP Account ","Pending","USD","2.00","0.00","2.00","","simon@joyful.com","3XJ107139A851061F","","","K9U43044RY432050M","","0.00",""
+"10/22/2019","05:07:06","PDT","Noble Benefactor","Subscription Payment","Completed","USD","10.00","-0.59","9.41","noble@bene.fac.tor","simon@joyful.com","6L8L1662YP1334033","Joyful Systems","","I-KC9VBGY2GWDB","","9.41",""
+
+# paypal-custom.csv.rules
+
+# Tips:
+# Export from Activity -> Statements -> Custom -> Activity download
+# Suggested transaction type: "Balance affecting"
+# Paypal's default fields in 2018 were:
+# "Date","Time","TimeZone","Name","Type","Status","Currency","Gross","Fee","Net","From Email Address","To Email Address","Transaction ID","Shipping Address","Address Status","Item Title","Item ID","Shipping and Handling Amount","Insurance Amount","Sales Tax","Option 1 Name","Option 1 Value","Option 2 Name","Option 2 Value","Reference Txn ID","Invoice Number","Custom Number","Quantity","Receipt ID","Balance","Address Line 1","Address Line 2/District/Neighborhood","Town/City","State/Province/Region/County/Territory/Prefecture/Republic","Zip/Postal Code","Country","Contact Phone Number","Subject","Note","Country Code","Balance Impact"
+# This rules file assumes the following more detailed fields, configured in "Customize report fields":
+# "Date","Time","TimeZone","Name","Type","Status","Currency","Gross","Fee","Net","From Email Address","To Email Address","Transaction ID","Item Title","Item ID","Reference Txn ID","Receipt ID","Balance","Note"
+
+fields date, time, timezone, description_, type, status_, currency, grossamount, feeamount, netamount, fromemail, toemail, code, itemtitle, itemid, referencetxnid, receiptid, balance, note
+
+skip  1
+
+date-format  %-m/%-d/%Y
+
+# ignore some paypal events
+if
+In Progress
+Temporary Hold
+Update to
+ skip
+
+# add more fields to the description
+description %description_ %itemtitle
+
+# save some other fields as tags
+comment  itemid:%itemid, fromemail:%fromemail, toemail:%toemail, time:%time, type:%type, status:%status_
+
+# convert to short currency symbols
+if %currency USD
+ currency $
+if %currency EUR
+ currency E
+if %currency GBP
+ currency P
+
+# generate postings
+
+# the first posting will be the money leaving/entering my paypal account
+# (negative means leaving my account, in all amount fields)
+account1 assets:online:paypal
+amount1  %netamount
+
+# the second posting will be money sent to/received from other party
+# (account2 is set below)
+amount2  -%grossamount
+
+# if there's a fee, add a third posting for the money taken by paypal.
+if %feeamount [1-9]
+ account3 expenses:banking:paypal
+ amount3  -%feeamount
+ comment3 business:
+
+# choose an account for the second posting
+
+# override the default account names:
+# if the amount is positive, it's income (a debit)
+if %grossamount ^[^-]
+ account2 income:unknown
+# if negative, it's an expense (a credit)
+if %grossamount ^-
+ account2 expenses:unknown
+
+# apply common rules for setting account2 & other tweaks
+include common.rules
+
+# apply some overrides specific to this csv
+
+# Transfers from/to bank. These are usually marked Pending,
+# which can be disregarded in this case.
+if
+Bank Account
+Bank Deposit to PP Account
+ description %type for %referencetxnid %itemtitle
+ account2 assets:bank:wf:pchecking
+ account1 assets:online:paypal
+
+# Currency conversions
+if Currency Conversion
+ account2 equity:currency conversion
+
+# common.rules
+
+if
+darcs
+noble benefactor
+ account2 revenues:foss donations:darcshub
+ comment2 business:
+
+if
+Calm Radio
+ account2 expenses:online:apps
+
+if
+electronic frontier foundation
+Patreon
+wikimedia
+Advent of Code
+ account2 expenses:dues
+
+if Google
+ account2 expenses:online:apps
+ description google | music
+
+$ hledger -f paypal-custom.csv  print
+2019-10-01 (60P57143A8206782E) Calm Radio MONTHLY - $1 for the first 2 Months: Me - Order 99309. Item total: $1.00 USD first 2 months, then $6.99 / Month  ; itemid:, fromemail:simon@joyful.com, toemail:memberships@calmradio.com, time:03:46:20, type:Subscription Payment, status:Completed
+    assets:online:paypal          $-6.99 = $-6.99
+    expenses:online:apps           $6.99
+
+2019-10-01 (0TU1544T080463733) Bank Deposit to PP Account for 60P57143A8206782E  ; itemid:, fromemail:, toemail:simon@joyful.com, time:03:46:20, type:Bank Deposit to PP Account, status:Pending
+    assets:online:paypal               $6.99 = $0.00
+    assets:bank:wf:pchecking          $-6.99
+
+2019-10-01 (2722394R5F586712G) Patreon Patreon* Membership  ; itemid:, fromemail:simon@joyful.com, toemail:support@patreon.com, time:08:57:01, type:PreApproved Payment Bill User Payment, status:Completed
+    assets:online:paypal          $-7.00 = $-7.00
+    expenses:dues                  $7.00
+
+2019-10-01 (71854087RG994194F) Bank Deposit to PP Account for 2722394R5F586712G Patreon* Membership  ; itemid:, fromemail:, toemail:simon@joyful.com, time:08:57:01, type:Bank Deposit to PP Account, status:Pending
+    assets:online:paypal               $7.00 = $0.00
+    assets:bank:wf:pchecking          $-7.00
+
+2019-10-19 (K9U43044RY432050M) Wikimedia Foundation, Inc. Monthly donation to the Wikimedia Foundation  ; itemid:, fromemail:simon@joyful.com, toemail:tle@wikimedia.org, time:03:02:12, type:Subscription Payment, status:Completed
+    assets:online:paypal             $-2.00 = $-2.00
+    expenses:dues                     $2.00
+    expenses:banking:paypal      ; business:
+
+2019-10-19 (3XJ107139A851061F) Bank Deposit to PP Account for K9U43044RY432050M  ; itemid:, fromemail:, toemail:simon@joyful.com, time:03:02:12, type:Bank Deposit to PP Account, status:Pending
+    assets:online:paypal               $2.00 = $0.00
+    assets:bank:wf:pchecking          $-2.00
+
+2019-10-22 (6L8L1662YP1334033) Noble Benefactor Joyful Systems  ; itemid:, fromemail:noble@bene.fac.tor, toemail:simon@joyful.com, time:05:07:06, type:Subscription Payment, status:Completed
+    assets:online:paypal                       $9.41 = $9.41
+    revenues:foss donations:darcshub         $-10.00  ; business:
+    expenses:banking:paypal                    $0.59  ; business:
+
+
+File: hledger.info,  Node: Timeclock,  Next: Timedot,  Prev: CSV,  Up: Top
+
+10 Timeclock
+************
+
+The time logging format of timeclock.el, as read by hledger.
+
+   hledger can read time logs in timeclock format.  As with Ledger,
+these are (a subset of) timeclock.el's format, containing clock-in and
+clock-out entries as in the example below.  The date is a simple date.
+The time format is HH:MM[:SS][+-ZZZZ]. Seconds and timezone are
+optional.  The timezone, if present, must be four digits and is ignored
+(currently the time is always interpreted as a local time).  Lines
+beginning with '#' or ';' or '*', and blank lines, are ignored.
+
+i 2015/03/30 09:00:00 some account  optional description after 2 spaces ; optional comment, tags:
+o 2015/03/30 09:20:00
+i 2015/03/31 22:21:45 another:account
+o 2015/04/01 02:00:34
+
+   hledger treats each clock-in/clock-out pair as a transaction posting
+some number of hours to an account.  Or if the session spans more than
+one day, it is split into several transactions, one for each day.  For
+the above time log, 'hledger print' generates these journal entries:
+
+$ hledger -f t.timeclock print
+2015-03-30 * optional description after 2 spaces   ; optional comment, tags:
+    (some account)           0.33h
+
+2015-03-31 * 22:21-23:59
+    (another:account)           1.64h
+
+2015-04-01 * 00:00-02:00
+    (another:account)           2.01h
+
+   Here is a sample.timeclock to download and some queries to try:
+
+$ hledger -f sample.timeclock balance                               # current time balances
+$ hledger -f sample.timeclock register -p 2009/3                    # sessions in march 2009
+$ hledger -f sample.timeclock register -p weekly --depth 1 --empty  # time summary by week
+
+   To generate time logs, ie to clock in and clock out, you could:
+
+   * use these shell aliases at the command line:
+
+     alias ti='echo i `date "+%Y-%m-%d %H:%M:%S"` $* >>$TIMELOG'
+     alias to='echo o `date "+%Y-%m-%d %H:%M:%S"` >>$TIMELOG'
+
+   * or Emacs's built-in timeclock.el, or the extended timeclock-x.el,
+     and perhaps the extras in ledgerutils.el
+
+   * or use the old 'ti' and 'to' scripts in the ledger 2.x repository.
+     These rely on a "timeclock" executable which I think is just the
+     ledger 2 executable renamed.
+
+
+File: hledger.info,  Node: Timedot,  Next: PART 3 REPORTING CONCEPTS,  Prev: Timeclock,  Up: Top
+
+11 Timedot
+**********
+
+'timedot' format is hledger's human-friendly time logging format.
+Compared to 'timeclock' format, it is more convenient for quick,
+approximate, and retroactive time logging, and more human-readable (you
+can see at a glance where time was spent).  A quick example:
+
+2023-05-01
+hom:errands          .... ....  ; two hours; the space is ignored
+fos:hledger:timedot  ..         ; half an hour
+per:admin:finance               ; no time spent yet
+
+   hledger reads this as a transaction on this day with three
+(unbalanced) postings, where each dot represents "0.25".  No commodity
+symbol is assumed, but we typically interpret it as hours.
+
+$ hledger -f a.timedot print   # .timedot file extension (or timedot: prefix) is required
+2023-05-01 *
+    (hom:errands)                    2.00  ; two hours
+    (fos:hledger:timedot)            0.50  ; half an hour
+    (per:admin:finance)                 0
+
+   A timedot file contains a series of transactions (usually one per
+day).  Each begins with a *simple date* (Y-M-D, Y/M/D, or Y.M.D),
+optionally be followed on the same line by a transaction description,
+and/or a transaction comment following a semicolon.
+
+   After the date line are zero or more time postings, consisting of:
+
+   * *An account name* - any hledger-style account name, optionally
+     indented.
+
+   * *Two or more spaces* - required if there is an amount (as in
+     journal format).
+
+   * *A timedot amount*, which can be
+
+        * empty (representing zero)
+
+        * a number, optionally followed by a unit 's', 'm', 'h', 'd',
+          'w', 'mo', or 'y', representing a precise number of seconds,
+          minutes, hours, days weeks, months or years (hours is assumed
+          by default), which will be converted to hours according to 60s
+          = 1m, 60m = 1h, 24h = 1d, 7d = 1w, 30d = 1mo, 365d = 1y.
+
+        * one or more dots (period characters), each representing 0.25.
+          These are the dots in "timedot".  Spaces are ignored and can
+          be used for grouping/alignment.
+
+        * _Added in 1.32_ one or more letters.  These are like dots but
+          they also generate a tag 't:' (short for "type") with the
+          letter as its value, and a separate posting for each of the
+          values.  This provides a second dimension of categorisation,
+          viewable in reports with '--pivot t'.
+
+   * *An optional comment* following a semicolon (a hledger-style
+     posting comment).
+
+   There is some flexibility to help with keeping time log data and
+notes in the same file:
+
+   * Blank lines and lines beginning with '#' or ';' are ignored.
+
+   * After the first date line, lines which do not contain a double
+     space are parsed as postings with zero amount.  (hledger's register
+     reports will show these if you add -E).
+
+   * Before the first date line, lines beginning with '*' (eg org
+     headings) are ignored.  And from the first date line onward, Emacs
+     org mode heading prefixes at the start of lines (one or more '*''s
+     followed by a space) will be ignored.  This means the time log can
+     also be a org outline.
+
+   Timedot files don't support directives like journal files.  So a
+common pattern is to have a main journal file (eg 'time.journal') that
+contains any needed directives, and then includes the timedot file
+('include time.timedot').
+
+* Menu:
+
+* Timedot examples::
+
+
+File: hledger.info,  Node: Timedot examples,  Up: Timedot
+
+11.1 Timedot examples
+=====================
+
+Numbers:
+
+2016/2/3
+inc:client1   4
+fos:hledger   3h
+biz:research  60m
+
+   Dots:
+
+# on this day, 6h was spent on client work, 1.5h on haskell FOSS work, etc.
+2016/2/1
+inc:client1   .... .... .... .... .... ....
+fos:haskell   .... ..
+biz:research  .
+
+2016/2/2
+inc:client1   .... ....
+biz:research  .
+
+$ hledger -f a.timedot print date:2016/2/2
+2016-02-02 *
+    (inc:client1)          2.00
+
+2016-02-02 *
+    (biz:research)          0.25
+
+$ hledger -f a.timedot bal --daily --tree
+Balance changes in 2016-02-01-2016-02-03:
+
+            ||  2016-02-01d  2016-02-02d  2016-02-03d 
+============++========================================
+ biz        ||         0.25         0.25         1.00 
+   research ||         0.25         0.25         1.00 
+ fos        ||         1.50            0         3.00 
+   haskell  ||         1.50            0            0 
+   hledger  ||            0            0         3.00 
+ inc        ||         6.00         2.00         4.00 
+   client1  ||         6.00         2.00         4.00 
+------------++----------------------------------------
+            ||         7.75         2.25         8.00 
+
+   Letters:
+
+# Activity types:
+#  c cleanup/catchup/repair
+#  e enhancement
+#  s support
+#  l learning/research
+
+2023-11-01
+work:adm  ccecces
+
+$ hledger -f a.timedot print
+2023-11-01
+    (work:adm)  1     ; t:c
+    (work:adm)  0.5   ; t:e
+    (work:adm)  0.25  ; t:s
+
+$ hledger -f a.timedot bal
+                1.75  work:adm
+--------------------
+                1.75  
+
+$ hledger -f a.timedot bal --pivot t
+                1.00  c
+                0.50  e
+                0.25  s
+--------------------
+                1.75  
+
+   Org:
+
+* 2023 Work Diary
+** Q1
+*** 2023-02-29
+**** DONE
+0700 yoga
+**** UNPLANNED
+**** BEGUN
+hom:chores
+ cleaning  ...
+ water plants
+  outdoor - one full watering can
+  indoor - light watering
+**** TODO
+adm:planning: trip
+*** LATER
+
+   Using '.' as account name separator:
+
+2016/2/4
+fos.hledger.timedot  4h
+fos.ledger           ..
+
+$ hledger -f a.timedot --alias '/\./=:' bal -t
+                4.50  fos
+                4.00    hledger:timedot
+                0.50    ledger
+--------------------
+                4.50
+
+
+File: hledger.info,  Node: PART 3 REPORTING CONCEPTS,  Next: Time periods,  Prev: Timedot,  Up: Top
+
+12 PART 3: REPORTING CONCEPTS
+*****************************
+
+
+File: hledger.info,  Node: Time periods,  Next: Depth,  Prev: PART 3 REPORTING CONCEPTS,  Up: Top
+
+13 Time periods
+***************
+
+* Menu:
+
+* Report start & end date::
+* Smart dates::
+* Report intervals::
+* Date adjustments::
+* Period headings::
+* Period expressions::
+
+
+File: hledger.info,  Node: Report start & end date,  Next: Smart dates,  Up: Time periods
+
+13.1 Report start & end date
+============================
+
+Most hledger reports will by default show the full time period
+represented by the journal.  The report start date will be the earliest
+transaction or posting date, and the report end date will be the latest
+transaction, posting, or market price date.
+
+   Often you will want to see a shorter period, such as the current
+month.  You can specify a start and/or end date with the '-b/--begin',
+'-e/--end', or '-p/--period' options, or a 'date:' query argument,
+described below.  All of these accept the smart date syntax, also
+described below.
+
+   End dates are exclusive; specify the day after the last day you want
+to see in the report.
+
+   When dates are specified by multiple options, the last (right-most)
+option wins.  And when 'date:' queries and date options are combined,
+the report period will be their intersection.
+
+   Examples:
+
+'-b 2016/3/17'
+
+     beginning on St.  Patrick's day 2016
+'-e 12/1'
+
+     ending at the start of December 1st in the current year
+'-p 'this month''
+
+     during the current month
+'-p thismonth'
+
+     same as above, spaces are optional
+'-b 2023'
+
+     beginning on the first day of 2023
+'date:2023..' or 'date:2023-'
+
+     same as above
+
+   '-b 2024 -e 2025 -p '2000 to 2030' date:2020-01 date:2020' :
+during January 2020 (the smallest common period, with the -p overriding
+-b and -e)
+
+
+File: hledger.info,  Node: Smart dates,  Next: Report intervals,  Prev: Report start & end date,  Up: Time periods
+
+13.2 Smart dates
+================
+
+In hledger's user interfaces (though not in the journal file), you can
+optionally use "smart date" syntax.  Smart dates can be written with
+english words, can be relative, and can have parts omitted.  Missing
+parts are inferred as 1, when needed.  Smart dates can be interpreted as
+dates or periods depending on context.
+
+   Examples:
+
+   '2004-01-01', '2004/10/1', '2004.9.1', '20240504' :
+Exact dates.  The year must have at least four digits, the month must be
+1-12, the day must be 1-31, the separator can be '-' or '/' or '.' or
+nothing.
+
+'2004-10'
+
+     start of month
+'2004'
+
+     start of year
+'10/1' or 'oct' or 'october'
+
+     October 1st in current year
+'21'
+
+     21st day in current month
+'yesterday, today, tomorrow'
+
+     -1, 0, 1 days from today
+'last/this/next day/week/month/quarter/year'
+
+     -1, 0, 1 periods from the current period
+'in n days/weeks/months/quarters/years'
+
+     n periods from the current period
+'n days/weeks/months/quarters/years ahead'
+
+     n periods from the current period
+'n days/weeks/months/quarters/years ago'
+
+     -n periods from the current period
+'20181201'
+
+     8 digit YYYYMMDD with valid year month and day
+'201812'
+
+     6 digit YYYYMM with valid year and month
+
+   Dates with no separators are allowed but might give surprising
+results if mistyped:
+
+   * '20181301' (YYYYMMDD with an invalid month) is parsed as an
+     eight-digit year
+   * '20181232' (YYYYMMDD with an invalid day) gives a parse error
+   * '201801012' (a valid YYYYMMDD followed by additional digits) gives
+     a parse error
+
+   The meaning of relative dates depends on today's date.  If you need
+to test or reproduce old reports, you can use the '--today' option to
+override that.  (Except for periodic transaction rules, which are not
+affected by '--today'.)
+
+
+File: hledger.info,  Node: Report intervals,  Next: Date adjustments,  Prev: Smart dates,  Up: Time periods
+
+13.3 Report intervals
+=====================
+
+A report interval can be specified so that reports like register,
+balance or activity become multi-period, showing each subperiod as a
+separate row or column.
+
+   The following standard intervals can be enabled with command-line
+flags:
+
+   * '-D/--daily'
+   * '-W/--weekly'
+   * '-M/--monthly'
+   * '-Q/--quarterly'
+   * '-Y/--yearly'
+
+   More complex intervals can be specified using '-p/--period',
+described below.
+
+
+File: hledger.info,  Node: Date adjustments,  Next: Period headings,  Prev: Report intervals,  Up: Time periods
+
+13.4 Date adjustments
+=====================
+
+* Menu:
+
+* Start date adjustment::
+* End date adjustment::
+
+
+File: hledger.info,  Node: Start date adjustment,  Next: End date adjustment,  Up: Date adjustments
+
+13.4.1 Start date adjustment
+----------------------------
+
+If you let hledger infer a report's start date, it will adjust the date
+to the previous natural boundary of the report interval, for convenient
+periodic reports.  (If you don't want that, specify a start date.)
+
+   For example, if the journal's first transaction is on january 10th,
+
+   * 'hledger register' (no report interval) will start the report on
+     january 10th.
+   * 'hledger register --monthly' will start the report on the previous
+     month boundary, january 1st.
+   * 'hledger register --monthly --begin 1/5' will start the report on
+     january 5th [1].
+
+   Also if you are generating transactions or budget goals with periodic
+transaction rules, their start date may be adjusted in a similar way (in
+certain situations).
+
+
+File: hledger.info,  Node: End date adjustment,  Prev: Start date adjustment,  Up: Date adjustments
+
+13.4.2 End date adjustment
+--------------------------
+
+A report's end date is always adjusted to include a whole number of
+intervals, so that the last subperiod has the same length as the others.
+
+   For example, if the journal's last transaction is on february 20th,
+
+   * 'hledger register' will end the report on february 20th.
+   * 'hledger register --monthly' will end the report at the end of
+     february.
+   * 'hledger register --monthly --end 2/14' also will end the report at
+     the end of february.
+   * 'hledger register --monthly --begin 1/5 --end 2/14' will end the
+     report on march 4th [1].
+
+   [1] Since hledger 1.29.
+
+
+File: hledger.info,  Node: Period headings,  Next: Period expressions,  Prev: Date adjustments,  Up: Time periods
+
+13.5 Period headings
+====================
+
+With non-standard subperiods, hledger will show "STARTDATE..ENDDATE"
+headings.  With standard subperiods (ie, starting on a natural interval
+boundary), you'll see more compact headings, which are usually
+preferable.  (Though month names will be in english, currently.)
+
+   So if you are specifying a start date and you want compact headings:
+choose a start of year for yearly reports, a start of quarter for
+quarterly reports, a start of month for monthly reports, etc.
+(Remember, you can write eg '-b 2024' or '1/1' as a shortcut for a start
+of year, or '2024-04' or '202404' or 'Apr' for a start of month or
+quarter.)
+
+   For weekly reports, choose a date that's a Monday.  (You can try
+different dates until you see the short headings, or write eg '-b '3
+weeks ago''.)
+
+
+File: hledger.info,  Node: Period expressions,  Prev: Period headings,  Up: Time periods
+
+13.6 Period expressions
+=======================
+
+The '-p/--period' option specifies a period expression, which is a
+compact way of expressing a start date, end date, and/or report
+interval.
+
+   Here's a period expression with a start and end date (specifying the
+first quarter of 2009):
+
+'-p "from 2009/1/1 to 2009/4/1"'
+
+   Several keywords like "from" and "to" are supported for readability;
+these are optional.  "to" can also be written as ".."  or "-".  The
+spaces are also optional, as long as you don't run two dates together.
+So the following are equivalent to the above:
+
+'-p "2009/1/1 2009/4/1"'
+'-p2009/1/1to2009/4/1'
+'-p2009/1/1..2009/4/1'
+
+   Dates are smart dates, so if the current year is 2009, these are also
+equivalent to the above:
+
+'-p "1/1 4/1"'
+'-p "jan-apr"'
+'-p "this year to 4/1"'
+
+   If you specify only one date, the missing start or end date will be
+the earliest or latest transaction date in the journal:
+
+'-p "from 2009/1/1"'   everything after january 1, 2009
+'-p "since 2009/1"'    the same, since is a synonym
+'-p "from 2009"'       the same
+'-p "to 2009"'         everything before january 1, 2009
+
+   You can also specify a period by writing a single partial or full
+date:
+
+'-p "2009"'     the year 2009; equivalent to “2009/1/1 to 2010/1/1”
+'-p "2009/1"'   the month of january 2009; equivalent to “2009/1/1 to
+                2009/2/1”
+'-p             the first day of 2009; equivalent to “2009/1/1 to
+"2009/1/1"'     2009/1/2”
+
+   or by using the "Q" quarter-year syntax (case insensitive):
+
+'-p "2009Q1"'    first quarter of 2009, equivalent to “2009/1/1 to
+                 2009/4/1”
+'-p "q4"'        fourth quarter of the current year
+
+* Menu:
+
+* Period expressions with a report interval::
+* More complex report intervals::
+* Multiple weekday intervals::
+
+
+File: hledger.info,  Node: Period expressions with a report interval,  Next: More complex report intervals,  Up: Period expressions
+
+13.6.1 Period expressions with a report interval
+------------------------------------------------
+
+A period expression can also begin with a report interval, separated
+from the start/end dates (if any) by a space or the word 'in':
+
+'-p "weekly from 2009/1/1 to 2009/4/1"'
+'-p "monthly in 2008"'
+'-p "quarterly"'
+
+
+File: hledger.info,  Node: More complex report intervals,  Next: Multiple weekday intervals,  Prev: Period expressions with a report interval,  Up: Period expressions
+
+13.6.2 More complex report intervals
+------------------------------------
+
+Some more complex intervals can be specified within period expressions,
+such as:
+
+   * 'biweekly' (every two weeks)
+   * 'fortnightly'
+   * 'bimonthly' (every two months)
+   * 'every day|week|month|quarter|year'
+   * 'every N days|weeks|months|quarters|years'
+
+   Weekly on a custom day:
+
+   * 'every Nth day of week' ('th', 'nd', 'rd', or 'st' are all accepted
+     after the number)
+   * 'every WEEKDAYNAME' (full or three-letter english weekday name,
+     case insensitive)
+
+   Monthly on a custom day:
+
+   * 'every Nth day [of month]' ('31st day' will be adjusted to each
+     month's last day)
+   * 'every Nth WEEKDAYNAME [of month]'
+
+   Yearly on a custom month and day:
+
+   * 'every MM/DD [of year]' (month number and day of month number)
+   * 'every MONTHNAME DDth [of year]' (full or three-letter english
+     month name, case insensitive, and day of month number)
+   * 'every DDth MONTHNAME [of year]' (equivalent to the above)
+
+   Examples:
+
+'-p "bimonthly from
+2008"'
+'-p "every 2 weeks"'
+'-p "every 5 months from
+2009/03"'
+'-p "every 2nd day of       periods will go from Tue to Tue
+week"'
+'-p "every Tue"'            same
+'-p "every 15th day"'       period boundaries will be on 15th of each
+                            month
+'-p "every 2nd Monday"'     period boundaries will be on second Monday
+                            of each month
+'-p "every 11/05"'          yearly periods with boundaries on 5th of
+                            November
+'-p "every 5th November"'   same
+'-p "every Nov 5th"'        same
+
+   Show historical balances at end of the 15th day of each month (N is
+an end date, exclusive as always):
+
+$ hledger balance -H -p "every 16th day"
+
+   Group postings from the start of wednesday to end of the following
+tuesday (N is both (inclusive) start date and (exclusive) end date):
+
+$ hledger register checking -p "every 3rd day of week"
+
+
+File: hledger.info,  Node: Multiple weekday intervals,  Prev: More complex report intervals,  Up: Period expressions
+
+13.6.3 Multiple weekday intervals
+---------------------------------
+
+This special form is also supported:
+
+   * 'every WEEKDAYNAME,WEEKDAYNAME,...' (full or three-letter english
+     weekday names, case insensitive)
+
+   Also, 'weekday' and 'weekendday' are shorthand for
+'mon,tue,wed,thu,fri' and 'sat,sun'.
+
+   This is mainly intended for use with '--forecast', to generate
+periodic transactions on arbitrary days of the week.  It may be less
+useful with '-p', since it divides each week into subperiods of unequal
+length, which is unusual.  (Related: #1632)
+
+   Examples:
+
+'-p "every         dates will be Mon, Wed, Fri; periods will be
+mon,wed,fri"'      Mon-Tue, Wed-Thu, Fri-Sun
+'-p "every         dates will be Mon, Tue, Wed, Thu, Fri; periods will
+weekday"'          be Mon, Tue, Wed, Thu, Fri-Sun
+'-p "every         dates will be Sat, Sun; periods will be Sat, Sun-Fri
+weekendday"'
+
+
+File: hledger.info,  Node: Depth,  Next: Queries,  Prev: Time periods,  Up: Top
+
+14 Depth
+********
+
+With the '--depth NUM' option (short form: '-NUM'), reports will show
+accounts only to the specified depth, hiding deeper subaccounts.  Use
+this when you want a summary with less detail.  This flag has the same
+effect as a 'depth:' query argument: 'depth:2', '--depth=2' or '-2' are
+equivalent.
+
+   In place of a single number which limits the depth for all accounts,
+you can also provide separate depth limits for different accounts using
+regular expressions _(since 1.41)_.
+
+   For example, '--depth assets=2' (or, equivalently: 'depth:assets=2')
+will collapse accounts matching the regular expression 'assets' to depth
+2.  So 'assets:bank:savings' would be collapsed to 'assets:bank', while
+'liabilities:bank:credit card' would not be affected.  This can be
+combined with a flat depth to collapse other accounts not matching the
+regular expression, so '--depth assets=2 --depth 1' would collapse
+'assets:bank:savings' to 'assets:bank' and 'liabilities:bank:credit
+card' to 'liabilities'.
+
+   You can supply multiple depth arguments and they will all be applied,
+so '--depth assets=2 --depth liabilities=3 --depth 1' would collapse:
+
+   * accounts matching 'assets' to depth 2,
+   * accounts matching 'liabilities' to depth 3,
+   * all other accounts to depth 1.
+
+   If an account is matched by more than one regular expression depth
+argument then the more specific one will used.  For example, if '--depth
+assets=1 --depth assets:bank:savings=2' is provided, then
+'assets:bank:savings' will be collapsed to depth 2 rather than depth 1.
+This is because 'assets:bank:savings' matches at level 3 in the account
+name, while 'assets' matches at level 1.  The same would be true with
+the argument '--depth assets=1 --depth savings=2'.
+
+
+File: hledger.info,  Node: Queries,  Next: Pivoting,  Prev: Depth,  Up: Top
+
+15 Queries
+**********
+
+One of hledger's strengths is being able to quickly report on a precise
+subset of your data.  Most hledger commands accept query arguments, to
+restrict their scope.  Multiple query terms can be provided to build up
+a more complex query.
+
+   * By default, a query term is interpreted as a case-insensitive
+     substring pattern for matching account names:
+
+     'car:fuel'
+     'dining groceries'
+
+   * Patterns containing spaces or other special characters must be
+     enclosed in single or double quotes:
+
+     ''personal care''
+
+   * These patterns are actually regular expressions, so you can add
+     regexp metacharacters for more precision (see "Regular expressions"
+     above for details):
+
+     ''^expenses\b''
+     ''food$''
+     ''fuel|repair''
+     ''accounts (payable|receivable)''
+
+   * To match something other than account name, add one of the query
+     type prefixes described in "Query types" below:
+
+     'date:202312-'
+     'status:'
+     'desc:amazon'
+     'cur:USD'
+     'cur:\\$'
+     'amt:'>0''
+
+   * Add a 'not:' prefix to negate a term:
+
+     'not:status:'*''
+     'not:desc:'opening|closing''
+     'not:cur:USD'
+
+   * Terms with different types are AND-ed, terms with the same type are
+     OR-ed (mostly; see "Combining query terms" below).  The following
+     query:
+
+     'date:2022 desc:amazon desc:amzn'
+
+     is interpreted as:
+
+     _date is in 2022 AND ( transaction description contains "amazon" OR
+     "amzn" )_
+
+* Menu:
+
+* Query types::
+* Combining query terms::
+* Queries and command options::
+* Queries and account aliases::
+* Queries and valuation::
+
+
+File: hledger.info,  Node: Query types,  Next: Combining query terms,  Up: Queries
+
+15.1 Query types
+================
+
+Here are the types of query term available.
+
+* Menu:
+
+* acct query::
+* amt query::
+* code query::
+* cur query::
+* desc query::
+* date query::
+* date2 query::
+* depth query::
+* expr query::
+* not query::
+* note query::
+* payee query::
+* real query::
+* status query::
+* type query::
+* tag query::
+
+
+File: hledger.info,  Node: acct query,  Next: amt query,  Up: Query types
+
+15.1.1 acct: query
+------------------
+
+*'acct:REGEX'*, or just *'REGEX'*
+Match account names containing this case insensitive regular expression.
+This is the default query type, so we usually don't bother writing the
+"acct:" prefix.
+
+
+File: hledger.info,  Node: amt query,  Next: code query,  Prev: acct query,  Up: Query types
+
+15.1.2 amt: query
+-----------------
+
+*'amt:N, amt:'<N', amt:'<=N', amt:'>N', amt:'>=N''*
+Match postings with a single-commodity amount equal to, less than, or
+greater than N. (Postings with multi-commodity amounts are not tested
+and will always match.)  The comparison has two modes: if N is preceded
+by a + or - sign (or is 0), the two signed numbers are compared.
+Otherwise, the absolute magnitudes are compared, ignoring sign.  'amt:'
+needs quotes to hide the less than/greater than sign from the command
+line shell.
+
+
+File: hledger.info,  Node: code query,  Next: cur query,  Prev: amt query,  Up: Query types
+
+15.1.3 code: query
+------------------
+
+*'code:REGEX'*
+Match by transaction code (eg check number).
+
+
+File: hledger.info,  Node: cur query,  Next: desc query,  Prev: code query,  Up: Query types
+
+15.1.4 cur: query
+-----------------
+
+*'cur:REGEX'*
+Match postings or transactions including any amounts whose
+currency/commodity symbol is fully matched by REGEX. (Contrary to
+hledger's usual infix matching.  To do infix matching, write
+'.*REGEX.*'.)  Note, to match special characters which are
+regex-significant, you need to escape them with '\'.  And for characters
+which are significant to your shell you will usually need one more level
+of escaping.  Eg to match the dollar sign: 'cur:\\$' or 'cur:'\$''
+
+
+File: hledger.info,  Node: desc query,  Next: date query,  Prev: cur query,  Up: Query types
+
+15.1.5 desc: query
+------------------
+
+*'desc:REGEX'*
+Match transaction descriptions.
+
+
+File: hledger.info,  Node: date query,  Next: date2 query,  Prev: desc query,  Up: Query types
+
+15.1.6 date: query
+------------------
+
+*'date:PERIODEXPR'*
+Match dates (or with the '--date2' flag, secondary dates) within the
+specified period.  PERIODEXPR is a period expression with no report
+interval.  Examples:
+'date:2016', 'date:thismonth', 'date:2/1-2/15',
+'date:2021-07-27..nextquarter'.
+
+
+File: hledger.info,  Node: date2 query,  Next: depth query,  Prev: date query,  Up: Query types
+
+15.1.7 date2: query
+-------------------
+
+*'date2:PERIODEXPR'*
+If you use secondary dates: this matches secondary dates within the
+specified period.  It is not affected by the '--date2' flag.
+
+
+File: hledger.info,  Node: depth query,  Next: expr query,  Prev: date2 query,  Up: Query types
+
+15.1.8 depth: query
+-------------------
+
+*'depth:[REGEXP=]N'*
+Match (or display, depending on command) accounts at or above this
+depth, optionally only for accounts matching a provided regular
+expression.  See Depth for detailed rules.
+
+
+File: hledger.info,  Node: expr query,  Next: not query,  Prev: depth query,  Up: Query types
+
+15.1.9 expr: query
+------------------
+
+*'expr:'QUERYEXPR''*
+'expr' lets you write more complicated query expressions with AND, OR,
+NOT, and parentheses.
+Eg: 'expr:'date:lastmonth and not (food or rent)''
+The expression should be enclosed in quotes.  See Combining query terms
+below.
+
+
+File: hledger.info,  Node: not query,  Next: note query,  Prev: expr query,  Up: Query types
+
+15.1.10 not: query
+------------------
+
+*'not:QUERYTERM'*
+You can prepend *'not:'* to any other query term to negate the match.
+Eg: 'not:equity', 'not:desc:apple'
+(Also, a trick: 'not:not:...' can sometimes solve query problems
+conveniently..)
+
+
+File: hledger.info,  Node: note query,  Next: payee query,  Prev: not query,  Up: Query types
+
+15.1.11 note: query
+-------------------
+
+*'note:REGEX'*
+Match transaction notes (the part of the description right of '|', or
+the whole description if there's no '|').
+
+
+File: hledger.info,  Node: payee query,  Next: real query,  Prev: note query,  Up: Query types
+
+15.1.12 payee: query
+--------------------
+
+*'payee:REGEX'*
+Match transaction payee/payer names (the part of the description left of
+'|', or the whole description if there's no '|').
+
+
+File: hledger.info,  Node: real query,  Next: status query,  Prev: payee query,  Up: Query types
+
+15.1.13 real: query
+-------------------
+
+*'real:, real:0'*
+Match real or virtual postings respectively.
+
+
+File: hledger.info,  Node: status query,  Next: type query,  Prev: real query,  Up: Query types
+
+15.1.14 status: query
+---------------------
+
+*'status:, status:!, status:*'*
+Match unmarked, pending, or cleared transactions respectively.
+
+
+File: hledger.info,  Node: type query,  Next: tag query,  Prev: status query,  Up: Query types
+
+15.1.15 type: query
+-------------------
+
+*'type:TYPECODES'*
+Match by account type (see Declaring accounts > Account types).
+'TYPECODES' is one or more of the single-letter account type codes
+'ALERXCV', case insensitive.  Note 'type:A' and 'type:E' will also match
+their respective subtypes 'C' (Cash) and 'V' (Conversion).  Certain
+kinds of account alias can disrupt account types, see Rewriting accounts
+> Aliases and account types.
+
+
+File: hledger.info,  Node: tag query,  Prev: type query,  Up: Query types
+
+15.1.16 tag: query
+------------------
+
+*'tag:NAMEREGEX[=VALREGEX]'*
+Match by tag name, and optionally also by tag value.  Note:
+
+   * Both regular expressions do infix matching.  If you need a complete
+     match, use '^' and '$'.
+     Eg: 'tag:'^fullname$'', 'tag:'^fullname$=^fullvalue$'
+   * To match values, ignoring names, do 'tag:.=VALREGEX'
+   * Accounts also inherit the tags of their parent accounts.
+   * Postings also inherit the tags of their account and their
+     transaction .
+   * Transactions also acquire the tags of their postings.
+
+
+File: hledger.info,  Node: Combining query terms,  Next: Queries and command options,  Prev: Query types,  Up: Queries
+
+15.2 Combining query terms
+==========================
+
+When given multiple space-separated query terms, most commands select
+things which match:
+
+   * any of the description terms AND
+   * any of the account terms AND
+   * any of the status terms AND
+   * all the other terms.
+
+   The print command is a little different, showing transactions which:
+
+   * match any of the description terms AND
+   * have any postings matching any of the positive account terms AND
+   * have no postings matching any of the negative account terms AND
+   * match all the other terms.
+
+   We also support more complex boolean queries with the 'expr:' prefix.
+This allows one to combine query terms using 'and', 'or', 'not' keywords
+(case insensitive), and to group them by enclosing in parentheses.
+
+   Some examples:
+
+   * Exclude account names containing 'food':
+
+     'expr:"not food"' ('not:food' is equivalent)
+
+   * Match things which have 'cool' in the description and the 'A' tag:
+
+     'expr:"desc:cool and tag:A"' ('expr:"desc:cool tag:A"' is
+     equivalent)
+
+   * Match things which either do not reference the 'expenses:food'
+     account, or do have the 'A' tag:
+
+     'expr:"not expenses:food or tag:A"'
+
+   * Match things which either do not reference the 'expenses:food'
+     account, or which reference the 'expenses:drink' account and also
+     have the 'A' tag:
+
+     'expr:"expenses:food or (expenses:drink and tag:A)"'
+
+   'expr:' has a restriction: 'date:' queries may not be used inside
+'or' expressions.  That would allow disjoint report periods or disjoint
+result sets, with unclear semantics for our reports.
+
+
+File: hledger.info,  Node: Queries and command options,  Next: Queries and account aliases,  Prev: Combining query terms,  Up: Queries
+
+15.3 Queries and command options
+================================
+
+Some queries can also be expressed as command-line options: 'depth:2' is
+equivalent to '--depth 2', 'date:2023' is equivalent to '-p 2023', etc.
+When you mix command options and query arguments, generally the
+resulting query is their intersection.
+
+
+File: hledger.info,  Node: Queries and account aliases,  Next: Queries and valuation,  Prev: Queries and command options,  Up: Queries
+
+15.4 Queries and account aliases
+================================
+
+When account names are rewritten with '--alias' or 'alias', 'acct:' will
+match either the old or the new account name.
+
+
+File: hledger.info,  Node: Queries and valuation,  Prev: Queries and account aliases,  Up: Queries
+
+15.5 Queries and valuation
+==========================
+
+When amounts are converted to other commodities in cost or value
+reports, 'cur:' and 'amt:' match the old commodity symbol and the old
+amount quantity, not the new ones.  (Except in hledger 1.22, #1625.)
+
+
+File: hledger.info,  Node: Pivoting,  Next: Generating data,  Prev: Queries,  Up: Top
+
+16 Pivoting
+***********
+
+Normally, hledger groups amounts and displays their totals by account
+(name).  With '--pivot PIVOTEXPR', some other field's (or multiple
+fields') value is used as a synthetic account name, causing different
+grouping and display.  PIVOTEXPR can be
+
+   * any of these standard transaction or posting fields (their value is
+     substituted): 'status', 'code', 'desc', 'payee', 'note', 'acct',
+     'comm'/'cur', 'amt', 'cost'
+   * or a tag name
+   * or any combination of these, colon-separated.
+
+   Some special cases:
+
+   * Colons appearing in PIVOTEXPR or in a pivoted tag value will
+     generate account hierarchy.
+   * When pivoting a posting has multiple values for a tag, the pivoted
+     value of that tag will be the first value.
+   * When a posting has multiple commodities, the pivoted value of
+     "comm"/"cur" will be "".  Also when an unrecognised tag name or
+     field is provided, its pivoted value will be "".  (If this causes
+     confusing output, consider excluding those postings from the
+     report.)
+
+   Examples:
+
+2016/02/16 Yearly Dues Payment
+    assets:bank account                 2 EUR
+    income:dues                        -2 EUR  ; member: John Doe, kind: Lifetime
+
+   Normal balance report showing account names:
+
+$ hledger balance
+               2 EUR  assets:bank account
+              -2 EUR  income:dues
+--------------------
+                   0
+
+   Pivoted balance report, using member: tag values instead:
+
+$ hledger balance --pivot member
+               2 EUR
+              -2 EUR  John Doe
+--------------------
+                   0
+
+   One way to show only amounts with a member: value (using a query):
+
+$ hledger balance --pivot member tag:member=.
+              -2 EUR  John Doe
+--------------------
+              -2 EUR
+
+   Another way (the acct: query matches against the pivoted "account
+name"):
+
+$ hledger balance --pivot member acct:.
+              -2 EUR  John Doe
+--------------------
+              -2 EUR
+
+   Hierarchical reports can be generated with multiple pivot values:
+
+$ hledger balance Income:Dues --pivot kind:member
+              -2 EUR  Lifetime:John Doe
+--------------------
+              -2 EUR
+
+
+File: hledger.info,  Node: Generating data,  Next: Forecasting,  Prev: Pivoting,  Up: Top
+
+17 Generating data
+******************
+
+hledger can enrich the data provided to it, or generate new data, in a
+number of ways.  Mostly, this is done only if you request it:
+
+   * Missing amounts or missing costs in transactions are inferred
+     automatically when possible.
+   * The '--infer-equity' flag infers missing conversion equity postings
+     from @/@@ costs.
+   * The '--infer-costs' flag infers missing costs from conversion
+     equity postings.
+   * The '--infer-market-prices' flag infers 'P' price directives from
+     costs.
+   * The '--auto' flag adds extra postings to transactions matched by
+     auto posting rules.
+   * The '--forecast' option generates transactions from periodic
+     transaction rules.
+   * The 'balance --budget' report infers budget goals from periodic
+     transaction rules.
+   * Commands like 'close', 'rewrite', and 'hledger-interest' generate
+     transactions or postings.
+   * CSV data is converted to transactions by applying CSV conversion
+     rules..  etc.
+
+   Such generated data is temporary, existing only at report time.  You
+can convert it to permanent recorded data by, eg, capturing the output
+of 'hledger print' and saving it in your journal file.  This can
+sometimes be useful as a data entry aid.
+
+   If you are curious what data is being generated and why, run 'hledger
+print -x --verbose-tags'.  '-x/--explicit' shows inferred amounts and
+'--verbose-tags' adds tags like 'generated-transaction' (from periodic
+rules) and 'generated-posting', 'modified' (from auto posting rules).
+Similar hidden tags (with an underscore prefix) are always present,
+also, so you can always match such data with queries like
+'tag:generated' or 'tag:modified'.
+
+
+File: hledger.info,  Node: Forecasting,  Next: Budgeting,  Prev: Generating data,  Up: Top
+
+18 Forecasting
+**************
+
+Forecasting, or speculative future reporting, can be useful for
+estimating future balances, or for exploring different future scenarios.
+
+   The simplest and most flexible way to do it with hledger is to
+manually record a bunch of future-dated transactions.  You could keep
+these in a separate 'future.journal' and include that with '-f' only
+when you want to see them.
+
+* Menu:
+
+* --forecast::
+* Inspecting forecast transactions::
+* Forecast reports::
+* Forecast tags::
+* Forecast period in detail::
+* Forecast troubleshooting::
+
+
+File: hledger.info,  Node: --forecast,  Next: Inspecting forecast transactions,  Up: Forecasting
+
+18.1 -forecast
+==============
+
+There is another way: with the '--forecast' option, hledger can generate
+temporary "forecast transactions" for reporting purposes, according to
+periodic transaction rules defined in the journal.  Each rule can
+generate multiple recurring transactions, so by changing one rule you
+can change many forecasted transactions.
+
+   Forecast transactions usually start after ordinary transactions end.
+By default, they begin after your latest-dated ordinary transaction, or
+today, whichever is later, and they end six months from today.  (The
+exact rules are a little more complicated, and are given below.)
+
+   This is the "forecast period", which need not be the same as the
+report period.  You can override it - eg to forecast farther into the
+future, or to force forecast transactions to overlap your ordinary
+transactions - by giving the -forecast option a period expression
+argument, like '--forecast=..2099' or '--forecast=2023-02-15..'.  Note
+that the '=' is required.
+
+
+File: hledger.info,  Node: Inspecting forecast transactions,  Next: Forecast reports,  Prev: --forecast,  Up: Forecasting
+
+18.2 Inspecting forecast transactions
+=====================================
+
+'print' is the best command for inspecting and troubleshooting forecast
+transactions.  Eg:
+
+~ monthly from 2022-12-20    rent
+    assets:bank:checking
+    expenses:rent           $1000
+
+$ hledger print --forecast --today=2023/4/21
+2023-05-20 rent
+    ; generated-transaction: ~ monthly from 2022-12-20
+    assets:bank:checking
+    expenses:rent                  $1000
+
+2023-06-20 rent
+    ; generated-transaction: ~ monthly from 2022-12-20
+    assets:bank:checking
+    expenses:rent                  $1000
+
+2023-07-20 rent
+    ; generated-transaction: ~ monthly from 2022-12-20
+    assets:bank:checking
+    expenses:rent                  $1000
+
+2023-08-20 rent
+    ; generated-transaction: ~ monthly from 2022-12-20
+    assets:bank:checking
+    expenses:rent                  $1000
+
+2023-09-20 rent
+    ; generated-transaction: ~ monthly from 2022-12-20
+    assets:bank:checking
+    expenses:rent                  $1000
+
+   Here there are no ordinary transactions, so the forecasted
+transactions begin on the first occurrence after today's date.  (You
+won't normally use '--today'; it's just to make these examples
+reproducible.)
+
+
+File: hledger.info,  Node: Forecast reports,  Next: Forecast tags,  Prev: Inspecting forecast transactions,  Up: Forecasting
+
+18.3 Forecast reports
+=====================
+
+Forecast transactions affect all reports, as you would expect.  Eg:
+
+$ hledger areg rent --forecast --today=2023/4/21
+Transactions in expenses:rent and subaccounts:
+2023-05-20 rent                 as:ba:checking               $1000         $1000
+2023-06-20 rent                 as:ba:checking               $1000         $2000
+2023-07-20 rent                 as:ba:checking               $1000         $3000
+2023-08-20 rent                 as:ba:checking               $1000         $4000
+2023-09-20 rent                 as:ba:checking               $1000         $5000
+
+$ hledger bal -M expenses --forecast --today=2023/4/21
+Balance changes in 2023-05-01..2023-09-30:
+
+               ||   May    Jun    Jul    Aug    Sep 
+===============++===================================
+ expenses:rent || $1000  $1000  $1000  $1000  $1000 
+---------------++-----------------------------------
+               || $1000  $1000  $1000  $1000  $1000 
+
+
+File: hledger.info,  Node: Forecast tags,  Next: Forecast period in detail,  Prev: Forecast reports,  Up: Forecasting
+
+18.4 Forecast tags
+==================
+
+Forecast transactions generated by -forecast have a hidden tag,
+'_generated-transaction'.  So if you ever need to match forecast
+transactions, you could use 'tag:_generated-transaction' (or just
+'tag:generated') in a query.
+
+   For troubleshooting, you can add the '--verbose-tags' flag.  Then,
+visible 'generated-transaction' tags will be added also, so you can view
+them with the 'print' command.  Their value indicates which periodic
+rule was responsible.
+
+
+File: hledger.info,  Node: Forecast period in detail,  Next: Forecast troubleshooting,  Prev: Forecast tags,  Up: Forecasting
+
+18.5 Forecast period, in detail
+===============================
+
+Forecast start/end dates are chosen so as to do something useful by
+default in almost all situations, while also being flexible.  Here are
+(with luck) the exact rules, to help with troubleshooting:
+
+   The forecast period starts on:
+
+   * the later of
+        * the start date in the periodic transaction rule
+        * the start date in '--forecast''s argument
+
+   * otherwise (if those are not available): the later of
+        * the report start date specified with '-b'/'-p'/'date:'
+        * the day after the latest ordinary transaction in the journal
+
+   * otherwise (if none of these are available): today.
+
+   The forecast period ends on:
+
+   * the earlier of
+        * the end date in the periodic transaction rule
+        * the end date in '--forecast''s argument
+
+   * otherwise: the report end date specified with '-e'/'-p'/'date:'
+   * otherwise: 180 days (~6 months) from today.
+
+
+File: hledger.info,  Node: Forecast troubleshooting,  Prev: Forecast period in detail,  Up: Forecasting
+
+18.6 Forecast troubleshooting
+=============================
+
+When -forecast is not doing what you expect, one of these tips should
+help:
+
+   * Remember to use the '--forecast' option.
+   * Remember to have at least one periodic transaction rule in your
+     journal.
+   * Test with 'print --forecast'.
+   * Check for typos or too-restrictive start/end dates in your periodic
+     transaction rule.
+   * Leave at least 2 spaces between the rule's period expression and
+     description fields.
+   * Check for future-dated ordinary transactions suppressing forecasted
+     transactions.
+   * Try setting explicit report start and/or end dates with '-b', '-e',
+     '-p' or 'date:'
+   * Try adding the '-E' flag to encourage display of empty periods/zero
+     transactions.
+   * Try setting explicit forecast start and/or end dates with
+     '--forecast=START..END'
+   * Consult Forecast period, in detail, above.
+   * Check inside the engine: add '--debug=2' (eg).
+
+
+File: hledger.info,  Node: Budgeting,  Next: Amount formatting,  Prev: Forecasting,  Up: Top
+
+19 Budgeting
+************
+
+With the balance command's '--budget' report, each periodic transaction
+rule generates recurring budget goals in specified accounts, and goals
+and actual performance can be compared.  See the balance command's doc
+below.
+
+   You can generate budget goals and forecast transactions at the same
+time, from the same or different periodic transaction rules: 'hledger
+bal -M --budget --forecast ...'
+
+   See also: Budgeting and Forecasting.
+
+
+File: hledger.info,  Node: Amount formatting,  Next: Cost reporting,  Prev: Budgeting,  Up: Top
+
+20 Amount formatting
+********************
+
+* Menu:
+
+* Commodity display style::
+* Rounding::
+* Trailing decimal marks::
+* Amount parseability::
+
+
+File: hledger.info,  Node: Commodity display style,  Next: Rounding,  Up: Amount formatting
+
+20.1 Commodity display style
+============================
+
+For the amounts in each commodity, hledger chooses a consistent display
+style (symbol placement, decimal mark and digit group marks, number of
+decimal digits) to use in most reports.  This is inferred as follows:
+
+   First, if there's a 'D' directive declaring a default commodity, that
+commodity symbol and amount format is applied to all no-symbol amounts
+in the journal.
+
+   Then each commodity's display style is determined from its
+'commodity' directive.  We recommend always declaring commodities with
+'commodity' directives, since they help ensure consistent display styles
+and precisions, and bring other benefits such as error checking for
+commodity symbols.  Here's an example:
+
+# Set display styles (and decimal marks, for parsing, if there is no decimal-mark directive)
+# for the $, EUR, INR and no-symbol commodities:
+commodity $1,000.00
+commodity EUR 1.000,00
+commodity INR 9,99,99,999.00
+commodity 1 000 000.9455
+
+   But for convenience, if a 'commodity' directive is not present,
+hledger infers a commodity's display styles from its amounts as they are
+written in the journal (excluding cost amounts and amounts in periodic
+transaction rules or auto posting rules).  It uses
+
+   * the symbol placement and decimal mark of the first amount seen
+   * the digit group marks of the first amount with digit group marks
+   * and the maximum number of decimal digits seen across all amounts.
+
+   And as fallback if no applicable amounts are found, it would use a
+default style, like '$1000.00' (symbol on the left with no space, period
+as decimal mark, and two decimal digits).
+
+   Finally, commodity styles can be overridden by the
+'-c/--commodity-style' command line option.
+
+
+File: hledger.info,  Node: Rounding,  Next: Trailing decimal marks,  Prev: Commodity display style,  Up: Amount formatting
+
+20.2 Rounding
+=============
+
+Amounts are stored internally as decimal numbers with up to 255 decimal
+places.  They are displayed with their original journal precisions by
+print and print-like reports, and rounded to their display precision
+(the number of decimal digits specified by the commodity display style)
+by other reports.  When rounding, hledger uses banker's rounding (it
+rounds to the nearest even digit).  So eg 0.5 displayed with zero
+decimal digits appears as "0".
+
+
+File: hledger.info,  Node: Trailing decimal marks,  Next: Amount parseability,  Prev: Rounding,  Up: Amount formatting
+
+20.3 Trailing decimal marks
+===========================
+
+If you're wondering why your 'print' report sometimes shows trailing
+decimal marks, with no decimal digits; it does this when showing amounts
+that have digit group marks but no decimal digits, to disambiguate them
+and allow them to be re-parsed reliably (see Decimal marks).  Eg:
+
+commodity $1,000.00
+
+2023-01-02
+    (a)      $1000
+
+$ hledger print
+2023-01-02
+    (a)        $1,000.
+
+   If this is a problem (eg when exporting to Ledger), you can avoid it
+by disabling digit group marks, eg with -c/-commodity (for each affected
+commodity):
+
+$ hledger print -c '$1000.00'
+2023-01-02
+    (a)          $1000
+
+   or by forcing print to always show decimal digits, with -round:
+
+$ hledger print -c '$1,000.00' --round=soft
+2023-01-02
+    (a)      $1,000.00
+
+
+File: hledger.info,  Node: Amount parseability,  Prev: Trailing decimal marks,  Up: Amount formatting
+
+20.4 Amount parseability
+========================
+
+More generally, hledger output falls into three rough categories, which
+format amounts a little bit differently to suit different consumers:
+
+   *1.  "hledger-readable output" - should be readable by hledger (and
+by humans)*
+
+   * This is produced by reports that show full journal entries:
+     'print', 'import', 'close', 'rewrite' etc.
+   * It shows amounts with their original journal precisions, which may
+     not be consistent.
+   * It adds a trailing decimal mark when needed to avoid showing
+     ambiguous amounts.
+   * It can be parsed reliably (by hledger and ledger2beancount at
+     least, but perhaps not by Ledger..)
+
+   *2.  "human-readable output" - usually for humans*
+
+   * This is produced by all other reports.
+   * It shows amounts with standard display precisions, which will be
+     consistent within each commodity.
+   * It shows ambiguous amounts unmodified.
+   * It can be parsed reliably in the context of a known report (when
+     you know decimals are consistently not being shown, you can assume
+     a single mark is a digit group mark).
+
+   *3.  "machine-readable output" - usually for other software*
+
+   * This is produced by all reports when an output format like 'csv',
+     'tsv', 'json', or 'sql' is selected.
+   * It shows amounts as 1 or 2 do, but without digit group marks.
+   * It can be parsed reliably (if needed, the decimal mark can be
+     changed with -c/-commodity-style).
+
+
+File: hledger.info,  Node: Cost reporting,  Next: Value reporting,  Prev: Amount formatting,  Up: Top
+
+21 Cost reporting
+*****************
+
+In some transactions - for example a currency conversion, or a purchase
+or sale of stock - one commodity is exchanged for another.  In these
+transactions there is a conversion rate, also called the cost (when
+buying) or selling price (when selling).  (In hledger docs we just say
+"cost" generically for convenience.)  With the '-B/--cost' flag, hledger
+can show amounts "at cost", converted to the cost's commodity.
+
+* Menu:
+
+* Recording costs::
+* Reporting at cost::
+* Equity conversion postings::
+* Inferring equity conversion postings::
+* Combining costs and equity conversion postings::
+* Requirements for detecting equity conversion postings::
+* Infer cost and equity by default ?::
+
+
+File: hledger.info,  Node: Recording costs,  Next: Reporting at cost,  Up: Cost reporting
+
+21.1 Recording costs
+====================
+
+We'll explore several ways of recording transactions involving costs.
+These are also summarised at hledger Cookbook > Cost notation.
+
+   Costs can be recorded explicitly in the journal, using the '@
+UNITCOST' or '@@ TOTALCOST' notation described in Journal > Costs:
+
+   *Variant 1*
+
+2022-01-01
+  assets:dollars    $-135
+  assets:euros       €100 @ $1.35   ; $1.35 per euro (unit cost)
+
+   *Variant 2*
+
+2022-01-01
+  assets:dollars    $-135
+  assets:euros       €100 @@ $135   ; $135 total cost
+
+   Typically, writing the unit cost (variant 1) is preferable; it can be
+more effort, requiring more attention to decimal digits; but it reveals
+the per-unit cost basis, and makes stock sales easier.
+
+   Costs can also be left implicit, and hledger will infer the cost that
+is consistent with a balanced transaction:
+
+   *Variant 3*
+
+2022-01-01
+  assets:dollars    $-135
+  assets:euros       €100
+
+   Here, hledger will attach a '@@ €100' cost to the first amount (you
+can see it with 'hledger print -x').  This form looks convenient, but
+there are downsides:
+
+   * It sacrifices some error checking.  For example, if you
+     accidentally wrote €10 instead of €100, hledger would not be able
+     to detect the mistake.
+
+   * It is sensitive to the order of postings - if they were reversed, a
+     different entry would be inferred and reports would be different.
+
+   * The per-unit cost basis is not easy to read.
+
+   So generally this kind of entry is not recommended.  You can make
+sure you have none of these by using '-s' (strict mode), or by running
+'hledger check balanced'.
+
+
+File: hledger.info,  Node: Reporting at cost,  Next: Equity conversion postings,  Prev: Recording costs,  Up: Cost reporting
+
+21.2 Reporting at cost
+======================
+
+Now when you add the '-B'/'--cost' flag to reports ("B" is from Ledger's
+-B/-basis/-cost flag), any amounts which have been annotated with costs
+will be converted to their cost's commodity (in the report output).  Ie
+they will be displayed "at cost" or "at sale price".
+
+   Some things to note:
+
+   * Costs are attached to specific posting amounts in specific
+     transactions, and once recorded they do not change.  This contrasts
+     with market prices, which are ambient and fluctuating.
+
+   * Conversion to cost is performed before conversion to market value
+     (described below).
+
+
+File: hledger.info,  Node: Equity conversion postings,  Next: Inferring equity conversion postings,  Prev: Reporting at cost,  Up: Cost reporting
+
+21.3 Equity conversion postings
+===============================
+
+There is a problem with the entries above - they are not conventional
+Double Entry Bookkeeping (DEB) notation, and because of the "magical"
+transformation of one commodity into another, they cause an imbalance in
+the Accounting Equation.  This shows up as a non-zero grand total in
+balance reports like 'hledger bse'.
+
+   For most hledger users, this doesn't matter in practice and can
+safely be ignored !  But if you'd like to learn more, keep reading.
+
+   Conventional DEB uses an extra pair of equity postings to balance the
+transaction.  Of course you can do this in hledger as well:
+
+   *Variant 4*
+
+2022-01-01
+    assets:dollars      $-135
+    assets:euros         €100
+    equity:conversion    $135
+    equity:conversion   €-100
+
+   Now the transaction is perfectly balanced according to standard DEB,
+and 'hledger bse''s total will not be disrupted.
+
+   And, hledger can still infer the cost for cost reporting, but it's
+not done by default - you must add the '--infer-costs' flag like so:
+
+$ hledger print --infer-costs
+2022-01-01 one hundred euros purchased at $1.35 each
+    assets:dollars       $-135 @@ €100
+    assets:euros                  €100
+    equity:conversion             $135
+    equity:conversion            €-100
+
+$ hledger bal --infer-costs -B
+               €-100  assets:dollars                                                                                                                                              
+                €100  assets:euros                                                                                                                                                
+--------------------                                                                                                                                                              
+                   0                                                                                                                                                              
+
+   Here are some downsides of this kind of entry:
+
+   * The per-unit cost basis is not easy to read.
+
+   * Instead of '-B' you must remember to type '-B --infer-costs'.
+
+   * '--infer-costs' works only where hledger can identify the two
+     equity:conversion postings and match them up with the two
+     non-equity postings.  So writing the journal entry in a particular
+     format becomes more important.  More on this below.
+
+
+File: hledger.info,  Node: Inferring equity conversion postings,  Next: Combining costs and equity conversion postings,  Prev: Equity conversion postings,  Up: Cost reporting
+
+21.4 Inferring equity conversion postings
+=========================================
+
+Can we go in the other direction ?  Yes, if you have transactions
+written with the @/@@ cost notation, hledger can infer the missing
+equity postings, if you add the '--infer-equity' flag.  Eg:
+
+2022-01-01
+  assets:dollars  -$135
+  assets:euros     €100 @ $1.35
+
+$ hledger print --infer-equity
+2022-01-01
+    assets:dollars                    $-135
+    assets:euros               €100 @ $1.35
+    equity:conversion:$-€:€           €-100
+    equity:conversion:$-€:$         $135.00
+
+   The equity account names will be "equity:conversion:A-B:A" and
+"equity:conversion:A-B:B" where A is the alphabetically first commodity
+symbol.  You can customise the "equity:conversion" part by declaring an
+account with the 'V'/'Conversion' account type.
+
+   Note you will need to add account declarations for these to your
+journal, if you use 'check accounts' or 'check --strict'.
+
+
+File: hledger.info,  Node: Combining costs and equity conversion postings,  Next: Requirements for detecting equity conversion postings,  Prev: Inferring equity conversion postings,  Up: Cost reporting
+
+21.5 Combining costs and equity conversion postings
+===================================================
+
+Finally, you can use both the @/@@ cost notation and equity postings at
+the same time.  This in theory gives the best of all worlds - preserving
+the accounting equation, revealing the per-unit cost basis, and
+providing more flexibility in how you write the entry:
+
+   *Variant 5*
+
+2022-01-01 one hundred euros purchased at $1.35 each
+    assets:dollars      $-135
+    equity:conversion    $135
+    equity:conversion   €-100
+    assets:euros         €100 @ $1.35
+
+   All the other variants above can (usually) be rewritten to this final
+form with:
+
+$ hledger print -x --infer-costs --infer-equity
+
+   Downsides:
+
+   * The precise format of the journal entry becomes more important.  If
+     hledger can't detect and match up the cost and equity postings, it
+     will give a transaction balancing error.
+
+   * The add command does not yet accept this kind of entry (#2056).
+
+   * This is the most verbose form.
+
+
+File: hledger.info,  Node: Requirements for detecting equity conversion postings,  Next: Infer cost and equity by default ?,  Prev: Combining costs and equity conversion postings,  Up: Cost reporting
+
+21.6 Requirements for detecting equity conversion postings
+==========================================================
+
+'--infer-costs' has certain requirements (unlike '--infer-equity', which
+always works).  It will infer costs only in transactions with:
+
+   * Two non-equity postings, in different commodities.  Their order is
+     significant: the cost will be added to the first of them.
+
+   * Two postings to equity conversion accounts, next to one another,
+     which balance the two non-equity postings.  This balancing is
+     checked to the same precision (number of decimal places) used in
+     the conversion posting's amount.  Equity conversion accounts are:
+
+        * any accounts declared with account type 'V'/'Conversion', or
+          their subaccounts
+        * otherwise, accounts named 'equity:conversion', 'equity:trade',
+          or 'equity:trading', or their subaccounts.
+
+   And multiple such four-posting groups can coexist within a single
+transaction.  When '--infer-costs' fails, it does not infer a cost in
+that transaction, and does not raise an error (ie, it infers costs where
+it can).
+
+   Reading variant 5 journal entries, combining cost notation and equity
+postings, has all the same requirements.  When reading such an entry
+fails, hledger raises an "unbalanced transaction" error.
+
+
+File: hledger.info,  Node: Infer cost and equity by default ?,  Prev: Requirements for detecting equity conversion postings,  Up: Cost reporting
+
+21.7 Infer cost and equity by default ?
+=======================================
+
+Should '--infer-costs' and '--infer-equity' be enabled by default ?  Try
+using them always, eg with a shell alias:
+
+alias h="hledger --infer-equity --infer-costs"
+
+   and let us know what problems you find.
+
+
+File: hledger.info,  Node: Value reporting,  Next: PART 4 COMMANDS,  Prev: Cost reporting,  Up: Top
+
+22 Value reporting
+******************
+
+hledger can also show amounts "at market value", converted to some other
+commodity using the market price or conversion rate on a certain date.
+
+   This is controlled by the '--value=TYPE[,COMMODITY]' option.  We also
+provide simpler '-V' and '-X COMMODITY' aliases for this, which are
+often sufficient.  The market prices are declared with a special 'P'
+directive, and/or they can be inferred from the costs recorded in
+transactions, by using the '--infer-market-prices' flag.
+
+* Menu:
+
+* -V Value::
+* -X Value in specified commodity::
+* Valuation date::
+* Finding market price::
+* --infer-market-prices market prices from transactions::
+* Valuation commodity::
+* --value Flexible valuation::
+* Valuation examples::
+* Interaction of valuation and queries::
+* Effect of valuation on reports::
+
+
+File: hledger.info,  Node: -V Value,  Next: -X Value in specified commodity,  Up: Value reporting
+
+22.1 -V: Value
+==============
+
+The '-V/--market' flag converts amounts to market value in their default
+_valuation commodity_, using the market prices in effect on the
+_valuation date(s)_, if any.  More on these in a minute.
+
+
+File: hledger.info,  Node: -X Value in specified commodity,  Next: Valuation date,  Prev: -V Value,  Up: Value reporting
+
+22.2 -X: Value in specified commodity
+=====================================
+
+The '-X/--exchange=COMM' option is like '-V', except you tell it which
+currency you want to convert to, and it tries to convert everything to
+that.
+
+
+File: hledger.info,  Node: Valuation date,  Next: Finding market price,  Prev: -X Value in specified commodity,  Up: Value reporting
+
+22.3 Valuation date
+===================
+
+Market prices can change from day to day.  hledger will use the prices
+on a particular valuation date (or on more than one date).  By default
+hledger uses "end" dates for valuation.  More specifically:
+
+   * For single period reports (including normal print and register
+     reports):
+        * If an explicit report end date is specified, that is used
+        * Otherwise the latest transaction date or P directive date is
+          used (even if it's in the future)
+
+   * For multiperiod reports, each period is valued on its last day.
+
+   This can be customised with the -value option described below, which
+can select either "then", "end", "now", or "custom" dates.  (Note, this
+has a bug in hledger-ui <=1.31: turning on valuation with the 'V' key
+always resets it to "end".)
+
+
+File: hledger.info,  Node: Finding market price,  Next: --infer-market-prices market prices from transactions,  Prev: Valuation date,  Up: Value reporting
+
+22.4 Finding market price
+=========================
+
+To convert a commodity A to its market value in another commodity B,
+hledger looks for a suitable market price (exchange rate) as follows, in
+this order of preference:
+
+  1. A _declared market price_ or _inferred market price_: A's latest
+     market price in B on or before the valuation date as declared by a
+     P directive, or (with the '--infer-market-prices' flag) inferred
+     from costs.
+
+  2. A _reverse market price_: the inverse of a declared or inferred
+     market price from B to A.
+
+  3. A _forward chain of market prices_: a synthetic price formed by
+     combining the shortest chain of "forward" (only 1 above) market
+     prices, leading from A to B.
+
+  4. _Any chain of market prices_: a chain of any market prices,
+     including both forward and reverse prices (1 and 2 above), leading
+     from A to B.
+
+   There is a limit to the length of these price chains; if hledger
+reaches that length without finding a complete chain or exhausting all
+possibilities, it will give up (with a "gave up" message visible in
+'--debug=2' output).  That limit is currently 1000.
+
+   Amounts for which no suitable market price can be found, are not
+converted.
+
+
+File: hledger.info,  Node: --infer-market-prices market prices from transactions,  Next: Valuation commodity,  Prev: Finding market price,  Up: Value reporting
+
+22.5 -infer-market-prices: market prices from transactions
+==========================================================
+
+Normally, market value in hledger is fully controlled by, and requires,
+P directives in your journal.  Since adding and updating those can be a
+chore, and since transactions usually take place at close to market
+value, why not use the recorded costs as additional market prices (as
+Ledger does) ?  Adding the '--infer-market-prices' flag to '-V', '-X' or
+'--value' enables this.
+
+   So for example, 'hledger bs -V --infer-market-prices' will get market
+prices both from P directives and from transactions.  If both occur on
+the same day, the P directive takes precedence.
+
+   There is a downside: value reports can sometimes be affected in
+confusing/undesired ways by your journal entries.  If this happens to
+you, read all of this Value reporting section carefully, and try adding
+'--debug' or '--debug=2' to troubleshoot.
+
+   '--infer-market-prices' can infer market prices from:
+
+   * multicommodity transactions with explicit prices ('@'/'@@')
+
+   * multicommodity transactions with implicit prices (no '@', two
+     commodities, unbalanced).  (With these, the order of postings
+     matters.  'hledger print -x' can be useful for troubleshooting.)
+
+   * multicommodity transactions with equity postings, if cost is
+     inferred with '--infer-costs'.
+
+   There is a limitation (bug) currently: when a valuation commodity is
+not specified, prices inferred with '--infer-market-prices' do not help
+select a default valuation commodity, as 'P' prices would.  So
+conversion might not happen because no valuation commodity was detected
+('--debug=2' will show this).  To be safe, specify the valuation
+commmodity, eg:
+
+   * '-X EUR --infer-market-prices', not '-V --infer-market-prices'
+   * '--value=then,EUR --infer-market-prices', not '--value=then
+     --infer-market-prices'
+
+   Signed costs and market prices can be confusing.  For reference, here
+is the current behaviour, since hledger 1.25.  (If you think it should
+work differently, see #1870.)
+
+2022-01-01 Positive Unit prices
+    a        A 1
+    b        B -1 @ A 1
+
+2022-01-01 Positive Total prices
+    a        A 1
+    b        B -1 @@ A 1
+
+
+2022-01-02 Negative unit prices
+    a        A 1
+    b        B 1 @ A -1
+
+2022-01-02 Negative total prices
+    a        A 1
+    b        B 1 @@ A -1
+
+
+2022-01-03 Double Negative unit prices
+    a        A -1
+    b        B -1 @ A -1
+
+2022-01-03 Double Negative total prices
+    a        A -1
+    b        B -1 @@ A -1
+
+   All of the transactions above are considered balanced (and on each
+day, the two transactions are considered equivalent).  Here are the
+market prices inferred for B:
+
+$ hledger -f- --infer-market-prices prices
+P 2022-01-01 B A 1
+P 2022-01-01 B A 1.0
+P 2022-01-02 B A -1
+P 2022-01-02 B A -1.0
+P 2022-01-03 B A -1
+P 2022-01-03 B A -1.0
+
+
+File: hledger.info,  Node: Valuation commodity,  Next: --value Flexible valuation,  Prev: --infer-market-prices market prices from transactions,  Up: Value reporting
+
+22.6 Valuation commodity
+========================
+
+*When you specify a valuation commodity ('-X COMM' or '--value
+TYPE,COMM'):*
+hledger will convert all amounts to COMM, wherever it can find a
+suitable market price (including by reversing or chaining prices).
+
+   *When you leave the valuation commodity unspecified ('-V' or '--value
+TYPE'):*
+For each commodity A, hledger picks a default valuation commodity as
+follows, in this order of preference:
+
+  1. The price commodity from the latest P-declared market price for A
+     on or before valuation date.
+
+  2. The price commodity from the latest P-declared market price for A
+     on any date.  (Allows conversion to proceed when there are inferred
+     prices before the valuation date.)
+
+  3. If there are no P directives at all (any commodity or date) and the
+     '--infer-market-prices' flag is used: the price commodity from the
+     latest transaction-inferred price for A on or before valuation
+     date.
+
+   This means:
+
+   * If you have P directives, they determine which commodities '-V'
+     will convert, and to what.
+
+   * If you have no P directives, and use the '--infer-market-prices'
+     flag, costs determine it.
+
+   Amounts for which no valuation commodity can be found are not
+converted.
+
+
+File: hledger.info,  Node: --value Flexible valuation,  Next: Valuation examples,  Prev: Valuation commodity,  Up: Value reporting
+
+22.7 -value: Flexible valuation
+===============================
+
+'-V' and '-X' are special cases of the more general '--value' option:
+
+ --value=TYPE[,COMM]  TYPE is then, end, now or YYYY-MM-DD.
+                      COMM is an optional commodity symbol.
+                      Shows amounts converted to:
+                      - default valuation commodity (or COMM) using market prices at posting dates
+                      - default valuation commodity (or COMM) using market prices at period end(s)
+                      - default valuation commodity (or COMM) using current market prices
+                      - default valuation commodity (or COMM) using market prices at some date
+
+   The TYPE part selects cost or value and valuation date:
+
+'--value=then'
+
+     Convert amounts to their value in the default valuation commodity,
+     using market prices on each posting's date.
+'--value=end'
+
+     Convert amounts to their value in the default valuation commodity,
+     using market prices on the last day of the report period (or if
+     unspecified, the journal's end date); or in multiperiod reports,
+     market prices on the last day of each subperiod.
+'--value=now'
+
+     Convert amounts to their value in the default valuation commodity
+     using current market prices (as of when report is generated).
+'--value=YYYY-MM-DD'
+
+     Convert amounts to their value in the default valuation commodity
+     using market prices on this date.
+
+   To select a different valuation commodity, add the optional ',COMM'
+part: a comma, then the target commodity's symbol.  Eg:
+*'--value=now,EUR'*.  hledger will do its best to convert amounts to
+this commodity, deducing market prices as described above.
+
+
+File: hledger.info,  Node: Valuation examples,  Next: Interaction of valuation and queries,  Prev: --value Flexible valuation,  Up: Value reporting
+
+22.8 Valuation examples
+=======================
+
+Here are some quick examples of '-V':
+
+; one euro is worth this many dollars from nov 1
+P 2016/11/01 € $1.10
+
+; purchase some euros on nov 3
+2016/11/3
+    assets:euros        €100
+    assets:checking
+
+; the euro is worth fewer dollars by dec 21
+P 2016/12/21 € $1.03
+
+   How many euros do I have ?
+
+$ hledger -f t.j bal -N euros
+                €100  assets:euros
+
+   What are they worth at end of nov 3 ?
+
+$ hledger -f t.j bal -N euros -V -e 2016/11/4
+             $110.00  assets:euros
+
+   What are they worth after 2016/12/21 ?  (no report end date
+specified, defaults to today)
+
+$ hledger -f t.j bal -N euros -V
+             $103.00  assets:euros
+
+   Here are some examples showing the effect of '--value', as seen with
+'print':
+
+P 2000-01-01 A  1 B
+P 2000-02-01 A  2 B
+P 2000-03-01 A  3 B
+P 2000-04-01 A  4 B
+
+2000-01-01
+  (a)      1 A @ 5 B
+
+2000-02-01
+  (a)      1 A @ 6 B
+
+2000-03-01
+  (a)      1 A @ 7 B
+
+   Show the cost of each posting:
+
+$ hledger -f- print --cost
+2000-01-01
+    (a)             5 B
+
+2000-02-01
+    (a)             6 B
+
+2000-03-01
+    (a)             7 B
+
+   Show the value as of the last day of the report period (2000-02-29):
+
+$ hledger -f- print --value=end date:2000/01-2000/03
+2000-01-01
+    (a)             2 B
+
+2000-02-01
+    (a)             2 B
+
+   With no report period specified, that shows the value as of the last
+day of the journal (2000-03-01):
+
+$ hledger -f- print --value=end
+2000-01-01
+    (a)             3 B
+
+2000-02-01
+    (a)             3 B
+
+2000-03-01
+    (a)             3 B
+
+   Show the current value (the 2000-04-01 price is still in effect
+today):
+
+$ hledger -f- print --value=now
+2000-01-01
+    (a)             4 B
+
+2000-02-01
+    (a)             4 B
+
+2000-03-01
+    (a)             4 B
+
+   Show the value on 2000/01/15:
+
+$ hledger -f- print --value=2000-01-15
+2000-01-01
+    (a)             1 B
+
+2000-02-01
+    (a)             1 B
+
+2000-03-01
+    (a)             1 B
+
+
+File: hledger.info,  Node: Interaction of valuation and queries,  Next: Effect of valuation on reports,  Prev: Valuation examples,  Up: Value reporting
+
+22.9 Interaction of valuation and queries
+=========================================
+
+When matching postings based on queries in the presence of valuation,
+the following happens:
+
+  1. The query is separated into two parts:
+       1. the currency ('cur:') or amount ('amt:').
+       2. all other parts.
+
+  2. The postings are matched to the currency and amount queries based
+     on pre-valued amounts.
+  3. Valuation is applied to the postings.
+  4. The postings are matched to the other parts of the query based on
+     post-valued amounts.
+
+   Related: #1625
+
+
+File: hledger.info,  Node: Effect of valuation on reports,  Prev: Interaction of valuation and queries,  Up: Value reporting
+
+22.10 Effect of valuation on reports
+====================================
+
+Here is a reference for how valuation is supposed to affect each part of
+hledger's reports.  (It's wide, you may need to scroll sideways.)  It
+may be useful when troubleshooting.  If you find problems, please report
+them, ideally with a reproducible example.  Related: #329, #1083.
+
+   First, a quick glossary:
+
+_cost_
+
+     calculated using price(s) recorded in the transaction(s).
+_value_
+
+     market value using available market price declarations, or the
+     unchanged amount if no conversion rate can be found.
+_report start_
+
+     the first day of the report period specified with -b or -p or
+     date:, otherwise today.
+_report or journal start_
+
+     the first day of the report period specified with -b or -p or
+     date:, otherwise the earliest transaction date in the journal,
+     otherwise today.
+_report end_
+
+     the last day of the report period specified with -e or -p or date:,
+     otherwise today.
+_report or journal end_
+
+     the last day of the report period specified with -e or -p or date:,
+     otherwise the latest transaction date in the journal, otherwise
+     today.
+_report interval_
+
+     a flag (-D/-W/-M/-Q/-Y) or period expression that activates the
+     report's multi-period mode (whether showing one or many
+     subperiods).
+
+Report     '-B',        '-V', '-X'   '--value=then'     '--value=end''--value=DATE',
+type       '--cost'                                                  '--value=now'
+------------------------------------------------------------------------------
+*print*
+posting    cost         value at     value at posting   value at     value
+amounts                 report end   date               report or    at
+                        or today                        journal      DATE/today
+                                                        end
+balance    unchanged    unchanged    unchanged          unchanged    unchanged
+assertions/assignments
+*register*
+starting   cost         value at     valued at day      value at     value
+balance                 report or    each historical    report or    at
+(-H)                    journal      posting was made   journal      DATE/today
+                        end                             end
+starting   cost         value at     valued at day      value at     value
+balance                 day before   each historical    day before   at
+(-H)                    report or    posting was made   report or    DATE/today
+with                    journal                         journal
+report                  start                           start
+interval
+posting    cost         value at     value at posting   value at     value
+amounts                 report or    date               report or    at
+                        journal                         journal      DATE/today
+                        end                             end
+summary    summarised   value at     sum of postings    value at     value
+posting    cost         period       in interval,       period       at
+amounts                 ends         valued at          ends         DATE/today
+with                                 interval start
+report
+interval
+running    sum/average  sum/average  sum/average of     sum/average  sum/average
+total/averageof         of           displayed values   of           of
+           displayed    displayed                       displayed    displayed
+           values       values                          values       values
+*balance
+(bs,
+bse, cf,
+is)*
+balance    sums of      value at     value at posting   value at     value
+changes    costs        report end   date               report or    at
+                        or today                        journal      DATE/today
+                        of sums of                      end of       of
+                        postings                        sums of      sums
+                                                        postings     of
+                                                                     postings
+budget     like         like         like balance       like         like
+amounts    balance      balance      changes            balances     balance
+(-budget)  changes      changes                                      changes
+grand      sum of       sum of       sum of displayed   sum of       sum of
+total      displayed    displayed    valued             displayed    displayed
+           values       values                          values       values
+*balance
+(bs,
+bse, cf,
+is) with
+report
+interval*
+starting   sums of      value at     sums of values     value at     sums
+balances   costs of     report       of postings        report       of
+(-H)       postings     start of     before report      start of     postings
+           before       sums of      start at           sums of      before
+           report       all          respective         all          report
+           start        postings     posting dates      postings     start
+                        before                          before
+                        report                          report
+                        start                           start
+balance    sums of      same as      sums of values     balance      value
+changes    costs of     -value=end   of postings in     change in    at
+(bal,      postings                  period at          each         DATE/today
+is, bs     in period                 respective         period,      of
+-change,                             posting dates      valued at    sums
+cf                                                      period       of
+-change)                                                ends         postings
+end        sums of      same as      sums of values     period end   value
+balances   costs of     -value=end   of postings from   balances,    at
+(bal -H,   postings                  before period      valued at    DATE/today
+is -H,     from                      start to period    period       of
+bs, cf)    before                    end at             ends         sums
+           report                    respective                      of
+           start to                  posting dates                   postings
+           period end
+budget     like         like         like balance       like         like
+amounts    balance      balance      changes/end        balances     balance
+(-budget)  changes/end  changes/end  balances                        changes/end
+           balances     balances                                     balances
+row        sums,        sums,        sums, averages     sums,        sums,
+totals,    averages     averages     of displayed       averages     averages
+row        of           of           values             of           of
+averages   displayed    displayed                       displayed    displayed
+(-T, -A)   values       values                          values       values
+column     sums of      sums of      sums of            sums of      sums
+totals     displayed    displayed    displayed values   displayed    of
+           values       values                          values       displayed
+                                                                     values
+grand      sum,         sum,         sum, average of    sum,         sum,
+total,     average of   average of   column totals      average of   average
+grand      column       column                          column       of
+average    totals       totals                          totals       column
+                                                                     totals
+
+   '--cumulative' is omitted to save space, it works like '-H' but with
+a zero starting balance.
+
+
+File: hledger.info,  Node: PART 4 COMMANDS,  Next: Help commands,  Prev: Value reporting,  Up: Top
+
+23 PART 4: COMMANDS
+*******************
+
+Here are the standard commands, which you can list by running 'hledger'.
+If you have installed more add-on commands, they also will be listed.
+
+   *Help commands*
+
+   * help - show the hledger manual with info/man/pager
+   * demo - show small hledger demos in the terminal
+
+   *User interface commands*
+
+   * ui - (if installed) run hledger's terminal UI
+   * web - (if installed) run hledger's web UI
+
+   *Data entry commands*
+
+   * add - add transactions using terminal prompts
+   * import - add new transactions from other files, eg CSV files
+
+   *Basic report commands*
+
+   * accounts - show account names
+   * codes - show transaction codes
+   * commodities - show commodity/currency symbols
+   * descriptions - show transaction descriptions
+   * files - show input file paths
+   * notes - show note parts of transaction descriptions
+   * payees - show payee parts of transaction descriptions
+   * prices - show market prices
+   * stats - show journal statistics
+   * tags - show tag names
+
+   *Standard report commands*
+
+   * print - show transactions or export journal data
+   * aregister (areg) - show transactions in a particular account
+   * register (reg) - show postings in one or more accounts & running
+     total
+   * balancesheet (bs) - show assets, liabilities and net worth
+   * balancesheetequity (bse) - show assets, liabilities and equity
+   * cashflow (cf) - show changes in liquid assets
+   * incomestatement (is) - show revenues and expenses
+
+   *Advanced report commands*
+
+   * balance (bal) - show balance changes, end balances, budgets,
+     gains..
+   * roi - show return on investments
+
+   *Chart commands*
+
+   * activity - show bar charts of posting counts per period
+
+   *Data generation commands*
+
+   * close - generate balance-zeroing/restoring transactions
+   * rewrite - generate auto postings, like print -auto
+
+   *Maintenance commands*
+
+   * check - check for various kinds of error in the data
+   * diff - compare account transactions in two journal files
+   * test - run self tests
+
+   Next, these commands are described in detail.
+
+
+File: hledger.info,  Node: Help commands,  Next: User interface commands,  Prev: PART 4 COMMANDS,  Up: Top
+
+24 Help commands
+****************
+
+* Menu:
+
+* commands::
+* demo::
+* help::
+
+
+File: hledger.info,  Node: commands,  Next: demo,  Up: Help commands
+
+24.1 commands
+=============
+
+Show the hledger commands list.
+
+Flags:
+     --builtin             show only builtin commands, not addons
+
+
+File: hledger.info,  Node: demo,  Next: help,  Prev: commands,  Up: Help commands
+
+24.2 demo
+=========
+
+Play demos of hledger usage in the terminal, if asciinema is installed.
+
+Flags:
+  -s --speed=SPEED         playback speed (1 is original speed, .5 is half, 2
+                           is double, etc (default: 2))
+
+   Run this command with no argument to list the demos.  To play a demo,
+write its number or a prefix or substring of its title.  Tips:
+
+   Make your terminal window large enough to see the demo clearly.
+
+   Use the -s/-speed SPEED option to set your preferred playback speed,
+eg '-s4' to play at 4x original speed or '-s.5' to play at half speed.
+The default speed is 2x.
+
+   Other asciinema options can be added following a double dash, eg '--
+-i.1' to limit pauses or '-- -h' to list asciinema's other options.
+
+   During playback, several keys are available: SPACE to pause/unpause,
+.  to step forward (while paused), CTRL-c quit.
+
+   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.
+
+
+File: hledger.info,  Node: help,  Prev: demo,  Up: Help commands
+
+24.3 help
+=========
+
+Show the hledger user manual with 'info', 'man', or a pager.  With a
+(case insensitive) TOPIC argument, try to open it at that section
+heading.
+
+Flags:
+  -i                       show the manual with info
+  -m                       show the manual with man
+  -p                       show the manual with $PAGER or less
+                           (less is always used if TOPIC is specified)
+
+   This command shows the hledger manual built in to your hledger
+executable.  It can be useful when offline, or when you prefer the
+terminal to a web browser, or when the appropriate hledger manual or
+viewers are not installed properly on your system.
+
+   By default it chooses the best viewer found in $PATH, trying in this
+order: 'info', 'man', '$PAGER', 'less', 'more', stdout.  (If a TOPIC is
+specified, '$PAGER' and 'more' are not tried.)  You can force the use of
+info, man, or a pager with the '-i', '-m', or '-p' flags.  If no viewer
+can be found, or if running non-interactively, it just prints the manual
+to stdout.
+
+   When using 'info', TOPIC can match either the full heading or a
+prefix.  If your 'info --version' is < 6, you'll need to upgrade it, eg
+with ''brew install texinfo'' on mac.
+
+   When using 'man' or 'less', TOPIC must match the full heading.  For a
+prefix match, you can write ''TOPIC.*''.
+
+   Examples
+
+$ hledger help -h                 # show the help command's usage
+$ hledger help                    # show the manual with info, man or $PAGER
+$ hledger help 'time periods'     # show the manual's "Time periods" topic
+$ hledger help 'time periods' -m  # use man, even if info is installed
+
+
+File: hledger.info,  Node: User interface commands,  Next: Data entry commands,  Prev: Help commands,  Up: Top
+
+25 User interface commands
+**************************
+
+* Menu:
+
+* repl::
+* run::
+* ui::
+* web::
+
+
+File: hledger.info,  Node: repl,  Next: run,  Up: User interface commands
+
+25.1 repl
+=========
+
+Start an interactive prompt, where you can run any of hledger's
+commands.  Data files are parsed just once, so the commands run faster.
+
+Flags:
+no command-specific flags
+
+   This command is experimental and could change in the future.
+
+   'hledger repl' starts a read-eval-print loop (REPL) where you can
+enter 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.
+
+   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,
+and commands will not see any changes made to input files (eg by 'add')
+until you exit and restart the REPL.
+
+   The command syntax is the same as with 'run':
+
+   * enter one hledger command at a time, without the usual 'hledger'
+     first 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.
+
+   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
+   * 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 useful.
+
+   You can type control-C to cancel a long-running command (but only
+once; typing it a second time will exit the REPL).
+
+   And in most shells you can type control-Z to exit temporarily to the
+shell (and 'fg' to return to the REPL).
+
+   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
+
+* Menu:
+
+* Examples::
+
+
+File: hledger.info,  Node: Examples,  Up: repl
+
+25.1.1 Examples
+---------------
+
+Start the REPL and enter some commands:
+
+$ 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:
+
+$ 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
+...
+
+
+File: hledger.info,  Node: run,  Next: ui,  Prev: repl,  Up: User interface commands
+
+25.2 run
+========
+
+Run a sequence of hledger commands, provided as files or command line
+arguments.  Data files are parsed just once, so the commands run faster.
+
+Flags:
+no command-specific flags
+
+   This command is experimental and could change in the future.
+
+   You can use 'run' in three ways:
+
+   * 'hledger run -- CMD1 -- CMD2 -- CMD3' - read commands from the
+     command line, separated by '--'
+   * 'hledger run SCRIPTFILE1 SCRIPTFILE2' - read commands from one or
+     more files
+   * 'cat SCRIPTFILE1 | hledger run' - read commands from standard
+     input.
+
+   'run' first loads the input file(s) specified by 'LEDGER_FILE' or by
+'-f' options, in the usual way.  Then it runs each command in turn, each
+using 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.
+
+   Each input file (more precisely, each combination of input file and
+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).
+
+   Command scripts, whether in a file or written on the command line,
+have a simple syntax:
+
+   * each line may contain a single hledger command and its arguments,
+     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.
+
+   On unix systems you can use '#!/usr/bin/env hledger run' in the first
+line of a command file to make it a runnable script.  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.
+
+   You may find some differences in behaviour between 'run' command
+lines and normal hledger command lines.  For example, with 'run',
+
+   * the command name must be written first, options afterward
+   * full command names or official abbreviations (as in the command
+     list) must be used
+
+* Menu:
+
+* Examples: Examples 2.
+
+
+File: hledger.info,  Node: Examples 2,  Up: run
+
+25.2.1 Examples
+---------------
+
+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
+
+   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 run 'stats' on 'some.journal'
+
+   Run commands from standard input:
+
+(echo "files"; echo "stats") | hledger -f some.journal run
+
+   Run commands as a script:
+
+$ cat report
+#!/usr/bin/env -S hledger run -f some.journal
+
+echo "List of accounts in some.journal"
+accounts
+
+echo "Assets of some.journal"
+balance assets --depth 2
+
+echo "Liabilities from /some/other.journal"
+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
+...
+
+
+File: hledger.info,  Node: ui,  Next: web,  Prev: run,  Up: User interface commands
+
+25.3 ui
+=======
+
+Runs hledger-ui (if installed).
+
+
+File: hledger.info,  Node: web,  Prev: ui,  Up: User interface commands
+
+25.4 web
+========
+
+Runs hledger-web (if installed).
+
+
+File: hledger.info,  Node: Data entry commands,  Next: Basic report commands,  Prev: User interface commands,  Up: Top
+
+26 Data entry commands
+**********************
+
+* Menu:
+
+* add::
+* import::
+
+
+File: hledger.info,  Node: add,  Next: import,  Up: Data entry commands
+
+26.1 add
+========
+
+Record new transactions with interactive prompting in the console.
+
+Flags:
+     --no-new-accounts      don't allow creating new accounts
+
+   Many hledger users edit their journals directly with a text editor,
+or generate them from CSV. For more interactive data entry, there is the
+'add' command, which prompts interactively on the console for new
+transactions, and appends them to the main journal file (which should be
+in journal format).  Existing transactions are not changed.  This is one
+of the few hledger commands that writes to the journal file (see also
+'import').
+
+   To use it, just run 'hledger add' and follow the prompts.  You can
+add as many transactions as you like; when you are finished, enter '.'
+or press control-d or control-c to exit.
+
+   Features:
+
+   * add tries to provide useful defaults, using the most similar (by
+     description) recent transaction (filtered by the query, if any) as
+     a template.
+   * You can also set the initial defaults with command line arguments.
+   * Readline-style edit keys can be used during data entry.
+   * The tab key will auto-complete whenever possible - accounts,
+     payees/descriptions, dates ('yesterday', 'today', 'tomorrow').  If
+     the input area is empty, it will insert the default value.
+   * A parenthesised transaction code may be entered following a date.
+   * Comments and tags may be entered following a description or amount.
+   * If you make a mistake, enter '<' at any prompt to go one step
+     backward.
+   * Input prompts are displayed in a different colour when the terminal
+     supports it.
+
+   Notes:
+
+   * If you enter a number with no commodity symbol, and you have
+     declared a default commodity with a 'D' directive, you might expect
+     'add' to add this symbol for you.  It does not do this; we assume
+     that if you are using a 'D' directive you prefer not to see the
+     commodity symbol repeated on amounts in the journal.
+
+   Examples:
+
+   * Record new transactions, saving to the default journal file:
+
+     'hledger add'
+
+   * Add transactions to 2024.journal, but also load 2023.journal for
+     completions:
+
+     'hledger add --file 2024.journal --file 2023.journal'
+
+   * Provide answers for the first four prompts:
+
+     'hledger add today 'best buy' expenses:supplies '$20''
+
+   There is a detailed tutorial at https://hledger.org/add.html.
+
+
+File: hledger.info,  Node: import,  Prev: add,  Up: Data entry commands
+
+26.2 import
+===========
+
+Import new transactions from one or more data files to the main journal.
+
+Flags:
+     --catchup              just mark all transactions as already imported
+     --dry-run              just show the transactions to be imported
+
+   This command detects new transactions in one or more data files
+specified as arguments, and appends them to the main journal.
+
+   You can import from any input file format hledger supports, but
+CSV/SSV/TSV files, downloaded from financial institutions, are the most
+common import source.
+
+   The import destination is the default journal file, or another
+specified in the usual way with '$LEDGER_FILE' or '-f/--file'.  It
+should be in journal format.
+
+   Examples:
+
+$ hledger import bank1-checking.csv bank1-savings.csv
+
+$ hledger import *.csv
+
+* Menu:
+
+* Import preview::
+* Overlap detection::
+* First import::
+* Importing balance assignments::
+* Import and commodity styles::
+* Import special cases::
+
+
+File: hledger.info,  Node: Import preview,  Next: Overlap detection,  Up: import
+
+26.2.1 Import preview
+---------------------
+
+It's useful to preview the import by running first with '--dry-run', to
+sanity check the range of dates being imported, and to check the effect
+of your conversion rules if converting from CSV. Eg:
+
+$ hledger import bank.csv --dry-run
+
+   The dry run output is valid journal format, so hledger can re-parse
+it.  If the output is large, you could show just the uncategorised
+transactions like so:
+
+$ hledger import --dry-run bank.csv | hledger -f- -I print unknown
+
+   You could also run this repeatedly to see the effect of edits to your
+conversion rules:
+
+$ watchexec -- 'hledger import --dry-run bank.csv | hledger -f- -I print unknown'
+
+   Once the conversion and dates look good enough to import to your
+journal, perhaps with some manual fixups to follow, you would do the
+actual import:
+
+$ hledger import bank.csv
+
+
+File: hledger.info,  Node: Overlap detection,  Next: First import,  Prev: Import preview,  Up: import
+
+26.2.2 Overlap detection
+------------------------
+
+Reading CSV files is built in to hledger, and not specific to 'import';
+so you could also import by doing 'hledger -f bank.csv print
+>>$LEDGER_FILE'.
+
+   But 'import' is easier and provides some advantages.  The main one is
+that it avoids re-importing transactions it has seen on previous runs.
+This means you don't have to worry about overlapping data in successive
+downloads of your bank CSV; just download and 'import' as often as you
+like, and only the new transactions will be imported each time.
+
+   We don't call this "deduplication", as it's generally not possible to
+reliably detect duplicates in bank CSV. Instead, 'import' remembers the
+latest date processed previously in each CSV file (saving it in a hidden
+file), and skips any records prior to that date.  This works well for
+most real-world CSV, where:
+
+  1. the data file name is stable (does not change) across imports
+  2. the item dates are stable across imports
+  3. the order of same-date items is stable across imports
+  4. the newest items have the newest dates
+
+   (Occasional violations of 2-4 are often harmless; you can reduce the
+chance of disruption by downloading and importing more often.)
+
+   Overlap detection is automatic, and shouldn't require much attention
+from you, except perhaps at first import (see below).  But here's how it
+works:
+
+   * For each 'FILE' being imported from:
+
+       1. hledger reads a file named '.latest.FILE' file in the same
+          directory, if any.  This file contains the latest record date
+          previously imported from FILE, in YYYY-MM-DD format.  If
+          multiple records with that date were imported, the date is
+          repeated on N lines.
+
+       2. hledger reads records from FILE. If a latest date was found in
+          step 1, any records before that date, and the first N records
+          on that date, are skipped.
+
+   * After a successful import from all FILEs, without error and without
+     '--dry-run', hledger updates each FILE's '.latest.FILE' for next
+     time.
+
+   If this goes wrong, it's relatively easy to repair:
+
+   * You'll notice it before import when you preview with 'import
+     --dry-run'.
+   * Or after import when you try to reconcile your hledger account
+     balances with your bank.
+   * 'hledger print -f FILE.csv' will show all recently downloaded
+     transactions.  Compare these with your journal.  Copy/paste if
+     needed.
+   * Update your conversion rules and print again, if needed.
+   * You can manually update or remove the .latest file, or use 'import
+     --catchup FILE'.
+   * Download and import more often, eg twice a week, at least while you
+     are learning.  It's easier to review and troubleshoot when there
+     are fewer transactions.
+
+
+File: hledger.info,  Node: First import,  Next: Importing balance assignments,  Prev: Overlap detection,  Up: import
+
+26.2.3 First import
+-------------------
+
+The first time you import from a file, when no corresponding .latest
+file has been created yet, all of the records will be imported.
+
+   But perhaps you have been entering the data manually, so you know
+that all of these transactions are already recorded in the journal.  In
+this case you can run 'hledger import --catchup' once.  This will create
+a .latest file containing the latest CSV record date, so that none of
+those records will be re-imported.
+
+   Or, if you know that some but not all of the transactions are in the
+journal, you can create the .latest file yourself.  Eg, let's say you
+previously recorded foobank transactions up to 2024-10-31 in the
+journal.  Then in the directory where you'll be saving 'foobank.csv',
+you would create a '.latest.foobank.csv' file containing
+
+2024-10-31
+
+   Or if you had three foobank transactions recorded with that date, you
+would repeat the date that many times:
+
+2024-10-31
+2024-10-31
+2024-10-31
+
+   Then 'hledger import foobank.csv [--dry-run]' will import only the
+newer records.
+
+
+File: hledger.info,  Node: Importing balance assignments,  Next: Import and commodity styles,  Prev: First import,  Up: import
+
+26.2.4 Importing balance assignments
+------------------------------------
+
+Journal entries added by import will have all posting amounts made
+explicit (like 'print -x').
+
+   This means that any balance assignments in the imported entries would
+need to be evaluated.  But this generally isn't possible, as the main
+file's account balances are not visible during import.  So try to avoid
+generating balance assignments with your CSV rules, or importing from a
+journal that contains balance assignments.  (Balance assignments are
+best avoided anyway.)
+
+   But if you must use them, eg because your CSV includes only balances:
+you can import with 'print', which leaves implicit amounts implicit.
+('print' can also do overlap detection like import, with the '--new'
+flag):
+
+$ hledger print --new -f bank.csv >> $LEDGER_FILE
+
+   (If you think 'import' should preserve implicit balances, please test
+that and send a pull request.)
+
+
+File: hledger.info,  Node: Import and commodity styles,  Next: Import special cases,  Prev: Importing balance assignments,  Up: import
+
+26.2.5 Import and commodity styles
+----------------------------------
+
+Amounts in entries added by import will be formatted according to the
+journal's canonical commodity styles, as declared by 'commodity'
+directives or inferred from the journal's amounts.
+
+   Related: CSV > Amount decimal places.
+
+
+File: hledger.info,  Node: Import special cases,  Prev: Import and commodity styles,  Up: import
+
+26.2.6 Import special cases
+---------------------------
+
+If you have a download whose file name varies, you could rename it to a
+fixed name after each download.  Or you could use a CSV 'source' rule
+with a suitable glob pattern, and import from the .rules file instead of
+the data file.
+
+   Here's a situation where you would need to run 'import' with care:
+say you download 'bank.csv', but forget to import it or delete it.  And
+next month you download it again.  This time your web browser may save
+it as 'bank (2).csv'.  So now each of these may have data not included
+in the other.  And a 'source' rule with a glob pattern would match only
+the most recent file.  So in this case you should import from each one
+in turn, in the correct order, taking care to use the same filename each
+time:
+
+$ hledger import bank.csv
+$ mv 'bank (2).csv' bank.csv
+$ hledger import bank.csv
+
+   Here are two kinds of "deduplication" which 'import' does not handle
+(and generally should not, since these can happen legitimately in
+financial data):
+
+   * Two or more of the new CSV records are identical, and generate
+     identical new journal entries.
+   * A new CSV record generates a journal entry identical to one(s)
+     already in the journal.
+
+
+File: hledger.info,  Node: Basic report commands,  Next: Standard report commands,  Prev: Data entry commands,  Up: Top
+
+27 Basic report commands
+************************
+
+* Menu:
+
+* accounts::
+* codes::
+* commodities::
+* descriptions::
+* files::
+* notes::
+* payees::
+* prices::
+* stats::
+* tags::
+
+
+File: hledger.info,  Node: accounts,  Next: codes,  Up: Basic report commands
+
+27.1 accounts
+=============
+
+List account names.
+
+Flags:
+  -u --used                 show only accounts used by transactions
+  -d --declared             show only accounts declared by account directive
+     --unused               show only accounts declared but not used
+     --undeclared           show only accounts used but not declared
+     --types                also show account types when known
+     --positions            also show where accounts were declared
+     --directives           show as account directives, for use in journals
+     --find                 find the first account matched by the first
+                            argument (a case-insensitive infix regexp or
+                            account name)
+  -l --flat                 show accounts as a flat list (default)
+  -t --tree                 show accounts as a tree
+     --drop=N               flat mode: omit N leading account name parts
+
+   This command lists account names.  By default it shows all known
+accounts, either used in transactions or declared with account
+directives.
+
+   With query arguments, only matched account names and account names
+referenced by matched postings are shown.
+
+   Or it can show just the used accounts ('--used'/'-u'), the declared
+accounts ('--declared'/'-d'), the accounts declared but not used
+('--unused'), the accounts used but not declared ('--undeclared'), or
+the first account matched by an account name pattern, if any ('--find').
+
+   It shows a flat list by default.  With '--tree', it uses indentation
+to show the account hierarchy.  In flat mode you can add '--drop N' to
+omit the first few account name components.  Account names can be
+depth-clipped with 'depth:N' or '--depth N' or '-N'.
+
+   With '--types', it also shows each account's type, if it's known.
+(See Declaring accounts > Account types.)
+
+   With '--positions', it also shows the file and line number of each
+account's declaration, if any, and the account's overall declaration
+order; these may be useful when troubleshooting account display order.
+
+   With '--directives', it adds the 'account' keyword, showing valid
+account directives which can be pasted into a journal file.  This is
+useful together with '--undeclared' when updating your account
+declarations to satisfy 'hledger check accounts'.
+
+   The '--find' flag can be used to look up a single account name, in
+the same way that the 'aregister' command does.  It returns the
+alphanumerically-first matched account name, or if none can be found, it
+fails with a non-zero exit code.
+
+   Examples:
+
+$ hledger accounts
+assets:bank:checking
+assets:bank:saving
+assets:cash
+expenses:food
+expenses:supplies
+income:gifts
+income:salary
+liabilities:debts
+
+$ hledger accounts --undeclared --directives >> $LEDGER_FILE
+$ hledger check accounts
+
+
+File: hledger.info,  Node: codes,  Next: commodities,  Prev: accounts,  Up: Basic report commands
+
+27.2 codes
+==========
+
+List the codes seen in transactions, in the order parsed.
+
+Flags:
+no command-specific flags
+
+   This command prints the value of each transaction's code field, in
+the order transactions were parsed.  The transaction code is an optional
+value written in parentheses between the date and description, often
+used to store a cheque number, order number or similar.
+
+   Transactions aren't required to have a code, and missing or empty
+codes will not be shown by default.  With the '-E'/'--empty' flag, they
+will be printed as blank lines.
+
+   You can add a query to select a subset of transactions.
+
+   Examples:
+
+2022/1/1 (123) Supermarket   
+ Food       $5.00
+ Checking    
+
+2022/1/2 (124) Post Office
+ Postage    $8.32
+ Checking
+
+2022/1/3 Supermarket
+ Food      $11.23
+ Checking 
+
+2022/1/4 (126) Post Office
+ Postage    $3.21
+ Checking
+
+$ hledger codes
+123
+124
+126
+
+$ hledger codes -E
+123
+124
+
+126
+
+
+File: hledger.info,  Node: commodities,  Next: descriptions,  Prev: codes,  Up: Basic report commands
+
+27.3 commodities
+================
+
+List all commodity/currency symbols used or declared in the journal.
+
+Flags:
+no command-specific flags
+
+
+File: hledger.info,  Node: descriptions,  Next: files,  Prev: commodities,  Up: Basic report commands
+
+27.4 descriptions
+=================
+
+List the unique descriptions that appear in transactions.
+
+Flags:
+no command-specific flags
+
+   This command lists the unique descriptions that appear in
+transactions, in alphabetic order.  You can add a query to select a
+subset of transactions.
+
+   Example:
+
+$ hledger descriptions
+Store Name
+Gas Station | Petrol
+Person A
+
+
+File: hledger.info,  Node: files,  Next: notes,  Prev: descriptions,  Up: Basic report commands
+
+27.5 files
+==========
+
+List all files included in the journal.  With a REGEX argument, only
+file names matching the regular expression (case sensitive) are shown.
+
+Flags:
+no command-specific flags
+
+
+File: hledger.info,  Node: notes,  Next: payees,  Prev: files,  Up: Basic report commands
+
+27.6 notes
+==========
+
+List the unique notes that appear in transactions.
+
+Flags:
+no command-specific flags
+
+   This command lists the unique notes that appear in transactions, in
+alphabetic order.  You can add a query to select a subset of
+transactions.  The note is the part of the transaction description after
+a | character (or if there is no |, the whole description).
+
+   Example:
+
+$ hledger notes
+Petrol
+Snacks
+
+
+File: hledger.info,  Node: payees,  Next: prices,  Prev: notes,  Up: Basic report commands
+
+27.7 payees
+===========
+
+List the unique payee/payer names that appear in transactions.
+
+Flags:
+     --declared             show payees declared with payee directives
+     --used                 show payees referenced by transactions
+
+   This command lists unique payee/payer names which have been declared
+with payee directives (-declared), used in transaction descriptions
+(-used), or both (the default).
+
+   The payee/payer is the part of the transaction description before a |
+character (or if there is no |, the whole description).
+
+   You can add query arguments to select a subset of transactions.  This
+implies -used.
+
+   Example:
+
+$ hledger payees
+Store Name
+Gas Station
+Person A
+
+
+File: hledger.info,  Node: prices,  Next: stats,  Prev: payees,  Up: Basic report commands
+
+27.8 prices
+===========
+
+Print the market prices declared with P directives.  With
+-infer-market-prices, also show any additional prices inferred from
+costs.  With -show-reverse, also show additional prices inferred by
+reversing known prices.
+
+Flags:
+     --show-reverse         also show the prices inferred by reversing known
+                            prices
+
+   Price amounts are always displayed with their full precision, except
+for reverse prices which are limited to 8 decimal digits.
+
+   Prices can be filtered by a date:, cur: or amt: query.
+
+   Generally if you run this command with -infer-market-prices
+-show-reverse, it will show the same prices used internally to calculate
+value reports.  But if in doubt, you can inspect those directly by
+running the value report with -debug=2.
+
+
+File: hledger.info,  Node: stats,  Next: tags,  Prev: prices,  Up: Basic report commands
+
+27.9 stats
+==========
+
+Show journal and performance statistics.
+
+Flags:
+  -v --verbose              show more detailed output
+  -o --output-file=FILE     write output to FILE.
+
+   The stats command shows summary information for the whole journal, or
+a matched part of it.  With a reporting interval, it shows a report for
+each report period.
+
+   The default output is fairly impersonal, though it reveals the main
+file name.  With '-v/--verbose', more details are shown, like file
+paths, included files, and commodity names.
+
+   It also shows some run time statistics:
+
+   * elapsed time
+   * throughput: the number of transactions processed per second
+   * live: the peak memory in use by the program to do its work
+   * alloc: the peak memory allocation from the OS as seen by GHC.
+     Measuring this externally, eg with GNU time, is more accurate;
+     usually that will be a larger number; sometimes (with swapping?)
+     smaller.
+
+   The 'stats' command's run time is similar to that of a balance
+report.
+
+   Example:
+
+$ hledger stats -f examples/1ktxns-1kaccts.journal 
+Main file           : .../1ktxns-1kaccts.journal
+Included files      : 0
+Txns span           : 2000-01-01 to 2002-09-27 (1000 days)
+Last txn            : 2002-09-26 (7827 days ago)
+Txns                : 1000 (1.0 per day)
+Txns last 30 days   : 0 (0.0 per day)
+Txns last 7 days    : 0 (0.0 per day)
+Payees/descriptions : 1000
+Accounts            : 1000 (depth 10)
+Commodities         : 26
+Market prices       : 1000
+Runtime stats       : 0.12 s elapsed, 8266 txns/s, 4 MB live, 16 MB alloc
+
+   This command supports the -o/-output-file option (but not
+-O/-output-format).
+
+
+File: hledger.info,  Node: tags,  Prev: stats,  Up: Basic report commands
+
+27.10 tags
+==========
+
+List the tags used in the journal, or their values.
+
+Flags:
+     --values               list tag values instead of tag names
+     --parsed               show tags/values in the order they were parsed,
+                            including duplicates
+
+   This command lists the tag names used in the journal, whether on
+transactions, postings, or account declarations.
+
+   With a TAGREGEX argument, only tag names matching this regular
+expression (case insensitive, infix matched) are shown.
+
+   With QUERY arguments, only transactions and accounts matching this
+query are considered.  If the query involves transaction fields (date:,
+desc:, amt:, ...), the search is restricted to the matched transactions
+and their accounts.
+
+   With the -values flag, the tags' unique non-empty values are listed
+instead.  With -E/-empty, blank/empty values are also shown.
+
+   With -parsed, tags or values are shown in the order they were parsed,
+with duplicates included.  (Except, tags from account declarations are
+always shown first.)
+
+   Tip: remember, accounts also acquire tags from their parents,
+postings also acquire tags from their account and transaction,
+transactions also acquire tags from their postings.
+
+
+File: hledger.info,  Node: Standard report commands,  Next: Advanced report commands,  Prev: Basic report commands,  Up: Top
+
+28 Standard report commands
+***************************
+
+* Menu:
+
+* print::
+* aregister::
+* register::
+* balancesheet::
+* balancesheetequity::
+* cashflow::
+* incomestatement::
+
+
+File: hledger.info,  Node: print,  Next: aregister,  Up: Standard report commands
+
+28.1 print
+==========
+
+Show full journal entries, representing transactions.
+
+Flags:
+  -x --explicit             show all amounts explicitly
+     --show-costs           show transaction prices even with conversion
+                            postings
+     --round=TYPE           how much rounding or padding should be done when
+                            displaying amounts ?
+                            none - show original decimal digits,
+                                   as in journal (default)
+                            soft - just add or remove decimal zeros
+                                   to match precision
+                            hard - round posting amounts to precision
+                                   (can unbalance transactions)
+                            all  - also round cost amounts to precision
+                                   (can unbalance transactions)
+     --invert               display all amounts with reversed sign
+     --new                  show only newer-dated transactions added in each
+                            file since last run
+  -m --match=DESC           fuzzy search for one recent transaction with
+                            description closest to DESC
+     --base-url=URLPREFIX   in html output, generate links to hledger-web,
+                            with this prefix. (Usually the base url shown by
+                            hledger-web; can also be relative.)
+  -O --output-format=FMT    select the output format. Supported formats:
+                            txt, beancount, csv, tsv, html, fods, json, sql.
+  -o --output-file=FILE     write output to FILE. A file extension matching
+                            one of the above formats selects that format.
+
+   The print command displays full journal entries (transactions) from
+the journal file, sorted by date (or with '--date2', by secondary date).
+
+   Directives and inter-transaction comments are not shown, currently.
+This means the print command is somewhat lossy, and if you are using it
+to reformat/regenerate your journal you should take care to also copy
+over the directives and inter-transaction comments.
+
+   Eg:
+
+$ hledger print -f examples/sample.journal date:200806
+2008/06/01 gift
+    assets:bank:checking            $1
+    income:gifts                   $-1
+
+2008/06/02 save
+    assets:bank:saving              $1
+    assets:bank:checking           $-1
+
+2008/06/03 * eat & shop
+    expenses:food                $1
+    expenses:supplies            $1
+    assets:cash                 $-2
+
+* Menu:
+
+* print explicitness::
+* print amount style::
+* print parseability::
+* print other features::
+* print output format::
+
+
+File: hledger.info,  Node: print explicitness,  Next: print amount style,  Up: print
+
+28.1.1 print explicitness
+-------------------------
+
+Normally, whether posting amounts are implicit or explicit is preserved.
+For example, when an amount is omitted in the journal, it will not
+appear in the output.  Similarly, if a conversion cost is implied but
+not written, it will not appear in the output.
+
+   You can use the '-x'/'--explicit' flag to force explicit display of
+all amounts and costs.  This can be useful for troubleshooting or for
+making your journal more readable and robust against data entry errors.
+'-x' is also implied by using any of '-B','-V','-X','--value'.
+
+   The '-x'/'--explicit' flag will cause any postings with a
+multi-commodity amount (which can arise when a multi-commodity
+transaction has an implicit amount) to be split into multiple
+single-commodity postings, keeping the output parseable.
+
+
+File: hledger.info,  Node: print amount style,  Next: print parseability,  Prev: print explicitness,  Up: print
+
+28.1.2 print amount style
+-------------------------
+
+Amounts are shown right-aligned within each transaction (but not aligned
+across all transactions; you can do that with ledger-mode in Emacs).
+
+   Amounts will be (mostly) normalised to their commodity display style:
+their symbol placement, decimal mark, and digit group marks will be made
+consistent.  By default, decimal digits are shown as they are written in
+the journal.
+
+   With the '--round' (_Added in 1.32_) option, 'print' will try
+increasingly hard to display decimal digits according to the commodity
+display styles:
+
+   * '--round=none' show amounts with original precisions (default)
+   * '--round=soft' add/remove decimal zeros in amounts (except costs)
+   * '--round=hard' round amounts (except costs), possibly hiding
+     significant digits
+   * '--round=all' round all amounts and costs
+
+   'soft' is good for non-lossy cleanup, formatting amounts more
+consistently where it's safe to do so.
+
+   'hard' and 'all' can cause 'print' to show invalid unbalanced journal
+entries; they may be useful eg for stronger cleanup, with manual fixups
+when needed.
+
+
+File: hledger.info,  Node: print parseability,  Next: print other features,  Prev: print amount style,  Up: print
+
+28.1.3 print parseability
+-------------------------
+
+print's output is usually a valid hledger journal, and you can process
+it again with a second hledger command.  This can be useful for certain
+kinds of search (though the same can be achieved with 'expr:' queries
+now):
+
+# Show running total of food expenses paid from cash.
+# -f- reads from stdin. -I/--ignore-assertions is sometimes needed.
+$ hledger print assets:cash | hledger -f- -I reg expenses:food
+
+   There are some situations where print's output can become
+unparseable:
+
+   * Value reporting affects posting amounts but not balance assertion
+     or balance assignment amounts, potentially causing those to fail.
+   * Auto postings can generate postings with too many missing amounts.
+   * Account aliases can generate bad account names.
+
+
+File: hledger.info,  Node: print other features,  Next: print output format,  Prev: print parseability,  Up: print
+
+28.1.4 print, other features
+----------------------------
+
+With '-B'/'--cost', amounts with costs are shown converted to cost.
+
+   With '--invert', posting amounts are shown with their sign flipped.
+It could be useful if you have accidentally recorded some transactions
+with the wrong signs.
+
+   With '--new', print shows only transactions it has not seen on a
+previous run.  This uses the same deduplication system as the 'import'
+command.  (See import's docs for details.)
+
+   With '-m DESC'/'--match=DESC', print shows one recent transaction
+whose description is most similar to DESC. DESC should contain at least
+two characters.  If there is no similar-enough match, no transaction
+will be shown and the program exit code will be non-zero.
+
+
+File: hledger.info,  Node: print output format,  Prev: print other features,  Up: print
+
+28.1.5 print output format
+--------------------------
+
+This command also supports the output destination and output format
+options The output formats supported are 'txt', 'beancount' (_Added in
+1.32_), 'csv', 'tsv' (_Added in 1.32_), 'json' and 'sql'.
+
+   The 'beancount' format tries to produce Beancount-compatible output,
+as follows:
+
+   * Transaction and postings with unmarked status are converted to
+     cleared ('*') status.
+   * Transactions' payee and note are backslash-escaped and
+     double-quote-escaped and wrapped in double quotes.
+   * Transaction tags are copied to Beancount #tag format.
+   * Commodity symbols are converted to upper case, and a small number
+     of currency symbols like '$' are converted to the corresponding
+     currency names.
+   * Account name parts are capitalised and unsupported characters are
+     replaced with '-'.  If an account name part does not begin with a
+     letter, or if the first part is not Assets, Liabilities, Equity,
+     Income, or Expenses, an error is raised.  (Use '--alias' options to
+     bring your accounts into compliance.)
+   * An 'open' directive is generated for each account used, on the
+     earliest transaction date.
+
+   Some limitations:
+
+   * Balance assertions are removed.
+   * Balance assignments become missing amounts.
+   * Virtual and balanced virtual postings become regular postings.
+   * Directives are not converted.
+
+   Here's an example of print's CSV output:
+
+$ hledger print -Ocsv
+"txnidx","date","date2","status","code","description","comment","account","amount","commodity","credit","debit","posting-status","posting-comment"
+"1","2008/01/01","","","","income","","assets:bank:checking","1","$","","1","",""
+"1","2008/01/01","","","","income","","income:salary","-1","$","1","","",""
+"2","2008/06/01","","","","gift","","assets:bank:checking","1","$","","1","",""
+"2","2008/06/01","","","","gift","","income:gifts","-1","$","1","","",""
+"3","2008/06/02","","","","save","","assets:bank:saving","1","$","","1","",""
+"3","2008/06/02","","","","save","","assets:bank:checking","-1","$","1","","",""
+"4","2008/06/03","","*","","eat & shop","","expenses:food","1","$","","1","",""
+"4","2008/06/03","","*","","eat & shop","","expenses:supplies","1","$","","1","",""
+"4","2008/06/03","","*","","eat & shop","","assets:cash","-2","$","2","","",""
+"5","2008/12/31","","*","","pay off","","liabilities:debts","1","$","","1","",""
+"5","2008/12/31","","*","","pay off","","assets:bank:checking","-1","$","1","","",""
+
+   * There is one CSV record per posting, with the parent transaction's
+     fields repeated.
+   * The "txnidx" (transaction index) field shows which postings belong
+     to the same transaction.  (This number might change if transactions
+     are reordered within the file, files are parsed/included in a
+     different order, etc.)
+   * The amount is separated into "commodity" (the symbol) and "amount"
+     (numeric quantity) fields.
+   * The numeric amount is repeated in either the "credit" or "debit"
+     column, for convenience.  (Those names are not accurate in the
+     accounting sense; it just puts negative amounts under credit and
+     zero or greater amounts under debit.)
+
+
+File: hledger.info,  Node: aregister,  Next: register,  Prev: print,  Up: Standard report commands
+
+28.2 aregister
+==============
+
+(areg)
+
+   Show the transactions and running balances in one account, with each
+transaction on one line.
+
+Flags:
+     --txn-dates            filter strictly by transaction date, not posting
+                            date. Warning: this can show a wrong running
+                            balance.
+     --no-elide             don't show only 2 commodities per amount
+     --cumulative           show running total from report start date
+  -H --historical           show historical running total/balance (includes
+                            postings before report start date) (default)
+     --invert               display all amounts with reversed sign
+     --heading=YN           show heading row above table: yes (default) or no
+  -w --width=N              set output width (default: terminal width). -wN,M
+                            sets description width as well.
+     --align-all            guarantee alignment across all lines (slower)
+  -O --output-format=FMT    select the output format. Supported formats:
+                            txt, html, csv, tsv, json.
+  -o --output-file=FILE     write output to FILE. A file extension matching
+                            one of the above formats selects that format.
+
+   'aregister' shows the overall transactions affecting a particular
+account (and any subaccounts).  Each report line represents one
+transaction in this account.  Transactions before the report start date
+are included in the running balance ('--historical' mode is the
+default).  You can suppress this behaviour using the '--cumulative'
+option.
+
+   This is a more "real world", bank-like view than the 'register'
+command (which shows individual postings, possibly from multiple
+accounts, not necessarily in historical mode).  As a quick rule of
+thumb: - use 'aregister' for reviewing and reconciling real-world
+asset/liability accounts - use 'register' for reviewing detailed
+revenues/expenses.
+
+   'aregister' requires one argument: the account to report on.  You can
+write either the full account name, or a case-insensitive regular
+expression which will select the alphabetically first matched account.
+
+   When there are multiple matches, the alphabetically-first choice can
+be surprising; eg if you have 'assets:per:checking 1' and
+'assets:biz:checking 2' accounts, 'hledger areg checking' would select
+'assets:biz:checking 2'.  It's just a convenience to save typing, so if
+in doubt, write the full account name, or a distinctive substring that
+matches uniquely.
+
+   Transactions involving subaccounts of this account will also be
+shown.  'aregister' ignores depth limits, so its final total will always
+match a balance report with similar arguments.
+
+   Any additional arguments form a query which will filter the
+transactions shown.  Note some queries will disturb the running balance,
+causing it to be different from the account's real-world running
+balance.
+
+   An example: this shows the transactions and historical running
+balance during july, in the first account whose name contains
+"checking":
+
+$ hledger areg checking date:jul
+
+   Each 'aregister' line item shows:
+
+   * the transaction's date (or the relevant posting's date if
+     different, see below)
+   * the names of all the other account(s) involved in this transaction
+     (probably abbreviated)
+   * the total change to this account's balance from this transaction
+   * the account's historical running balance after this transaction.
+
+   Transactions making a net change of zero are not shown by default;
+add the '-E/--empty' flag to show them.
+
+   For performance reasons, column widths are chosen based on the first
+1000 lines; this means unusually wide values in later lines can cause
+visual discontinuities as column widths are adjusted.  If you want to
+ensure perfect alignment, at the cost of more time and memory, use the
+'--align-all' flag.
+
+   By default, 'aregister' shows a heading above the data.  However,
+when reporting in a language different from English, it is easier to
+omit this heading and prepend your own one.  For this purpose, use the
+'--heading=no' option.
+
+   This command also supports the output destination and output format
+options.  The output formats supported are 'txt', 'csv', 'tsv' (_Added
+in 1.32_), 'html', 'fods' (_Added in 1.41_) and 'json'.
+
+* Menu:
+
+* aregister and posting dates::
+
+
+File: hledger.info,  Node: aregister and posting dates,  Up: aregister
+
+28.2.1 aregister and posting dates
+----------------------------------
+
+aregister always shows one line (and date and amount) per transaction.
+But sometimes transactions have postings with different dates.  Also,
+not all of a transaction's postings may be within the report period.  To
+resolve this, aregister shows the earliest of the transaction's date and
+posting dates that is in-period, and the sum of the in-period postings.
+In other words it will show a combined line item with just the earliest
+date, and the running balance will (temporarily, until the transaction's
+last posting) be inaccurate.  Use 'register -H' if you need to see the
+individual postings.
+
+   There is also a '--txn-dates' flag, which filters strictly by
+transaction date, ignoring posting dates.  This too can cause an
+inaccurate running balance.
+
+
+File: hledger.info,  Node: register,  Next: balancesheet,  Prev: aregister,  Up: Standard report commands
+
+28.3 register
+=============
+
+(reg)
+
+   Show postings and their running total.
+
+Flags:
+     --cumulative           show running total from report start date
+                            (default)
+  -H --historical           show historical running total/balance (includes
+                            postings before report start date)
+  -A --average              show running average of posting amounts instead
+                            of total (implies --empty)
+  -m --match=DESC           fuzzy search for one recent posting with
+                            description closest to DESC
+  -r --related              show postings' siblings instead
+     --invert               display all amounts with reversed sign
+     --sort=FIELDS          sort by: date, desc, account, amount, absamount,
+                            or a comma-separated combination of these. For a
+                            descending sort, prefix with -. (Default: date)
+  -w --width=N              set output width (default: terminal width). -wN,M
+                            sets description width as well.
+     --align-all            guarantee alignment across all lines (slower)
+     --base-url=URLPREFIX   in html output, generate links to hledger-web,
+                            with this prefix. (Usually the base url shown by
+                            hledger-web; can also be relative.)
+  -O --output-format=FMT    select the output format. Supported formats:
+                            txt, csv, tsv, html, fods, json.
+  -o --output-file=FILE     write output to FILE. A file extension matching
+                            one of the above formats selects that format.
+
+   The register command displays matched postings, across all accounts,
+in date order, with their running total or running historical balance.
+(See also the 'aregister' command, which shows matched transactions in a
+specific account.)
+
+   register normally shows line per posting, but note that
+multi-commodity amounts will occupy multiple lines (one line per
+commodity).
+
+   It is typically used with a query selecting a particular account, to
+see that account's activity:
+
+$ hledger register checking
+2008/01/01 income               assets:bank:checking            $1           $1
+2008/06/01 gift                 assets:bank:checking            $1           $2
+2008/06/02 save                 assets:bank:checking           $-1           $1
+2008/12/31 pay off              assets:bank:checking           $-1            0
+
+   With '--date2', it shows and sorts by secondary date instead.
+
+   For performance reasons, column widths are chosen based on the first
+1000 lines; this means unusually wide values in later lines can cause
+visual discontinuities as column widths are adjusted.  If you want to
+ensure perfect alignment, at the cost of more time and memory, use the
+'--align-all' flag.
+
+   The '--historical'/'-H' flag adds the balance from any undisplayed
+prior postings to the running total.  This is useful when you want to
+see only recent activity, with a historically accurate running balance:
+
+$ hledger register checking -b 2008/6 --historical
+2008/06/01 gift                 assets:bank:checking            $1           $2
+2008/06/02 save                 assets:bank:checking           $-1           $1
+2008/12/31 pay off              assets:bank:checking           $-1            0
+
+   The '--depth' option limits the amount of sub-account detail
+displayed.
+
+   The '--average'/'-A' flag shows the running average posting amount
+instead of the running total (so, the final number displayed is the
+average for the whole report period).  This flag implies '--empty' (see
+below).  It is affected by '--historical'.  It works best when showing
+just one account and one commodity.
+
+   The '--related'/'-r' flag shows the _other_ postings in the
+transactions of the postings which would normally be shown.
+
+   The '--invert' flag negates all amounts.  For example, it can be used
+on an income account where amounts are normally displayed as negative
+numbers.  It's also useful to show postings on the checking account
+together with the related account:
+
+   The '--sort=FIELDS' flag sorts by the fields given, which can be any
+of 'account', 'amount', 'absamount', 'date', or 'desc'/'description',
+optionally separated by commas.  For example, '--sort account,amount'
+will group all transactions in each account, sorted by transaction
+amount.  Each field can be negated by a preceding '-', so '--sort
+-amount' will show transactions ordered from smallest amount to largest
+amount.
+
+$ hledger register --related --invert assets:checking
+
+   With a reporting interval, register shows summary postings, one per
+interval, aggregating the postings to each account:
+
+$ hledger register --monthly income
+2008/01                 income:salary                          $-1          $-1
+2008/06                 income:gifts                           $-1          $-2
+
+   Periods with no activity, and summary postings with a zero amount,
+are not shown by default; use the '--empty'/'-E' flag to see them:
+
+$ hledger register --monthly income -E
+2008/01                 income:salary                          $-1          $-1
+2008/02                                                          0          $-1
+2008/03                                                          0          $-1
+2008/04                                                          0          $-1
+2008/05                                                          0          $-1
+2008/06                 income:gifts                           $-1          $-2
+2008/07                                                          0          $-2
+2008/08                                                          0          $-2
+2008/09                                                          0          $-2
+2008/10                                                          0          $-2
+2008/11                                                          0          $-2
+2008/12                                                          0          $-2
+
+   Often, you'll want to see just one line per interval.  The '--depth'
+option helps with this, causing subaccounts to be aggregated:
+
+$ hledger register --monthly assets --depth 1h
+2008/01                 assets                                  $1           $1
+2008/06                 assets                                 $-1            0
+2008/12                 assets                                 $-1          $-1
+
+   Note when using report intervals, if you specify start/end dates
+these will be adjusted outward if necessary to contain a whole number of
+intervals.  This ensures that the first and last intervals are full
+length and comparable to the others in the report.
+
+   With '-m DESC'/'--match=DESC', register does a fuzzy search for one
+recent posting whose description is most similar to DESC. DESC should
+contain at least two characters.  If there is no similar-enough match,
+no posting will be shown and the program exit code will be non-zero.
+
+* Menu:
+
+* Custom register output::
+
+
+File: hledger.info,  Node: Custom register output,  Up: register
+
+28.3.1 Custom register output
+-----------------------------
+
+register normally uses the full terminal width (or 80 columns if it
+can't detect that).  You can override this with 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
+description width as part of -width's argument, comma-separated:
+'--width W,D' .  Here's a diagram (won't display correctly in -help):
+
+<--------------------------------- width (W) ---------------------------------->
+date (10)  description (D)       account (W-41-D)     amount (12)   balance (12)
+DDDDDDDDDD dddddddddddddddddddd  aaaaaaaaaaaaaaaaaaa  AAAAAAAAAAAA  AAAAAAAAAAAA
+
+   and some examples:
+
+$ hledger reg                     # use terminal width (or 80 on windows)
+$ hledger reg -w 100              # use width 100
+$ hledger reg -w 100,40           # set overall width 100, 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_), and 'json'.
+
+
+File: hledger.info,  Node: balancesheet,  Next: balancesheetequity,  Prev: register,  Up: Standard report commands
+
+28.4 balancesheet
+=================
+
+(bs)
+
+   Show the end balances in asset and liability accounts.  Amounts are
+shown with normal positive sign, as in conventional financial
+statements.
+
+Flags:
+     --sum                  show sum of posting amounts (default)
+     --valuechange          show total change of period-end historical
+                            balance value (caused by deposits, withdrawals,
+                            market price fluctuations)
+     --gain                 show unrealised capital gain/loss (historical
+                            balance value minus cost basis)
+     --count                show the count of postings
+     --change               accumulate amounts from column start to column
+                            end (in multicolumn reports)
+     --cumulative           accumulate amounts from report start (specified
+                            by e.g. -b/--begin) to column end
+  -H --historical           accumulate amounts from journal start to column
+                            end (includes postings before report start date)
+                            (default)
+  -l --flat                 show accounts as a flat list (default). Amounts
+                            exclude subaccount amounts, except where the
+                            account is depth-clipped.
+  -t --tree                 show accounts as a tree. Amounts include
+                            subaccount amounts.
+     --drop=N               flat mode: omit N leading account name parts
+     --declared             include non-parent declared accounts (best used
+                            with -E)
+  -A --average              show a row average column (in multicolumn
+                            reports)
+  -T --row-total            show a row total column (in multicolumn reports)
+     --summary-only         display only row summaries (e.g. row total,
+                            average) (in multicolumn reports)
+  -N --no-total             omit the final total row
+     --no-elide             don't squash boring parent accounts (in tree
+                            mode)
+     --format=FORMATSTR     use this custom line format (in simple reports)
+  -S --sort-amount          sort by amount instead of account code/name
+  -% --percent              express values in percentage of each column's
+                            total
+     --layout=ARG           how to show multi-commodity amounts:
+                            'wide[,WIDTH]': all commodities on one line
+                            'tall'        : each commodity on a new line
+                            'bare'        : bare numbers, symbols in a column
+     --base-url=URLPREFIX   in html output, generate hyperlinks to
+                            hledger-web, with this prefix. (Usually the base
+                            url shown by hledger-web; can also be relative.)
+  -O --output-format=FMT    select the output format. Supported formats:
+                            txt, html, csv, tsv, json.
+  -o --output-file=FILE     write output to FILE. A file extension matching
+                            one of the above formats selects that format.
+
+   This command displays a balance sheet, showing historical ending
+balances of asset and liability accounts.  (To see equity as well, use
+the balancesheetequity command.)
+
+   Accounts declared with the 'Asset', 'Cash' or 'Liability' type are
+shown (see account types).  Or if no such accounts are declared, it
+shows top-level accounts named 'asset' or 'liability' (case insensitive,
+plurals allowed) and their subaccounts.
+
+   Example:
+
+$ hledger balancesheet
+Balance Sheet 2008-12-31
+
+                    || 2008-12-31 
+====================++============
+ Assets             ||            
+--------------------++------------
+ assets:bank:saving ||         $1 
+ assets:cash        ||        $-2 
+--------------------++------------
+                    ||        $-1 
+====================++============
+ Liabilities        ||            
+--------------------++------------
+ liabilities:debts  ||        $-1 
+--------------------++------------
+                    ||        $-1 
+====================++============
+ Net:               ||          0 
+
+   This command is a higher-level variant of the 'balance' command, and
+supports many of that command's features, such as multi-period reports.
+It is similar to 'hledger balance -H assets liabilities', but with
+smarter account detection, and liabilities displayed with their sign
+flipped.
+
+   This command also supports the output destination and output format
+options The output formats supported are 'txt', 'csv', 'tsv' (_Added in
+1.32_), 'html', and 'json'.
+
+
+File: hledger.info,  Node: balancesheetequity,  Next: cashflow,  Prev: balancesheet,  Up: Standard report commands
+
+28.5 balancesheetequity
+=======================
+
+(bse)
+
+   This command displays a balance sheet, showing historical ending
+balances of asset, liability and equity accounts.  Amounts are shown
+with normal positive sign, as in conventional financial statements.
+
+Flags:
+     --sum                  show sum of posting amounts (default)
+     --valuechange          show total change of period-end historical
+                            balance value (caused by deposits, withdrawals,
+                            market price fluctuations)
+     --gain                 show unrealised capital gain/loss (historical
+                            balance value minus cost basis)
+     --count                show the count of postings
+     --change               accumulate amounts from column start to column
+                            end (in multicolumn reports)
+     --cumulative           accumulate amounts from report start (specified
+                            by e.g. -b/--begin) to column end
+  -H --historical           accumulate amounts from journal start to column
+                            end (includes postings before report start date)
+                            (default)
+  -l --flat                 show accounts as a flat list (default). Amounts
+                            exclude subaccount amounts, except where the
+                            account is depth-clipped.
+  -t --tree                 show accounts as a tree. Amounts include
+                            subaccount amounts.
+     --drop=N               flat mode: omit N leading account name parts
+     --declared             include non-parent declared accounts (best used
+                            with -E)
+  -A --average              show a row average column (in multicolumn
+                            reports)
+  -T --row-total            show a row total column (in multicolumn reports)
+     --summary-only         display only row summaries (e.g. row total,
+                            average) (in multicolumn reports)
+  -N --no-total             omit the final total row
+     --no-elide             don't squash boring parent accounts (in tree
+                            mode)
+     --format=FORMATSTR     use this custom line format (in simple reports)
+  -S --sort-amount          sort by amount instead of account code/name
+  -% --percent              express values in percentage of each column's
+                            total
+     --layout=ARG           how to show multi-commodity amounts:
+                            'wide[,WIDTH]': all commodities on one line
+                            'tall'        : each commodity on a new line
+                            'bare'        : bare numbers, symbols in a column
+     --base-url=URLPREFIX   in html output, generate hyperlinks to
+                            hledger-web, with this prefix. (Usually the base
+                            url shown by hledger-web; can also be relative.)
+  -O --output-format=FMT    select the output format. Supported formats:
+                            txt, html, csv, tsv, json.
+  -o --output-file=FILE     write output to FILE. A file extension matching
+                            one of the above formats selects that format.
+
+   This report shows accounts declared with the 'Asset', 'Cash',
+'Liability' or 'Equity' type (see account types).  Or if no such
+accounts are declared, it shows top-level accounts named 'asset',
+'liability' or 'equity' (case insensitive, plurals allowed) and their
+subaccounts.
+
+   Example:
+
+$ hledger balancesheetequity
+Balance Sheet With Equity 2008-12-31
+
+                    || 2008-12-31 
+====================++============
+ Assets             ||            
+--------------------++------------
+ assets:bank:saving ||         $1 
+ assets:cash        ||        $-2 
+--------------------++------------
+                    ||        $-1 
+====================++============
+ Liabilities        ||            
+--------------------++------------
+ liabilities:debts  ||        $-1 
+--------------------++------------
+                    ||        $-1 
+====================++============
+ Equity             ||            
+--------------------++------------
+--------------------++------------
+                    ||          0 
+====================++============
+ Net:               ||          0 
+
+   This command is a higher-level variant of the 'balance' command, and
+supports many of that command's features, such as multi-period reports.
+It is similar to 'hledger balance -H assets liabilities equity', but
+with smarter account detection, and liabilities/equity displayed with
+their sign flipped.
+
+   This report is the easiest way to see if the accounting equation
+(A+L+E = 0) is satisfied (after you have done a 'close --retain' to
+merge revenues and expenses with equity, and perhaps added
+'--infer-equity' to balance your commodity conversions).
+
+   This command also supports the output destination and output format
+options The output formats supported are 'txt', 'csv', 'tsv', 'html',
+and 'json'.
+
+
+File: hledger.info,  Node: cashflow,  Next: incomestatement,  Prev: balancesheetequity,  Up: Standard report commands
+
+28.6 cashflow
+=============
+
+(cf)
+
+   This command displays a (simple) cashflow statement, showing the
+inflows and outflows affecting "cash" (ie, liquid, easily convertible)
+assets.  Amounts are shown with normal positive sign, as in conventional
+financial statements.
+
+Flags:
+     --sum                  show sum of posting amounts (default)
+     --valuechange          show total change of period-end historical
+                            balance value (caused by deposits, withdrawals,
+                            market price fluctuations)
+     --gain                 show unrealised capital gain/loss (historical
+                            balance value minus cost basis)
+     --count                show the count of postings
+     --change               accumulate amounts from column start to column
+                            end (in multicolumn reports) (default)
+     --cumulative           accumulate amounts from report start (specified
+                            by e.g. -b/--begin) to column end
+  -H --historical           accumulate amounts from journal start to column
+                            end (includes postings before report start date)
+  -l --flat                 show accounts as a flat list (default). Amounts
+                            exclude subaccount amounts, except where the
+                            account is depth-clipped.
+  -t --tree                 show accounts as a tree. Amounts include
+                            subaccount amounts.
+     --drop=N               flat mode: omit N leading account name parts
+     --declared             include non-parent declared accounts (best used
+                            with -E)
+  -A --average              show a row average column (in multicolumn
+                            reports)
+  -T --row-total            show a row total column (in multicolumn reports)
+     --summary-only         display only row summaries (e.g. row total,
+                            average) (in multicolumn reports)
+  -N --no-total             omit the final total row
+     --no-elide             don't squash boring parent accounts (in tree
+                            mode)
+     --format=FORMATSTR     use this custom line format (in simple reports)
+  -S --sort-amount          sort by amount instead of account code/name
+  -% --percent              express values in percentage of each column's
+                            total
+     --layout=ARG           how to show multi-commodity amounts:
+                            'wide[,WIDTH]': all commodities on one line
+                            'tall'        : each commodity on a new line
+                            'bare'        : bare numbers, symbols in a column
+     --base-url=URLPREFIX   in html output, generate hyperlinks to
+                            hledger-web, with this prefix. (Usually the base
+                            url shown by hledger-web; can also be relative.)
+  -O --output-format=FMT    select the output format. Supported formats:
+                            txt, html, csv, tsv, json.
+  -o --output-file=FILE     write output to FILE. A file extension matching
+                            one of the above formats selects that format.
+
+   This report shows accounts declared with the 'Cash' type (see account
+types).  Or if no such accounts are declared, it shows accounts
+
+   * under a top-level account named 'asset' (case insensitive, plural
+     allowed)
+   * whose name contains some variation of 'cash', 'bank', 'checking' or
+     'saving'.
+
+   More precisely: all accounts matching this case insensitive regular
+expression:
+
+   '^assets?(:.+)?:(cash|bank|che(ck|que?)(ing)?|savings?|currentcash)(:|$)'
+
+   and their subaccounts.
+
+   An example cashflow report:
+
+$ hledger cashflow
+Cashflow Statement 2008
+
+                    || 2008 
+====================++======
+ Cash flows         ||      
+--------------------++------
+ assets:bank:saving ||   $1 
+ assets:cash        ||  $-2 
+--------------------++------
+                    ||  $-1 
+
+   This command is a higher-level variant of the 'balance' command, and
+supports many of that command's features, such as multi-period reports.
+It is similar to 'hledger balance assets not:fixed not:investment
+not:receivable', but with smarter account detection.
+
+   This command also supports the output destination and output format
+options The output formats supported are 'txt', 'csv', 'tsv' (_Added in
+1.32_), 'html', and 'json'.
+
+
+File: hledger.info,  Node: incomestatement,  Prev: cashflow,  Up: Standard report commands
+
+28.7 incomestatement
+====================
+
+(is)
+
+   Show revenue inflows and expense outflows during the report period.
+Amounts are shown with normal positive sign, as in conventional
+financial statements.
+
+Flags:
+     --sum                  show sum of posting amounts (default)
+     --valuechange          show total change of period-end historical
+                            balance value (caused by deposits, withdrawals,
+                            market price fluctuations)
+     --gain                 show unrealised capital gain/loss (historical
+                            balance value minus cost basis)
+     --count                show the count of postings
+     --change               accumulate amounts from column start to column
+                            end (in multicolumn reports) (default)
+     --cumulative           accumulate amounts from report start (specified
+                            by e.g. -b/--begin) to column end
+  -H --historical           accumulate amounts from journal start to column
+                            end (includes postings before report start date)
+  -l --flat                 show accounts as a flat list (default). Amounts
+                            exclude subaccount amounts, except where the
+                            account is depth-clipped.
+  -t --tree                 show accounts as a tree. Amounts include
+                            subaccount amounts.
+     --drop=N               flat mode: omit N leading account name parts
+     --declared             include non-parent declared accounts (best used
+                            with -E)
+  -A --average              show a row average column (in multicolumn
+                            reports)
+  -T --row-total            show a row total column (in multicolumn reports)
+     --summary-only         display only row summaries (e.g. row total,
+                            average) (in multicolumn reports)
+  -N --no-total             omit the final total row
+     --no-elide             don't squash boring parent accounts (in tree
+                            mode)
+     --format=FORMATSTR     use this custom line format (in simple reports)
+  -S --sort-amount          sort by amount instead of account code/name
+  -% --percent              express values in percentage of each column's
+                            total
+     --layout=ARG           how to show multi-commodity amounts:
+                            'wide[,WIDTH]': all commodities on one line
+                            'tall'        : each commodity on a new line
+                            'bare'        : bare numbers, symbols in a column
+     --base-url=URLPREFIX   in html output, generate hyperlinks to
+                            hledger-web, with this prefix. (Usually the base
+                            url shown by hledger-web; can also be relative.)
+  -O --output-format=FMT    select the output format. Supported formats:
+                            txt, html, csv, tsv, json.
+  -o --output-file=FILE     write output to FILE. A file extension matching
+                            one of the above formats selects that format.
+
+   This command displays an income statement, showing revenues and
+expenses during one or more periods.
+
+   It shows accounts declared with the 'Revenue' or 'Expense' type (see
+account types).  Or if no such accounts are declared, it shows top-level
+accounts named 'revenue' or 'income' or 'expense' (case insensitive,
+plurals allowed) and their subaccounts.
+
+   Example:
+
+$ hledger incomestatement
+Income Statement 2008
+
+                   || 2008 
+===================++======
+ Revenues          ||      
+-------------------++------
+ income:gifts      ||   $1 
+ income:salary     ||   $1 
+-------------------++------
+                   ||   $2 
+===================++======
+ Expenses          ||      
+-------------------++------
+ expenses:food     ||   $1 
+ expenses:supplies ||   $1 
+-------------------++------
+                   ||   $2 
+===================++======
+ Net:              ||    0 
+
+   This command is a higher-level variant of the 'balance' command, and
+supports many of that command's features, such as multi-period reports.
+It is similar to 'hledger balance '(revenues|income)' expenses', but
+with smarter account detection, and revenues/income displayed with their
+sign flipped.
+
+   This command also supports the output destination and output format
+options The output formats supported are 'txt', 'csv', 'tsv' (_Added in
+1.32_), 'html', and 'json'.
+
+
+File: hledger.info,  Node: Advanced report commands,  Next: Chart commands,  Prev: Standard report commands,  Up: Top
+
+29 Advanced report commands
+***************************
+
+* Menu:
+
+* balance::
+* roi::
+
+
+File: hledger.info,  Node: balance,  Next: roi,  Up: Advanced report commands
+
+29.1 balance
+============
+
+(bal)
+
+   A flexible, general purpose "summing" report that shows accounts with
+some kind of numeric data.  This can be balance changes per period, end
+balances, budget performance, unrealised capital gains, etc.
+
+Flags:
+     --sum                  show sum of posting amounts (default)
+     --valuechange          show total change of value of period-end
+                            historical balances (caused by deposits,
+                            withdrawals, market price fluctuations)
+     --gain                 show unrealised capital gain/loss (historical
+                            balance value minus cost basis)
+     --budget[=DESCPAT]     show sum of posting amounts together with budget
+                            goals defined by periodic
+                            transactions. With a DESCPAT argument (must be
+                            separated by = not space),
+                            use only periodic transactions with matching
+                            description
+                            (case insensitive substring match).
+     --count                show the count of postings
+     --change               accumulate amounts from column start to column
+                            end (in multicolumn reports, default)
+     --cumulative           accumulate amounts from report start (specified
+                            by e.g. -b/--begin) to column end
+  -H --historical           accumulate amounts from journal start to column
+                            end (includes postings before report start date)
+  -l --flat                 show accounts as a flat list (default). Amounts
+                            exclude subaccount amounts, except where the
+                            account is depth-clipped.
+  -t --tree                 show accounts as a tree. Amounts include
+                            subaccount amounts.
+     --drop=N               omit N leading account name parts (in flat mode)
+     --declared             include non-parent declared accounts (best used
+                            with -E)
+  -A --average              show a row average column (in multicolumn
+                            reports)
+  -T --row-total            show a row total column (in multicolumn reports)
+     --summary-only         display only row summaries (e.g. row total,
+                            average) (in multicolumn reports)
+  -N --no-total             omit the final total row
+     --no-elide             don't squash boring parent accounts (in tree
+                            mode)
+     --format=FORMATSTR     use this custom line format (in simple reports)
+  -S --sort-amount          sort by amount instead of account code/name (in
+                            flat mode). With multiple columns, sorts by the row
+                            total, or by row average if that is displayed.
+  -% --percent              express values in percentage of each column's
+                            total
+  -r --related              show the other accounts transacted with, instead
+     --invert               display all amounts with reversed sign
+     --transpose            switch rows and columns (use vertical time axis)
+     --layout=ARG           how to lay out multi-commodity amounts and the
+                            overall table:
+                            'wide[,W]': commodities on same line, up to W wide
+                            'tall'    : commodities on separate lines
+                            'bare'    : commodity symbols in a separate column
+                            'tidy'    : each data field in its own column
+     --base-url=URLPREFIX   in html output, generate links to hledger-web,
+                            with this prefix. (Usually the base url shown by
+                            hledger-web; can also be relative.)
+  -O --output-format=FMT    select the output format. Supported formats:
+                            txt, html, csv, tsv, json, fods.
+  -o --output-file=FILE     write output to FILE. A file extension matching
+                            one of the above formats selects that format.
+
+   'balance' is one of hledger's oldest and most versatile commands, for
+listing account balances, balance changes, values, value changes and
+more, during one time period or many.  Generally it shows a table, with
+rows representing accounts, and columns representing periods.
+
+   Note there are some higher-level variants of the 'balance' command
+with convenient defaults, which can be simpler to use: 'balancesheet',
+'balancesheetequity', 'cashflow' and 'incomestatement'.  When you need
+more control, then use 'balance'.
+
+* Menu:
+
+* balance features::
+* Simple balance report::
+* Balance report line format::
+* Filtered balance report::
+* List or tree mode::
+* Depth limiting::
+* Dropping top-level accounts::
+* Showing declared accounts::
+* Sorting by amount::
+* Percentages::
+* Multi-period balance report::
+* Balance change end balance::
+* Balance report types::
+* Budget report::
+* Balance report layout::
+* Balance report output::
+* Some useful balance reports::
+
+
+File: hledger.info,  Node: balance features,  Next: Simple balance report,  Up: balance
+
+29.1.1 balance features
+-----------------------
+
+Here's a quick overview of the 'balance' command's features, followed by
+more detailed descriptions and examples.  Many of these work with the
+higher-level commands as well.
+
+   'balance' can show..
+
+   * accounts as a list ('-l') or a tree ('-t')
+   * optionally depth-limited ('-[1-9]')
+   * sorted by declaration order and name, or by amount
+
+   ..and their..
+
+   * balance changes (the default)
+   * or actual and planned balance changes ('--budget')
+   * or value of balance changes ('-V')
+   * or change of balance values ('--valuechange')
+   * or unrealised capital gain/loss ('--gain')
+   * or balance changes from sibling postings ('--related'/'-r')
+   * or postings count ('--count')
+
+   ..in..
+
+   * one time period (the whole journal period by default)
+   * or multiple periods ('-D', '-W', '-M', '-Q', '-Y', '-p INTERVAL')
+
+   ..either..
+
+   * per period (the default)
+   * or accumulated since report start date ('--cumulative')
+   * or accumulated since account creation ('--historical/-H')
+
+   ..possibly converted to..
+
+   * cost ('--value=cost[,COMM]'/'--cost'/'-B')
+   * or market value, as of transaction dates ('--value=then[,COMM]')
+   * or at period ends ('--value=end[,COMM]')
+   * or now ('--value=now')
+   * or at some other date ('--value=YYYY-MM-DD')
+
+   ..with..
+
+   * totals ('-T'), averages ('-A'), percentages ('-%'), inverted sign
+     ('--invert')
+   * rows and columns swapped ('--transpose')
+   * another field used as account name ('--pivot')
+   * custom-formatted line items (single-period reports only)
+     ('--format')
+   * commodities displayed on the same line or multiple lines
+     ('--layout')
+
+   This command supports the output destination and output format
+options, with output formats 'txt', 'csv', 'tsv' (_Added in 1.32_),
+'json', and (multi-period reports only:) 'html', 'fods' (_Added in
+1.40_).  In 'txt' output in a colour-supporting terminal, negative
+amounts are shown in red.
+
+
+File: hledger.info,  Node: Simple balance report,  Next: Balance report line format,  Prev: balance features,  Up: balance
+
+29.1.2 Simple balance report
+----------------------------
+
+With no arguments, 'balance' shows a list of all accounts and their
+change of balance - ie, the sum of posting amounts, both inflows and
+outflows - during the entire period of the journal.  ("Simple" here
+means just one column of numbers, covering a single period.  You can
+also have multi-period reports, described later.)
+
+   For real-world accounts, these numbers will normally be their end
+balance at the end of the journal period; more on this below.
+
+   Accounts are sorted by declaration order if any, and then
+alphabetically by account name.  For instance (using
+examples/sample.journal):
+
+$ hledger -f examples/sample.journal bal
+                  $1  assets:bank:saving
+                 $-2  assets:cash
+                  $1  expenses:food
+                  $1  expenses:supplies
+                 $-1  income:gifts
+                 $-1  income:salary
+                  $1  liabilities:debts
+--------------------
+                   0  
+
+   Accounts with a zero balance (and no non-zero subaccounts, in tree
+mode - see below) are hidden by default.  Use '-E/--empty' to show them
+(revealing 'assets:bank:checking' here):
+
+$ hledger -f examples/sample.journal bal  -E
+                   0  assets:bank:checking
+                  $1  assets:bank:saving
+                 $-2  assets:cash
+                  $1  expenses:food
+                  $1  expenses:supplies
+                 $-1  income:gifts
+                 $-1  income:salary
+                  $1  liabilities:debts
+--------------------
+                   0  
+
+   The total of the amounts displayed is shown as the last line, unless
+'-N'/'--no-total' is used.
+
+
+File: hledger.info,  Node: Balance report line format,  Next: Filtered balance report,  Prev: Simple balance report,  Up: balance
+
+29.1.3 Balance report line format
+---------------------------------
+
+For single-period balance reports displayed in the terminal (only), you
+can use '--format FMT' to customise the format and content of each line.
+Eg:
+
+$ hledger -f examples/sample.journal balance --format "%20(account) %12(total)"
+              assets          $-1
+         bank:saving           $1
+                cash          $-2
+            expenses           $2
+                food           $1
+            supplies           $1
+              income          $-2
+               gifts          $-1
+              salary          $-1
+   liabilities:debts           $1
+---------------------------------
+                                0
+
+   The FMT format string specifies the formatting applied to each
+account/balance pair.  It may contain any suitable text, with data
+fields interpolated like so:
+
+   '%[MIN][.MAX](FIELDNAME)'
+
+   * MIN pads with spaces to at least this width (optional)
+
+   * MAX truncates at this width (optional)
+
+   * FIELDNAME must be enclosed in parentheses, and can be one of:
+
+        * 'depth_spacer' - a number of spaces equal to the account's
+          depth, or if MIN is specified, MIN * depth spaces.
+        * 'account' - the account's name
+        * 'total' - the account's balance/posted total, right justified
+
+   Also, FMT can begin with an optional prefix to control how
+multi-commodity amounts are rendered:
+
+   * '%_' - render on multiple lines, bottom-aligned (the default)
+   * '%^' - render on multiple lines, top-aligned
+   * '%,' - render on one line, comma-separated
+
+   There are some quirks.  Eg in one-line mode, '%(depth_spacer)' has no
+effect, instead '%(account)' has indentation built in.  Experimentation
+may be needed to get pleasing results.
+
+   Some example formats:
+
+   * '%(total)' - the account's total
+   * '%-20.20(account)' - the account's name, left justified, padded to
+     20 characters and clipped at 20 characters
+   * '%,%-50(account) %25(total)' - account name padded to 50
+     characters, total padded to 20 characters, with multiple
+     commodities rendered on one line
+   * '%20(total) %2(depth_spacer)%-(account)' - the default format for
+     the single-column balance report
+
+
+File: hledger.info,  Node: Filtered balance report,  Next: List or tree mode,  Prev: Balance report line format,  Up: balance
+
+29.1.4 Filtered balance report
+------------------------------
+
+You can show fewer accounts, a different time period, totals from
+cleared transactions only, etc.  by using query arguments or options to
+limit the postings being matched.  Eg:
+
+$ hledger -f examples/sample.journal bal --cleared assets date:200806
+                 $-2  assets:cash
+--------------------
+                 $-2  
+
+
+File: hledger.info,  Node: List or tree mode,  Next: Depth limiting,  Prev: Filtered balance report,  Up: balance
+
+29.1.5 List or tree mode
+------------------------
+
+By default, or with '-l/--flat', accounts are shown as a flat list with
+their full names visible, as in the examples above.
+
+   With '-t/--tree', the account hierarchy is shown, with subaccounts'
+"leaf" names indented below their parent:
+
+$ hledger -f examples/sample.journal balance
+                 $-1  assets
+                  $1    bank:saving
+                 $-2    cash
+                  $2  expenses
+                  $1    food
+                  $1    supplies
+                 $-2  income
+                 $-1    gifts
+                 $-1    salary
+                  $1  liabilities:debts
+--------------------
+                   0
+
+   Notes:
+
+   * "Boring" accounts are combined with their subaccount for more
+     compact output, unless '--no-elide' is used.  Boring accounts have
+     no balance of their own and just one subaccount (eg 'assets:bank'
+     and 'liabilities' above).
+
+   * All balances shown are "inclusive", ie including the balances from
+     all subaccounts.  Note this means some repetition in the output,
+     which requires explanation when sharing reports with
+     non-plaintextaccounting-users.  A tree mode report's final total is
+     the sum of the top-level balances shown, not of all the balances
+     shown.
+
+   * Each group of sibling accounts (ie, under a common parent) is
+     sorted separately.
+
+
+File: hledger.info,  Node: Depth limiting,  Next: Dropping top-level accounts,  Prev: List or tree mode,  Up: balance
+
+29.1.6 Depth limiting
+---------------------
+
+With a 'depth:NUM' query, or '--depth NUM' option, or just '-NUM' (eg:
+'-3') balance reports will show accounts only to the specified depth,
+hiding the deeper subaccounts.  This can be useful for getting an
+overview without too much detail.
+
+   Account balances at the depth limit always include the balances from
+any deeper subaccounts (even in list mode).  Eg, limiting to depth 1:
+
+$ hledger -f examples/sample.journal balance -1
+                 $-1  assets
+                  $2  expenses
+                 $-2  income
+                  $1  liabilities
+--------------------
+                   0  
+
+
+File: hledger.info,  Node: Dropping top-level accounts,  Next: Showing declared accounts,  Prev: Depth limiting,  Up: balance
+
+29.1.7 Dropping top-level accounts
+----------------------------------
+
+You can also hide one or more top-level account name parts, using
+'--drop NUM'.  This can be useful for hiding repetitive top-level
+account names:
+
+$ hledger -f examples/sample.journal bal expenses --drop 1
+                  $1  food
+                  $1  supplies
+--------------------
+                  $2  
+
+
+File: hledger.info,  Node: Showing declared accounts,  Next: Sorting by amount,  Prev: Dropping top-level accounts,  Up: balance
+
+29.1.8 Showing declared accounts
+--------------------------------
+
+With '--declared', accounts which have been declared with an account
+directive will be included in the balance report, even if they have no
+transactions.  (Since they will have a zero balance, you will also need
+'-E/--empty' to see them.)
+
+   More precisely, _leaf_ declared accounts (with no subaccounts) will
+be included, since those are usually the more useful in reports.
+
+   The idea of this is to be able to see a useful "complete" balance
+report, even when you don't have transactions in all of your declared
+accounts yet.
+
+
+File: hledger.info,  Node: Sorting by amount,  Next: Percentages,  Prev: Showing declared accounts,  Up: balance
+
+29.1.9 Sorting by amount
+------------------------
+
+With '-S/--sort-amount', accounts with the largest (most positive)
+balances are shown first.  Eg: 'hledger bal expenses -MAS' shows your
+biggest averaged monthly expenses first.  When more than one commodity
+is present, they will be sorted by the alphabetically earliest commodity
+first, and then by subsequent commodities (if an amount is missing a
+commodity, it is treated as 0).
+
+   Revenues and liability balances are typically negative, however, so
+'-S' shows these in reverse order.  To work around this, you can add
+'--invert' to flip the signs.  (Or, use one of the higher-level reports,
+which flip the sign automatically.  Eg: 'hledger incomestatement -MAS').
+
+
+File: hledger.info,  Node: Percentages,  Next: Multi-period balance report,  Prev: Sorting by amount,  Up: balance
+
+29.1.10 Percentages
+-------------------
+
+With '-%/--percent', balance reports show each account's value expressed
+as a percentage of the (column) total.
+
+   Note it is not useful to calculate percentages if the amounts in a
+column have mixed signs.  In this case, make a separate report for each
+sign, eg:
+
+$ hledger bal -% amt:`>0`
+$ hledger bal -% amt:`<0`
+
+   Similarly, if the amounts in a column have mixed commodities, convert
+them to one commodity with '-B', '-V', '-X' or '--value', or make a
+separate report for each commodity:
+
+$ hledger bal -% cur:\\$
+$ hledger bal -% cur:€
+
+
+File: hledger.info,  Node: Multi-period balance report,  Next: Balance change end balance,  Prev: Percentages,  Up: balance
+
+29.1.11 Multi-period balance report
+-----------------------------------
+
+With a report interval (set by the '-D/--daily', '-W/--weekly',
+'-M/--monthly', '-Q/--quarterly', '-Y/--yearly', or '-p/--period' flag),
+'balance' shows a tabular report, with columns representing successive
+time periods (and a title):
+
+$ hledger -f examples/sample.journal bal --quarterly income expenses -E
+Balance changes in 2008:
+
+                   ||  2008q1  2008q2  2008q3  2008q4 
+===================++=================================
+ expenses:food     ||       0      $1       0       0 
+ expenses:supplies ||       0      $1       0       0 
+ income:gifts      ||       0     $-1       0       0 
+ income:salary     ||     $-1       0       0       0 
+-------------------++---------------------------------
+                   ||     $-1      $1       0       0 
+
+   Notes:
+
+   * The report's start/end dates will be expanded, if necessary, to
+     fully encompass the displayed subperiods (so that the first and
+     last subperiods have the same duration as the others).
+   * Leading and trailing periods (columns) containing all zeroes are
+     not shown, unless '-E/--empty' is used.
+   * Accounts (rows) containing all zeroes are not shown, unless
+     '-E/--empty' is used.
+   * Amounts with many commodities are shown in abbreviated form, unless
+     '--no-elide' is used.
+   * Average and/or total columns can be added with the '-A/--average'
+     and '-T/--row-total' flags.
+   * The '--transpose' flag can be used to exchange rows and columns.
+   * The '--pivot FIELD' option causes a different transaction field to
+     be used as "account name".  See PIVOTING.
+   * The '--summary-only' flag ('--summary' also works) hides all but
+     the Total and Average columns (those should be enabled with
+     '--row-total' and '-A/--average').
+
+   Multi-period reports with many periods can be too wide for easy
+viewing in the terminal.  Here are some ways to handle that:
+
+   * Hide the totals row with '-N/--no-total'
+   * Filter to a single currency with 'cur:'
+   * Convert to a single currency with '-V [--infer-market-price]'
+   * Use a more compact layout like '--layout=bare'
+   * Maximize the terminal window
+   * Reduce the terminal's font size
+   * View with a pager like less, eg: 'hledger bal -D --color=yes | less
+     -RS'
+   * Output as CSV and use a CSV viewer like visidata ('hledger bal -D
+     -O csv | vd -f csv'), Emacs' csv-mode ('M-x csv-mode, C-c C-a'), or
+     a spreadsheet ('hledger bal -D -o a.csv && open a.csv')
+   * Output as HTML and view with a browser: 'hledger bal -D -o a.html
+     && open a.html'
+
+
+File: hledger.info,  Node: Balance change end balance,  Next: Balance report types,  Prev: Multi-period balance report,  Up: balance
+
+29.1.12 Balance change, end balance
+-----------------------------------
+
+It's important to be clear on the meaning of the numbers shown in
+balance reports.  Here is some terminology we use:
+
+   A *_balance change_* is the net amount added to, or removed from, an
+account during some period.
+
+   An *_end balance_* is the amount accumulated in an account as of some
+date (and some time, but hledger doesn't store that; assume end of day
+in your timezone).  It is the sum of previous balance changes.
+
+   We call it a *_historical end balance_* if it includes all balance
+changes since the account was created.  For a real world account, this
+means it will match the "historical record", eg the balances reported in
+your bank statements or bank web UI. (If they are correct!)
+
+   In general, balance changes are what you want to see when reviewing
+revenues and expenses, and historical end balances are what you want to
+see when reviewing or reconciling asset, liability and equity accounts.
+
+   'balance' shows balance changes by default.  To see accurate
+historical end balances:
+
+  1. Initialise account starting balances with an "opening balances"
+     transaction (a transfer from equity to the account), unless the
+     journal covers the account's full lifetime.
+
+  2. Include all of of the account's prior postings in the report, by
+     not specifying a report start date, or by using the
+     '-H/--historical' flag.  ('-H' causes report start date to be
+     ignored when summing postings.)
+
+
+File: hledger.info,  Node: Balance report types,  Next: Budget report,  Prev: Balance change end balance,  Up: balance
+
+29.1.13 Balance report types
+----------------------------
+
+The balance command is quite flexible; here is the full detail on how to
+control what it reports.  If the following seems complicated, don't
+worry - this is for advanced reporting, and it does take time and
+experimentation to get familiar with all the report modes.
+
+   There are three important option groups:
+
+   'hledger balance [CALCULATIONTYPE] [ACCUMULATIONTYPE] [VALUATIONTYPE]
+...'
+
+* Menu:
+
+* Calculation type::
+* Accumulation type::
+* Valuation type::
+* Combining balance report types::
+
+
+File: hledger.info,  Node: Calculation type,  Next: Accumulation type,  Up: Balance report types
+
+29.1.13.1 Calculation type
+..........................
+
+The basic calculation to perform for each table cell.  It is one of:
+
+   * '--sum' : sum the posting amounts (*default*)
+   * '--budget' : sum the amounts, but also show the budget goal amount
+     (for each account/period)
+   * '--valuechange' : show the change in period-end historical balance
+     values (caused by deposits, withdrawals, and/or market price
+     fluctuations)
+   * '--gain' : show the unrealised capital gain/loss, (the current
+     valued balance minus each amount's original cost)
+   * '--count' : show the count of postings
+
+
+File: hledger.info,  Node: Accumulation type,  Next: Valuation type,  Prev: Calculation type,  Up: Balance report types
+
+29.1.13.2 Accumulation type
+...........................
+
+How amounts should accumulate across a report's subperiods/columns.
+Another way to say it: which time period's postings should contribute to
+each cell's calculation.  It is one of:
+
+   * '--change' : calculate with postings from column start to column
+     end, ie "just this column".  Typically used to see
+     revenues/expenses.  (*default for balance, cashflow,
+     incomestatement*)
+
+   * '--cumulative' : calculate with postings from report start to
+     column end, ie "previous columns plus this column".  Typically used
+     to show changes accumulated since the report's start date.  Not
+     often used.
+
+   * '--historical/-H' : calculate with postings from journal start to
+     column end, ie "all postings from before report start date until
+     this column's end".  Typically used to see historical end balances
+     of assets/liabilities/equity.  (*default for balancesheet,
+     balancesheetequity*)
+
+
+File: hledger.info,  Node: Valuation type,  Next: Combining balance report types,  Prev: Accumulation type,  Up: Balance report types
+
+29.1.13.3 Valuation type
+........................
+
+Which kind of value or cost conversion should be applied, if any, before
+displaying the report.  It is one of:
+
+   * no valuation type : don't convert to cost or value (*default*)
+   * '--value=cost[,COMM]' : convert amounts to cost (then optionally to
+     some other commodity)
+   * '--value=then[,COMM]' : convert amounts to market value on
+     transaction dates
+   * '--value=end[,COMM]' : convert amounts to market value on period
+     end date(s)
+     (*default with '--valuechange', '--gain'*)
+   * '--value=now[,COMM]' : convert amounts to market value on today's
+     date
+   * '--value=YYYY-MM-DD[,COMM]' : convert amounts to market value on
+     another date
+
+   or one of the equivalent simpler flags:
+
+   * '-B/--cost' : like -value=cost (though, note -cost and -value are
+     independent options which can both be used at once)
+   * '-V/--market' : like -value=end
+   * '-X COMM/--exchange COMM' : like -value=end,COMM
+
+   See Cost reporting and Value reporting for more about these.
+
+
+File: hledger.info,  Node: Combining balance report types,  Prev: Valuation type,  Up: Balance report types
+
+29.1.13.4 Combining balance report types
+........................................
+
+Most combinations of these options should produce reasonable reports,
+but if you find any that seem wrong or misleading, let us know.  The
+following restrictions are applied:
+
+   * '--valuechange' implies '--value=end'
+   * '--valuechange' makes '--change' the default when used with the
+     'balancesheet'/'balancesheetequity' commands
+   * '--cumulative' or '--historical' disables '--row-total/-T'
+
+   For reference, here is what the combinations of accumulation and
+valuation show:
+
+Valuation:>no valuation    '--value= then'   '--value= end'   '--value=
+Accumulation:v                                                YYYY-MM-DD
+                                                              /now'
+-----------------------------------------------------------------------------
+'--change'change in        sum of            period-end       DATE-value
+         period            posting-date      value of         of change in
+                           market values     change in        period
+                           in period         period
+'--cumulative'change from  sum of            period-end       DATE-value
+         report start to   posting-date      value of         of change
+         period end        market values     change from      from report
+                           from report       report start     start to
+                           start to period   to period end    period end
+                           end
+'--historicalchange from   sum of            period-end       DATE-value
+/-H'     journal start     posting-date      value of         of change
+         to period end     market values     change from      from journal
+         (historical end   from journal      journal start    start to
+         balance)          start to period   to period end    period end
+                           end
+
+
+File: hledger.info,  Node: Budget report,  Next: Balance report layout,  Prev: Balance report types,  Up: balance
+
+29.1.14 Budget report
+---------------------
+
+The '--budget' report type is like a regular balance report, but with
+two main differences:
+
+   * Budget goals and performance percentages are also shown, in
+     brackets
+   * Accounts which don't have budget goals are hidden by default.
+
+   This is useful for comparing planned and actual income, expenses,
+time usage, etc.
+
+   Periodic transaction rules are used to define budget goals.  For
+example, here's a periodic rule defining monthly goals for bus travel
+and food expenses:
+
+;; Budget
+~ monthly
+  (expenses:bus)              $30
+  (expenses:food)            $400
+
+   After recording some actual expenses,
+
+;; Two months worth of expenses
+2017-11-01
+  income                   $-1950
+  expenses:bus                $35
+  expenses:food:groceries    $310
+  expenses:food:dining        $42
+  expenses:movies             $38
+  assets:bank:checking
+
+2017-12-01
+  income                   $-2100
+  expenses:bus                $53
+  expenses:food:groceries    $380
+  expenses:food:dining        $32
+  expenses:gifts             $100
+  assets:bank:checking
+
+   we can see a budget report like this:
+
+$ hledger bal -M --budget
+Budget performance in 2017-11-01..2017-12-31:
+
+               ||                  Nov                   Dec 
+===============++============================================
+ <unbudgeted>  || $-425                 $-565                
+ expenses      ||  $425 [ 99% of $430]   $565 [131% of $430] 
+ expenses:bus  ||   $35 [117% of  $30]    $53 [177% of  $30] 
+ expenses:food ||  $352 [ 88% of $400]   $412 [103% of $400] 
+---------------++--------------------------------------------
+               ||     0 [  0% of $430]      0 [  0% of $430] 
+
+   This is "goal-based budgeting"; you define goals for accounts and
+periods, often recurring, and hledger shows performance relative to the
+goals.  This contrasts with "envelope budgeting", which is more detailed
+and strict - useful when cash is tight, but also quite a bit more work.
+https://plaintextaccounting.org/Budgeting has more on this topic.
+
+* Menu:
+
+* Using the budget report::
+* Budget date surprises::
+* Selecting budget goals::
+* Budgeting vs forecasting::
+
+
+File: hledger.info,  Node: Using the budget report,  Next: Budget date surprises,  Up: Budget report
+
+29.1.14.1 Using the budget report
+.................................
+
+Historically this report has been confusing and fragile.  hledger's
+version should be relatively robust and intuitive, but you may still
+find surprises.  Here are more notes to help with learning and
+troubleshooting.
+
+   * In the above example, 'expenses:bus' and 'expenses:food' are shown
+     because they have budget goals during the report period.
+
+   * Their parent 'expenses' is also shown, with budget goals aggregated
+     from the children.
+
+   * The subaccounts 'expenses:food:groceries' and
+     'expenses:food:dining' are not shown since they have no budget goal
+     of their own, but they contribute to 'expenses:food''s actual
+     amount.
+
+   * Unbudgeted accounts 'expenses:movies' and 'expenses:gifts' are also
+     not shown, but they contribute to 'expenses''s actual amount.
+
+   * The other unbudgeted accounts 'income' and 'assets:bank:checking'
+     are grouped as '<unbudgeted>'.
+
+   * '--depth' or 'depth:' can be used to limit report depth in the
+     usual way (but will not reveal unbudgeted subaccounts).
+
+   * Amounts are always inclusive of subaccounts (even in '-l/--list'
+     mode).
+
+   * Numbers displayed in a -budget report will not always agree with
+     the totals, because of hidden unbudgeted accounts; this is normal.
+     '-E/--empty' can be used to reveal the hidden accounts.
+
+   * In the periodic rules used for setting budget goals, unbalanced
+     postings are convenient.
+
+   * You can filter budget reports with the usual queries, eg to focus
+     on particular accounts.  It's common to restrict them to just
+     expenses.  (The '<unbudgeted>' account is occasionally hard to
+     exclude; this is because of date surprises, discussed below.)
+
+   * When you have multiple currencies, you may want to convert them to
+     one ('-X COMM --infer-market-prices') and/or show just one at a
+     time ('cur:COMM').  If you do need to show multiple currencies at
+     once, '--layout bare' can be helpful.
+
+   * You can "roll over" amounts (actual and budgeted) to the next
+     period with '--cumulative'.
+
+   See also: https://hledger.org/budgeting.html.
+
+
+File: hledger.info,  Node: Budget date surprises,  Next: Selecting budget goals,  Prev: Using the budget report,  Up: Budget report
+
+29.1.14.2 Budget date surprises
+...............................
+
+With small data, or when starting out, some of the generated budget goal
+transaction dates might fall outside the report periods.  Eg with the
+following journal and report, the first period appears to have no
+'expenses:food' budget.  (Also the '<unbudgeted>' account should be
+excluded by the 'expenses' query, but isn't.):
+
+~ monthly in 2020
+  (expenses:food)  $500
+
+2020-01-15
+  expenses:food    $400
+  assets:checking
+
+$ hledger bal --budget expenses
+Budget performance in 2020-01-15:
+
+               ||         2020-01-15 
+===============++====================
+ <unbudgeted>  || $400               
+ expenses:food ||    0 [ 0% of $500] 
+---------------++--------------------
+               || $400 [80% of $500] 
+
+   In this case, the budget goal transactions are generated on first
+days of of month (this can be seen with 'hledger print --forecast
+tag:generated expenses').  Whereas the report period defaults to just
+the 15th day of january (this can be seen from the report table's column
+headings).
+
+   To fix this kind of thing, be more explicit about the report period
+(and/or the periodic rules' dates).  In this case, adding '-b 2020' does
+the trick.
+
+
+File: hledger.info,  Node: Selecting budget goals,  Next: Budgeting vs forecasting,  Prev: Budget date surprises,  Up: Budget report
+
+29.1.14.3 Selecting budget goals
+................................
+
+By default, the budget report uses all available periodic transaction
+rules to generate goals.  This includes rules with a different report
+interval from your report.  Eg if you have daily, weekly and monthly
+periodic rules, all of these will contribute to the goals in a monthly
+budget report.
+
+   You can select a subset of periodic rules by providing an argument to
+the '--budget' flag.  '--budget=DESCPAT' will match all periodic rules
+whose description contains DESCPAT, a case-insensitive substring (not a
+regular expression or query).  This means you can give your periodic
+rules descriptions (remember that two spaces are needed between period
+expression and description), and then select from multiple budgets
+defined in your journal.
+
+
+File: hledger.info,  Node: Budgeting vs forecasting,  Prev: Selecting budget goals,  Up: Budget report
+
+29.1.14.4 Budgeting vs forecasting
+..................................
+
+'--forecast' and '--budget' both use the periodic transaction rules in
+the journal to generate temporary transactions for reporting purposes.
+However they are separate features - though you can use both at the same
+time if you want.  Here are some differences between them:
+
+-forecast                                -budget
+--------------------------------------------------------------------------
+is a general option; it enables          is a balance command option;
+forecasting with all reports             it selects the balance
+                                         report's budget mode
+generates visible transactions which     generates invisible
+appear in reports                        transactions which produce
+                                         goal amounts
+generates forecast transactions from     generates budget goal
+after the last regular transaction, to   transactions throughout the
+the end of the report period; or with    report period, optionally
+an argument '--forecast=PERIODEXPR'      restricted by periods
+generates them throughout the            specified in the periodic
+specified period, both optionally        transaction rules
+restricted by periods specified in the
+periodic transaction rules
+uses all periodic rules                  uses all periodic rules; or
+                                         with an argument
+                                         '--budget=DESCPAT' uses just
+                                         the rules matched by DESCPAT
+
+
+File: hledger.info,  Node: Balance report layout,  Next: Balance report output,  Prev: Budget report,  Up: balance
+
+29.1.15 Balance report layout
+-----------------------------
+
+The '--layout' option affects how 'balance' and the other balance-like
+commands show multi-commodity amounts and commodity symbols.  It can
+improve readability, for humans and/or machines (other software).  It
+has four possible values:
+
+   * '--layout=wide[,WIDTH]': commodities are shown on a single line,
+     optionally elided to WIDTH
+   * '--layout=tall': each commodity is shown on a separate line
+   * '--layout=bare': commodity symbols are in their own column, amounts
+     are bare numbers
+   * '--layout=tidy': data is normalised to easily-consumed "tidy" form,
+     with one row per data value.  (This one is currently supported only
+     by the 'balance' command.)
+
+   Here are the '--layout' modes supported by each output format Only
+CSV output supports all of them:
+
+-      txt   csv   html   json   sql
+---------------------------------------
+wide   Y     Y     Y
+tall   Y     Y     Y
+bare   Y     Y     Y
+tidy         Y
+
+   Examples:
+
+* Menu:
+
+* Wide layout::
+* Tall layout::
+* Bare layout::
+* Tidy layout::
+
+
+File: hledger.info,  Node: Wide layout,  Next: Tall layout,  Up: Balance report layout
+
+29.1.15.1 Wide layout
+.....................
+
+With many commodities, reports can be very wide:
+
+$ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=wide
+Balance changes in 2012-01-01..2014-12-31:
+
+                  ||                                          2012                                                     2013                                             2014                                                      Total 
+==================++====================================================================================================================================================================================================================
+ Assets:US:ETrade || 10.00 ITOT, 337.18 USD, 12.00 VEA, 106.00 VHT  70.00 GLD, 18.00 ITOT, -98.12 USD, 10.00 VEA, 18.00 VHT  -11.00 ITOT, 4881.44 USD, 14.00 VEA, 170.00 VHT  70.00 GLD, 17.00 ITOT, 5120.50 USD, 36.00 VEA, 294.00 VHT 
+------------------++--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+                  || 10.00 ITOT, 337.18 USD, 12.00 VEA, 106.00 VHT  70.00 GLD, 18.00 ITOT, -98.12 USD, 10.00 VEA, 18.00 VHT  -11.00 ITOT, 4881.44 USD, 14.00 VEA, 170.00 VHT  70.00 GLD, 17.00 ITOT, 5120.50 USD, 36.00 VEA, 294.00 VHT 
+
+   A width limit reduces the width, but some commodities will be hidden:
+
+$ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=wide,32
+Balance changes in 2012-01-01..2014-12-31:
+
+                  ||                             2012                             2013                   2014                            Total 
+==================++===========================================================================================================================
+ Assets:US:ETrade || 10.00 ITOT, 337.18 USD, 2 more..  70.00 GLD, 18.00 ITOT, 3 more..  -11.00 ITOT, 3 more..  70.00 GLD, 17.00 ITOT, 3 more.. 
+------------------++---------------------------------------------------------------------------------------------------------------------------
+                  || 10.00 ITOT, 337.18 USD, 2 more..  70.00 GLD, 18.00 ITOT, 3 more..  -11.00 ITOT, 3 more..  70.00 GLD, 17.00 ITOT, 3 more.. 
+
+
+File: hledger.info,  Node: Tall layout,  Next: Bare layout,  Prev: Wide layout,  Up: Balance report layout
+
+29.1.15.2 Tall layout
+.....................
+
+Each commodity gets a new line (may be different in each column), and
+account names are repeated:
+
+$ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=tall
+Balance changes in 2012-01-01..2014-12-31:
+
+                  ||       2012        2013         2014        Total 
+==================++==================================================
+ Assets:US:ETrade || 10.00 ITOT   70.00 GLD  -11.00 ITOT    70.00 GLD 
+ Assets:US:ETrade || 337.18 USD  18.00 ITOT  4881.44 USD   17.00 ITOT 
+ Assets:US:ETrade ||  12.00 VEA  -98.12 USD    14.00 VEA  5120.50 USD 
+ Assets:US:ETrade || 106.00 VHT   10.00 VEA   170.00 VHT    36.00 VEA 
+ Assets:US:ETrade ||              18.00 VHT                294.00 VHT 
+------------------++--------------------------------------------------
+                  || 10.00 ITOT   70.00 GLD  -11.00 ITOT    70.00 GLD 
+                  || 337.18 USD  18.00 ITOT  4881.44 USD   17.00 ITOT 
+                  ||  12.00 VEA  -98.12 USD    14.00 VEA  5120.50 USD 
+                  || 106.00 VHT   10.00 VEA   170.00 VHT    36.00 VEA 
+                  ||              18.00 VHT                294.00 VHT 
+
+
+File: hledger.info,  Node: Bare layout,  Next: Tidy layout,  Prev: Tall layout,  Up: Balance report layout
+
+29.1.15.3 Bare layout
+.....................
+
+Commodity symbols are kept in one column, each commodity has its own
+row, amounts are bare numbers, account names are repeated:
+
+$ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=bare
+Balance changes in 2012-01-01..2014-12-31:
+
+                  || Commodity    2012    2013     2014    Total 
+==================++=============================================
+ Assets:US:ETrade || GLD             0   70.00        0    70.00 
+ Assets:US:ETrade || ITOT        10.00   18.00   -11.00    17.00 
+ Assets:US:ETrade || USD        337.18  -98.12  4881.44  5120.50 
+ Assets:US:ETrade || VEA         12.00   10.00    14.00    36.00 
+ Assets:US:ETrade || VHT        106.00   18.00   170.00   294.00 
+------------------++---------------------------------------------
+                  || GLD             0   70.00        0    70.00 
+                  || ITOT        10.00   18.00   -11.00    17.00 
+                  || USD        337.18  -98.12  4881.44  5120.50 
+                  || VEA         12.00   10.00    14.00    36.00 
+                  || VHT        106.00   18.00   170.00   294.00 
+
+   Bare layout also affects CSV output, which is useful for producing
+data that is easier to consume, eg for making charts:
+
+$ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -O csv --layout=bare
+"account","commodity","balance"
+"Assets:US:ETrade","GLD","70.00"
+"Assets:US:ETrade","ITOT","17.00"
+"Assets:US:ETrade","USD","5120.50"
+"Assets:US:ETrade","VEA","36.00"
+"Assets:US:ETrade","VHT","294.00"
+"Total:","GLD","70.00"
+"Total:","ITOT","17.00"
+"Total:","USD","5120.50"
+"Total:","VEA","36.00"
+"Total:","VHT","294.00"
+
+   Bare layout will sometimes display an extra row for the no-symbol
+commodity, because of zero amounts (hledger treats zeroes as
+commodity-less, usually).  This can break 'hledger-bar' confusingly
+(workaround: add a 'cur:' query to exclude the no-symbol row).
+
+
+File: hledger.info,  Node: Tidy layout,  Prev: Bare layout,  Up: Balance report layout
+
+29.1.15.4 Tidy layout
+.....................
+
+This produces normalised "tidy data" (see
+https://cran.r-project.org/web/packages/tidyr/vignettes/tidy-data.html)
+where every variable has its own column and each row represents a single
+data point.  This is the easiest kind of data for other software to
+consume:
+
+$ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -Y -O csv --layout=tidy
+"account","period","start_date","end_date","commodity","value"
+"Assets:US:ETrade","2012","2012-01-01","2012-12-31","GLD","0"
+"Assets:US:ETrade","2012","2012-01-01","2012-12-31","ITOT","10.00"
+"Assets:US:ETrade","2012","2012-01-01","2012-12-31","USD","337.18"
+"Assets:US:ETrade","2012","2012-01-01","2012-12-31","VEA","12.00"
+"Assets:US:ETrade","2012","2012-01-01","2012-12-31","VHT","106.00"
+"Assets:US:ETrade","2013","2013-01-01","2013-12-31","GLD","70.00"
+"Assets:US:ETrade","2013","2013-01-01","2013-12-31","ITOT","18.00"
+"Assets:US:ETrade","2013","2013-01-01","2013-12-31","USD","-98.12"
+"Assets:US:ETrade","2013","2013-01-01","2013-12-31","VEA","10.00"
+"Assets:US:ETrade","2013","2013-01-01","2013-12-31","VHT","18.00"
+"Assets:US:ETrade","2014","2014-01-01","2014-12-31","GLD","0"
+"Assets:US:ETrade","2014","2014-01-01","2014-12-31","ITOT","-11.00"
+"Assets:US:ETrade","2014","2014-01-01","2014-12-31","USD","4881.44"
+"Assets:US:ETrade","2014","2014-01-01","2014-12-31","VEA","14.00"
+"Assets:US:ETrade","2014","2014-01-01","2014-12-31","VHT","170.00"
+
+
+File: hledger.info,  Node: Balance report output,  Next: Some useful balance reports,  Prev: Balance report layout,  Up: balance
+
+29.1.16 Balance report output
+-----------------------------
+
+As noted in Output format, if you choose HTML output (by using '-O html'
+or '-o somefile.html'), it will use the UTF-8 text encoding, And you can
+create a 'hledger.css' file in the same directory to customise the
+report's appearance.
+
+   The HTML and FODS output formats can generate hyperlinks to a
+'hledger-web' register view for each account and period.  E.g.  if your
+'hledger-web' server is reachable at 'http://localhost:5000' then you
+might run the 'balance' command with the extra option
+'--base-url=http://localhost:5000'.  You can also produce relative
+links, like '--base-url="some/path"' or '--base-url=""'.)
+
+
+File: hledger.info,  Node: Some useful balance reports,  Prev: Balance report output,  Up: balance
+
+29.1.17 Some useful balance reports
+-----------------------------------
+
+Some frequently used 'balance' options/reports are:
+
+   * 'bal -M revenues expenses'
+     Show revenues/expenses in each month.  Also available as the
+     'incomestatement' command.
+
+   * 'bal -M -H assets liabilities'
+     Show historical asset/liability balances at each month end.  Also
+     available as the 'balancesheet' command.
+
+   * 'bal -M -H assets liabilities equity'
+     Show historical asset/liability/equity balances at each month end.
+     Also available as the 'balancesheetequity' command.
+
+   * 'bal -M assets not:receivable'
+     Show changes to liquid assets in each month.  Also available as the
+     'cashflow' command.
+
+   Also:
+
+   * 'bal -M expenses -2 -SA'
+     Show monthly expenses summarised to depth 2 and sorted by average
+     amount.
+
+   * 'bal -M --budget expenses'
+     Show monthly expenses and budget goals.
+
+   * 'bal -M --valuechange investments'
+     Show monthly change in market value of investment assets.
+
+   * 'bal investments --valuechange -D date:lastweek amt:'>1000' -STA
+     [--invert]'
+     Show top gainers [or losers] last week
+
+
+File: hledger.info,  Node: roi,  Prev: balance,  Up: Advanced report commands
+
+29.2 roi
+========
+
+Shows the time-weighted (TWR) and money-weighted (IRR) rate of return on
+your investments.
+
+Flags:
+     --cashflow                 show all amounts that were used to compute
+                                returns
+     --investment=QUERY         query to select your investment transactions
+     --profit-loss=QUERY --pnl  query to select profit-and-loss or
+                                appreciation/valuation transactions
+
+   At a minimum, you need to supply a query (which could be just an
+account name) to select your investment(s) with '--inv', and another
+query to identify your profit and loss transactions with '--pnl'.
+
+   If you do not record changes in the value of your investment
+manually, or do not require computation of time-weighted return (TWR),
+'--pnl' could be an empty query ('--pnl ""' or '--pnl STR' where 'STR'
+does not match any of your accounts).
+
+   This command will compute and display the internalized rate of return
+(IRR, also known as money-weighted rate of return) and time-weighted
+rate of return (TWR) for your investments for the time period requested.
+IRR is always annualized due to the way it is computed, but TWR is
+reported both as a rate over the chosen reporting period and as an
+annual rate.
+
+   Price directives will be taken into account if you supply appropriate
+'--cost' or '--value' flags (see VALUATION).
+
+   Note, in some cases this report can fail, for these reasons:
+
+   * Error (NotBracketed): No solution for Internal Rate of Return
+     (IRR). Possible causes: IRR is huge (>1000000%), balance of
+     investment becomes negative at some point in time.
+   * Error (SearchFailed): Failed to find solution for Internal Rate of
+     Return (IRR). Either search does not converge to a solution, or
+     converges too slowly.
+
+   Examples:
+
+   * Using roi to compute total return of investment in stocks:
+     https://github.com/simonmichael/hledger/blob/master/examples/investing/roi-unrealised.ledger
+
+   * Cookbook > Return on Investment: https://hledger.org/roi.html
+
+* Menu:
+
+* Spaces and special characters in --inv and --pnl::
+* Semantics of --inv and --pnl::
+* IRR and TWR explained::
+
+
+File: hledger.info,  Node: Spaces and special characters in --inv and --pnl,  Next: Semantics of --inv and --pnl,  Up: roi
+
+29.2.1 Spaces and special characters in '--inv' and
+---------------------------------------------------
+
+'--pnl' Note that '--inv' and '--pnl''s argument is a query, and queries
+could have several space-separated terms (see QUERIES).
+
+   To indicate that all search terms form single command-line argument,
+you will need to put them in quotes (see Special characters):
+
+$ hledger roi --inv 'term1 term2 term3 ...'
+
+   If any query terms contain spaces themselves, you will need an extra
+level of nested quoting, eg:
+
+$ hledger roi --inv="'Assets:Test 1'" --pnl="'Equity:Unrealized Profit and Loss'"
+
+
+File: hledger.info,  Node: Semantics of --inv and --pnl,  Next: IRR and TWR explained,  Prev: Spaces and special characters in --inv and --pnl,  Up: roi
+
+29.2.2 Semantics of '--inv' and '--pnl'
+---------------------------------------
+
+Query supplied to '--inv' has to match all transactions that are related
+to your investment.  Transactions not matching '--inv' will be ignored.
+
+   In these transactions, ROI will conside postings that match '--inv'
+to be "investment postings" and other postings (not matching '--inv')
+will be sorted into two categories: "cash flow" and "profit and loss",
+as ROI needs to know which part of the investment value is your
+contributions and which is due to the return on investment.
+
+   * "Cash flow" is depositing or withdrawing money, buying or selling
+     assets, or otherwise converting between your investment commodity
+     and any other commodity.  Example:
+
+     2019-01-01 Investing in Snake Oil
+       assets:cash          -$100
+       investment:snake oil
+     
+     2020-01-01 Selling my Snake Oil
+       assets:cash           $10
+       investment:snake oil  = 0
+
+   * "Profit and loss" is change in the value of your investment:
+
+     2019-06-01 Snake Oil falls in value
+       investment:snake oil  = $57
+       equity:unrealized profit or loss
+
+   All non-investment postings are assumed to be "cash flow", unless
+they match '--pnl' query.  Changes in value of your investment due to
+"profit and loss" postings will be considered as part of your investment
+return.
+
+   Example: if you use '--inv snake --pnl equity:unrealized', then
+postings in the example below would be classifed as:
+
+2019-01-01 Snake Oil #1
+  assets:cash          -$100   ; cash flow posting
+  investment:snake oil         ; investment posting
+
+2019-03-01 Snake Oil #2
+  equity:unrealized pnl  -$100 ; profit and loss posting
+  snake oil                    ; investment posting
+
+2019-07-01 Snake Oil #3
+  equity:unrealized pnl        ; profit and loss posting
+  cash          -$100          ; cash flow posting
+  snake oil     $50            ; investment posting
+
+
+File: hledger.info,  Node: IRR and TWR explained,  Prev: Semantics of --inv and --pnl,  Up: roi
+
+29.2.3 IRR and TWR explained
+----------------------------
+
+"ROI" stands for "return on investment".  Traditionally this was
+computed as a difference between current value of investment and its
+initial value, expressed in percentage of the initial value.
+
+   However, this approach is only practical in simple cases, where
+investments receives no in-flows or out-flows of money, and where rate
+of growth is fixed over time.  For more complex scenarios you need
+different ways to compute rate of return, and this command implements
+two of them: IRR and TWR.
+
+   Internal rate of return, or "IRR" (also called "money-weighted rate
+of return") takes into account effects of in-flows and out-flows, and
+the time between them.  Investment at a particular fixed interest rate
+is going to give you more interest than the same amount invested at the
+same interest rate, but made later in time.  If you are withdrawing from
+your investment, your future gains would be smaller (in absolute
+numbers), and will be a smaller percentage of your initial investment,
+so your IRR will be smaller.  And if you are adding to your investment,
+you will receive bigger absolute gains, which will be a bigger
+percentage of your initial investment, so your IRR will be larger.
+
+   As mentioned before, in-flows and out-flows would be any cash that
+you personally put in or withdraw, and for the "roi" command, these are
+the postings that match the query in the'--inv' argument and NOT match
+the query in the'--pnl' argument.
+
+   If you manually record changes in the value of your investment as
+transactions that balance them against "profit and loss" (or "unrealized
+gains") account or use price directives, then in order for IRR to
+compute the precise effect of your in-flows and out-flows on the rate of
+return, you will need to record the value of your investement on or
+close to the days when in- or out-flows occur.
+
+   In technical terms, IRR uses the same approach as computation of net
+present value, and tries to find a discount rate that makes net present
+value of all the cash flows of your investment to add up to zero.  This
+could be hard to wrap your head around, especially if you haven't done
+discounted cash flow analysis before.  Implementation of IRR in hledger
+should produce results that match the '=XIRR' formula in Excel.
+
+   Second way to compute rate of return that 'roi' command implements is
+called "time-weighted rate of return" or "TWR". Like IRR, it will
+account for the effect of your in-flows and out-flows, but unlike IRR it
+will try to compute the true rate of return of the underlying asset,
+compensating for the effect that deposits and withdrawas have on the
+apparent rate of growth of your investment.
+
+   TWR represents your investment as an imaginary "unit fund" where
+in-flows/ out-flows lead to buying or selling "units" of your investment
+and changes in its value change the value of "investment unit".  Change
+in "unit price" over the reporting period gives you rate of return of
+your investment, and make TWR less sensitive than IRR to the effects of
+cash in-flows and out-flows.
+
+   References:
+
+   * Explanation of rate of return
+   * Explanation of IRR
+   * Explanation of TWR
+   * IRR vs TWR
+   * Examples of computing IRR and TWR and discussion of the limitations
+     of both metrics
+
+
+File: hledger.info,  Node: Chart commands,  Next: Data generation commands,  Prev: Advanced report commands,  Up: Top
+
+30 Chart commands
+*****************
+
+* Menu:
+
+* activity::
+
+
+File: hledger.info,  Node: activity,  Up: Chart commands
+
+30.1 activity
+=============
+
+Show an ascii barchart of posting counts per interval.
+
+Flags:
+no command-specific flags
+
+   The activity command displays an ascii histogram showing transaction
+counts by day, week, month or other reporting interval (by day is the
+default).  With query arguments, it counts only matched transactions.
+
+   Examples:
+
+$ hledger activity --quarterly
+2008-01-01 **
+2008-04-01 *******
+2008-07-01 
+2008-10-01 **
+
+
+File: hledger.info,  Node: Data generation commands,  Next: Maintenance commands,  Prev: Chart commands,  Up: Top
+
+31 Data generation commands
+***************************
+
+* Menu:
+
+* close::
+* rewrite::
+
+
+File: hledger.info,  Node: close,  Next: rewrite,  Up: Data generation commands
+
+31.1 close
+==========
+
+(equity)
+
+   'close' prints several kinds of "closing" and/or "opening"
+transactions, useful in various situations: migrating balances to a new
+journal file, retaining earnings into equity, consolidating balances,
+viewing lot costs..  Like 'print', it prints valid journal entries.  You
+can copy these into your journal file(s) when you are happy with how
+they look.
+
+Flags:
+     --clopen[=TAGVAL]      show closing and opening balances transactions,
+                            for AL accounts by default
+     --close[=TAGVAL]       show just a closing balances transaction
+     --open[=TAGVAL]        show just an opening balances transaction
+     --assert[=TAGVAL]      show a balance assertions transaction
+     --assign[=TAGVAL]      show a balance assignments transaction
+     --retain[=TAGVAL]      show a retain earnings transaction, for RX
+                            accounts by default
+  -x --explicit             show all amounts explicitly
+     --show-costs           show amounts with different costs separately
+     --interleaved          show source and destination postings together
+     --assertion-type=TYPE  =, ==, =* or ==*
+     --close-desc=DESC      set closing transaction's description
+     --close-acct=ACCT      set closing transaction's destination account
+     --open-desc=DESC       set opening transaction's description
+     --open-acct=ACCT       set opening transaction's source account
+     --round=TYPE           how much rounding or padding should be done when
+                            displaying amounts ?
+                            none - show original decimal digits,
+                                   as in journal (default)
+                            soft - just add or remove decimal zeros
+                                   to match precision
+                            hard - round posting amounts to precision
+                                   (can unbalance transactions)
+                            all  - also round cost amounts to precision
+                                   (can unbalance transactions)
+
+   'close' has six modes, selected by choosing one of the mode flags
+('--close' is the default).  They all do much the same operation, but
+with different defaults, useful in different situations.
+
+* Menu:
+
+* close --clopen::
+* close --close::
+* close --open::
+* close --assert::
+* close --assign::
+* close --retain::
+* close customisation::
+* close and balance assertions::
+* close examples::
+
+
+File: hledger.info,  Node: close --clopen,  Next: close --close,  Up: close
+
+31.1.1 close -clopen
+--------------------
+
+This is useful if migrating balances to a new journal file at the start
+of a new year.  It prints a "closing balances" transaction that zeroes
+out account balances (Asset and Liability accounts, by default), and an
+opposite "opening balances" transaction that restores them again.
+Typically, you would run
+
+hledger close --clopen -e NEWYEAR >> $LEDGER_FILE
+
+   and then move the opening transaction from the old file to the new
+file (and probably also update your LEDGER_FILE environment variable).
+
+   Why might you do this ?  If your reports are fast, you may not need
+it.  But at some point you will probably want to partition your data by
+time, for performance or data integrity or regulatory reasons.  A new
+file or set of files per year is common.  Then, having each file/fileset
+"bookended" with opening and closing balance transactions will allow you
+to freely pick and choose which files to read - just the current year,
+any past year, any sequence of years, or all of them - while showing
+correct account balances in each case.  The earliest opening balances
+transaction sets correct starting balances, and any later
+closing/opening pairs will harmlessly cancel each other out.
+
+   The balances will be transferred to and from 'equity:opening/closing
+balances' by default.  You can override this by using '--close-acct'
+and/or '--open-acct'.
+
+   You can select a different set of accounts to close/open by providing
+an account query.  Eg to add Equity accounts, provide arguments like
+'assets liabilities equity' or 'type:ALE'.  When migrating to a new
+file, you'll usually want to bring along the AL or ALE accounts, but not
+the RX accounts (Revenue, Expense).
+
+   Assertions will be added indicating and checking the new balances of
+the closed/opened accounts.
+
+   The generated transactions will have a 'clopen:' tag.  If the main
+journal's base file name contains a number (eg a year number), the tag's
+value will be that base file name with the number incremented.  Or you
+can choose the tag value yourself, by using '--clopen=TAGVAL'.
+
+
+File: hledger.info,  Node: close --close,  Next: close --open,  Prev: close --clopen,  Up: close
+
+31.1.2 close -close
+-------------------
+
+This prints just the closing balances transaction of '--clopen'.  It is
+the default if you don't specify a mode.
+
+   More customisation options are described below.  Among other things,
+you can use 'close --close' to generate a transaction moving the
+balances from any set of accounts, to a different account.  (If you need
+to move just a portion of the balance, see hledger-move.)
+
+
+File: hledger.info,  Node: close --open,  Next: close --assert,  Prev: close --close,  Up: close
+
+31.1.3 close -open
+------------------
+
+This prints just the opening balances transaction of '--clopen'.  (It is
+similar to Ledger's equity command.)
+
+
+File: hledger.info,  Node: close --assert,  Next: close --assign,  Prev: close --open,  Up: close
+
+31.1.4 close -assert
+--------------------
+
+This prints a transaction that asserts the account balances as they are
+on the end date (and adds an 'assert:' tag).  It could be useful as
+documention and to guard against changes.
+
+
+File: hledger.info,  Node: close --assign,  Next: close --retain,  Prev: close --assert,  Up: close
+
+31.1.5 close -assign
+--------------------
+
+This prints a transaction that assigns the account balances as they are
+on the end date (and adds an "assign:" tag).  Unlike balance assertions,
+assignments will post changes to balances as needed to reach the
+specified amounts.
+
+   This is another way to set starting balances when migrating to a new
+file, and it will set them correctly even in the presence of earlier
+files which do not have a closing balances transaction.  However, it can
+hide errors, and disturb the accounting equation, so '--clopen' is
+usually recommended.
+
+
+File: hledger.info,  Node: close --retain,  Next: close customisation,  Prev: close --assign,  Up: close
+
+31.1.6 close -retain
+--------------------
+
+This is like '--close', but it closes Revenue and Expense account
+balances by default.  They will be transferred to 'equity:retained
+earnings', or another account specified with '--close-acct'.
+
+   Revenues and expenses correspond to changes in equity.  They are
+categorised separately for reporting purposes, but traditionally at the
+end of each accounting period, businesses consolidate them into equity,
+This is called "retaining earnings", or "closing the books".
+
+   In personal accounting, there's not much reason to do this, and most
+people don't.  (One reason to do it is to help the 'balancesheetequity'
+report show a zero total, demonstrating that the accounting equation
+(A-L=E) is satisfied.)
+
+
+File: hledger.info,  Node: close customisation,  Next: close and balance assertions,  Prev: close --retain,  Up: close
+
+31.1.7 close customisation
+--------------------------
+
+In all modes, the following things can be overridden:
+
+   * the accounts to be closed/opened, with account query arguments
+   * the balancing account, with '--close-acct=ACCT' and/or
+     '--open-acct=ACCT'
+   * the transaction descriptions, with '--close-desc=DESC' and
+     '--open-desc=DESC'
+   * the transaction's tag value, with a '--MODE=NEW' option argument
+   * the closing/opening dates, with '-e OPENDATE'
+
+   By default, the closing date is yesterday, or the journal's end date,
+whichever is later; and the opening date is always one day after the
+closing date.  You can change these by specifying a report end date; the
+closing date will be the last day of the report period.  Eg '-e 2024'
+means "close on 2023-12-31, open on 2024-01-01".
+
+   With '--x/--explicit', the balancing amount will be shown explicitly,
+and if it involves multiple commodities, a separate posting will be
+generated for each of them (similar to 'print -x').
+
+   With '--interleaved', each individual transfer is shown with source
+and destination postings next to each other (perhaps useful for
+troubleshooting).
+
+   With '--show-costs', balances' costs are also shown, with different
+costs kept separate.  This may generate very large journal entries, if
+you have many currency conversions or investment transactions.  'close
+--show-costs' is currently the best way to view investment lots with
+hledger.  (To move or dispose of lots, see the more capable
+'hledger-move' script.)
+
+
+File: hledger.info,  Node: close and balance assertions,  Next: close examples,  Prev: close customisation,  Up: close
+
+31.1.8 close and balance assertions
+-----------------------------------
+
+'close' adds balance assertions verifying that the accounts have been
+reset to zero in a closing transaction or restored to their previous
+balances in an opening transaction.  These provide useful error
+checking, but you can ignore them temporarily with '-I', or remove them
+if you prefer.
+
+   Single-commodity, subaccount-exclusive balance assertions ('=') are
+generated by default.  This can be changed with '--assertion-type='==*''
+(eg).
+
+   When running 'close' you should probably avoid using '-C', '-R',
+'status:' (filtering by status or realness) or '--auto' (generating
+postings), since the generated balance assertions would then require
+these.
+
+   Transactions with multiple dates (eg posting dates) spanning the file
+boundary also can disrupt the balance assertions:
+
+2023-12-30 a purchase made in december, cleared in january
+    expenses:food          5
+    assets:bank:checking  -5  ; date: 2023-01-02
+
+   To solve this you can transfer the money to and from a temporary
+account, splitting the multi-day transaction into two single-day
+transactions:
+
+; in 2022.journal:
+2022-12-30 a purchase made in december, cleared in january
+    expenses:food          5
+    equity:pending        -5
+
+; in 2023.journal:
+2023-01-02 last year's transaction cleared
+    equity:pending         5 = 0
+    assets:bank:checking  -5
+
+
+File: hledger.info,  Node: close examples,  Prev: close and balance assertions,  Up: close
+
+31.1.9 close examples
+---------------------
+
+* Menu:
+
+* Retain earnings::
+* Migrate balances to a new file::
+* More detailed close examples::
+
+
+File: hledger.info,  Node: Retain earnings,  Next: Migrate balances to a new file,  Up: close examples
+
+31.1.9.1 Retain earnings
+........................
+
+Record 2022's revenues/expenses as retained earnings on 2022-12-31,
+appending the generated transaction to the journal:
+
+$ hledger close --retain -f 2022.journal -p 2022 >> 2022.journal
+
+   After this, to see 2022's revenues and expenses you must exclude the
+retain earnings transaction:
+
+$ hledger -f 2022.journal is not:desc:'retain earnings'
+
+
+File: hledger.info,  Node: Migrate balances to a new file,  Next: More detailed close examples,  Prev: Retain earnings,  Up: close examples
+
+31.1.9.2 Migrate balances to a new file
+.......................................
+
+Close assets/liabilities on 2022-12-31 and re-open them on 2023-01-01:
+
+$ hledger close --clopen -f 2022.journal -p 2022
+# copy/paste the closing transaction to the end of 2022.journal
+# copy/paste the opening transaction to the start of 2023.journal
+
+   After this, to see 2022's end-of-year balances you must exclude the
+closing balances transaction:
+
+$ hledger -f 2022.journal bs not:desc:'closing balances'
+
+   For more flexibility, it helps to tag closing and opening
+transactions with eg 'clopen:NEWYEAR', then you can ensure correct
+balances by excluding all opening/closing transactions except the first,
+like so:
+
+$ hledger bs -Y -f 2021.j -f 2022.j -f 2023.j expr:'tag:clopen=2021 or not tag:clopen'
+$ hledger bs -Y -f 2021.j -f 2022.j           expr:'tag:clopen=2021 or not tag:clopen'
+$ hledger bs -Y -f 2022.j -f 2023.j           expr:'tag:clopen=2022 or not tag:clopen'
+$ hledger bs -Y -f 2021.j                     expr:'tag:clopen=2021 or not tag:clopen'
+$ hledger bs -Y -f 2022.j                     expr:'tag:clopen=2022 or not tag:clopen'
+$ hledger bs -Y -f 2023.j                     # unclosed file, no query needed
+
+
+File: hledger.info,  Node: More detailed close examples,  Prev: Migrate balances to a new file,  Up: close examples
+
+31.1.9.3 More detailed close examples
+.....................................
+
+See examples/multi-year.
+
+
+File: hledger.info,  Node: rewrite,  Prev: close,  Up: Data generation commands
+
+31.2 rewrite
+============
+
+Print all transactions, rewriting the postings of matched transactions.
+For now the only rewrite available is adding new postings, like print
+-auto.
+
+Flags:
+     --add-posting='ACCT  AMTEXPR'  add a posting to ACCT, which may be
+                                    parenthesised. AMTEXPR is either a literal
+                                    amount, or *N which means the transaction's
+                                    first matched amount multiplied by N (a
+                                    decimal number). Two spaces separate ACCT
+                                    and AMTEXPR.
+     --diff                         generate diff suitable as an input for
+                                    patch tool
+
+   This is a start at a generic rewriter of transaction entries.  It
+reads the default journal and prints the transactions, like print, but
+adds one or more specified postings to any transactions matching QUERY.
+The posting amounts can be fixed, or a multiplier of the existing
+transaction's first posting amount.
+
+   Examples:
+
+$ hledger-rewrite.hs ^income --add-posting '(liabilities:tax)  *.33  ; income tax' --add-posting '(reserve:gifts)  $100'
+$ hledger-rewrite.hs expenses:gifts --add-posting '(reserve:gifts)  *-1"'
+$ hledger-rewrite.hs -f rewrites.hledger
+
+   rewrites.hledger may consist of entries like:
+
+= ^income amt:<0 date:2017
+  (liabilities:tax)  *0.33  ; tax on income
+  (reserve:grocery)  *0.25  ; reserve 25% for grocery
+  (reserve:)  *0.25  ; reserve 25% for grocery
+
+   Note the single quotes to protect the dollar sign from bash, and the
+two spaces between account and amount.
+
+   More:
+
+$ hledger rewrite -- [QUERY]        --add-posting "ACCT  AMTEXPR" ...
+$ hledger rewrite -- ^income        --add-posting '(liabilities:tax)  *.33'
+$ hledger rewrite -- expenses:gifts --add-posting '(budget:gifts)  *-1"'
+$ hledger rewrite -- ^income        --add-posting '(budget:foreign currency)  *0.25 JPY; diversify'
+
+   Argument for '--add-posting' option is a usual posting of transaction
+with an exception for amount specification.  More precisely, you can use
+''*'' (star symbol) before the amount to indicate that that this is a
+factor for an amount of original matched posting.  If the amount
+includes a commodity name, the new posting amount will be in the new
+commodity; otherwise, it will be in the matched posting amount's
+commodity.
+
+* Menu:
+
+* Re-write rules in a file::
+* Diff output format::
+* rewrite vs print --auto::
+
+
+File: hledger.info,  Node: Re-write rules in a file,  Next: Diff output format,  Up: rewrite
+
+31.2.1 Re-write rules in a file
+-------------------------------
+
+During the run this tool will execute so called "Automated Transactions"
+found in any journal it process.  I.e instead of specifying this
+operations in command line you can put them in a journal file.
+
+$ rewrite-rules.journal
+
+   Make contents look like this:
+
+= ^income
+    (liabilities:tax)  *.33
+
+= expenses:gifts
+    budget:gifts  *-1
+    assets:budget  *1
+
+   Note that ''='' (equality symbol) that is used instead of date in
+transactions you usually write.  It indicates the query by which you
+want to match the posting to add new ones.
+
+$ hledger rewrite -- -f input.journal -f rewrite-rules.journal > rewritten-tidy-output.journal
+
+   This is something similar to the commands pipeline:
+
+$ hledger rewrite -- -f input.journal '^income' --add-posting '(liabilities:tax)  *.33' \
+  | hledger rewrite -- -f - expenses:gifts      --add-posting 'budget:gifts  *-1'       \
+                                                --add-posting 'assets:budget  *1'       \
+  > rewritten-tidy-output.journal
+
+   It is important to understand that relative order of such entries in
+journal is important.  You can re-use result of previously added
+postings.
+
+
+File: hledger.info,  Node: Diff output format,  Next: rewrite vs print --auto,  Prev: Re-write rules in a file,  Up: rewrite
+
+31.2.2 Diff output format
+-------------------------
+
+To use this tool for batch modification of your journal files you may
+find useful output in form of unified diff.
+
+$ hledger rewrite -- --diff -f examples/sample.journal '^income' --add-posting '(liabilities:tax)  *.33'
+
+   Output might look like:
+
+--- /tmp/examples/sample.journal
++++ /tmp/examples/sample.journal
+@@ -18,3 +18,4 @@
+ 2008/01/01 income
+-    assets:bank:checking  $1
++    assets:bank:checking            $1
+     income:salary
++    (liabilities:tax)                0
+@@ -22,3 +23,4 @@
+ 2008/06/01 gift
+-    assets:bank:checking  $1
++    assets:bank:checking            $1
+     income:gifts
++    (liabilities:tax)                0
+
+   If you'll pass this through 'patch' tool you'll get transactions
+containing the posting that matches your query be updated.  Note that
+multiple files might be update according to list of input files
+specified via '--file' options and 'include' directives inside of these
+files.
+
+   Be careful.  Whole transaction being re-formatted in a style of
+output from 'hledger print'.
+
+   See also:
+
+   https://github.com/simonmichael/hledger/issues/99
+
+
+File: hledger.info,  Node: rewrite vs print --auto,  Prev: Diff output format,  Up: rewrite
+
+31.2.3 rewrite vs. print -auto
+------------------------------
+
+This command predates print -auto, and currently does much the same
+thing, but with these differences:
+
+   * with multiple files, rewrite lets rules in any file affect all
+     other files.  print -auto uses standard directive scoping; rules
+     affect only child files.
+
+   * rewrite's query limits which transactions can be rewritten; all are
+     printed.  print -auto's query limits which transactions are
+     printed.
+
+   * rewrite applies rules specified on command line or in the journal.
+     print -auto applies rules specified in the journal.
+
+
+File: hledger.info,  Node: Maintenance commands,  Next: PART 5 COMMON TASKS,  Prev: Data generation commands,  Up: Top
+
+32 Maintenance commands
+***********************
+
+* Menu:
+
+* check::
+* diff::
+* test::
+
+
+File: hledger.info,  Node: check,  Next: diff,  Up: Maintenance commands
+
+32.1 check
+==========
+
+Check for various kinds of errors in your data.
+
+Flags:
+no command-specific flags
+
+   hledger provides a number of built-in correctness checks to help
+validate your data and prevent errors.  Some are run automatically, some
+when you enable '--strict' mode; or you can run any of them on demand by
+providing them as arguments to the 'check' command.  'check' produces no
+output and a zero exit code if all is well.  Eg:
+
+hledger check                      # run basic checks
+hledger check -s                   # run basic and strict checks
+hledger check ordereddates payees  # run basic checks and two others
+
+   If you are an Emacs user, you can also configure flycheck-hledger to
+run these checks, providing instant feedback as you edit the journal.
+
+   Here are the checks currently available.  Generally, they are
+performed in the order they are shown here (and only the first failure
+is reported).
+
+* Menu:
+
+* Basic checks::
+* Strict checks::
+* Other checks::
+* Custom checks::
+
+
+File: hledger.info,  Node: Basic checks,  Next: Strict checks,  Up: check
+
+32.1.1 Basic checks
+-------------------
+
+These important checks are performed by default, by almost all hledger
+commands:
+
+   * *parseable* - data files are in a supported format, with no syntax
+     errors and no invalid include directives.  This ensures that all
+     files exist and are readable.
+
+   * *autobalanced* - all transactions are balanced, after inferring
+     missing amounts and conversion costs where possible, and then
+     converting to cost.  This ensures that each individual transaction
+     is well formed.
+
+   * *assertions* - all balance assertions in the journal are passing.
+     Balance assertions are like canaries in your journal, they catch
+     many problems.  They can get in the way sometimes; you can disable
+     them temporarily with '-I'/'--ignore-assertions' (unless overridden
+     with '-s'/'--strict' or 'hledger check assertions').
+
+
+File: hledger.info,  Node: Strict checks,  Next: Other checks,  Prev: Basic checks,  Up: check
+
+32.1.2 Strict checks
+--------------------
+
+These additional checks are performed by any command when the
+'-s'/'--strict' flag is used (strict mode).  Strict mode always enables
+the balance assertions check, also.  These provide extra error-catching
+power when you are serious about keeping your data clean and free of
+typos:
+
+   * *balanced* - like 'autobalanced', but in conversion transactions,
+     costs must be written explicitly.  This ensures some redundancy in
+     the entry, which helps prevent typos.
+
+   * *commodities* - all commodity symbols used must be declared.  This
+     guards against mistyping or omitting commodity symbols.
+
+   * *accounts* - all account names used must be declared.  This
+     prevents the use of mis-spelled or outdated account names.
+
+
+File: hledger.info,  Node: Other checks,  Next: Custom checks,  Prev: Strict checks,  Up: check
+
+32.1.3 Other checks
+-------------------
+
+These other checks are not wanted by everyone, but can be run using the
+'check' command:
+
+   * *ordereddates* - within each file, transactions are ordered by
+     date.  This is a simple and effective error catcher, and you should
+     use it.  Alas!  not everyone wants it.  If you do, use 'hledger
+     check -s ordereddates'.  When enabled, this check is performed
+     early, before balance assertions (because copy-pasted dates are
+     often the root cause of balance assertion failures).
+
+   * *payees* - all payees used by transactions must be declared.  This
+     will force you to always use known/declared payee names.  For most
+     people this is a bit too restrictive.
+
+   * *tags* - all tags used by transactions must be declared.  This
+     prevents mistyped tag names.
+
+   * *recentassertions* - all accounts with balance assertions must have
+     a balance assertion within the last 7 days before their latest
+     posting.  This encourages you to add balance assertions fairly
+     regularly for your active asset/liability accounts, which in turn
+     should encourage you to check and reconcile with their real world
+     balances fairly regularly.  'close --assert' can be helpful.  (The
+     older balance assertions become redundant; you can remove them
+     periodically, or leave them in place, perhaps commented, as
+     documentation.)
+
+   * *uniqueleafnames* - no two accounts may have the same leaf name.
+     The leaf name is the last colon-separated part of an account name,
+     eg 'checking' in 'assets:bank:checking'.  This encourages you to
+     keep those unique, effectively giving each account a short name
+     which is easier to remember and to type in reporting commands.
+
+
+File: hledger.info,  Node: Custom checks,  Prev: Other checks,  Up: check
+
+32.1.4 Custom checks
+--------------------
+
+You can build your own custom checks with add-on command scripts.  See
+also Cookbook > Scripting.  Here are some examples from hledger/bin/:
+
+   * *hledger-check-tagfiles* - all tag values containing / (a forward
+     slash) exist as file paths
+
+   * *hledger-check-fancyassertions* - more complex balance assertions
+     are passing
+
+
+File: hledger.info,  Node: diff,  Next: test,  Prev: check,  Up: Maintenance commands
+
+32.2 diff
+=========
+
+Compares a particular account's transactions in two input files.  It
+shows any transactions to this account which are in one file but not in
+the other.
+
+Flags:
+no command-specific flags
+
+   More precisely: for each posting affecting this account in either
+file, this command looks for a corresponding posting in the other file
+which posts the same amount to the same account (ignoring date,
+description, etc).
+
+   Since it compares postings, not transactions, this also works when
+multiple bank transactions have been combined into a single journal
+entry.
+
+   This command is useful eg if you have downloaded an account's
+transactions from your bank (eg as CSV data): when hledger and your bank
+disagree about the account balance, you can compare the bank data with
+your journal to find out the cause.
+
+   Examples:
+
+$ hledger diff -f $LEDGER_FILE -f bank.csv assets:bank:giro 
+These transactions are in the first file only:
+
+2014/01/01 Opening Balances
+    assets:bank:giro              EUR ...
+    ...
+    equity:opening balances       EUR -...
+
+These transactions are in the second file only:
+
+
+File: hledger.info,  Node: test,  Prev: diff,  Up: Maintenance commands
+
+32.3 test
+=========
+
+Run built-in unit tests.
+
+Flags:
+no command-specific flags
+
+   This command runs the unit tests built in to hledger and hledger-lib,
+printing the results on stdout.  If any test fails, the exit code will
+be non-zero.
+
+   This is mainly used by hledger developers, but you can also use it to
+sanity-check the installed hledger executable on your platform.  All
+tests are expected to pass - if you ever see a failure, please report as
+a bug!
+
+   This command also accepts tasty test runner options, written after a
+- (double hyphen).  Eg to run only the tests in Hledger.Data.Amount,
+with ANSI colour codes disabled:
+
+$ hledger test -- -pData.Amount --color=never
+
+   For help on these, see https://github.com/feuerbach/tasty#options
+('-- --help' currently doesn't show them).
+
+
+File: hledger.info,  Node: PART 5 COMMON TASKS,  Next: Getting help,  Prev: Maintenance commands,  Up: Top
+
+33 PART 5: COMMON TASKS
+***********************
+
+Here are some quick examples of how to do some basic tasks with hledger.
+
+
+File: hledger.info,  Node: Getting help,  Next: Constructing command lines,  Prev: PART 5 COMMON TASKS,  Up: Top
+
+34 Getting help
+***************
+
+Here's how to list commands and view options and command docs:
+
+$ hledger                # show available commands
+$ hledger --help         # show common options
+$ hledger CMD --help     # show CMD's options, common options and CMD's documentation
+
+   You can also view your hledger version's manual in several formats by
+using the help command.  Eg:
+
+$ hledger help           # show the hledger manual with info, man or $PAGER (best available)
+$ hledger help journal   # show the journal topic in the hledger manual
+$ hledger help --help    # find out more about the help command
+
+   To view manuals and introductory docs on the web, visit
+https://hledger.org.  Chat and mail list support and discussion archives
+can be found at https://hledger.org/support.
+
+
+File: hledger.info,  Node: Constructing command lines,  Next: Starting a journal file,  Prev: Getting help,  Up: Top
+
+35 Constructing command lines
+*****************************
+
+hledger has a flexible command line interface.  We strive to keep it
+simple and ergonomic, but if you run into one of the sharp edges
+described in OPTIONS, here are some tips that might help:
+
+   * command-specific options must go after the command (it's fine to
+     put common options there too: 'hledger CMD OPTS ARGS')
+   * running add-on executables directly simplifies command line parsing
+     ('hledger-ui OPTS ARGS')
+   * enclose "problematic" args in single quotes
+   * if needed, also add a backslash to hide regular expression
+     metacharacters from the shell
+   * to see how a misbehaving command line is being parsed, add
+     '--debug=2'.
+
+
+File: hledger.info,  Node: Starting a journal file,  Next: Setting LEDGER_FILE,  Prev: Constructing command lines,  Up: Top
+
+36 Starting a journal file
+**************************
+
+hledger looks for your accounting data in a journal file,
+'$HOME/.hledger.journal' by default:
+
+$ hledger stats
+The hledger journal file "/Users/simon/.hledger.journal" was not found.
+Please create it first, eg with "hledger add" or a text editor.
+Or, specify an existing journal file with -f or LEDGER_FILE.
+
+   You can override this by setting the 'LEDGER_FILE' environment
+variable (see below).  It's a good practice to keep this important file
+under version control, and to start a new file each year.  So you could
+do something like this:
+
+$ mkdir ~/finance
+$ cd ~/finance
+$ git init
+Initialized empty Git repository in /Users/simon/finance/.git/
+$ touch 2023.journal
+$ echo "export LEDGER_FILE=$HOME/finance/2023.journal" >> ~/.profile
+$ source ~/.profile
+$ hledger stats
+Main file                : /Users/simon/finance/2023.journal
+Included files           : 
+Transactions span        :  to  (0 days)
+Last transaction         : none
+Transactions             : 0 (0.0 per day)
+Transactions last 30 days: 0 (0.0 per day)
+Transactions last 7 days : 0 (0.0 per day)
+Payees/descriptions      : 0
+Accounts                 : 0 (depth 0)
+Commodities              : 0 ()
+Market prices            : 0 ()
+
+
+File: hledger.info,  Node: Setting LEDGER_FILE,  Next: Setting opening balances,  Prev: Starting a journal file,  Up: Top
+
+37 Setting LEDGER_FILE
+**********************
+
+How to set 'LEDGER_FILE' permanently depends on your setup:
+
+   On unix and mac, running these commands in the terminal will work for
+many people; adapt as needed:
+
+$ echo 'export LEDGER_FILE=~/finance/2023.journal' >> ~/.profile
+$ source ~/.profile
+
+   When correctly configured, in a new terminal window 'env | grep
+LEDGER_FILE' will show your file, and so will 'hledger files'.
+
+   On mac, this additional step might be helpful for GUI applications
+(like Emacs started from the dock): add an entry to
+'~/.MacOSX/environment.plist' like
+
+{
+  "LEDGER_FILE" : "~/finance/2023.journal"
+}
+
+   and then run 'killall Dock' in a terminal window (or restart the
+machine).
+
+   On Windows, see https://www.java.com/en/download/help/path.html, or
+try running these commands in a powershell window (let us know if it
+persists across a reboot, and if you need to be an Administrator):
+
+> CD
+> MKDIR finance
+> SETX LEDGER_FILE "C:\Users\USERNAME\finance\2023.journal"
+
+   When correctly configured, in a new terminal window
+'$env:LEDGER_FILE' will show the file path, and so will 'hledger files'.
+
+
+File: hledger.info,  Node: Setting opening balances,  Next: Recording transactions,  Prev: Setting LEDGER_FILE,  Up: Top
+
+38 Setting opening balances
+***************************
+
+Pick a starting date for which you can look up the balances of some
+real-world assets (bank accounts, wallet..)  and liabilities (credit
+cards..).
+
+   To avoid a lot of data entry, you may want to start with just one or
+two accounts, like your checking account or cash wallet; and pick a
+recent starting date, like today or the start of the week.  You can
+always come back later and add more accounts and older transactions, eg
+going back to january 1st.
+
+   Add an opening balances transaction to the journal, declaring the
+balances on this date.  Here are two ways to do it:
+
+   * The first way: open the journal in any text editor and save an
+     entry like this:
+
+     2023-01-01 * opening balances
+         assets:bank:checking                $1000   = $1000
+         assets:bank:savings                 $2000   = $2000
+         assets:cash                          $100   = $100
+         liabilities:creditcard               $-50   = $-50
+         equity:opening/closing balances
+
+     These are start-of-day balances, ie whatever was in the account at
+     the end of the previous day.
+
+     The * after the date is an optional status flag.  Here it means
+     "cleared & confirmed".
+
+     The currency symbols are optional, but usually a good idea as
+     you'll be dealing with multiple currencies sooner or later.
+
+     The = amounts are optional balance assertions, providing extra
+     error checking.
+
+   * The second way: run 'hledger add' and follow the prompts to record
+     a similar transaction:
+
+     $ hledger add
+     Adding transactions to journal file /Users/simon/finance/2023.journal
+     Any command line arguments will be used as defaults.
+     Use tab key to complete, readline keys to edit, enter to accept defaults.
+     An optional (CODE) may follow transaction dates.
+     An optional ; COMMENT may follow descriptions or amounts.
+     If you make a mistake, enter < at any prompt to go one step backward.
+     To end a transaction, enter . when prompted.
+     To quit, enter . at a date prompt or press control-d or control-c.
+     Date [2023-02-07]: 2023-01-01
+     Description: * opening balances
+     Account 1: assets:bank:checking
+     Amount  1: $1000
+     Account 2: assets:bank:savings
+     Amount  2 [$-1000]: $2000
+     Account 3: assets:cash
+     Amount  3 [$-3000]: $100
+     Account 4: liabilities:creditcard
+     Amount  4 [$-3100]: $-50
+     Account 5: equity:opening/closing balances
+     Amount  5 [$-3050]: 
+     Account 6 (or . or enter to finish this transaction): .
+     2023-01-01 * opening balances
+         assets:bank:checking                      $1000
+         assets:bank:savings                       $2000
+         assets:cash                                $100
+         liabilities:creditcard                     $-50
+         equity:opening/closing balances          $-3050
+     
+     Save this transaction to the journal ? [y]: 
+     Saved.
+     Starting the next transaction (. or ctrl-D/ctrl-C to quit)
+     Date [2023-01-01]: .
+
+   If you're using version control, this could be a good time to commit
+the journal.  Eg:
+
+$ git commit -m 'initial balances' 2023.journal
+
+
+File: hledger.info,  Node: Recording transactions,  Next: Reconciling,  Prev: Setting opening balances,  Up: Top
+
+39 Recording transactions
+*************************
+
+As you spend or receive money, you can record these transactions using
+one of the methods above (text editor, hledger add) or by using the
+hledger-iadd or hledger-web add-ons, or by using the import command to
+convert CSV data downloaded from your bank.
+
+   Here are some simple transactions, see the hledger_journal(5) manual
+and hledger.org for more ideas:
+
+2023/1/10 * gift received
+  assets:cash   $20
+  income:gifts
+
+2023.1.12 * farmers market
+  expenses:food    $13
+  assets:cash
+
+2023-01-15 paycheck
+  income:salary
+  assets:bank:checking    $1000
+
+
+File: hledger.info,  Node: Reconciling,  Next: Reporting,  Prev: Recording transactions,  Up: Top
+
+40 Reconciling
+**************
+
+Periodically you should reconcile - compare your hledger-reported
+balances against external sources of truth, like bank statements or your
+bank's website - to be sure that your ledger accurately represents the
+real-world balances (and, that the real-world institutions have not made
+a mistake!).  This gets easy and fast with (1) practice and (2)
+frequency.  If you do it daily, it can take 2-10 minutes.  If you let it
+pile up, expect it to take longer as you hunt down errors and
+discrepancies.
+
+   A typical workflow:
+
+  1. Reconcile cash.  Count what's in your wallet.  Compare with what
+     hledger reports ('hledger bal cash').  If they are different, try
+     to remember the missing transaction, or look for the error in the
+     already-recorded transactions.  A register report can be helpful
+     ('hledger reg cash').  If you can't find the error, add an
+     adjustment transaction.  Eg if you have $105 after the above, and
+     can't explain the missing $2, it could be:
+
+     2023-01-16 * adjust cash
+         assets:cash    $-2 = $105
+         expenses:misc
+
+  2. Reconcile checking.  Log in to your bank's website.  Compare
+     today's (cleared) balance with hledger's cleared balance ('hledger
+     bal checking -C').  If they are different, track down the error or
+     record the missing transaction(s) or add an adjustment transaction,
+     similar to the above.  Unlike the cash case, you can usually
+     compare the transaction history and running balance from your bank
+     with the one reported by 'hledger reg checking -C'.  This will be
+     easier if you generally record transaction dates quite similar to
+     your bank's clearing dates.
+
+  3. Repeat for other asset/liability accounts.
+
+   Tip: instead of the register command, use hledger-ui to see a
+live-updating register while you edit the journal: 'hledger-ui --watch
+--register checking -C'
+
+   After reconciling, it could be a good time to mark the reconciled
+transactions' status as "cleared and confirmed", if you want to track
+that, by adding the '*' marker.  Eg in the paycheck transaction above,
+insert '*' between '2023-01-15' and 'paycheck'
+
+   If you're using version control, this can be another good time to
+commit:
+
+$ git commit -m 'txns' 2023.journal
+
+
+File: hledger.info,  Node: Reporting,  Next: Migrating to a new file,  Prev: Reconciling,  Up: Top
+
+41 Reporting
+************
+
+Here are some basic reports.
+
+   Show all transactions:
+
+$ hledger print
+2023-01-01 * opening balances
+    assets:bank:checking                      $1000
+    assets:bank:savings                       $2000
+    assets:cash                                $100
+    liabilities:creditcard                     $-50
+    equity:opening/closing balances          $-3050
+
+2023-01-10 * gift received
+    assets:cash              $20
+    income:gifts
+
+2023-01-12 * farmers market
+    expenses:food             $13
+    assets:cash
+
+2023-01-15 * paycheck
+    income:salary
+    assets:bank:checking           $1000
+
+2023-01-16 * adjust cash
+    assets:cash               $-2 = $105
+    expenses:misc
+
+   Show account names, and their hierarchy:
+
+$ hledger accounts --tree
+assets
+  bank
+    checking
+    savings
+  cash
+equity
+  opening/closing balances
+expenses
+  food
+  misc
+income
+  gifts
+  salary
+liabilities
+  creditcard
+
+   Show all account totals:
+
+$ hledger balance
+               $4105  assets
+               $4000    bank
+               $2000      checking
+               $2000      savings
+                $105    cash
+              $-3050  equity:opening/closing balances
+                 $15  expenses
+                 $13    food
+                  $2    misc
+              $-1020  income
+                $-20    gifts
+              $-1000    salary
+                $-50  liabilities:creditcard
+--------------------
+                   0
+
+   Show only asset and liability balances, as a flat list, limited to
+depth 2:
+
+$ hledger bal assets liabilities -2
+               $4000  assets:bank
+                $105  assets:cash
+                $-50  liabilities:creditcard
+--------------------
+               $4055
+
+   Show the same thing without negative numbers, formatted as a simple
+balance sheet:
+
+$ hledger bs -2
+Balance Sheet 2023-01-16
+
+                        || 2023-01-16 
+========================++============
+ Assets                 ||            
+------------------------++------------
+ assets:bank            ||      $4000 
+ assets:cash            ||       $105 
+------------------------++------------
+                        ||      $4105 
+========================++============
+ Liabilities            ||            
+------------------------++------------
+ liabilities:creditcard ||        $50 
+------------------------++------------
+                        ||        $50 
+========================++============
+ Net:                   ||      $4055 
+
+   The final total is your "net worth" on the end date.  (Or use 'bse'
+for a full balance sheet with equity.)
+
+   Show income and expense totals, formatted as an income statement:
+
+hledger is 
+Income Statement 2023-01-01-2023-01-16
+
+               || 2023-01-01-2023-01-16 
+===============++=======================
+ Revenues      ||                       
+---------------++-----------------------
+ income:gifts  ||                   $20 
+ income:salary ||                 $1000 
+---------------++-----------------------
+               ||                 $1020 
+===============++=======================
+ Expenses      ||                       
+---------------++-----------------------
+ expenses:food ||                   $13 
+ expenses:misc ||                    $2 
+---------------++-----------------------
+               ||                   $15 
+===============++=======================
+ Net:          ||                 $1005 
+
+   The final total is your net income during this period.
+
+   Show transactions affecting your wallet, with running total:
+
+$ hledger register cash
+2023-01-01 opening balances     assets:cash                   $100          $100
+2023-01-10 gift received        assets:cash                    $20          $120
+2023-01-12 farmers market       assets:cash                   $-13          $107
+2023-01-16 adjust cash          assets:cash                    $-2          $105
+
+   Show weekly posting counts as a bar chart:
+
+$ hledger activity -W
+2019-12-30 *****
+2023-01-06 ****
+2023-01-13 ****
+
+
+File: hledger.info,  Node: Migrating to a new file,  Next: BUGS,  Prev: Reporting,  Up: Top
+
+42 Migrating to a new file
+**************************
+
+At the end of the year, you may want to continue your journal in a new
+file, so that old transactions don't slow down or clutter your reports,
+and to help ensure the integrity of your accounting history.  See the
+close command.
+
+   If using version control, don't forget to 'git add' the new file.
+
+
+File: hledger.info,  Node: BUGS,  Prev: Migrating to a new file,  Up: Top
+
+43 BUGS
+*******
+
+We welcome bug reports in the hledger issue tracker (shortcut:
+https://bugs.hledger.org), or on the hledger chat or mail list
+(https://hledger.org/support).
+
+   Some known issues and limitations:
+
+   The need to precede add-on command options with '--' when invoked
+from hledger is awkward.  (See Command options, Constructing command
+lines.)
+
+   A UTF-8-aware system locale must be configured to work with non-ascii
+data.  (See Unicode characters, Troubleshooting.)
+
+   On Microsoft Windows, depending whether you are running in a CMD
+window or a Cygwin/MSYS/Mintty window and how you installed hledger,
+non-ascii characters and colours may not be supported, and the tab key
+may not be supported by 'hledger add'.  (Running in a WSL window should
+resolve these.)
+
+   When processing large data files, hledger uses more memory than
+Ledger.
+
+* Menu:
+
+* Troubleshooting::
+
+
+File: hledger.info,  Node: Troubleshooting,  Up: BUGS
+
+43.1 Troubleshooting
+====================
+
+Here are some common issues you might encounter when you run hledger,
+and how to resolve them (and remember also you can usually get quick
+Support):
+
+   *PATH issues: I get an error like "No command 'hledger' found"*
+Depending how you installed hledger, the executables may not be in your
+shell's PATH. Eg on unix systems, stack installs hledger in
+'~/.local/bin' and cabal installs it in '~/.cabal/bin'.  You may need to
+add one of these directories to your shell's PATH, and/or open a new
+terminal window.
+
+   *LEDGER_FILE issues: I configured LEDGER_FILE but hledger is not
+using it*
+
+   * 'LEDGER_FILE' should be a real environment variable, not just a
+     shell variable.  Eg on unix, the command 'env | grep LEDGER_FILE'
+     should show it.  You may need to use 'export' (see
+     https://stackoverflow.com/a/7411509).  On Windows,
+     '$env:LEDGER_FILE' should show it.
+   * You may need to force your shell to see the new configuration.  A
+     simple way is to close your terminal window and open a new one.
+
+   *LANG issues: I get errors like "Illegal byte sequence" or "Invalid
+or incomplete multibyte or wide character" or "commitAndReleaseBuffer:
+invalid argument (invalid character)"*
+Programs compiled with GHC (hledger, haskell build tools, etc.)  need
+the system locale to be UTF-8-aware, or they will fail when they
+encounter non-ascii characters.  To fix it, set the LANG environment
+variable to a locale which supports UTF-8 and which is installed on your
+system.
+
+   On unix, 'locale -a' lists the installed locales.  Look for one which
+mentions 'utf8', 'UTF-8' or similar.  Some examples: 'C.UTF-8',
+'en_US.utf-8', 'fr_FR.utf8'.  If necessary, use your system package
+manager to install one.  Then select it by setting the 'LANG'
+environment variable.  Note, exact spelling and capitalisation of the
+locale name may be important: Here's one common way to configure this
+permanently for your shell:
+
+$ echo "export LANG=en_US.utf8" >>~/.profile
+# close and re-open terminal window
+
+   If you are using Nix (not NixOS) for GHC and Hledger, you might need
+to set the 'LOCALE_ARCHIVE' variable:
+
+$ echo "export LOCALE_ARCHIVE=${glibcLocales}/lib/locale/locale-archive" >>~/.profile
+# close and re-open terminal window
+
+   *COMPATIBILITY ISSUES: hledger gives an error with my Ledger file*
+Not all of Ledger's journal file syntax or feature set is supported.
+See hledger and Ledger for full details.
+
+
+Tag Table:
+Node: Top208
+Node: PART 1 USER INTERFACE4360
+Node: Input4499
+Node: Text encoding5591
+Node: Data formats6448
+Node: Standard input8172
+Node: Multiple files8561
+Node: Strict mode9298
+Node: Commands10132
+Node: Add-on commands11318
+Node: Options12536
+Node: Special characters19110
+Node: Escaping shell special characters20060
+Node: Escaping on Windows21304
+Node: Escaping regular expression special characters22037
+Node: Escaping add-on arguments23024
+Node: Escaping in other situations24053
+Node: Using a wild card25012
+Node: Unicode characters25391
+Node: Regular expressions27055
+Node: hledger's regular expressions30314
+Node: Argument files31955
+Node: Config files32658
+Node: Shell completions35811
+Node: Output36300
+Node: Output destination36491
+Node: Output format37049
+Node: Text output38835
+Node: Box-drawing characters39814
+Node: Colour40314
+Node: Paging40900
+Node: HTML output42426
+Node: CSV / TSV output42880
+Node: FODS output43134
+Node: Beancount output43938
+Node: Beancount account names45393
+Node: Beancount commodity names45934
+Node: Beancount virtual postings46581
+Node: Beancount metadata46897
+Node: Beancount costs47677
+Node: Beancount operating currency48093
+Node: SQL output48543
+Node: JSON output49334
+Node: Commodity styles50151
+Node: Debug output51038
+Node: Environment51870
+Node: PART 2 DATA FORMATS52527
+Node: Journal52670
+Node: Journal cheatsheet55148
+Node: Comments61362
+Node: Transactions62306
+Node: Dates63443
+Node: Simple dates63595
+Node: Posting dates64211
+Node: Status65298
+Node: Code67064
+Node: Description67399
+Node: Payee and note68086
+Node: Transaction comments69177
+Node: Postings69693
+Node: Debits and credits70856
+Node: The two space delimiter71466
+Node: Account names72031
+Node: Amounts73835
+Node: Decimal marks74864
+Node: Digit group marks75968
+Node: Commodity76603
+Node: Costs77720
+Node: Balance assertions79972
+Node: Assertions and ordering81235
+Node: Assertions and multiple included files81963
+Node: Assertions and multiple -f files82723
+Node: Assertions and costs83365
+Node: Assertions and commodities84015
+Node: Assertions and subaccounts85674
+Node: Assertions and status86334
+Node: Assertions and virtual postings86754
+Node: Assertions and auto postings87119
+Node: Assertions and precision87994
+Node: Posting comments88445
+Node: Transaction balancing88985
+Node: Tags90987
+Node: Querying with tags92281
+Node: Displaying tags93080
+Node: When to use tags ?93476
+Node: Tag names94140
+Node: Special tags94693
+Node: Directives96258
+Node: Directives and multiple files97715
+Node: Directive effects98660
+Node: account directive101816
+Node: Account comments103266
+Node: Account error checking103925
+Node: Account display order105462
+Node: Account types106660
+Node: alias directive110434
+Node: Basic aliases111645
+Node: Regex aliases112520
+Node: Combining aliases113567
+Node: Aliases and multiple files115021
+Node: end aliases directive115804
+Node: Aliases can generate bad account names116172
+Node: Aliases and account types117005
+Node: commodity directive117897
+Node: Commodity directive syntax119484
+Node: Commodity error checking121133
+Node: decimal-mark directive121608
+Node: include directive122187
+Node: P directive123263
+Node: payee directive124297
+Node: tag directive124919
+Node: Periodic transactions125531
+Node: Periodic rule syntax127685
+Node: Periodic rules and relative dates128508
+Node: Two spaces between period expression and description!129285
+Node: Auto postings130246
+Node: Auto postings and multiple files133406
+Node: Auto postings and dates133811
+Node: Auto postings and transaction balancing / inferred amounts / balance assertions134252
+Node: Auto posting tags135098
+Node: Auto postings on forecast transactions only135993
+Node: Other syntax136463
+Node: Balance assignments137235
+Node: Balance assignments and costs138763
+Node: Balance assignments and multiple files139185
+Node: Bracketed posting dates139608
+Node: D directive140306
+Node: apply account directive142079
+Node: Y directive142946
+Node: Secondary dates143934
+Node: Star comments145419
+Node: Valuation expressions146111
+Node: Virtual postings146410
+Node: Other Ledger directives148034
+Node: Other cost/lot notations148796
+Node: CSV151637
+Node: CSV rules cheatsheet153733
+Node: source155760
+Node: encoding156760
+Node: separator157699
+Node: skip158352
+Node: date-format159002
+Node: timezone159845
+Node: newest-first160971
+Node: intra-day-reversed161684
+Node: decimal-mark162284
+Node: fields list162764
+Node: Field assignment164572
+Node: Field names165791
+Node: date field167123
+Node: date2 field167287
+Node: status field167482
+Node: code field167672
+Node: description field167860
+Node: comment field168077
+Node: account field168634
+Node: amount field169352
+Node: currency field172191
+Node: balance field172599
+Node: if block173122
+Node: Matchers174649
+Node: Multiple matchers176639
+Node: Match groups177447
+Node: if table178340
+Node: balance-type180403
+Node: include181230
+Node: Working with CSV181799
+Node: Rapid feedback182351
+Node: Valid CSV182934
+Node: File Extension183810
+Node: Reading CSV from standard input184545
+Node: Reading multiple CSV files184931
+Node: Reading files specified by rule185407
+Node: Valid transactions186804
+Node: Deduplicating importing187629
+Node: Setting amounts188858
+Node: Amount signs191385
+Node: Setting currency/commodity192450
+Node: Amount decimal places193826
+Node: Referencing other fields195083
+Node: How CSV rules are evaluated196191
+Node: Well factored rules197859
+Node: CSV rules examples198349
+Node: Bank of Ireland198547
+Node: Coinbase200144
+Node: Amazon201327
+Node: Paypal203169
+Node: Timeclock210919
+Node: Timedot213188
+Node: Timedot examples216665
+Node: PART 3 REPORTING CONCEPTS218942
+Node: Time periods219106
+Node: Report start & end date219379
+Node: Smart dates220855
+Node: Report intervals222798
+Node: Date adjustments223372
+Node: Start date adjustment223592
+Node: End date adjustment224495
+Node: Period headings225240
+Node: Period expressions226173
+Node: Period expressions with a report interval228078
+Node: More complex report intervals228526
+Node: Multiple weekday intervals230642
+Node: Depth231653
+Node: Queries233488
+Node: Query types235186
+Node: acct query235603
+Node: amt query235914
+Node: code query236531
+Node: cur query236726
+Node: desc query237332
+Node: date query237515
+Node: date2 query237911
+Node: depth query238202
+Node: expr query238538
+Node: not query238919
+Node: note query239259
+Node: payee query239525
+Node: real query239806
+Node: status query240011
+Node: type query240251
+Node: tag query240784
+Node: Combining query terms241413
+Node: Queries and command options243153
+Node: Queries and account aliases243607
+Node: Queries and valuation243932
+Node: Pivoting244294
+Node: Generating data246570
+Node: Forecasting248370
+Node: --forecast249026
+Node: Inspecting forecast transactions250127
+Node: Forecast reports251460
+Node: Forecast tags252569
+Node: Forecast period in detail253189
+Node: Forecast troubleshooting254277
+Node: Budgeting255348
+Node: Amount formatting255908
+Node: Commodity display style256152
+Node: Rounding257993
+Node: Trailing decimal marks258598
+Node: Amount parseability259531
+Node: Cost reporting261112
+Node: Recording costs261943
+Node: Reporting at cost263670
+Node: Equity conversion postings264435
+Node: Inferring equity conversion postings267080
+Node: Combining costs and equity conversion postings268222
+Node: Requirements for detecting equity conversion postings269447
+Node: Infer cost and equity by default ?270969
+Node: Value reporting271406
+Node: -V Value272342
+Node: -X Value in specified commodity272669
+Node: Valuation date273019
+Node: Finding market price273979
+Node: --infer-market-prices market prices from transactions275359
+Node: Valuation commodity278403
+Node: --value Flexible valuation279836
+Node: Valuation examples281679
+Node: Interaction of valuation and queries283811
+Node: Effect of valuation on reports284528
+Node: PART 4 COMMANDS292426
+Node: Help commands294642
+Node: commands294828
+Node: demo295036
+Node: help296270
+Node: User interface commands297975
+Node: repl298186
+Node: Examples300656
+Node: run301214
+Node: Examples 2303631
+Node: ui304655
+Node: web304792
+Node: Data entry commands304920
+Node: add305118
+Node: import307573
+Node: Import preview308607
+Node: Overlap detection309555
+Node: First import312441
+Node: Importing balance assignments313636
+Node: Import and commodity styles314691
+Node: Import special cases315129
+Node: Basic report commands316464
+Node: accounts316765
+Node: codes319638
+Node: commodities320660
+Node: descriptions320904
+Node: files321371
+Node: notes321668
+Node: payees322180
+Node: prices322964
+Node: stats323856
+Node: tags325597
+Node: Standard report commands326904
+Node: print327209
+Node: print explicitness329950
+Node: print amount style330870
+Node: print parseability332108
+Node: print other features333027
+Node: print output format333890
+Node: aregister337175
+Node: aregister and posting dates341634
+Node: register342535
+Node: Custom register output349710
+Node: balancesheet350895
+Node: balancesheetequity355665
+Node: cashflow360805
+Node: incomestatement365367
+Node: Advanced report commands369965
+Node: balance370173
+Node: balance features375349
+Node: Simple balance report377425
+Node: Balance report line format379235
+Node: Filtered balance report381595
+Node: List or tree mode382114
+Node: Depth limiting383627
+Node: Dropping top-level accounts384394
+Node: Showing declared accounts384904
+Node: Sorting by amount385634
+Node: Percentages386471
+Node: Multi-period balance report387178
+Node: Balance change end balance389930
+Node: Balance report types391567
+Node: Calculation type392246
+Node: Accumulation type392950
+Node: Valuation type394051
+Node: Combining balance report types395240
+Node: Budget report397272
+Node: Using the budget report399577
+Node: Budget date surprises401853
+Node: Selecting budget goals403217
+Node: Budgeting vs forecasting404165
+Node: Balance report layout405842
+Node: Wide layout407047
+Node: Tall layout409452
+Node: Bare layout410758
+Node: Tidy layout412822
+Node: Balance report output414366
+Node: Some useful balance reports415181
+Node: roi416441
+Node: Spaces and special characters in --inv and --pnl418688
+Node: Semantics of --inv and --pnl419414
+Node: IRR and TWR explained421501
+Node: Chart commands424912
+Node: activity425093
+Node: Data generation commands425590
+Node: close425796
+Node: close --clopen428359
+Node: close --close430533
+Node: close --open431057
+Node: close --assert431307
+Node: close --assign431634
+Node: close --retain432313
+Node: close customisation433170
+Node: close and balance assertions434814
+Node: close examples436336
+Node: Retain earnings436573
+Node: Migrate balances to a new file437076
+Node: More detailed close examples438438
+Node: rewrite438660
+Node: Re-write rules in a file441232
+Node: Diff output format442542
+Node: rewrite vs print --auto443815
+Node: Maintenance commands444529
+Node: check444738
+Node: Basic checks445820
+Node: Strict checks446773
+Node: Other checks447648
+Node: Custom checks449503
+Node: diff449958
+Node: test451165
+Node: PART 5 COMMON TASKS452037
+Node: Getting help452270
+Node: Constructing command lines453179
+Node: Starting a journal file454017
+Node: Setting LEDGER_FILE455401
+Node: Setting opening balances456659
+Node: Recording transactions459981
+Node: Reconciling460706
+Node: Reporting463095
+Node: Migrating to a new file467209
+Node: BUGS467658
+Node: Troubleshooting468623
 
 End Tag Table
 
diff --git a/embeddedfiles/hledger.txt b/embeddedfiles/hledger.txt
--- a/embeddedfiles/hledger.txt
+++ b/embeddedfiles/hledger.txt
@@ -19,10070 +19,10327 @@
        and  largely  compatible  with  ledger(1), and largely interconvertible
        with beancount(1).
 
-       This manual is for hledger's command line interface, version 1.41.   It
-       also  describes  the  common options, file formats and concepts used by
-       all hledger programs.  It might accidentally teach you  some  bookkeep-
-       ing/accounting  as  well!  You don't need to know everything in here to
-       use hledger productively, but when you have a question about  function-
-       ality,  this doc should answer it.  It is detailed, so do skip ahead or
-       skim when needed.  You can read it on hledger.org, or as an info manual
-       or man page on your system.  You can also open a built-in  copy,  at  a
-       point of interest, by running
-       hledger --man [CMD], hledger --info [CMD] or hledger help [TOPIC].
-
-       (And for shorter help, try hledger --tldr [CMD].)
-
-       The  main  function  of the hledger CLI is to read plain text files de-
-       scribing financial transactions, crunch the numbers, and print a useful
-       report on the terminal (or save it as HTML, CSV, JSON  or  SQL).   Many
-       reports  are available, as subcommands.  hledger will also detect other
-       hledger-* executables as extra subcommands.
-
-       hledger usually reads from (and appends to) a journal file specified by
-       the     LEDGER_FILE     environment     variable     (defaulting     to
-       $HOME/.hledger.journal);  or you can specify files with -f options.  It
-       can also read timeclock files, timedot files, or any  CSV/SSV/TSV  file
-       with a date field.
-
-       Here is a small journal file describing one transaction:
-
-              2015-10-16 bought food
-                expenses:food          $10
-                assets:cash
-
-       Transactions  are  dated movements of money (etc.)  between two or more
-       accounts: bank accounts, your wallet, revenue/expense categories,  peo-
-       ple,  etc.  You can choose any account names you wish, using : to indi-
-       cate subaccounts.  There must be at least two  spaces  between  account
-       name  and amount.  Positive amounts are inflow to that account (debit),
-       negatives are outflow from it (credit).  (Some  reports  show  revenue,
-       liability  and equity account balances as negative numbers as a result;
-       this is normal.)
-
-       hledger's add command can help you add transactions, or you can install
-       other data entry UIs like hledger-web or hledger-iadd.  For more exten-
-       sive/efficient changes, use a text editor: Emacs + ledger-mode,  VIM  +
-       vim-ledger,  or  VS  Code  +  hledger-vscode are some good choices (see
-       https://hledger.org/editors.html).
-
-       To get started, run hledger add and follow the prompts,  or  save  some
-       entries  like  the  above  in $HOME/.hledger.journal, then try commands
-       like:
-
-              $ hledger print -x
-              $ hledger aregister assets
-              $ hledger balance
-              $ hledger balancesheet
-              $ hledger incomestatement
-
-       Run hledger to list the commands.  See also  the  "Starting  a  journal
-       file" and "Setting opening balances" sections in PART 5: COMMON TASKS.
-
-PART 1: USER INTERFACE
-Input
-       hledger  reads  one  or more data files, each time you run it.  You can
-       specify a file with -f, like so
-
-              $ hledger -f FILE [-f FILE2 ...] print
-
-       Files are most often in hledger's journal  format,  with  the  .journal
-       file  extension (.hledger or .j also work); these files describe trans-
-       actions, like an accounting general journal.
-
-       When no file is specified, hledger looks for .hledger.journal  in  your
-       home directory.
-
-       But  most  people prefer to keep financial files in a dedicated folder,
-       perhaps with version control.  Also, starting a new journal  file  each
-       year  is  common (it's not required, but helps keep things fast and or-
-       ganised).  So we usually configure a different journal file, by setting
-       the  LEDGER_FILE  environment  variable,  to   something   like   ~/fi-
-       nance/2023.journal.   For more about how to do that on your system, see
-       Common tasks > Setting LEDGER_FILE.
-
-   Text encoding
-       Data files containing non-ascii characters must use UTF-8 encoding.  An
-       optional byte order mark (BOM) is allowed, at the beginning of the file
-       (only).
-
-       Also, your system should be configured with a locale  that  can  decode
-       UTF-8  text.   On some unix systems, you may need set the LANG environ-
-       ment variable, eg.  You can read more about this in Unicode characters,
-       below.
-
-       On unix systems you can check a file's encoding with the file  command.
-       If you need to import from a UTF-16-encoded CSV file, say, you can con-
-       vert it to UTF-8 with the iconv command.
-
-   Data formats
-       Usually  the data file is in hledger's journal format, but it can be in
-       any of the supported file formats, which currently are:
-
-       Reader:         Reads:                              Automatically used  for
-                                                           files with extensions:
-       -----------------------------------------------------------------------------
-       journal         hledger  journal  files  and some   .journal  .j   .hledger
-                       Ledger journals, for transactions   .ledger
-       timeclock       timeclock files, for precise time   .timeclock
-                       logging
-       timedot         timedot  files,  for  approximate   .timedot
-                       time logging
-       csv             Comma or  other  character  sepa-   .csv
-                       rated values, for data import
-       ssv             Semicolon separated values          .ssv
-       tsv             Tab separated values                .tsv
-       rules           CSV/SSV/TSV/other  separated val-   .rules
-                       ues, alternate way
-
-       These formats are described in more detail below.
-
-       hledger detects the format automatically based on the  file  extensions
-       shown  above.   If  it  can't  recognise the file extension, it assumes
-       journal format.  So for non-journal files,  it's  important  to  use  a
-       recognised file extension, so as to either read successfully or to show
-       relevant error messages.
-
-       You  can also force a specific reader/format by prefixing the file path
-       with the format and a colon.  Eg, to read a .dat  file  containing  tab
-       separated values:
-
-              $ hledger -f tsv:/some/file.dat stats
-
-   Standard input
-       The file name - means standard input:
-
-              $ cat FILE | hledger -f- print
-
-       If  reading non-journal data in this way, you'll need to write the for-
-       mat as a prefix, like timeclock: here:
-
-              $ echo 'i 2009/13/1 08:00:00' | hledger print -f timeclock:-
-
-   Multiple files
-       You can specify multiple -f options, to read multiple files as one  big
-       journal.  When doing this, note that certain features (described below)
-       will be affected:
-
-       o Balance  assertions will not see the effect of transactions in previ-
-         ous files.  (Usually this doesn't matter as each file  will  set  the
-         corresponding opening balances.)
-
-       o Some directives will not affect previous or subsequent files.
-
-       If  needed,  you  can  work  around these by using a single parent file
-       which includes the others, or concatenating the files into one, eg: cat
-       a.journal b.journal | hledger -f- CMD.
-
-   Strict mode
-       hledger checks input files for valid data.  By default, the most impor-
-       tant errors are detected, while  still  accepting  easy  journal  files
-       without a lot of declarations:
-
-       o Are the input files parseable, with valid syntax ?
-
-       o Are all transactions balanced ?
-
-       o Do all balance assertions pass ?
-
-       With the -s/--strict flag, additional checks are performed:
-
-       o Are  all  accounts  posted  to,  declared with an account directive ?
-         (Account error checking)
-
-       o Are all commodities declared with a commodity directive ?  (Commodity
-         error checking)
-
-       o Are all commodity conversions declared explicitly ?
-
-       You can use the check command to run  individual  checks  --  the  ones
-       listed above and some more.
-
-Commands
-       hledger  provides various subcommands for getting things done.  Most of
-       these commands do not change the journal file; they just  read  it  and
-       output  a report.  A few commands assist with adding data and file man-
-       agement.
-
-       To show a summary of commands, run hledger with no arguments.  You  can
-       see the same commands summary at the start of PART 4: COMMANDS below.
-
-       To use a particular command, run hledger CMD [CMDOPTS] [CMDARGS],
-
-       o CMD  is  the full command name, or its standard abbreviation shown in
-         the commands list, or any unambiguous prefix of the name.
-
-       o CMDOPTS are command-specific options, if any.   Command-specific  op-
-         tions must be written after the command name.  Eg: hledger print -x.
-
-       o CMDARGS  are  additional  arguments  to  the  command,  if any.  Most
-         hledger commands accept arguments representing a query, to limit  the
-         data in some way.  Eg: hledger reg assets:checking.
-
-       To list a command's options, arguments, and documentation in the termi-
-       nal, run hledger CMD -h.  Eg: hledger bal -h.
-
-   Add-on commands
-       In  addition to the built-in commands, you can install add-on commands:
-       programs or scripts named "hledger-SOMETHING", which will  also  appear
-       in  hledger's  commands  list.  If you used the hledger-install script,
-       you will have several add-ons installed  already.   Some  more  can  be
-       found     in     hledger's     bin/     directory,     documented    at
-       https://hledger.org/scripts.html.
-
-       More precisely, add-on commands are programs or scripts in your shell's
-       PATH, whose name starts with "hledger-" and ends with no extension or a
-       recognised extension (".bat", ".com",  ".exe",  ".hs",  ".js",  ".lhs",
-       ".lua",  ".php",  ".pl",  ".py", ".rb", ".rkt", or ".sh"), and (on unix
-       and mac) which has executable permission for the current user.
-
-       You can run add-on commands using hledger, much like built-in commands:
-       hledger ADDONCMD [-- ADDONCMDOPTS] [ADDONCMDARGS].  But note the double
-       hyphen argument, required before add-on-specific options.  Eg:  hledger
-       ui  --  --watch  or hledger web -- --serve.  If this causes difficulty,
-       you  can  always  run  the  add-on  directly,  without  using  hledger:
-       hledger-ui --watch or hledger-web --serve.
-
-Options
-       Run  hledger -h to see general command line help.  Options can be writ-
-       ten either before or after the command name.  These  options  are  spe-
-       cific to the hledger CLI:
-
-              Flags:
-                   --conf=CONFFILE        Use extra options defined in this config file. If
-                                          not specified, searches upward and in XDG config
-                                          dir for hledger.conf (or .hledger.conf in $HOME).
-                -n --no-conf              ignore any config file
-
-       And the following general options are common to most hledger commands:
-
-              General input/data transformation flags:
-                -f --file=[FMT:]FILE      Read data from FILE, or from stdin if FILE is -,
-                                          inferring format from extension or a FMT: prefix.
-                                          Can be specified more than once. If not specified,
-                                          reads from $LEDGER_FILE or $HOME/.hledger.journal.
-                   --rules=RULESFILE      Use rules defined in this rules file for
-                                          converting subsequent CSV/SSV/TSV files. If not
-                                          specified, uses FILE.csv.rules for each FILE.csv.
-                   --alias=A=B|/RGX/=RPL  transform account names from A to B, or by
-                                          replacing regular expression matches
-                   --auto                 generate extra postings by applying auto posting
-                                          rules ("=") to all transactions
-                   --forecast[=PERIOD]    Generate extra transactions from periodic rules
-                                          ("~"), from after the latest ordinary transaction
-                                          until 6 months from now. Or, during the specified
-                                          PERIOD (the equals is required). Auto posting rules
-                                          will also be applied to these transactions. In
-                                          hledger-ui, also make future-dated transactions
-                                          visible at startup.
-                -I --ignore-assertions    don't check balance assertions by default
-                   --infer-costs          infer conversion equity postings from costs
-                   --infer-equity         infer costs from conversion equity postings
-                   --infer-market-prices  infer market prices from costs
-                   --pivot=TAGNAME        use a different field or tag as account names
-                -s --strict               do extra error checks (and override -I)
-                   --verbose-tags         add tags indicating generated/modified data
-
-              General output/reporting flags (supported by some commands):
-                -b --begin=DATE           include postings/transactions on/after this date
-                -e --end=DATE             include postings/transactions before this date
-                                          (with a report interval, will be adjusted to
-                                          following subperiod end)
-                -D --daily                multiperiod report with 1 day interval
-                -W --weekly               multiperiod report with 1 week interval
-                -M --monthly              multiperiod report with 1 month interval
-                -Q --quarterly            multiperiod report with 1 quarter interval
-                -Y --yearly               multiperiod report with 1 year interval
-                -p --period=PERIODEXP     set begin date, end date, and/or report interval,
-                                          with more flexibility
-                   --today=DATE           override today's date (affects relative dates)
-                   --date2                match/use secondary dates instead (deprecated)
-                -U --unmarked             include only unmarked postings/transactions
-                -P --pending              include only pending postings/transactions
-                -C --cleared              include only cleared postings/transactions
-                                          (-U/-P/-C can be combined)
-                -R --real                 include only non-virtual postings
-                -E --empty                Show zero items, which are normally hidden.
-                                          In hledger-ui & hledger-web, do the opposite.
-                   --depth=DEPTHEXP       if a number (or -NUM): show only top NUM levels
-                                          of accounts. If REGEXP=NUM, only apply limiting to
-                                          accounts matching the regular expression.
-                -B --cost                 show amounts converted to their cost/sale amount
-                -V --market               Show amounts converted to their value at period
-                                          end(s) in their default valuation commodity.
-                                          Equivalent to --value=end.
-                -X --exchange=COMM        Show amounts converted to their value at period
-                                          end(s) in the specified commodity.
-                                          Equivalent to --value=end,COMM.
-                   --value=WHEN[,COMM]    show amounts converted to their value on the
-                                          specified date(s) in their default valuation
-                                          commodity or a specified commodity. WHEN can be:
-                                          'then':     value on transaction dates
-                                          'end':      value at period end(s)
-                                          'now':      value today
-                                          YYYY-MM-DD: value on given date
-                -c --commodity-style=S    Override a commodity's display style.
-                                          Eg: -c '.' or -c '1.000,00 EUR'
-                   --pretty[=YN]          Use box-drawing characters in text output? Can be
-                                          'y'/'yes' or 'n'/'no'.
-                                          If YN is specified, the equals is required.
-
-              General help flags:
-                -h --help                 show command line help
-                   --tldr                 show command examples with tldr
-                   --info                 show the manual with info
-                   --man                  show the manual with man
-                   --version              show version information
-                   --debug=[1-9]          show this much debug output (default: 1)
-                   --pager=YN             use a pager when needed ? y/yes (default) or n/no
-                   --color=YNA --colour   use ANSI color ? y/yes, n/no, or auto (default)
-
-       Usually  hledger  accepts any unambiguous flag prefix, eg you can write
-       --tl instead of --tldr or --dry instead of --dry-run.
-
-       If the same option appears more than once in  a  command,  usually  the
-       last (right-most) wins.
-
-       With  most commands, arguments are interpreted as a hledger query which
-       filter the data.  Some queries can be expressed either with options  or
-       with arguments.
-
-       Below are more tips for using the command line interface - feel free to
-       skip these until you need them.
-
-   Special characters
-       Here  we touch on shell escaping/quoting rules, and give some examples.
-       This is a slightly complicated topic which you may not need  at  first,
-       but you should be aware of it, so you can return here when needed.
-
-       If you are able to minimise the use of special characters in your data,
-       you  won't  need  escaping as much, and your command lines will be sim-
-       pler.  For example, avoiding spaces in  account  names,  and  using  an
-       ISO-4217  currency  code like USD instead of the $ currency symbol, can
-       be helpful.
-
-       But if you want to use spaced account names and $, go right ahead;  es-
-       caping isn't a big deal.
-
-   Escaping shell special characters
-       At  the  command  line,  characters which have special meaning for your
-       shell must be "shell-escaped" (AKA "quoted") if you want hledger to see
-       them.  Often these include space, <, >, (, ), |, \, $ and/or %.
-
-       For example, to match an account name  containing  the  phrase  "credit
-       card", don't write this:
-
-              $ hledger register credit card
-
-       In  that command, "credit" and "card" are treated as separate query ar-
-       guments (described below), so this would match accounts containing  ei-
-       ther word.  Instead, enclose the phrase in double or single quotes:
-
-              $ hledger register "credit card"
-
-       In Unix shells, writing a backslash before the character can also work.
-       Eg:
-
-              $ hledger register credit\ card
-
-       Some  shell  characters  still  have  a  special  meaning inside double
-       quotes, such as the dollar sign ($).  Eg in "assets:$account", the bash
-       shell would replace $account with the value of a  shell  variable  with
-       that  name.   When you don't want that, use single quotes, which escape
-       more strongly:
-
-              $ hledger balance 'assets:$account'
-
-   Escaping on Windows
-       If you are using hledger in a Powershell or Command window on Microsoft
-       Windows, the escaping rules are different:
-
-       o In a Powershell window (powershell, blue background),  you  must  use
-         double quotes or single quotes (not backslash).
-
-       o In  a  Command  window  (cmd,  black background), you must use double
-         quotes (not single quotes or backslash).
-
-       The next two sections were written for Unix-like shells, so might  need
-       to be adapted if you're using cmd or powershell.  (Edits welcome.)
-
-   Escaping regular expression special characters
-       Many  hledger  arguments are regular expressions (described below), and
-       these too have characters which cause special effects.  Some  of  those
-       characters  are  .,  ^,  $,  [, ], (, ), |, and \.  When you don't want
-       these to cause special effects, you can "regex-escape" them by  writing
-       \  (a  backslash)  before them.  But since backslash is also special to
-       the shell, you may need to also shell-escape the backslashes.
-
-       Eg, in the bash shell, to match a literal $ sign, you could write:
-
-              $ hledger balance cur:\\$
-
-       or:
-
-              $ hledger balance 'cur:\$'
-
-       (The dollar sign is regex-escaped by the backslash preceding it.   Then
-       that  backslash  is  shell-escaped  by  another backslash, or by single
-       quotes.)
-
-   Escaping add-on arguments
-       When you run an external add-on command with hledger (described below),
-       any options or arguments being passed through to the add-on  executable
-       lose  one  level  of  shell-escaping, so you must add an extra level of
-       shell-escaping to compensate.
-
-       Eg, in the bash shell, to run the ui add-on and match a literal $ sign,
-       you need to write:
-
-              $ hledger ui cur:'\\$'
-
-       or:
-
-              $ hledger ui cur:\\\\$
-
-       If you are wondering why four backslashes:
-
-       o $ is unescaped
-
-       o \$ is regex-escaped
-
-       o \\$ is regex-escaped, then shell-escaped
-
-       o \\\\$ is regex-escaped, then shell-escaped,  then  both  slashes  are
-         shell-escaped once more for hledger argument pass-through.
-
-       Or you can avoid such triple-escaping, by running the add-on executable
-       directly:
-
-              $ hledger-ui cur:\\$
-
-   Escaping in other situations
-       hledger  options  and arguments are sometimes used in places other than
-       the command line, with different escaping rules.   For  example,  back-
-       slash-quoting generally does not work there.  Here are some more tips.
-
-       In Windows cmd      Use double quotes
-       In Windows power-   Use single or double quotes
-       shell
-       In   hledger-ui's   Use single or double quotes
-       filter prompt
-       In  hledger-web's   Use single or double quotes
-       search form
-       In   an  argument   Don't use spaces, don't shell-escape,  do  regex-es-
-       file                cape when needed
-       In a config file    Use  single  or double quotes, and enclose the whole
-                           argument ("desc:a b" not desc:"a b")
-       In   ghci    (the   Use double quotes, and enclose the whole argument
-       Haskell REPL)
-
-   Using a wild card
-       When  escaping  a special character is too much hassle (or impossible),
-       you can often just write . (period) instead.  In  regular  expressions,
-       this means "accept any character here".  Eg:
-
-              $ hledger register credit.card
-
-   Unicode characters
-       hledger is expected to handle non-ascii characters correctly:
-
-       o they  should  be  parsed  correctly in input files and on the command
-         line, by all hledger tools (add, iadd, hledger-web's  search/add/edit
-         forms, etc.)
-
-       o they  should  be  displayed  correctly  by  all  hledger  tools,  and
-         on-screen alignment should be preserved.
-
-       This requires a well-configured environment.  Here are some tips:
-
-       o A system locale must be configured, and it must be one that  can  de-
-         code  the  characters being used.  In bash, you can set a locale like
-         this: export LANG=en_US.UTF-8.  There are some more details in  Trou-
-         bleshooting.   This step is essential - without it, hledger will quit
-         on encountering a non-ascii character (as with all GHC-compiled  pro-
-         grams).
-
-       o Your  terminal  software  (eg  Terminal.app, iTerm, CMD.exe, xterm..)
-         must support unicode.  On Windows, you may need to use Windows Termi-
-         nal and/or enable UTF-8 support.
-
-       o The terminal must be using a font which includes the required unicode
-         glyphs.
-
-       o The terminal should be configured to display wide characters as  dou-
-         ble width (for report alignment).
-
-       o On  Windows, for best results you should run hledger in the same kind
-         of environment in which it was built.  Eg hledger built in the  stan-
-         dard  CMD.EXE  environment  (like  the binaries on our download page)
-         might show display problems when run in a cygwin  or  msys  terminal,
-         and vice versa.  (See eg #961).
-
-   Regular expressions
-       A  regular  expression  (regexp) is a small piece of text where certain
-       characters (like ., ^, $, +, *, (), |, [], \)  have  special  meanings,
-       forming  a  tiny  language for matching text precisely - very useful in
-       hledger and elsewhere.  To learn all about them, visit  regular-expres-
-       sions.info.
-
-       hledger  supports  regexps whenever you are entering a pattern to match
-       something, eg in  query  arguments,  account  aliases,  CSV  if  rules,
-       hledger-web's search form, hledger-ui's / search, etc.  You may need to
-       wrap  them in quotes, especially at the command line (see Special char-
-       acters above).  Here are some examples:
-
-       Account name queries (quoted for command line use):
-
-              Regular expression:  Matches:
-              -------------------  ------------------------------------------------------------
-              bank                 assets:bank, assets:bank:savings, expenses:art:banksy, ...
-              :bank                assets:bank:savings, expenses:art:banksy
-              :bank:               assets:bank:savings
-              '^bank'              none of those ( ^ matches beginning of text )
-              'bank$'              assets:bank   ( $ matches end of text )
-              'big \$ bank'        big $ bank    ( \ disables following character's special meaning )
-              '\bbank\b'           assets:bank, assets:bank:savings  ( \b matches word boundaries )
-              '(sav|check)ing'     saving or checking  ( (|) matches either alternative )
-              'saving|checking'    saving or checking  ( outer parentheses are not needed )
-              'savings?'           saving or savings   ( ? matches 0 or 1 of the preceding thing )
-              'my +bank'           my bank, my  bank, ... ( + matches 1 or more of the preceding thing )
-              'my *bank'           mybank, my bank, my  bank, ... ( * matches 0 or more of the preceding thing )
-              'b.nk'               bank, bonk, b nk, ... ( . matches any character )
-
-       Some other queries:
-
-              desc:'amazon|amzn|audible'  Amazon transactions
-              cur:EUR              amounts with commodity symbol containing EUR
-              cur:'\$'             amounts with commodity symbol containing $
-              cur:'^\$$'           only $ amounts, not eg AU$ or CA$
-              cur:....?            amounts with 4-or-more-character symbols
-              tag:.=202[1-3]       things with any tag whose value contains 2021, 2022 or 2023
-
-       Account name aliases: accept . instead of : as account separator:
-
-              alias /\./=:         replaces all periods in account names with colons
-
-       Show multiple top-level accounts combined as one:
-
-              --alias='/^[^:]+/=combined'  ( [^:] matches any character other than : )
-
-       Show accounts with the second-level part removed:
-
-              --alias '/^([^:]+):[^:]+/ = \1'
-                                   match a top-level account and a second-level account
-                                   and replace those with just the top-level account
-                                   ( \1 in the replacement text means "whatever was matched
-                                   by the first parenthesised part of the regexp"
-
-       CSV rules: match CSV records containing dining-related MCC codes:
-
-              if \?MCC581[124]
-
-       Match CSV records with a specific amount around the end/start of month:
-
-              if %amount \b3\.99
-              &  %date   (29|30|31|01|02|03)$
-
-   hledger's regular expressions
-       hledger's regular expressions come from  the  regex-tdfa  library.   If
-       they're  not doing what you expect, it's important to know exactly what
-       they support:
-
-       1. they are case insensitive
-
-       2. they are infix matching (they do not need to match the entire  thing
-          being matched)
-
-       3. they are POSIX ERE (extended regular expressions)
-
-       4. they also support GNU word boundaries (\b, \B, \<, \>)
-
-       5. backreferences  are supported when doing text replacement in account
-          aliases or CSV rules, where backreferences can be used  in  the  re-
-          placement string to reference capturing groups in the search regexp.
-          Otherwise, if you write \1, it will match the digit 1.
-
-       6. they  do  not  support mode modifiers ((?s)), character classes (\w,
-          \d), or anything else not mentioned above.
-
-       7. they may not (I'm guessing not) properly  support  right-to-left  or
-          bidirectional text.
-
-       Some things to note:
-
-       o In  the  alias directive and --alias option, regular expressions must
-         be enclosed in forward  slashes  (/REGEX/).   Elsewhere  in  hledger,
-         these are not required.
-
-       o In  queries,  to match a regular expression metacharacter like $ as a
-         literal character, prepend a backslash.  Eg  to  search  for  amounts
-         with the dollar sign in hledger-web, write cur:\$.
-
-       o On  the command line, some metacharacters like $ have a special mean-
-         ing to the shell and so must be escaped at least once more.  See Spe-
-         cial characters.
-
-   Argument files
-       You can save a set of command line options and arguments in a file, and
-       then reuse them by writing @FILENAME as a command line  argument.   Eg:
-       hledger bal @foo.args.
-
-       An  argument  file's  format is more restrictive than the command line.
-       Each line should contain just one option or argument.  Don't use spaces
-       except inside quotes; write = or nothing between a flag and  its  argu-
-       ment.   If  you  use quotes, they must enclose the whole line.  For the
-       special characters mentioned above, use one less level of quoting  than
-       you would at the command line.
-
-   Config files
-       With  hledger  1.40+, you can save extra command line options and argu-
-       ments in a more featureful hledger config file.  Here's a  small  exam-
-       ple:
-
-              # General options are listed first, and used with hledger commands that support them.
-              --pretty
-
-              # Options following a `[COMMAND]` heading are used with that hledger command only.
-              [print]
-              --explicit --show-costs
-
-       To  use  a config file, specify it with the --conf option.  Its options
-       will be inserted near the start of your command line, so you can  over-
-       ride them with command line options if needed.
-
-       Or,  you  can set up an automatic config file that is used whenever you
-       run hledger, by creating  hledger.conf  in  the  current  directory  or
-       above,  or  .hledger.conf  in your home directory (~/.hledger.conf), or
-       hledger.conf    in    your    XDG     config     directory     (~/.con-
-       fig/hledger/hledger.conf).
-
-       Here    is    another    example   config   you   could   start   with:
-       https://github.com/simonmichael/hledger/blob/master/hledger.conf.sample
-
-       You can put not only options, but also arguments in a config file.   If
-       the  first word in a config file's top (general) section does not begin
-       with a dash (eg: print), it is treated as the command  argument  (over-
-       riding any argument on the command line).
-
-       On  unix  machines,  you  can add a shebang line at the top of a config
-       file, set executable permission on the file, and use it like a  script.
-       Eg (the -S is needed on some operating systems):
-
-              #!/usr/bin/env -S hledger --conf
-
-       You can ignore config files by adding the -n/--no-conf flag to the com-
-       mand line.  This is useful when using hledger in scripts, or when trou-
-       bleshooting.   When  both  --conf  and  --no-conf options are used, the
-       right-most wins.
-
-       To inspect the processing of config files, use --debug or --debug=8.
-
-       Warning!
-
-       There aren't many hledger features that need a  warning,  but  this  is
-       one!
-
-       Automatic  config  files, while convenient, also make hledger less pre-
-       dictable and dependable.  It's easy to make a config file that  changes
-       a  report's  behaviour,  or  breaks your hledger-using scripts/applica-
-       tions, in ways that will surprise you later.
-
-       If you don't want this,
-
-       1. Just don't create a hledger.conf file on your machine.
-
-       2. Also  be  alert  to  downloaded  directories  which  may  contain  a
-          hledger.conf file.
-
-       3. Also  if  you  are  sharing scripts or examples or support, consider
-          that others may have a hledger.conf file.
-
-       Conversely, once you decide to use this feature, try to remember:
-
-       1. Whenever a hledger command does not work as expected, try  it  again
-          with -n (--no-conf) to see if a config file was to blame.
-
-       2. Whenever  you call hledger from a script, consider whether that call
-          should use -n or not.
-
-       3. Be conservative about what you put in your config file; try to  con-
-          sider the effect on all your reports.
-
-       4. To  troubleshoot  the  effect  of  config files, run with --debug or
-          --debug 8.
-
-       The config file feature was added in hledger 1.40 and is considered ex-
-       perimental.
-
-   Shell completions
-       If you use the bash shell, you can optionally set up  context-sensitive
-       autocompletions  when  you  press  TAB in a hledger command line.  At a
-       bash shell prompt, try pressing hledger<SPACE><TAB><TAB>  (should  list
-       all  hledger commands) or hledger reg acct:<TAB><TAB> (should list your
-       top-level account names).  If completions aren't working, or  for  more
-       details, see Install > Shell completions.
-
-Output
-   Output destination
-       hledger commands send their output to the terminal by default.  You can
-       of course redirect this, eg into a file, using standard shell syntax:
-
-              $ hledger print > foo.txt
-
-       Some  commands (print, register, stats, the balance commands) also pro-
-       vide the -o/--output-file option, which does  the  same  thing  without
-       needing the shell.  Eg:
-
-              $ hledger print -o foo.txt
-              $ hledger print -o -        # write to stdout (the default)
-
-   Output format
-       Some  commands offer other kinds of output, not just text on the termi-
-       nal.  Here are those commands and the formats currently supported:
-
-       command                 txt     html     csv/tsv     fods     beancount      sql     json
-       --------------------------------------------------------------------------------------------
-       aregister               Y       Y        Y           Y                               Y
-       balance                 Y       Y        Y           Y                               Y
-       balancesheet            Y       Y        Y           Y                               Y
-       balancesheetequity      Y       Y        Y           Y                               Y
-       cashflow                Y       Y        Y           Y                               Y
-       incomestatement         Y       Y        Y           Y                               Y
-       print                   Y       Y        Y           Y        Y              Y       Y
-       register                Y       Y        Y           Y                               Y
-
-       You can also see which output formats a  command  supports  by  running
-       hledger CMD -h and looking for the -O/--output-format=FMT option,
-
-       You can select the output format by using that option:
-
-              $ hledger print -O csv    # print CSV to standard output
-
-       or  by  choosing  a  suitable  filename  extension  with  the -o/--out-
-       put-file=FILE.FMT option:
-
-              $ hledger balancesheet -o foo.csv    # write CSV to foo.csv
-
-       The -O option can be combined with -o to override the file extension if
-       needed:
-
-              $ hledger balancesheet -o foo.txt -O csv    # write CSV to foo.txt
-
-       Here are some notes about the various output formats.
-
-   Text output
-       This is the default: human readable, plain text report output, suitable
-       for viewing with a monospace font in a terminal.  If your data contains
-       unicode or wide characters, you'll need a terminal and font that render
-       those correctly.  (This can be challenging on MS Windows.)
-
-       Some reports (register, aregister) will use the width indicated by  the
-       COLUMNS  environment  variable.  If your shell and terminal are working
-       well, they will keep COLUMNS updated as you resize the window.  So reg-
-       ister reports normally will use the full window width.  When this isn't
-       working or you want to override it, you can manually  set  COLUMNS,  or
-       use the -w/--width option.
-
-       Balance  reports (balance, balancesheet, incomestatement...)  use what-
-       ever width they need.  Multi-period multi-currency reports can often be
-       wider than the window.  Besides using a pager, helpful  techniques  for
-       this  situation  include  --layout=bare, -V, cur:, --transpose, --tree,
-       --depth, --drop, switching to html output, etc.
-
-   Box-drawing characters
-       hledger draws simple table borders by default, to minimise the risk  of
-       display  problems  caused by a terminal/font not supporting box-drawing
-       characters.
-
-       But your terminal and font probably do support them,  so  we  recommend
-       using  the --pretty flag to show prettier tables in the terminal.  This
-       is a good flag to add to your hledger config file.
-
-   Colour
-       hledger tries to automatically detect ANSI colour and text styling sup-
-       port and use it when appropriate.  (Currently, it is used rather  mini-
-       mally:  some reports show negative numbers in red, and help output uses
-       bold text for emphasis.)
-
-       You can override this by setting the NO_COLOR environment  variable  to
-       disable  it,  or  by using the --color/--colour option, perhaps in your
-       config file, with a y/yes or n/no value to force it on or off.
-
-   Paging
-       In unix-like environments, when displaying large output (in any  output
-       format) in the terminal, hledger tries to use a pager when appropriate.
-       The  pager shows one page of text at a time, and lets you scroll around
-       to see more.  While it is active, usually SPACE shows the next page,  h
-       shows  help,  and q quits.  The home/end/page up/page down/cursor keys,
-       and mouse scrolling, may also work.
-
-       hledger will use the pager specified by the PAGER environment variable,
-       otherwise less if available, otherwise more if  available.   (With  one
-       exception:  hledger  help -p TOPIC will always use less, so that it can
-       scroll to the topic.)
-
-       The pager is  expected  to  display  hledger's  ANSI  colour  and  text
-       styling.   If you see junk characters, you might need to configure your
-       pager to handle ANSI codes.  Or you could disable colour  as  described
-       above.
-
-       If you are using the less pager, hledger automatically appends a number
-       of  options  to the LESS variable to enable ANSI colour and a number of
-       other  conveniences.   (At  the  time  of  writing:   --chop-long-lines
-       --hilite-unread    --ignore-case    --mouse   --no-init   --quit-at-eof
-       --quit-if-one-screen           --RAW-CONTROL-CHARS            --shift=8
-       --squeeze-blank-lines  --use-backslash  --use-color  ).  If these don't
-       work well, you can set your preferred options in the HLEDGER_LESS vari-
-       able, which will be used instead.
-
-   HTML output
-       HTML output can be styled by an optional hledger.css file in  the  same
-       directory.
-
-       HTML output will be UTF-8 encoded.  If your web browser is showing junk
-       characters,  you  may need to change its text encoding to UTF-8.  Eg in
-       Safari, see View -> Text Encoding and Settings -> Advanced  ->  Default
-       Encoding.
-
-   CSV / TSV output
-       In  CSV or TSV output, digit group marks (such as thousands separators)
-       are disabled automatically.
-
-   FODS output
-       FODS is the OpenDocument Spreadsheet format as plain XML,  as  accepted
-       by  LibreOffice  and OpenOffice.  If you use their spreadsheet applica-
-       tions, this is better than CSV because it works across locales (decimal
-       point vs.  decimal comma, character encoding stored in XML header, thus
-       no problems with umlauts), it supports fixed header rows  and  columns,
-       cell  types  (string  vs.   number vs.  date), separation of number and
-       currency (currency is displayed but the cell type is still a number ac-
-       cessible for computation), styles (bold), borders.  Btw.  you can still
-       extract CSV from FODS/ODS  using  various  utilities  like  libreoffice
-       --headless or ods2csv.
-
-   Beancount output
-       This  is  Beancount's  journal format.  You can use this to export your
-       hledger data to Beancount, eg to use the Fava web app.
-
-       hledger will try to adjust your data to suit Beancount,  automatically.
-       Be  cautious  and  check  the  conversion until you are confident it is
-       good.  If you plan to export to Beancount often, you may want to follow
-       its conventions, for a cleaner conversion:
-
-       o use Beancount-friendly account names
-
-       o use currency codes instead of currency symbols
-
-       o use cost notation instead of equity conversion postings
-
-       o avoid virtual postings
-
-       There is one big adjustment you must handle  yourself:  for  Beancount,
-       the  top  level  account names must be Assets, Liabilities, Equity, In-
-       come, and/or Expenses.  You can use account aliases to rewrite your ac-
-       count names temporarily, if needed, as in  this  hledger2beancount.conf
-       config file.
-
-   Beancount account names
-       Aside  from the top-level names, hledger will adjust your account names
-       to make valid Beancount account names, by capitalising each  part,  re-
-       placing  spaces  with  -,  replacing  other unsupported characters with
-       C<HEXBYTES>, prepending A to account name parts which don't begin  with
-       a  letter  or  digit, and appending :A to account names which have only
-       one part.
-
-   Beancount commodity names
-       hledger will adjust your commodity names to make valid  Beancount  com-
-       modity/currency names, which must be 2-24 uppercase letters, digits, or
-       ',  ., _, -, beginning with a letter and ending with a letter or digit.
-       hledger will convert known currency symbols to ISO 4217 currency codes,
-       capitalise letters, replace spaces with -,  replace  other  unsupported
-       characters with C<HEXBYTES>, and prepend or append C if needed.
-
-   Beancount virtual postings
-       Beancount doesn't allow virtual postings; if you have any, they will be
-       omitted from beancount output.
-
-   Beancount metadata
-       hledger  tags  will be converted to Beancount metadata (except for tags
-       whose name begins with _).  Metadata names will be adjusted to be Bean-
-       count-compatible: beginning with a lowercase letter, at least two char-
-       acters long, and with unsupported characters encoded.  Metadata  values
-       will use Beancount's string type.
-
-       In  hledger,  objects can have the same tag repeated with multiple val-
-       ues.   Eg  an  assets:cash  account  might  have  both  type:Asset  and
-       type:Cash  tags.   For  Beancount these will be combined into one, with
-       the values combined, comma separated.  Eg: type: "Asset, Cash".
-
-   Beancount costs
-       Beancount doesn't allow redundant  costs  and  conversion  postings  as
-       hledger  does.   If you have any of these, the conversion postings will
-       be omitted.  Currently we support at most one cost +  conversion  post-
-       ings group per transaction.
-
-   Beancount operating currency
-       Declaring  an  operating  currency  (or several) improves Beancount and
-       Fava reports.  Currently hledger will declare  each  currency  used  in
-       cost  amounts  as an operating currency.  If needed, replace these with
-       your own declaration, like
-
-              option "operating_currency" "USD"
-
-   SQL output
-       SQL output is expected to work at least with SQLite,  MySQL  and  Post-
-       gres.
-
-       The  SQL  statements are expected to be executed in the empty database.
-       If you already have tables created via SQL output of hledger, you would
-       probably want to either clear data from these (via delete  or  truncate
-       SQL  statements) or drop the tables completely before import; otherwise
-       your postings would be duplicated.
-
-       For SQLite, it is more useful if you modify the generated id  field  to
-       be a PRIMARY KEY.  Eg:
-
-              $ hledger print -O sql | sed 's/id serial/id INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL/g' | ...
-
-       This is not yet much used; feedback is welcome.
-
-   JSON output
-       Our  JSON is rather large and verbose, since it is a faithful represen-
-       tation of hledger's internal data types.  To understand its  structure,
-       read    the   Haskell   type   definitions,   which   are   mostly   in
-       https://github.com/simonmichael/hledger/blob/mas-
-       ter/hledger-lib/Hledger/Data/Types.hs.  hledger-web's OpenAPI  specifi-
-       cation may also be relevant.
-
-       hledger  stores  numbers  with  sometimes up to 255 significant digits.
-       This is too many digits for most JSON consumers, so in JSON  output  we
-       round numbers to at most 10 decimal places.  (We don't limit the number
-       of  integer  digits.)  If you find this causing problems, please let us
-       know.  Related: #1195
-
-       This is not yet much used; feedback is welcome.
-
-   Commodity styles
-       When displaying amounts, hledger infers a standard  display  style  for
-       each commodity/currency, as described below in Commodity display style.
-
-       If needed, this can be overridden by a -c/--commodity-style option (ex-
-       cept for cost amounts and amounts displayed by the print command, which
-       are  always  displayed with all decimal digits).  For example, the fol-
-       lowing will force dollar amounts to be displayed as shown:
-
-              $ hledger print -c '$1.000,0'
-
-       This option can repeated to set the display style for multiple commodi-
-       ties/currencies.  Its argument is as described in the commodity  direc-
-       tive.
-
-       In  some  cases  hledger will adjust number formatting to improve their
-       parseability (such as adding trailing decimal marks when needed).
-
-   Debug output
-       We intend hledger to be relatively easy to troubleshoot, introspect and
-       develop.  You can add --debug[=N] to any hledger command  line  to  see
-       additional  debug  output.  N ranges from 1 (least output, the default)
-       to 9 (maximum output).  Typically you would start with 1  and  increase
-       until  you  are seeing enough.  Debug output goes to stderr, and is not
-       affected by -o/--output-file (unless you redirect stderr to stdout, eg:
-       2>&1).  It will be interleaved with normal output, which can  help  re-
-       veal  when parts of the code are evaluated.  To capture debug output in
-       a log file instead, you can usually redirect stderr, eg:
-
-              hledger bal --debug=3 2>hledger.log
-
-       (This option doesn't work in a config file yet.)
-
-Environment
-       These environment variables affect hledger:
-
-       COLUMNS This is normally set by your terminal;  some  hledger  commands
-       (register)  will  format  their output to this width.  If not set, they
-       will try to use the available terminal width.
-
-       HLEDGER_LESS If less is your pager, this variable  specifies  the  less
-       options  hledger  should  use.   (Otherwise,  LESS + custom options are
-       used.)
-
-       LEDGER_FILE The main journal  file  to  use  when  not  specified  with
-       -f/--file.  Default: $HOME/.hledger.journal.
-
-       NO_COLOR If this environment variable exists (with any value, including
-       empty),  hledger  will not use ANSI color codes in terminal output, un-
-       less overridden by an explicit --color=y or --colour=y option.
-
-PART 2: DATA FORMATS
-Journal
-       hledger's usual data source is a plain text file containing journal en-
-       tries in hledger journal format.  If you're looking for a quick  refer-
-       ence,  jump  ahead  to the journal cheatsheet (or use the table of con-
-       tents at https://hledger.org/hledger.html).
-
-       This file represents an accounting General Journal.  The .journal  file
-       extension  is most often used, though not strictly required.  The jour-
-       nal file contains a number of transaction entries,  each  describing  a
-       transfer  of  money  (or  any  commodity) between two or more named ac-
-       counts, in a simple format readable by both hledger and humans.
-
-       hledger's journal format is compatible with most  of  Ledger's  journal
-       format, but not all of it.  The differences and interoperation tips are
-       described  at  hledger and Ledger.  With some care, and by avoiding in-
-       compatible features, you can keep  your  hledger  journal  readable  by
-       Ledger  and vice versa.  This can useful eg for comparing the behaviour
-       of one app against the other.
-
-       You can use hledger without learning any more about this file; just use
-       the add or web or import commands to create and update it.
-
-       Many users, though, edit the journal file with a text editor, and track
-       changes with a version control system such as git.  Editor add-ons such
-       as ledger-mode or hledger-mode  for  Emacs,  vim-ledger  for  Vim,  and
-       hledger-vscode for Visual Studio Code, make this easier, adding colour,
-       formatting, tab completion, and useful commands.  See Editor configura-
-       tion at hledger.org for the full list.
-
-       A hledger journal file can contain three kinds of thing: comment lines,
-       transactions,  and/or  directives (including periodic transaction rules
-       and auto posting rules).  Understanding the journal  file  format  will
-       also  give  you a good understanding of hledger's data model.  Here's a
-       quick cheatsheet/overview, followed by detailed  descriptions  of  each
-       part.
-
-   Journal cheatsheet
-              # Here is the main syntax of hledger's journal format
-              # (omitting extra Ledger compatibility syntax).
-
-              ###############################################################################
-
-              # 1. These are comment lines, for notes or temporarily disabling things.
-              ; They begin with # or ;
-
-              comment
-              Or, lines can be enclosed within "comment" / "end comment".
-              This is a block of
-              commented lines.
-              end comment
-
-              # Some journal entries can have semicolon comments at end of line  ; like this
-              # Some of them require 2 or more spaces before the semicolon.
-
-              ###############################################################################
-
-              # 2. Directives customise processing or output in some way.
-              # You don't need any directives to get started.
-              # But they can add more error checking, or change how things are displayed.
-              # They begin with a word, letter, or symbol.
-              # They are most often placed at the top, before transactions.
-
-              account assets             ; Declare valid account names and display order.
-              account assets:savings     ; A subaccount. This one represents a bank account.
-              account assets:checking    ; Another. Note, 2+ spaces after the account name.
-              account assets:receivable  ; Accounting type is inferred from english names,
-              account passifs            ; or declared with a "type" tag, type:L
-              account expenses           ; type:X
-                                         ; A follow-on comment line, indented.
-              account expenses:rent      ; Expense and revenue categories are also accounts.
-                                         ; Subaccounts inherit their parent's type.
-
-              commodity $0.00         ; Declare valid commodities and their display styles.
-              commodity 1.000,00 EUR
-
-              decimal-mark .          ; The decimal mark used in this file (if ambiguous).
-
-              payee Whole Foods       ; Declare a valid payee name.
-
-              tag trip                ; Declare a valid tag name.
-
-              P 2024-03-01 AAPL $179  ; Declare a market price for AAPL in $ on this date.
-
-              include other.journal   ; Include another journal file here.
-
-              # Declare a recurring "periodic transaction", for budget/forecast reports
-              ~ monthly  set budget goals  ; <- Note, 2+ spaces before the description.
-                  (expenses:rent)      $1000
-                  (expenses:food)       $500
-
-              # Declare an auto posting rule, to modify existing transactions in reports
-              = revenues:consulting
-                  liabilities:tax:2024:us          *0.25  ; Add a tax liability & expense
-                  expenses:tax:2024:us            *-0.25  ; for 25% of the revenue.
-
-              ###############################################################################
-
-              # 3. Transactions are what it's all about.
-              # They are dated events, usually movements of money between 2 or more accounts.
-              # They begin with a numeric date.
-              # Here is their basic shape:
-              #
-              # DATE DESCRIPTION    ; The transaction's date and optional description.
-              #   ACCOUNT1  AMOUNT  ; A posting of an amount to/from this account, indented.
-              #   ACCOUNT2  AMOUNT  ; A second posting, balancing the first.
-              #   ...               ; More if needed. Amounts must sum to zero.
-              #                     ; Note, 2+ spaces between account names and amounts.
-
-              2024-01-01 opening balances         ; At the start, declare pre-existing balances this way.
-                  assets:savings          $10000  ; Account names can be anything. lower case is easy to type.
-                  assets:checking          $1000  ; assets, liabilities, equity, revenues, expenses are common.
-                  liabilities:credit card  $-500  ; liabilities, equity, revenues balances are usually negative.
-                  equity:start                    ; One amount can be left blank. $-10500 is inferred here.
-                                                  ; Some of these accounts we didn't declare above,
-                                                  ; so -s/--strict would complain.
-
-              2024-01-03 ! (12345) pay rent
-                  ; Additional transaction comment lines, indented.
-                  ; There can be a ! or * after the date meaning "pending" or "cleared".
-                  ; There can be a parenthesised (code) after the date/status.
-                                                  ; Amounts' sign shows direction of flow.
-                  assets:checking          $-500  ; Minus means removed from this account (credit).
-                  expenses:rent             $500  ; Plus means added to this account (debit).
-
-              ; Keeping transactions in date order is optional (but helps error checking).
-
-              2024-01-02 Gringott's Bank | withdrawal  ; Description can be PAYEE | NOTE
-                  assets:bank:gold       -10 gold
-                  assets:pouch            10 gold
-
-              2024-01-02 shopping
-                  expenses:clothing        1 gold
-                  expenses:wands           5 gold
-                  assets:pouch            -6 gold
-
-              2024-01-02 receive gift
-                  revenues:gifts          -3 "Chocolate Frogs"  ; Complex commodity symbols
-                  assets:pouch             3 "Chocolate Frogs"  ; must be in double quotes.
-
-              2024-01-15 buy some shares, in two lots                 ; Cost can be noted.
-                  assets:investments:2024-01-15     2.0 AAAA @ $1.50  ; @  means per-unit cost
-                  assets:investments:2024-01-15-02  3.0 AAAA @@ $4    ; @@ means total cost
-                                    ; ^ Per-lot subaccounts are sometimes useful.
-                  assets:checking                 $-7
-
-              2024-01-15 assert some account balances on this date
-                  ; Balances can be asserted in any transaction, with =, for extra error checking.
-                  ; Assertion txns like this one can be made with hledger close --assert --show-costs
-                  ;
-                  assets:savings                    $0                   = $10000
-                  assets:checking                   $0                   =   $493
-                  assets:bank:gold                   0 gold              =    -10 gold
-                  assets:pouch                       0 gold              =      4 gold
-                  assets:pouch                       0 "Chocolate Frogs" =      3 "Chocolate Frogs"
-                  assets:investments:2024-01-15      0.0 AAAA            =      2.0 AAAA @  $1.50
-                  assets:investments:2024-01-15-02   0.0 AAAA            =      3.0 AAAA @@ $4
-                  liabilities:credit card           $0                   =  $-500
-
-              2024-02-01 note some event, or a transaction not yet fully entered, on this date
-                  ; Postings are not required.
-
-              ; Some other date formats are allowed (but, consistent YYYY-MM-DD is useful).
-              2024.01.01
-              2024/1/1
-
-   Comments
-       Lines in the journal will be ignored if they begin with a hash (#) or a
-       semicolon  (;).  (See also Other syntax.)  hledger will also ignore re-
-       gions beginning with a comment line and ending with an end comment line
-       (or file end).  Here's a suggestion for choosing between them:
-
-       o # for top-level notes
-
-       o ; for commenting out things temporarily
-
-       o comment for quickly commenting large regions (remember it's there, or
-         you might get confused)
-
-       Eg:
-
-              # a comment line
-              ; another commentline
-              comment
-              A multi-line comment block,
-              continuing until "end comment" directive
-              or the end of the current file.
-              end comment
-
-       Some hledger entries can have same-line comments attached to them, from
-       ; (semicolon) to end of line.  See Transaction comments,  Posting  com-
-       ments, and Account comments below.
-
-   Transactions
-       Transactions  are the main unit of information in a journal file.  They
-       represent events, typically a movement of some quantity of  commodities
-       between two or more named accounts.
-
-       Each  transaction is recorded as a journal entry, beginning with a sim-
-       ple date in column 0.  This can be followed by any of the following op-
-       tional fields, separated by spaces:
-
-       o a status character (empty, !, or *)
-
-       o a code (any short number or text, enclosed in parentheses)
-
-       o a description (any remaining text until end of line or a semicolon)
-
-       o a comment (any remaining text following  a  semicolon  until  end  of
-         line, and any following indented lines beginning with a semicolon)
-
-       o 0 or more indented posting lines, describing what was transferred and
-         the  accounts  involved (indented comment lines are also allowed, but
-         not blank lines or non-indented lines).
-
-       Here's a simple journal file containing one transaction:
-
-              2008/01/01 income
-                assets:bank:checking   $1
-                income:salary         $-1
-
-   Dates
-   Simple dates
-       Dates in the journal  file  use  simple  dates  format:  YYYY-MM-DD  or
-       YYYY/MM/DD or YYYY.MM.DD, with leading zeros optional.  The year may be
-       omitted,  in  which case it will be inferred from the context: the cur-
-       rent transaction, the default year set with a Y directive, or the  cur-
-       rent  date  when  the  command  is  run.   Some  examples:  2010-01-31,
-       2010/01/31, 2010.1.31, 1/31.
-
-       (The UI also accepts simple dates, as well as the more  flexible  smart
-       dates documented in the hledger manual.)
-
-   Posting dates
-       You  can  give  individual  postings a different date from their parent
-       transaction, by adding a posting comment containing a tag  (see  below)
-       like date:DATE.  This is probably the best way to control posting dates
-       precisely.   Eg  in  this  example the expense should appear in May re-
-       ports, and the deduction from checking should be reported  on  6/1  for
-       easy bank reconciliation:
-
-              2015/5/30
-                  expenses:food     $10  ; food purchased on saturday 5/30
-                  assets:checking        ; bank cleared it on monday, date:6/1
-
-              $ hledger -f t.j register food
-              2015-05-30                      expenses:food                  $10           $10
-
-              $ hledger -f t.j register checking
-              2015-06-01                      assets:checking               $-10          $-10
-
-       DATE  should be a simple date; if the year is not specified it will use
-       the year of the transaction's date.
-       The date: tag must have a valid simple date value if it is present,  eg
-       a date: tag with no value is not allowed.
-
-   Status
-       Transactions  (or  individual postings within a transaction) can have a
-       status mark, which is a single character  before  the  transaction  de-
-       scription  (or posting account name), separated from it by a space, in-
-       dicating one of three statuses:
-
-       mark     status
-       ------------------
-                unmarked
-       !        pending
-       *        cleared
-
-       When reporting, you  can  filter  by  status  with  the  -U/--unmarked,
-       -P/--pending, and -C/--cleared flags (and you can combine these, eg -UP
-       to  match all except cleared things).  Or you can use the status:, sta-
-       tus:!, and status:* queries, or the U, P, C keys in hledger-ui.
-
-       (Note: in Ledger the "unmarked" state is called "uncleared"; in hledger
-       we renamed it to "unmarked" for semantic clarity.)
-
-       Status marks are optional, but can be helpful eg for  reconciling  with
-       real-world accounts.  Some editor modes provide highlighting and short-
-       cuts  for working with status.  Eg in Emacs ledger-mode, you can toggle
-       transaction status with C-c C-e, or posting status with C-c C-c.
-
-       What "uncleared", "pending", and "cleared" actually mean is up to  you.
-       Here's one suggestion:
-
-       status       meaning
-       --------------------------------------------------------------------------
-       uncleared    recorded but not yet reconciled; needs review
-       pending      tentatively reconciled (if needed, eg during a big reconcil-
-                    iation)
-       cleared      complete, reconciled as far as possible, and considered cor-
-                    rect
-
-       With  this scheme, you would use -PC to see the current balance at your
-       bank, -U to see things which will probably hit your bank soon (like un-
-       cashed checks), and no flags to see the most up-to-date state  of  your
-       finances.
-
-   Code
-       After  the  status mark, but before the description, you can optionally
-       write a transaction "code", enclosed in parentheses.  This  is  a  good
-       place  to record a check number, or some other important transaction id
-       or reference number.
-
-   Description
-       After the date, status mark and/or code fields, the rest  of  the  line
-       (or  until a comment is begun with ;) is the transaction's description.
-       Here you can describe the transaction (called the "narration" in tradi-
-       tional bookkeeping), or you can record a payee/payer name, or  you  can
-       leave it empty.
-
-       Transaction  descriptions  show  up in print output and in register re-
-       ports, and can be listed with the descriptions command.
-
-       You can query by description with desc:DESCREGEX, or pivot on  descrip-
-       tion with --pivot desc.
-
-   Payee and note
-       Sometimes people want a dedicated payee/payer field that can be queried
-       and  checked more strictly.  If you want that, you can write a | (pipe)
-       character in the description.  This divides it into a "payee" field  on
-       the left, and a "note" field on the right.  (Either can be empty.)
-
-       You  can  query  these  with  payee:PAYEEREGEX and note:NOTEREGEX, list
-       their values with the payees and notes commands, or pivot on  payee  or
-       note.
-
-       Note: in transactions with no | character, description, payee, and note
-       all have the same value.  Once a | is added, they become distinct.  (If
-       you'd  like  to  change  this  behaviour, please propose it on the mail
-       list.)
-
-       If you want more strict error checking, you can declare the valid payee
-       names with payee directives, and then enforce these with hledger  check
-       payees.   (Note:  because  of the above, for this you'll need to ensure
-       every transaction description contains a | and  therefore  a  checkable
-       payee name, even if it's empty.)
-
-   Transaction comments
-       Text  following  ;, after a transaction description, and/or on indented
-       lines immediately below it, form comments for that  transaction.   They
-       are  reproduced by print but otherwise ignored, except they may contain
-       tags, which are not ignored.
-
-              2012-01-01 something  ; a transaction comment
-                  ; a second line of transaction comment
-                  expenses   1
-                  assets
-
-   Postings
-       A posting is an addition of some amount to, or removal of  some  amount
-       from,  an account.  Each posting line begins with at least one space or
-       tab (2 or 4 spaces is common), followed by:
-
-       o (optional) a status character (empty, !, or *), followed by a space
-
-       o (required) an account name (any text,  optionally  containing  single
-         spaces, until end of line or a double space)
-
-       o (optional) two or more spaces (or tabs) followed by an amount.
-
-       If  the  amount is positive, it is being added to the account; if nega-
-       tive, it is being removed from the account.
-
-       The posting amounts in a transaction must sum up  to  zero,  indicating
-       that  the  inflows  and  outflows  are  equal.  We call this a balanced
-       transaction.  (You can read more about the nitty-gritty details of "sum
-       up to zero" in Transaction balancing below.)
-
-       As a convenience, you can optionally leave one  amount  blank;  hledger
-       will infer what it should be so as to balance the transaction.
-
-   Debits and credits
-       The traditional accounting concepts of debit and credit of course exist
-       in  hledger,  but  we  represent  them  with numeric sign, as described
-       above.  Positive and negative  posting  amounts  represent  debits  and
-       credits respectively.
-
-       You  don't  need  to  remember  that, but if you would like to - eg for
-       helping newcomers or for talking with your accountant - here's a  handy
-       mnemonic:
-
-       debit  / plus  / left  / short  words
-       credit / minus / right / longer words
-
-   The two space delimiter
-       Be  sure  to  notice the unusual separator between the account name and
-       the following amount.  Because hledger allows account names with spaces
-       in them, you must separate the account name and amount (if any) by  two
-       or  more  spaces (or tabs).  It's easy to forget at first.  If you ever
-       see the amount being treated as part of the account name,  you'll  know
-       you probably need to add another space between them.
-
-   Account names
-       Accounts  are  the  main  way of categorising things in hledger.  As in
-       Double Entry Bookkeeping, they can represent real world accounts  (such
-       as a bank account), or more abstract categories such as "money borrowed
-       from Frank" or "money spent on electricity".
-
-       You  can  use any account names you like, but we usually start with the
-       traditional accounting categories, which in english are assets, liabil-
-       ities, equity, revenues, expenses.  (You might see these referred to as
-       A, L, E, R, X for short.)
-
-       For more precise reporting, we usually divide the  top  level  accounts
-       into more detailed subaccounts, by writing a full colon between account
-       name  parts.   For example, from the account names assets:bank:checking
-       and expenses:food, hledger will infer this hierarchy of five accounts:
-
-              assets
-              assets:bank
-              assets:bank:checking
-              expenses
-              expenses:food
-
-       Shown as an outline, the hierarchical tree structure is more clear:
-
-              assets
-               bank
-                checking
-              expenses
-               food
-
-       hledger reports can summarise the account tree to any depth, so you can
-       go as deep as you like with subcategories,  but  keeping  your  account
-       names relatively simple may be best when starting out.
-
-       Account names may be capitalised or not; they may contain letters, num-
-       bers,  symbols,  or  single  spaces.  Note, when an account name and an
-       amount are written on the same line, they must be separated by  two  or
-       more spaces (or tabs).
-
-       Parentheses  or  brackets enclosing the full account name indicate vir-
-       tual postings, described below.  Parentheses or  brackets  internal  to
-       the account name have no special meaning.
-
-       Account  names  can  be  altered  temporarily or permanently by account
-       aliases.
-
-   Amounts
-       After the account name, there is usually an amount.  (Remember: between
-       account name and amount, there must be two or more spaces.)
-
-       hledger's amount format is flexible, supporting  several  international
-       formats.   Here  are  some examples.  Amounts have a number (the "quan-
-       tity"):
-
-              1
-
-       ..and usually a currency symbol or commodity name (more on this below),
-       to the left or right of the quantity,  with  or  without  a  separating
-       space:
-
-              $1
-              4000 AAPL
-              3 "green apples"
-
-       Amounts can be preceded by a minus sign (or a plus sign, though plus is
-       the  default), The sign can be written before or after a left-side com-
-       modity symbol:
-
-              -$1
-              $-1
-
-       One or more spaces between the sign and the number are acceptable  when
-       parsing (but they won't be displayed in output):
-
-              + $1
-              $-      1
-
-       Scientific E notation is allowed:
-
-              1E-6
-              EUR 1E3
-
-   Decimal marks
-       A decimal mark can be written as a period or a comma:
-
-              1.23
-              1,23
-
-       Both of these are common in international number formats, so hledger is
-       not  biased  towards  one  or the other.  Because hledger also supports
-       digit group marks (eg thousands separators), this means that  a  number
-       like  1,000  or 1.000 containing just one period or comma is ambiguous.
-       In such cases, hledger by default assumes it is  a  decimal  mark,  and
-       will parse both of those as 1.
-
-       To  help  hledger  parse such ambiguous numbers more accurately, if you
-       use digit group marks, we recommend declaring the decimal mark  explic-
-       itly.   The  best  way is to add a decimal-mark directive at the top of
-       each data file, like this:
-
-              decimal-mark .
-
-       Or you can declare it per  commodity  with  commodity  directives,  de-
-       scribed below.
-
-       hledger  also accepts numbers like 10. with no digits after the decimal
-       mark (and will sometimes display numbers that way to disambiguate  them
-       - see Trailing decimal marks).
-
-   Digit group marks
-       In  the integer part of the amount quantity (left of the decimal mark),
-       groups of digits can optionally be separated by a digit group mark -  a
-       comma  or  period  (whichever  is not used as decimal mark), or a space
-       (several Unicode space variants, like  no-break  space,  are  also  ac-
-       cepted).   So these are all valid amounts in a journal file:
-
-                   $1,000,000.00
-                EUR 2.000.000,00
-              INR 9,99,99,999.00
-                    1 000 000.00   ; <- ordinary space
-                    1 000 000.00   ; <- no-break space
-
-   Commodity
-       Amounts  in  hledger  have both a "quantity", which is a signed decimal
-       number, and a "commodity", which is a currency symbol, stock ticker, or
-       any word or phrase describing something you are tracking.
-
-       If the commodity name contains non-letters (spaces, numbers, or punctu-
-       ation), you must always write it inside double quotes ("green  apples",
-       "ABC123").
-
-       If  you  write just a bare number, that too will have a commodity, with
-       name ""; we call that the "no-symbol commodity".
-
-       Actually, hledger combines these  single-commodity  amounts  into  more
-       powerful  multi-commodity amounts, which are what it works with most of
-       the time.  A multi-commodity amount could be, eg: 1 USD, 2  EUR,  3.456
-       TSLA.   In  practice,  you  will  only  see  multi-commodity amounts in
-       hledger's output; you can't write them directly in the journal file.
-
-       By default, the format of amounts in the journal influences how hledger
-       displays them in output.  This is explained in Commodity display  style
-       below.
-
-   Costs
-       After  a posting amount, you can note its cost (when buying) or selling
-       price (when selling) in another commodity, by writing  either  @  UNIT-
-       PRICE  or @@ TOTALPRICE after it.  This indicates a conversion transac-
-       tion, where one commodity is exchanged for another.
-
-       (You might also see this called "transaction price"  in  hledger  docs,
-       discussions,  or code; that term was directionally neutral and reminded
-       that it is a price specific to a transaction, but we now just  call  it
-       "cost", with the understanding that the transaction could be a purchase
-       or a sale.)
-
-       Costs  are usually written explicitly with @ or @@, but can also be in-
-       ferred automatically for simple multi-commodity transactions.  Note, if
-       costs are inferred, the order of postings  is  significant;  the  first
-       posting will have a cost attached, in the commodity of the second.
-
-       As  an  example, here are several ways to record purchases of a foreign
-       currency in hledger, using the cost notation either explicitly  or  im-
-       plicitly:
-
-       1. Write the price per unit, as @ UNITPRICE after the amount:
-
-                  2009/1/1
-                    assets:euros     100 @ $1.35  ; one hundred euros purchased at $1.35 each
-                    assets:dollars                 ; balancing amount is -$135.00
-
-       2. Write the total price, as @@ TOTALPRICE after the amount:
-
-                  2009/1/1
-                    assets:euros     100 @@ $135  ; one hundred euros purchased at $135 for the lot
-                    assets:dollars
-
-       3. Specify amounts for all postings, using exactly two commodities, and
-          let hledger infer the price that balances the transaction.  Note the
-          effect of posting order: the price is added to first posting, making
-          it 100 @@ $135, as in example 2:
-
-                  2009/1/1
-                    assets:euros     100          ; one hundred euros purchased
-                    assets:dollars  $-135          ; for $135
-
-       Amounts  can  be  converted  to cost at report time using the -B/--cost
-       flag; this is discussed more in the Cost reporting section.
-
-       Note that the cost normally should be a positive  amount,  though  it's
-       not  required to be.  This can be a little confusing, see discussion at
-       --infer-market-prices: market prices from transactions.
-
-   Balance assertions
-       hledger supports Ledger-style  balance  assertions  in  journal  files.
-       These  look  like, for example, = EXPECTEDBALANCE following a posting's
-       amount.  Eg here we assert the expected dollar balance  in  accounts  a
-       and b after each posting:
-
-              2013/1/1
-                a   $1 =  $1
-                b      = $-1
-
-              2013/1/2
-                a   $1 =  $2
-                b  $-1 = $-2
-
-       After reading a journal file, hledger will check all balance assertions
-       and  report  an error if any of them fail.  Balance assertions can pro-
-       tect you from, eg, inadvertently disrupting reconciled  balances  while
-       cleaning  up  old  entries.   You can disable them temporarily with the
-       -I/--ignore-assertions flag, which can be useful for troubleshooting or
-       for reading Ledger files.  (Note: this flag currently does not  disable
-       balance assignments, described below).
-
-   Assertions and ordering
-       hledger  calculates  and checks an account's balance assertions in date
-       order (and when there are multiple assertions on the same day, in parse
-       order).  Note this is different from Ledger,  which  checks  assertions
-       always in parse order, ignoring dates.
-
-       This means in hledger you can freely reorder transactions, postings, or
-       files, and balance assertions will usually keep working.  The exception
-       is  when you reorder multiple postings on the same day, to the same ac-
-       count, which have balance assertions; those will likely need updating.
-
-   Assertions and multiple included files
-       Multiple files included with the include directive are processed as  if
-       concatenated  into one file, preserving their order and the posting or-
-       der within each file.  It means that balance assertions in later  files
-       will see balance from earlier files.
-
-       And  if you have multiple postings to an account on the same day, split
-       across multiple files, and you want to assert the account's balance  on
-       that day, you'll need to put the assertion in the right file - the last
-       one in the sequence, probably.
-
-   Assertions and multiple -f files
-       Unlike  include,  when multiple files are specified on the command line
-       with multiple -f/--file options, balance assertions will not  see  bal-
-       ance from earlier files.  This can be useful when you do not want prob-
-       lems in earlier files to disrupt valid assertions in later files.
-
-       If  you  do  want assertions to see balance from earlier files, use in-
-       clude, or concatenate the files temporarily.
-
-   Assertions and costs
-       Balance assertions ignore costs, and should normally be written without
-       one:
-
-              2019/1/1
-                (a)     $1 @ 1 = $1
-
-       We do allow costs to be written in balance assertion amounts,  however,
-       and  print  shows  them,  but  they  don't affect whether the assertion
-       passes or fails.  This is for backward compatibility  (hledger's  close
-       command  used  to  generate balance assertions with costs), and because
-       balance assignments do use costs (see below).
-
-   Assertions and commodities
-       The balance assertions described so far are "single  commodity  balance
-       assertions": they assert and check the balance in one commodity, ignor-
-       ing  any  others  that  may be present.  This is how balance assertions
-       work in Ledger also.
-
-       If an account contains multiple commodities, you can assert their  bal-
-       ances  by  writing  multiple  postings with balance assertions, one for
-       each commodity:
-
-              2013/1/1
-                usd   $-1
-                eur   -1
-                both
-
-              2013/1/2
-                both    0 = $1
-                both    0 = 1
-
-       In hledger you can make a stronger "sole commodity  balance  assertion"
-       by  writing  two  equals signs (== EXPECTEDBALANCE).  This also asserts
-       that there are no other commodities in the account besides the asserted
-       one (or at least, that their current balance is zero):
-
-              2013/1/1
-                usd   $-1  == $-1  ; these sole commodity assertions succeed
-                eur   -1  == -1
-                both      ;==  $1  ; this one would fail because 'both' contains $ and
-
-       It's less easy to make a "sole commodities balance assertion" (note the
-       plural) - ie, asserting that an account contains two or more  specified
-       commodities and no others.  It can be done by
-
-       1. isolating each commodity in a subaccount, and asserting those
-
-       2. and  also  asserting  there are no commodities in the parent account
-          itself:
-
-          2013/1/1
-            usd       $-1
-            eur       -1
-            both        0 == 0   ; nothing up my sleeve
-            both:usd   $1 == $1  ; a dollar here
-            both:eur   1 == 1  ; a euro there
-
-   Assertions and subaccounts
-       All of the balance assertions above (both = and ==) are "subaccount-ex-
-       clusive balance assertions"; they ignore any  balances  that  exist  in
-       deeper subaccounts.
-
-       In  hledger  you  can make "subaccount-inclusive balance assertions" by
-       adding a star after the equals (=* or ==*):
-
-              2019/1/1
-                equity:start
-                assets:checking  $10
-                assets:savings   $10
-                assets            $0 ==* $20  ; assets + subaccounts contains $20 and nothing else
-
-   Assertions and status
-       Balance assertions always consider postings of all statuses  (unmarked,
-       pending,  or  cleared);  they  are  not affected by the -U/--unmarked /
-       -P/--pending / -C/--cleared flags or the status: query.
-
-   Assertions and virtual postings
-       Balance assertions always consider both real and virtual postings; they
-       are not affected by the --real/-R flag or real: query.
-
-   Assertions and auto postings
-       Balance assertions are affected by the  --auto  flag,  which  generates
-       auto postings, which can alter account balances.  Because auto postings
-       are optional in hledger, accounts affected by them effectively have two
-       balances.   But  balance  assertions  can only test one or the other of
-       these.  So to avoid making fragile assertions, either:
-
-       o assert the balance calculated with --auto, and always use --auto with
-         that file
-
-       o or assert the balance calculated without --auto, and never use --auto
-         with that file
-
-       o or avoid balance assertions on accounts affected by auto postings (or
-         avoid auto postings entirely).
-
-   Assertions and precision
-       Balance assertions compare the exactly calculated  amounts,  which  are
-       not  always  what  is  shown  by reports.  Eg a commodity directive may
-       limit the display precision, but this will not  affect  balance  asser-
-       tions.  Balance assertion failure messages show exact amounts.
-
-   Posting comments
-       Text  following  ;,  at  the  end of a posting line, and/or on indented
-       lines immediately below it, form comments for that posting.   They  are
-       reproduced  by  print  but  otherwise  ignored, except they may contain
-       tags, which are not ignored.
-
-              2012-01-01
-                  expenses   1  ; a comment for posting 1
-                  assets
-                  ; a comment for posting 2
-                  ; a second comment line for posting 2
-
-   Transaction balancing
-       How exactly does hledger decide when a transaction is balanced  ?   The
-       general goal is that if you look at the journal entry and calculate the
-       amounts' sum perfectly with pencil and paper, hledger should agree with
-       you.
-
-       Real  world  transactions,  especially for investments or cryptocurren-
-       cies, often involve imprecise costs,  complex  decimals,  and/or  infi-
-       nitely-recurring  decimals, which are difficult or inconvenient to han-
-       dle on a computer.  So to be a practical accounting system, hledger al-
-       lows some imprecision  when  checking  transaction  balancedness.   The
-       question is, how much imprecision should be allowed ?
-
-       hledger  currently decides it based on the commodity display styles: if
-       the postings' sum would appear to be zero when displayed with the stan-
-       dard display precisions, the transaction is considered balanced.
-
-       Or equivalently: if the journal entry is displayed with amounts rounded
-       to the standard display precisions (with hledger  print  --round=hard),
-       and  a  human  with  pencil  and paper would agree that those displayed
-       amounts add up to zero, the transaction is considered balanced.
-
-       This  has  some  advantages:  it  is  fairly  intuitive,  general   not
-       hard-coded,  yet  configurable  when  needed.  On the downside it means
-       that transaction balancedness is related to  commodity  display  preci-
-       sions,  so  eg  when  using -c/--commodity-style to display things with
-       more than usual precision, you might need to fix some of  your  journal
-       entries (ie, add decimal digits to make them balance more precisely).
-
-       Other PTA tools (Ledger, Beancount..)  have their own ways of doing it.
-       Possible improvements are discussed at #1964.
-
-       Note:  if you have multiple journal files, and are relying on commodity
-       directives to make imprecise journal entries balance,  the  directives'
-       placement might be important - see commodity directive.
-
-   Tags
-       Tags  are  a  way  to  add extra labels or data fields to transactions,
-       postings, or accounts.  They are usually a word or hyphenated word, im-
-       mediately followed by a full colon, written within  the  comment  of  a
-       transaction, a posting, or an account directive.  (Yes, storing data in
-       comments is slightly weird!)
-
-       You can write each tag on its own comment line, or multiple tags on one
-       line,  separated  by  commas.  Tags can also have a value, which is any
-       text after the colon until the next comma or  end  of  line,  excluding
-       surrounding whitespace.  (hledger tag values can't contain commas.)  If
-       the  same tag name appears multiple times in a comment, each name:value
-       pair is preserved.
-
-       An example: in this journal there are six tags,  one  of  them  with  a
-       value:
-
-              account assets:checking         ; accounttag:
-              account expenses:food
-
-              2017/1/16 bought groceries      ; transactiontag:
-                  ; transactiontag2:
-                  assets:checking        $-1
-                   ; posting-tag-1:, (belongs to the posting above)
-                  expenses:food           $1  ; posting-tag-2:, posting-tag-3: with a value
-
-   Querying with tags
-       Tags  are  most  often  used  to select a subset of data; you can match
-       tagged things by tag name and or tag value with  a  tag:  query.   (See
-       queries below.)
-
-       When  querying for tag names or values, note that postings inherit tags
-       from their transaction and from their account, and transactions acquire
-       tags from their postings.  So in the example above, - the assets:check-
-       ing posting effectively has four tags (one of its own, one from the ac-
-       count, two from the transaction) -  the  expenses:food  posting  effec-
-       tively  has  four tags (two of its own, two from the transaction) - the
-       transaction effectively has all six tags (two of its own, and two  from
-       each posting)
-
-   Displaying tags
-       You can use the tags command to list tag names or values.
-
-       The print command also shows tags.
-
-       You  can use --pivot to display tag values in other reports, in various
-       ways (eg appended to account names, like pseudo subaccounts).
-
-   When to use tags ?
-       Tags provide more dimensions of categorisation, complementing  accounts
-       and  transaction descriptions.  When to use each of these is somewhat a
-       matter of taste.  Accounts have the most built-in  support,  and  regex
-       queries  on  descriptions are also quite powerful.  So you may not need
-       tags at all.  But if you want to  track  multiple  cross-cutting  cate-
-       gories,  they  can  be a good fit.  For example, you could tag trip-re-
-       lated transactions with trip: YEAR:PLACE, without disturbing your usual
-       account categories.
-
-   Tag names
-       What is allowed in a tag name ?  Currently, most non-whitespace charac-
-       ters.  Eg : is a valid tag.
-
-       For extra error checking, you can declare valid tag names with the  tag
-       directive, and then enforce these with the check command.
-
-       But  note  that  tags  are detected quite loosely at present, sometimes
-       where you didn't intend them.  Eg  ;  see  https://foo.com  contains  a
-       https tag with value //foo.com.
-
-   Special tags
-       Some  tag  names  have  special  significance to hledger.  They are ex-
-       plained elsewhere, but here's a quick reference:
-
-               type                   -- declares an account's type
-               date                   -- overrides a posting's date
-               date2                  -- overrides a posting's secondary date
-               assert                 -- appears on txns generated by close --assert
-               retain                 -- appears on txns generated by close --retain
-               start                  -- appears on txns generated by close --migrate/--close/--open/--assign
-               t                      -- appears on postings generated from timedot letters
-
-               generated-transaction  -- appears on txns generated by a periodic rule
-               modified-transaction   -- appears on txns which have had auto postings added
-               generated-posting      -- appears on generated postings
-               cost-posting           -- appears on postings which have (or could have) a cost,
-                                         and which have equivalent conversion postings in the transaction
-               conversion-posting     -- appears on postings which are to a V/Conversion account
-                                         and which have an equivalent cost posting in the transaction
-
-       The second group above (generated-transaction, etc.)  are normally hid-
-       den, with a _ prefix added.  This means print doesn't show them by  de-
-       fault;  but  you can still use them in queries.  You can add the --ver-
-       bose-tags flag to make them visible, which  can  be  useful  for  trou-
-       bleshooting.
-
-   Directives
-       Besides  transactions, there is something else you can put in a journal
-       file: directives.  These are declarations, beginning  with  a  keyword,
-       that  modify  hledger's  behaviour.  Some directives can have more spe-
-       cific subdirectives, indented below  them.   hledger's  directives  are
-       similar to Ledger's in many cases, but there are also many differences.
-       Directives  are not required, but can be useful.  Here are the main di-
-       rectives:
-
-       purpose                                    directive
-       --------------------------------------------------------------------------
-       READING DATA:
-       Rewrite account names                      alias
-       Comment out sections of the file           comment
-       Declare file's  decimal  mark,  to  help   decimal-mark
-       parse amounts accurately
-       Include other data files                   include
-       GENERATING DATA:
-       Generate  recurring transactions or bud-   ~
-       get goals
-       Generate  extra  postings  on   existing   =
-       transactions
-       CHECKING FOR ERRORS:
-       Define  valid  entities  to provide more   account, commodity, payee, tag
-       error checking
-       REPORTING:
-       Declare accounts' type and display order   account
-       Declare commodity display styles           commodity
-       Declare market prices                      P
-
-   Directives and multiple files
-       Directives vary in their scope, ie which journal entries and which  in-
-       put files they affect.  Most often, a directive will affect the follow-
-       ing  entries  and  included  files if any, until the end of the current
-       file - and no further.  You might find this inconvenient!  For example,
-       alias directives do not affect parent or sibling files.  But there  are
-       usually workarounds; for example, put alias directives in your top-most
-       file, before including other files.
-
-       The  restriction,  though  it  may  be  annoying at first, is in a good
-       cause; it allows reports to be stable and deterministic, independent of
-       the order of input.  Without it, reports could show  different  numbers
-       depending  on  the order of -f options, or the positions of include di-
-       rectives in your files.
-
-   Directive effects
-       Here are all hledger's directives, with their effects  and  scope  sum-
-       marised  -  nine  main  directives,  plus four others which we consider
-       non-essential:
-
-       di-        what it does                                                       ends
-       rec-                                                                          at
-       tive                                                                          file
-                                                                                     end?
-       --------------------------------------------------------------------------------------
-       ac-        Declares an account, for checking all entries in all files;  and   N
-       count      its display order and type.  Subdirectives: any text, ignored.
-       alias      Rewrites  account  names, in following entries until end of cur-   Y
-                  rent file or end aliases.  Command line equivalent: --alias
-       com-       Ignores part of the journal file, until end of current  file  or   Y
-       ment       end comment.
-       com-       Declares up to four things: 1.  a commodity symbol, for checking   N,N,Y,Y
-       mod-       all  amounts  in all files 2.  the display style for all amounts
-       ity        of this commodity 3.  the decimal mark for  parsing  amounts  of
-                  this  commodity,  in  the rest of this file and its children, if
-                  there is no decimal-mark directive 4.  the precision to use  for
-                  balanced-transaction  checking  in  this commodity, in this file
-                  and its children.   Takes  precedence  over  D.   Subdirectives:
-                  format (ignored).  Command line equivalent: -c/--commodity-style
-       deci-      Declares  the  decimal mark, for parsing amounts of all commodi-   Y
-       mal-mark   ties in following entries until next decimal-mark or end of cur-
-                  rent file.  Included files can override.  Takes precedence  over
-                  commodity and D.
-       include    Includes  entries  and  directives from another file, as if they   N
-                  were  written  inline.   Command  line   alternative:   multiple
-                  -f/--file
-       payee      Declares a payee name, for checking all entries in all files.      N
-       P          Declares the market price of a commodity on some date, for value   N
-                  reports.
-       ~          Declares  a  periodic  transaction  rule  that  generates future   N
-       (tilde)    transactions with  --forecast  and  budget  goals  with  balance
-                  --budget.
-       Other
-       syntax:
-       apply      Prepends  a  common parent account to all account names, in fol-   Y
-       account    lowing entries until end of current file or end apply account.
-       D          Sets a default commodity to use for  no-symbol  amounts;and,  if   Y,Y,N,N
-                  there  is no commodity directive for this commodity: its decimal
-                  mark, balancing precision, and display style, as above.
-       Y          Sets a default year to use for any yearless dates, in  following   Y
-                  entries until end of current file.
-       =          Declares  an  auto posting rule that generates extra postings on   partly
-       (equals)   matched transactions with --auto, in current, parent, and  child
-                  files (but not sibling files, see #1212).
-       Other      Other  directives from Ledger's file format are accepted but ig-
-       Ledger     nored.
-       direc-
-       tives
-
-   account directive
-       account directives can be used to declare accounts (ie, the places that
-       amounts are transferred from and to).  Though not required, these  dec-
-       larations can provide several benefits:
-
-       o They can document your intended chart of accounts, providing a refer-
-         ence.
-
-       o They can store additional account information as comments, or as tags
-         which can be used to filter or pivot reports.
-
-       o They can restrict which accounts may be posted to by transactions, eg
-         in strict mode, which helps prevent errors.
-
-       o They  influence account display order in reports, allowing non-alpha-
-         betic sorting (eg Revenues to appear above Expenses).
-
-       o They can help hledger know your accounts'  types  (asset,  liability,
-         equity, revenue, expense), enabling reports like balancesheet and in-
-         comestatement.
-
-       o They  help with account name completion (in hledger add, hledger-web,
-         hledger-iadd, ledger-mode, etc.)
-
-       They are written as the word account followed by  a  hledger-style  ac-
-       count name.  Eg:
-
-              account assets:bank:checking
-
-       Ledger-style indented subdirectives are also accepted, but ignored:
-
-              account assets:bank:checking
-                format subdirective  ; currently ignored
-
-   Account comments
-       Text following two or more spaces and ; at the end of an account direc-
-       tive  line,  and/or following ; on indented lines immediately below it,
-       form comments for that account.  They are ignored except they may  con-
-       tain tags, which are not ignored.
-
-       The  two-space  requirement for same-line account comments is because ;
-       is allowed in account names.
-
-              account assets:bank:checking    ; same-line comment, at least 2 spaces before the semicolon
-                ; next-line comment
-                ; some tags - type:A, acctnum:12345
-
-   Account error checking
-       By default, accounts need not be declared;  they  come  into  existence
-       when  a  posting  references  them.   This  is convenient, but it means
-       hledger can't warn you when you mis-spell an account name in the  jour-
-       nal.  Usually you'll find that error later, as an extra account in bal-
-       ance reports, or an incorrect balance when reconciling.
-
-       In  strict  mode,  enabled  with  the -s/--strict flag, or when you run
-       hledger check accounts, hledger will report an error if any transaction
-       uses an account name that has not been declared by  an  account  direc-
-       tive.  Some notes:
-
-       o The  declaration is case-sensitive; transactions must use the correct
-         account name capitalisation.
-
-       o The account directive's scope is "whole file and below"  (see  direc-
-         tives).  This means it affects all of the current file, and any files
-         it  includes,  but  not parent or sibling files.  The position of ac-
-         count directives within the file does not matter, though  it's  usual
-         to put them at the top.
-
-       o Accounts  can  only be declared in journal files, but will affect in-
-         cluded files of all types.
-
-       o It's currently not possible to  declare  "all  possible  subaccounts"
-         with a wildcard; every account posted to must be declared.
-
-       o If  you  use the --infer-equity flag, you will also need declarations
-         for the account names it generates.
-
-   Account display order
-       Account directives also cause hledger to display accounts in a particu-
-       lar order, not just alphabetically.  Eg, here is a conventional  order-
-       ing for the top-level accounts:
-
-              account assets
-              account liabilities
-              account equity
-              account revenues
-              account expenses
-
-       Now hledger displays them in that order:
-
-              $ hledger accounts
-              assets
-              liabilities
-              equity
-              revenues
-              expenses
-
-       If  there are undeclared accounts, those will be displayed last, in al-
-       phabetical order.
-
-       Sorting is done within each group of sibling accounts, at each level of
-       the account tree.  Eg, a declaration like account  parent:child  influ-
-       ences child's position among its siblings.
-
-       Note,  it  does not affect parent's position; for that, you need an ac-
-       count parent declaration.
-
-       Sibling accounts are always displayed together; hledger  won't  display
-       x:y in between a:b and a:c.
-
-       An  account  directive both declares an account as a valid posting tar-
-       get, and declares its display order; you can't easily  do  one  without
-       the other.
-
-   Account types
-       hledger knows that accounts come in several types: assets, liabilities,
-       expenses  and  so  on.  This enables easy reports like balancesheet and
-       incomestatement, and filtering by account type with the type: query.
-
-       As a convenience, hledger will detect these account types automatically
-       if you are using common english-language top-level account  names  (de-
-       scribed  below).   But  it's more robust to declare accounts' types ex-
-       plicitly, by adding type: tags to their account directives.  The  tag's
-       value should be one of the five main account types:
-
-       o A or Asset (things you own)
-
-       o L or Liability (things you owe)
-
-       o E  or  Equity (investment/ownership; balanced counterpart of assets &
-         liabilities)
-
-       o R or Revenue (what you received money from, AKA  income;  technically
-         part of Equity)
-
-       o X or Expense (what you spend money on; technically part of Equity)
-
-       or, it can be (these are used less often):
-
-       o C or Cash (a subtype of Asset, indicating liquid assets for the cash-
-         flow report)
-
-       o V  or  Conversion (a subtype of Equity, for conversions (see Cost re-
-         porting).)
-
-       Subaccounts inherit their parent's type, or they can override it.  Here
-       is a typical set of account type declarations:
-
-              account assets             ; type: A
-              account liabilities        ; type: L
-              account equity             ; type: E
-              account revenues           ; type: R
-              account expenses           ; type: X
-
-              account assets:bank        ; type: C
-              account assets:cash        ; type: C
-
-              account equity:conversion  ; type: V
-
-       Here are some tips for working with account types.
-
-       o The rules for inferring types from  account  names  are  as  follows.
-         These are just a convenience that sometimes help new users get going;
-         if they don't work for you, just ignore them and declare your account
-         types.  See also Regular expressions.
-
-                If account's name contains this (CI) regular expression:            | its type is:
-                --------------------------------------------------------------------|-------------
-                ^assets?(:.+)?:(cash|bank|che(ck|que?)(ing)?|savings?|current)(:|$) | Cash
-                ^assets?(:|$)                                                       | Asset
-                ^(debts?|liabilit(y|ies))(:|$)                                      | Liability
-                ^equity:(trad(e|ing)|conversion)s?(:|$)                             | Conversion
-                ^equity(:|$)                                                        | Equity
-                ^(income|revenue)s?(:|$)                                            | Revenue
-                ^expenses?(:|$)                                                     | Expense
-
-       o If  you declare any account types, it's a good idea to declare an ac-
-         count for all of the account types, because a mixture of declared and
-         name-inferred types can disrupt certain reports.
-
-       o Certain uses of account  aliases  can  disrupt  account  types.   See
-         Rewriting accounts > Aliases and account types.
-
-       o As mentioned above, subaccounts will inherit a type from their parent
-         account.   More  precisely, an account's type is decided by the first
-         of these that exists:
-
-         1. A type: declaration for this account.
-
-         2. A type: declaration in the parent accounts  above  it,  preferring
-            the nearest.
-
-         3. An account type inferred from this account's name.
-
-         4. An  account type inferred from a parent account's name, preferring
-            the nearest parent.
-
-         5. Otherwise, it will have no type.
-
-       o For troubleshooting, you can list accounts and their types with:
-
-                $ hledger accounts --types [ACCTPAT] [-DEPTH] [type:TYPECODES]
-
-   alias directive
-       You can define account alias rules which rewrite your account names, or
-       parts of them, before generating reports.  This can be useful for:
-
-       o expanding shorthand account names to their full form, allowing easier
-         data entry and a less verbose journal
-
-       o adapting old journals to your current chart of accounts
-
-       o experimenting with new account organisations, like a new hierarchy
-
-       o combining two accounts into one, eg to see their sum or difference on
-         one line
-
-       o customising reports
-
-       Account aliases also rewrite account names in account directives.  They
-       do  not  affect  account  names  being  entered  via  hledger  add   or
-       hledger-web.
-
-       Account aliases are very powerful.  They are generally easy to use cor-
-       rectly, but you can also generate invalid account names with them; more
-       on this below.
-
-       See also Rewrite account names.
-
-   Basic aliases
-       To  set an account alias, use the alias directive in your journal file.
-       This affects all subsequent journal entries in the current file or  its
-       included  files  (but  note:  not sibling or parent files).  The spaces
-       around the = are optional:
-
-              alias OLD = NEW
-
-       Or, you can use the --alias 'OLD=NEW' option on the command line.  This
-       affects all entries.  It's useful for trying out aliases interactively.
-
-       OLD and NEW are case sensitive full account names.   hledger  will  re-
-       place  any occurrence of the old account name with the new one.  Subac-
-       counts are also affected.  Eg:
-
-              alias checking = assets:bank:wells fargo:checking
-              ; rewrites "checking" to "assets:bank:wells fargo:checking", or "checking:a" to "assets:bank:wells fargo:checking:a"
-
-   Regex aliases
-       There is also a more powerful variant that uses a  regular  expression,
-       indicated  by  wrapping  the  pattern in forward slashes.  (This is the
-       only place where hledger requires forward slashes around a regular  ex-
-       pression.)
-
-       Eg:
-
-              alias /REGEX/ = REPLACEMENT
-
-       or:
-
-              $ hledger --alias '/REGEX/=REPLACEMENT' ...
-
-       Any  part  of  an account name matched by REGEX will be replaced by RE-
-       PLACEMENT.  REGEX is case-insensitive as usual.
-
-       If you need to match a forward slash, escape it with  a  backslash,  eg
-       /\/=:.
-
-       If  REGEX  contains parenthesised match groups, these can be referenced
-       by the usual backslash and number in REPLACEMENT:
-
-              alias /^(.+):bank:([^:]+):(.*)/ = \1:\2 \3
-              ; rewrites "assets:bank:wells fargo:checking" to  "assets:wells fargo checking"
-
-       REPLACEMENT continues to the end of line (or on command line, to end of
-       option argument), so it can contain trailing whitespace.
-
-   Combining aliases
-       You can define as many aliases as you like,  using  journal  directives
-       and/or command line options.
-
-       Recursive  aliases  -  where an account name is rewritten by one alias,
-       then by another alias, and so on - are allowed.  Each  alias  sees  the
-       effect of previously applied aliases.
-
-       In  such  cases it can be important to understand which aliases will be
-       applied and in which order.  For (each account name  in)  each  journal
-       entry, we apply:
-
-       1. alias  directives  preceding the journal entry, most recently parsed
-          first (ie, reading upward from the journal entry, bottom to top)
-
-       2. --alias options, in the order they  appeared  on  the  command  line
-          (left to right).
-
-       In other words, for (an account name in) a given journal entry:
-
-       o the nearest alias declaration before/above the entry is applied first
-
-       o the next alias before/above that will be be applied next, and so on
-
-       o aliases defined after/below the entry do not affect it.
-
-       This  gives nearby aliases precedence over distant ones, and helps pro-
-       vide semantic stability - aliases will keep working the same way  inde-
-       pendent of which files are being read and in which order.
-
-       In  case  of  trouble,  adding  --debug=6 to the command line will show
-       which aliases are being applied when.
-
-   Aliases and multiple files
-       As explained at Directives and multiple files, alias directives do  not
-       affect parent or sibling files.  Eg in this command,
-
-              hledger -f a.aliases -f b.journal
-
-       account  aliases  defined  in a.aliases will not affect b.journal.  In-
-       cluding the aliases doesn't work either:
-
-              include a.aliases
-
-              2023-01-01  ; not affected by a.aliases
-                foo  1
-                bar
-
-       This means that account aliases should usually be declared at the start
-       of your top-most file, like this:
-
-              alias foo=Foo
-              alias bar=Bar
-
-              2023-01-01  ; affected by aliases above
-                foo  1
-                bar
-
-              include c.journal  ; also affected
-
-   end aliases directive
-       You can clear (forget) all currently defined aliases (seen in the jour-
-       nal so far, or defined on the command line) with this directive:
-
-              end aliases
-
-   Aliases can generate bad account names
-       Be aware that account aliases  can  produce  malformed  account  names,
-       which could cause confusing reports or invalid print output.  For exam-
-       ple, you could erase all account names:
-
-              2021-01-01
-                a:aa     1
-                b
-
-              $ hledger print --alias '/.*/='
-              2021-01-01
-                                 1
-
-       The  above print output is not a valid journal.  Or you could insert an
-       illegal double space, causing print output that would give a  different
-       journal when reparsed:
-
-              2021-01-01
-                old    1
-                other
-
-              $ hledger print --alias old="new  USD" | hledger -f- print
-              2021-01-01
-                  new             USD 1
-                  other
-
-   Aliases and account types
-       If an account with a type declaration (see Declaring accounts > Account
-       types) is renamed by an alias, normally the account type remains in ef-
-       fect.
-
-       However,  renaming in a way that reshapes the account tree (eg renaming
-       parent accounts but not their children, or vice  versa)  could  prevent
-       child accounts from inheriting the account type of their parents.
-
-       Secondly,  if an account's type is being inferred from its name, renam-
-       ing it by an alias could prevent or alter that.
-
-       If you are using account aliases and the type: query  is  not  matching
-       accounts  as you expect, try troubleshooting with the accounts command,
-       eg something like:
-
-              $ hledger accounts --alias assets=bassetts type:a
-
-   commodity directive
-       The commodity directive performs several functions:
-
-       1. It declares which commodity symbols may be used in the journal,  en-
-          abling  useful error checking with strict mode or the check command.
-          See Commodity error checking below.
-
-       2. It declares how all amounts in this commodity should  be  displayed,
-          eg how many decimals to show.  See Commodity display style above.
-
-       3. (If  no  decimal-mark  directive  is in effect:) It sets the decimal
-          mark to expect (period or comma) when parsing amounts in  this  com-
-          modity, in this file and files it includes, from the directive until
-          end of current file.  See Decimal marks above.
-
-       4. It declares the precision with which this commodity's amounts should
-          be  compared  when  checking  for balanced transactions, anywhere in
-          this file and files it includes, until end of current file.
-
-       Declaring commodities solves several common  parsing/display  problems,
-       so we recommend it.
-
-       Note that effects 3 and 4 above end at the end of the directive's file,
-       and  will not affect sibling or parent files.  So if you are relying on
-       them (especially 4) and using multiple files,  placing  your  commodity
-       directives  in  a  top-level  parent file might be important.  Or, keep
-       your decimal marks unambiguous and your entries well balanced and  pre-
-       cise.
-
-       (Related: #793)
-
-   Commodity directive syntax
-       A commodity directive is normally the word commodity followed by a sam-
-       ple  amount  (and  optionally a comment).  Only the amount's symbol and
-       format is significant.  Eg:
-
-              commodity $1000.00
-              commodity 1.000,00 EUR
-              commodity 1 000 000.0000   ; the no-symbol commodity
-
-       Commodities do not have tags (tags in the comment will be ignored).
-
-       A commodity directive's sample amount must always include a  period  or
-       comma  decimal  mark  (this  rule  helps disambiguate decimal marks and
-       digit group marks).  If you don't want  to  show  any  decimal  digits,
-       write the decimal mark at the end:
-
-              commodity 1000. AAAA       ; show AAAA with no decimals
-
-       Commodity  symbols  containing  spaces, numbers, or punctuation must be
-       enclosed in double quotes, as usual:
-
-              commodity 1.0000 "AAAA 2023"
-
-       Commodity directives normally include a sample amount, but can  declare
-       only a symbol (ie, just function 1 above):
-
-              commodity $
-              commodity INR
-              commodity "AAAA 2023"
-              commodity ""               ; the no-symbol commodity
-
-       Commodity directives may also be written with an indented format subdi-
-       rective,  as in Ledger.  The symbol is repeated and must be the same in
-       both places.  Other subdirectives are currently ignored:
-
-              ; display indian rupees with currency name on the left,
-              ; thousands, lakhs and crores comma-separated,
-              ; period as decimal point, and two decimal places.
-              commodity INR
-                format INR 1,00,00,000.00
-                an unsupported subdirective  ; ignored by hledger
-
-   Commodity error checking
-       In strict mode (-s/--strict) (or when you run  hledger  check  commodi-
-       ties),  hledger  will report an error if an undeclared commodity symbol
-       is used.  (With one exception: zero amounts are always allowed to  have
-       no  commodity symbol.)  It works like account error checking (described
-       above).
-
-   decimal-mark directive
-       You can use a decimal-mark directive - usually one per file, at the top
-       of the file - to declare which character represents a decimal mark when
-       parsing amounts in this file.  It can look like
-
-              decimal-mark .
-
-       or
-
-              decimal-mark ,
-
-       This prevents any ambiguity when parsing numbers in  the  file,  so  we
-       recommend  it,  especially  if  the file contains digit group marks (eg
-       thousands separators).
-
-   include directive
-       You can pull in the content of additional files by writing  an  include
-       directive, like this:
-
-              include FILEPATH
-
-       Only  journal files can include, and only journal, timeclock or timedot
-       files can be included (not CSV files, currently).
-
-       If the file path does not begin with a slash, it  is  relative  to  the
-       current file's folder.
-
-       A tilde means home directory, eg: include ~/main.journal.
-
-       The path may contain glob patterns to match multiple files, eg: include
-       *.journal.
-
-       There is limited support for recursive wildcards: **/ (the slash is re-
-       quired)  matches  0  or more subdirectories.  It's not super convenient
-       since you have to avoid include cycles and including  directories,  but
-       this can be done, eg: include */**/*.journal.
-
-       The path may also be prefixed to force a specific file format, overrid-
-       ing  the  file  extension (as described in Data formats): include time-
-       dot:~/notes/2023*.md.
-
-   P directive
-       The P directive declares a market price, which is a conversion rate be-
-       tween two commodities on a certain date.  This allows value reports  to
-       convert amounts of one commodity to their value in another, on or after
-       that  date.   These  prices  are  often obtained from a stock exchange,
-       cryptocurrency exchange, the or foreign exchange market.
-
-       The format is:
-
-              P DATE COMMODITY1SYMBOL COMMODITY2AMOUNT
-
-       DATE is a simple date, COMMODITY1SYMBOL is the symbol of the  commodity
-       being  priced, and COMMODITY2AMOUNT is the amount (symbol and quantity)
-       of commodity 2 that one unit of commodity 1 is worth on this date.  Ex-
-       amples:
-
-              # one euro was worth $1.35 from 2009-01-01 onward:
-              P 2009-01-01  $1.35
-
-              # and $1.40 from 2010-01-01 onward:
-              P 2010-01-01  $1.40
-
-       The -V, -X and --value flags use these market  prices  to  show  amount
-       values in another commodity.  See Value reporting.
-
-   payee directive
-       payee PAYEE NAME
-
-       This directive can be used to declare a limited set of payees which may
-       appear  in transaction descriptions.  The "payees" check will report an
-       error if any transaction refers to a payee that has not been  declared.
-       Eg:
-
-              payee Whole Foods    ; a comment
-
-       Payees do not have tags (tags in the comment will be ignored).
-
-       To declare the empty payee name, use "".
-
-              payee ""
-
-       Ledger-style indented subdirectives, if any, are currently ignored.
-
-   tag directive
-       tag TAGNAME
-
-       This  directive  can  be used to declare a limited set of tag names al-
-       lowed in tags.  TAGNAME should be a valid tag name (no spaces).  Eg:
-
-              tag  item-id
-
-       Any indented subdirectives are currently ignored.
-
-       The "tags" check will report an error if any  undeclared  tag  name  is
-       used.  It is quite easy to accidentally create a tag through normal use
-       of colons in comments; if you want to prevent this, you can declare and
-       check your tags .
-
-   Periodic transactions
-       The  ~  directive  declares a "periodic rule" which generates temporary
-       extra transactions, usually recurring at some interval, when hledger is
-       run with the --forecast flag.  These "forecast transactions" are useful
-       for forecasting future activity.  They exist only for the  duration  of
-       the report, and only when --forecast is used; they are not saved in the
-       journal file by hledger.
-
-       Periodic  rules also have a second use: with the --budget flag they set
-       budget goals for budgeting.
-
-       Periodic rules can be a little tricky, so before  you  use  them,  read
-       this whole section, or at least the following tips:
-
-       1. Two  spaces  accidentally  added or omitted will cause you trouble -
-          read about this below.
-
-       2. For troubleshooting, show the generated  transactions  with  hledger
-          print   --forecast  tag:generated  or  hledger  register  --forecast
-          tag:generated.
-
-       3. Forecasted transactions will begin only  after  the  last  non-fore-
-          casted transaction's date.
-
-       4. Forecasted  transactions  will  end 6 months from today, by default.
-          See below for the exact start/end rules.
-
-       5. period expressions can be tricky.   Their  documentation  needs  im-
-          provement, but is worth studying.
-
-       6. Some  period  expressions  with a repeating interval must begin on a
-          natural boundary of that interval.  Eg in  weekly  from  DATE,  DATE
-          must  be a monday.  ~ weekly from 2019/10/1 (a tuesday) will give an
-          error.
-
-       7. Other period expressions with an interval are automatically expanded
-          to cover a whole number of that interval.  (This is done to  improve
-          reports, but it also affects periodic transactions.  Yes, it's a bit
-          inconsistent  with  the above.)  Eg:  ~ every 10th day of month from
-          2023/01, which is equivalent to  ~ every  10th  day  of  month  from
-          2023/01/01, will be adjusted to start on 2019/12/10.
-
-   Periodic rule syntax
-       A periodic transaction rule looks like a normal journal entry, with the
-       date replaced by a tilde (~) followed by a period expression (mnemonic:
-       ~ looks like a recurring sine wave.):
-
-              # every first of month
-              ~ monthly
-                  expenses:rent          $2000
-                  assets:bank:checking
-
-              # every 15th of month in 2023's first quarter:
-              ~ monthly from 2023-04-15 to 2023-06-16
-                  expenses:utilities          $400
-                  assets:bank:checking
-
-       The  period expression is the same syntax used for specifying multi-pe-
-       riod reports, just interpreted differently; there, it specifies  report
-       periods; here it specifies recurrence dates (the periods' start dates).
-
-   Periodic rules and relative dates
-       Partial  or  relative  dates (like 12/31, 25, tomorrow, last week, next
-       quarter) are usually not recommended in periodic rules, since  the  re-
-       sults  will  change  as time passes.  If used, they will be interpreted
-       relative to, in order of preference:
-
-       1. the first day of the default year specified by a recent Y directive
-
-       2. or the date specified with --today
-
-       3. or the date on which you are running the report.
-
-       They will not be affected at all by report period  or  forecast  period
-       dates.
-
-   Two spaces between period expression and description!
-       If  the  period  expression  is  followed by a transaction description,
-       these must be separated by two or more spaces.  This helps hledger know
-       where the period expression ends, so that descriptions can not acciden-
-       tally alter their meaning, as in this example:
-
-              ; 2 or more spaces needed here, so the period is not understood as "every 2 months in 2023"
-              ;               ||
-              ;               vv
-              ~ every 2 months  in 2023, we will review
-                  assets:bank:checking   $1500
-                  income:acme inc
-
-       So,
-
-       o Do write two spaces between your period expression and your  transac-
-         tion description, if any.
-
-       o Don't  accidentally write two spaces in the middle of your period ex-
-         pression.
-
-   Auto postings
-       The = directive declares an "auto posting rule", which adds extra post-
-       ings to existing transactions.  (Remember,  postings  are  the  account
-       name & amount lines below a transaction's date & description.)
-
-       In  the  journal,  an auto posting rule looks quite like a transaction,
-       but instead of date and description it has = (mnemonic: "match") and  a
-       query, like this:
-
-              = QUERY
-                  ACCOUNT    AMOUNT
-                  ...
-
-       Queries  are  just like command line queries; an account name substring
-       is most common.  Query terms containing spaces should  be  enclosed  in
-       single or double quotes.
-
-       Each  = rule works like this: when hledger is run with the --auto flag,
-       wherever the QUERY matches a posting in the journal, the  rule's  post-
-       ings are added to that transaction, immediately below the matched post-
-       ing.   Note  these  generated postings are temporary, existing only for
-       the duration of the report, and only when --auto is used; they are  not
-       saved in the journal file by hledger.
-
-       Generated postings' amounts can depend on the matched posting's amount.
-       So  auto  postings  can  be  useful for, eg, adding tax postings with a
-       standard percentage.  AMOUNT can be:
-
-       o a number with no commodity symbol, like  2.   The  matched  posting's
-         commodity symbol will be added to this.
-
-       o a  normal amount with a commodity symbol, like $2.  This will be used
-         as-is.
-
-       o an asterisk followed by a number, like *2.  This  will  multiply  the
-         matched posting's amount (and total price, if any) by the number.
-
-       o an  asterisk  followed  by an amount with commodity symbol, like *$2.
-         This multiplies and also replaces the commodity symbol with this  new
-         one.
-
-       Some examples:
-
-              ; every time I buy food, schedule a dollar donation
-              = expenses:food
-                  (liabilities:charity)   $-1
-
-              ; when I buy a gift, also deduct that amount from a budget envelope subaccount
-              = expenses:gifts
-                  assets:checking:gifts  *-1
-                  assets:checking         *1
-
-              2017/12/1
-                expenses:food    $10
-                assets:checking
-
-              2017/12/14
-                expenses:gifts   $20
-                assets:checking
-
-              $ hledger print --auto
-              2017-12-01
-                  expenses:food              $10
-                  assets:checking
-                  (liabilities:charity)      $-1
-
-              2017-12-14
-                  expenses:gifts             $20
-                  assets:checking
-                  assets:checking:gifts     -$20
-                  assets:checking            $20
-
-       Note that depending fully on generated data such as this has some draw-
-       backs  -  it's less portable, less future-proof, less auditable by oth-
-       ers, and less robust (eg your balance assertions will depend on whether
-       you use or don't use --auto).  An alternative is to use  auto  postings
-       in "one time" fashion - use them to help build a complex journal entry,
-       view  it  with hledger print --auto, and then copy that output into the
-       journal file to make it permanent.
-
-   Auto postings and multiple files
-       An auto posting rule can affect any transaction in the current file, or
-       in any parent file or child file.  Note, currently it will  not  affect
-       sibling files (when multiple -f/--file are used - see #1212).
-
-   Auto postings and dates
-       A  posting  date (or secondary date) in the matched posting, or (taking
-       precedence) a posting date in the auto posting rule itself,  will  also
-       be used in the generated posting.
-
-   Auto postings and transaction balancing / inferred amounts / balance asser-
-       tions
-       Currently, auto postings are added:
-
-       o after  missing amounts are inferred, and transactions are checked for
-         balancedness,
-
-       o but before balance assertions are checked.
-
-       Note this means that journal entries must be balanced both  before  and
-       after auto postings are added.  This changed in hledger 1.12+; see #893
-       for background.
-
-       This  also means that you cannot have more than one auto-posting with a
-       missing amount applied to a given transaction, as it will be unable  to
-       infer amounts.
-
-   Auto posting tags
-       Automated postings will have some extra tags:
-
-       o generated-posting:= QUERY - shows this was generated by an auto post-
-         ing rule, and the query
-
-       o _generated-posting:=  QUERY  - a hidden tag, which does not appear in
-         hledger's output.  This can be used to match postings generated "just
-         now", rather than generated in the past and saved to the journal.
-
-       Also, any transaction that has been changed by auto posting rules  will
-       have these tags added:
-
-       o modified: - this transaction was modified
-
-       o _modified: - a hidden tag not appearing in the comment; this transac-
-         tion was modified "just now".
-
-   Auto postings on forecast transactions only
-       Tip:  you can can make auto postings that will apply to forecast trans-
-       actions but not recorded transactions, by adding  tag:_generated-trans-
-       action  to their QUERY.  This can be useful when generating new journal
-       entries to be saved in the journal.
-
-   Other syntax
-       hledger journal format supports quite a few other features,  mainly  to
-       make  interoperating  with or converting from Ledger easier.  Note some
-       of the features below are powerful and can be useful in special  cases,
-       but  in general, features in this section are considered less important
-       or even not recommended for most users.   Downsides  are  mentioned  to
-       help you decide if you want to use them.
-
-   Balance assignments
-       Ledger-style  balance  assignments  are also supported.  These are like
-       balance assertions, but with no posting amount on the left side of  the
-       equals  sign;  instead  it is calculated automatically so as to satisfy
-       the assertion.  This can be a convenience during data  entry,  eg  when
-       setting opening balances:
-
-              ; starting a new journal, set asset account balances
-              2016/1/1 opening balances
-                assets:checking            = $409.32
-                assets:savings             = $735.24
-                assets:cash                 = $42
-                equity:opening balances
-
-       or when adjusting a balance to reality:
-
-              ; no cash left; update balance, record any untracked spending as a generic expense
-              2016/1/15
-                assets:cash    = $0
-                expenses:misc
-
-       The calculated amount depends on the account's balance in the commodity
-       at  that  point  (which depends on the previously-dated postings of the
-       commodity to that account since the last balance assertion  or  assign-
-       ment).
-
-       Downsides:  using balance assignments makes your journal less explicit;
-       to know the exact amount posted, you have to run hledger or do the cal-
-       culations yourself, instead of just reading it.  Also  balance  assign-
-       ments' forcing of balances can hide errors.  These things make your fi-
-       nancial  data less portable, less future-proof, and less trustworthy in
-       an audit.
-
-   Balance assignments and costs
-       A cost in a balance assignment will cause the calculated amount to have
-       that cost attached:
-
-              2019/1/1
-                (a)             = $1 @ 2
-
-              $ hledger print --explicit
-              2019-01-01
-                  (a)         $1 @ 2 = $1 @ 2
-
-   Balance assignments and multiple files
-       Balance assignments handle  multiple  files  like  balance  assertions.
-       They  see balance from other files previously included from the current
-       file, but not from previous sibling or parent files.
-
-   Bracketed posting dates
-       For setting posting dates and secondary posting dates, Ledger's  brack-
-       eted date syntax is also supported: [DATE], [DATE=DATE2] or [=DATE2] in
-       posting  comments.   hledger will attempt to parse any square-bracketed
-       sequence of the 0123456789/-.= characters in this way.  With this  syn-
-       tax,  DATE  infers  its  year from the transaction and DATE2 infers its
-       year from DATE.
-
-       Downsides:  another  syntax  to   learn,   redundant   with   hledger's
-       date:/date2: tags, and confusingly similar to Ledger's lot date syntax.
-
-   D directive
-       D AMOUNT
-
-       This  directive sets a default commodity, to be used for any subsequent
-       commodityless amounts (ie, plain numbers) seen while parsing the  jour-
-       nal.   This  effect lasts until the next D directive, or the end of the
-       current file.
-
-       For compatibility/historical reasons, D also acts like a commodity  di-
-       rective  (setting  the commodity's decimal mark for parsing and display
-       style for output).  So its argument is not just a commodity symbol, but
-       a full amount demonstrating the style.  The amount must include a deci-
-       mal mark (either period or comma).  Eg:
-
-              ; commodity-less amounts should be treated as dollars
-              ; (and displayed with the dollar sign on the left, thousands separators and two decimal places)
-              D $1,000.00
-
-              1/1
-                a     5  ; <- commodity-less amount, parsed as $5 and displayed as $5.00
-                b
-
-       Interactions with other directives:
-
-       For setting a commodity's display  style,  a  commodity  directive  has
-       highest priority, then a D directive.
-
-       For  detecting  a commodity's decimal mark during parsing, decimal-mark
-       has highest priority, then commodity, then D.
-
-       For checking commodity symbols with the check command, a commodity  di-
-       rective is required (hledger check commodities ignores D directives).
-
-       Downsides:  omitting  commodity  symbols makes your financial data less
-       explicit, less portable, and less trustworthy in an audit.  It is  usu-
-       ally  an unsustainable shortcut; sooner or later you will want to track
-       multiple commodities.  D is overloaded with  functions  redundant  with
-       commodity and decimal-mark.  And it works differently from Ledger's D.
-
-   apply account directive
-       This  directive  sets a default parent account, which will be prepended
-       to all accounts in following entries, until an end apply account direc-
-       tive or end of current file.  Eg:
-
-              apply account home
-
-              2010/1/1
-                  food    $10
-                  cash
-
-              end apply account
-
-       is equivalent to:
-
-              2010/01/01
-                  home:food           $10
-                  home:cash          $-10
-
-       account directives are also affected, and so is any included content.
-
-       Account names entered via hledger add or hledger-web are not affected.
-
-       Account aliases, if any,  are  applied  after  the  parent  account  is
-       prepended.
-
-       Downsides:  this  can  make  your  financial  data  less explicit, less
-       portable, and less trustworthy in an audit.
-
-   Y directive
-       Y YEAR
-
-       or (deprecated backward-compatible forms):
-
-       year YEAR apply year YEAR
-
-       The space is optional.  This sets a default year to be used for  subse-
-       quent dates which don't specify a year.  Eg:
-
-              Y2009  ; set default year to 2009
-
-              12/15  ; equivalent to 2009/12/15
-                expenses  1
-                assets
-
-              year 2010  ; change default year to 2010
-
-              2009/1/30  ; specifies the year, not affected
-                expenses  1
-                assets
-
-              1/31   ; equivalent to 2010/1/31
-                expenses  1
-                assets
-
-       Downsides: omitting the year (from primary transaction dates, at least)
-       makes your financial data less explicit, less portable, and less trust-
-       worthy  in  an  audit.   Such dates can get separated from their corre-
-       sponding Y directive, eg when evaluating a region  of  the  journal  in
-       your  editor.  A missing Y directive makes reports dependent on today's
-       date.
-
-   Secondary dates
-       A secondary date is written after the primary date, following an equals
-       sign: DATE1=DATE2.  If the year is omitted, the primary date's year  is
-       assumed.  When running reports, the primary (left side) date is used by
-       default, but with the --date2 flag (--aux-date or--effective also work,
-       for  Ledger  users),  the  secondary (right side) date will be used in-
-       stead.
-
-       The meaning of secondary dates is up to you.  Eg it could  be  "primary
-       is  the bank's clearing date, secondary is the date the transaction was
-       initiated, if different".
-
-       In practice, this feature usually adds confusion:
-
-       o You have to remember the primary and secondary  dates'  meaning,  and
-         follow that consistently.
-
-       o It  splits  your bookkeeping into two modes, and you have to remember
-         which mode is appropriate for a given report.
-
-       o Usually your balance assertions will work  with  only  one  of  these
-         modes.
-
-       o It  makes  your  financial  data more complicated, less portable, and
-         less clear in an audit.
-
-       o It interacts with every feature, creating an ongoing cost for  imple-
-         mentors.
-
-       o It distracts new users and supporters.
-
-       o Posting dates are simpler and work better.
-
-       So secondary dates are officially deprecated in hledger, remaining only
-       as  a  Ledger  compatibility  aid; we recommend using posting dates in-
-       stead.
-
-   Star comments
-       Lines beginning with * (star/asterisk) are also  comment  lines.   This
-       feature allows Emacs users to insert org headings in their journal, al-
-       lowing them to fold/unfold/navigate it like an outline when viewed with
-       org mode.
-
-       Downsides:  another, unconventional comment syntax to learn.  Decreases
-       your journal's portability.  And switching to Emacs org mode  just  for
-       folding/unfolding  meant  losing  the benefits of ledger mode; nowadays
-       you can add outshine mode to ledger mode to get folding without  losing
-       ledger mode's features.
-
-   Valuation expressions
-       Ledger  allows  a  valuation  function or value to be written in double
-       parentheses after an amount.  hledger ignores these.
-
-   Virtual postings
-       A posting with parentheses around the account name, like (some:account)
-       10, is called an unbalanced virtual posting.   These  postings  do  not
-       participate  in  transaction balancing.  (And if you write them without
-       an amount, a zero amount is always inferred.)  These  can  occasionally
-       be  convenient for special circumstances, but they violate double entry
-       bookkeeping and make your data less portable  across  applications,  so
-       many people avoid using them at all.
-
-       A  posting  with  brackets  around the account name ([some:account]) is
-       called a balanced virtual posting.  The balanced virtual postings in  a
-       transaction must add up to zero, just like ordinary postings, but sepa-
-       rately  from  them.  These are not part of double entry bookkeeping ei-
-       ther, but they are at least balanced.  An example:
-
-              2022-01-01 buy food with cash, update budget envelope subaccounts, & something else
-                assets:cash                    $-10  ; <- these balance each other
-                expenses:food                    $7  ; <-
-                expenses:food                    $3  ; <-
-                [assets:checking:budget:food]  $-10  ;   <- and these balance each other
-                [assets:checking:available]     $10  ;   <-
-                (something:else)                 $5  ;     <- this is not required to balance
-
-       Ordinary postings, whose account names are  neither  parenthesised  nor
-       bracketed,  are called real postings.  You can exclude virtual postings
-       from reports with the -R/--real flag or a real:1 query.
-
-   Other Ledger directives
-       These other Ledger directives are currently accepted but ignored.  This
-       allows hledger to read more Ledger files, but be aware  that  hledger's
-       reports may differ from Ledger's if you use these.
-
-              apply fixed COMM AMT
-              apply tag   TAG
-              assert      EXPR
-              bucket / A  ACCT
-              capture     ACCT REGEX
-              check       EXPR
-              define      VAR=EXPR
-              end apply fixed
-              end apply tag
-              end apply year
-              end tag
-              eval / expr EXPR
-              python
-                PYTHONCODE
-              tag         NAME
-              value       EXPR
-              --command-line-flags
-
-       See  also https://hledger.org/ledger.html for a detailed hledger/Ledger
-       syntax comparison.
-
-   Other cost/lot notations
-       A slight digression for Ledger and Beancount users.  Ledger has a  num-
-       ber of cost/lot-related notations:
-
-       o @ UNITCOST and @@ TOTALCOST
-
-         o expresses a conversion rate, as in hledger
-
-         o when  buying,  also  creates  a lot than can be selected at selling
-           time
-
-       o (@) UNITCOST and (@@) TOTALCOST (virtual cost)
-
-         o like the above, but also means "this cost  was  exceptional,  don't
-           use it when inferring market prices".
-
-       Currently,  hledger treats the above like @ and @@; the parentheses are
-       ignored.
-
-       o {=FIXEDUNITCOST} and {{=FIXEDTOTALCOST}} (fixed price)
-
-         o when buying, means "this cost is also the fixed price, don't let it
-           fluctuate in value reports"
-
-       o {UNITCOST} and {{TOTALCOST}} (lot price)
-
-         o can be used identically to @ UNITCOST and @@ TOTALCOST,  also  cre-
-           ates a lot
-
-         o when  selling,  combined with @ ..., specifies an investment lot by
-           its cost basis; does not check if that lot is present
-
-       o and related: [YYYY/MM/DD] (lot date)
-
-         o when buying, attaches this acquisition date to the lot
-
-         o when selling, selects a lot by its acquisition date
-
-       o (SOME TEXT) (lot note)
-
-         o when buying, attaches this note to the lot
-
-         o when selling, selects a lot by its note
-
-       Currently, hledger accepts any or all of the above in any  order  after
-       the posting amount, but ignores them.  (This can break transaction bal-
-       ancing.)
-
-       For Beancount users, the notation and behaviour is different:
-
-       o @ UNITCOST and @@ TOTALCOST
-
-         o expresses a cost without creating a lot, as in hledger
-
-         o when buying (augmenting) or selling (reducing) a lot, combined with
-           {...}:  documents  the cost/selling price (not used for transaction
-           balancing)
-
-       o {UNITCOST} and {{TOTALCOST}}
-
-         o when buying (augmenting), expresses the cost for  transaction  bal-
-           ancing, and also creates a lot with this cost basis attached
-
-         o when selling (reducing),
-
-           o selects a lot by its cost basis
-
-           o raises an error if that lot is not present or can not be selected
-             unambiguously (depending on booking method configured)
-
-           o expresses the selling price for transaction balancing
-
-       Currently,  hledger  accepts  the {UNITCOST}/{{TOTALCOST}} notation but
-       ignores it.
-
-       o variations: {}, {YYYY-MM-DD}, {"LABEL"}, {UNITCOST, "LABEL"},  {UNIT-
-         COST, YYYY-MM-DD, "LABEL"} etc.
-
-       Currently, hledger rejects these.
-
-CSV
-       hledger  can read CSV files (Character Separated Value - usually comma,
-       semicolon, or tab) containing dated records,  automatically  converting
-       each record into a transaction.
-
-       (To learn about writing CSV, see CSV output.)
-
-       For  best error messages when reading CSV/TSV/SSV files, make sure they
-       have a corresponding .csv, .tsv or .ssv file extension or use a hledger
-       file prefix (see File Extension below).
-
-       Each CSV file must be described by a corresponding rules file.
-       This contains rules describing the CSV data (header line,  fields  lay-
-       out,  date format etc.), how to construct hledger transactions from it,
-       and how to categorise transactions based on description  or  other  at-
-       tributes.
-
-       By  default,  hledger  expects this rules file to be named like the CSV
-       file, with an extra .rules extension added, in the same directory.   Eg
-       when  asked to read foo/FILE.csv, hledger looks for foo/FILE.csv.rules.
-       You can specify a different rules file with the --rules option.
-
-       At minimum, the rules file must identify the date  and  amount  fields,
-       and  often  it also specifies the date format and how many header lines
-       there are.  Here's a simple CSV file and a rules file for it:
-
-              Date, Description, Id, Amount
-              12/11/2019, Foo, 123, 10.23
-
-              # basic.csv.rules
-              skip         1
-              fields       date, description, , amount
-              date-format  %d/%m/%Y
-
-              $ hledger print -f basic.csv
-              2019-11-12 Foo
-                  expenses:unknown           10.23
-                  income:unknown            -10.23
-
-       There's an introductory Importing CSV data tutorial on hledger.org, and
-       more  CSV  rules  examples  below,   and   a   larger   collection   at
-       https://github.com/simonmichael/hledger/tree/master/examples/csv.
-
-   CSV rules cheatsheet
-       The following kinds of rule can appear in the rules file, in any order.
-       (Blank lines and lines beginning with # or ; or * are ignored.)
-
-       source                     optionally  declare  which  file  to read data
-                                  from
-       separator                  declare the field separator, instead of  rely-
-                                  ing on file extension
-       skip                       skip one or more header lines at start of file
-       date-format                declare how to parse CSV dates/date-times
-       timezone                   declare   the   time  zone  of  ambiguous  CSV
-                                  date-times
-       newest-first               improve txn order  when:  there  are  multiple
-                                  records, newest first, all with the same date
-       intra-day-reversed         improve  txn  order when: same-day txns are in
-                                  opposite order to the overall file
-       decimal-mark               declare the decimal mark used in CSV  amounts,
-                                  when ambiguous
-       fields list                name  CSV  fields  for easy reference, and op-
-                                  tionally assign their values to hledger fields
-       Field assignment           assign a CSV value or interpolated text  value
-                                  to a hledger field
-       if block                   conditionally assign values to hledger fields,
-                                  or skip a record or end (skip rest of file)
-       if table                   conditionally assign values to hledger fields,
-                                  using compact syntax
-       balance-type               select  which  type  of balance assertions/as-
-                                  signments to generate
-       include                    inline another CSV rules file
-
-       Working with CSV tips can be found below, including How CSV  rules  are
-       evaluated.
-
-   source
-       If  you  tell  hledger to read a csv file with -f foo.csv, it will look
-       for rules in foo.csv.rules.  Or, you can tell  it  to  read  the  rules
-       file,  with  -f  foo.csv.rules,  and  it  will look for data in foo.csv
-       (since 1.30).
-
-       These are mostly equivalent, but the second method provides some  extra
-       features.   For  one,  the data file can be missing, without causing an
-       error; it is just considered empty.  And, you can specify  a  different
-       data file by adding a "source" rule:
-
-              source ./Checking1.csv
-
-       If  you specify just a file name with no path, hledger will look for it
-       in your system's downloads directory (~/Downloads, currently):
-
-              source Checking1.csv
-
-       And if you specify a glob pattern, hledger will read the most recent of
-       the matched files (useful with repeated downloads):
-
-              source Checking1*.csv
-
-       See also "Working with CSV > Reading files specified by rule".
-
-   separator
-       You can use the separator rule to read other kinds  of  character-sepa-
-       rated  data.   The  argument  is any single separator character, or the
-       words tab or space (case insensitive).  Eg, for comma-separated  values
-       (CSV):
-
-              separator ,
-
-       or for semicolon-separated values (SSV):
-
-              separator ;
-
-       or for tab-separated values (TSV):
-
-              separator TAB
-
-       If  the  input file has a .csv, .ssv or .tsv file extension (or a csv:,
-       ssv:, tsv: prefix), the appropriate separator will be inferred automat-
-       ically, and you won't need this rule.
-
-   skip
-              skip N
-
-       The word skip followed by a number (or  no  number,  meaning  1)  tells
-       hledger  to  ignore this many non-empty lines at the start of the input
-       data.  You'll need this whenever your CSV data contains  header  lines.
-       Note,  empty  and  blank  lines are skipped automatically, so you don't
-       need to count those.
-
-       skip has a second meaning: it can be used inside if  blocks  (described
-       below),  to  skip  one  or more records whenever the condition is true.
-       Records skipped in this way are ignored, except they are still required
-       to be valid CSV.
-
-   date-format
-              date-format DATEFMT
-
-       This is a helper for the date (and date2) fields.  If  your  CSV  dates
-       are  not  formatted  like  YYYY-MM-DD, YYYY/MM/DD or YYYY.MM.DD, you'll
-       need to add a date-format rule describing them  with  a  strptime-style
-       date    parsing   pattern   -   see   https://hackage.haskell.org/pack-
-       age/time/docs/Data-Time-Format.html#v:formatTime.   The  pattern   must
-       parse the CSV date value completely.  Some examples:
-
-              # MM/DD/YY
-              date-format %m/%d/%y
-
-              # D/M/YYYY
-              # The - makes leading zeros optional.
-              date-format %-d/%-m/%Y
-
-              # YYYY-Mmm-DD
-              date-format %Y-%h-%d
-
-              # M/D/YYYY HH:MM AM some other junk
-              # Note the time and junk must be fully parsed, though only the date is used.
-              date-format %-m/%-d/%Y %l:%M %p some other junk
-
-   timezone
-              timezone TIMEZONE
-
-       When  CSV  contains  date-times  that  are implicitly in some time zone
-       other than yours, but containing no explicit time zone information, you
-       can use this rule to declare the CSV's native time  zone,  which  helps
-       prevent off-by-one dates.
-
-       When  the  CSV  date-times  do contain time zone information, you don't
-       need this rule; instead, use %Z in date-format (or %z,  %EZ,  %Ez;  see
-       the formatTime link above).
-
-       In either of these cases, hledger will do a time-zone-aware conversion,
-       localising the CSV date-times to your current system time zone.  If you
-       prefer to localise to some other time zone, eg for reproducibility, you
-       can  (on unix at least) set the output timezone with the TZ environment
-       variable, eg:
-
-              $ TZ=-1000 hledger print -f foo.csv  # or TZ=-1000 hledger import foo.csv
-
-       timezone currently does not understand timezone  names,  except  "UTC",
-       "GMT",  "EST", "EDT", "CST", "CDT", "MST", "MDT", "PST", or "PDT".  For
-       others, use numeric format: +HHMM or -HHMM.
-
-   newest-first
-       hledger tries to ensure that the generated transactions will be ordered
-       chronologically,  including  same-day  transactions.   Usually  it  can
-       auto-detect  how the CSV records are ordered.  But if it encounters CSV
-       where all records are on the same date, it assumes that the records are
-       oldest first.  If in fact the CSV's records are normally newest  first,
-       like:
-
-              2022-10-01, txn 3...
-              2022-10-01, txn 2...
-              2022-10-01, txn 1...
-
-       you can add the newest-first rule to help hledger generate the transac-
-       tions in correct order.
-
-              # same-day CSV records are newest first
-              newest-first
-
-   intra-day-reversed
-       If  CSV records within a single day are ordered opposite to the overall
-       record order, you can add the intra-day-reversed rule  to  improve  the
-       order  of journal entries.  Eg, here the overall record order is newest
-       first, but same-day records are oldest first:
-
-              2022-10-02, txn 3...
-              2022-10-02, txn 4...
-              2022-10-01, txn 1...
-              2022-10-01, txn 2...
-
-              # transactions within each day are reversed with respect to the overall date order
-              intra-day-reversed
-
-   decimal-mark
-              decimal-mark .
-
-       or:
-
-              decimal-mark ,
-
-       hledger automatically accepts either period or comma as a decimal  mark
-       when  parsing  numbers (cf Amounts).  However if any numbers in the CSV
-       contain digit group marks,  such  as  thousand-separating  commas,  you
-       should  declare  the  decimal  mark explicitly with this rule, to avoid
-       misparsed numbers.
-
-   fields list
-              fields FIELDNAME1, FIELDNAME2, ...
-
-       A fields list (the word fields followed by comma-separated field names)
-       is optional, but convenient.  It does two things:
-
-       1. It names the CSV field in each column.  This can  be  convenient  if
-          you  are  referencing them in other rules, so you can say %SomeField
-          instead of remembering %13.
-
-       2. Whenever you use one of the special hledger field  names  (described
-          below),  it  assigns  the CSV value in this position to that hledger
-          field.  This is the quickest way to populate  hledger's  fields  and
-          build a transaction.
-
-       Here's  an  example  that  says "use the 1st, 2nd and 4th fields as the
-       transaction's date, description and amount; name the  last  two  fields
-       for later reference; and ignore the others":
-
-              fields date, description, , amount, , , somefield, anotherfield
-
-       In a fields list, the separator is always comma; it is unrelated to the
-       CSV file's separator.  Also:
-
-       o There must be least two items in the list (at least one comma).
-
-       o Field  names may not contain spaces.  Spaces before/after field names
-         are optional.
-
-       o Field names may contain _ (underscore) or - (hyphen).
-
-       o Fields you don't care about can be given a dummy  name  or  an  empty
-         name.
-
-       If  the  CSV contains column headings, it's convenient to use these for
-       your field names, suitably modified (eg  lower-cased  with  spaces  re-
-       placed by underscores).
-
-       Sometimes  you may want to alter a CSV field name to avoid assigning to
-       a hledger field with the same name.  Eg you could call the CSV's  "bal-
-       ance"  field balance_ to avoid directly setting hledger's balance field
-       (and generating a balance assertion).
-
-   Field assignment
-              HLEDGERFIELD FIELDVALUE
-
-       Field assignments are the more flexible way to  assign  CSV  values  to
-       hledger fields.  They can be used instead of or in addition to a fields
-       list (see above).
-
-       To  assign a value to a hledger field, write the field name (any of the
-       standard hledger field/pseudo-field names,  defined  below),  a  space,
-       followed  by a text value on the same line.  This text value may inter-
-       polate CSV fields, referenced either by their 1-based position  in  the
-       CSV  record  (%N)  or  by  the  name they were given in the fields list
-       (%CSVFIELD), and regular expression match groups (\N).
-
-       Some examples:
-
-              # set the amount to the 4th CSV field, with " USD" appended
-              amount %4 USD
-
-              # combine three fields to make a comment, containing note: and date: tags
-              comment note: %somefield - %anotherfield, date: %1
-
-       Tips:
-
-       o Interpolation strips outer whitespace (so a CSV value like " 1 "  be-
-         comes 1 when interpolated) (#1051).
-
-       o Interpolations  always refer to a CSV field - you can't interpolate a
-         hledger field.  (See Referencing other fields below).
-
-   Field names
-       Note the two kinds of field names mentioned  here,  and  used  only  in
-       hledger CSV rules files:
-
-       1. CSV  field  names  (CSVFIELD in these docs): you can optionally name
-          the CSV columns for easy reference (since hledger doesn't yet  auto-
-          matically recognise column headings in a CSV file), by writing arbi-
-          trary names in a fields list, eg:
-
-                  fields When, What, Some_Id, Net, Total, Foo, Bar
-
-       2. Special  hledger  field names (HLEDGERFIELD in these docs): you must
-          set at least some of these to generate the hledger transaction  from
-          a  CSV  record, by writing them as the left hand side of a field as-
-          signment, eg:
-
-                  date        %When
-                  code        %Some_Id
-                  description %What
-                  comment     %Foo %Bar
-                  amount1     $ %Total
-
-           or directly in a fields list:
-
-                  fields date, description, code, , amount1, Foo, Bar
-                  currency $
-                  comment  %Foo %Bar
-
-       Here are all the special hledger field names available, and  what  hap-
-       pens when you assign values to them:
-
-   date field
-       Assigning to date sets the transaction date.
-
-   date2 field
-       date2 sets the transaction's secondary date, if any.
-
-   status field
-       status sets the transaction's status, if any.
-
-   code field
-       code sets the transaction's code, if any.
-
-   description field
-       description sets the transaction's description, if any.
-
-   comment field
-       comment sets the transaction's comment, if any.
-
-       commentN, where N is a number, sets the Nth posting's comment.
-
-       You  can  assign multi-line comments by writing literal \n in the code.
-       A comment starting with \n will begin on a new line.
-
-       Comments can contain tags, as usual.
-
-       Posting comments can also contain a posting date.  A secondary date, or
-       a year-less date, will be ignored.
-
-   account field
-       Assigning to accountN, where N is 1 to 99, sets the account name of the
-       Nth posting, and causes that posting to be generated.
-
-       Most often there are two postings, so you'll want to set  account1  and
-       account2.   Typically  account1 is associated with the CSV file, and is
-       set once with a top-level assignment, while account2 is  set  based  on
-       each transaction's description, in conditional rules.
-
-       If  a  posting's  account name is left unset but its amount is set (see
-       below), a default account name will be chosen (like  "expenses:unknown"
-       or "income:unknown").
-
-   amount field
-       There  are several ways to set posting amounts from CSV, useful in dif-
-       ferent situations.
-
-       1. amount is the oldest and  simplest.   Assigning  to  this  sets  the
-          amount of the first and second postings.  In the second posting, the
-          amount  will be negated; also, if it has a cost attached, it will be
-          converted to cost.
-
-       2. amount-in and amount-out work exactly like the above, but should  be
-          used  when  the  CSV  has  two  amount  fields  (such as "Debit" and
-          "Credit",  or  "Inflow"  and  "Outflow").   Whichever  field  has  a
-          non-zero  value  will  be used as the amount of the first and second
-          postings.  Here are some tips to avoid confusion:
-
-           o It's not "amount-in for posting 1 and amount-out for posting  2",
-             it  is  "extract a single amount from the amount-in or amount-out
-             field, and use that for posting 1 and (negated) for posting 2".
-
-           o Don't use both amount and amount-in/amount-out in the same  rules
-             file; choose based on whether the amount is in a single CSV field
-             or spread across two fields.
-
-           o In  each record, at most one of the two CSV fields should contain
-             a non-zero amount; the other field must contain a zero  or  noth-
-             ing.
-
-           o hledger  assumes both CSV fields contain unsigned numbers, and it
-             automatically negates the amount-out values.
-
-           o If the data doesn't fit these requirements, you'll probably  need
-             an if rule (see below).
-
-       3. amountN (where N is a number from 1 to 99) sets the amount of only a
-          single  posting: the Nth posting in the transaction.  You'll usually
-          need at least two such assignments to make a  balanced  transaction.
-          You can also generate more than two postings, to represent more com-
-          plex  transactions.   The  posting numbers don't have to be consecu-
-          tive; with if rules, higher posting numbers can be useful to  ensure
-          a certain order of postings.
-
-       4. amountN-in  and  amountN-out work exactly like the above, but should
-          be used when the CSV has two amount fields.  This  is  analogous  to
-          amount-in and amount-out, and those tips also apply here.
-
-       5. Remember that a fields list can also do assignments.  So in a fields
-          list  if  you name a CSV field "amount", that counts as assigning to
-          amount.  (If you don't want that, call  it  something  else  in  the
-          fields list, like "amount_".)
-
-       6. The  above  don't handle every situation; if you need more flexibil-
-          ity, use an if rule to set amounts conditionally.  See "Working with
-          CSV > Setting amounts" below for more on this and on  amount-setting
-          generally.
-
-   currency field
-       currency  sets  a  currency  symbol,  to  be prepended to all postings'
-       amounts.  You can use this if the CSV amounts do not  have  a  currency
-       symbol, eg if it is in a separate column.
-
-       currencyN prepends a currency symbol to just the Nth posting's amount.
-
-   balance field
-       balanceN  sets  a balance assertion amount (or if the posting amount is
-       left empty, a balance assignment) on posting N.
-
-       balance is a compatibility spelling for hledger <1.17; it is equivalent
-       to balance1.
-
-       You can adjust the type of assertion/assignment with  the  balance-type
-       rule (see below).
-
-       See  the Working with CSV tips below for more about setting amounts and
-       currency.
-
-   if block
-       Rules can be applied conditionally, depending on patterns  in  the  CSV
-       data.   This allows flexibility; in particular, it is how you can cate-
-       gorise transactions, selecting an appropriate  account  name  based  on
-       their  description  (for  example).  There are two ways to write condi-
-       tional rules: "if blocks", described here, and "if  tables",  described
-       below.
-
-       An  if  block is the word if and one or more "matcher" expressions (can
-       be a word or phrase), one per line, starting either on the same or next
-       line; followed by one or more indented rules.  Eg,
-
-              if MATCHER
-               RULE
-
-       or
-
-              if
-              MATCHER
-              MATCHER
-              MATCHER
-               RULE
-               RULE
-
-       If any of the matchers succeeds, all of the indented rules will be  ap-
-       plied.   They  are usually field assignments, but the following special
-       rules may also be used within an if block:
-
-       o skip - skips the matched CSV record (generating no  transaction  from
-         it)
-
-       o end - skips the rest of the current CSV file.
-
-       Some examples:
-
-              # if the record contains "groceries", set account2 to "expenses:groceries"
-              if groceries
-               account2 expenses:groceries
-
-              # if the record contains any of these phrases, set account2 and a transaction comment as shown
-              if
-              monthly service fee
-              atm transaction fee
-              banking thru software
-               account2 expenses:business:banking
-               comment  XXX deductible ? check it
-
-              # if an empty record is seen (assuming five fields), ignore the rest of the CSV file
-              if ,,,,
-               end
-
-   Matchers
-       There are two kinds of matcher:
-
-       1. A  whole  record matcher is simplest: it is just a word, single-line
-          text fragment, or other regular expression, which hledger  will  try
-          to match case-insensitively anywhere within the CSV record.
-       Eg: whole foods.
-
-       2. A  field matcher has a percent-prefixed CSV field number or name be-
-          fore the pattern.
-       Eg: %3 whole foods or %description whole foods.
-       hledger will try to match the pattern just within the named CSV field.
-
-       When using these, there's two things to be aware of:
-
-       1. Whole record matchers don't see the exact original record; they  see
-          a  reconstruction  of  it,  in which values are comma-separated, and
-          quotes enclosing values and whitespace outside those quotes are  re-
-          moved.
-       Eg when reading an SSV record like: 2023-01-01 ; "Acme, Inc. " ;  1,000
-       the whole record matcher sees instead: 2023-01-01,Acme, Inc. ,1,000
-
-       2. Field matchers expect either a CSV field number, or a CSV field name
-          declared  with fields.  (Don't use a hledger field name here, unless
-          it is also a CSV field name.)  A non-CSV field name will  cause  the
-          matcher  to  match against "" (the empty string), and does not raise
-          an error, allowing easier reuse of common rules with  different  CSV
-          files.
-
-       You can also prefix a matcher with ! (and optional space) to negate it.
-       Eg  !  whole  foods,  !  %3 whole foods, !%description whole foods will
-       match if "whole foods" is NOT present.  Added in 1.32.
-
-       The pattern is, as usual in hledger, a POSIX extended  regular  expres-
-       sion  that also supports GNU word boundaries (\b, \B, \<, \>) and noth-
-       ing else.  If you have trouble with it, see  "Regular  expressions"  in
-       the  hledger  manual  (https://hledger.org/hledger.html#regular-expres-
-       sions).
-
-   Multiple matchers
-       When an if block has multiple matchers, each on its own line,
-
-       o By default they are OR'd (any of them can match).
-
-       o Matcher lines beginning with & (and optional space) are  AND'ed  with
-         the matcher above (all in the AND'ed group must match).
-
-       (Since  1.41:) You can use a negated ! matcher on a & line, meaning AND
-       NOT.
-
-   Match groups
-       Added in 1.32
-
-       Matchers can define match groups: parenthesised portions of the regular
-       expression which are available  for  reference  in  field  assignments.
-       Groups are enclosed in regular parentheses (( and )) and can be nested.
-       Each  group is available in field assignments using the token \N, where
-       N is an index into the match groups for this  conditional  block  (e.g.
-       \1, \2, etc.).
-
-       Example:  Warp  credit  card  payment  postings to the beginning of the
-       billing period (Month start), to match how they are presented in state-
-       ments, using posting dates:
-
-              if %date (....-..)-..
-                comment2 date:\1-01
-
-       Another example: Read the expense account from the CSV field, but throw
-       away a prefix:
-
-              if %account1 liabilities:family:(expenses:.*)
-                  account1 \1
-
-   if table
-       "if tables" are an alternative to if  blocks;  they  can  express  many
-       matchers  and  field assignments in a more compact tabular format, like
-       this:
-
-              if,HLEDGERFIELD1,HLEDGERFIELD2,...
-              MATCHERA,VALUE1,VALUE2,...
-              MATCHERB,VALUE1,VALUE2,...
-              ; Comment line that explains MATCHERC
-              MATCHERC,VALUE1,VALUE2,...
-              <empty line>
-
-       The first character after if is taken to be this if table's field sepa-
-       rator.  It is unrelated to the separator used  in  the  CSV  file.   It
-       should be a non-alphanumeric character like , or | that does not appear
-       anywhere  else  in  the  table (it should not be used in field names or
-       matchers or values, and it cannot be escaped with a backslash).
-
-       Each line must contain the same number of separators; empty values  are
-       allowed.   Whitespace  can be used in the matcher lines for readability
-       (but not in the if line, currently).  You can use the comment lines  in
-       the  table body.  The table must be terminated by an empty line (or end
-       of file).
-
-       An if table like the above is interpreted as follows: try  all  of  the
-       matchers; whenever a matcher succeeds, assign all of the values on that
-       line  to  the  corresponding  hledger  fields; If multiple lines match,
-       later lines will override fields assigned by the earlier  ones  -  just
-       like the sequence of if blocks would behave.
-
-       If table presented above is equivalent to this sequence of if blocks:
-
-              if MATCHERA
-                HLEDGERFIELD1 VALUE1
-                HLEDGERFIELD2 VALUE2
-                ...
-
-              if MATCHERB
-                HLEDGERFIELD1 VALUE1
-                HLEDGERFIELD2 VALUE2
-                ...
-
-              ; Comment line which explains MATCHERC
-              if MATCHERC
-                HLEDGERFIELD1 VALUE1
-                HLEDGERFIELD2 VALUE2
-                ...
-
-       Example:
-
-              if,account2,comment
-              atm transaction fee,expenses:business:banking,deductible? check it
-              %description groceries,expenses:groceries,
-              ;; Comment line that desribes why this particular date is special
-              2023/01/12.*Plumbing LLC,expenses:house:upkeep,emergency plumbing call-out
-
-   balance-type
-       Balance assertions generated by assigning to balanceN are of the simple
-       =  type  by  default, which is a single-commodity, subaccount-excluding
-       assertion.  You may find the subaccount-including variants more useful,
-       eg if you have created some virtual subaccounts  of  checking  to  help
-       with  budgeting.  You can select a different type of assertion with the
-       balance-type rule:
-
-              # balance assertions will consider all commodities and all subaccounts
-              balance-type ==*
-
-       Here are the balance assertion types for quick reference:
-
-              =    single commodity, exclude subaccounts
-              =*   single commodity, include subaccounts
-              ==   multi commodity,  exclude subaccounts
-              ==*  multi commodity,  include subaccounts
-
-   include
-              include RULESFILE
-
-       This includes the contents of another CSV rules  file  at  this  point.
-       RULESFILE  is  an  absolute file path or a path relative to the current
-       file's directory.  This can be useful for sharing common rules  between
-       several rules files, eg:
-
-              # someaccount.csv.rules
-
-              ## someaccount-specific rules
-              fields   date,description,amount
-              account1 assets:someaccount
-              account2 expenses:misc
-
-              ## common rules
-              include categorisation.rules
-
-   Working with CSV
-       Some tips:
-
-   Rapid feedback
-       It's  a  good idea to get rapid feedback while creating/troubleshooting
-       CSV rules.  Here's a good way, using entr from eradman.com/entrproject:
-
-              $ ls foo.csv* | entr bash -c 'echo ----; hledger -f foo.csv print desc:SOMEDESC'
-
-       A desc: query (eg) is used to select just one, or a  few,  transactions
-       of  interest.   "bash  -c"  is used to run multiple commands, so we can
-       echo a separator each time the command re-runs,  making  it  easier  to
-       read the output.
-
-   Valid CSV
-       Note  that  hledger  will only accept valid CSV conforming to RFC 4180,
-       and equivalent SSV and TSV formats (like RFC 4180 but with semicolon or
-       tab as separators).  This means, eg:
-
-       o Values may be enclosed in double quotes, or not.  Enclosing in single
-         quotes is not allowed.  (Eg 'A','B' is rejected.)
-
-       o When values are enclosed in double quotes, spaces outside the  quotes
-         are not allowed.  (Eg "A", "B" is rejected.)
-
-       o When  values  are not enclosed in quotes, they may not contain double
-         quotes.  (Eg A"A, B is rejected.)
-
-       If your CSV/SSV/TSV is not valid in this sense, you'll need  to  trans-
-       form  it before reading with hledger.  Try using sed, or a more permis-
-       sive CSV parser like python's csv lib.
-
-   File Extension
-       To help hledger choose the CSV file reader and  show  the  right  error
-       messages  (and  choose the right field separator character by default),
-       it's best if CSV/SSV/TSV files are named with  a  .csv,  .ssv  or  .tsv
-       filename extension.  (More about this at Data formats.)
-
-       When  reading  files with the "wrong" extension, you can ensure the CSV
-       reader (and the default field separator) by  prefixing  the  file  path
-       with csv:, ssv: or tsv:: Eg:
-
-              $ hledger -f ssv:foo.dat print
-
-       You can also override the default field separator with a separator rule
-       if needed.
-
-   Reading CSV from standard input
-       You'll  need  the  file format prefix when reading CSV from stdin also,
-       since hledger assumes journal format by default.  Eg:
-
-              $ cat foo.dat | hledger -f ssv:- print
-
-   Reading multiple CSV files
-       If you use multiple -f options to read  multiple  CSV  files  at  once,
-       hledger  will  look for a correspondingly-named rules file for each CSV
-       file.  But if you specify a rules file with --rules,  that  rules  file
-       will be used for all the CSV files.
-
-   Reading files specified by rule
-       Instead of specifying a CSV file in the command line, you can specify a
-       rules  file,  as in hledger -f foo.csv.rules CMD.  By default this will
-       read data from foo.csv in the same directory, but you can add a  source
-       rule  to  specify  a  different  data file, perhaps located in your web
-       browser's download directory.
-
-       This feature was added in hledger 1.30, so you won't see it in most CSV
-       rules examples.  But it helps remove some of the busywork  of  managing
-       CSV downloads.  Most of your financial institutions's default CSV file-
-       names  are  different  and can be recognised by a glob pattern.  So you
-       can put a rule like source  Checking1*.csv  in  foo-checking.csv.rules,
-       and then periodically follow a workflow like:
-
-       1. Download CSV from Foo's website, using your browser's defaults
-
-       2. Run hledger import foo-checking.csv.rules to import any new transac-
-          tions
-
-       After  import,  you can: discard the CSV, or leave it where it is for a
-       while, or move it into your archives, as you prefer.  If you  do  noth-
-       ing,  next  time your browser will save something like Checking1-2.csv,
-       and hledger will use that because of the * wild card and because it  is
-       the most recent.
-
-   Valid transactions
-       After reading a CSV file, hledger post-processes and validates the gen-
-       erated journal entries as it would for a journal file - balancing them,
-       applying  balance  assignments,  and canonicalising amount styles.  Any
-       errors at this stage will be reported in the usual way, displaying  the
-       problem entry.
-
-       There is one exception: balance assertions, if you have generated them,
-       will  not  be checked, since normally these will work only when the CSV
-       data is part of the main journal.  If you do need to check balance  as-
-       sertions generated from CSV right away, pipe into another hledger:
-
-              $ hledger -f file.csv print | hledger -f- print
-
-   Deduplicating, importing
-       When  you  download a CSV file periodically, eg to get your latest bank
-       transactions, the new file may overlap with  the  old  one,  containing
-       some of the same records.
-
-       The import command will (a) detect the new transactions, and (b) append
-       just those transactions to your main journal.  It is idempotent, so you
-       don't  have to remember how many times you ran it or with which version
-       of the CSV.  (It keeps state in a hidden .latest.FILE.csv file.)   This
-       is the easiest way to import CSV data.  Eg:
-
-              # download the latest CSV files, then run this command.
-              # Note, no -f flags needed here.
-              $ hledger import *.csv [--dry]
-
-       This  method  works  for  most CSV files.  (Where records have a stable
-       chronological order, and new records appear only at the new end.)
-
-       A number of other tools and workflows, hledger-specific and  otherwise,
-       exist for converting, deduplicating, classifying and managing CSV data.
-       See:
-
-       o https://hledger.org/cookbook.html#setups-and-workflows
-
-       o https://plaintextaccounting.org -> data import/conversion
-
-   Setting amounts
-       Continuing  from amount field above, here are more tips for amount-set-
-       ting:
-
-       1. If the amount is in a single CSV field:
-           a. If its sign indicates direction of flow:
-           Assign it to amountN, to set the Nth posting's amount.  N  is  usu-
-           ally 1 or 2 but can go up to 99.
-
-           b. If another field indicates direction of flow:
-           Use  one  or  more  conditional rules to set the appropriate amount
-           sign.  Eg:
-
-                  # assume a withdrawal unless Type contains "deposit":
-                  amount1  -%Amount
-                  if %Type deposit
-                    amount1  %Amount
-
-       2. If the amount is in two CSV fields (such as Debit and Credit, or  In
-          and Out):
-           a. If both fields are unsigned:
-           Assign  one  field  to  amountN-in  and  the  other to amountN-out.
-           hledger will automatically negate the "out"  field,  and  will  use
-           whichever field value is non-zero as posting N's amount.
-
-           b. If either field is signed:
-           You  will  probably  need to override hledger's sign for one or the
-           other field, as in the following example:
-
-                  # Negate the -out value, but only if it is not empty:
-                  fields date, description, amount1-in, amount1-out
-                  if %amount1-out [1-9]
-                   amount1-out -%amount1-out
-
-           c. If both fields can contain a non-zero  value  (or  both  can  be
-              empty):
-           The   -in/-out   rules   normally   choose   the   value  which  is
-           non-zero/non-empty.  Some value pairs can be ambiguous, such  as  1
-           and none.  For such cases, use conditional rules to help select the
-           amount.   Eg,  to  handle the above you could select the value con-
-           taining non-zero digits:
-
-                  fields date, description, in, out
-                  if %in [1-9]
-                   amount1 %in
-                  if %out [1-9]
-                   amount1 %out
-
-       3. If you want posting 2's amount converted to cost:
-       Use the unnumbered amount (or amount-in and amount-out) syntax.
-
-       4. If the CSV has only balance amounts, not transaction amounts:
-       Assign to balanceN, to set a balance assignment  on  the  Nth  posting,
-       causing  the  posting's amount to be calculated automatically.  balance
-       with no number is equivalent to balance1.  In this situation hledger is
-       more likely to guess the wrong default account name, so you may need to
-       set that explicitly.
-
-   Amount signs
-       There is some special handling making it easier to parse and to reverse
-       amount signs.  (This only works for whole amounts, not for cost amounts
-       such as COST in amount1  AMT @ COST):
-
-       o If an amount value begins with a plus sign:
-       that will be removed: +AMT becomes AMT
-
-       o If an amount value is parenthesised:
-       it will be de-parenthesised and sign-flipped: (AMT) becomes -AMT
-
-       o If an amount value has two minus signs (or two sets  of  parentheses,
-         or a minus sign and parentheses):
-       they cancel out and will be removed: --AMT or -(AMT) becomes AMT
-
-       o If  an  amount value contains just a sign (or just a set of parenthe-
-         ses):
-       that is removed, making it an empty value.  "+" or "-" or "()"  becomes
-       "".
-
-       It's  not  possible (without preprocessing the CSV) to set an amount to
-       its absolute value, ie discard its sign.
-
-   Setting currency/commodity
-       If the currency/commodity  symbol  is  included  in  the  CSV's  amount
-       field(s):
-
-              2023-01-01,foo,$123.00
-
-       you don't have to do anything special for the commodity symbol, it will
-       be assigned as part of the amount.  Eg:
-
-              fields date,description,amount
-
-              2023-01-01 foo
-                  expenses:unknown         $123.00
-                  income:unknown          $-123.00
-
-       If the currency is provided as a separate CSV field:
-
-              2023-01-01,foo,USD,123.00
-
-       You can assign that to the currency pseudo-field, which has the special
-       effect  of prepending itself to every amount in the transaction (on the
-       left, with no separating space):
-
-              fields date,description,currency,amount
-
-              2023-01-01 foo
-                  expenses:unknown       USD123.00
-                  income:unknown        USD-123.00
-
-       Or, you can use a field assignment to construct  the  amount  yourself,
-       with more control.  Eg to put the symbol on the right, and separated by
-       a space:
-
-              fields date,description,cur,amt
-              amount %amt %cur
-
-              2023-01-01 foo
-                  expenses:unknown        123.00 USD
-                  income:unknown         -123.00 USD
-
-       Note  we  used a temporary field name (cur) that is not currency - that
-       would trigger the prepending effect, which we don't want here.
-
-   Amount decimal places
-       When you are reading CSV data,  eg  with  a  command  like  hledger  -f
-       foo.csv  print,  hledger  will infer each commodity's decimal precision
-       (and other commodity display styles) from the amounts -  much  as  when
-       reading a journal file without commodity directives (see the link).
-
-       Note,  the  commodity  styles  are not inferred from the numbers in the
-       original CSV data; rather, they are inferred from the amounts generated
-       by the CSV rules.
-
-       When you are importing CSV data with the import command, eg hledger im-
-       port foo.csv, there's another step: import tries to make  the  new  en-
-       tries  conform to the journal's existing styles.  So for each commodity
-       - let's say it's EUR - import will choose:
-
-       1. the style declared for EUR by a commodity directive in the journal
-
-       2. otherwise, the style inferred from EUR amounts in the journal
-
-       3. otherwise, the style inferred from EUR amounts generated by the  CSV
-          rules.
-
-       TLDR:  if  import  is not generating the precisions or styles you want,
-       add a commodity directive to specify them.
-
-   Referencing other fields
-       In field assignments, you can interpolate only CSV fields, not  hledger
-       fields.   In  the example below, there's both a CSV field and a hledger
-       field named amount1, but %amount1 always means the CSV field,  not  the
-       hledger field:
-
-              # Name the third CSV field "amount1"
-              fields date,description,amount1
-
-              # Set hledger's amount1 to the CSV amount1 field followed by USD
-              amount1 %amount1 USD
-
-              # Set comment to the CSV amount1 (not the amount1 assigned above)
-              comment %amount1
-
-       Here,  since there's no CSV amount1 field, %amount1 will produce a lit-
-       eral "amount1":
-
-              fields date,description,csvamount
-              amount1 %csvamount USD
-              # Can't interpolate amount1 here
-              comment %amount1
-
-       When there are multiple field assignments to the  same  hledger  field,
-       only the last one takes effect.  Here, comment's value will be be B, or
-       C if "something" is matched, but never A:
-
-              comment A
-              comment B
-              if something
-               comment C
-
-   How CSV rules are evaluated
-       Here's  how  to  think of CSV rules being evaluated (if you really need
-       to).  First,
-
-       o include - all includes are inlined, from top to bottom, depth  first.
-         (At  each  include  point the file is inlined and scanned for further
-         includes, recursively, before proceeding.)
-
-       Then "global" rules are evaluated, top to bottom.  If  a  rule  is  re-
-       peated, the last one wins:
-
-       o skip (at top level)
-
-       o date-format
-
-       o newest-first
-
-       o fields - names the CSV fields, optionally sets up initial assignments
-         to hledger fields
-
-       Then for each CSV record in turn:
-
-       o test  all if blocks.  If any of them contain a end rule, skip all re-
-         maining CSV records.  Otherwise if any of them contain a  skip  rule,
-         skip  that  many  CSV  records.   If  there are multiple matched skip
-         rules, the first one wins.
-
-       o collect all field assignments at top level and in matched if  blocks.
-         When  there  are multiple assignments for a field, keep only the last
-         one.
-
-       o compute a value for each hledger field - either the one that was  as-
-         signed to it (and interpolate the %CSVFIELD references), or a default
-
-       o generate a hledger transaction (journal entry) from these values.
-
-       This  is all part of the CSV reader, one of several readers hledger can
-       use to parse input files.  When all files have been read  successfully,
-       the  transactions  are passed as input to whichever hledger command the
-       user specified.
-
-   Well factored rules
-       Some things than can help reduce duplication and  complexity  in  rules
-       files:
-
-       o Extracting  common  rules  usable with multiple CSV files into a com-
-         mon.rules, and adding include common.rules to each CSV's rules file.
-
-       o Splitting if blocks into smaller if blocks, extracting the frequently
-         used parts.
-
-   CSV rules examples
-   Bank of Ireland
-       Here's a CSV with two amount fields (Debit and Credit), and  a  balance
-       field,  which we can use to add balance assertions, which is not neces-
-       sary but provides extra error checking:
-
-              Date,Details,Debit,Credit,Balance
-              07/12/2012,LODGMENT       529898,,10.0,131.21
-              07/12/2012,PAYMENT,5,,126
-
-              # bankofireland-checking.csv.rules
-
-              # skip the header line
-              skip
-
-              # name the csv fields, and assign some of them as journal entry fields
-              fields  date, description, amount-out, amount-in, balance
-
-              # We generate balance assertions by assigning to "balance"
-              # above, but you may sometimes need to remove these because:
-              #
-              # - the CSV balance differs from the true balance,
-              #   by up to 0.0000000000005 in my experience
-              #
-              # - it is sometimes calculated based on non-chronological ordering,
-              #   eg when multiple transactions clear on the same day
-
-              # date is in UK/Ireland format
-              date-format  %d/%m/%Y
-
-              # set the currency
-              currency  EUR
-
-              # set the base account for all txns
-              account1  assets:bank:boi:checking
-
-              $ hledger -f bankofireland-checking.csv print
-              2012-12-07 LODGMENT       529898
-                  assets:bank:boi:checking         EUR10.0 = EUR131.2
-                  income:unknown                  EUR-10.0
-
-              2012-12-07 PAYMENT
-                  assets:bank:boi:checking         EUR-5.0 = EUR126.0
-                  expenses:unknown                  EUR5.0
-
-       The balance assertions don't raise an error above, because we're  read-
-       ing  directly  from  CSV, but they will be checked if these entries are
-       imported into a journal file.
-
-   Coinbase
-       A simple example with some  CSV  from  Coinbase.   The  spot  price  is
-       recorded  using  cost  notation.   The  legacy amount field name conve-
-       niently sets amount 2 (posting 2's amount) to the total cost.
-
-              # Timestamp,Transaction Type,Asset,Quantity Transacted,Spot Price Currency,Spot Price at Transaction,Subtotal,Total (inclusive of fees and/or spread),Fees and/or Spread,Notes
-              # 2021-12-30T06:57:59Z,Receive,USDC,100,GBP,0.740000,"","","","Received 100.00 USDC from an external account"
-
-              # coinbase.csv.rules
-              skip         1
-              fields       Timestamp,Transaction_Type,Asset,Quantity_Transacted,Spot_Price_Currency,Spot_Price_at_Transaction,Subtotal,Total,Fees_Spread,Notes
-              date         %Timestamp
-              date-format  %Y-%m-%dT%T%Z
-              description  %Notes
-              account1     assets:coinbase:cc
-              amount       %Quantity_Transacted %Asset @ %Spot_Price_at_Transaction %Spot_Price_Currency
-
-              $ hledger print -f coinbase.csv
-              2021-12-30 Received 100.00 USDC from an external account
-                  assets:coinbase:cc    100 USDC @ 0.740000 GBP
-                  income:unknown                 -74.000000 GBP
-
-   Amazon
-       Here we convert amazon.com order history, and use an if block to gener-
-       ate a third posting if there's a fee.  (In practice you'd probably  get
-       this data from your bank instead, but it's an example.)
-
-              "Date","Type","To/From","Name","Status","Amount","Fees","Transaction ID"
-              "Jul 29, 2012","Payment","To","Foo.","Completed","$20.00","$0.00","16000000000000DGLNJPI1P9B8DKPVHL"
-              "Jul 30, 2012","Payment","To","Adapteva, Inc.","Completed","$25.00","$1.00","17LA58JSKRD4HDGLNJPI1P9B8DKPVHL"
-
-              # amazon-orders.csv.rules
-
-              # skip one header line
-              skip 1
-
-              # name the csv fields, and assign the transaction's date, amount and code.
-              # Avoided the "status" and "amount" hledger field names to prevent confusion.
-              fields date, _, toorfrom, name, amzstatus, amzamount, fees, code
-
-              # how to parse the date
-              date-format %b %-d, %Y
-
-              # combine two fields to make the description
-              description %toorfrom %name
-
-              # save the status as a tag
-              comment     status:%amzstatus
-
-              # set the base account for all transactions
-              account1    assets:amazon
-              # leave amount1 blank so it can balance the other(s).
-              # I'm assuming amzamount excludes the fees, don't remember
-
-              # set a generic account2
-              account2    expenses:misc
-              amount2     %amzamount
-              # and maybe refine it further:
-              #include categorisation.rules
-
-              # add a third posting for fees, but only if they are non-zero.
-              if %fees [1-9]
-               account3    expenses:fees
-               amount3     %fees
-
-              $ hledger -f amazon-orders.csv print
-              2012-07-29 (16000000000000DGLNJPI1P9B8DKPVHL) To Foo.  ; status:Completed
-                  assets:amazon
-                  expenses:misc          $20.00
-
-              2012-07-30 (17LA58JSKRD4HDGLNJPI1P9B8DKPVHL) To Adapteva, Inc.  ; status:Completed
-                  assets:amazon
-                  expenses:misc          $25.00
-                  expenses:fees           $1.00
-
-   Paypal
-       Here's  a  real-world rules file for (customised) Paypal CSV, with some
-       Paypal-specific rules, and a second rules file included:
-
-              "Date","Time","TimeZone","Name","Type","Status","Currency","Gross","Fee","Net","From Email Address","To Email Address","Transaction ID","Item Title","Item ID","Reference Txn ID","Receipt ID","Balance","Note"
-              "10/01/2019","03:46:20","PDT","Calm Radio","Subscription Payment","Completed","USD","-6.99","0.00","-6.99","simon@joyful.com","memberships@calmradio.com","60P57143A8206782E","MONTHLY - $1 for the first 2 Months: Me - Order 99309. Item total: $1.00 USD first 2 months, then $6.99 / Month","","I-R8YLY094FJYR","","-6.99",""
-              "10/01/2019","03:46:20","PDT","","Bank Deposit to PP Account ","Pending","USD","6.99","0.00","6.99","","simon@joyful.com","0TU1544T080463733","","","60P57143A8206782E","","0.00",""
-              "10/01/2019","08:57:01","PDT","Patreon","PreApproved Payment Bill User Payment","Completed","USD","-7.00","0.00","-7.00","simon@joyful.com","support@patreon.com","2722394R5F586712G","Patreon* Membership","","B-0PG93074E7M86381M","","-7.00",""
-              "10/01/2019","08:57:01","PDT","","Bank Deposit to PP Account ","Pending","USD","7.00","0.00","7.00","","simon@joyful.com","71854087RG994194F","Patreon* Membership","","2722394R5F586712G","","0.00",""
-              "10/19/2019","03:02:12","PDT","Wikimedia Foundation, Inc.","Subscription Payment","Completed","USD","-2.00","0.00","-2.00","simon@joyful.com","tle@wikimedia.org","K9U43044RY432050M","Monthly donation to the Wikimedia Foundation","","I-R5C3YUS3285L","","-2.00",""
-              "10/19/2019","03:02:12","PDT","","Bank Deposit to PP Account ","Pending","USD","2.00","0.00","2.00","","simon@joyful.com","3XJ107139A851061F","","","K9U43044RY432050M","","0.00",""
-              "10/22/2019","05:07:06","PDT","Noble Benefactor","Subscription Payment","Completed","USD","10.00","-0.59","9.41","noble@bene.fac.tor","simon@joyful.com","6L8L1662YP1334033","Joyful Systems","","I-KC9VBGY2GWDB","","9.41",""
-
-              # paypal-custom.csv.rules
-
-              # Tips:
-              # Export from Activity -> Statements -> Custom -> Activity download
-              # Suggested transaction type: "Balance affecting"
-              # Paypal's default fields in 2018 were:
-              # "Date","Time","TimeZone","Name","Type","Status","Currency","Gross","Fee","Net","From Email Address","To Email Address","Transaction ID","Shipping Address","Address Status","Item Title","Item ID","Shipping and Handling Amount","Insurance Amount","Sales Tax","Option 1 Name","Option 1 Value","Option 2 Name","Option 2 Value","Reference Txn ID","Invoice Number","Custom Number","Quantity","Receipt ID","Balance","Address Line 1","Address Line 2/District/Neighborhood","Town/City","State/Province/Region/County/Territory/Prefecture/Republic","Zip/Postal Code","Country","Contact Phone Number","Subject","Note","Country Code","Balance Impact"
-              # This rules file assumes the following more detailed fields, configured in "Customize report fields":
-              # "Date","Time","TimeZone","Name","Type","Status","Currency","Gross","Fee","Net","From Email Address","To Email Address","Transaction ID","Item Title","Item ID","Reference Txn ID","Receipt ID","Balance","Note"
-
-              fields date, time, timezone, description_, type, status_, currency, grossamount, feeamount, netamount, fromemail, toemail, code, itemtitle, itemid, referencetxnid, receiptid, balance, note
-
-              skip  1
-
-              date-format  %-m/%-d/%Y
-
-              # ignore some paypal events
-              if
-              In Progress
-              Temporary Hold
-              Update to
-               skip
-
-              # add more fields to the description
-              description %description_ %itemtitle
-
-              # save some other fields as tags
-              comment  itemid:%itemid, fromemail:%fromemail, toemail:%toemail, time:%time, type:%type, status:%status_
-
-              # convert to short currency symbols
-              if %currency USD
-               currency $
-              if %currency EUR
-               currency E
-              if %currency GBP
-               currency P
-
-              # generate postings
-
-              # the first posting will be the money leaving/entering my paypal account
-              # (negative means leaving my account, in all amount fields)
-              account1 assets:online:paypal
-              amount1  %netamount
-
-              # the second posting will be money sent to/received from other party
-              # (account2 is set below)
-              amount2  -%grossamount
-
-              # if there's a fee, add a third posting for the money taken by paypal.
-              if %feeamount [1-9]
-               account3 expenses:banking:paypal
-               amount3  -%feeamount
-               comment3 business:
-
-              # choose an account for the second posting
-
-              # override the default account names:
-              # if the amount is positive, it's income (a debit)
-              if %grossamount ^[^-]
-               account2 income:unknown
-              # if negative, it's an expense (a credit)
-              if %grossamount ^-
-               account2 expenses:unknown
-
-              # apply common rules for setting account2 & other tweaks
-              include common.rules
-
-              # apply some overrides specific to this csv
-
-              # Transfers from/to bank. These are usually marked Pending,
-              # which can be disregarded in this case.
-              if
-              Bank Account
-              Bank Deposit to PP Account
-               description %type for %referencetxnid %itemtitle
-               account2 assets:bank:wf:pchecking
-               account1 assets:online:paypal
-
-              # Currency conversions
-              if Currency Conversion
-               account2 equity:currency conversion
-
-              # common.rules
-
-              if
-              darcs
-              noble benefactor
-               account2 revenues:foss donations:darcshub
-               comment2 business:
-
-              if
-              Calm Radio
-               account2 expenses:online:apps
-
-              if
-              electronic frontier foundation
-              Patreon
-              wikimedia
-              Advent of Code
-               account2 expenses:dues
-
-              if Google
-               account2 expenses:online:apps
-               description google | music
-
-              $ hledger -f paypal-custom.csv  print
-              2019-10-01 (60P57143A8206782E) Calm Radio MONTHLY - $1 for the first 2 Months: Me - Order 99309. Item total: $1.00 USD first 2 months, then $6.99 / Month  ; itemid:, fromemail:simon@joyful.com, toemail:memberships@calmradio.com, time:03:46:20, type:Subscription Payment, status:Completed
-                  assets:online:paypal          $-6.99 = $-6.99
-                  expenses:online:apps           $6.99
-
-              2019-10-01 (0TU1544T080463733) Bank Deposit to PP Account for 60P57143A8206782E  ; itemid:, fromemail:, toemail:simon@joyful.com, time:03:46:20, type:Bank Deposit to PP Account, status:Pending
-                  assets:online:paypal               $6.99 = $0.00
-                  assets:bank:wf:pchecking          $-6.99
-
-              2019-10-01 (2722394R5F586712G) Patreon Patreon* Membership  ; itemid:, fromemail:simon@joyful.com, toemail:support@patreon.com, time:08:57:01, type:PreApproved Payment Bill User Payment, status:Completed
-                  assets:online:paypal          $-7.00 = $-7.00
-                  expenses:dues                  $7.00
-
-              2019-10-01 (71854087RG994194F) Bank Deposit to PP Account for 2722394R5F586712G Patreon* Membership  ; itemid:, fromemail:, toemail:simon@joyful.com, time:08:57:01, type:Bank Deposit to PP Account, status:Pending
-                  assets:online:paypal               $7.00 = $0.00
-                  assets:bank:wf:pchecking          $-7.00
-
-              2019-10-19 (K9U43044RY432050M) Wikimedia Foundation, Inc. Monthly donation to the Wikimedia Foundation  ; itemid:, fromemail:simon@joyful.com, toemail:tle@wikimedia.org, time:03:02:12, type:Subscription Payment, status:Completed
-                  assets:online:paypal             $-2.00 = $-2.00
-                  expenses:dues                     $2.00
-                  expenses:banking:paypal      ; business:
-
-              2019-10-19 (3XJ107139A851061F) Bank Deposit to PP Account for K9U43044RY432050M  ; itemid:, fromemail:, toemail:simon@joyful.com, time:03:02:12, type:Bank Deposit to PP Account, status:Pending
-                  assets:online:paypal               $2.00 = $0.00
-                  assets:bank:wf:pchecking          $-2.00
-
-              2019-10-22 (6L8L1662YP1334033) Noble Benefactor Joyful Systems  ; itemid:, fromemail:noble@bene.fac.tor, toemail:simon@joyful.com, time:05:07:06, type:Subscription Payment, status:Completed
-                  assets:online:paypal                       $9.41 = $9.41
-                  revenues:foss donations:darcshub         $-10.00  ; business:
-                  expenses:banking:paypal                    $0.59  ; business:
-
-Timeclock
-       The time logging format of timeclock.el, as read by hledger.
-
-       hledger can read time logs in timeclock format.  As with Ledger,  these
-       are  (a  subset  of)  timeclock.el's  format,  containing  clock-in and
-       clock-out entries as in the example below.  The date is a simple  date.
-       The  time  format  is HH:MM[:SS][+-ZZZZ].  Seconds and timezone are op-
-       tional.  The timezone, if present, must be four digits and  is  ignored
-       (currently  the time is always interpreted as a local time).  Lines be-
-       ginning with # or ; or *, and blank lines, are ignored.
-
-              i 2015/03/30 09:00:00 some account  optional description after 2 spaces ; optional comment, tags:
-              o 2015/03/30 09:20:00
-              i 2015/03/31 22:21:45 another:account
-              o 2015/04/01 02:00:34
-
-       hledger treats each clock-in/clock-out pair as  a  transaction  posting
-       some  number of hours to an account.  Or if the session spans more than
-       one day, it is split into several transactions, one for each day.   For
-       the above time log, hledger print generates these journal entries:
-
-              $ hledger -f t.timeclock print
-              2015-03-30 * optional description after 2 spaces   ; optional comment, tags:
-                  (some account)           0.33h
-
-              2015-03-31 * 22:21-23:59
-                  (another:account)           1.64h
-
-              2015-04-01 * 00:00-02:00
-                  (another:account)           2.01h
-
-       Here is a sample.timeclock to download and some queries to try:
-
-              $ hledger -f sample.timeclock balance                               # current time balances
-              $ hledger -f sample.timeclock register -p 2009/3                    # sessions in march 2009
-              $ hledger -f sample.timeclock register -p weekly --depth 1 --empty  # time summary by week
-
-       To generate time logs, ie to clock in and clock out, you could:
-
-       o use these shell aliases at the command line:
-
-                alias ti='echo i `date "+%Y-%m-%d %H:%M:%S"` $* >>$TIMELOG'
-                alias to='echo o `date "+%Y-%m-%d %H:%M:%S"` >>$TIMELOG'
-
-       o or Emacs's built-in timeclock.el, or the extended timeclock-x.el, and
-         perhaps the extras in ledgerutils.el
-
-       o or use the old ti and to scripts in the ledger 2.x repository.  These
-         rely  on  a "timeclock" executable which I think is just the ledger 2
-         executable renamed.
-
-Timedot
-       timedot format is hledger's human-friendly time logging  format.   Com-
-       pared  to  timeclock  format, it is more convenient for quick, approxi-
-       mate, and retroactive time logging, and more  human-readable  (you  can
-       see at a glance where time was spent).  A quick example:
-
-              2023-05-01
-              hom:errands          .... ....  ; two hours; the space is ignored
-              fos:hledger:timedot  ..         ; half an hour
-              per:admin:finance               ; no time spent yet
-
-       hledger reads this as a transaction on this day with three (unbalanced)
-       postings, where each dot represents "0.25".  No commodity symbol is as-
-       sumed, but we typically interpret it as hours.
-
-              $ hledger -f a.timedot print   # .timedot file extension (or timedot: prefix) is required
-              2023-05-01 *
-                  (hom:errands)                    2.00  ; two hours
-                  (fos:hledger:timedot)            0.50  ; half an hour
-                  (per:admin:finance)                 0
-
-       A timedot file contains a series of transactions (usually one per day).
-       Each  begins with a simple date (Y-M-D, Y/M/D, or Y.M.D), optionally be
-       followed on the same line by a transaction description, and/or a trans-
-       action comment following a semicolon.
-
-       After the date line are zero or more time postings, consisting of:
-
-       o An account name - any  hledger-style  account  name,  optionally  in-
-         dented.
-
-       o Two  or  more  spaces - required if there is an amount (as in journal
-         format).
-
-       o A timedot amount, which can be
-
-         o empty (representing zero)
-
-         o a number, optionally followed by a unit s, m, h, d, w,  mo,  or  y,
-           representing  a  precise  number  of  seconds, minutes, hours, days
-           weeks, months or years (hours is assumed by default), which will be
-           converted to hours according to 60s = 1m, 60m = 1h, 24h = 1d, 7d  =
-           1w, 30d = 1mo, 365d = 1y.
-
-         o one  or  more  dots  (period  characters),  each representing 0.25.
-           These are the dots in "timedot".  Spaces are  ignored  and  can  be
-           used for grouping/alignment.
-
-         o Added  in  1.32  one or more letters.  These are like dots but they
-           also generate a tag t: (short for "type") with the  letter  as  its
-           value,  and  a  separate posting for each of the values.  This pro-
-           vides a second dimension of  categorisation,  viewable  in  reports
-           with --pivot t.
-
-       o An  optional  comment  following a semicolon (a hledger-style posting
-         comment).
-
-       There is some flexibility to help with keeping time log data and  notes
-       in the same file:
-
-       o Blank lines and lines beginning with # or ; are ignored.
-
-       o After  the first date line, lines which do not contain a double space
-         are parsed as postings with zero amount.  (hledger's register reports
-         will show these if you add -E).
-
-       o Before the first date line, lines beginning with * (eg org  headings)
-         are  ignored.   And  from  the first date line onward, Emacs org mode
-         heading prefixes at the start of lines (one or more *'s followed by a
-         space) will be ignored.  This means the time log can also  be  a  org
-         outline.
-
-       Timedot files don't support directives like journal files.  So a common
-       pattern  is to have a main journal file (eg time.journal) that contains
-       any needed directives, and then  includes  the  timedot  file  (include
-       time.timedot).
-
-   Timedot examples
-       Numbers:
-
-              2016/2/3
-              inc:client1   4
-              fos:hledger   3h
-              biz:research  60m
-
-       Dots:
-
-              # on this day, 6h was spent on client work, 1.5h on haskell FOSS work, etc.
-              2016/2/1
-              inc:client1   .... .... .... .... .... ....
-              fos:haskell   .... ..
-              biz:research  .
-
-              2016/2/2
-              inc:client1   .... ....
-              biz:research  .
-
-              $ hledger -f a.timedot print date:2016/2/2
-              2016-02-02 *
-                  (inc:client1)          2.00
-
-              2016-02-02 *
-                  (biz:research)          0.25
-
-              $ hledger -f a.timedot bal --daily --tree
-              Balance changes in 2016-02-01-2016-02-03:
-
-                          ||  2016-02-01d  2016-02-02d  2016-02-03d
-              ============++========================================
-               biz        ||         0.25         0.25         1.00
-                 research ||         0.25         0.25         1.00
-               fos        ||         1.50            0         3.00
-                 haskell  ||         1.50            0            0
-                 hledger  ||            0            0         3.00
-               inc        ||         6.00         2.00         4.00
-                 client1  ||         6.00         2.00         4.00
-              ------------++----------------------------------------
-                          ||         7.75         2.25         8.00
-
-       Letters:
-
-              # Activity types:
-              #  c cleanup/catchup/repair
-              #  e enhancement
-              #  s support
-              #  l learning/research
-
-              2023-11-01
-              work:adm  ccecces
-
-              $ hledger -f a.timedot print
-              2023-11-01
-                  (work:adm)  1     ; t:c
-                  (work:adm)  0.5   ; t:e
-                  (work:adm)  0.25  ; t:s
-
-              $ hledger -f a.timedot bal
-                              1.75  work:adm
-              --------------------
-                              1.75
-
-              $ hledger -f a.timedot bal --pivot t
-                              1.00  c
-                              0.50  e
-                              0.25  s
-              --------------------
-                              1.75
-
-       Org:
-
-              * 2023 Work Diary
-              ** Q1
-              *** 2023-02-29
-              **** DONE
-              0700 yoga
-              **** UNPLANNED
-              **** BEGUN
-              hom:chores
-               cleaning  ...
-               water plants
-                outdoor - one full watering can
-                indoor - light watering
-              **** TODO
-              adm:planning: trip
-              *** LATER
-
-       Using . as account name separator:
-
-              2016/2/4
-              fos.hledger.timedot  4h
-              fos.ledger           ..
-
-              $ hledger -f a.timedot --alias '/\./=:' bal -t
-                              4.50  fos
-                              4.00    hledger:timedot
-                              0.50    ledger
-              --------------------
-                              4.50
-
-PART 3: REPORTING CONCEPTS
-Time periods
-   Report start & end date
-       Most  hledger  reports will by default show the full time period repre-
-       sented by the journal.  The report start  date  will  be  the  earliest
-       transaction or posting date, and the report end date will be the latest
-       transaction, posting, or market price date.
-
-       Often you will want to see a shorter period, such as the current month.
-       You  can specify a start and/or end date with the -b/--begin, -e/--end,
-       or -p/--period options, or a date:  query  argument,  described  below.
-       All of these accept the smart date syntax, also described below.
-
-       End dates are exclusive; specify the day after the last day you want to
-       see in the report.
-
-       When dates are specified by multiple options, the last (right-most) op-
-       tion  wins.   And when date: queries and date options are combined, the
-       report period will be their intersection.
-
-       Examples:
-
-       -b 2016/3/17
-              beginning on St.  Patrick's day 2016
-
-       -e 12/1
-              ending at the start of December 1st in the current year
-
-       -p 'this month'
-              during the current month
-
-       -p thismonth
-              same as above, spaces are optional
-
-       -b 2023
-              beginning on the first day of 2023
-
-       date:2023.. or date:2023-
-              same as above
-
-       -b 2024 -e 2025 -p '2000 to 2030' date:2020-01 date:2020 :
-       during January 2020 (the smallest common period, with the -p overriding
-       -b and -e)
-
-   Smart dates
-       In hledger's user interfaces (though not in the journal file), you  can
-       optionally  use  "smart  date" syntax.  Smart dates can be written with
-       english words, can be relative, and can have  parts  omitted.   Missing
-       parts  are  inferred as 1, when needed.  Smart dates can be interpreted
-       as dates or periods depending on context.
-
-       Examples:
-
-       2004-01-01, 2004/10/1, 2004.9.1, 20240504 :
-       Exact dates.  The year must have at least four digits, the  month  must
-       be  1-12,  the  day  must  be 1-31, the separator can be - or / or . or
-       nothing.
-
-       2004-10
-              start of month
-
-       2004   start of year
-
-       10/1 or oct or october
-              October 1st in current year
-
-       21     21st day in current month
-
-       yesterday, today, tomorrow
-              -1, 0, 1 days from today
-
-       last/this/next day/week/month/quarter/year
-              -1, 0, 1 periods from the current period
-
-       in n days/weeks/months/quarters/years
-              n periods from the current period
-
-       n days/weeks/months/quarters/years ahead
-              n periods from the current period
-
-       n days/weeks/months/quarters/years ago
-              -n periods from the current period
-
-       20181201
-              8 digit YYYYMMDD with valid year month and day
-
-       201812 6 digit YYYYMM with valid year and month
-
-       Dates with no separators are allowed but might give surprising  results
-       if mistyped:
-
-       o 20181301 (YYYYMMDD with an invalid month) is parsed as an eight-digit
-         year
-
-       o 20181232 (YYYYMMDD with an invalid day) gives a parse error
-
-       o 201801012  (a  valid  YYYYMMDD followed by additional digits) gives a
-         parse error
-
-       The meaning of relative dates depends on today's date.  If you need  to
-       test  or reproduce old reports, you can use the --today option to over-
-       ride that.  (Except for periodic transaction rules, which are  not  af-
-       fected by --today.)
-
-   Report intervals
-       A  report interval can be specified so that reports like register, bal-
-       ance or activity become multi-period, showing each subperiod as a sepa-
-       rate row or column.
-
-       The following standard  intervals  can  be  enabled  with  command-line
-       flags:
-
-       o -D/--daily
-
-       o -W/--weekly
-
-       o -M/--monthly
-
-       o -Q/--quarterly
-
-       o -Y/--yearly
-
-       More  complex  intervals  can be specified using -p/--period, described
-       below.
-
-   Date adjustments
-   Start date adjustment
-       If you let hledger infer a report's start date, it will adjust the date
-       to the previous natural boundary of the report interval, for convenient
-       periodic reports.  (If you don't want that, specify a start date.)
-
-       For example, if the journal's first transaction is on january 10th,
-
-       o hledger register (no report interval) will start the report on  janu-
-         ary 10th.
-
-       o hledger  register  --monthly  will  start  the report on the previous
-         month boundary, january 1st.
-
-       o hledger register --monthly --begin 1/5 will start the report on janu-
-         ary 5th [1].
-
-       Also if you are generating transactions or budget goals  with  periodic
-       transaction  rules,  their  start date may be adjusted in a similar way
-       (in certain situations).
-
-   End date adjustment
-       A report's end date is always adjusted to include a whole number of in-
-       tervals, so that the last subperiod has the same length as the others.
-
-       For example, if the journal's last transaction is on february 20th,
-
-       o hledger register will end the report on february 20th.
-
-       o hledger register --monthly will end the report at the end  of  febru-
-         ary.
-
-       o hledger register --monthly --end 2/14 also will end the report at the
-         end of february.
-
-       o hledger register --monthly --begin 1/5 --end 2/14 will end the report
-         on march 4th [1].
-
-       [1] Since hledger 1.29.
-
-   Period headings
-       With  non-standard  subperiods,  hledger will show "STARTDATE..ENDDATE"
-       headings.  With standard subperiods (ie, starting on a natural interval
-       boundary), you'll see more compact headings, which are usually  prefer-
-       able.  (Though month names will be in english, currently.)
-
-       So  if  you  are specifying a start date and you want compact headings:
-       choose a start of year for yearly reports, a start of quarter for quar-
-       terly reports, a start of month for monthly reports,  etc.   (Remember,
-       you  can  write eg -b 2024 or 1/1 as a shortcut for a start of year, or
-       2024-04 or 202404 or Apr for a start of month or quarter.)
-
-       For weekly reports, choose a date that's a Monday.  (You can  try  dif-
-       ferent  dates until you see the short headings, or write eg -b '3 weeks
-       ago'.)
-
-   Period expressions
-       The -p/--period option specifies a period expression, which is  a  com-
-       pact way of expressing a start date, end date, and/or report interval.
-
-       Here's  a  period  expression with a start and end date (specifying the
-       first quarter of 2009):
-
-       -p "from 2009/1/1 to 2009/4/1"
-
-       Several keywords like "from" and "to" are  supported  for  readability;
-       these  are  optional.   "to"  can  also be written as ".." or "-".  The
-       spaces are also optional, as long as you don't run two dates  together.
-       So the following are equivalent to the above:
-
-       -p "2009/1/1 2009/4/1"
-       -p2009/1/1to2009/4/1
-       -p2009/1/1..2009/4/1
-
-       Dates  are  smart dates, so if the current year is 2009, these are also
-       equivalent to the above:
-
-       -p "1/1 4/1"
-       -p "jan-apr"
-       -p "this year to 4/1"
-
-       If you specify only one date, the missing start or end date will be the
-       earliest or latest transaction date in the journal:
-
-       -p "from 2009/1/1"   everything  after  january
-                            1, 2009
-       -p "since 2009/1"    the  same, since is a syn-
-                            onym
-       -p "from 2009"       the same
-       -p "to 2009"         everything before  january
-                            1, 2009
-
-       You can also specify a period by writing a single partial or full date:
-
-       -p "2009"        the year 2009; equivalent to "2009/1/1 to 2010/1/1"
-       -p "2009/1"      the  month  of january 2009; equivalent to "2009/1/1 to
-                        2009/2/1"
-       -p "2009/1/1"    the first day  of  2009;  equivalent  to  "2009/1/1  to
-                        2009/1/2"
-
-       or by using the "Q" quarter-year syntax (case insensitive):
-
-       -p "2009Q1"       first  quarter  of  2009,  equivalent  to  "2009/1/1 to
-                         2009/4/1"
-       -p "q4"           fourth quarter of the current year
-
-   Period expressions with a report interval
-       A period expression can also begin with a  report  interval,  separated
-       from the start/end dates (if any) by a space or the word in:
-
-       -p "weekly from 2009/1/1 to 2009/4/1"
-       -p "monthly in 2008"
-       -p "quarterly"
-
-   More complex report intervals
-       Some more complex intervals can be specified within period expressions,
-       such as:
-
-       o biweekly (every two weeks)
-
-       o fortnightly
-
-       o bimonthly (every two months)
-
-       o every day|week|month|quarter|year
-
-       o every N days|weeks|months|quarters|years
-
-       Weekly on a custom day:
-
-       o every  Nth  day of week (th, nd, rd, or st are all accepted after the
-         number)
-
-       o every WEEKDAYNAME (full or three-letter english  weekday  name,  case
-         insensitive)
-
-       Monthly on a custom day:
-
-       o every  Nth  day [of month] (31st day will be adjusted to each month's
-         last day)
-
-       o every Nth WEEKDAYNAME [of month]
-
-       Yearly on a custom month and day:
-
-       o every MM/DD [of year] (month number and day of month number)
-
-       o every MONTHNAME DDth [of year] (full or  three-letter  english  month
-         name, case insensitive, and day of month number)
-
-       o every DDth MONTHNAME [of year] (equivalent to the above)
-
-       Examples:
-
-       -p "bimonthly from 2008"
-       -p "every 2 weeks"
-       -p  "every  5  months  from
-       2009/03"
-       -p "every 2nd day of week"    periods will go from Tue to Tue
-       -p "every Tue"                same
-       -p "every 15th day"           period boundaries will be on 15th  of  each
-                                     month
-       -p "every 2nd Monday"         period  boundaries will be on second Monday
-                                     of each month
-       -p "every 11/05"              yearly periods with boundaries  on  5th  of
-                                     November
-       -p "every 5th November"       same
-       -p "every Nov 5th"            same
-
-       Show  historical balances at end of the 15th day of each month (N is an
-       end date, exclusive as always):
-
-              $ hledger balance -H -p "every 16th day"
-
-       Group postings from the start of wednesday  to  end  of  the  following
-       tuesday (N is both (inclusive) start date and (exclusive) end date):
-
-              $ hledger register checking -p "every 3rd day of week"
-
-   Multiple weekday intervals
-       This special form is also supported:
-
-       o every WEEKDAYNAME,WEEKDAYNAME,... (full or three-letter english week-
-         day names, case insensitive)
-
-       Also,  weekday and weekendday are shorthand for mon,tue,wed,thu,fri and
-       sat,sun.
-
-       This is mainly intended for use with --forecast, to  generate  periodic
-       transactions on arbitrary days of the week.  It may be less useful with
-       -p, since it divides each week into subperiods of unequal length, which
-       is unusual.  (Related: #1632)
-
-       Examples:
-
-       -p          "every   dates  will  be  Mon,  Wed,  Fri;  periods  will  be
-       mon,wed,fri"         Mon-Tue, Wed-Thu, Fri-Sun
-       -p "every weekday"   dates  will be Mon, Tue, Wed, Thu, Fri; periods will
-                            be Mon, Tue, Wed, Thu, Fri-Sun
-       -p "every weekend-   dates will be Sat, Sun; periods will be Sat, Sun-Fri
-       day"
-
-Depth
-       With the --depth NUM option (short form: -NUM), reports will  show  ac-
-       counts  only  to  the  specified depth, hiding deeper subaccounts.  Use
-       this when you want a summary with less detail.  This flag has the  same
-       effect as a depth: query argument: depth:2, --depth=2 or -2 are equiva-
-       lent.
-
-       In  place  of  a single number which limits the depth for all accounts,
-       you can also provide separate depth limits for different accounts using
-       regular expressions (since 1.41).
-
-       For example, --depth assets=2 (or, equivalently:  depth:assets=2)  will
-       collapse  accounts  matching  the regular expression assets to depth 2.
-       So assets:bank:savings would be collapsed to assets:bank, while liabil-
-       ities:bank:credit card would not be affected.   This  can  be  combined
-       with  a  flat depth to collapse other accounts not matching the regular
-       expression,  so  --depth  assets=2  --depth  1   would   collapse   as-
-       sets:bank:savings  to  assets:bank  and liabilities:bank:credit card to
-       liabilities.
-
-       You can supply multiple depth arguments and they will all  be  applied,
-       so --depth assets=2 --depth liabilities=3 --depth 1 would collapse:
-
-       o accounts matching assets to depth 2,
-
-       o accounts matching liabilities to depth 3,
-
-       o all other accounts to depth 1.
-
-       If  an account is matched by more than one regular expression depth ar-
-       gument then the more specific one will used.  For example,  if  --depth
-       assets=1   --depth   assets:bank:savings=2   is   provided,   then  as-
-       sets:bank:savings will be collapsed to depth 2  rather  than  depth  1.
-       This  is  because assets:bank:savings matches at level 3 in the account
-       name, while assets matches at level 1.  The same would be true with the
-       argument --depth assets=1 --depth savings=2.
-
-Queries
-       One of hledger's strengths is being able to quickly report on a precise
-       subset of your data.  Most hledger commands accept query arguments,  to
-       restrict their scope.  Multiple query terms can be provided to build up
-       a more complex query.
-
-       o By  default,  a  query term is interpreted as a case-insensitive sub-
-         string pattern for matching account names:
-
-         car:fuel
-         dining groceries
-       o Patterns containing spaces or other special characters  must  be  en-
-         closed in single or double quotes:
-
-         'personal care'
-       o These  patterns are actually regular expressions, so you can add reg-
-         exp metacharacters for  more  precision  (see  "Regular  expressions"
-         above for details):
-
-         '^expenses\b'
-         'food$'
-         'fuel|repair'
-         'accounts (payable|receivable)'
-       o To match something other than account name, add one of the query type
-         prefixes described in "Query types" below:
-
-         date:202312-
-         status:
-         desc:amazon
-         cur:USD
-         cur:\\$
-         amt:'>0'
-       o Add a not: prefix to negate a term:
-
-         not:status:'*'
-         not:desc:'opening|closing'
-         not:cur:USD
-       o Terms  with  different types are AND-ed, terms with the same type are
-         OR-ed (mostly; see "Combining query  terms"  below).   The  following
-         query:
-
-         date:2022 desc:amazon desc:amzn
-
-         is interpreted as:
-
-         date  is  in  2022 AND ( transaction description contains "amazon" OR
-         "amzn" )
-
-   Query types
-       Here are the types of query term available.
-
-   acct: query
-       acct:REGEX, or just REGEX
-       Match account names containing this case  insensitive  regular  expres-
-       sion.
-       This  is the default query type, so we usually don't bother writing the
-       "acct:" prefix.
-
-   amt: query
-       amt:N, amt:'<N', amt:'<=N', amt:'>N', amt:'>=N'
-       Match postings with a single-commodity amount equal to, less  than,  or
-       greater  than  N. (Postings with multi-commodity amounts are not tested
-       and will always match.)  The comparison has two modes: if N is preceded
-       by a + or - sign (or is 0), the two signed numbers are compared.   Oth-
-       erwise,  the  absolute  magnitudes  are  compared, ignoring sign.  amt:
-       needs quotes to hide the less than/greater than sign from  the  command
-       line shell.
-
-   code: query
-       code:REGEX
-       Match by transaction code (eg check number).
-
-   cur: query
-       cur:REGEX
-       Match  postings  or  transactions  including  any  amounts  whose  cur-
-       rency/commodity  symbol  is  fully  matched  by  REGEX.   (Contrary  to
-       hledger's   usual   infix   matching.   To  do  infix  matching,  write
-       .*REGEX.*.)  Note, to match special characters which are regex-signifi-
-       cant, you need to escape them with \.  And  for  characters  which  are
-       significant  to  your shell you will usually need one more level of es-
-       caping.  Eg to match the dollar sign: cur:\\$ or cur:'\$'
-
-   desc: query
-       desc:REGEX
-       Match transaction descriptions.
-
-   date: query
-       date:PERIODEXPR
-       Match dates (or with the --date2  flag,  secondary  dates)  within  the
-       specified period.  PERIODEXPR is a period expression with no report in-
-       terval.  Examples:
-       date:2016, date:thismonth, date:2/1-2/15, date:2021-07-27..nextquarter.
-
-   date2: query
-       date2:PERIODEXPR
-       If  you  use  secondary  dates: this matches secondary dates within the
-       specified period.  It is not affected by the --date2 flag.
-
-   depth: query
-       depth:[REGEXP=]N
-       Match (or display, depending on command)  accounts  at  or  above  this
-       depth, optionally only for accounts matching a provided regular expres-
-       sion.  See Depth for detailed rules.
-
-   expr: query
-       expr:'QUERYEXPR'
-       expr  lets  you  write more complicated query expressions with AND, OR,
-       NOT, and parentheses.
-       Eg: expr:'date:lastmonth and not (food or rent)'
-       The expression should be enclosed in quotes.  See Combining query terms
-       below.
-
-   not: query
-       not:QUERYTERM
-       You can prepend not: to any other query term to negate the match.
-       Eg: not:equity, not:desc:apple
-       (Also, a trick: not:not:... can sometimes solve query  problems  conve-
-       niently..)
-
-   note: query
-       note:REGEX
-       Match transaction notes (the part of the description right of |, or the
-       whole description if there's no |).
-
-   payee: query
-       payee:REGEX
-       Match  transaction  payee/payer names (the part of the description left
-       of |, or the whole description if there's no |).
-
-   real: query
-       real:, real:0
-       Match real or virtual postings respectively.
-
-   status: query
-       status:, status:!, status:*
-       Match unmarked, pending, or cleared transactions respectively.
-
-   type: query
-       type:TYPECODES
-       Match by account type (see Declaring accounts > Account types).   TYPE-
-       CODES  is  one or more of the single-letter account type codes ALERXCV,
-       case insensitive.  Note type:A and type:E will also match their respec-
-       tive subtypes C (Cash) and V (Conversion).  Certain  kinds  of  account
-       alias  can  disrupt account types, see Rewriting accounts > Aliases and
-       account types.
-
-   tag: query
-       tag:NAMEREGEX[=VALREGEX]
-       Match by tag name, and optionally also by tag value.  Note:
-
-       o Both regular expressions do infix matching.  If you need  a  complete
-         match, use ^ and $.
-       Eg: tag:'^fullname$', tag:'^fullname$=^fullvalue$
-
-       o To match values, ignoring names, do tag:.=VALREGEX
-
-       o Accounts also inherit the tags of their parent accounts.
-
-       o Postings also inherit the tags of their account and their transaction
-         .
-
-       o Transactions also acquire the tags of their postings.
-
-   Combining query terms
-       When  given  multiple space-separated query terms, most commands select
-       things which match:
-
-       o any of the description terms AND
-
-       o any of the account terms AND
-
-       o any of the status terms AND
-
-       o all the other terms.
-
-       The print command is a little different, showing transactions which:
-
-       o match any of the description terms AND
-
-       o have any postings matching any of the positive account terms AND
-
-       o have no postings matching any of the negative account terms AND
-
-       o match all the other terms.
-
-       We also support more complex boolean queries  with  the  expr:  prefix.
-       This  allows  one  to  combine  query terms using and, or, not keywords
-       (case insensitive), and to group them by enclosing in parentheses.
-
-       Some examples:
-
-       o Exclude account names containing 'food':
-
-         expr:"not food" (not:food is equivalent)
-
-       o Match things which have 'cool' in the description and the 'A' tag:
-
-         expr:"desc:cool and tag:A" (expr:"desc:cool tag:A" is equivalent)
-
-       o Match things which either do not reference  the  'expenses:food'  ac-
-         count, or do have the 'A' tag:
-
-         expr:"not expenses:food or tag:A"
-
-       o Match  things  which  either do not reference the 'expenses:food' ac-
-         count, or which reference the 'expenses:drink' account and also  have
-         the 'A' tag:
-
-         expr:"expenses:food or (expenses:drink and tag:A)"
-
-       expr:  has  a  restriction: date: queries may not be used inside or ex-
-       pressions.  That would allow disjoint report periods or disjoint result
-       sets, with unclear semantics for our reports.
-
-   Queries and command options
-       Some queries can also be expressed as command-line options: depth:2  is
-       equivalent to --depth 2, date:2023 is equivalent to -p 2023, etc.  When
-       you  mix  command  options and query arguments, generally the resulting
-       query is their intersection.
-
-   Queries and account aliases
-       When account names are rewritten with  --alias  or  alias,  acct:  will
-       match either the old or the new account name.
-
-   Queries and valuation
-       When  amounts  are  converted to other commodities in cost or value re-
-       ports, cur: and amt: match the old commodity symbol and the old  amount
-       quantity, not the new ones.  (Except in hledger 1.22, #1625.)
-
-Pivoting
-       Normally,  hledger  groups  and  sums amounts within each account.  The
-       --pivot FIELD option substitutes some other transaction field  for  ac-
-       count  names,  causing amounts to be grouped and summed by that field's
-       value instead.  FIELD can be any of the transaction fields  acct,  sta-
-       tus,  code,  desc,  payee, note, or a tag name.  When pivoting on a tag
-       and a posting has multiple values of that tag, only the first value  is
-       displayed.   Values  containing colon:separated:parts will be displayed
-       hierarchically, like account names.  Multiple,  colon-delimited  fields
-       can be pivoted simultaneously, generating a hierarchical account name.
-
-       Some examples:
-
-              2016/02/16 Yearly Dues Payment
-                  assets:bank account                 2 EUR
-                  income:dues                        -2 EUR  ; member: John Doe, kind: Lifetime
-
-       Normal balance report showing account names:
-
-              $ hledger balance
-                             2 EUR  assets:bank account
-                            -2 EUR  income:dues
-              --------------------
-                                 0
-
-       Pivoted balance report, using member: tag values instead:
-
-              $ hledger balance --pivot member
-                             2 EUR
-                            -2 EUR  John Doe
-              --------------------
-                                 0
-
-       One way to show only amounts with a member: value (using a query):
-
-              $ hledger balance --pivot member tag:member=.
-                            -2 EUR  John Doe
-              --------------------
-                            -2 EUR
-
-       Another  way  (the  acct:  query  matches  against the pivoted "account
-       name"):
-
-              $ hledger balance --pivot member acct:.
-                            -2 EUR  John Doe
-              --------------------
-                            -2 EUR
-
-       Hierarchical reports can be generated with multiple pivots:
-
-              $ hledger balance Income:Dues --pivot kind:member
-                            -2 EUR  Lifetime:John Doe
-              --------------------
-                            -2 EUR
-
-Generating data
-       hledger can enrich the data provided to it, or generate new data, in  a
-       number of ways.  Mostly, this is done only if you request it:
-
-       o Missing  amounts  or missing costs in transactions are inferred auto-
-         matically when possible.
-
-       o The --infer-equity flag infers  missing  conversion  equity  postings
-         from @/@@ costs.
-
-       o The  --infer-costs  flag  infers missing costs from conversion equity
-         postings.
-
-       o The --infer-market-prices flag infers P price directives from costs.
-
-       o The --auto flag adds extra postings to transactions matched  by  auto
-         posting rules.
-
-       o The  --forecast  option generates transactions from periodic transac-
-         tion rules.
-
-       o The balance --budget report infers budget goals from periodic  trans-
-         action rules.
-
-       o Commands  like close, rewrite, and hledger-interest generate transac-
-         tions or postings.
-
-       o CSV data is converted to  transactions  by  applying  CSV  conversion
-         rules..  etc.
-
-       Such  generated  data  is temporary, existing only at report time.  You
-       can convert it to permanent recorded data by, eg, capturing the  output
-       of  hledger  print  and saving it in your journal file.  This can some-
-       times be useful as a data entry aid.
-
-       If you are curious what data is being generated and  why,  run  hledger
-       print  -x  --verbose-tags.   -x/--explicit  shows  inferred amounts and
-       --verbose-tags adds  tags  like  generated-transaction  (from  periodic
-       rules) and generated-posting, modified (from auto posting rules).  Sim-
-       ilar  hidden tags (with an underscore prefix) are always present, also,
-       so you can always match such data with queries  like  tag:generated  or
-       tag:modified.
-
-Forecasting
-       Forecasting,  or  speculative future reporting, can be useful for esti-
-       mating future balances, or for exploring different future scenarios.
-
-       The simplest and most flexible way to do it with hledger is to manually
-       record a bunch of future-dated transactions.  You could keep these in a
-       separate future.journal and include that with -f only when you want  to
-       see them.
-
-   --forecast
-       There  is another way: with the --forecast option, hledger can generate
-       temporary "forecast transactions" for reporting purposes, according  to
-       periodic  transaction rules defined in the journal.  Each rule can gen-
-       erate multiple recurring transactions, so by changing one rule you  can
-       change many forecasted transactions.
-
-       Forecast  transactions  usually  start after ordinary transactions end.
-       By default, they begin after your latest-dated ordinary transaction, or
-       today, whichever is later, and they end six months  from  today.   (The
-       exact rules are a little more complicated, and are given below.)
-
-       This is the "forecast period", which need not be the same as the report
-       period.   You can override it - eg to forecast farther into the future,
-       or to force forecast transactions to overlap your ordinary transactions
-       - by giving the --forecast option a period  expression  argument,  like
-       --forecast=..2099  or  --forecast=2023-02-15...  Note that the = is re-
-       quired.
-
-   Inspecting forecast transactions
-       print is the best command for inspecting and  troubleshooting  forecast
-       transactions.  Eg:
-
-              ~ monthly from 2022-12-20    rent
-                  assets:bank:checking
-                  expenses:rent           $1000
-
-              $ hledger print --forecast --today=2023/4/21
-              2023-05-20 rent
-                  ; generated-transaction: ~ monthly from 2022-12-20
-                  assets:bank:checking
-                  expenses:rent                  $1000
-
-              2023-06-20 rent
-                  ; generated-transaction: ~ monthly from 2022-12-20
-                  assets:bank:checking
-                  expenses:rent                  $1000
-
-              2023-07-20 rent
-                  ; generated-transaction: ~ monthly from 2022-12-20
-                  assets:bank:checking
-                  expenses:rent                  $1000
-
-              2023-08-20 rent
-                  ; generated-transaction: ~ monthly from 2022-12-20
-                  assets:bank:checking
-                  expenses:rent                  $1000
-
-              2023-09-20 rent
-                  ; generated-transaction: ~ monthly from 2022-12-20
-                  assets:bank:checking
-                  expenses:rent                  $1000
-
-       Here there are no ordinary transactions, so the forecasted transactions
-       begin  on the first occurrence after today's date.  (You won't normally
-       use --today; it's just to make these examples reproducible.)
-
-   Forecast reports
-       Forecast transactions affect all reports, as you would expect.  Eg:
-
-              $ hledger areg rent --forecast --today=2023/4/21
-              Transactions in expenses:rent and subaccounts:
-              2023-05-20 rent                 as:ba:checking               $1000         $1000
-              2023-06-20 rent                 as:ba:checking               $1000         $2000
-              2023-07-20 rent                 as:ba:checking               $1000         $3000
-              2023-08-20 rent                 as:ba:checking               $1000         $4000
-              2023-09-20 rent                 as:ba:checking               $1000         $5000
-
-              $ hledger bal -M expenses --forecast --today=2023/4/21
-              Balance changes in 2023-05-01..2023-09-30:
-
-                             ||   May    Jun    Jul    Aug    Sep
-              ===============++===================================
-               expenses:rent || $1000  $1000  $1000  $1000  $1000
-              ---------------++-----------------------------------
-                             || $1000  $1000  $1000  $1000  $1000
-
-   Forecast tags
-       Forecast transactions generated by --forecast have a hidden tag,  _gen-
-       erated-transaction.   So  if  you  ever need to match forecast transac-
-       tions, you could use tag:_generated-transaction (or just tag:generated)
-       in a query.
-
-       For troubleshooting, you can add the --verbose-tags flag.  Then,  visi-
-       ble generated-transaction tags will be added also, so you can view them
-       with  the print command.  Their value indicates which periodic rule was
-       responsible.
-
-   Forecast period, in detail
-       Forecast start/end dates are chosen so as to do something useful by de-
-       fault in almost all situations, while also being  flexible.   Here  are
-       (with luck) the exact rules, to help with troubleshooting:
-
-       The forecast period starts on:
-
-       o the later of
-
-         o the start date in the periodic transaction rule
-
-         o the start date in --forecast's argument
-
-       o otherwise (if those are not available): the later of
-
-         o the report start date specified with -b/-p/date:
-
-         o the day after the latest ordinary transaction in the journal
-
-       o otherwise (if none of these are available): today.
-
-       The forecast period ends on:
-
-       o the earlier of
-
-         o the end date in the periodic transaction rule
-
-         o the end date in --forecast's argument
-
-       o otherwise: the report end date specified with -e/-p/date:
-
-       o otherwise: 180 days (~6 months) from today.
-
-   Forecast troubleshooting
-       When  --forecast is not doing what you expect, one of these tips should
-       help:
-
-       o Remember to use the --forecast option.
-
-       o Remember to have at least one periodic transaction rule in your jour-
-         nal.
-
-       o Test with print --forecast.
-
-       o Check for typos or too-restrictive start/end dates in  your  periodic
-         transaction rule.
-
-       o Leave  at least 2 spaces between the rule's period expression and de-
-         scription fields.
-
-       o Check for future-dated ordinary transactions  suppressing  forecasted
-         transactions.
-
-       o Try setting explicit report start and/or end dates with -b, -e, -p or
-         date:
-
-       o Try  adding  the  -E  flag to encourage display of empty periods/zero
-         transactions.
-
-       o Try setting explicit forecast start and/or  end  dates  with  --fore-
-         cast=START..END
-
-       o Consult Forecast period, in detail, above.
-
-       o Check inside the engine: add --debug=2 (eg).
-
-Budgeting
-       With  the  balance command's --budget report, each periodic transaction
-       rule generates recurring budget goals in specified accounts, and  goals
-       and  actual performance can be compared.  See the balance command's doc
-       below.
-
-       You can generate budget goals and forecast  transactions  at  the  same
-       time,  from  the  same or different periodic transaction rules: hledger
-       bal -M --budget --forecast ...
-
-       See also: Budgeting and Forecasting.
-
-Amount formatting
-   Commodity display style
-       For the amounts in each commodity, hledger chooses a consistent display
-       style (symbol placement, decimal mark and digit group marks, number  of
-       decimal digits) to use in most reports.  This is inferred as follows:
-
-       First,  if  there's  a  D directive declaring a default commodity, that
-       commodity symbol and amount format is applied to all no-symbol  amounts
-       in the journal.
-
-       Then  each  commodity's  display style is determined from its commodity
-       directive.  We recommend always declaring  commodities  with  commodity
-       directives, since they help ensure consistent display styles and preci-
-       sions,  and  bring  other benefits such as error checking for commodity
-       symbols.  Here's an example:
-
-              # Set display styles (and decimal marks, for parsing, if there is no decimal-mark directive)
-              # for the $, EUR, INR and no-symbol commodities:
-              commodity $1,000.00
-              commodity EUR 1.000,00
-              commodity INR 9,99,99,999.00
-              commodity 1 000 000.9455
-
-       But for convenience, if a commodity directive is not  present,  hledger
-       infers  a commodity's display styles from its amounts as they are writ-
-       ten in the journal (excluding cost  amounts  and  amounts  in  periodic
-       transaction rules or auto posting rules).  It uses
-
-       o the symbol placement and decimal mark of the first amount seen
-
-       o the digit group marks of the first amount with digit group marks
-
-       o and the maximum number of decimal digits seen across all amounts.
-
-       And  as fallback if no applicable amounts are found, it would use a de-
-       fault style, like $1000.00 (symbol on the left with no space, period as
-       decimal mark, and two decimal digits).
-
-       Finally, commodity styles can be overridden by the -c/--commodity-style
-       command line option.
-
-   Rounding
-       Amounts are stored internally as decimal numbers with up to 255 decimal
-       places.  They are displayed with their original journal  precisions  by
-       print  and  print-like  reports, and rounded to their display precision
-       (the number of decimal digits specified by the commodity display style)
-       by other reports.  When rounding, hledger uses  banker's  rounding  (it
-       rounds to the nearest even digit).  So eg 0.5 displayed with zero deci-
-       mal digits appears as "0".
-
-   Trailing decimal marks
-       If you're wondering why your print report sometimes shows trailing dec-
-       imal  marks,  with no decimal digits; it does this when showing amounts
-       that have digit group marks but no decimal digits, to disambiguate them
-       and allow them to be re-parsed reliably (see Decimal marks).  Eg:
-
-              commodity $1,000.00
-
-              2023-01-02
-                  (a)      $1000
-
-              $ hledger print
-              2023-01-02
-                  (a)        $1,000.
-
-       If this is a problem (eg when exporting to Ledger), you can avoid it by
-       disabling digit group marks, eg with -c/--commodity (for each  affected
-       commodity):
-
-              $ hledger print -c '$1000.00'
-              2023-01-02
-                  (a)          $1000
-
-       or by forcing print to always show decimal digits, with --round:
-
-              $ hledger print -c '$1,000.00' --round=soft
-              2023-01-02
-                  (a)      $1,000.00
-
-   Amount parseability
-       More generally, hledger output falls into three rough categories, which
-       format amounts a little bit differently to suit different consumers:
-
-       1.   "hledger-readable  output" - should be readable by hledger (and by
-       humans)
-
-       o This is produced by reports that show full  journal  entries:  print,
-         import, close, rewrite etc.
-
-       o It  shows  amounts  with their original journal precisions, which may
-         not be consistent.
-
-       o It adds a trailing decimal mark when needed to avoid showing  ambigu-
-         ous amounts.
-
-       o It  can be parsed reliably (by hledger and ledger2beancount at least,
-         but perhaps not by Ledger..)
-
-       2.  "human-readable output" - usually for humans
-
-       o This is produced by all other reports.
-
-       o It shows amounts with standard display precisions, which will be con-
-         sistent within each commodity.
-
-       o It shows ambiguous amounts unmodified.
-
-       o It can be parsed reliably in the context of a known report (when  you
-         know decimals are consistently not being shown, you can assume a sin-
-         gle mark is a digit group mark).
-
-       3.  "machine-readable output" - usually for other software
-
-       o This  is produced by all reports when an output format like csv, tsv,
-         json, or sql is selected.
-
-       o It shows amounts as 1 or 2 do, but without digit group marks.
-
-       o It can be parsed reliably (if needed, the decimal mark can be changed
-         with -c/--commodity-style).
-
-Cost reporting
-       In some transactions - for example a currency conversion, or a purchase
-       or sale of stock - one commodity is exchanged for  another.   In  these
-       transactions  there  is  a  conversion rate, also called the cost (when
-       buying) or selling price (when selling).  In hledger docs we  just  say
-       "cost", for convenience; feel free to mentally translate to "conversion
-       rate" or "selling price" if helpful.
-
-   Recording costs
-       We'll  explore  several ways of recording transactions involving costs.
-       These are also summarised at hledger Cookbook > Cost notation.
-
-       Costs can be recorded explicitly in the journal, using the  @  UNITCOST
-       or @@ TOTALCOST notation described in Journal > Costs:
-
-       Variant 1
-
-              2022-01-01
-                assets:dollars    $-135
-                assets:euros       100 @ $1.35   ; $1.35 per euro (unit cost)
-
-       Variant 2
-
-              2022-01-01
-                assets:dollars    $-135
-                assets:euros       100 @@ $135   ; $135 total cost
-
-       Typically,  writing  the unit cost (variant 1) is preferable; it can be
-       more effort, requiring more attention to decimal digits; but it reveals
-       the per-unit cost basis, and makes stock sales easier.
-
-       Costs can also be left implicit, and hledger will infer the  cost  that
-       is consistent with a balanced transaction:
-
-       Variant 3
-
-              2022-01-01
-                assets:dollars    $-135
-                assets:euros       100
-
-       Here,  hledger  will  attach a @@ 100 cost to the first amount (you can
-       see it with hledger print -x).  This form looks convenient,  but  there
-       are downsides:
-
-       o It  sacrifices some error checking.  For example, if you accidentally
-         wrote 10 instead of 100, hledger would not be able to detect the mis-
-         take.
-
-       o It is sensitive to the order of postings - if they were  reversed,  a
-         different entry would be inferred and reports would be different.
-
-       o The per-unit cost basis is not easy to read.
-
-       So  generally this kind of entry is not recommended.  You can make sure
-       you have none of these by using -s (strict mode), or by running hledger
-       check balanced.
-
-   Reporting at cost
-       Now when you add the -B/--cost flag to reports ("B"  is  from  Ledger's
-       -B/--basis/--cost  flag),  any  amounts  which have been annotated with
-       costs will be converted to their cost's commodity (in the  report  out-
-       put).  Ie they will be displayed "at cost" or "at sale price".
-
-       Some things to note:
-
-       o Costs  are  attached to specific posting amounts in specific transac-
-         tions, and once recorded they do not  change.   This  contrasts  with
-         market prices, which are ambient and fluctuating.
-
-       o Conversion  to  cost  is  performed before conversion to market value
-         (described below).
-
-   Equity conversion postings
-       There is a problem with the entries above - they are  not  conventional
-       Double  Entry  Bookkeeping (DEB) notation, and because of the "magical"
-       transformation of one commodity into another, they cause  an  imbalance
-       in the Accounting Equation.  This shows up as a non-zero grand total in
-       balance reports like hledger bse.
-
-       For  most hledger users, this doesn't matter in practice and can safely
-       be ignored !  But if you'd like to learn more, keep reading.
-
-       Conventional DEB uses an extra pair of equity postings to  balance  the
-       transaction.  Of course you can do this in hledger as well:
-
-       Variant 4
-
-              2022-01-01
-                  assets:dollars      $-135
-                  assets:euros         100
-                  equity:conversion    $135
-                  equity:conversion   -100
-
-       Now  the  transaction  is perfectly balanced according to standard DEB,
-       and hledger bse's total will not be disrupted.
-
-       And, hledger can still infer the cost for cost reporting, but it's  not
-       done by default - you must add the --infer-costs flag like so:
-
-              $ hledger print --infer-costs
-              2022-01-01 one hundred euros purchased at $1.35 each
-                  assets:dollars       $-135 @@ 100
-                  assets:euros                  100
-                  equity:conversion             $135
-                  equity:conversion            -100
-
-              $ hledger bal --infer-costs -B
-                             -100  assets:dollars
-                              100  assets:euros
-              --------------------
-                                 0
-
-       Here are some downsides of this kind of entry:
-
-       o The per-unit cost basis is not easy to read.
-
-       o Instead of -B you must remember to type -B --infer-costs.
-
-       o --infer-costs  works  only  where  hledger  can  identify the two eq-
-         uity:conversion postings and match them up with  the  two  non-equity
-         postings.   So  writing  the journal entry in a particular format be-
-         comes more important.  More on this below.
-
-   Inferring equity conversion postings
-       Can we go in the other direction ?  Yes, if you have transactions writ-
-       ten with the @/@@ cost notation, hledger can infer the  missing  equity
-       postings, if you add the --infer-equity flag.  Eg:
-
-              2022-01-01
-                assets:dollars  -$135
-                assets:euros     100 @ $1.35
-
-              $ hledger print --infer-equity
-              2022-01-01
-                  assets:dollars                    $-135
-                  assets:euros               100 @ $1.35
-                  equity:conversion:$-:           -100
-                  equity:conversion:$-:$         $135.00
-
-       The  equity  account  names  will be "equity:conversion:A-B:A" and "eq-
-       uity:conversion:A-B:B" where A is the  alphabetically  first  commodity
-       symbol.  You can customise the "equity:conversion" part by declaring an
-       account with the V/Conversion account type.
-
-       Note  you will need to add account declarations for these to your jour-
-       nal, if you use check accounts or check --strict.
-
-   Combining costs and equity conversion postings
-       Finally, you can use both the @/@@ cost notation and equity postings at
-       the same time.  This in theory gives the best of all worlds -  preserv-
-       ing  the  accounting  equation,  revealing the per-unit cost basis, and
-       providing more flexibility in how you write the entry:
-
-       Variant 5
-
-              2022-01-01 one hundred euros purchased at $1.35 each
-                  assets:dollars      $-135
-                  equity:conversion    $135
-                  equity:conversion   -100
-                  assets:euros         100 @ $1.35
-
-       All the other variants above can (usually) be rewritten to  this  final
-       form with:
-
-              $ hledger print -x --infer-costs --infer-equity
-
-       Downsides:
-
-       o The  precise  format of the journal entry becomes more important.  If
-         hledger can't detect and match up the cost and  equity  postings,  it
-         will give a transaction balancing error.
-
-       o The add command does not yet accept this kind of entry (#2056).
-
-       o This is the most verbose form.
-
-   Requirements for detecting equity conversion postings
-       --infer-costs  has  certain  requirements (unlike --infer-equity, which
-       always works).  It will infer costs only in transactions with:
-
-       o Two non-equity postings, in different commodities.   Their  order  is
-         significant: the cost will be added to the first of them.
-
-       o Two  postings  to  equity  conversion  accounts, next to one another,
-         which balance the two non-equity postings.  This balancing is checked
-         to the same precision (number of decimal places) used in the  conver-
-         sion posting's amount.  Equity conversion accounts are:
-
-         o any accounts declared with account type V/Conversion, or their sub-
-           accounts
-
-         o otherwise,  accounts  named equity:conversion, equity:trade, or eq-
-           uity:trading, or their subaccounts.
-
-       And multiple such four-posting  groups  can  coexist  within  a  single
-       transaction.   When  --infer-costs  fails,  it does not infer a cost in
-       that transaction, and does not raise an  error  (ie,  it  infers  costs
-       where it can).
-
-       Reading  variant  5 journal entries, combining cost notation and equity
-       postings, has all the same requirements.  When reading  such  an  entry
-       fails, hledger raises an "unbalanced transaction" error.
-
-   Infer cost and equity by default ?
-       Should  --infer-costs  and  --infer-equity be enabled by default ?  Try
-       using them always, eg with a shell alias:
-
-              alias h="hledger --infer-equity --infer-costs"
-
-       and let us know what problems you find.
-
-Value reporting
-       Instead of reporting amounts in their original commodity,  hledger  can
-       convert them to cost/sale amount (using the conversion rate recorded in
-       the  transaction), and/or to market value (using some market price on a
-       certain date).  This is controlled by the --value=TYPE[,COMMODITY]  op-
-       tion,  which  will  be described below.  We also provide the simpler -V
-       and -X COMMODITY options, and often one of these is all you need:
-
-   -V: Value
-       The -V/--market flag converts amounts to market value in their  default
-       valuation commodity, using the market prices in effect on the valuation
-       date(s), if any.  More on these in a minute.
-
-   -X: Value in specified commodity
-       The -X/--exchange=COMM option is like -V, except you tell it which cur-
-       rency  you  want  to  convert to, and it tries to convert everything to
-       that.
-
-   Valuation date
-       Market prices can change from day to day.  hledger will use the  prices
-       on  a particular valuation date (or on more than one date).  By default
-       hledger uses "end" dates for valuation.  More specifically:
-
-       o For single period reports (including normal print  and  register  re-
-         ports):
-
-         o If an explicit report end date is specified, that is used
-
-         o Otherwise  the  latest transaction date or P directive date is used
-           (even if it's in the future)
-
-       o For multiperiod reports, each period is valued on its last day.
-
-       This can be customised with the --value option described  below,  which
-       can select either "then", "end", "now", or "custom" dates.  (Note, this
-       has a bug in hledger-ui <=1.31: turning on valuation with the V key al-
-       ways resets it to "end".)
-
-   Finding market price
-       To  convert  a  commodity A to its market value in another commodity B,
-       hledger looks for a suitable market price (exchange rate)  as  follows,
-       in this order of preference:
-
-       1. A  declared market price or inferred market price: A's latest market
-          price in B on or before the valuation date as declared by a P direc-
-          tive, or (with the --infer-market-prices flag) inferred from costs.
-
-       2. A reverse market price: the inverse of a declared or inferred market
-          price from B to A.
-
-       3. A forward chain of market prices: a synthetic price formed  by  com-
-          bining the shortest chain of "forward" (only 1 above) market prices,
-          leading from A to B.
-
-       4. Any  chain of market prices: a chain of any market prices, including
-          both forward and reverse prices (1 and 2 above), leading from  A  to
-          B.
-
-       There  is  a  limit  to  the  length  of these price chains; if hledger
-       reaches that length without finding a complete chain or exhausting  all
-       possibilities,  it  will  give  up (with a "gave up" message visible in
-       --debug=2 output).  That limit is currently 1000.
-
-       Amounts for which no suitable market price can be found, are  not  con-
-       verted.
-
-   --infer-market-prices: market prices from transactions
-       Normally, market value in hledger is fully controlled by, and requires,
-       P directives in your journal.  Since adding and updating those can be a
-       chore,  and  since  transactions  usually take place at close to market
-       value, why not use the recorded costs as additional market  prices  (as
-       Ledger  does)  ?   Adding  the  --infer-market-prices flag to -V, -X or
-       --value enables this.
-
-       So for example, hledger bs -V  --infer-market-prices  will  get  market
-       prices  both from P directives and from transactions.  If both occur on
-       the same day, the P directive takes precedence.
-
-       There is a downside: value reports can sometimes be affected in confus-
-       ing/undesired ways by your journal entries.  If this  happens  to  you,
-       read  all  of  this  Value  reporting section carefully, and try adding
-       --debug or --debug=2 to troubleshoot.
-
-       --infer-market-prices can infer market prices from:
-
-       o multicommodity transactions with explicit prices (@/@@)
-
-       o multicommodity transactions with implicit prices (no @, two  commodi-
-         ties,  unbalanced).   (With  these,  the  order  of postings matters.
-         hledger print -x can be useful for troubleshooting.)
-
-       o multicommodity transactions with equity postings, if cost is inferred
-         with --infer-costs.
-
-       There is a limitation (bug) currently: when a  valuation  commodity  is
-       not  specified,  prices inferred with --infer-market-prices do not help
-       select a default valuation commodity, as P prices would.  So conversion
-       might not happen because no valuation commodity was detected (--debug=2
-       will show this).  To be safe, specify the valuation commmodity, eg:
-
-       o -X EUR --infer-market-prices, not -V --infer-market-prices
-
-       o --value=then,EUR --infer-market-prices, not --value=then --infer-mar-
-         ket-prices
-
-       Signed costs and market prices can be confusing.  For  reference,  here
-       is  the current behaviour, since hledger 1.25.  (If you think it should
-       work differently, see #1870.)
-
-              2022-01-01 Positive Unit prices
-                  a        A 1
-                  b        B -1 @ A 1
-
-              2022-01-01 Positive Total prices
-                  a        A 1
-                  b        B -1 @@ A 1
-
-
-              2022-01-02 Negative unit prices
-                  a        A 1
-                  b        B 1 @ A -1
-
-              2022-01-02 Negative total prices
-                  a        A 1
-                  b        B 1 @@ A -1
-
-
-              2022-01-03 Double Negative unit prices
-                  a        A -1
-                  b        B -1 @ A -1
-
-              2022-01-03 Double Negative total prices
-                  a        A -1
-                  b        B -1 @@ A -1
-
-       All of the transactions above are considered balanced (and on each day,
-       the two transactions are considered equivalent).  Here are  the  market
-       prices inferred for B:
-
-              $ hledger -f- --infer-market-prices prices
-              P 2022-01-01 B A 1
-              P 2022-01-01 B A 1.0
-              P 2022-01-02 B A -1
-              P 2022-01-02 B A -1.0
-              P 2022-01-03 B A -1
-              P 2022-01-03 B A -1.0
-
-   Valuation commodity
-       When you specify a valuation commodity (-X COMM or --value TYPE,COMM):
-       hledger  will convert all amounts to COMM, wherever it can find a suit-
-       able market price (including by reversing or chaining prices).
-
-       When you leave the  valuation  commodity  unspecified  (-V  or  --value
-       TYPE):
-       For  each  commodity  A, hledger picks a default valuation commodity as
-       follows, in this order of preference:
-
-       1. The price commodity from the latest P-declared market price for A on
-          or before valuation date.
-
-       2. The price commodity from the latest P-declared market price for A on
-          any date.  (Allows conversion to proceed  when  there  are  inferred
-          prices before the valuation date.)
-
-       3. If  there are no P directives at all (any commodity or date) and the
-          --infer-market-prices flag is used: the  price  commodity  from  the
-          latest transaction-inferred price for A on or before valuation date.
-
-       This means:
-
-       o If  you  have  P directives, they determine which commodities -V will
-         convert, and to what.
-
-       o If you have no P directives, and use the --infer-market-prices  flag,
-         costs determine it.
-
-       Amounts  for  which  no  valuation  commodity can be found are not con-
-       verted.
-
-   --value: Flexible valuation
-       -V and -X are special cases of the more general --value option:
-
-               --value=TYPE[,COMM]  TYPE is then, end, now or YYYY-MM-DD.
-                                    COMM is an optional commodity symbol.
-                                    Shows amounts converted to:
-                                    - default valuation commodity (or COMM) using market prices at posting dates
-                                    - default valuation commodity (or COMM) using market prices at period end(s)
-                                    - default valuation commodity (or COMM) using current market prices
-                                    - default valuation commodity (or COMM) using market prices at some date
-
-       The TYPE part selects cost or value and valuation date:
-
-       --value=then
-              Convert amounts to their value in the default valuation  commod-
-              ity, using market prices on each posting's date.
-
-       --value=end
-              Convert  amounts to their value in the default valuation commod-
-              ity, using market prices on the last day of  the  report  period
-              (or  if  unspecified, the journal's end date); or in multiperiod
-              reports, market prices on the last day of each subperiod.
-
-       --value=now
-              Convert amounts to their value in the default valuation  commod-
-              ity  using  current  market  prices (as of when report is gener-
-              ated).
-
-       --value=YYYY-MM-DD
-              Convert amounts to their value in the default valuation  commod-
-              ity using market prices on this date.
-
-       To select a different valuation commodity, add the optional ,COMM part:
-       a  comma,  then  the  target  commodity's symbol.  Eg: --value=now,EUR.
-       hledger will do its best to convert amounts to this commodity, deducing
-       market prices as described above.
-
-   Valuation examples
-       Here are some quick examples of -V:
-
-              ; one euro is worth this many dollars from nov 1
-              P 2016/11/01  $1.10
-
-              ; purchase some euros on nov 3
-              2016/11/3
-                  assets:euros        100
-                  assets:checking
-
-              ; the euro is worth fewer dollars by dec 21
-              P 2016/12/21  $1.03
-
-       How many euros do I have ?
-
-              $ hledger -f t.j bal -N euros
-                              100  assets:euros
-
-       What are they worth at end of nov 3 ?
-
-              $ hledger -f t.j bal -N euros -V -e 2016/11/4
-                           $110.00  assets:euros
-
-       What are they worth after 2016/12/21 ?  (no report end date  specified,
-       defaults to today)
-
-              $ hledger -f t.j bal -N euros -V
-                           $103.00  assets:euros
-
-       Here  are  some  examples  showing  the effect of --value, as seen with
-       print:
-
-              P 2000-01-01 A  1 B
-              P 2000-02-01 A  2 B
-              P 2000-03-01 A  3 B
-              P 2000-04-01 A  4 B
-
-              2000-01-01
-                (a)      1 A @ 5 B
-
-              2000-02-01
-                (a)      1 A @ 6 B
-
-              2000-03-01
-                (a)      1 A @ 7 B
-
-       Show the cost of each posting:
-
-              $ hledger -f- print --cost
-              2000-01-01
-                  (a)             5 B
-
-              2000-02-01
-                  (a)             6 B
-
-              2000-03-01
-                  (a)             7 B
-
-       Show the value as of the last day of the report period (2000-02-29):
-
-              $ hledger -f- print --value=end date:2000/01-2000/03
-              2000-01-01
-                  (a)             2 B
-
-              2000-02-01
-                  (a)             2 B
-
-       With no report period specified, that shows the value as  of  the  last
-       day of the journal (2000-03-01):
-
-              $ hledger -f- print --value=end
-              2000-01-01
-                  (a)             3 B
-
-              2000-02-01
-                  (a)             3 B
-
-              2000-03-01
-                  (a)             3 B
-
-       Show the current value (the 2000-04-01 price is still in effect today):
-
-              $ hledger -f- print --value=now
-              2000-01-01
-                  (a)             4 B
-
-              2000-02-01
-                  (a)             4 B
-
-              2000-03-01
-                  (a)             4 B
-
-       Show the value on 2000/01/15:
-
-              $ hledger -f- print --value=2000-01-15
-              2000-01-01
-                  (a)             1 B
-
-              2000-02-01
-                  (a)             1 B
-
-              2000-03-01
-                  (a)             1 B
-
-   Interaction of valuation and queries
-       When  matching  postings based on queries in the presence of valuation,
-       the following happens:
-
-       1. The query is separated into two parts:
-
-           1. the currency (cur:) or amount (amt:).
-
-           2. all other parts.
-
-       2. The postings are matched to the currency and amount queries based on
-          pre-valued amounts.
-
-       3. Valuation is applied to the postings.
-
-       4. The postings are matched to the other parts of the  query  based  on
-          post-valued amounts.
-
-       Related: #1625
-
-   Effect of valuation on reports
-       Here  is  a reference for how valuation is supposed to affect each part
-       of hledger's reports.  (It's wide, you may need  to  scroll  sideways.)
-       It  may  be  useful when troubleshooting.  If you find problems, please
-       report them, ideally  with  a  reproducible  example.   Related:  #329,
-       #1083.
-
-       First, a quick glossary:
-
-       cost   calculated using price(s) recorded in the transaction(s).
-
-       value  market  value  using available market price declarations, or the
-              unchanged amount if no conversion rate can be found.
-
-       report start
-              the first day of the report period specified with -b  or  -p  or
-              date:, otherwise today.
-
-       report or journal start
-              the  first  day  of the report period specified with -b or -p or
-              date:, otherwise the earliest transaction date in  the  journal,
-              otherwise today.
-
-       report end
-              the  last  day  of  the report period specified with -e or -p or
-              date:, otherwise today.
-
-       report or journal end
-              the last day of the report period specified with  -e  or  -p  or
-              date:,  otherwise  the  latest  transaction date in the journal,
-              otherwise today.
-
-       report interval
-              a flag (-D/-W/-M/-Q/-Y) or period expression that activates  the
-              report's multi-period mode (whether showing one or many subperi-
-              ods).
-
-       Report      -B, --cost     -V, -X         --value=then         --value=end    --value=DATE,
-       type                                                                          --value=now
-       --------------------------------------------------------------------------------------------
-       print
-       posting     cost           value at re-   value at  posting    value at re-   value      at
-       amounts                    port  end or   date                 port      or   DATE/today
-                                  today                               journal end
-       balance     unchanged      unchanged      unchanged            unchanged      unchanged
-       asser-
-       tions/as-
-       signments
-
-       register
-       starting    cost           value at re-   valued   at   day    value at re-   value      at
-       balance                    port      or   each   historical    port      or   DATE/today
-       (-H)                       journal end    posting was made     journal end
-       starting    cost           value at day   valued   at   day    value at day   value      at
-       balance                    before   re-   each   historical    before   re-   DATE/today
-       (-H) with                  port      or   posting was made     port      or
-       report                     journal                             journal
-       interval                   start                               start
-       posting     cost           value at re-   value at  posting    value at re-   value      at
-       amounts                    port      or   date                 port      or   DATE/today
-                                  journal end                         journal end
-       summary     summarised     value at pe-   sum  of  postings    value at pe-   value      at
-       posting     cost           riod ends      in interval, val-    riod ends      DATE/today
-       amounts                                   ued  at  interval
-       with  re-                                 start
-       port  in-
-       terval
-       running     sum/average    sum/average    sum/average    of    sum/average    sum/average
-       total/av-   of displayed   of displayed   displayed values     of displayed   of  displayed
-       erage       values         values                              values         values
-
-       balance
-       (bs, bse,
-       cf, is)
-       balance     sums      of   value at re-   value at  posting    value at re-   value      at
-       changes     costs          port  end or   date                 port      or   DATE/today of
-                                  today     of                        journal  end   sums of post-
-                                  sums      of                        of  sums  of   ings
-                                  postings                            postings
-       budget      like balance   like balance   like      balance    like    bal-   like  balance
-       amounts     changes        changes        changes              ances          changes
-       (--bud-
-       get)
-       grand to-   sum of  dis-   sum of  dis-   sum of  displayed    sum  of dis-   sum  of  dis-
-       tal         played  val-   played  val-   valued               played  val-   played values
-                   ues            ues                                 ues
-
-       balance
-       (bs, bse,
-       cf,   is)
-       with  re-
-       port  in-
-       terval
-       starting    sums      of   value at re-   sums of values of    value at re-   sums of post-
-       balances    costs     of   port   start   postings   before    port   start   ings   before
-       (-H)        postings be-   of  sums  of   report  start  at    of  sums  of   report start
-                   fore  report   all postings   respective  post-    all postings
-                   start          before   re-   ing dates            before   re-
-                                  port start                          port start
-       balance     sums      of   same      as   sums of values of    balance        value      at
-       changes     costs     of   --value=end    postings  in  pe-    change    in   DATE/today of
-       (bal, is,   postings  in                  riod  at  respec-    each period,   sums of post-
-       bs          period                        tive      posting    valued    at   ings
-       --change,                                 dates                period ends
-       cf
-       --change)
-       end  bal-   sums      of   same      as   sums of values of    period   end   value      at
-       ances       costs     of   --value=end    postings from be-    balances,      DATE/today of
-       (bal  -H,   postings                      fore period start    valued    at   sums of post-
-       is   --H,   from  before                  to period end  at    period ends    ings
-       bs, cf)     report start                  respective  post-
-                   to    period                  ing dates
-                   end
-       budget      like balance   like balance   like      balance    like    bal-   like  balance
-       amounts     changes/end    changes/end    changes/end  bal-    ances          changes/end
-       (--bud-     balances       balances       ances                               balances
-       get)
-       row   to-   sums,  aver-   sums,  aver-   sums, averages of    sums,  aver-   sums,   aver-
-       tals, row   ages of dis-   ages of dis-   displayed values     ages of dis-   ages  of dis-
-       averages    played  val-   played  val-                        played  val-   played values
-       (-T, -A)    ues            ues                                 ues
-       column      sums of dis-   sums of dis-   sums of displayed    sums of dis-   sums  of dis-
-       totals      played  val-   played  val-   values               played  val-   played values
-                   ues            ues                                 ues
-       grand to-   sum, average   sum, average   sum,  average  of    sum, average   sum,  average
-       tal,        of    column   of    column   column totals        of    column   of column to-
-       grand av-   totals         totals                              totals         tals
-       erage
-
-
-       --cumulative is omitted to save space, it works like -H but with a zero
-       starting balance.
-
-PART 4: COMMANDS
-       Here  are the standard commands, which you can list by running hledger.
-       If you have installed more add-on commands, they also will be listed.
-
-       Help commands
-
-       o help - show the hledger manual with info/man/pager
-
-       o demo - show small hledger demos in the terminal
-
-       User interface commands
-
-       o ui - (if installed) run hledger's terminal UI
-
-       o web - (if installed) run hledger's web UI
-
-       Data entry commands
-
-       o add - add transactions using terminal prompts
-
-       o import - add new transactions from other files, eg CSV files
-
-       Basic report commands
-
-       o accounts - show account names
-
-       o codes - show transaction codes
-
-       o commodities - show commodity/currency symbols
-
-       o descriptions - show transaction descriptions
-
-       o files - show input file paths
-
-       o notes - show note parts of transaction descriptions
-
-       o payees - show payee parts of transaction descriptions
-
-       o prices - show market prices
-
-       o stats - show journal statistics
-
-       o tags - show tag names
-
-       Standard report commands
-
-       o print - show transactions or export journal data
-
-       o aregister (areg) - show transactions in a particular account
-
-       o register (reg) - show postings in one or more accounts & running  to-
-         tal
-
-       o balancesheet (bs) - show assets, liabilities and net worth
-
-       o balancesheetequity (bse) - show assets, liabilities and equity
-
-       o cashflow (cf) - show changes in liquid assets
-
-       o incomestatement (is) - show revenues and expenses
-
-       Advanced report commands
-
-       o balance (bal) - show balance changes, end balances, budgets, gains..
-
-       o roi - show return on investments
-
-       Chart commands
-
-       o activity - show bar charts of posting counts per period
-
-       Data generation commands
-
-       o close - generate balance-zeroing/restoring transactions
-
-       o rewrite - generate auto postings, like print --auto
-
-       Maintenance commands
-
-       o check - check for various kinds of error in the data
-
-       o diff - compare account transactions in two journal files
-
-       o test - run self tests
-
-       Next, these commands are described in detail.
-
-Help commands
-   help
-       Show  the hledger user manual with info, man, or a pager.  With a (case
-       insensitive) TOPIC argument, try to open it at that section heading.
-
-              Flags:
-                -i                       show the manual with info
-                -m                       show the manual with man
-                -p                       show the manual with $PAGER or less
-                                         (less is always used if TOPIC is specified)
-
-       This command shows the hledger manual built in  to  your  hledger  exe-
-       cutable.   It can be useful when offline, or when you prefer the termi-
-       nal to a web browser, or when the appropriate hledger manual or viewers
-       are not installed properly on your system.
-
-       By default it chooses the best viewer found in $PATH,  trying  in  this
-       order:  info,  man,  $PAGER, less, more, stdout.  (If a TOPIC is speci-
-       fied, $PAGER and more are not tried.)  You can force the use  of  info,
-       man,  or  a  pager  with  the -i, -m, or -p flags.  If no viewer can be
-       found, or if running non-interactively, it just prints  the  manual  to
-       stdout.
-
-       When  using  info, TOPIC can match either the full heading or a prefix.
-       If your info --version is < 6, you'll need to upgrade it, eg with 'brew
-       install texinfo' on mac.
-
-       When using man or less, TOPIC must match the full heading.  For a  pre-
-       fix match, you can write 'TOPIC.*'.
-
-       Examples
-
-              $ hledger help -h                 # show the help command's usage
-              $ hledger help                    # show the manual with info, man or $PAGER
-              $ hledger help 'time periods'     # show the manual's "Time periods" topic
-              $ hledger help 'time periods' -m  # use man, even if info is installed
-
-   demo
-       Play demos of hledger usage in the terminal, if asciinema is installed.
-
-              Flags:
-                -s --speed=SPEED         playback speed (1 is original speed, .5 is half, 2
-                                         is double, etc (default: 2))
-
-       Run  this  command with no argument to list the demos.  To play a demo,
-       write its number or a prefix or substring of its title.  Tips:
-
-       Make your terminal window large enough to see the demo clearly.
-
-       Use the -s/--speed SPEED option to set your preferred  playback  speed,
-       eg -s4 to play at 4x original speed or -s.5 to play at half speed.  The
-       default speed is 2x.
-
-       Other  asciinema  options  can  be added following a double dash, eg --
-       -i.1 to limit pauses or -- -h to list asciinema's other options.
-
-       During playback, several keys are available: SPACE to pause/unpause,  .
-       to step forward (while paused), CTRL-c quit.
-
-       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
-
-User interface commands
-   ui
-       Runs hledger-ui (if installed).
-
-   web
-       Runs hledger-web (if installed).
-
-Data entry commands
-   add
-       Record new transactions with interactive prompting in the console.
-
-              Flags:
-                   --no-new-accounts      don't allow creating new accounts
-
-       Many  hledger users edit their journals directly with a text editor, or
-       generate them from CSV.  For more interactive data entry, there is  the
-       add  command, which prompts interactively on the console for new trans-
-       actions, and appends them to the main journal file (which should be  in
-       journal  format).   Existing transactions are not changed.  This is one
-       of the few hledger commands that writes to the journal file  (see  also
-       import).
-
-       To use it, just run hledger add and follow the prompts.  You can add as
-       many  transactions as you like; when you are finished, enter . or press
-       control-d or control-c to exit.
-
-       Features:
-
-       o add tries to provide useful defaults, using the most similar (by  de-
-         scription)  recent  transaction  (filtered by the query, if any) as a
-         template.
-
-       o You can also set the initial defaults with command line arguments.
-
-       o Readline-style edit keys can be used during data entry.
-
-       o The tab key will auto-complete whenever  possible  -  accounts,  pay-
-         ees/descriptions,  dates  (yesterday, today, tomorrow).  If the input
-         area is empty, it will insert the default value.
-
-       o A parenthesised transaction code may be entered following a date.
-
-       o Comments and tags may be entered following a description or amount.
-
-       o If you make a mistake, enter < at any prompt to go one step backward.
-
-       o Input prompts are displayed in a different colour when  the  terminal
-         supports it.
-
-       Notes:
-
-       o If you enter a number with no commodity symbol, and you have declared
-         a  default  commodity with a D directive, you might expect add to add
-         this symbol for you.  It does not do this; we assume that if you  are
-         using  a  D  directive you prefer not to see the commodity symbol re-
-         peated on amounts in the journal.
-
-       Examples:
-
-       o Record new transactions, saving to the default journal file:
-
-         hledger add
-
-       o Add transactions to 2024.journal, but also load 2023.journal for com-
-         pletions:
-
-         hledger add --file 2024.journal --file 2023.journal
-
-       o Provide answers for the first four prompts:
-
-         hledger add today 'best buy' expenses:supplies '$20'
-
-       There is a detailed tutorial at https://hledger.org/add.html.
-
-   import
-       Import new transactions from one or more data files to the  main  jour-
-       nal.
-
-              Flags:
-                   --catchup              just mark all transactions as already imported
-                   --dry-run              just show the transactions to be imported
-
-       This  command detects new transactions in one or more data files speci-
-       fied as arguments, and appends them to the main journal.
-
-       You can import  from  any  input  file  format  hledger  supports,  but
-       CSV/SSV/TSV files, downloaded from financial institutions, are the most
-       common import source.
-
-       The  import  destination is the default journal file, or another speci-
-       fied in the usual way with $LEDGER_FILE or -f/--file.  It should be  in
-       journal format.
-
-       Examples:
-
-              $ hledger import bank1-checking.csv bank1-savings.csv
-
-              $ hledger import *.csv
-
-   Import preview
-       It's  useful  to preview the import by running first with --dry-run, to
-       sanity check the range of dates being imported, and to check the effect
-       of your conversion rules if converting from CSV.  Eg:
-
-              $ hledger import bank.csv --dry-run
-
-       The dry run output is valid journal format, so hledger can re-parse it.
-       If the output is large, you could show just the uncategorised  transac-
-       tions like so:
-
-              $ hledger import --dry-run bank.csv | hledger -f- -I print unknown
-
-       You  could  also run this repeatedly to see the effect of edits to your
-       conversion rules:
-
-              $ watchexec -- 'hledger import --dry-run bank.csv | hledger -f- -I print unknown'
-
-       Once the conversion and dates look good enough to import to your  jour-
-       nal, perhaps with some manual fixups to follow, you would do the actual
-       import:
-
-              $ hledger import bank.csv
-
-   Overlap detection
-       Reading  CSV  files is built in to hledger, and not specific to import;
-       so  you  could  also  import  by  doing  hledger  -f   bank.csv   print
-       >>$LEDGER_FILE.
-
-       But  import  is  easier  and provides some advantages.  The main one is
-       that it avoids re-importing transactions it has seen on previous  runs.
-       This means you don't have to worry about overlapping data in successive
-       downloads  of  your  bank CSV; just download and import as often as you
-       like, and only the new transactions will be imported each time.
-
-       We don't call this "deduplication", as it's generally not  possible  to
-       reliably  detect duplicates in bank CSV.  Instead, import remembers the
-       latest date processed previously in each CSV file (saving it in a  hid-
-       den  file),  and skips any records prior to that date.  This works well
-       for most real-world CSV, where:
-
-       1. the data file name is stable (does not change) across imports
-
-       2. the item dates are stable across imports
-
-       3. the order of same-date items is stable across imports
-
-       4. the newest items have the newest dates
-
-       (Occasional violations of 2-4 are often harmless; you  can  reduce  the
-       chance of disruption by downloading and importing more often.)
-
-       Overlap  detection  is  automatic, and shouldn't require much attention
-       from you, except perhaps at first import (see below).  But  here's  how
-       it works:
-
-       o For each FILE being imported from:
-
-         1. hledger  reads  a  file named .latest.FILE file in the same direc-
-            tory, if any.  This file contains the latest  record  date  previ-
-            ously  imported  from  FILE,  in  YYYY-MM-DD  format.  If multiple
-            records with that date were imported, the date is  repeated  on  N
-            lines.
-
-         2. hledger  reads  records  from FILE.  If a latest date was found in
-            step 1, any records before that date, and the first N  records  on
-            that date, are skipped.
-
-       o After  a  successful import from all FILEs, without error and without
-         --dry-run, hledger updates each FILE's .latest.FILE for next time.
-
-       If this goes wrong, it's relatively easy to repair:
-
-       o You'll  notice  it  before  import  when  you  preview  with   import
-         --dry-run.
-
-       o Or  after  import when you try to reconcile your hledger account bal-
-         ances with your bank.
-
-       o hledger print -f FILE.csv will show all recently downloaded  transac-
-         tions.  Compare these with your journal.  Copy/paste if needed.
-
-       o Update your conversion rules and print again, if needed.
-
-       o You  can  manually  update  or remove the .latest file, or use import
-         --catchup FILE.
-
-       o Download and import more often, eg twice a week, at least  while  you
-         are  learning.  It's easier to review and troubleshoot when there are
-         fewer transactions.
-
-   First import
-       The first time you import from a file, when  no  corresponding  .latest
-       file has been created yet, all of the records will be imported.
-
-       But  perhaps you have been entering the data manually, so you know that
-       all of these transactions are already recorded in the journal.  In this
-       case you can run hledger import --catchup once.   This  will  create  a
-       .latest  file  containing  the  latest CSV record date, so that none of
-       those records will be re-imported.
-
-       Or, if you know that some but not all of the transactions  are  in  the
-       journal,  you  can create the .latest file yourself.  Eg, let's say you
-       previously recorded foobank transactions up to 2024-10-31 in the  jour-
-       nal.   Then  in  the  directory where you'll be saving foobank.csv, you
-       would create a .latest.foobank.csv file containing
-
-              2024-10-31
-
-       Or if you had three foobank transactions recorded with that  date,  you
-       would repeat the date that many times:
-
-              2024-10-31
-              2024-10-31
-              2024-10-31
-
-       Then  hledger import foobank.csv [--dry-run] will import only the newer
-       records.
-
-   Importing balance assignments
-       Journal entries added by import will have all posting amounts made  ex-
-       plicit (like print -x).
-
-       This  means  that any balance assignments in the imported entries would
-       need to be evaluated.  But this generally isn't possible, as  the  main
-       file's account balances are not visible during import.  So try to avoid
-       generating balance assignments with your CSV rules, or importing from a
-       journal  that  contains  balance assignments.  (Balance assignments are
-       best avoided anyway.)
-
-       But if you must use them, eg because your CSV includes  only  balances:
-       you  can  import  with  print,  which leaves implicit amounts implicit.
-       (print can also do overlap detection like import, with the --new flag):
-
-              $ hledger print --new -f bank.csv >> $LEDGER_FILE
-
-       (If you think import should preserve  implicit  balances,  please  test
-       that and send a pull request.)
-
-   Import and commodity styles
-       Amounts  in  entries added by import will be formatted according to the
-       journal's canonical commodity styles, as declared by  commodity  direc-
-       tives or inferred from the journal's amounts.
-
-       Related: CSV > Amount decimal places.
-
-   Import special cases
-       If you have a download whose file name varies, you could rename it to a
-       fixed  name  after  each  download.  Or you could use a CSV source rule
-       with a suitable glob pattern, and import from the .rules  file  instead
-       of the data file.
-
-       Here's  a  situation  where you would need to run import with care: say
-       you download bank.csv, but forget to import it or delete it.  And  next
-       month you download it again.  This time your web browser may save it as
-       bank  (2).csv.   So now each of these may have data not included in the
-       other.  And a source rule with a glob pattern would match only the most
-       recent file.  So in this case you should import from each one in  turn,
-       in the correct order, taking care to use the same filename each time:
-
-              $ hledger import bank.csv
-              $ mv 'bank (2).csv' bank.csv
-              $ hledger import bank.csv
-
-       Here are two kinds of "deduplication" which import does not handle (and
-       generally  should not, since these can happen legitimately in financial
-       data):
-
-       o Two or more of the new CSV records are identical, and generate  iden-
-         tical new journal entries.
-
-       o A  new  CSV  record generates a journal entry identical to one(s) al-
-         ready in the journal.
-
-Basic report commands
-   accounts
-       List account names.
-
-              Flags:
-                -u --used                 show only accounts used by transactions
-                -d --declared             show only accounts declared by account directive
-                   --unused               show only accounts declared but not used
-                   --undeclared           show only accounts used but not declared
-                   --types                also show account types when known
-                   --positions            also show where accounts were declared
-                   --directives           show as account directives, for use in journals
-                   --find                 find the first account matched by the first
-                                          argument (a case-insensitive infix regexp or
-                                          account name)
-                -l --flat                 show accounts as a flat list (default)
-                -t --tree                 show accounts as a tree
-                   --drop=N               flat mode: omit N leading account name parts
-
-       This command lists account names.  By default it shows  all  known  ac-
-       counts,  either  used  in  transactions or declared with account direc-
-       tives.
-
-       With query arguments, only matched account names and account names ref-
-       erenced by matched postings are shown.
-
-       Or it can show just the used accounts  (--used/-u),  the  declared  ac-
-       counts  (--declared/-d), the accounts declared but not used (--unused),
-       the accounts used but not declared (--undeclared), or the first account
-       matched by an account name pattern, if any (--find).
-
-       It shows a flat list by default.  With --tree, it uses  indentation  to
-       show  the account hierarchy.  In flat mode you can add --drop N to omit
-       the  first  few  account  name  components.   Account  names   can   be
-       depth-clipped with depth:N or --depth N or -N.
-
-       With  --types,  it also shows each account's type, if it's known.  (See
-       Declaring accounts > Account types.)
-
-       With --positions, it also shows the file and line number  of  each  ac-
-       count's  declaration, if any, and the account's overall declaration or-
-       der; these may be useful when troubleshooting account display order.
-
-       With --directives, it adds the account keyword, showing  valid  account
-       directives which can be pasted into a journal file.  This is useful to-
-       gether  with  --undeclared  when  updating your account declarations to
-       satisfy hledger check accounts.
-
-       The --find flag can be used to look up a single account  name,  in  the
-       same  way that the aregister command does.  It returns the alphanumeri-
-       cally-first matched account name, or if none can  be  found,  it  fails
-       with a non-zero exit code.
-
-       Examples:
-
-              $ hledger accounts
-              assets:bank:checking
-              assets:bank:saving
-              assets:cash
-              expenses:food
-              expenses:supplies
-              income:gifts
-              income:salary
-              liabilities:debts
-
-              $ hledger accounts --undeclared --directives >> $LEDGER_FILE
-              $ hledger check accounts
-
-   codes
-       List the codes seen in transactions, in the order parsed.
-
-              Flags:
-              no command-specific flags
-
-       This  command prints the value of each transaction's code field, in the
-       order transactions were parsed.  The transaction code  is  an  optional
-       value  written  in  parentheses between the date and description, often
-       used to store a cheque number, order number or similar.
-
-       Transactions aren't required to have a code, and missing or empty codes
-       will not be shown by default.  With the -E/--empty flag, they  will  be
-       printed as blank lines.
-
-       You can add a query to select a subset of transactions.
-
-       Examples:
-
-              2022/1/1 (123) Supermarket
-               Food       $5.00
-               Checking
-
-              2022/1/2 (124) Post Office
-               Postage    $8.32
-               Checking
-
-              2022/1/3 Supermarket
-               Food      $11.23
-               Checking
-
-              2022/1/4 (126) Post Office
-               Postage    $3.21
-               Checking
-
-              $ hledger codes
-              123
-              124
-              126
-
-              $ hledger codes -E
-              123
-              124
-
-              126
-
-   commodities
-       List all commodity/currency symbols used or declared in the journal.
-
-              Flags:
-              no command-specific flags
-
-   descriptions
-       List the unique descriptions that appear in transactions.
-
-              Flags:
-              no command-specific flags
-
-       This command lists the unique descriptions that appear in transactions,
-       in  alphabetic order.  You can add a query to select a subset of trans-
-       actions.
-
-       Example:
-
-              $ hledger descriptions
-              Store Name
-              Gas Station | Petrol
-              Person A
-
-   files
-       List all files included in the journal.  With a  REGEX  argument,  only
-       file names matching the regular expression (case sensitive) are shown.
-
-              Flags:
-              no command-specific flags
-
-   notes
-       List the unique notes that appear in transactions.
-
-              Flags:
-              no command-specific flags
-
-       This command lists the unique notes that appear in transactions, in al-
-       phabetic  order.   You  can  add a query to select a subset of transac-
-       tions.  The note is the part of the transaction description after  a  |
-       character (or if there is no |, the whole description).
-
-       Example:
-
-              $ hledger notes
-              Petrol
-              Snacks
-
-   payees
-       List the unique payee/payer names that appear in transactions.
-
-              Flags:
-                   --declared             show payees declared with payee directives
-                   --used                 show payees referenced by transactions
-
-       This  command  lists  unique payee/payer names which have been declared
-       with payee directives (--declared), used  in  transaction  descriptions
-       (--used), or both (the default).
-
-       The  payee/payer  is the part of the transaction description before a |
-       character (or if there is no |, the whole description).
-
-       You can add query arguments to select a subset of  transactions.   This
-       implies --used.
-
-       Example:
-
-              $ hledger payees
-              Store Name
-              Gas Station
-              Person A
-
-   prices
-       Print  the market prices declared with P directives.  With --infer-mar-
-       ket-prices, also show any additional prices inferred from costs.   With
-       --show-reverse, also show additional prices inferred by reversing known
-       prices.
-
-              Flags:
-                   --show-reverse         also show the prices inferred by reversing known
-                                          prices
-
-       Price  amounts  are  always displayed with their full precision, except
-       for reverse prices which are limited to 8 decimal digits.
-
-       Prices can be filtered by a date:, cur: or amt: query.
-
-       Generally if you run this command with --infer-market-prices --show-re-
-       verse, it will show the same prices used internally to calculate  value
-       reports.   But  if  in doubt, you can inspect those directly by running
-       the value report with --debug=2.
-
-   stats
-       Show journal and performance statistics.
-
-              Flags:
-                -v --verbose              show more detailed output
-                -o --output-file=FILE     write output to FILE.
-
-       The stats command shows summary information for the whole journal, or a
-       matched part of it.  With a reporting interval, it shows a  report  for
-       each report period.
-
-       The  default  output  is  fairly impersonal, though it reveals the main
-       file name.  With -v/--verbose, more details are shown, like file paths,
-       included files, and commodity names.
-
-       It also shows some run time statistics:
-
-       o elapsed time
-
-       o throughput: the number of transactions processed per second
-
-       o live: the peak memory in use by the program to do its work
-
-       o alloc: the peak memory allocation from the OS as seen by  GHC.   Mea-
-         suring  this  externally, eg with GNU time, is more accurate; usually
-         that will be a larger number; sometimes (with swapping?)  smaller.
-
-       The stats command's run time is similar to that of a balance report.
-
-       Example:
-
-              $ hledger stats -f examples/1ktxns-1kaccts.journal
-              Main file           : .../1ktxns-1kaccts.journal
-              Included files      : 0
-              Txns span           : 2000-01-01 to 2002-09-27 (1000 days)
-              Last txn            : 2002-09-26 (7827 days ago)
-              Txns                : 1000 (1.0 per day)
-              Txns last 30 days   : 0 (0.0 per day)
-              Txns last 7 days    : 0 (0.0 per day)
-              Payees/descriptions : 1000
-              Accounts            : 1000 (depth 10)
-              Commodities         : 26
-              Market prices       : 1000
-              Runtime stats       : 0.12 s elapsed, 8266 txns/s, 4 MB live, 16 MB alloc
-
-       This command supports the -o/--output-file option  (but  not  -O/--out-
-       put-format).
-
-   tags
-       List the tags used in the journal, or their values.
-
-              Flags:
-                   --values               list tag values instead of tag names
-                   --parsed               show tags/values in the order they were parsed,
-                                          including duplicates
-
-       This command lists the tag names used in the journal, whether on trans-
-       actions, postings, or account declarations.
-
-       With  a TAGREGEX argument, only tag names matching this regular expres-
-       sion (case insensitive, infix matched) are shown.
-
-       With QUERY arguments, only  transactions  and  accounts  matching  this
-       query are considered.  If the query involves transaction fields (date:,
-       desc:, amt:, ...), the search is restricted to the matched transactions
-       and their accounts.
-
-       With  the  --values  flag, the tags' unique non-empty values are listed
-       instead.  With -E/--empty, blank/empty values are also shown.
-
-       With --parsed, tags or values are shown in the order they were  parsed,
-       with  duplicates included.  (Except, tags from account declarations are
-       always shown first.)
-
-       Tip: remember, accounts also acquire tags from their parents,  postings
-       also acquire tags from their account and transaction, transactions also
-       acquire tags from their postings.
-
-Standard report commands
-   print
-       Show full journal entries, representing transactions.
-
-              Flags:
-                -x --explicit             show all amounts explicitly
-                   --show-costs           show transaction prices even with conversion
-                                          postings
-                   --round=TYPE           how much rounding or padding should be done when
-                                          displaying amounts ?
-                                          none - show original decimal digits,
-                                                 as in journal
-                                          soft - just add or remove decimal zeros
-                                                 to match precision (default)
-                                          hard - round posting amounts to precision
-                                                 (can unbalance transactions)
-                                          all  - also round cost amounts to precision
-                                                 (can unbalance transactions)
-                   --new                  show only newer-dated transactions added in each
-                                          file since last run
-                -m --match=DESC           fuzzy search for one recent transaction with
-                                          description closest to DESC
-                   --base-url=URLPREFIX   in html output, generate links to hledger-web,
-                                          with this prefix. (Usually the base url shown by
-                                          hledger-web; can also be relative.)
-                -O --output-format=FMT    select the output format. Supported formats:
-                                          txt, beancount, csv, tsv, html, fods, json, sql.
-                -o --output-file=FILE     write output to FILE. A file extension matching
-                                          one of the above formats selects that format.
-
-       The print command displays full journal entries (transactions) from the
-       journal file, sorted by date (or with --date2, by secondary date).
-
-       Directives  and  inter-transaction  comments  are not shown, currently.
-       This means the print command is somewhat lossy, and if you are using it
-       to reformat/regenerate your journal you should take care to  also  copy
-       over the directives and inter-transaction comments.
-
-       Eg:
-
-              $ hledger print -f examples/sample.journal date:200806
-              2008/06/01 gift
-                  assets:bank:checking            $1
-                  income:gifts                   $-1
-
-              2008/06/02 save
-                  assets:bank:saving              $1
-                  assets:bank:checking           $-1
-
-              2008/06/03 * eat & shop
-                  expenses:food                $1
-                  expenses:supplies            $1
-                  assets:cash                 $-2
-
-   print explicitness
-       Normally,  whether  posting  amounts  are  implicit or explicit is pre-
-       served.  For example, when an amount is omitted in the journal, it will
-       not appear in the output.  Similarly, if a conversion cost  is  implied
-       but not written, it will not appear in the output.
-
-       You  can  use  the  -x/--explicit flag to force explicit display of all
-       amounts and costs.  This can be useful for troubleshooting or for  mak-
-       ing  your  journal  more readable and robust against data entry errors.
-       -x is also implied by using any of -B,-V,-X,--value.
-
-       The -x/--explicit flag will cause any postings with  a  multi-commodity
-       amount  (which  can arise when a multi-commodity transaction has an im-
-       plicit amount) to be split  into  multiple  single-commodity  postings,
-       keeping the output parseable.
-
-   print amount style
-       Amounts  are  shown  right-aligned  within  each  transaction  (but not
-       aligned across all transactions; you can do that  with  ledger-mode  in
-       Emacs).
-
-       Amounts  will  be (mostly) normalised to their commodity display style:
-       their symbol placement, decimal mark, and digit  group  marks  will  be
-       made  consistent.   By  default,  decimal  digits are shown as they are
-       written in the journal.
-
-       With the --round (Added in 1.32) option, print  will  try  increasingly
-       hard  to  display  decimal  digits  according  to the commodity display
-       styles:
-
-       o --round=none show amounts with original precisions (default)
-
-       o --round=soft add/remove decimal zeros in amounts (except costs)
-
-       o --round=hard round amounts (except costs), possibly  hiding  signifi-
-         cant digits
-
-       o --round=all round all amounts and costs
-
-       soft  is  good  for  non-lossy cleanup, formatting amounts more consis-
-       tently where it's safe to do so.
-
-       hard and all can cause print to show  invalid  unbalanced  journal  en-
-       tries;  they  may be useful eg for stronger cleanup, with manual fixups
-       when needed.
-
-   print parseability
-       print's output is usually a valid hledger journal, and you can  process
-       it again with a second hledger command.  This can be useful for certain
-       kinds  of  search  (though  the same can be achieved with expr: queries
-       now):
-
-              # Show running total of food expenses paid from cash.
-              # -f- reads from stdin. -I/--ignore-assertions is sometimes needed.
-              $ hledger print assets:cash | hledger -f- -I reg expenses:food
-
-       There are some situations where print's output can become unparseable:
-
-       o Value reporting affects posting amounts but not balance assertion  or
-         balance assignment amounts, potentially causing those to fail.
-
-       o Auto postings can generate postings with too many missing amounts.
-
-       o Account aliases can generate bad account names.
-
-   print, other features
-       With -B/--cost, amounts with costs are shown converted to cost.
-
-       With --new, print shows only transactions it has not seen on a previous
-       run.   This  uses  the same deduplication system as the import command.
-       (See import's docs for details.)
-
-       With -m DESC/--match=DESC, print shows one recent transaction whose de-
-       scription is most similar to DESC.  DESC should contain  at  least  two
-       characters.   If  there is no similar-enough match, no transaction will
-       be shown and the program exit code will be non-zero.
-
-   print output format
-       This command also supports the output destination and output format op-
-       tions The output formats supported are txt, beancount (Added in  1.32),
-       csv, tsv (Added in 1.32), json and sql.
-
-       The  beancount  format tries to produce Beancount-compatible output, as
-       follows:
-
-       o Transaction and  postings  with  unmarked  status  are  converted  to
-         cleared (*) status.
-
-       o Transactions'   payee   and   note  are  backslash-escaped  and  dou-
-         ble-quote-escaped and wrapped in double quotes.
-
-       o Transaction tags are copied to Beancount #tag format.
-
-       o Commodity symbols are converted to upper case, and a small number  of
-         currency  symbols  like $ are converted to the corresponding currency
-         names.
-
-       o Account name parts are capitalised and unsupported characters are re-
-         placed with -.  If an account name part does not begin with a letter,
-         or if the first part is not Assets, Liabilities, Equity,  Income,  or
-         Expenses, an error is raised.  (Use --alias options to bring your ac-
-         counts into compliance.)
-
-       o An open directive is generated for each account used, on the earliest
-         transaction date.
-
-       Some limitations:
-
-       o Balance assertions are removed.
-
-       o Balance assignments become missing amounts.
-
-       o Virtual and balanced virtual postings become regular postings.
-
-       o Directives are not converted.
-
-       Here's an example of print's CSV output:
-
-              $ hledger print -Ocsv
-              "txnidx","date","date2","status","code","description","comment","account","amount","commodity","credit","debit","posting-status","posting-comment"
-              "1","2008/01/01","","","","income","","assets:bank:checking","1","$","","1","",""
-              "1","2008/01/01","","","","income","","income:salary","-1","$","1","","",""
-              "2","2008/06/01","","","","gift","","assets:bank:checking","1","$","","1","",""
-              "2","2008/06/01","","","","gift","","income:gifts","-1","$","1","","",""
-              "3","2008/06/02","","","","save","","assets:bank:saving","1","$","","1","",""
-              "3","2008/06/02","","","","save","","assets:bank:checking","-1","$","1","","",""
-              "4","2008/06/03","","*","","eat & shop","","expenses:food","1","$","","1","",""
-              "4","2008/06/03","","*","","eat & shop","","expenses:supplies","1","$","","1","",""
-              "4","2008/06/03","","*","","eat & shop","","assets:cash","-2","$","2","","",""
-              "5","2008/12/31","","*","","pay off","","liabilities:debts","1","$","","1","",""
-              "5","2008/12/31","","*","","pay off","","assets:bank:checking","-1","$","1","","",""
-
-       o There  is  one  CSV record per posting, with the parent transaction's
-         fields repeated.
-
-       o The "txnidx" (transaction index) field shows which postings belong to
-         the same transaction.  (This number might change if transactions  are
-         reordered  within  the file, files are parsed/included in a different
-         order, etc.)
-
-       o The amount is separated into "commodity" (the  symbol)  and  "amount"
-         (numeric quantity) fields.
-
-       o The numeric amount is repeated in either the "credit" or "debit" col-
-         umn,  for convenience.  (Those names are not accurate in the account-
-         ing sense; it just puts negative amounts under  credit  and  zero  or
-         greater amounts under debit.)
-
-   aregister
-       (areg)
-
-       Show  the  transactions  and running balances in one account, with each
-       transaction on one line.
-
-              Flags:
-                   --txn-dates            filter strictly by transaction date, not posting
-                                          date. Warning: this can show a wrong running
-                                          balance.
-                   --no-elide             don't show only 2 commodities per amount
-                   --cumulative           show running total from report start date
-                -H --historical           show historical running total/balance (includes
-                                          postings before report start date) (default)
-
-                   --invert               display all amounts with reversed sign
-                   --heading=YN           show heading row above table: yes (default) or no
-                -w --width=N              set output width (default: terminal width or
-                                          $COLUMNS). -wN,M sets description width as well.
-                   --align-all            guarantee alignment across all lines (slower)
-                -O --output-format=FMT    select the output format. Supported formats:
-                                          txt, html, csv, tsv, json.
-                -o --output-file=FILE     write output to FILE. A file extension matching
-                                          one of the above formats selects that format.
-
-       aregister shows the overall transactions affecting a particular account
-       (and any subaccounts).  Each report line represents one transaction  in
-       this  account.   Transactions before the report start date are included
-       in the running balance (--historical mode is  the  default).   You  can
-       suppress this behaviour using the --cumulative option.
-
-       This  is  a more "real world", bank-like view than the register command
-       (which shows individual postings, possibly from multiple accounts,  not
-       necessarily in historical mode).  As a quick rule of thumb: - use areg-
-       ister for reviewing and reconciling real-world asset/liability accounts
-       - use register for reviewing detailed revenues/expenses.
-
-       aregister  requires  one  argument:  the account to report on.  You can
-       write either the full account name, or a case-insensitive  regular  ex-
-       pression which will select the alphabetically first matched account.
-
-       When there are multiple matches, the alphabetically-first choice can be
-       surprising;  eg if you have assets:per:checking 1 and assets:biz:check-
-       ing 2 accounts, hledger areg checking would select  assets:biz:checking
-       2.   It's  just a convenience to save typing, so if in doubt, write the
-       full account name, or a distinctive substring that matches uniquely.
-
-       Transactions involving subaccounts of this account will also be  shown.
-       aregister  ignores depth limits, so its final total will always match a
-       balance report with similar arguments.
-
-       Any additional arguments form a query which will  filter  the  transac-
-       tions shown.  Note some queries will disturb the running balance, caus-
-       ing it to be different from the account's real-world running balance.
-
-       An  example: this shows the transactions and historical running balance
-       during july, in the first account whose name contains "checking":
-
-              $ hledger areg checking date:jul
-
-       Each aregister line item shows:
-
-       o the transaction's date (or the relevant posting's date if  different,
-         see below)
-
-       o the  names  of  all the other account(s) involved in this transaction
-         (probably abbreviated)
-
-       o the total change to this account's balance from this transaction
-
-       o the account's historical running balance after this transaction.
-
-       Transactions making a net change of zero are not shown by default;  add
-       the -E/--empty flag to show them.
-
-       For  performance  reasons,  column widths are chosen based on the first
-       1000 lines; this means unusually wide values in later lines  can  cause
-       visual  discontinuities  as column widths are adjusted.  If you want to
-       ensure perfect alignment, at the cost of more time and memory, use  the
-       --align-all flag.
-
-       By  default,  aregister  shows a heading above the data.  However, when
-       reporting in a language different from English, it is  easier  to  omit
-       this  heading  and  prepend  your  own  one.  For this purpose, use the
-       --heading=no option.
-
-       This command also supports the output destination and output format op-
-       tions.  The output formats supported are txt, csv, tsv (Added in 1.32),
-       html, fods (Added in 1.41) and json.
-
-   aregister and posting dates
-       aregister always shows one line (and date and amount) per  transaction.
-       But  sometimes  transactions have postings with different dates.  Also,
-       not all of a transaction's postings may be within  the  report  period.
-       To resolve this, aregister shows the earliest of the transaction's date
-       and posting dates that is in-period, and the sum of the in-period post-
-       ings.   In  other words it will show a combined line item with just the
-       earliest date, and the running balance  will  (temporarily,  until  the
-       transaction's last posting) be inaccurate.  Use register -H if you need
-       to see the individual postings.
-
-       There is also a --txn-dates flag, which filters strictly by transaction
-       date, ignoring posting dates.  This too can cause an inaccurate running
-       balance.
-
-   register
-       (reg)
-
-       Show postings and their running total.
-
-              Flags:
-                   --cumulative           show running total from report start date
-                                          (default)
-                -H --historical           show historical running total/balance (includes
-                                          postings before report start date)
-                -A --average              show running average of posting amounts instead
-                                          of total (implies --empty)
-                -m --match=DESC           fuzzy search for one recent posting with
-                                          description closest to DESC
-                -r --related              show postings' siblings instead
-                   --invert               display all amounts with reversed sign
-                   --sort=FIELDS          sort by: date, desc, account, amount, absamount,
-                                          or a comma-separated combination of these. For a
-                                          descending sort, prefix with -. (Default: date)
-                -w --width=N              set output width (default: terminal width or
-                                          $COLUMNS). -wN,M sets description width as well.
-                   --align-all            guarantee alignment across all lines (slower)
-                   --base-url=URLPREFIX   in html output, generate links to hledger-web,
-                                          with this prefix. (Usually the base url shown by
-                                          hledger-web; can also be relative.)
-                -O --output-format=FMT    select the output format. Supported formats:
-                                          txt, csv, tsv, html, fods, json.
-                -o --output-file=FILE     write output to FILE. A file extension matching
-                                          one of the above formats selects that format.
-
-       The register command displays matched postings, across all accounts, in
-       date  order,  with  their  running total or running historical balance.
-       (See also the aregister command, which shows matched transactions in  a
-       specific account.)
-
-       register normally shows line per posting, but note that multi-commodity
-       amounts will occupy multiple lines (one line per commodity).
-
-       It  is  typically  used with a query selecting a particular account, to
-       see that account's activity:
-
-              $ hledger register checking
-              2008/01/01 income               assets:bank:checking            $1           $1
-              2008/06/01 gift                 assets:bank:checking            $1           $2
-              2008/06/02 save                 assets:bank:checking           $-1           $1
-              2008/12/31 pay off              assets:bank:checking           $-1            0
-
-       With --date2, it shows and sorts by secondary date instead.
-
-       For performance reasons, column widths are chosen based  on  the  first
-       1000  lines;  this means unusually wide values in later lines can cause
-       visual discontinuities as column widths are adjusted.  If you  want  to
-       ensure  perfect alignment, at the cost of more time and memory, use the
-       --align-all flag.
-
-       The --historical/-H flag adds the balance from  any  undisplayed  prior
-       postings  to  the  running  total.  This is useful when you want to see
-       only recent activity, with a historically accurate running balance:
-
-              $ hledger register checking -b 2008/6 --historical
-              2008/06/01 gift                 assets:bank:checking            $1           $2
-              2008/06/02 save                 assets:bank:checking           $-1           $1
-              2008/12/31 pay off              assets:bank:checking           $-1            0
-
-       The --depth option limits the amount of sub-account detail displayed.
-
-       The --average/-A flag shows the running average posting amount  instead
-       of the running total (so, the final number displayed is the average for
-       the  whole  report period).  This flag implies --empty (see below).  It
-       is affected by --historical.  It works best when showing just  one  ac-
-       count and one commodity.
-
-       The  --related/-r  flag shows the other postings in the transactions of
-       the postings which would normally be shown.
-
-       The --invert flag negates all amounts.  For example, it can be used  on
-       an income account where amounts are normally displayed as negative num-
-       bers.   It's  also  useful to show postings on the checking account to-
-       gether with the related account:
-
-       The --sort=FIELDS flag sorts by the fields given, which can be  any  of
-       account, amount, absamount, date, or desc/description, optionally sepa-
-       rated  by  commas.   For  example, --sort account,amount will group all
-       transactions in each account, sorted by transaction amount.  Each field
-       can be negated by a preceding -, so --sort -amount will  show  transac-
-       tions ordered from smallest amount to largest amount.
-
-              $ hledger register --related --invert assets:checking
-
-       With a reporting interval, register shows summary postings, one per in-
-       terval, aggregating the postings to each account:
-
-              $ hledger register --monthly income
-              2008/01                 income:salary                          $-1          $-1
-              2008/06                 income:gifts                           $-1          $-2
-
-       Periods  with no activity, and summary postings with a zero amount, are
-       not shown by default; use the --empty/-E flag to see them:
-
-              $ hledger register --monthly income -E
-              2008/01                 income:salary                          $-1          $-1
-              2008/02                                                          0          $-1
-              2008/03                                                          0          $-1
-              2008/04                                                          0          $-1
-              2008/05                                                          0          $-1
-              2008/06                 income:gifts                           $-1          $-2
-              2008/07                                                          0          $-2
-              2008/08                                                          0          $-2
-              2008/09                                                          0          $-2
-              2008/10                                                          0          $-2
-              2008/11                                                          0          $-2
-              2008/12                                                          0          $-2
-
-       Often, you'll want to see just one line per interval.  The --depth  op-
-       tion helps with this, causing subaccounts to be aggregated:
-
-              $ hledger register --monthly assets --depth 1h
-              2008/01                 assets                                  $1           $1
-              2008/06                 assets                                 $-1            0
-              2008/12                 assets                                 $-1          $-1
-
-       Note  when using report intervals, if you specify start/end dates these
-       will be adjusted outward if necessary to contain a whole number of  in-
-       tervals.   This  ensures  that  the  first  and last intervals are full
-       length and comparable to the others in the report.
-
-       With -m DESC/--match=DESC, register does a fuzzy search for one  recent
-       posting whose description is most similar to DESC.  DESC should contain
-       at least two characters.  If there is no similar-enough match, no post-
-       ing 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 can override this by setting the COLUMNS environment variable  (not
-       a 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 de-
-       scription width as part of --width's argument, comma-separated: --width
-       W,D .  Here's a diagram (won't display correctly in --help):
-
-              <--------------------------------- width (W) ---------------------------------->
-              date (10)  description (D)       account (W-41-D)     amount (12)   balance (12)
-              DDDDDDDDDD dddddddddddddddddddd  aaaaaaaaaaaaaaaaaaa  AAAAAAAAAAAA  AAAAAAAAAAAA
-
-       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 op-
-       tions The output formats supported are txt, csv, tsv (Added  in  1.32),
-       and json.
-
-   balancesheet
-       (bs)
-
-       Show  the  end  balances  in asset and liability accounts.  Amounts are
-       shown with normal positive sign, as in  conventional  financial  state-
-       ments.
-
-              Flags:
-                   --sum                  show sum of posting amounts (default)
-                   --valuechange          show total change of period-end historical
-                                          balance value (caused by deposits, withdrawals,
-                                          market price fluctuations)
-                   --gain                 show unrealised capital gain/loss (historical
-                                          balance value minus cost basis)
-                   --budget               show sum of posting amounts compared to budget
-                                          goals defined by periodic transactions
-                   --count                show the count of postings
-                   --change               accumulate amounts from column start to column
-                                          end (in multicolumn reports)
-                   --cumulative           accumulate amounts from report start (specified
-                                          by e.g. -b/--begin) to column end
-                -H --historical           accumulate amounts from journal start to column
-                                          end (includes postings before report start date)
-                                          (default)
-                -l --flat                 show accounts as a flat list (default). Amounts
-                                          exclude subaccount amounts, except where the
-                                          account is depth-clipped.
-                -t --tree                 show accounts as a tree. Amounts include
-                                          subaccount amounts.
-                   --drop=N               flat mode: omit N leading account name parts
-                   --declared             include non-parent declared accounts (best used
-                                          with -E)
-                -A --average              show a row average column (in multicolumn
-                                          reports)
-                -T --row-total            show a row total column (in multicolumn reports)
-                   --summary-only         display only row summaries (e.g. row total,
-                                          average) (in multicolumn reports)
-                -N --no-total             omit the final total row
-                   --no-elide             don't squash boring parent accounts (in tree
-                                          mode)
-                   --format=FORMATSTR     use this custom line format (in simple reports)
-                -S --sort-amount          sort by amount instead of account code/name
-                -% --percent              express values in percentage of each column's
-                                          total
-                   --layout=ARG           how to show multi-commodity amounts:
-                                          'wide[,WIDTH]': all commodities on one line
-                                          'tall'        : each commodity on a new line
-                                          'bare'        : bare numbers, symbols in a column
-                   --base-url=URLPREFIX   in html output, generate hyperlinks to
-                                          hledger-web, with this prefix. (Usually the base
-                                          url shown by hledger-web; can also be relative.)
-                -O --output-format=FMT    select the output format. Supported formats:
-                                          txt, html, csv, tsv, json.
-                -o --output-file=FILE     write output to FILE. A file extension matching
-                                          one of the above formats selects that format.
-
-       This  command  displays a balance sheet, showing historical ending bal-
-       ances of asset and liability accounts.  (To see equity as well, use the
-       balancesheetequity command.)
-
-       Accounts declared with the Asset, Cash or Liability type are shown (see
-       account types).   Or  if  no  such  accounts  are  declared,  it  shows
-       top-level  accounts named asset or liability (case insensitive, plurals
-       allowed) and their subaccounts.
-
-       Example:
-
-              $ hledger balancesheet
-              Balance Sheet 2008-12-31
-
-                                  || 2008-12-31
-              ====================++============
-               Assets             ||
-              --------------------++------------
-               assets:bank:saving ||         $1
-               assets:cash        ||        $-2
-              --------------------++------------
-                                  ||        $-1
-              ====================++============
-               Liabilities        ||
-              --------------------++------------
-               liabilities:debts  ||        $-1
-              --------------------++------------
-                                  ||        $-1
-              ====================++============
-               Net:               ||          0
-
-       This command is a higher-level variant of the balance command, and sup-
-       ports many of that command's features, such  as  multi-period  reports.
-       It  is  similar  to  hledger  balance  -H  assets liabilities, but with
-       smarter account detection, and liabilities displayed  with  their  sign
-       flipped.
-
-       This command also supports the output destination and output format op-
-       tions  The  output formats supported are txt, csv, tsv (Added in 1.32),
-       html, and json.
-
-   balancesheetequity
-       (bse)
-
-       This command displays a balance sheet, showing historical  ending  bal-
-       ances  of asset, liability and equity accounts.  Amounts are shown with
-       normal positive sign, as in conventional financial statements.
-
-              Flags:
-                   --sum                  show sum of posting amounts (default)
-                   --valuechange          show total change of period-end historical
-                                          balance value (caused by deposits, withdrawals,
-                                          market price fluctuations)
-                   --gain                 show unrealised capital gain/loss (historical
-                                          balance value minus cost basis)
-                   --budget               show sum of posting amounts compared to budget
-                                          goals defined by periodic transactions
-                   --count                show the count of postings
-                   --change               accumulate amounts from column start to column
-                                          end (in multicolumn reports)
-                   --cumulative           accumulate amounts from report start (specified
-                                          by e.g. -b/--begin) to column end
-                -H --historical           accumulate amounts from journal start to column
-                                          end (includes postings before report start date)
-                                          (default)
-                -l --flat                 show accounts as a flat list (default). Amounts
-                                          exclude subaccount amounts, except where the
-                                          account is depth-clipped.
-                -t --tree                 show accounts as a tree. Amounts include
-                                          subaccount amounts.
-                   --drop=N               flat mode: omit N leading account name parts
-                   --declared             include non-parent declared accounts (best used
-                                          with -E)
-                -A --average              show a row average column (in multicolumn
-                                          reports)
-                -T --row-total            show a row total column (in multicolumn reports)
-                   --summary-only         display only row summaries (e.g. row total,
-                                          average) (in multicolumn reports)
-                -N --no-total             omit the final total row
-                   --no-elide             don't squash boring parent accounts (in tree
-                                          mode)
-                   --format=FORMATSTR     use this custom line format (in simple reports)
-                -S --sort-amount          sort by amount instead of account code/name
-                -% --percent              express values in percentage of each column's
-                                          total
-                   --layout=ARG           how to show multi-commodity amounts:
-                                          'wide[,WIDTH]': all commodities on one line
-                                          'tall'        : each commodity on a new line
-                                          'bare'        : bare numbers, symbols in a column
-                   --base-url=URLPREFIX   in html output, generate hyperlinks to
-                                          hledger-web, with this prefix. (Usually the base
-                                          url shown by hledger-web; can also be relative.)
-                -O --output-format=FMT    select the output format. Supported formats:
-                                          txt, html, csv, tsv, json.
-                -o --output-file=FILE     write output to FILE. A file extension matching
-                                          one of the above formats selects that format.
-
-       This report shows accounts declared with the Asset, Cash, Liability  or
-       Equity  type (see account types).  Or if no such accounts are declared,
-       it shows top-level accounts named asset, liability or equity (case  in-
-       sensitive, plurals allowed) and their subaccounts.
-
-       Example:
-
-              $ hledger balancesheetequity
-              Balance Sheet With Equity 2008-12-31
-
-                                  || 2008-12-31
-              ====================++============
-               Assets             ||
-              --------------------++------------
-               assets:bank:saving ||         $1
-               assets:cash        ||        $-2
-              --------------------++------------
-                                  ||        $-1
-              ====================++============
-               Liabilities        ||
-              --------------------++------------
-               liabilities:debts  ||        $-1
-              --------------------++------------
-                                  ||        $-1
-              ====================++============
-               Equity             ||
-              --------------------++------------
-              --------------------++------------
-                                  ||          0
-              ====================++============
-               Net:               ||          0
-
-       This command is a higher-level variant of the balance command, and sup-
-       ports  many  of  that command's features, such as multi-period reports.
-       It is similar to hledger balance -H assets liabilities equity, but with
-       smarter account detection, and liabilities/equity displayed with  their
-       sign flipped.
-
-       This report is the easiest way to see if the accounting equation (A+L+E
-       =  0)  is satisfied (after you have done a close --retain to merge rev-
-       enues and expenses with equity, and  perhaps  added  --infer-equity  to
-       balance your commodity conversions).
-
-       This command also supports the output destination and output format op-
-       tions The output formats supported are txt, csv, tsv, html, and json.
-
-   cashflow
-       (cf)
-
-       This  command  displays  a (simple) cashflow statement, showing the in-
-       flows and outflows affecting "cash" (ie,  liquid,  easily  convertible)
-       assets.   Amounts  are  shown  with normal positive sign, as in conven-
-       tional financial statements.
-
-              Flags:
-                   --sum                  show sum of posting amounts (default)
-                   --valuechange          show total change of period-end historical
-                                          balance value (caused by deposits, withdrawals,
-                                          market price fluctuations)
-                   --gain                 show unrealised capital gain/loss (historical
-                                          balance value minus cost basis)
-                   --budget               show sum of posting amounts compared to budget
-                                          goals defined by periodic transactions
-                   --count                show the count of postings
-                   --change               accumulate amounts from column start to column
-                                          end (in multicolumn reports) (default)
-                   --cumulative           accumulate amounts from report start (specified
-                                          by e.g. -b/--begin) to column end
-                -H --historical           accumulate amounts from journal start to column
-                                          end (includes postings before report start date)
-                -l --flat                 show accounts as a flat list (default). Amounts
-                                          exclude subaccount amounts, except where the
-                                          account is depth-clipped.
-                -t --tree                 show accounts as a tree. Amounts include
-                                          subaccount amounts.
-                   --drop=N               flat mode: omit N leading account name parts
-                   --declared             include non-parent declared accounts (best used
-                                          with -E)
-                -A --average              show a row average column (in multicolumn
-                                          reports)
-                -T --row-total            show a row total column (in multicolumn reports)
-                   --summary-only         display only row summaries (e.g. row total,
-                                          average) (in multicolumn reports)
-                -N --no-total             omit the final total row
-                   --no-elide             don't squash boring parent accounts (in tree
-                                          mode)
-                   --format=FORMATSTR     use this custom line format (in simple reports)
-                -S --sort-amount          sort by amount instead of account code/name
-                -% --percent              express values in percentage of each column's
-                                          total
-                   --layout=ARG           how to show multi-commodity amounts:
-                                          'wide[,WIDTH]': all commodities on one line
-                                          'tall'        : each commodity on a new line
-                                          'bare'        : bare numbers, symbols in a column
-                   --base-url=URLPREFIX   in html output, generate hyperlinks to
-                                          hledger-web, with this prefix. (Usually the base
-                                          url shown by hledger-web; can also be relative.)
-                -O --output-format=FMT    select the output format. Supported formats:
-                                          txt, html, csv, tsv, json.
-                -o --output-file=FILE     write output to FILE. A file extension matching
-                                          one of the above formats selects that format.
-
-       This report shows accounts declared with the  Cash  type  (see  account
-       types).  Or if no such accounts are declared, it shows accounts
-
-       o under  a  top-level account named asset (case insensitive, plural al-
-         lowed)
-
-       o whose name contains some variation of cash, bank, checking or saving.
-
-       More precisely: all accounts matching this case insensitive regular ex-
-       pression:
-
-       ^assets?(:.+)?:(cash|bank|che(ck|que?)(ing)?|savings?|currentcash)(:|$)
-
-       and their subaccounts.
-
-       An example cashflow report:
-
-              $ hledger cashflow
-              Cashflow Statement 2008
-
-                                  || 2008
-              ====================++======
-               Cash flows         ||
-              --------------------++------
-               assets:bank:saving ||   $1
-               assets:cash        ||  $-2
-              --------------------++------
-                                  ||  $-1
-
-       This command is a higher-level variant of the balance command, and sup-
-       ports many of that command's features, such  as  multi-period  reports.
-       It  is  similar  to  hledger  balance  assets  not:fixed not:investment
-       not:receivable, but with smarter account detection.
-
-       This command also supports the output destination and output format op-
-       tions The output formats supported are txt, csv, tsv (Added  in  1.32),
-       html, and json.
-
-   incomestatement
-       (is)
-
-       Show  revenue  inflows  and  expense outflows during the report period.
-       Amounts are shown with normal positive sign, as in conventional  finan-
-       cial statements.
-
-              Flags:
-                   --sum                  show sum of posting amounts (default)
-                   --valuechange          show total change of period-end historical
-                                          balance value (caused by deposits, withdrawals,
-                                          market price fluctuations)
-                   --gain                 show unrealised capital gain/loss (historical
-                                          balance value minus cost basis)
-                   --budget               show sum of posting amounts compared to budget
-                                          goals defined by periodic transactions
-                   --count                show the count of postings
-                   --change               accumulate amounts from column start to column
-                                          end (in multicolumn reports) (default)
-                   --cumulative           accumulate amounts from report start (specified
-                                          by e.g. -b/--begin) to column end
-                -H --historical           accumulate amounts from journal start to column
-                                          end (includes postings before report start date)
-                -l --flat                 show accounts as a flat list (default). Amounts
-                                          exclude subaccount amounts, except where the
-                                          account is depth-clipped.
-                -t --tree                 show accounts as a tree. Amounts include
-                                          subaccount amounts.
-                   --drop=N               flat mode: omit N leading account name parts
-                   --declared             include non-parent declared accounts (best used
-                                          with -E)
-                -A --average              show a row average column (in multicolumn
-                                          reports)
-                -T --row-total            show a row total column (in multicolumn reports)
-                   --summary-only         display only row summaries (e.g. row total,
-                                          average) (in multicolumn reports)
-                -N --no-total             omit the final total row
-                   --no-elide             don't squash boring parent accounts (in tree
-                                          mode)
-                   --format=FORMATSTR     use this custom line format (in simple reports)
-                -S --sort-amount          sort by amount instead of account code/name
-                -% --percent              express values in percentage of each column's
-                                          total
-                   --layout=ARG           how to show multi-commodity amounts:
-                                          'wide[,WIDTH]': all commodities on one line
-                                          'tall'        : each commodity on a new line
-                                          'bare'        : bare numbers, symbols in a column
-                   --base-url=URLPREFIX   in html output, generate hyperlinks to
-                                          hledger-web, with this prefix. (Usually the base
-                                          url shown by hledger-web; can also be relative.)
-                -O --output-format=FMT    select the output format. Supported formats:
-                                          txt, html, csv, tsv, json.
-                -o --output-file=FILE     write output to FILE. A file extension matching
-                                          one of the above formats selects that format.
-
-       This  command  displays  an  income statement, showing revenues and ex-
-       penses during one or more periods.
-
-       It shows accounts declared with the Revenue or Expense  type  (see  ac-
-       count  types).  Or if no such accounts are declared, it shows top-level
-       accounts named revenue or income or expense (case insensitive,  plurals
-       allowed) and their subaccounts.
-
-       Example:
-
-              $ hledger incomestatement
-              Income Statement 2008
-
-                                 || 2008
-              ===================++======
-               Revenues          ||
-              -------------------++------
-               income:gifts      ||   $1
-               income:salary     ||   $1
-              -------------------++------
-                                 ||   $2
-              ===================++======
-               Expenses          ||
-              -------------------++------
-               expenses:food     ||   $1
-               expenses:supplies ||   $1
-              -------------------++------
-                                 ||   $2
-              ===================++======
-               Net:              ||    0
-
-       This command is a higher-level variant of the balance command, and sup-
-       ports  many  of  that command's features, such as multi-period reports.
-       It is similar to hledger balance '(revenues|income)' expenses, but with
-       smarter account detection, and  revenues/income  displayed  with  their
-       sign flipped.
-
-       This command also supports the output destination and output format op-
-       tions  The  output formats supported are txt, csv, tsv (Added in 1.32),
-       html, and json.
-
-Advanced report commands
-   balance
-       (bal)
-
-       A flexible, general purpose "summing" report that shows  accounts  with
-       some kind of numeric data.  This can be balance changes per period, end
-       balances, budget performance, unrealised capital gains, etc.
-
-              Flags:
-                   --sum                  show sum of posting amounts (default)
-                   --valuechange          show total change of value of period-end
-                                          historical balances (caused by deposits,
-                                          withdrawals, market price fluctuations)
-                   --gain                 show unrealised capital gain/loss (historical
-                                          balance value minus cost basis)
-                   --budget[=DESCPAT]     show sum of posting amounts together with budget
-                                          goals defined by periodic
-                                          transactions. With a DESCPAT argument (must be
-                                          separated by = not space),
-                                          use only periodic transactions with matching
-                                          description
-                                          (case insensitive substring match).
-                   --count                show the count of postings
-                   --change               accumulate amounts from column start to column
-                                          end (in multicolumn reports, default)
-                   --cumulative           accumulate amounts from report start (specified
-                                          by e.g. -b/--begin) to column end
-                -H --historical           accumulate amounts from journal start to column
-                                          end (includes postings before report start date)
-                -l --flat                 show accounts as a flat list (default). Amounts
-                                          exclude subaccount amounts, except where the
-                                          account is depth-clipped.
-                -t --tree                 show accounts as a tree. Amounts include
-                                          subaccount amounts.
-                   --drop=N               omit N leading account name parts (in flat mode)
-                   --declared             include non-parent declared accounts (best used
-                                          with -E)
-                -A --average              show a row average column (in multicolumn
-                                          reports)
-                -T --row-total            show a row total column (in multicolumn reports)
-                   --summary-only         display only row summaries (e.g. row total,
-                                          average) (in multicolumn reports)
-                -N --no-total             omit the final total row
-                   --no-elide             don't squash boring parent accounts (in tree
-                                          mode)
-                   --format=FORMATSTR     use this custom line format (in simple reports)
-                -S --sort-amount          sort by amount instead of account code/name (in
-                                          flat mode). With multiple columns, sorts by the row
-                                          total, or by row average if that is displayed.
-                -% --percent              express values in percentage of each column's
-                                          total
-                -r --related              show the other accounts transacted with, instead
-                   --invert               display all amounts with reversed sign
-                   --transpose            switch rows and columns (use vertical time axis)
-                   --layout=ARG           how to lay out multi-commodity amounts and the
-                                          overall table:
-                                          'wide[,WIDTH]': commodities on one line
-                                          'tall'        : commodities on separate lines
-                                          'bare'        : commodity symbols in one column
-                                          'tidy'        : every attribute in its own column
-                   --base-url=URLPREFIX   in html output, generate links to hledger-web,
-                                          with this prefix. (Usually the base url shown by
-                                          hledger-web; can also be relative.)
-                -O --output-format=FMT    select the output format. Supported formats:
-                                          txt, html, csv, tsv, json, fods.
-                -o --output-file=FILE     write output to FILE. A file extension matching
-                                          one of the above formats selects that format.
-
-       balance  is  one  of  hledger's oldest and most versatile commands, for
-       listing account balances, balance changes, values,  value  changes  and
-       more, during one time period or many.  Generally it shows a table, with
-       rows representing accounts, and columns representing periods.
-
-       Note  there  are some higher-level variants of the balance command with
-       convenient defaults, which can be simpler to  use:  balancesheet,  bal-
-       ancesheetequity, cashflow and incomestatement.  When you need more con-
-       trol, then use balance.
-
-   balance features
-       Here's  a quick overview of the balance command's features, followed by
-       more detailed descriptions and examples.  Many of these work  with  the
-       higher-level commands as well.
-
-       balance can show..
-
-       o accounts as a list (-l) or a tree (-t)
-
-       o optionally depth-limited (-[1-9])
-
-       o sorted by declaration order and name, or by amount
-
-       ..and their..
-
-       o balance changes (the default)
-
-       o or actual and planned balance changes (--budget)
-
-       o or value of balance changes (-V)
-
-       o or change of balance values (--valuechange)
-
-       o or unrealised capital gain/loss (--gain)
-
-       o or balance changes from sibling postings (--related/-r)
-
-       o or postings count (--count)
-
-       ..in..
-
-       o one time period (the whole journal period by default)
-
-       o or multiple periods (-D, -W, -M, -Q, -Y, -p INTERVAL)
-
-       ..either..
-
-       o per period (the default)
-
-       o or accumulated since report start date (--cumulative)
-
-       o or accumulated since account creation (--historical/-H)
-
-       ..possibly converted to..
-
-       o cost (--value=cost[,COMM]/--cost/-B)
-
-       o or market value, as of transaction dates (--value=then[,COMM])
-
-       o or at period ends (--value=end[,COMM])
-
-       o or now (--value=now)
-
-       o or at some other date (--value=YYYY-MM-DD)
-
-       ..with..
-
-       o totals  (-T),  averages  (-A), percentages (-%), inverted sign (--in-
-         vert)
-
-       o rows and columns swapped (--transpose)
-
-       o another field used as account name (--pivot)
-
-       o custom-formatted line items (single-period reports only) (--format)
-
-       o commodities displayed on the same line or multiple lines (--layout)
-
-       This command supports the output destination and output format options,
-       with output formats txt, csv, tsv (Added in 1.32), json, and (multi-pe-
-       riod reports only:) html, fods (Added in 1.40).  In  txt  output  in  a
-       colour-supporting terminal, negative amounts are shown in red.
-
-   Simple balance report
-       With  no  arguments,  balance  shows  a  list of all accounts and their
-       change of balance - ie, the sum of posting amounts,  both  inflows  and
-       outflows  -  during  the  entire period of the journal.  ("Simple" here
-       means just one column of numbers, covering a single  period.   You  can
-       also have multi-period reports, described later.)
-
-       For  real-world accounts, these numbers will normally be their end bal-
-       ance at the end of the journal period; more on this below.
-
-       Accounts are sorted by declaration order if any,  and  then  alphabeti-
-       cally by account name.  For instance (using examples/sample.journal):
-
-              $ hledger -f examples/sample.journal bal
-                                $1  assets:bank:saving
-                               $-2  assets:cash
-                                $1  expenses:food
-                                $1  expenses:supplies
-                               $-1  income:gifts
-                               $-1  income:salary
-                                $1  liabilities:debts
-              --------------------
-                                 0
-
-       Accounts with a zero balance (and no non-zero subaccounts, in tree mode
-       -  see  below) are hidden by default.  Use -E/--empty to show them (re-
-       vealing assets:bank:checking here):
-
-              $ hledger -f examples/sample.journal bal  -E
-                                 0  assets:bank:checking
-                                $1  assets:bank:saving
-                               $-2  assets:cash
-                                $1  expenses:food
-                                $1  expenses:supplies
-                               $-1  income:gifts
-                               $-1  income:salary
-                                $1  liabilities:debts
-              --------------------
-                                 0
-
-       The total of the amounts displayed is shown as the  last  line,  unless
-       -N/--no-total is used.
-
-   Balance report line format
-       For single-period balance reports displayed in the terminal (only), you
-       can  use --format FMT to customise the format and content of each line.
-       Eg:
-
-              $ hledger -f examples/sample.journal balance --format "%20(account) %12(total)"
-                            assets          $-1
-                       bank:saving           $1
-                              cash          $-2
-                          expenses           $2
-                              food           $1
-                          supplies           $1
-                            income          $-2
-                             gifts          $-1
-                            salary          $-1
-                 liabilities:debts           $1
-              ---------------------------------
-                                              0
-
-       The FMT format string specifies the  formatting  applied  to  each  ac-
-       count/balance pair.  It may contain any suitable text, with data fields
-       interpolated like so:
-
-       %[MIN][.MAX](FIELDNAME)
-
-       o MIN pads with spaces to at least this width (optional)
-
-       o MAX truncates at this width (optional)
-
-       o FIELDNAME must be enclosed in parentheses, and can be one of:
-
-         o depth_spacer  - a number of spaces equal to the account's depth, or
-           if MIN is specified, MIN * depth spaces.
-
-         o account - the account's name
-
-         o total - the account's balance/posted total, right justified
-
-       Also, FMT can begin with an optional prefix to control  how  multi-com-
-       modity amounts are rendered:
-
-       o %_ - render on multiple lines, bottom-aligned (the default)
-
-       o %^ - render on multiple lines, top-aligned
-
-       o %, - render on one line, comma-separated
-
-       There are some quirks.  Eg in one-line mode, %(depth_spacer) has no ef-
-       fect,  instead  %(account)  has indentation built in.   Experimentation
-       may be needed to get pleasing results.
-
-       Some example formats:
-
-       o %(total) - the account's total
-
-       o %-20.20(account) - the account's name, left justified, padded  to  20
-         characters and clipped at 20 characters
-
-       o %,%-50(account)   %25(total)  - account name padded to 50 characters,
-         total padded to 20 characters, with multiple commodities rendered  on
-         one line
-
-       o %20(total)   %2(depth_spacer)%-(account) - the default format for the
-         single-column balance report
-
-   Filtered balance report
-       You can show fewer accounts,  a  different  time  period,  totals  from
-       cleared transactions only, etc.  by using query arguments or options to
-       limit the postings being matched.  Eg:
-
-              $ hledger -f examples/sample.journal bal --cleared assets date:200806
-                               $-2  assets:cash
-              --------------------
-                               $-2
-
-   List or tree mode
-       By  default,  or with -l/--flat, accounts are shown as a flat list with
-       their full names visible, as in the examples above.
-
-       With -t/--tree, the  account  hierarchy  is  shown,  with  subaccounts'
-       "leaf" names indented below their parent:
-
-              $ hledger -f examples/sample.journal balance
-                               $-1  assets
-                                $1    bank:saving
-                               $-2    cash
-                                $2  expenses
-                                $1    food
-                                $1    supplies
-                               $-2  income
-                               $-1    gifts
-                               $-1    salary
-                                $1  liabilities:debts
-              --------------------
-                                 0
-
-       Notes:
-
-       o "Boring" accounts are combined with their subaccount for more compact
-         output,  unless  --no-elide is used.  Boring accounts have no balance
-         of their own and just one subaccount (eg assets:bank and  liabilities
-         above).
-
-       o All  balances  shown  are "inclusive", ie including the balances from
-         all subaccounts.  Note this means  some  repetition  in  the  output,
-         which requires explanation when sharing reports with non-plaintextac-
-         counting-users.   A  tree mode report's final total is the sum of the
-         top-level balances shown, not of all the balances shown.
-
-       o Each group of sibling accounts (ie, under a common parent) is  sorted
-         separately.
-
-   Depth limiting
-       With  a  depth:NUM  query, or --depth NUM option, or just -NUM (eg: -3)
-       balance reports will show accounts only to the specified depth,  hiding
-       the  deeper  subaccounts.   This  can be useful for getting an overview
-       without too much detail.
-
-       Account balances at the depth limit always include  the  balances  from
-       any deeper subaccounts (even in list mode).  Eg, limiting to depth 1:
-
-              $ hledger -f examples/sample.journal balance -1
-                               $-1  assets
-                                $2  expenses
-                               $-2  income
-                                $1  liabilities
-              --------------------
-                                 0
-
-   Dropping top-level accounts
-       You  can  also  hide  one  or  more top-level account name parts, using
-       --drop NUM.  This can be useful for hiding repetitive top-level account
-       names:
-
-              $ hledger -f examples/sample.journal bal expenses --drop 1
-                                $1  food
-                                $1  supplies
-              --------------------
-                                $2
-
-   Showing declared accounts
-       With --declared, accounts which have been declared with an account  di-
-       rective  will  be  included in the balance report, even if they have no
-       transactions.  (Since they will have a zero balance, you will also need
-       -E/--empty to see them.)
-
-       More precisely, leaf declared accounts (with no  subaccounts)  will  be
-       included, since those are usually the more useful in reports.
-
-       The  idea  of this is to be able to see a useful "complete" balance re-
-       port, even when you don't have transactions in all of your declared ac-
-       counts yet.
-
-   Sorting by amount
-       With -S/--sort-amount, accounts with the largest (most  positive)  bal-
-       ances  are  shown  first.   Eg:  hledger  bal  expenses -MAS shows your
-       biggest averaged monthly expenses first.  When more than one  commodity
-       is  present, they will be sorted by the alphabetically earliest commod-
-       ity first, and then by subsequent commodities (if an amount is  missing
-       a commodity, it is treated as 0).
-
-       Revenues  and liability balances are typically negative, however, so -S
-       shows these in reverse order.  To work around this, you can  add  --in-
-       vert  to  flip  the  signs.   (Or, use one of the higher-level reports,
-       which flip the sign automatically.  Eg: hledger incomestatement -MAS).
-
-   Percentages
-       With -%/--percent, balance reports show each account's value  expressed
-       as a percentage of the (column) total.
-
-       Note it is not useful to calculate percentages if the amounts in a col-
-       umn  have  mixed  signs.  In this case, make a separate report for each
-       sign, eg:
-
-              $ hledger bal -% amt:`>0`
-              $ hledger bal -% amt:`<0`
-
-       Similarly, if the amounts in a column have mixed  commodities,  convert
-       them  to  one  commodity with -B, -V, -X or --value, or make a separate
-       report for each commodity:
-
-              $ hledger bal -% cur:\\$
-              $ hledger bal -% cur:
-
-   Multi-period balance report
-       With  a  report  interval  (set   by   the   -D/--daily,   -W/--weekly,
-       -M/--monthly,  -Q/--quarterly,  -Y/--yearly, or -p/--period flag), bal-
-       ance shows a tabular report, with columns representing successive  time
-       periods (and a title):
-
-              $ hledger -f examples/sample.journal bal --quarterly income expenses -E
-              Balance changes in 2008:
-
-                                 ||  2008q1  2008q2  2008q3  2008q4
-              ===================++=================================
-               expenses:food     ||       0      $1       0       0
-               expenses:supplies ||       0      $1       0       0
-               income:gifts      ||       0     $-1       0       0
-               income:salary     ||     $-1       0       0       0
-              -------------------++---------------------------------
-                                 ||     $-1      $1       0       0
-
-       Notes:
-
-       o The report's start/end dates will be expanded, if necessary, to fully
-         encompass the displayed subperiods (so that the first and last subpe-
-         riods have the same duration as the others).
-
-       o Leading  and trailing periods (columns) containing all zeroes are not
-         shown, unless -E/--empty is used.
-
-       o Accounts  (rows)  containing  all  zeroes  are  not   shown,   unless
-         -E/--empty is used.
-
-       o Amounts  with  many commodities are shown in abbreviated form, unless
-         --no-elide is used.
-
-       o Average and/or total columns can be added with the  -A/--average  and
-         -T/--row-total flags.
-
-       o The --transpose flag can be used to exchange rows and columns.
-
-       o The  --pivot  FIELD option causes a different transaction field to be
-         used as "account name".  See PIVOTING.
-
-       o The --summary-only flag (--summary also works) hides all but the  To-
-         tal and Average columns (those should be enabled with --row-total and
-         -A/--average).
-
-       Multi-period reports with many periods can be too wide for easy viewing
-       in the terminal.  Here are some ways to handle that:
-
-       o Hide the totals row with -N/--no-total
-
-       o Filter to a single currency with cur:
-
-       o Convert to a single currency with -V [--infer-market-price]
-
-       o Use a more compact layout like --layout=bare
-
-       o Maximize the terminal window
-
-       o Reduce the terminal's font size
-
-       o View  with  a  pager like less, eg: hledger bal -D --color=yes | less
-         -RS
-
-       o Output as CSV and use a CSV viewer like visidata (hledger bal  -D  -O
-         csv  |  vd  -f  csv),  Emacs'  csv-mode (M-x csv-mode, C-c C-a), or a
-         spreadsheet (hledger bal -D -o a.csv && open a.csv)
-
-       o Output as HTML and view with a browser: hledger bal -D -o  a.html  &&
-         open a.html
-
-   Balance change, end balance
-       It's  important to be clear on the meaning of the numbers shown in bal-
-       ance reports.  Here is some terminology we use:
-
-       A balance change is the net amount added to, or removed  from,  an  ac-
-       count during some period.
-
-       An  end balance is the amount accumulated in an account as of some date
-       (and some time, but hledger doesn't store that; assume end  of  day  in
-       your timezone).  It is the sum of previous balance changes.
-
-       We  call it a historical end balance if it includes all balance changes
-       since the account was created.  For a real world account, this means it
-       will match the "historical record", eg the balances  reported  in  your
-       bank statements or bank web UI.  (If they are correct!)
-
-       In  general,  balance  changes  are what you want to see when reviewing
-       revenues and expenses, and historical end balances are what you want to
-       see when reviewing or reconciling asset, liability and equity accounts.
-
-       balance shows balance changes by default.  To see  accurate  historical
-       end balances:
-
-       1. Initialise  account  starting  balances  with  an "opening balances"
-          transaction (a transfer from equity  to  the  account),  unless  the
-          journal covers the account's full lifetime.
-
-       2. Include all of of the account's prior postings in the report, by not
-          specifying  a  report  start  date,  or by using the -H/--historical
-          flag.  (-H causes report start date to be ignored when summing post-
-          ings.)
-
-   Balance report types
-       The balance command is quite flexible; here is the full detail  on  how
-       to  control what it reports.  If the following seems complicated, don't
-       worry - this is for advanced reporting, and it does take time  and  ex-
-       perimentation to get familiar with all the report modes.
-
-       There are three important option groups:
-
-       hledger  balance  [CALCULATIONTYPE]  [ACCUMULATIONTYPE] [VALUATIONTYPE]
-       ...
-
-   Calculation type
-       The basic calculation to perform for each table cell.  It is one of:
-
-       o --sum : sum the posting amounts (default)
-
-       o --budget : sum the amounts, but also show the budget goal amount (for
-         each account/period)
-
-       o --valuechange : show the change in period-end historical balance val-
-         ues (caused by deposits, withdrawals, and/or  market  price  fluctua-
-         tions)
-
-       o --gain  :  show the unrealised capital gain/loss, (the current valued
-         balance minus each amount's original cost)
-
-       o --count : show the count of postings
-
-   Accumulation type
-       How amounts should accumulate  across  a  report's  subperiods/columns.
-       Another  way  to say it: which time period's postings should contribute
-       to each cell's calculation.  It is one of:
-
-       o --change : calculate with postings from column start to  column  end,
-         ie  "just  this  column".   Typically  used to see revenues/expenses.
-         (default for balance, cashflow, incomestatement)
-
-       o --cumulative : calculate with postings from report  start  to  column
-         end,  ie "previous columns plus this column".  Typically used to show
-         changes accumulated since the report's start date.  Not often used.
-
-       o --historical/-H : calculate with postings from journal start to  col-
-         umn  end,  ie  "all postings from before report start date until this
-         column's end".  Typically used to see historical end balances of  as-
-         sets/liabilities/equity.   (default  for balancesheet, balancesheete-
-         quity)
-
-   Valuation type
-       Which kind of value or cost conversion should be applied, if  any,  be-
-       fore displaying the report.  It is one of:
-
-       o no valuation type : don't convert to cost or value (default)
-
-       o --value=cost[,COMM]  :  convert  amounts  to cost (then optionally to
-         some other commodity)
-
-       o --value=then[,COMM] : convert amounts to market value on  transaction
-         dates
-
-       o --value=end[,COMM]  :  convert  amounts to market value on period end
-         date(s)
-       (default with --valuechange, --gain)
-
-       o --value=now[,COMM] : convert amounts to market value on today's date
-
-       o --value=YYYY-MM-DD[,COMM] : convert amounts to market  value  on  an-
-         other date
-
-       or one of the equivalent simpler flags:
-
-       o -B/--cost  :  like  --value=cost (though, note --cost and --value are
-         independent options which can both be used at once)
-
-       o -V/--market : like --value=end
-
-       o -X COMM/--exchange COMM : like --value=end,COMM
-
-       See Cost reporting and Value reporting for more about these.
-
-   Combining balance report types
-       Most combinations of these options should produce  reasonable  reports,
-       but  if  you  find any that seem wrong or misleading, let us know.  The
-       following restrictions are applied:
-
-       o --valuechange implies --value=end
-
-       o --valuechange makes --change the default  when  used  with  the  bal-
-         ancesheet/balancesheetequity commands
-
-       o --cumulative or --historical disables --row-total/-T
-
-       For reference, here is what the combinations of accumulation and valua-
-       tion show:
-
-       Valua-     no valuation       --value= then       --value= end      --value=
-       tion:>                                                              YYYY-MM-DD
-       Accumu-                                                             /now
-       lation:v
-       -----------------------------------------------------------------------------------
-       --change   change in period   sum    of   post-   period-end        DATE-value  of
-                                     ing-date   market   value of change   change in  pe-
-                                     values in period    in period         riod
-       --cumu-    change  from re-   sum    of   post-   period-end        DATE-value  of
-       lative     port  start   to   ing-date   market   value of change   change    from
-                  period end         values  from  re-   from     report   report   start
-                                     port start to pe-   start to period   to period end
-                                     riod end            end
-       --his-     change      from   sum    of   post-   period-end        DATE-value  of
-       torical    journal start to   ing-date   market   value of change   change    from
-       /-H        period end (his-   values from jour-   from    journal   journal  start
-                  torical end bal-   nal  start to pe-   start to period   to period end
-                  ance)              riod end            end
-
-   Budget report
-       The --budget report type is like a regular balance report, but with two
-       main differences:
-
-       o Budget goals and performance percentages are also shown, in brackets
-
-       o Accounts which don't have budget goals are hidden by default.
-
-       This is useful for comparing planned and actual income, expenses,  time
-       usage, etc.
-
-       Periodic  transaction rules are used to define budget goals.  For exam-
-       ple, here's a periodic rule defining monthly goals for bus  travel  and
-       food expenses:
-
-              ;; Budget
-              ~ monthly
-                (expenses:bus)              $30
-                (expenses:food)            $400
-
-       After recording some actual expenses,
-
-              ;; Two months worth of expenses
-              2017-11-01
-                income                   $-1950
-                expenses:bus                $35
-                expenses:food:groceries    $310
-                expenses:food:dining        $42
-                expenses:movies             $38
-                assets:bank:checking
-
-              2017-12-01
-                income                   $-2100
-                expenses:bus                $53
-                expenses:food:groceries    $380
-                expenses:food:dining        $32
-                expenses:gifts             $100
-                assets:bank:checking
-
-       we can see a budget report like this:
-
-              $ hledger bal -M --budget
-              Budget performance in 2017-11-01..2017-12-31:
-
-                             ||                  Nov                   Dec
-              ===============++============================================
-               <unbudgeted>  || $-425                 $-565
-               expenses      ||  $425 [ 99% of $430]   $565 [131% of $430]
-               expenses:bus  ||   $35 [117% of  $30]    $53 [177% of  $30]
-               expenses:food ||  $352 [ 88% of $400]   $412 [103% of $400]
-              ---------------++--------------------------------------------
-                             ||     0 [  0% of $430]      0 [  0% of $430]
-
-       This is "goal-based budgeting"; you define goals for accounts and peri-
-       ods,  often  recurring,  and  hledger shows performance relative to the
-       goals.  This contrasts with "envelope budgeting",  which  is  more  de-
-       tailed  and  strict  -  useful when cash is tight, but also quite a bit
-       more work.  https://plaintextaccounting.org/Budgeting has more on  this
-       topic.
-
-   Using the budget report
-       Historically  this  report  has  been confusing and fragile.  hledger's
-       version should be relatively robust and intuitive, but  you  may  still
-       find  surprises.   Here  are more notes to help with learning and trou-
-       bleshooting.
-
-       o In the above example, expenses:bus and expenses:food  are  shown  be-
-         cause they have budget goals during the report period.
-
-       o Their  parent  expenses  is  also shown, with budget goals aggregated
-         from the children.
-
-       o The subaccounts expenses:food:groceries and expenses:food:dining  are
-         not  shown since they have no budget goal of their own, but they con-
-         tribute to expenses:food's actual amount.
-
-       o Unbudgeted accounts expenses:movies and expenses:gifts are  also  not
-         shown, but they contribute to expenses's actual amount.
-
-       o The  other  unbudgeted  accounts  income and assets:bank:checking are
-         grouped as <unbudgeted>.
-
-       o --depth or depth: can be used to limit report depth in the usual  way
-         (but will not reveal unbudgeted subaccounts).
-
-       o Amounts are always inclusive of subaccounts (even in -l/--list mode).
-
-       o Numbers displayed in a --budget report will not always agree with the
-         totals,  because  of  hidden  unbudgeted  accounts;  this  is normal.
-         -E/--empty can be used to reveal the hidden accounts.
-
-       o In the periodic rules used for setting budget goals, unbalanced post-
-         ings are convenient.
-
-       o You can filter budget reports with the usual queries, eg to focus  on
-         particular  accounts.  It's common to restrict them to just expenses.
-         (The <unbudgeted> account is occasionally hard to  exclude;  this  is
-         because of date surprises, discussed below.)
-
-       o When  you  have  multiple currencies, you may want to convert them to
-         one (-X COMM --infer-market-prices) and/or show just one  at  a  time
-         (cur:COMM).   If  you  do  need  to show multiple currencies at once,
-         --layout bare can be helpful.
-
-       o You can "roll over" amounts (actual and budgeted) to the next  period
-         with --cumulative.
-
-       See also: https://hledger.org/budgeting.html.
-
-   Budget date surprises
-       With  small  data,  or  when starting out, some of the generated budget
-       goal transaction dates might fall outside the report periods.  Eg  with
-       the  following  journal and report, the first period appears to have no
-       expenses:food budget.  (Also the <unbudgeted>  account  should  be  ex-
-       cluded by the expenses query, but isn't.):
-
-              ~ monthly in 2020
-                (expenses:food)  $500
-
-              2020-01-15
-                expenses:food    $400
-                assets:checking
-
-              $ hledger bal --budget expenses
-              Budget performance in 2020-01-15:
-
-                             ||         2020-01-15
-              ===============++====================
-               <unbudgeted>  || $400
-               expenses:food ||    0 [ 0% of $500]
-              ---------------++--------------------
-                             || $400 [80% of $500]
-
-       In  this case, the budget goal transactions are generated on first days
-       of of month (this can be seen with hledger print --forecast  tag:gener-
-       ated  expenses).   Whereas  the report period defaults to just the 15th
-       day of january (this can be seen from the report table's  column  head-
-       ings).
-
-       To  fix  this  kind  of thing, be more explicit about the report period
-       (and/or the periodic rules' dates).  In this case, adding -b 2020  does
-       the trick.
-
-   Selecting budget goals
-       By  default,  the budget report uses all available periodic transaction
-       rules to generate goals.  This includes rules with a  different  report
-       interval  from  your  report.  Eg if you have daily, weekly and monthly
-       periodic rules, all of these will contribute to the goals in a  monthly
-       budget report.
-
-       You  can  select a subset of periodic rules by providing an argument to
-       the --budget flag.  --budget=DESCPAT  will  match  all  periodic  rules
-       whose description contains DESCPAT, a case-insensitive substring (not a
-       regular  expression  or  query).  This means you can give your periodic
-       rules descriptions (remember that two spaces are needed between  period
-       expression  and description), and then select from multiple budgets de-
-       fined in your journal.
-
-   Budgeting vs forecasting
-       --forecast and --budget both use the periodic transaction rules in  the
-       journal  to  generate  temporary  transactions  for reporting purposes.
-       However they are separate features - though you can  use  both  at  the
-       same time if you want.  Here are some differences between them:
-
-       --forecast                               --budget
-       --------------------------------------------------------------------------
-       is  a general option; it enables fore-   is a balance command option;  it
-       casting with all reports                 selects   the  balance  report's
-                                                budget mode
-       generates visible  transactions  which   generates invisible transactions
-       appear in reports                        which produce goal amounts
-       generates  forecast  transactions from   generates budget  goal  transac-
-       after the last regular transaction, to   tions  throughout the report pe-
-       the end of the report period; or  with   riod, optionally  restricted  by
-       an argument --forecast=PERIODEXPR gen-   periods  specified  in the peri-
-       erates  them  throughout the specified   odic transaction rules
-       period, both optionally restricted  by
-       periods   specified  in  the  periodic
-       transaction rules
-       uses all periodic rules                  uses all periodic rules; or with
-                                                an   argument   --budget=DESCPAT
-                                                uses  just  the rules matched by
-                                                DESCPAT
-
-   Balance report layout
-       The --layout option affects how balance and the other balance-like com-
-       mands show multi-commodity amounts and commodity symbols.  It  can  im-
-       prove readability, for humans and/or machines (other software).  It has
-       four possible values:
-
-       o --layout=wide[,WIDTH]:  commodities  are  shown on a single line, op-
-         tionally elided to WIDTH
-
-       o --layout=tall: each commodity is shown on a separate line
-
-       o --layout=bare: commodity symbols are in their own column, amounts are
-         bare numbers
-
-       o --layout=tidy: data is normalised  to  easily-consumed  "tidy"  form,
-         with  one  row per data value.  (This one is currently supported only
-         by the balance command.)
-
-       Here are the --layout modes supported by each output  format  Only  CSV
-       output supports all of them:
-
-       -      txt   csv   html   json   sql
-       -------------------------------------
-       wide   Y     Y     Y
-       tall   Y     Y     Y
-       bare   Y     Y     Y
-       tidy         Y
-
-       Examples:
-
-   Wide layout
-       With many commodities, reports can be very wide:
-
-              $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=wide
-              Balance changes in 2012-01-01..2014-12-31:
-
-                                ||                                          2012                                                     2013                                             2014                                                      Total
-              ==================++====================================================================================================================================================================================================================
-               Assets:US:ETrade || 10.00 ITOT, 337.18 USD, 12.00 VEA, 106.00 VHT  70.00 GLD, 18.00 ITOT, -98.12 USD, 10.00 VEA, 18.00 VHT  -11.00 ITOT, 4881.44 USD, 14.00 VEA, 170.00 VHT  70.00 GLD, 17.00 ITOT, 5120.50 USD, 36.00 VEA, 294.00 VHT
-              ------------------++--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
-                                || 10.00 ITOT, 337.18 USD, 12.00 VEA, 106.00 VHT  70.00 GLD, 18.00 ITOT, -98.12 USD, 10.00 VEA, 18.00 VHT  -11.00 ITOT, 4881.44 USD, 14.00 VEA, 170.00 VHT  70.00 GLD, 17.00 ITOT, 5120.50 USD, 36.00 VEA, 294.00 VHT
-
-       A width limit reduces the width, but some commodities will be hidden:
-
-              $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=wide,32
-              Balance changes in 2012-01-01..2014-12-31:
-
-                                ||                             2012                             2013                   2014                            Total
-              ==================++===========================================================================================================================
-               Assets:US:ETrade || 10.00 ITOT, 337.18 USD, 2 more..  70.00 GLD, 18.00 ITOT, 3 more..  -11.00 ITOT, 3 more..  70.00 GLD, 17.00 ITOT, 3 more..
-              ------------------++---------------------------------------------------------------------------------------------------------------------------
-                                || 10.00 ITOT, 337.18 USD, 2 more..  70.00 GLD, 18.00 ITOT, 3 more..  -11.00 ITOT, 3 more..  70.00 GLD, 17.00 ITOT, 3 more..
-
-   Tall layout
-       Each  commodity  gets a new line (may be different in each column), and
-       account names are repeated:
-
-              $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=tall
-              Balance changes in 2012-01-01..2014-12-31:
-
-                                ||       2012        2013         2014        Total
-              ==================++==================================================
-               Assets:US:ETrade || 10.00 ITOT   70.00 GLD  -11.00 ITOT    70.00 GLD
-               Assets:US:ETrade || 337.18 USD  18.00 ITOT  4881.44 USD   17.00 ITOT
-               Assets:US:ETrade ||  12.00 VEA  -98.12 USD    14.00 VEA  5120.50 USD
-               Assets:US:ETrade || 106.00 VHT   10.00 VEA   170.00 VHT    36.00 VEA
-               Assets:US:ETrade ||              18.00 VHT                294.00 VHT
-              ------------------++--------------------------------------------------
-                                || 10.00 ITOT   70.00 GLD  -11.00 ITOT    70.00 GLD
-                                || 337.18 USD  18.00 ITOT  4881.44 USD   17.00 ITOT
-                                ||  12.00 VEA  -98.12 USD    14.00 VEA  5120.50 USD
-                                || 106.00 VHT   10.00 VEA   170.00 VHT    36.00 VEA
-                                ||              18.00 VHT                294.00 VHT
-
-   Bare layout
-       Commodity symbols are kept in one column, each commodity  has  its  own
-       row, amounts are bare numbers, account names are repeated:
-
-              $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=bare
-              Balance changes in 2012-01-01..2014-12-31:
-
-                                || Commodity    2012    2013     2014    Total
-              ==================++=============================================
-               Assets:US:ETrade || GLD             0   70.00        0    70.00
-               Assets:US:ETrade || ITOT        10.00   18.00   -11.00    17.00
-               Assets:US:ETrade || USD        337.18  -98.12  4881.44  5120.50
-               Assets:US:ETrade || VEA         12.00   10.00    14.00    36.00
-               Assets:US:ETrade || VHT        106.00   18.00   170.00   294.00
-              ------------------++---------------------------------------------
-                                || GLD             0   70.00        0    70.00
-                                || ITOT        10.00   18.00   -11.00    17.00
-                                || USD        337.18  -98.12  4881.44  5120.50
-                                || VEA         12.00   10.00    14.00    36.00
-                                || VHT        106.00   18.00   170.00   294.00
-
-       Bare layout also affects CSV output, which is useful for producing data
-       that is easier to consume, eg for making charts:
-
-              $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -O csv --layout=bare
-              "account","commodity","balance"
-              "Assets:US:ETrade","GLD","70.00"
-              "Assets:US:ETrade","ITOT","17.00"
-              "Assets:US:ETrade","USD","5120.50"
-              "Assets:US:ETrade","VEA","36.00"
-              "Assets:US:ETrade","VHT","294.00"
-              "Total:","GLD","70.00"
-              "Total:","ITOT","17.00"
-              "Total:","USD","5120.50"
-              "Total:","VEA","36.00"
-              "Total:","VHT","294.00"
-
-       Bare  layout will sometimes display an extra row for the no-symbol com-
-       modity, because of zero  amounts  (hledger  treats  zeroes  as  commod-
-       ity-less,   usually).    This   can   break   hledger-bar   confusingly
-       (workaround: add a cur: query to exclude the no-symbol row).
-
-   Tidy layout
-       This       produces       normalised       "tidy       data"       (see
-       https://cran.r-project.org/web/packages/tidyr/vignettes/tidy-data.html)
-       where  every variable has its own column and each row represents a sin-
-       gle data point.  This is the easiest kind of data for other software to
-       consume:
-
-              $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -Y -O csv --layout=tidy
-              "account","period","start_date","end_date","commodity","value"
-              "Assets:US:ETrade","2012","2012-01-01","2012-12-31","GLD","0"
-              "Assets:US:ETrade","2012","2012-01-01","2012-12-31","ITOT","10.00"
-              "Assets:US:ETrade","2012","2012-01-01","2012-12-31","USD","337.18"
-              "Assets:US:ETrade","2012","2012-01-01","2012-12-31","VEA","12.00"
-              "Assets:US:ETrade","2012","2012-01-01","2012-12-31","VHT","106.00"
-              "Assets:US:ETrade","2013","2013-01-01","2013-12-31","GLD","70.00"
-              "Assets:US:ETrade","2013","2013-01-01","2013-12-31","ITOT","18.00"
-              "Assets:US:ETrade","2013","2013-01-01","2013-12-31","USD","-98.12"
-              "Assets:US:ETrade","2013","2013-01-01","2013-12-31","VEA","10.00"
-              "Assets:US:ETrade","2013","2013-01-01","2013-12-31","VHT","18.00"
-              "Assets:US:ETrade","2014","2014-01-01","2014-12-31","GLD","0"
-              "Assets:US:ETrade","2014","2014-01-01","2014-12-31","ITOT","-11.00"
-              "Assets:US:ETrade","2014","2014-01-01","2014-12-31","USD","4881.44"
-              "Assets:US:ETrade","2014","2014-01-01","2014-12-31","VEA","14.00"
-              "Assets:US:ETrade","2014","2014-01-01","2014-12-31","VHT","170.00"
-
-   Balance report output
-       As noted in Output format, if you choose HTML output (by using -O  html
-       or  -o somefile.html), it will use the UTF-8 text encoding, And you can
-       create a hledger.css file in the same directory to  customise  the  re-
-       port's appearance.
-
-       The  HTML  and  FODS  output  formats  can  generate  hyperlinks  to  a
-       hledger-web register view for each account and period.  E.g.   if  your
-       hledger-web server is reachable at http://localhost:5000 then you might
-       run  the balance command with the extra option --base-url=http://local-
-       host:5000.    You   can   also    produce    relative    links,    like
-       --base-url="some/path" or --base-url="".)
-
-       The  balance  reports'  HTML output currently does not indent tree mode
-       reports properly (#1846).  So in HTML balance reports,  use  list  mode
-       for now (it is the default).
-
-   Some useful balance reports
-       Some frequently used balance options/reports are:
-
-       o bal -M revenues expenses
-       Show  revenues/expenses  in each month.  Also available as the incomes-
-       tatement command.
-
-       o bal -M -H assets liabilities
-       Show historical asset/liability  balances  at  each  month  end.   Also
-       available as the balancesheet command.
-
-       o bal -M -H assets liabilities equity
-       Show  historical  asset/liability/equity  balances  at  each month end.
-       Also available as the balancesheetequity command.
-
-       o bal -M assets not:receivable
-       Show changes to liquid assets in each month.   Also  available  as  the
-       cashflow command.
-
-       Also:
-
-       o bal -M expenses -2 -SA
-       Show  monthly  expenses  summarised  to  depth  2 and sorted by average
-       amount.
-
-       o bal -M --budget expenses
-       Show monthly expenses and budget goals.
-
-       o bal -M --valuechange investments
-       Show monthly change in market value of investment assets.
-
-       o bal  investments  --valuechange  -D  date:lastweek  amt:'>1000'  -STA
-         [--invert]
-       Show top gainers [or losers] last week
-
-   roi
-       Shows  the  time-weighted (TWR) and money-weighted (IRR) rate of return
-       on your investments.
-
-              Flags:
-                   --cashflow                 show all amounts that were used to compute
-                                              returns
-                   --investment=QUERY         query to select your investment transactions
-                   --profit-loss=QUERY --pnl  query to select profit-and-loss or
-                                              appreciation/valuation transactions
-
-       At a minimum, you need to supply a query (which could be  just  an  ac-
-       count  name) to select your investment(s) with --inv, and another query
-       to identify your profit and loss transactions with --pnl.
-
-       If you do not record changes in the value of your investment  manually,
-       or  do  not  require  computation  of time-weighted return (TWR), --pnl
-       could be an empty query (--pnl "" or --pnl STR where STR does not match
-       any of your accounts).
-
-       This command will compute and display the internalized rate  of  return
-       (IRR,  also  known  as money-weighted rate of return) and time-weighted
-       rate of return (TWR) for your  investments  for  the  time  period  re-
-       quested.   IRR  is always annualized due to the way it is computed, but
-       TWR is reported both as a rate over the chosen reporting period and  as
-       an annual rate.
-
-       Price  directives  will be taken into account if you supply appropriate
-       --cost or --value flags (see VALUATION).
-
-       Note, in some cases this report can fail, for these reasons:
-
-       o Error (NotBracketed): No solution for Internal Rate of Return  (IRR).
-         Possible  causes:  IRR is huge (>1000000%), balance of investment be-
-         comes negative at some point in time.
-
-       o Error (SearchFailed): Failed to find solution for  Internal  Rate  of
-         Return (IRR).  Either search does not converge to a solution, or con-
-         verges too slowly.
-
-       Examples:
-
-       o Using   roi   to  compute  total  return  of  investment  in  stocks:
-         https://github.com/simonmichael/hledger/blob/master/examples/invest-
-         ing/roi-unrealised.ledger
-
-       o Cookbook > Return on Investment: https://hledger.org/roi.html
-
-   Spaces and special characters in --inv and --pnl
-       Note that --inv and --pnl's argument is a query, and queries could have
-       several space-separated terms (see QUERIES).
-
-       To indicate that all search terms form  single  command-line  argument,
-       you will need to put them in quotes (see Special characters):
-
-              $ hledger roi --inv 'term1 term2 term3 ...'
-
-       If  any  query  terms contain spaces themselves, you will need an extra
-       level of nested quoting, eg:
-
-              $ hledger roi --inv="'Assets:Test 1'" --pnl="'Equity:Unrealized Profit and Loss'"
-
-   Semantics of --inv and --pnl
-       Query supplied to --inv has to match all transactions that are  related
-       to your investment.  Transactions not matching --inv will be ignored.
-
-       In these transactions, ROI will conside postings that match --inv to be
-       "investment  postings"  and other postings (not matching --inv) will be
-       sorted into two categories: "cash flow" and "profit and loss",  as  ROI
-       needs  to know which part of the investment value is your contributions
-       and which is due to the return on investment.
-
-       o "Cash flow" is depositing or withdrawing money, buying or selling as-
-         sets, or otherwise converting between your investment  commodity  and
-         any other commodity.  Example:
-
-                2019-01-01 Investing in Snake Oil
-                  assets:cash          -$100
-                  investment:snake oil
-
-                2020-01-01 Selling my Snake Oil
-                  assets:cash           $10
-                  investment:snake oil  = 0
-
-       o "Profit and loss" is change in the value of your investment:
-
-                2019-06-01 Snake Oil falls in value
-                  investment:snake oil  = $57
-                  equity:unrealized profit or loss
-
-       All  non-investment postings are assumed to be "cash flow", unless they
-       match --pnl query.  Changes in value of your investment due to  "profit
-       and  loss"  postings  will be considered as part of your investment re-
-       turn.
-
-       Example: if you use --inv snake --pnl equity:unrealized, then  postings
-       in the example below would be classifed as:
-
-              2019-01-01 Snake Oil #1
-                assets:cash          -$100   ; cash flow posting
-                investment:snake oil         ; investment posting
-
-              2019-03-01 Snake Oil #2
-                equity:unrealized pnl  -$100 ; profit and loss posting
-                snake oil                    ; investment posting
-
-              2019-07-01 Snake Oil #3
-                equity:unrealized pnl        ; profit and loss posting
-                cash          -$100          ; cash flow posting
-                snake oil     $50            ; investment posting
-
-   IRR and TWR explained
-       "ROI"  stands  for "return on investment".  Traditionally this was com-
-       puted as a difference between current value of investment and its  ini-
-       tial value, expressed in percentage of the initial value.
-
-       However, this approach is only practical in simple cases, where invest-
-       ments  receives  no  in-flows  or out-flows of money, and where rate of
-       growth is fixed over time.  For more complex scenarios you need differ-
-       ent ways to compute rate of return, and this command implements two  of
-       them: IRR and TWR.
-
-       Internal  rate of return, or "IRR" (also called "money-weighted rate of
-       return") takes into account effects of in-flows and out-flows, and  the
-       time  between  them.  Investment at a particular fixed interest rate is
-       going to give you more interest than the same amount  invested  at  the
-       same  interest  rate,  but  made later in time.  If you are withdrawing
-       from your investment, your future gains would be smaller  (in  absolute
-       numbers),  and will be a smaller percentage of your initial investment,
-       so your IRR will be smaller.  And if you are adding to your investment,
-       you will receive bigger absolute gains, which will be a bigger percent-
-       age of your initial investment, so your IRR will be larger.
-
-       As mentioned before, in-flows and out-flows would be any cash that  you
-       personally put in or withdraw, and for the "roi" command, these are the
-       postings  that  match  the query in the--inv argument and NOT match the
-       query in the--pnl argument.
-
-       If you manually record changes in  the  value  of  your  investment  as
-       transactions  that  balance them against "profit and loss" (or "unreal-
-       ized gains") account or use price directives, then in order for IRR  to
-       compute  the  precise effect of your in-flows and out-flows on the rate
-       of return, you will need to record the value of your investement on  or
-       close to the days when in- or out-flows occur.
-
-       In  technical  terms,  IRR uses the same approach as computation of net
-       present value, and tries to find a discount rate that makes net present
-       value of all the cash flows of your investment to add up to zero.  This
-       could be hard to wrap your head around, especially if you haven't  done
-       discounted cash flow analysis before.  Implementation of IRR in hledger
-       should produce results that match the =XIRR formula in Excel.
-
-       Second  way  to  compute  rate of return that roi command implements is
-       called "time-weighted rate of return" or "TWR".  Like IRR, it will  ac-
-       count  for the effect of your in-flows and out-flows, but unlike IRR it
-       will try to compute the true rate of return of  the  underlying  asset,
-       compensating  for  the  effect that deposits and withdrawas have on the
-       apparent rate of growth of your investment.
-
-       TWR represents your  investment  as  an  imaginary  "unit  fund"  where
-       in-flows/  out-flows  lead to buying or selling "units" of your invest-
-       ment and changes in its value change the value  of  "investment  unit".
-       Change  in "unit price" over the reporting period gives you rate of re-
-       turn of your investment, and make TWR less sensitive than  IRR  to  the
-       effects of cash in-flows and out-flows.
-
-       References:
-
-       o Explanation of rate of return
-
-       o Explanation of IRR
-
-       o Explanation of TWR
-
-       o IRR vs TWR
-
-       o Examples  of  computing IRR and TWR and discussion of the limitations
-         of both metrics
-
-Chart commands
-   activity
-       Show an ascii barchart of posting counts per interval.
-
-              Flags:
-              no command-specific flags
-
-       The activity command displays an ascii  histogram  showing  transaction
-       counts  by  day, week, month or other reporting interval (by day is the
-       default).  With query arguments, it counts only matched transactions.
-
-       Examples:
-
-              $ hledger activity --quarterly
-              2008-01-01 **
-              2008-04-01 *******
-              2008-07-01
-              2008-10-01 **
-
-Data generation commands
-   close
-       (equity)
-
-       close generates several kinds of "closing"  and/or  "opening"  transac-
-       tions,  useful in certain situations, including migrating balances to a
-       new journal file, retaining earnings into  equity,  consolidating  bal-
-       ances,  or  viewing lots.  Like print, it prints valid journal entries.
-       You can append or copy these to your journal file(s) when you are happy
-       with how they look.
-
-              Flags:
-                   --migrate[=NEW]        show closing and opening transactions, for Asset
-                                          and Liability accounts by default, tagged for easy
-                                          matching. The tag's default value can be overridden
-                                          by providing NEW.
-                   --close[=NEW]          (default) show a closing transaction
-                   --open[=NEW]           show an opening transaction
-                   --assign[=NEW]         show opening balance assignments
-                   --assert[=NEW]         show closing balance assertions
-                   --retain[=NEW]         show a retain earnings transaction, for Revenue
-                                          and Expense accounts by default
-                -x --explicit             show all amounts explicitly
-                   --show-costs           show amounts with different costs separately
-                   --interleaved          show source and destination postings together
-                   --assertion-type=TYPE  =, ==, =* or ==*
-                   --close-desc=DESC      set closing transaction's description
-                   --close-acct=ACCT      set closing transaction's destination account
-                   --open-desc=DESC       set opening transaction's description
-                   --open-acct=ACCT       set opening transaction's source account
-                   --round=TYPE           how much rounding or padding should be done when
-                                          displaying amounts ?
-                                          none - show original decimal digits,
-                                                 as in journal
-                                          soft - just add or remove decimal zeros
-                                                 to match precision (default)
-                                          hard - round posting amounts to precision
-                                                 (can unbalance transactions)
-                                          all  - also round cost amounts to precision
-                                                 (can unbalance transactions)
-
-       close currently has six modes, selected by a single mode flag:
-
-   close --migrate
-       This is the most common mode.  It prints a "closing balances"  transac-
-       tion that zeroes out all asset and liability balances (by default), and
-       an  opposite  "opening  balances" transaction that restores them again.
-       The balancing account will be equity:opening/closing balances  (or  an-
-       other specified by --close-acct or --open-acct).
-
-       This  is  useful  when  migrating balances to a new journal file at the
-       start of  a  new  year.   Essentially,  you  run  hledger  close  --mi-
-       grate=NEWYEAR  -e  NEWYEAR and then copy the closing transaction to the
-       end of the old file and the opening transaction to the start of the new
-       file.  The opening transaction sets correct starting  balances  in  the
-       new  file when it is used alone, and the closing transaction keeps bal-
-       ances correct when you use both old and new  files  together,  by  can-
-       celling out the following opening transaction and preventing buildup of
-       duplicated  opening  balances.   Think  of  the closing/opening pair as
-       "moving the balances into the next file".
-
-       You can close a different set of accounts by providing a query.  Eg  if
-       you  want  to  include equity, you can add assets liabilities equity or
-       type:ALE arguments.  (The balancing account is always excluded.)   Rev-
-       enues and expenses usually are not migrated to a new file directly; see
-       --retain below.
-
-       The  generated  transactions will have a start: tag, with its value set
-       to --migrate's NEW argument if any, for easier matching  or  exclusion.
-       When  NEW  is  not specified, it will be inferred if possible by incre-
-       menting a number (eg a year number) within the default  journal's  main
-       file name.  The other modes behave similarly.
-
-   close --close
-       This  prints just the closing balances transaction of --migrate.  It is
-       the default behaviour if you specify no mode flag.  Using the  customi-
-       sation options below, you can move balances from any set of accounts to
-       a different account.
-
-   close --open
-       This  prints just the opening balances transaction of --migrate.  It is
-       similar to Ledger's equity command.
-
-   close --assert
-       This prints a "closing balances" transaction (with balances: tag), that
-       just declares balance  assertions  for  the  current  balances  without
-       changing  them.  It could be useful as documention and to guard against
-       changes.
-
-   close --assign
-       This prints an "opening balances" transaction that restores the account
-       balances using balance assignments.  Balance assignments  work  regard-
-       less  of any previous balance, so a preceding closing balances transac-
-       tion is not needed.
-
-       However, omitting the closing balances transaction would unbalance  eq-
-       uity.   This  is  relatively harmless for personal reports, but it dis-
-       turbs the accounting equation, removing a source  of  error  detection.
-       So  --migrate  is  generally the best way to set to set balances in new
-       files, for now.
-
-   close --retain
-       This is like --close with different defaults: it prints a "retain earn-
-       ings" transaction (with retain: tag), that transfers  revenue  and  ex-
-       pense balances to equity:retained earnings.
-
-       This  is  a  different  kind of closing, called "retaining earnings" or
-       "closing the books"; it is traditionally performed by businesses at the
-       end of each accounting period, to  consolidate  revenues  and  expenses
-       into  the main equity balance.  ("Revenues" and "expenses" are actually
-       equity by another name, kept separate temporarily  for  reporting  pur-
-       poses.)
-
-       In  personal accounting you generally don't need to do this, unless you
-       want the balancesheetequity report to show a zero total,  demonstrating
-       that the accounting equation (A-L=E) is satisfied.
-
-   close customisation
-       In all modes, the following things can be overridden:
-
-       o the accounts to be closed/opened, with account query arguments
-
-       o the balancing account, with --close-acct=ACCT and/or --open-acct=ACCT
-
-       o the    transaction    descriptions,    with   --close-desc=DESC   and
-         --open-desc=DESC
-
-       o the transaction's tag value, with a --MODE=NEW option argument
-
-       o the closing/opening dates, with -e OPENDATE
-
-       By default, the closing date is yesterday, or the journal's  end  date,
-       whichever  is  later;  and the opening date is always one day after the
-       closing date.  You can change these by specifying a  report  end  date;
-       the closing date will be the last day of the report period.  Eg -e 2024
-       means "close on 2023-12-31, open on 2024-01-01".
-
-       With --x/--explicit, the balancing amount will be shown explicitly, and
-       if  it involves multiple commodities, a separate posting will be gener-
-       ated for each of them (similar to print -x).
-
-       With --interleaved, each individual transfer is shown with  source  and
-       destination  postings  next  to  each  other  (perhaps useful for trou-
-       bleshooting).
-
-       With --show-costs, balances' costs are also shown, with different costs
-       kept separate.  This may generate very large journal  entries,  if  you
-       have  many  currency  conversions  or  investment  transactions.  close
-       --show-costs is currently the best way to  view  investment  lots  with
-       hledger.    (To   move  or  dispose  of  lots,  see  the  more  capable
-       hledger-move script.)
-
-   close and balance assertions
-       close adds balance assertions verifying that the accounts have been re-
-       set to zero in a closing transaction or restored to their previous bal-
-       ances in an opening transaction.  These provide useful error  checking,
-       but you can ignore them temporarily with -I, or remove them if you pre-
-       fer.
-
-       Single-commodity,  subaccount-exclusive balance assertions (=) are gen-
-       erated by default.  This can  be  changed  with  --assertion-type='==*'
-       (eg).
-
-       When  running  close  you  should  probably avoid using -C, -R, status:
-       (filtering by status or  realness)  or  --auto  (generating  postings),
-       since the generated balance assertions would then require these.
-
-       Transactions  with  multiple dates (eg posting dates) spanning the file
-       boundary also can disrupt the balance assertions:
-
-              2023-12-30 a purchase made in december, cleared in january
-                  expenses:food          5
-                  assets:bank:checking  -5  ; date: 2023-01-02
-
-       To solve this you can transfer the money to and from  a  temporary  ac-
-       count, splitting the multi-day transaction into two single-day transac-
-       tions:
-
-              ; in 2022.journal:
-              2022-12-30 a purchase made in december, cleared in january
-                  expenses:food          5
-                  equity:pending        -5
-
-              ; in 2023.journal:
-              2023-01-02 last year's transaction cleared
-                  equity:pending         5 = 0
-                  assets:bank:checking  -5
-
-   close examples
-   Retain earnings
-       Record 2022's revenues/expenses as retained earnings on 2022-12-31, ap-
-       pending the generated transaction to the journal:
-
-              $ hledger close --retain -f 2022.journal -p 2022 >> 2022.journal
-
-       After  this,  to  see 2022's revenues and expenses you must exclude the
-       retain earnings transaction:
-
-              $ hledger -f 2022.journal is not:desc:'retain earnings'
-
-   Migrate balances to a new file
-       Close assets/liabilities on 2022-12-31 and re-open them on 2023-01-01:
-
-              $ hledger close --migrate -f 2022.journal -p 2022
-              # copy/paste the closing transaction to the end of 2022.journal
-              # copy/paste the opening transaction to the start of 2023.journal
-
-       After this, to see 2022's end-of-year balances  you  must  exclude  the
-       closing balances transaction:
-
-              $ hledger -f 2022.journal bs not:desc:'closing balances'
-
-       For  more flexibility, it helps to tag closing and opening transactions
-       with eg start:NEWYEAR, then you can ensure correct balances by  exclud-
-       ing all opening/closing transactions except the first, like so:
-
-              $ hledger bs -Y -f 2021.j -f 2022.j -f 2023.j expr:'tag:start=2021 or not tag:start'
-              $ hledger bs -Y -f 2021.j -f 2022.j           expr:'tag:start=2021 or not tag:start'
-              $ hledger bs -Y -f 2022.j -f 2023.j           expr:'tag:start=2022 or not tag:start'
-              $ hledger bs -Y -f 2021.j                     expr:'tag:start=2021 or not tag:start'
-              $ hledger bs -Y -f 2022.j                     expr:'tag:start=2022 or not tag:start'
-              $ hledger bs -Y -f 2023.j                     # unclosed file, no query needed
-
-   More detailed close examples
-       See examples/multi-year.
-
-   rewrite
-       Print all transactions, rewriting the postings of matched transactions.
-       For  now  the only rewrite available is adding new postings, like print
-       --auto.
-
-              Flags:
-                   --add-posting='ACCT  AMTEXPR'  add a posting to ACCT, which may be
-                                                  parenthesised. AMTEXPR is either a literal
-                                                  amount, or *N which means the transaction's
-                                                  first matched amount multiplied by N (a
-                                                  decimal number). Two spaces separate ACCT
-                                                  and AMTEXPR.
-                   --diff                         generate diff suitable as an input for
-                                                  patch tool
-
-       This is a start at a generic rewriter of transaction entries.  It reads
-       the default journal and prints the transactions, like print,  but  adds
-       one or more specified postings to any transactions matching QUERY.  The
-       posting  amounts can be fixed, or a multiplier of the existing transac-
-       tion's first posting amount.
-
-       Examples:
-
-              $ hledger-rewrite.hs ^income --add-posting '(liabilities:tax)  *.33  ; income tax' --add-posting '(reserve:gifts)  $100'
-              $ hledger-rewrite.hs expenses:gifts --add-posting '(reserve:gifts)  *-1"'
-              $ hledger-rewrite.hs -f rewrites.hledger
-
-       rewrites.hledger may consist of entries like:
-
-              = ^income amt:<0 date:2017
-                (liabilities:tax)  *0.33  ; tax on income
-                (reserve:grocery)  *0.25  ; reserve 25% for grocery
-                (reserve:)  *0.25  ; reserve 25% for grocery
-
-       Note the single quotes to protect the dollar sign from  bash,  and  the
-       two spaces between account and amount.
-
-       More:
-
-              $ hledger rewrite -- [QUERY]        --add-posting "ACCT  AMTEXPR" ...
-              $ hledger rewrite -- ^income        --add-posting '(liabilities:tax)  *.33'
-              $ hledger rewrite -- expenses:gifts --add-posting '(budget:gifts)  *-1"'
-              $ hledger rewrite -- ^income        --add-posting '(budget:foreign currency)  *0.25 JPY; diversify'
-
-       Argument  for  --add-posting  option  is a usual posting of transaction
-       with an exception for amount specification.  More  precisely,  you  can
-       use '*' (star symbol) before the amount to indicate that that this is a
-       factor  for  an  amount of original matched posting.  If the amount in-
-       cludes a commodity name, the new posting amount will be in the new com-
-       modity; otherwise, it will be in the matched posting  amount's  commod-
-       ity.
-
-   Re-write rules in a file
-       During  the  run  this  tool will execute so called "Automated Transac-
-       tions" found in any journal it process.  I.e instead of specifying this
-       operations in command line you can put them in a journal file.
-
-              $ rewrite-rules.journal
-
-       Make contents look like this:
-
-              = ^income
-                  (liabilities:tax)  *.33
-
-              = expenses:gifts
-                  budget:gifts  *-1
-                  assets:budget  *1
-
-       Note that '=' (equality symbol) that is used instead of date in  trans-
-       actions you usually write.  It indicates the query by which you want to
-       match the posting to add new ones.
-
-              $ hledger rewrite -- -f input.journal -f rewrite-rules.journal > rewritten-tidy-output.journal
-
-       This is something similar to the commands pipeline:
-
-              $ hledger rewrite -- -f input.journal '^income' --add-posting '(liabilities:tax)  *.33' \
-                | hledger rewrite -- -f - expenses:gifts      --add-posting 'budget:gifts  *-1'       \
-                                                              --add-posting 'assets:budget  *1'       \
-                > rewritten-tidy-output.journal
-
-       It  is  important  to understand that relative order of such entries in
-       journal is important.  You can re-use result of previously added  post-
-       ings.
-
-   Diff output format
-       To  use  this tool for batch modification of your journal files you may
-       find useful output in form of unified diff.
-
-              $ hledger rewrite -- --diff -f examples/sample.journal '^income' --add-posting '(liabilities:tax)  *.33'
-
-       Output might look like:
-
-              --- /tmp/examples/sample.journal
-              +++ /tmp/examples/sample.journal
-              @@ -18,3 +18,4 @@
-               2008/01/01 income
-              -    assets:bank:checking  $1
-              +    assets:bank:checking            $1
-                   income:salary
-              +    (liabilities:tax)                0
-              @@ -22,3 +23,4 @@
-               2008/06/01 gift
-              -    assets:bank:checking  $1
-              +    assets:bank:checking            $1
-                   income:gifts
-              +    (liabilities:tax)                0
-
-       If you'll pass this through patch tool you'll get transactions contain-
-       ing the posting that matches your query be updated.  Note that multiple
-       files might be update according to list of input  files  specified  via
-       --file options and include directives inside of these files.
-
-       Be  careful.  Whole transaction being re-formatted in a style of output
-       from hledger print.
-
-       See also:
-
-       https://github.com/simonmichael/hledger/issues/99
-
-   rewrite vs. print --auto
-       This command predates print --auto, and currently does  much  the  same
-       thing, but with these differences:
-
-       o with  multiple files, rewrite lets rules in any file affect all other
-         files.  print --auto uses standard directive  scoping;  rules  affect
-         only child files.
-
-       o rewrite's  query  limits which transactions can be rewritten; all are
-         printed.  print --auto's query limits which transactions are printed.
-
-       o rewrite applies rules specified on command line or  in  the  journal.
-         print --auto applies rules specified in the journal.
-
-Maintenance commands
-   check
-       Check for various kinds of errors in your data.
-
-              Flags:
-              no command-specific flags
-
-       hledger  provides a number of built-in correctness checks to help vali-
-       date your data and prevent errors.  Some are  run  automatically,  some
-       when  you enable --strict mode; or you can run any of them on demand by
-       providing them as arguments to the check command.   check  produces  no
-       output and a zero exit code if all is well.  Eg:
-
-              hledger check                      # run basic checks
-              hledger check -s                   # run basic and strict checks
-              hledger check ordereddates payees  # run basic checks and two others
-
-       If  you  are  an Emacs user, you can also configure flycheck-hledger to
-       run these checks, providing instant feedback as you edit the journal.
-
-       Here are the checks currently available.  Generally, they are performed
-       in the order they are shown here (and only the  first  failure  is  re-
-       ported).
-
-   Basic checks
-       These  important checks are performed by default, by almost all hledger
-       commands:
-
-       o parseable - data files are in a supported format, with no syntax  er-
-         rors  and no invalid include directives.  This ensures that all files
-         exist and are readable.
-
-       o autobalanced - all transactions are balanced, after inferring missing
-         amounts and conversion costs where possible, and then  converting  to
-         cost.  This ensures that each individual transaction is well formed.
-
-       o assertions - all balance assertions in the journal are passing.  Bal-
-         ance  assertions  are  like canaries in your journal, they catch many
-         problems.  They can get in the way sometimes; you  can  disable  them
-         temporarily   with  -I/--ignore-assertions  (unless  overridden  with
-         -s/--strict or hledger check assertions).
-
-   Strict checks
-       These  additional  checks  are  performed  by  any  command  when   the
-       -s/--strict flag is used (strict mode).  Strict mode always enables the
-       balance  assertions  check,  also.   These provide extra error-catching
-       power when you are serious about keeping your data clean  and  free  of
-       typos:
-
-       o balanced  -  like autobalanced, but in conversion transactions, costs
-         must be written explicitly.  This ensures some redundancy in the  en-
-         try, which helps prevent typos.
-
-       o commodities  -  all  commodity  symbols  used must be declared.  This
-         guards against mistyping or omitting commodity symbols.
-
-       o accounts - all account names used must be  declared.   This  prevents
-         the use of mis-spelled or outdated account names.
-
-   Other checks
-       These other checks are not wanted by everyone, but can be run using the
-       check command:
-
-       o ordereddates  -  within  each file, transactions are ordered by date.
-         This is a simple and effective error catcher, and you should use  it.
-         Alas!   not  everyone  wants it.  If you do, use hledger check -s or-
-         dereddates.  When enabled, this check is performed early, before bal-
-         ance assertions (because copy-pasted dates are often the  root  cause
-         of balance assertion failures).
-
-       o payees - all payees used by transactions must be declared.  This will
-         force  you to always use known/declared payee names.  For most people
-         this is a bit too restrictive.
-
-       o tags - all tags used by transactions must be declared.  This prevents
-         mistyped tag names.
-
-       o recentassertions - all accounts with balance assertions must  have  a
-         balance assertion within the last 7 days before their latest posting.
-         This  encourages  you  to add balance assertions fairly regularly for
-         your active asset/liability accounts, which in turn should  encourage
-         you to check and reconcile with their real world balances fairly reg-
-         ularly.   close  --assert  can be helpful.  (The older balance asser-
-         tions become redundant; you can remove them  periodically,  or  leave
-         them in place, perhaps commented, as documentation.)
-
-       o uniqueleafnames  -  no two accounts may have the same leaf name.  The
-         leaf name is the last colon-separated part of  an  account  name,  eg
-         checking  in assets:bank:checking.  This encourages you to keep those
-         unique, effectively giving each account a short name which is  easier
-         to remember and to type in reporting commands.
-
-   Custom checks
-       You  can build your own custom checks with add-on command scripts.  See
-       also Cookbook > Scripting.  Here are some examples from hledger/bin/:
-
-       o hledger-check-tagfiles - all  tag  values  containing  /  (a  forward
-         slash) exist as file paths
-
-       o hledger-check-fancyassertions  -  more complex balance assertions are
-         passing
-
-   diff
-       Compares a particular account's transactions in two  input  files.   It
-       shows any transactions to this account which are in one file but not in
-       the other.
-
-              Flags:
-              no command-specific flags
-
-       More precisely: for each posting affecting this account in either file,
-       this  command looks for a corresponding posting in the other file which
-       posts the same amount to the same account (ignoring date,  description,
-       etc).
-
-       Since it compares postings, not transactions, this also works when mul-
-       tiple bank transactions have been combined into a single journal entry.
-
-       This  command is useful eg if you have downloaded an account's transac-
-       tions from your bank (eg as CSV data): when hledger and your bank  dis-
-       agree  about  the  account  balance, you can compare the bank data with
-       your journal to find out the cause.
-
-       Examples:
-
-              $ hledger diff -f $LEDGER_FILE -f bank.csv assets:bank:giro
-              These transactions are in the first file only:
-
-              2014/01/01 Opening Balances
-                  assets:bank:giro              EUR ...
-                  ...
-                  equity:opening balances       EUR -...
-
-              These transactions are in the second file only:
-
-   test
-       Run built-in unit tests.
-
-              Flags:
-              no command-specific flags
-
-       This command runs the unit tests built in to hledger  and  hledger-lib,
-       printing  the results on stdout.  If any test fails, the exit code will
-       be non-zero.
-
-       This is mainly used by hledger developers, but you can also use  it  to
-       sanity-check  the  installed  hledger executable on your platform.  All
-       tests are expected to pass - if you ever see a failure,  please  report
-       as a bug!
-
-       This command also accepts tasty test runner options, written after a --
-       (double hyphen).  Eg to run only the tests in Hledger.Data.Amount, with
-       ANSI colour codes disabled:
-
-              $ hledger test -- -pData.Amount --color=never
-
-       For  help  on these, see https://github.com/feuerbach/tasty#options (--
-       --help currently doesn't show them).
-
-PART 5: COMMON TASKS
-       Here are some quick examples  of  how  to  do  some  basic  tasks  with
-       hledger.
-
-Getting help
-       Here's how to list commands and view options and command docs:
-
-              $ hledger                # show available commands
-              $ hledger --help         # show common options
-              $ hledger CMD --help     # show CMD's options, common options and CMD's documentation
-
-       You  can  also view your hledger version's manual in several formats by
-       using the help command.  Eg:
-
-              $ hledger help           # show the hledger manual with info, man or $PAGER (best available)
-              $ hledger help journal   # show the journal topic in the hledger manual
-              $ hledger help --help    # find out more about the help command
-
-       To  view  manuals   and   introductory   docs   on   the   web,   visit
-       https://hledger.org.    Chat  and  mail  list  support  and  discussion
-       archives can be found at https://hledger.org/support.
-
-Constructing command lines
-       hledger has a flexible command line interface.  We strive  to  keep  it
-       simple  and  ergonomic,  but if you run into one of the sharp edges de-
-       scribed in OPTIONS, here are some tips that might help:
-
-       o command-specific options must go after the command (it's fine to  put
-         common options there too: hledger CMD OPTS ARGS)
-
-       o running  add-on  executables directly simplifies command line parsing
-         (hledger-ui OPTS ARGS)
-
-       o enclose "problematic" args in single quotes
-
-       o if needed, also add a backslash to hide regular expression  metachar-
-         acters from the shell
-
-       o to see how a misbehaving command line is being parsed, add --debug=2.
-
-Starting a journal file
-       hledger   looks   for   your   accounting   data  in  a  journal  file,
-       $HOME/.hledger.journal by default:
-
-              $ hledger stats
-              The hledger journal file "/Users/simon/.hledger.journal" was not found.
-              Please create it first, eg with "hledger add" or a text editor.
-              Or, specify an existing journal file with -f or LEDGER_FILE.
-
-       You can override this by setting the LEDGER_FILE  environment  variable
-       (see  below).   It's  a good practice to keep this important file under
-       version control, and to start a new file each year.  So  you  could  do
-       something like this:
-
-              $ mkdir ~/finance
-              $ cd ~/finance
-              $ git init
-              Initialized empty Git repository in /Users/simon/finance/.git/
-              $ touch 2023.journal
-              $ echo "export LEDGER_FILE=$HOME/finance/2023.journal" >> ~/.profile
-              $ source ~/.profile
-              $ hledger stats
-              Main file                : /Users/simon/finance/2023.journal
-              Included files           :
-              Transactions span        :  to  (0 days)
-              Last transaction         : none
-              Transactions             : 0 (0.0 per day)
-              Transactions last 30 days: 0 (0.0 per day)
-              Transactions last 7 days : 0 (0.0 per day)
-              Payees/descriptions      : 0
-              Accounts                 : 0 (depth 0)
-              Commodities              : 0 ()
-              Market prices            : 0 ()
-
-Setting LEDGER_FILE
-       How to set LEDGER_FILE permanently depends on your setup:
-
-       On  unix  and mac, running these commands in the terminal will work for
-       many people; adapt as needed:
-
-              $ echo 'export LEDGER_FILE=~/finance/2023.journal' >> ~/.profile
-              $ source ~/.profile
-
-       When correctly  configured,  in  a  new  terminal  window  env  |  grep
-       LEDGER_FILE will show your file, and so will hledger files.
-
-       On  mac,  this  additional  step  might be helpful for GUI applications
-       (like Emacs started from the dock): add an entry to  ~/.MacOSX/environ-
-       ment.plist like
-
-              {
-                "LEDGER_FILE" : "~/finance/2023.journal"
-              }
-
-       and  then  run  killall  Dock  in a terminal window (or restart the ma-
-       chine).
-
-       On Windows, see https://www.java.com/en/download/help/path.html, or try
-       running these commands in a powershell window (let us know if  it  per-
-       sists across a reboot, and if you need to be an Administrator):
-
-              > CD
-              > MKDIR finance
-              > SETX LEDGER_FILE "C:\Users\USERNAME\finance\2023.journal"
-
-       When  correctly  configured,  in a new terminal window $env:LEDGER_FILE
-       will show the file path, and so will hledger files.
-
-Setting opening balances
-       Pick a starting date for which you can look up  the  balances  of  some
-       real-world  assets  (bank  accounts, wallet..)  and liabilities (credit
-       cards..).
-
-       To avoid a lot of data entry, you may want to start with  just  one  or
-       two accounts, like your checking account or cash wallet; and pick a re-
-       cent  starting  date, like today or the start of the week.  You can al-
-       ways come back later and add more accounts and older  transactions,  eg
-       going back to january 1st.
-
-       Add  an opening balances transaction to the journal, declaring the bal-
-       ances on this date.  Here are two ways to do it:
-
-       o The first way: open the journal in any text editor and save an  entry
-         like this:
-
-                2023-01-01 * opening balances
-                    assets:bank:checking                $1000   = $1000
-                    assets:bank:savings                 $2000   = $2000
-                    assets:cash                          $100   = $100
-                    liabilities:creditcard               $-50   = $-50
-                    equity:opening/closing balances
-
-         These  are  start-of-day  balances, ie whatever was in the account at
-         the end of the previous day.
-
-         The * after the date is an  optional  status  flag.   Here  it  means
-         "cleared & confirmed".
-
-         The  currency symbols are optional, but usually a good idea as you'll
-         be dealing with multiple currencies sooner or later.
-
-         The = amounts are optional balance assertions, providing extra  error
-         checking.
-
-       o The  second  way:  run hledger add and follow the prompts to record a
-         similar transaction:
-
-                $ hledger add
-                Adding transactions to journal file /Users/simon/finance/2023.journal
-                Any command line arguments will be used as defaults.
-                Use tab key to complete, readline keys to edit, enter to accept defaults.
-                An optional (CODE) may follow transaction dates.
-                An optional ; COMMENT may follow descriptions or amounts.
-                If you make a mistake, enter < at any prompt to go one step backward.
-                To end a transaction, enter . when prompted.
-                To quit, enter . at a date prompt or press control-d or control-c.
-                Date [2023-02-07]: 2023-01-01
-                Description: * opening balances
-                Account 1: assets:bank:checking
-                Amount  1: $1000
-                Account 2: assets:bank:savings
-                Amount  2 [$-1000]: $2000
-                Account 3: assets:cash
-                Amount  3 [$-3000]: $100
-                Account 4: liabilities:creditcard
-                Amount  4 [$-3100]: $-50
-                Account 5: equity:opening/closing balances
-                Amount  5 [$-3050]:
-                Account 6 (or . or enter to finish this transaction): .
-                2023-01-01 * opening balances
-                    assets:bank:checking                      $1000
-                    assets:bank:savings                       $2000
-                    assets:cash                                $100
-                    liabilities:creditcard                     $-50
-                    equity:opening/closing balances          $-3050
-
-                Save this transaction to the journal ? [y]:
-                Saved.
-                Starting the next transaction (. or ctrl-D/ctrl-C to quit)
-                Date [2023-01-01]: .
-
-       If you're using version control, this could be a good  time  to  commit
-       the journal.  Eg:
-
-              $ git commit -m 'initial balances' 2023.journal
-
-Recording transactions
-       As  you spend or receive money, you can record these transactions using
-       one of the methods above (text editor, hledger add)  or  by  using  the
-       hledger-iadd  or hledger-web add-ons, or by using the import command to
-       convert CSV data downloaded from your bank.
-
-       Here are some simple transactions, see  the  hledger_journal(5)  manual
-       and hledger.org for more ideas:
-
-              2023/1/10 * gift received
-                assets:cash   $20
-                income:gifts
-
-              2023.1.12 * farmers market
-                expenses:food    $13
-                assets:cash
-
-              2023-01-15 paycheck
-                income:salary
-                assets:bank:checking    $1000
-
-Reconciling
-       Periodically  you should reconcile - compare your hledger-reported bal-
-       ances against external sources of truth, like bank statements  or  your
-       bank's  website - to be sure that your ledger accurately represents the
-       real-world balances (and, that the  real-world  institutions  have  not
-       made  a  mistake!).   This gets easy and fast with (1) practice and (2)
-       frequency.  If you do it daily, it can take 2-10 minutes.  If  you  let
-       it  pile  up, expect it to take longer as you hunt down errors and dis-
-       crepancies.
-
-       A typical workflow:
-
-       1. Reconcile cash.  Count what's in your  wallet.   Compare  with  what
-          hledger  reports  (hledger bal cash).  If they are different, try to
-          remember the missing transaction, or look for the error in  the  al-
-          ready-recorded  transactions.   A  register  report  can  be helpful
-          (hledger reg cash).  If you can't find the error, add an  adjustment
-          transaction.  Eg if you have $105 after the above, and can't explain
-          the missing $2, it could be:
-
-                  2023-01-16 * adjust cash
-                      assets:cash    $-2 = $105
-                      expenses:misc
-
-       2. Reconcile checking.  Log in to your bank's website.  Compare today's
-          (cleared) balance with hledger's cleared balance (hledger bal check-
-          ing  -C).  If they are different, track down the error or record the
-          missing transaction(s) or add an adjustment transaction, similar  to
-          the above.  Unlike the cash case, you can usually compare the trans-
-          action  history  and running balance from your bank with the one re-
-          ported by hledger reg checking -C.  This will be easier if you  gen-
-          erally  record transaction dates quite similar to your bank's clear-
-          ing dates.
-
-       3. Repeat for other asset/liability accounts.
-
-       Tip: instead of the register command, use hledger-ui to see a  live-up-
-       dating register while you edit the journal: hledger-ui --watch --regis-
-       ter checking -C
-
-       After  reconciling,  it  could  be  a  good time to mark the reconciled
-       transactions' status as "cleared and confirmed", if you want  to  track
-       that,  by  adding  the * marker.  Eg in the paycheck transaction above,
-       insert * between 2023-01-15 and paycheck
-
-       If you're using version control, this can be another good time to  com-
-       mit:
-
-              $ git commit -m 'txns' 2023.journal
-
-Reporting
-       Here are some basic reports.
-
-       Show all transactions:
-
-              $ hledger print
-              2023-01-01 * opening balances
-                  assets:bank:checking                      $1000
-                  assets:bank:savings                       $2000
-                  assets:cash                                $100
-                  liabilities:creditcard                     $-50
-                  equity:opening/closing balances          $-3050
-
-              2023-01-10 * gift received
-                  assets:cash              $20
-                  income:gifts
-
-              2023-01-12 * farmers market
-                  expenses:food             $13
-                  assets:cash
-
-              2023-01-15 * paycheck
-                  income:salary
-                  assets:bank:checking           $1000
-
-              2023-01-16 * adjust cash
-                  assets:cash               $-2 = $105
-                  expenses:misc
-
-       Show account names, and their hierarchy:
-
-              $ hledger accounts --tree
-              assets
-                bank
-                  checking
-                  savings
-                cash
-              equity
-                opening/closing balances
-              expenses
-                food
-                misc
-              income
-                gifts
-                salary
-              liabilities
-                creditcard
-
-       Show all account totals:
-
-              $ hledger balance
-                             $4105  assets
-                             $4000    bank
-                             $2000      checking
-                             $2000      savings
-                              $105    cash
-                            $-3050  equity:opening/closing balances
-                               $15  expenses
-                               $13    food
-                                $2    misc
-                            $-1020  income
-                              $-20    gifts
-                            $-1000    salary
-                              $-50  liabilities:creditcard
-              --------------------
-                                 0
-
-       Show  only  asset  and  liability  balances, as a flat list, limited to
-       depth 2:
-
-              $ hledger bal assets liabilities -2
-                             $4000  assets:bank
-                              $105  assets:cash
-                              $-50  liabilities:creditcard
-              --------------------
-                             $4055
-
-       Show the same thing without negative numbers,  formatted  as  a  simple
-       balance sheet:
-
-              $ hledger bs -2
-              Balance Sheet 2023-01-16
-
-                                      || 2023-01-16
-              ========================++============
-               Assets                 ||
-              ------------------------++------------
-               assets:bank            ||      $4000
-               assets:cash            ||       $105
-              ------------------------++------------
-                                      ||      $4105
-              ========================++============
-               Liabilities            ||
-              ------------------------++------------
-               liabilities:creditcard ||        $50
-              ------------------------++------------
-                                      ||        $50
-              ========================++============
-               Net:                   ||      $4055
-
-       The final total is your "net worth" on the end date.  (Or use bse for a
-       full balance sheet with equity.)
-
-       Show income and expense totals, formatted as an income statement:
-
-              hledger is
-              Income Statement 2023-01-01-2023-01-16
-
-                             || 2023-01-01-2023-01-16
-              ===============++=======================
-               Revenues      ||
-              ---------------++-----------------------
-               income:gifts  ||                   $20
-               income:salary ||                 $1000
-              ---------------++-----------------------
-                             ||                 $1020
-              ===============++=======================
-               Expenses      ||
-              ---------------++-----------------------
-               expenses:food ||                   $13
-               expenses:misc ||                    $2
-              ---------------++-----------------------
-                             ||                   $15
-              ===============++=======================
-               Net:          ||                 $1005
-
-       The final total is your net income during this period.
-
-       Show transactions affecting your wallet, with running total:
-
-              $ hledger register cash
-              2023-01-01 opening balances     assets:cash                   $100          $100
-              2023-01-10 gift received        assets:cash                    $20          $120
-              2023-01-12 farmers market       assets:cash                   $-13          $107
-              2023-01-16 adjust cash          assets:cash                    $-2          $105
-
-       Show weekly posting counts as a bar chart:
-
-              $ hledger activity -W
-              2019-12-30 *****
-              2023-01-06 ****
-              2023-01-13 ****
-
-Migrating to a new file
-       At  the end of the year, you may want to continue your journal in a new
-       file, so that old transactions don't slow down or clutter your reports,
-       and to help ensure the integrity of your accounting history.   See  the
-       close command.
-
-       If using version control, don't forget to git add the new file.
-
-BUGS
-       We  welcome  bug  reports  in  the  hledger  issue  tracker  (shortcut:
-       https://bugs.hledger.org),  or  on  the  hledger  chat  or  mail   list
-       (https://hledger.org/support).
-
-       Some known issues and limitations:
-
-       The  need  to  precede add-on command options with -- when invoked from
-       hledger is awkward.  (See Command options, Constructing command lines.)
-
-       A UTF-8-aware system locale must be configured to work  with  non-ascii
-       data.  (See Unicode characters, Troubleshooting.)
-
-       On Microsoft Windows, depending whether you are running in a CMD window
-       or a Cygwin/MSYS/Mintty window and how you installed hledger, non-ascii
-       characters and colours may not be supported, and the tab key may not be
-       supported  by  hledger  add.   (Running  in a WSL window should resolve
-       these.)
-
-       When processing large data files, hledger uses more memory than Ledger.
-
-   Troubleshooting
-       Here are some common issues you might encounter when you  run  hledger,
-       and  how  to  resolve them (and remember also you can usually get quick
-       Support):
-
-       PATH issues: I get an error like "No command 'hledger' found"
-       Depending how you installed hledger, the executables may not be in your
-       shell's PATH.  Eg on unix systems, stack  installs  hledger  in  ~/.lo-
-       cal/bin and cabal installs it in ~/.cabal/bin.  You may need to add one
-       of  these  directories to your shell's PATH, and/or open a new terminal
-       window.
-
-       LEDGER_FILE issues: I configured LEDGER_FILE but hledger is  not  using
-       it
-       o LEDGER_FILE  should  be a real environment variable, not just a shell
-         variable.  Eg on unix, the command env | grep LEDGER_FILE should show
-         it.   You  may   need   to   use   export   (see   https://stackover-
-         flow.com/a/7411509).  On Windows, $env:LEDGER_FILE should show it.
-
-       o You  may  need  to  force your shell to see the new configuration.  A
-         simple way is to close your terminal window and open a new one.
-
-       LANG issues: I get errors like "Illegal byte sequence" or  "Invalid  or
-       incomplete multibyte or wide character" or "commitAndReleaseBuffer: in-
-       valid argument (invalid character)"
-       Programs  compiled  with GHC (hledger, haskell build tools, etc.)  need
-       the system locale to be UTF-8-aware, or they will fail  when  they  en-
-       counter  non-ascii  characters.   To  fix  it, set the LANG environment
-       variable to a locale which supports UTF-8 and  which  is  installed  on
-       your system.
-
-       On  unix,  locale  -a  lists the installed locales.  Look for one which
-       mentions utf8, UTF-8 or similar.  Some examples: C.UTF-8,  en_US.utf-8,
-       fr_FR.utf8.   If  necessary, use your system package manager to install
-       one.  Then select it by setting the LANG environment  variable.   Note,
-       exact  spelling and capitalisation of the locale name may be important:
-       Here's one common way to configure this permanently for your shell:
-
-              $ echo "export LANG=en_US.utf8" >>~/.profile
-              # close and re-open terminal window
-
-       If you are using Nix (not NixOS) for GHC and Hledger, you might need to
-       set the LOCALE_ARCHIVE variable:
-
-              $ echo "export LOCALE_ARCHIVE=${glibcLocales}/lib/locale/locale-archive" >>~/.profile
-              # close and re-open terminal window
-
-       COMPATIBILITY ISSUES: hledger gives an error with my Ledger file
-       Not all of Ledger's journal file syntax or feature  set  is  supported.
-       See hledger and Ledger for full details.
-
-
-
-AUTHORS
-       Simon Michael <simon@joyful.com> and contributors.
-       See http://hledger.org/CREDITS.html
-
-
-COPYRIGHT
-       Copyright 2007-2023 Simon Michael and contributors.
-
-
-LICENSE
-       Released under GNU GPL v3 or later.
-
-
-SEE ALSO
-       hledger(1), hledger-ui(1), hledger-web(1), ledger(1)
-
-hledger-1.41                     October 2024                       HLEDGER(1)
+       This manual is for hledger's command line interface, version 1.42.   It
+       also  describes  the  common options, file formats and concepts used by
+       all hledger programs.  It might accidentally teach you  some  bookkeep-
+       ing/accounting  as  well!  You don't need to know everything in here to
+       use hledger productively, but when you have a question about  function-
+       ality,  this doc should answer it.  It is detailed, so do skip ahead or
+       skim when needed.  You can read it on hledger.org, or as an info manual
+       or man page on your system.  You can also open a built-in  copy,  at  a
+       point of interest, by running
+       hledger --man [CMD], hledger --info [CMD] or hledger help [TOPIC].
+
+       (And for shorter help, try hledger --tldr [CMD].)
+
+       The  main  function  of the hledger CLI is to read plain text files de-
+       scribing financial transactions, crunch the numbers, and print a useful
+       report on the terminal (or save it as HTML, CSV, JSON  or  SQL).   Many
+       reports  are available, as subcommands.  hledger will also detect other
+       hledger-* executables as extra subcommands.
+
+       hledger usually reads from (and appends to) a journal file specified by
+       the     LEDGER_FILE     environment     variable     (defaulting     to
+       $HOME/.hledger.journal);  or you can specify files with -f options.  It
+       can also read timeclock files, timedot files, or any  CSV/SSV/TSV  file
+       with a date field.
+
+       Here is a small journal file describing one transaction:
+
+              2015-10-16 bought food
+                expenses:food          $10
+                assets:cash
+
+       Transactions  are  dated movements of money (etc.)  between two or more
+       accounts: bank accounts, your wallet, revenue/expense categories,  peo-
+       ple,  etc.  You can choose any account names you wish, using : to indi-
+       cate subaccounts.  There must be at least two  spaces  between  account
+       name  and amount.  Positive amounts are inflow to that account (debit),
+       negatives are outflow from it (credit).  (Some  reports  show  revenue,
+       liability  and equity account balances as negative numbers as a result;
+       this is normal.)
+
+       hledger's add command can help you add transactions, or you can install
+       other data entry UIs like hledger-web or hledger-iadd.  For more exten-
+       sive/efficient changes, use a text editor: Emacs + ledger-mode,  VIM  +
+       vim-ledger,  or  VS  Code  +  hledger-vscode are some good choices (see
+       https://hledger.org/editors.html).
+
+       To get started, run hledger add and follow the prompts,  or  save  some
+       entries  like  the  above  in $HOME/.hledger.journal, then try commands
+       like:
+
+              $ hledger print -x
+              $ hledger aregister assets
+              $ hledger balance
+              $ hledger balancesheet
+              $ hledger incomestatement
+
+       Run hledger to list the commands.  See also  the  "Starting  a  journal
+       file" and "Setting opening balances" sections in PART 5: COMMON TASKS.
+
+PART 1: USER INTERFACE
+Input
+       hledger  reads  one  or more data files, each time you run it.  You can
+       specify a file with -f, like so
+
+              $ hledger -f FILE [-f FILE2 ...] print
+
+       Files are most often in hledger's journal  format,  with  the  .journal
+       file  extension (.hledger or .j also work); these files describe trans-
+       actions, like an accounting general journal.
+
+       When no file is specified, hledger looks for .hledger.journal  in  your
+       home directory.
+
+       But  most  people prefer to keep financial files in a dedicated folder,
+       perhaps with version control.  Also, starting a new journal  file  each
+       year  is  common (it's not required, but helps keep things fast and or-
+       ganised).  So we usually configure a different journal file, by setting
+       the  LEDGER_FILE  environment  variable,  to   something   like   ~/fi-
+       nance/2023.journal.   For more about how to do that on your system, see
+       Common tasks > Setting LEDGER_FILE.
+
+   Text encoding
+       hledger input files containing non-ascii characters must use UTF-8  en-
+       coding,  with  the  exception  of CSV (SSV, TSV..)  files, which can be
+       read from other encodings (see encoding CSV rule).
+
+       In UTF-8 input files, an optional byte order mark (BOM) at  the  begin-
+       ning of the file is allowed.
+
+       Your  system  may  need to be configured with a locale that understands
+       the input file's encoding.  Eg on some unix systems, you may  need  set
+       the LANG environment variable.  You can read more about this in Unicode
+       characters, below.
+
+       On some unix systems you can use the file command to show a file's text
+       encoding.   On mac, you'll need the version from homebrew: brew install
+       file-formula.
+
+       hledger's text output is always UTF-8 encoded.
+
+   Data formats
+       Usually the data file is in hledger's journal format, but it can be  in
+       any of the supported file formats, which currently are:
+
+       Reader:         Reads:                              Automatically  used for
+                                                           files with extensions:
+       -----------------------------------------------------------------------------
+       journal         hledger journal  files  and  some   .journal   .j  .hledger
+                       Ledger journals, for transactions   .ledger
+       timeclock       timeclock files, for precise time   .timeclock
+                       logging
+       timedot         timedot  files,  for  approximate   .timedot
+                       time logging
+       csv             Comma  or  other  character sepa-   .csv
+                       rated values, for data import
+       ssv             Semicolon separated values          .ssv
+       tsv             Tab separated values                .tsv
+       rules           CSV/SSV/TSV/other separated  val-   .rules
+                       ues, alternate way
+
+       These formats are described in more detail below.
+
+       hledger  detects  the format automatically based on the file extensions
+       shown above.  If it can't recognise  the  file  extension,  it  assumes
+       journal  format.   So  for  non-journal  files, it's important to use a
+       recognised file extension, so as to either read successfully or to show
+       relevant error messages.
+
+       You can also force a specific reader/format by prefixing the file  path
+       with  the  format  and a colon.  Eg, to read a .dat file containing tab
+       separated values:
+
+              $ hledger -f tsv:/some/file.dat stats
+
+   Standard input
+       The file name - means standard input:
+
+              $ cat FILE | hledger -f- print
+
+       If reading non-journal data in this way, you'll need to write the  for-
+       mat as a prefix, like timeclock: here:
+
+              $ echo 'i 2009/13/1 08:00:00' | hledger print -f timeclock:-
+
+   Multiple files
+       You  can specify multiple -f options, to read multiple files as one big
+       journal.  When doing this, note that certain features (described below)
+       will be affected:
+
+       o Balance assertions will not see the effect of transactions in  previ-
+         ous  files.   (Usually  this doesn't matter as each file will set the
+         corresponding opening balances.)
+
+       o Some directives will not affect previous or subsequent files.
+
+       If needed, you can work around these by  using  a  single  parent  file
+       which includes the others, or concatenating the files into one, eg: cat
+       a.journal b.journal | hledger -f- CMD.
+
+   Strict mode
+       hledger checks input files for valid data.  By default, the most impor-
+       tant  errors  are  detected,  while  still accepting easy journal files
+       without a lot of declarations:
+
+       o Are the input files parseable, with valid syntax ?
+
+       o Are all transactions balanced ?
+
+       o Do all balance assertions pass ?
+
+       With the -s/--strict flag, additional checks are performed:
+
+       o Are all accounts posted to, declared  with  an  account  directive  ?
+         (Account error checking)
+
+       o Are all commodities declared with a commodity directive ?  (Commodity
+         error checking)
+
+       o Are all commodity conversions declared explicitly ?
+
+       You  can  use  the  check  command to run individual checks -- the ones
+       listed above and some more.
+
+Commands
+       hledger provides various subcommands for getting things done.  Most  of
+       these  commands  do  not change the journal file; they just read it and
+       output a report.  A few commands assist with adding data and file  man-
+       agement.
+
+       To  show a summary of commands, run hledger with no arguments.  You can
+       see the same commands summary at the start of PART 4: COMMANDS below.
+
+       To use a particular command, run hledger CMD [CMDOPTS] [CMDARGS],
+
+       o CMD is the full command name, or its standard abbreviation  shown  in
+         the commands list, or any unambiguous prefix of the name.
+
+       o CMDOPTS  are  command-specific options, if any.  Command-specific op-
+         tions must be written after the command name.  Eg: hledger print -x.
+
+       o CMDARGS are additional  arguments  to  the  command,  if  any.   Most
+         hledger  commands accept arguments representing a query, to limit the
+         data in some way.  Eg: hledger reg assets:checking.
+
+       To list a command's options, arguments, and documentation in the termi-
+       nal, run hledger CMD -h.  Eg: hledger bal -h.
+
+   Add-on commands
+       In addition to the built-in commands, you can install add-on  commands:
+       programs  or  scripts named "hledger-SOMETHING", which will also appear
+       in hledger's commands list.  If you used  the  hledger-install  script,
+       you  will  have  several  add-ons  installed already.  Some more can be
+       found    in     hledger's     bin/     directory,     documented     at
+       https://hledger.org/scripts.html.
+
+       More precisely, add-on commands are programs or scripts in your shell's
+       PATH, whose name starts with "hledger-" and ends with no extension or a
+       recognised  extension  (".bat",  ".com",  ".exe", ".hs", ".js", ".lhs",
+       ".lua", ".php", ".pl", ".py", ".rb", ".rkt", or ".sh"),  and  (on  unix
+       and mac) which has executable permission for the current user.
+
+       You can run add-on commands using hledger, much like built-in commands:
+       hledger ADDONCMD [-- ADDONCMDOPTS] [ADDONCMDARGS].  But note the double
+       hyphen  argument, required before add-on-specific options.  Eg: hledger
+       ui -- --watch or hledger web -- --serve.  If  this  causes  difficulty,
+       you  can  always  run  the  add-on  directly,  without  using  hledger:
+       hledger-ui --watch or hledger-web --serve.
+
+Options
+       Run hledger -h to see general command line help.  Options can be  writ-
+       ten  either  before  or after the command name.  These options are spe-
+       cific to the hledger CLI:
+
+              Flags:
+                   --conf=CONFFILE        Use extra options defined in this config file. If
+                                          not specified, searches upward and in XDG config
+                                          dir for hledger.conf (or .hledger.conf in $HOME).
+                -n --no-conf              ignore any config file
+
+       And the following general options are common to most hledger commands:
+
+              General input/data transformation flags:
+                -f --file=[FMT:]FILE      Read data from FILE, or from stdin if FILE is -,
+                                          inferring format from extension or a FMT: prefix.
+                                          Can be specified more than once. If not specified,
+                                          reads from $LEDGER_FILE or $HOME/.hledger.journal.
+                   --rules=RULESFILE      Use rules defined in this rules file for
+                                          converting subsequent CSV/SSV/TSV files. If not
+                                          specified, uses FILE.csv.rules for each FILE.csv.
+                   --alias=A=B|/RGX/=RPL  transform account names from A to B, or by
+                                          replacing regular expression matches
+                   --auto                 generate extra postings by applying auto posting
+                                          rules ("=") to all transactions
+                   --forecast[=PERIOD]    Generate extra transactions from periodic rules
+                                          ("~"), from after the latest ordinary transaction
+                                          until 6 months from now. Or, during the specified
+                                          PERIOD (the equals is required). Auto posting rules
+                                          will also be applied to these transactions. In
+                                          hledger-ui, also make future-dated transactions
+                                          visible at startup.
+                -I --ignore-assertions    don't check balance assertions by default
+                   --infer-costs          infer conversion equity postings from costs
+                   --infer-equity         infer costs from conversion equity postings
+                   --infer-market-prices  infer market prices from costs
+                   --pivot=TAGNAME        use a different field or tag as account names
+                -s --strict               do extra error checks (and override -I)
+                   --verbose-tags         add tags indicating generated/modified data
+
+              General output/reporting flags (supported by some commands):
+                -b --begin=DATE           include postings/transactions on/after this date
+                -e --end=DATE             include postings/transactions before this date
+                                          (with a report interval, will be adjusted to
+                                          following subperiod end)
+                -D --daily                multiperiod report with 1 day interval
+                -W --weekly               multiperiod report with 1 week interval
+                -M --monthly              multiperiod report with 1 month interval
+                -Q --quarterly            multiperiod report with 1 quarter interval
+                -Y --yearly               multiperiod report with 1 year interval
+                -p --period=PERIODEXP     set begin date, end date, and/or report interval,
+                                          with more flexibility
+                   --today=DATE           override today's date (affects relative dates)
+                   --date2                match/use secondary dates instead (deprecated)
+                -U --unmarked             include only unmarked postings/transactions
+                -P --pending              include only pending postings/transactions
+                -C --cleared              include only cleared postings/transactions
+                                          (-U/-P/-C can be combined)
+                -R --real                 include only non-virtual postings
+                -E --empty                Show zero items, which are normally hidden.
+                                          In hledger-ui & hledger-web, do the opposite.
+                   --depth=DEPTHEXP       if a number (or -NUM): show only top NUM levels
+                                          of accounts. If REGEXP=NUM, only apply limiting to
+                                          accounts matching the regular expression.
+                -B --cost                 show amounts converted to their cost/sale amount
+                -V --market               Show amounts converted to their value at period
+                                          end(s) in their default valuation commodity.
+                                          Equivalent to --value=end.
+                -X --exchange=COMM        Show amounts converted to their value at period
+                                          end(s) in the specified commodity.
+                                          Equivalent to --value=end,COMM.
+                   --value=WHEN[,COMM]    show amounts converted to their value on the
+                                          specified date(s) in their default valuation
+                                          commodity or a specified commodity. WHEN can be:
+                                          'then':     value on transaction dates
+                                          'end':      value at period end(s)
+                                          'now':      value today
+                                          YYYY-MM-DD: value on given date
+                -c --commodity-style=S    Override a commodity's display style.
+                                          Eg: -c '.' or -c '1.000,00 EUR'
+                   --pretty[=YN]          Use box-drawing characters in text output? Can be
+                                          'y'/'yes' or 'n'/'no'.
+                                          If YN is specified, the equals is required.
+
+              General help flags:
+                -h --help                 show command line help
+                   --tldr                 show command examples with tldr
+                   --info                 show the manual with info
+                   --man                  show the manual with man
+                   --version              show version information
+                   --debug=[1-9]          show this much debug output (default: 1)
+                   --pager=YN             use a pager when needed ? y/yes (default) or n/no
+                   --color=YNA --colour   use ANSI color ? y/yes, n/no, or auto (default)
+
+       Usually hledger accepts any unambiguous flag prefix, eg you  can  write
+       --tl instead of --tldr or --dry instead of --dry-run.
+
+       If  the  same  option  appears more than once in a command, usually the
+       last (right-most) wins.
+
+       With most commands, arguments are interpreted as a hledger query  which
+       filter  the data.  Some queries can be expressed either with options or
+       with arguments.
+
+       Below are more tips for using the command line interface - feel free to
+       skip these until you need them.
+
+   Special characters
+       Here we touch on shell escaping/quoting rules, and give some  examples.
+       This  is  a slightly complicated topic which you may not need at first,
+       but you should be aware of it, so you can return here when needed.
+
+       If you are able to minimise the use of special characters in your data,
+       you won't need escaping as much, and your command lines  will  be  sim-
+       pler.   For  example,  avoiding  spaces  in account names, and using an
+       ISO-4217 currency code like USD instead of the $ currency  symbol,  can
+       be helpful.
+
+       But  if you want to use spaced account names and $, go right ahead; es-
+       caping isn't a big deal.
+
+   Escaping shell special characters
+       At the command line, characters which have  special  meaning  for  your
+       shell must be "shell-escaped" (AKA "quoted") if you want hledger to see
+       them.  Often these include space, <, >, (, ), |, \, $ and/or %.
+
+       For  example,  to  match  an account name containing the phrase "credit
+       card", don't write this:
+
+              $ hledger register credit card
+
+       In that command, "credit" and "card" are treated as separate query  ar-
+       guments  (described below), so this would match accounts containing ei-
+       ther word.  Instead, enclose the phrase in double or single quotes:
+
+              $ hledger register "credit card"
+
+       In Unix shells, writing a backslash before the character can also work.
+       Eg:
+
+              $ hledger register credit\ card
+
+       Some shell characters  still  have  a  special  meaning  inside  double
+       quotes, such as the dollar sign ($).  Eg in "assets:$account", the bash
+       shell  would  replace  $account with the value of a shell variable with
+       that name.  When you don't want that, use single quotes,  which  escape
+       more strongly:
+
+              $ hledger balance 'assets:$account'
+
+   Escaping on Windows
+       If you are using hledger in a Powershell or Command window on Microsoft
+       Windows, the escaping rules are different:
+
+       o In  a  Powershell  window (powershell, blue background), you must use
+         double quotes or single quotes (not backslash).
+
+       o In a Command window (cmd, black  background),  you  must  use  double
+         quotes (not single quotes or backslash).
+
+       The  next two sections were written for Unix-like shells, so might need
+       to be adapted if you're using cmd or powershell.  (Edits welcome.)
+
+   Escaping regular expression special characters
+       Many hledger arguments are regular expressions (described  below),  and
+       these  too  have characters which cause special effects.  Some of those
+       characters are ., ^, $, [, ], (, ), |, and  \.   When  you  don't  want
+       these  to cause special effects, you can "regex-escape" them by writing
+       \ (a backslash) before them.  But since backslash is  also  special  to
+       the shell, you may need to also shell-escape the backslashes.
+
+       Eg, in the bash shell, to match a literal $ sign, you could write:
+
+              $ hledger balance cur:\\$
+
+       or:
+
+              $ hledger balance 'cur:\$'
+
+       (The  dollar sign is regex-escaped by the backslash preceding it.  Then
+       that backslash is shell-escaped by  another  backslash,  or  by  single
+       quotes.)
+
+   Escaping add-on arguments
+       When you run an external add-on command with hledger (described below),
+       any  options or arguments being passed through to the add-on executable
+       lose one level of shell-escaping, so you must add  an  extra  level  of
+       shell-escaping to compensate.
+
+       Eg, in the bash shell, to run the ui add-on and match a literal $ sign,
+       you need to write:
+
+              $ hledger ui cur:'\\$'
+
+       or:
+
+              $ hledger ui cur:\\\\$
+
+       If you are wondering why four backslashes:
+
+       o $ is unescaped
+
+       o \$ is regex-escaped
+
+       o \\$ is regex-escaped, then shell-escaped
+
+       o \\\\$  is  regex-escaped,  then  shell-escaped, then both slashes are
+         shell-escaped once more for hledger argument pass-through.
+
+       Or you can avoid such triple-escaping, by running the add-on executable
+       directly:
+
+              $ hledger-ui cur:\\$
+
+   Escaping in other situations
+       hledger options and arguments are sometimes used in places  other  than
+       the  command  line,  with different escaping rules.  For example, back-
+       slash-quoting generally does not work there.  Here are some more tips.
+
+       In Windows cmd      Use double quotes
+       In Windows power-   Use single or double quotes
+       shell
+       In   hledger-ui's   Use single or double quotes
+       filter prompt
+       In  hledger-web's   Use single or double quotes
+       search form
+       In  an   argument   Don't  use  spaces, don't shell-escape, do regex-es-
+       file                cape when needed
+       In a config file    Use single or double quotes, and enclose  the  whole
+                           argument ("desc:a b" not desc:"a b")
+       In    ghci   (the   Use double quotes, and enclose the whole argument
+       Haskell REPL)
+
+   Using a wild card
+       When escaping a special character is too much hassle  (or  impossible),
+       you  can  often just write . (period) instead.  In regular expressions,
+       this means "accept any character here".  Eg:
+
+              $ hledger register credit.card
+
+   Unicode characters
+       hledger is expected to handle non-ascii characters correctly:
+
+       o they should be parsed correctly in input files  and  on  the  command
+         line,  by all hledger tools (add, iadd, hledger-web's search/add/edit
+         forms, etc.)
+
+       o they  should  be  displayed  correctly  by  all  hledger  tools,  and
+         on-screen alignment should be preserved.
+
+       This requires a well-configured environment.  Here are some tips:
+
+       o A  system  locale must be configured, and it must be one that can de-
+         code the characters being used.  In bash, you can set a  locale  like
+         this:  export LANG=en_US.UTF-8.  There are some more details in Trou-
+         bleshooting.  This step is essential - without it, hledger will  quit
+         on  encountering a non-ascii character (as with all GHC-compiled pro-
+         grams).
+
+       o Your terminal software (eg  Terminal.app,  iTerm,  CMD.exe,  xterm..)
+         must support unicode.  On Windows, you may need to use Windows Termi-
+         nal and/or enable UTF-8 support.
+
+       o The terminal must be using a font which includes the required unicode
+         glyphs.
+
+       o The  terminal should be configured to display wide characters as dou-
+         ble width (for report alignment).
+
+       o On Windows, for best results you should run hledger in the same  kind
+         of  environment in which it was built.  Eg hledger built in the stan-
+         dard CMD.EXE environment (like the binaries  on  our  download  page)
+         might  show  display  problems when run in a cygwin or msys terminal,
+         and vice versa.  (See eg #961).
+
+   Regular expressions
+       A regular expression (regexp) is a small piece of  text  where  certain
+       characters  (like  .,  ^, $, +, *, (), |, [], \) have special meanings,
+       forming a tiny language for matching text precisely -  very  useful  in
+       hledger  and elsewhere.  To learn all about them, visit regular-expres-
+       sions.info.
+
+       hledger supports regexps whenever you are entering a pattern  to  match
+       something,  eg  in  query  arguments,  account  aliases,  CSV if rules,
+       hledger-web's search form, hledger-ui's / search, etc.  You may need to
+       wrap them in quotes, especially at the command line (see Special  char-
+       acters above).  Here are some examples:
+
+       Account name queries (quoted for command line use):
+
+              Regular expression:  Matches:
+              -------------------  ------------------------------------------------------------
+              bank                 assets:bank, assets:bank:savings, expenses:art:banksy, ...
+              :bank                assets:bank:savings, expenses:art:banksy
+              :bank:               assets:bank:savings
+              '^bank'              none of those ( ^ matches beginning of text )
+              'bank$'              assets:bank   ( $ matches end of text )
+              'big \$ bank'        big $ bank    ( \ disables following character's special meaning )
+              '\bbank\b'           assets:bank, assets:bank:savings  ( \b matches word boundaries )
+              '(sav|check)ing'     saving or checking  ( (|) matches either alternative )
+              'saving|checking'    saving or checking  ( outer parentheses are not needed )
+              'savings?'           saving or savings   ( ? matches 0 or 1 of the preceding thing )
+              'my +bank'           my bank, my  bank, ... ( + matches 1 or more of the preceding thing )
+              'my *bank'           mybank, my bank, my  bank, ... ( * matches 0 or more of the preceding thing )
+              'b.nk'               bank, bonk, b nk, ... ( . matches any character )
+
+       Some other queries:
+
+              desc:'amazon|amzn|audible'  Amazon transactions
+              cur:EUR              amounts with commodity symbol containing EUR
+              cur:'\$'             amounts with commodity symbol containing $
+              cur:'^\$$'           only $ amounts, not eg AU$ or CA$
+              cur:....?            amounts with 4-or-more-character symbols
+              tag:.=202[1-3]       things with any tag whose value contains 2021, 2022 or 2023
+
+       Account name aliases: accept . instead of : as account separator:
+
+              alias /\./=:         replaces all periods in account names with colons
+
+       Show multiple top-level accounts combined as one:
+
+              --alias='/^[^:]+/=combined'  ( [^:] matches any character other than : )
+
+       Show accounts with the second-level part removed:
+
+              --alias '/^([^:]+):[^:]+/ = \1'
+                                   match a top-level account and a second-level account
+                                   and replace those with just the top-level account
+                                   ( \1 in the replacement text means "whatever was matched
+                                   by the first parenthesised part of the regexp"
+
+       CSV rules: match CSV records containing dining-related MCC codes:
+
+              if \?MCC581[124]
+
+       Match CSV records with a specific amount around the end/start of month:
+
+              if %amount \b3\.99
+              &  %date   (29|30|31|01|02|03)$
+
+   hledger's regular expressions
+       hledger's  regular  expressions  come  from the regex-tdfa library.  If
+       they're not doing what you expect, it's important to know exactly  what
+       they support:
+
+       1. they are case insensitive
+
+       2. they  are infix matching (they do not need to match the entire thing
+          being matched)
+
+       3. they are POSIX ERE (extended regular expressions)
+
+       4. they also support GNU word boundaries (\b, \B, \<, \>)
+
+       5. backreferences are supported when doing text replacement in  account
+          aliases  or  CSV  rules, where backreferences can be used in the re-
+          placement string to reference capturing groups in the search regexp.
+          Otherwise, if you write \1, it will match the digit 1.
+
+       6. they do not support mode modifiers ((?s)),  character  classes  (\w,
+          \d), or anything else not mentioned above.
+
+       7. they  may  not  (I'm guessing not) properly support right-to-left or
+          bidirectional text.
+
+       Some things to note:
+
+       o In the alias directive and --alias option, regular  expressions  must
+         be  enclosed  in  forward  slashes  (/REGEX/).  Elsewhere in hledger,
+         these are not required.
+
+       o In queries, to match a regular expression metacharacter like $  as  a
+         literal  character,  prepend  a  backslash.  Eg to search for amounts
+         with the dollar sign in hledger-web, write cur:\$.
+
+       o On the command line, some metacharacters like $ have a special  mean-
+         ing to the shell and so must be escaped at least once more.  See Spe-
+         cial characters.
+
+   Argument files
+       You can save a set of command line options and arguments in a file, and
+       then  reuse  them by writing @FILENAME as a command line argument.  Eg:
+       hledger bal @foo.args.
+
+       An argument file's format is more restrictive than  the  command  line.
+       Each line should contain just one option or argument.  Don't use spaces
+       except  inside  quotes; write = or nothing between a flag and its argu-
+       ment.  If you use quotes, they must enclose the whole  line.   For  the
+       special  characters mentioned above, use one less level of quoting than
+       you would at the command line.
+
+   Config files
+       With hledger 1.40+, you can save extra command line options  and  argu-
+       ments  in  a more featureful hledger config file.  Here's a small exam-
+       ple:
+
+              # General options are listed first, and used with hledger commands that support them.
+              --pretty
+
+              # Options following a `[COMMAND]` heading are used with that hledger command only.
+              [print]
+              --explicit --show-costs
+
+       To use a config file, specify it with the --conf option.   Its  options
+       will  be inserted near the start of your command line, so you can over-
+       ride them with command line options if needed.
+
+       Or, you can set up an automatic config file that is used  whenever  you
+       run  hledger,  by  creating  hledger.conf  in  the current directory or
+       above, or .hledger.conf in your home  directory  (~/.hledger.conf),  or
+       hledger.conf     in     your     XDG    config    directory    (~/.con-
+       fig/hledger/hledger.conf).
+
+       Here   is   another   example   config   you    could    start    with:
+       https://github.com/simonmichael/hledger/blob/master/hledger.conf.sample
+
+       You  can put not only options, but also arguments in a config file.  If
+       the first word in a config file's top (general) section does not  begin
+       with  a  dash (eg: print), it is treated as the command argument (over-
+       riding any argument on the command line).
+
+       On unix machines, you can add a shebang line at the  top  of  a  config
+       file,  set executable permission on the file, and use it like a script.
+       Eg (the -S is needed on some operating systems):
+
+              #!/usr/bin/env -S hledger --conf
+
+       You can ignore config files by adding the -n/--no-conf flag to the com-
+       mand line.  This is useful when using hledger in scripts, or when trou-
+       bleshooting.  When both --conf and  --no-conf  options  are  used,  the
+       right-most wins.
+
+       To inspect the processing of config files, use --debug or --debug=8.
+
+       Warning!
+
+       There  aren't  many  hledger  features that need a warning, but this is
+       one!
+
+       Automatic config files, while convenient, also make hledger  less  pre-
+       dictable  and dependable.  It's easy to make a config file that changes
+       a report's behaviour, or  breaks  your  hledger-using  scripts/applica-
+       tions, in ways that will surprise you later.
+
+       If you don't want this,
+
+       1. Just don't create a hledger.conf file on your machine.
+
+       2. Also  be  alert  to  downloaded  directories  which  may  contain  a
+          hledger.conf file.
+
+       3. Also if you are sharing scripts or  examples  or  support,  consider
+          that others may have a hledger.conf file.
+
+       Conversely, once you decide to use this feature, try to remember:
+
+       1. Whenever  a  hledger command does not work as expected, try it again
+          with -n (--no-conf) to see if a config file was to blame.
+
+       2. Whenever you call hledger from a script, consider whether that  call
+          should use -n or not.
+
+       3. Be  conservative about what you put in your config file; try to con-
+          sider the effect on all your reports.
+
+       4. To troubleshoot the effect of config  files,  run  with  --debug  or
+          --debug 8.
+
+       The config file feature was added in hledger 1.40 and is considered ex-
+       perimental.
+
+   Shell completions
+       If  you  use  the  bash  or  zsh shells, you can optionally set up con-
+       text-sensitive autocompletion for hledger command lines.  Try  pressing
+       hledger<SPACE><TAB><TAB>  (should list all hledger commands) or hledger
+       reg acct:<TAB><TAB> (should list your  top-level  account  names).   If
+       completions  aren't  working,  or for more details, see Install > Shell
+       completions.
+
+Output
+   Output destination
+       hledger commands send their output to the terminal by default.  You can
+       of course redirect this, eg into a file, using standard shell syntax:
+
+              $ hledger print > foo.txt
+
+       Some commands (print, register, stats, the balance commands) also  pro-
+       vide  the  -o/--output-file  option,  which does the same thing without
+       needing the shell.  Eg:
+
+              $ hledger print -o foo.txt
+              $ hledger print -o -        # write to stdout (the default)
+
+   Output format
+       Some commands offer other kinds of output, not just text on the  termi-
+       nal.  Here are those commands and the formats currently supported:
+
+       command                 txt     html     csv/tsv     fods     beancount      sql     json
+       --------------------------------------------------------------------------------------------
+       aregister               Y       Y        Y           Y                               Y
+       balance                 Y       Y        Y           Y                               Y
+       balancesheet            Y       Y        Y           Y                               Y
+       balancesheetequity      Y       Y        Y           Y                               Y
+       cashflow                Y       Y        Y           Y                               Y
+       incomestatement         Y       Y        Y           Y                               Y
+       print                   Y       Y        Y           Y        Y              Y       Y
+       register                Y       Y        Y           Y                               Y
+
+       You  can  also  see  which output formats a command supports by running
+       hledger CMD -h and looking for the -O/--output-format=FMT option,
+
+       You can select the output format by using that option:
+
+              $ hledger print -O csv    # print CSV to standard output
+
+       or by  choosing  a  suitable  filename  extension  with  the  -o/--out-
+       put-file=FILE.FMT option:
+
+              $ hledger balancesheet -o foo.csv    # write CSV to foo.csv
+
+       The -O option can be combined with -o to override the file extension if
+       needed:
+
+              $ hledger balancesheet -o foo.txt -O csv    # write CSV to foo.txt
+
+       Here are some notes about the various output formats.
+
+   Text output
+       This is the default: human readable, plain text report output, suitable
+       for viewing with a monospace font in a terminal.  If your data contains
+       unicode or wide characters, you'll need a terminal and font that render
+       those correctly.  (This can be challenging on MS Windows.)
+
+       Some  reports  (register,  aregister) will normally use the full window
+       width.  If this isn't working or you want to override it, you  can  use
+       the -w/--width option.
+
+       Balance  reports (balance, balancesheet, incomestatement...)  use what-
+       ever width they need.  Multi-period multi-currency reports can often be
+       wider than the window.  Besides using a pager, helpful  techniques  for
+       this  situation  include  --layout=bare, -V, cur:, --transpose, --tree,
+       --depth, --drop, switching to html output, etc.
+
+   Box-drawing characters
+       hledger draws simple table borders by default, to minimise the risk  of
+       display  problems  caused by a terminal/font not supporting box-drawing
+       characters.
+
+       But your terminal and font probably do support them,  so  we  recommend
+       using  the --pretty flag to show prettier tables in the terminal.  This
+       is a good flag to add to your hledger config file.
+
+   Colour
+       hledger tries to automatically detect ANSI colour and text styling sup-
+       port and use it when appropriate.  (Currently, it is used rather  mini-
+       mally:  some reports show negative numbers in red, and help output uses
+       bold text for emphasis.)
+
+       You can override this by setting the NO_COLOR environment  variable  to
+       disable  it,  or  by using the --color/--colour option, perhaps in your
+       config file, with a y/yes or n/no value to force it on or off.
+
+   Paging
+       In unix-like environments, when displaying large output (in any  output
+       format) in the terminal, hledger tries to use a pager when appropriate.
+       (You  can disable this with the --pager=no option, perhaps in your con-
+       fig file.)
+
+       The pager shows one page of text at a time, and lets you scroll  around
+       to  see more.  While it is active, usually SPACE shows the next page, h
+       shows help, and q quits.  The home/end/page up/page  down/cursor  keys,
+       and mouse scrolling, may also work.
+
+       hledger will use the pager specified by the PAGER environment variable,
+       otherwise  less  if  available, otherwise more if available.  (With one
+       exception: hledger help -p TOPIC will always use less, so that  it  can
+       scroll to the topic.)
+
+       The  pager  is  expected  to  display  hledger's  ANSI  colour and text
+       styling.  If you see junk characters, you might need to configure  your
+       pager  to  handle ANSI codes.  Or you could disable colour as described
+       above.
+
+       If you are using the less pager, hledger automatically appends a number
+       of options to the LESS variable to enable ANSI colour and a  number  of
+       other   conveniences.   (At  the  time  of  writing:  --chop-long-lines
+       --hilite-unread   --ignore-case   --mouse    --no-init    --quit-at-eof
+       --quit-if-one-screen            --RAW-CONTROL-CHARS           --shift=8
+       --squeeze-blank-lines --use-backslash ).  If these don't work well, you
+       can set your preferred options in the HLEDGER_LESS variable, which will
+       be used instead.
+
+   HTML output
+       HTML output can be styled by an optional hledger.css file in  the  same
+       directory.
+
+       HTML output will be UTF-8 encoded.  If your web browser is showing junk
+       characters,  you  may need to change its text encoding to UTF-8.  Eg in
+       Safari, see View -> Text Encoding and Settings -> Advanced  ->  Default
+       Encoding.
+
+   CSV / TSV output
+       In  CSV or TSV output, digit group marks (such as thousands separators)
+       are disabled automatically.
+
+   FODS output
+       FODS is the OpenDocument Spreadsheet format as plain XML,  as  accepted
+       by  LibreOffice  and OpenOffice.  If you use their spreadsheet applica-
+       tions, this is better than CSV because it works across locales (decimal
+       point vs.  decimal comma, character encoding stored in XML header, thus
+       no problems with umlauts), it supports fixed header rows  and  columns,
+       cell  types  (string  vs.   number vs.  date), separation of number and
+       currency (currency is displayed but the cell type is still a number ac-
+       cessible for computation), styles (bold), borders.  Btw.  you can still
+       extract CSV from FODS/ODS  using  various  utilities  like  libreoffice
+       --headless or ods2csv.
+
+   Beancount output
+       This  is  Beancount's  journal format.  You can use this to export your
+       hledger data to Beancount, eg to use the Fava web app.
+
+       hledger will try to adjust your data to suit Beancount,  automatically.
+       Be  cautious  and  check  the  conversion until you are confident it is
+       good.  If you plan to export to Beancount often, you may want to follow
+       its conventions, for a cleaner conversion:
+
+       o use Beancount-friendly account names
+
+       o use currency codes instead of currency symbols
+
+       o use cost notation instead of equity conversion postings
+
+       o avoid virtual postings
+
+       There is one big adjustment you must handle  yourself:  for  Beancount,
+       the  top  level  account names must be Assets, Liabilities, Equity, In-
+       come, and/or Expenses.  You can use account aliases to rewrite your ac-
+       count names temporarily, if needed, as in  this  hledger2beancount.conf
+       config file.
+
+       2024-12-20: Some more things not yet handled for you:
+
+       o P directives are not converted automatically - convert those yourself
+
+       o Balance assignments are not converted (Beancount doesnt support them)
+         - replace those with explicit amounts
+
+   Beancount account names
+       Aside  from the top-level names, hledger will adjust your account names
+       to make valid Beancount account names, by capitalising each  part,  re-
+       placing  spaces  with  -,  replacing  other unsupported characters with
+       C<HEXBYTES>, prepending A to account name parts which don't begin  with
+       a  letter  or  digit, and appending :A to account names which have only
+       one part.
+
+   Beancount commodity names
+       hledger will adjust your commodity names to make valid  Beancount  com-
+       modity/currency names, which must be 2-24 uppercase letters, digits, or
+       ',  ., _, -, beginning with a letter and ending with a letter or digit.
+       hledger will convert known currency symbols to ISO 4217 currency codes,
+       capitalise letters, replace spaces with -,  replace  other  unsupported
+       characters with C<HEXBYTES>, and prepend or append C if needed.
+
+   Beancount virtual postings
+       Beancount doesn't allow virtual postings; if you have any, they will be
+       omitted from beancount output.
+
+   Beancount metadata
+       hledger  tags  will be converted to Beancount metadata (except for tags
+       whose name begins with _).  Metadata names will be adjusted to be Bean-
+       count-compatible: beginning with a lowercase letter, at least two char-
+       acters long, and with unsupported characters encoded.  Metadata  values
+       will use Beancount's string type.
+
+       In  hledger,  objects can have the same tag repeated with multiple val-
+       ues.   Eg  an  assets:cash  account  might  have  both  type:Asset  and
+       type:Cash  tags.   For  Beancount these will be combined into one, with
+       the values combined, comma separated.  Eg: type: "Asset, Cash".
+
+   Beancount costs
+       Beancount doesn't allow redundant  costs  and  conversion  postings  as
+       hledger  does.   If you have any of these, the conversion postings will
+       be omitted.  Currently we support at most one cost +  conversion  post-
+       ings group per transaction.
+
+   Beancount operating currency
+       Declaring  an  operating  currency  (or several) improves Beancount and
+       Fava reports.  Currently hledger will declare  each  currency  used  in
+       cost  amounts  as an operating currency.  If needed, replace these with
+       your own declaration, like
+
+              option "operating_currency" "USD"
+
+   SQL output
+       SQL output is expected to work at least with SQLite,  MySQL  and  Post-
+       gres.
+
+       The  SQL  statements are expected to be executed in the empty database.
+       If you already have tables created via SQL output of hledger, you would
+       probably want to either clear data from these (via delete  or  truncate
+       SQL  statements) or drop the tables completely before import; otherwise
+       your postings would be duplicated.
+
+       For SQLite, it is more useful if you modify the generated id  field  to
+       be a PRIMARY KEY.  Eg:
+
+              $ hledger print -O sql | sed 's/id serial/id INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL/g' | ...
+
+       This is not yet much used; feedback is welcome.
+
+   JSON output
+       Our  JSON is rather large and verbose, since it is a faithful represen-
+       tation of hledger's internal data types.  To understand its  structure,
+       read    the   Haskell   type   definitions,   which   are   mostly   in
+       https://github.com/simonmichael/hledger/blob/mas-
+       ter/hledger-lib/Hledger/Data/Types.hs.  hledger-web's OpenAPI  specifi-
+       cation may also be relevant.
+
+       hledger  stores  numbers  with  sometimes up to 255 significant digits.
+       This is too many digits for most JSON consumers, so in JSON  output  we
+       round numbers to at most 10 decimal places.  (We don't limit the number
+       of  integer  digits.)  If you find this causing problems, please let us
+       know.  Related: #1195
+
+       This is not yet much used; feedback is welcome.
+
+   Commodity styles
+       When displaying amounts, hledger infers a standard  display  style  for
+       each commodity/currency, as described below in Commodity display style.
+
+       If needed, this can be overridden by a -c/--commodity-style option (ex-
+       cept for cost amounts and amounts displayed by the print command, which
+       are  always  displayed with all decimal digits).  For example, the fol-
+       lowing will force dollar amounts to be displayed as shown:
+
+              $ hledger print -c '$1.000,0'
+
+       This option can be repeated to set the display style for multiple  com-
+       modities/currencies.  Its argument is as described in the commodity di-
+       rective.
+
+       In  some  cases  hledger will adjust number formatting to improve their
+       parseability (such as adding trailing decimal marks when needed).
+
+   Debug output
+       We intend hledger to be relatively easy to troubleshoot, introspect and
+       develop.  You can add --debug[=N] to any hledger command  line  to  see
+       additional  debug  output.  N ranges from 1 (least output, the default)
+       to 9 (maximum output).  Typically you would start with 1  and  increase
+       until  you  are seeing enough.  Debug output goes to stderr, and is not
+       affected by -o/--output-file (unless you redirect stderr to stdout, eg:
+       2>&1).  It will be interleaved with normal output, which can  help  re-
+       veal  when parts of the code are evaluated.  To capture debug output in
+       a log file instead, you can usually redirect stderr, eg:
+
+              hledger bal --debug=3 2>hledger.log
+
+       (This option doesn't work in a config file yet.)
+
+Environment
+       These environment variables affect hledger:
+
+       HLEDGER_LESS If less is your pager, this variable  specifies  the  less
+       options  hledger  should  use.   (Otherwise,  LESS + custom options are
+       used.)
+
+       LEDGER_FILE The main journal  file  to  use  when  not  specified  with
+       -f/--file.  Default: $HOME/.hledger.journal.
+
+       NO_COLOR If this environment variable exists (with any value, including
+       empty),  hledger  will not use ANSI color codes in terminal output, un-
+       less overridden by an explicit --color=y or --colour=y option.
+
+PART 2: DATA FORMATS
+Journal
+       hledger's usual data source is a plain text file containing journal en-
+       tries in hledger journal format.  If you're looking for a quick  refer-
+       ence,  jump  ahead  to the journal cheatsheet (or use the table of con-
+       tents at https://hledger.org/hledger.html).
+
+       This file represents an accounting General Journal.  The .journal  file
+       extension  is most often used, though not strictly required.  The jour-
+       nal file contains a number of transaction entries,  each  describing  a
+       transfer  of  money  (or  any  commodity) between two or more named ac-
+       counts, in a simple format readable by both hledger and humans.
+
+       hledger's journal format is compatible with most  of  Ledger's  journal
+       format, but not all of it.  The differences and interoperation tips are
+       described  at  hledger and Ledger.  With some care, and by avoiding in-
+       compatible features, you can keep  your  hledger  journal  readable  by
+       Ledger  and vice versa.  This can useful eg for comparing the behaviour
+       of one app against the other.
+
+       You can use hledger without learning any more about this file; just use
+       the add or web or import commands to create and update it.
+
+       Many users, though, edit the journal file with a text editor, and track
+       changes with a version control system such as git.  Editor add-ons such
+       as ledger-mode or hledger-mode  for  Emacs,  vim-ledger  for  Vim,  and
+       hledger-vscode for Visual Studio Code, make this easier, adding colour,
+       formatting, tab completion, and useful commands.  See Editor configura-
+       tion at hledger.org for the full list.
+
+       A hledger journal file can contain three kinds of thing: comment lines,
+       transactions,  and/or  directives (including periodic transaction rules
+       and auto posting rules).  Understanding the journal  file  format  will
+       also  give  you a good understanding of hledger's data model.  Here's a
+       quick cheatsheet/overview, followed by detailed  descriptions  of  each
+       part.
+
+   Journal cheatsheet
+              # Here is the main syntax of hledger's journal format
+              # (omitting extra Ledger compatibility syntax).
+
+              ###############################################################################
+
+              # 1. These are comment lines, for notes or temporarily disabling things.
+              ; They begin with # or ;
+
+              comment
+              Or, lines can be enclosed within "comment" / "end comment".
+              This is a block of
+              commented lines.
+              end comment
+
+              # Some journal entries can have semicolon comments at end of line  ; like this
+              # Some of them require 2 or more spaces before the semicolon.
+
+              ###############################################################################
+
+              # 2. Directives customise processing or output in some way.
+              # You don't need any directives to get started.
+              # But they can add more error checking, or change how things are displayed.
+              # They begin with a word, letter, or symbol.
+              # They are most often placed at the top, before transactions.
+
+              account assets             ; Declare valid account names and display order.
+              account assets:savings     ; A subaccount. This one represents a bank account.
+              account assets:checking    ; Another. Note, 2+ spaces after the account name.
+              account assets:receivable  ; Accounting type is inferred from english names,
+              account passifs            ; or declared with a "type" tag, type:L
+              account expenses           ; type:X
+                                         ; A follow-on comment line, indented.
+              account expenses:rent      ; Expense and revenue categories are also accounts.
+                                         ; Subaccounts inherit their parent's type.
+
+              commodity $0.00         ; Declare valid commodities and their display styles.
+              commodity 1.000,00 EUR
+
+              decimal-mark .          ; The decimal mark used in this file (if ambiguous).
+
+              payee Whole Foods       ; Declare a valid payee name.
+
+              tag trip                ; Declare a valid tag name.
+
+              P 2024-03-01 AAPL $179  ; Declare a market price for AAPL in $ on this date.
+
+              include other.journal   ; Include another journal file here.
+
+              # Declare a recurring "periodic transaction", for budget/forecast reports
+              ~ monthly  set budget goals  ; <- Note, 2+ spaces before the description.
+                  (expenses:rent)      $1000
+                  (expenses:food)       $500
+
+              # Declare an auto posting rule, to modify existing transactions in reports
+              = revenues:consulting
+                  liabilities:tax:2024:us          *0.25  ; Add a tax liability & expense
+                  expenses:tax:2024:us            *-0.25  ; for 25% of the revenue.
+
+              ###############################################################################
+
+              # 3. Transactions are what it's all about.
+              # They are dated events, usually movements of money between 2 or more accounts.
+              # They begin with a numeric date.
+              # Here is their basic shape:
+              #
+              # DATE DESCRIPTION    ; The transaction's date and optional description.
+              #   ACCOUNT1  AMOUNT  ; A posting of an amount to/from this account, indented.
+              #   ACCOUNT2  AMOUNT  ; A second posting, balancing the first.
+              #   ...               ; More if needed. Amounts must sum to zero.
+              #                     ; Note, 2+ spaces between account names and amounts.
+
+              2024-01-01 opening balances         ; At the start, declare pre-existing balances this way.
+                  assets:savings          $10000  ; Account names can be anything. lower case is easy to type.
+                  assets:checking          $1000  ; assets, liabilities, equity, revenues, expenses are common.
+                  liabilities:credit card  $-500  ; liabilities, equity, revenues balances are usually negative.
+                  equity:start                    ; One amount can be left blank. $-10500 is inferred here.
+                                                  ; Some of these accounts we didn't declare above,
+                                                  ; so -s/--strict would complain.
+
+              2024-01-03 ! (12345) pay rent
+                  ; Additional transaction comment lines, indented.
+                  ; There can be a ! or * after the date meaning "pending" or "cleared".
+                  ; There can be a parenthesised (code) after the date/status.
+                                                  ; Amounts' sign shows direction of flow.
+                  assets:checking          $-500  ; Minus means removed from this account (credit).
+                  expenses:rent             $500  ; Plus means added to this account (debit).
+
+              ; Keeping transactions in date order is optional (but helps error checking).
+
+              2024-01-02 Gringott's Bank | withdrawal  ; Description can be PAYEE | NOTE
+                  assets:bank:gold       -10 gold
+                  assets:pouch            10 gold
+
+              2024-01-02 shopping
+                  expenses:clothing        1 gold
+                  expenses:wands           5 gold
+                  assets:pouch            -6 gold
+
+              2024-01-02 receive gift
+                  revenues:gifts          -3 "Chocolate Frogs"  ; Complex commodity symbols
+                  assets:pouch             3 "Chocolate Frogs"  ; must be in double quotes.
+
+              2024-01-15 buy some shares, in two lots                 ; Cost can be noted.
+                  assets:investments:2024-01-15     2.0 AAAA @ $1.50  ; @  means per-unit cost
+                  assets:investments:2024-01-15-02  3.0 AAAA @@ $4    ; @@ means total cost
+                                    ; ^ Per-lot subaccounts are sometimes useful.
+                  assets:checking                 $-7
+
+              2024-01-15 assert some account balances on this date
+                  ; Balances can be asserted in any transaction, with =, for extra error checking.
+                  ; Assertion txns like this one can be made with hledger close --assert --show-costs
+                  ;
+                  assets:savings                    $0                   = $10000
+                  assets:checking                   $0                   =   $493
+                  assets:bank:gold                   0 gold              =    -10 gold
+                  assets:pouch                       0 gold              =      4 gold
+                  assets:pouch                       0 "Chocolate Frogs" =      3 "Chocolate Frogs"
+                  assets:investments:2024-01-15      0.0 AAAA            =      2.0 AAAA @  $1.50
+                  assets:investments:2024-01-15-02   0.0 AAAA            =      3.0 AAAA @@ $4
+                  liabilities:credit card           $0                   =  $-500
+
+              2024-02-01 note some event, or a transaction not yet fully entered, on this date
+                  ; Postings are not required.
+
+              ; Some other date formats are allowed (but, consistent YYYY-MM-DD is useful).
+              2024.01.01
+              2024/1/1
+
+   Comments
+       Lines in the journal will be ignored if they begin with a hash (#) or a
+       semicolon  (;).  (See also Other syntax.)  hledger will also ignore re-
+       gions beginning with a comment line and ending with an end comment line
+       (or file end).  Here's a suggestion for choosing between them:
+
+       o # for top-level notes
+
+       o ; for commenting out things temporarily
+
+       o comment for quickly commenting large regions (remember it's there, or
+         you might get confused)
+
+       Eg:
+
+              # a comment line
+              ; another commentline
+              comment
+              A multi-line comment block,
+              continuing until "end comment" directive
+              or the end of the current file.
+              end comment
+
+       Some hledger entries can have same-line comments attached to them, from
+       ; (semicolon) to end of line.  See Transaction comments,  Posting  com-
+       ments, and Account comments below.
+
+   Transactions
+       Transactions  are the main unit of information in a journal file.  They
+       represent events, typically a movement of some quantity of  commodities
+       between two or more named accounts.
+
+       Each  transaction is recorded as a journal entry, beginning with a sim-
+       ple date in column 0.  This can be followed by any of the following op-
+       tional fields, separated by spaces:
+
+       o a status character (empty, !, or *)
+
+       o a code (any short number or text, enclosed in parentheses)
+
+       o a description (any remaining text until end of line or a semicolon)
+
+       o a comment (any remaining text following  a  semicolon  until  end  of
+         line, and any following indented lines beginning with a semicolon)
+
+       o 0 or more indented posting lines, describing what was transferred and
+         the  accounts  involved (indented comment lines are also allowed, but
+         not blank lines or non-indented lines).
+
+       Here's a simple journal file containing one transaction:
+
+              2008/01/01 income
+                assets:bank:checking   $1
+                income:salary         $-1
+
+   Dates
+   Simple dates
+       Dates in the journal  file  use  simple  dates  format:  YYYY-MM-DD  or
+       YYYY/MM/DD or YYYY.MM.DD, with leading zeros optional.  The year may be
+       omitted,  in  which case it will be inferred from the context: the cur-
+       rent transaction, the default year set with a Y directive, or the  cur-
+       rent  date  when  the  command  is  run.   Some  examples:  2010-01-31,
+       2010/01/31, 2010.1.31, 1/31.
+
+       (The UI also accepts simple dates, as well as the more  flexible  smart
+       dates documented in the hledger manual.)
+
+   Posting dates
+       You  can  give  individual  postings a different date from their parent
+       transaction, by adding a posting comment containing a tag  (see  below)
+       like date:DATE.  This is probably the best way to control posting dates
+       precisely.   Eg  in  this  example the expense should appear in May re-
+       ports, and the deduction from checking should be reported  on  6/1  for
+       easy bank reconciliation:
+
+              2015/5/30
+                  expenses:food     $10  ; food purchased on saturday 5/30
+                  assets:checking        ; bank cleared it on monday, date:6/1
+
+              $ hledger -f t.j register food
+              2015-05-30                      expenses:food                  $10           $10
+
+              $ hledger -f t.j register checking
+              2015-06-01                      assets:checking               $-10          $-10
+
+       DATE  should be a simple date; if the year is not specified it will use
+       the year of the transaction's date.
+       The date: tag must have a valid simple date value if it is present,  eg
+       a date: tag with no value is not allowed.
+
+   Status
+       Transactions  (or  individual postings within a transaction) can have a
+       status mark, which is a single character  before  the  transaction  de-
+       scription  (or posting account name), separated from it by a space, in-
+       dicating one of three statuses:
+
+       mark     status
+       ------------------
+                unmarked
+       !        pending
+       *        cleared
+
+       When reporting, you  can  filter  by  status  with  the  -U/--unmarked,
+       -P/--pending, and -C/--cleared flags (and you can combine these, eg -UP
+       to  match all except cleared things).  Or you can use the status:, sta-
+       tus:!, and status:* queries, or the U, P, C keys in hledger-ui.
+
+       (Note: in Ledger the "unmarked" state is called "uncleared"; in hledger
+       we renamed it to "unmarked" for semantic clarity.)
+
+       Status marks are optional, but can be helpful eg for  reconciling  with
+       real-world accounts.  Some editor modes provide highlighting and short-
+       cuts  for working with status.  Eg in Emacs ledger-mode, you can toggle
+       transaction status with C-c C-e, or posting status with C-c C-c.
+
+       What "uncleared", "pending", and "cleared" actually mean is up to  you.
+       Here's one suggestion:
+
+       status       meaning
+       --------------------------------------------------------------------------
+       uncleared    recorded but not yet reconciled; needs review
+       pending      tentatively reconciled (if needed, eg during a big reconcil-
+                    iation)
+       cleared      complete, reconciled as far as possible, and considered cor-
+                    rect
+
+       With  this scheme, you would use -PC to see the current balance at your
+       bank, -U to see things which will probably hit your bank soon (like un-
+       cashed checks), and no flags to see the most up-to-date state  of  your
+       finances.
+
+   Code
+       After  the  status mark, but before the description, you can optionally
+       write a transaction "code", enclosed in parentheses.  This  is  a  good
+       place  to record a check number, or some other important transaction id
+       or reference number.
+
+   Description
+       After the date, status mark and/or code fields, the rest  of  the  line
+       (or  until a comment is begun with ;) is the transaction's description.
+       Here you can describe the transaction (called the "narration" in tradi-
+       tional bookkeeping), or you can record a payee/payer name, or  you  can
+       leave it empty.
+
+       Transaction  descriptions  show  up in print output and in register re-
+       ports, and can be listed with the descriptions command.
+
+       You can query by description with desc:DESCREGEX, or pivot on  descrip-
+       tion with --pivot desc.
+
+   Payee and note
+       Sometimes people want a dedicated payee/payer field that can be queried
+       and  checked more strictly.  If you want that, you can write a | (pipe)
+       character in the description.  This divides it into a "payee" field  on
+       the left, and a "note" field on the right.  (Either can be empty.)
+
+       You  can  query  these  with  payee:PAYEEREGEX and note:NOTEREGEX, list
+       their values with the payees and notes commands, or pivot on  payee  or
+       note.
+
+       Note: in transactions with no | character, description, payee, and note
+       all have the same value.  Once a | is added, they become distinct.  (If
+       you'd  like  to  change  this  behaviour, please propose it on the mail
+       list.)
+
+       If you want more strict error checking, you can declare the valid payee
+       names with payee directives, and then enforce these with hledger  check
+       payees.   (Note:  because  of the above, for this you'll need to ensure
+       every transaction description contains a | and  therefore  a  checkable
+       payee name, even if it's empty.)
+
+   Transaction comments
+       Text  following  ;, after a transaction description, and/or on indented
+       lines immediately below it, form comments for that  transaction.   They
+       are  reproduced by print but otherwise ignored, except they may contain
+       tags, which are not ignored.
+
+              2012-01-01 something  ; a transaction comment
+                  ; a second line of transaction comment
+                  expenses   1
+                  assets
+
+   Postings
+       A posting is an addition of some amount to, or removal of  some  amount
+       from,  an account.  Each posting line begins with at least one space or
+       tab (2 or 4 spaces is common), followed by:
+
+       o (optional) a status character (empty, !, or *), followed by a space
+
+       o (required) an account name (any text,  optionally  containing  single
+         spaces, until end of line or a double space)
+
+       o (optional) two or more spaces (or tabs) followed by an amount.
+
+       If  the  amount is positive, it is being added to the account; if nega-
+       tive, it is being removed from the account.
+
+       The posting amounts in a transaction must sum up  to  zero,  indicating
+       that  the  inflows  and  outflows  are  equal.  We call this a balanced
+       transaction.  (You can read more about the nitty-gritty details of "sum
+       up to zero" in Transaction balancing below.)
+
+       As a convenience, you can optionally leave one  amount  blank;  hledger
+       will infer what it should be so as to balance the transaction.
+
+   Debits and credits
+       The traditional accounting concepts of debit and credit of course exist
+       in  hledger,  but  we  represent  them  with numeric sign, as described
+       above.  Positive and negative  posting  amounts  represent  debits  and
+       credits respectively.
+
+       You  don't  need  to  remember  that, but if you would like to - eg for
+       helping newcomers or for talking with your accountant - here's a  handy
+       mnemonic:
+
+       debit  / plus  / left  / short  words
+       credit / minus / right / longer words
+
+   The two space delimiter
+       Be  sure  to  notice the unusual separator between the account name and
+       the following amount.  Because hledger allows account names with spaces
+       in them, you must separate the account name and amount (if any) by  two
+       or  more  spaces (or tabs).  It's easy to forget at first.  If you ever
+       see the amount being treated as part of the account name,  you'll  know
+       you probably need to add another space between them.
+
+   Account names
+       Accounts  are  the  main  way of categorising things in hledger.  As in
+       Double Entry Bookkeeping, they can represent real world accounts  (such
+       as a bank account), or more abstract categories such as "money borrowed
+       from Frank" or "money spent on electricity".
+
+       You  can  use any account names you like, but we usually start with the
+       traditional accounting categories, which in english are assets, liabil-
+       ities, equity, revenues, expenses.  (You might see these referred to as
+       A, L, E, R, X for short.)
+
+       For more precise reporting, we usually divide the  top  level  accounts
+       into more detailed subaccounts, by writing a full colon between account
+       name  parts.   For example, from the account names assets:bank:checking
+       and expenses:food, hledger will infer this hierarchy of five accounts:
+
+              assets
+              assets:bank
+              assets:bank:checking
+              expenses
+              expenses:food
+
+       Shown as an outline, the hierarchical tree structure is more clear:
+
+              assets
+               bank
+                checking
+              expenses
+               food
+
+       hledger reports can summarise the account tree to any depth, so you can
+       go as deep as you like with subcategories,  but  keeping  your  account
+       names relatively simple may be best when starting out.
+
+       Account names may be capitalised or not; they may contain letters, num-
+       bers,  symbols,  or  single  spaces.  Note, when an account name and an
+       amount are written on the same line, they must be separated by  two  or
+       more spaces (or tabs).
+
+       Parentheses  or  brackets enclosing the full account name indicate vir-
+       tual postings, described below.  Parentheses or  brackets  internal  to
+       the account name have no special meaning.
+
+       Account  names  can  be  altered  temporarily or permanently by account
+       aliases.
+
+   Amounts
+       After the account name, there is usually an amount.  (Remember: between
+       account name and amount, there must be two or more spaces.)
+
+       hledger's amount format is flexible, supporting  several  international
+       formats.   Here  are  some examples.  Amounts have a number (the "quan-
+       tity"):
+
+              1
+
+       ..and usually a currency symbol or commodity name (more on this below),
+       to the left or right of the quantity,  with  or  without  a  separating
+       space:
+
+              $1
+              4000 AAPL
+              3 "green apples"
+
+       Amounts can be preceded by a minus sign (or a plus sign, though plus is
+       the  default), The sign can be written before or after a left-side com-
+       modity symbol:
+
+              -$1
+              $-1
+
+       One or more spaces between the sign and the number are acceptable  when
+       parsing (but they won't be displayed in output):
+
+              + $1
+              $-      1
+
+       Scientific E notation is allowed:
+
+              1E-6
+              EUR 1E3
+
+   Decimal marks
+       A decimal mark can be written as a period or a comma:
+
+              1.23
+              1,23
+
+       Both of these are common in international number formats, so hledger is
+       not  biased  towards  one  or the other.  Because hledger also supports
+       digit group marks (eg thousands separators), this means that  a  number
+       like  1,000  or 1.000 containing just one period or comma is ambiguous.
+       In such cases, hledger by default assumes it is  a  decimal  mark,  and
+       will parse both of those as 1.
+
+       To  help  hledger  parse such ambiguous numbers more accurately, if you
+       use digit group marks, we recommend declaring the decimal mark  explic-
+       itly.   The  best  way is to add a decimal-mark directive at the top of
+       each data file, like this:
+
+              decimal-mark .
+
+       Or you can declare it per  commodity  with  commodity  directives,  de-
+       scribed below.
+
+       hledger  also accepts numbers like 10. with no digits after the decimal
+       mark (and will sometimes display numbers that way to disambiguate  them
+       - see Trailing decimal marks).
+
+   Digit group marks
+       In  the integer part of the amount quantity (left of the decimal mark),
+       groups of digits can optionally be separated by a digit group mark -  a
+       comma  or  period  (whichever  is not used as decimal mark), or a space
+       (several Unicode space variants, like  no-break  space,  are  also  ac-
+       cepted).   So these are all valid amounts in a journal file:
+
+                   $1,000,000.00
+                EUR 2.000.000,00
+              INR 9,99,99,999.00
+                    1 000 000.00   ; <- ordinary space
+                    1 000 000.00   ; <- no-break space
+
+   Commodity
+       Amounts  in  hledger  have both a "quantity", which is a signed decimal
+       number, and a "commodity", which is a currency symbol, stock ticker, or
+       any word or phrase describing something you are tracking.
+
+       If the commodity name contains non-letters (spaces, numbers, or punctu-
+       ation), you must always write it inside double quotes ("green  apples",
+       "ABC123").
+
+       If  you  write just a bare number, that too will have a commodity, with
+       name ""; we call that the "no-symbol commodity".
+
+       Actually, hledger combines these  single-commodity  amounts  into  more
+       powerful  multi-commodity amounts, which are what it works with most of
+       the time.  A multi-commodity amount could be, eg: 1 USD, 2  EUR,  3.456
+       TSLA.   In  practice,  you  will  only  see  multi-commodity amounts in
+       hledger's output; you can't write them directly in the journal file.
+
+       By default, the format of amounts in the journal influences how hledger
+       displays them in output.  This is explained in Commodity display  style
+       below.
+
+   Costs
+       After  a posting amount, you can note its cost (when buying) or selling
+       price (when selling) in another commodity, by writing  either  @  UNIT-
+       PRICE  or @@ TOTALPRICE after it.  This indicates a conversion transac-
+       tion, where one commodity is exchanged for another.
+
+       (You might also see this called "transaction price"  in  hledger  docs,
+       discussions,  or code; that term was directionally neutral and reminded
+       that it is a price specific to a transaction, but we now just  call  it
+       "cost", with the understanding that the transaction could be a purchase
+       or a sale.)
+
+       Costs  are usually written explicitly with @ or @@, but can also be in-
+       ferred automatically for simple multi-commodity transactions.  Note, if
+       costs are inferred, the order of postings  is  significant;  the  first
+       posting will have a cost attached, in the commodity of the second.
+
+       As  an  example, here are several ways to record purchases of a foreign
+       currency in hledger, using the cost notation either explicitly  or  im-
+       plicitly:
+
+       1. Write the price per unit, as @ UNITPRICE after the amount:
+
+                  2009/1/1
+                    assets:euros     100 @ $1.35  ; one hundred euros purchased at $1.35 each
+                    assets:dollars                 ; balancing amount is -$135.00
+
+       2. Write the total price, as @@ TOTALPRICE after the amount:
+
+                  2009/1/1
+                    assets:euros     100 @@ $135  ; one hundred euros purchased at $135 for the lot
+                    assets:dollars
+
+       3. Specify amounts for all postings, using exactly two commodities, and
+          let hledger infer the price that balances the transaction.  Note the
+          effect of posting order: the price is added to first posting, making
+          it 100 @@ $135, as in example 2:
+
+                  2009/1/1
+                    assets:euros     100          ; one hundred euros purchased
+                    assets:dollars  $-135          ; for $135
+
+       Amounts  can  be  converted  to cost at report time using the -B/--cost
+       flag; this is discussed more in the Cost reporting section.
+
+       Note that the cost normally should be a positive  amount,  though  it's
+       not  required to be.  This can be a little confusing, see discussion at
+       --infer-market-prices: market prices from transactions.
+
+   Balance assertions
+       hledger supports Ledger-style  balance  assertions  in  journal  files.
+       These  look  like, for example, = EXPECTEDBALANCE following a posting's
+       amount.  Eg here we assert the expected dollar balance  in  accounts  a
+       and b after each posting:
+
+              2013/1/1
+                a   $1 =  $1
+                b      = $-1
+
+              2013/1/2
+                a   $1 =  $2
+                b  $-1 = $-2
+
+       After reading a journal file, hledger will check all balance assertions
+       and  report  an error if any of them fail.  Balance assertions can pro-
+       tect you from, eg, inadvertently disrupting reconciled  balances  while
+       cleaning  up  old  entries.   You can disable them temporarily with the
+       -I/--ignore-assertions flag, which can be useful for troubleshooting or
+       for reading Ledger files.  (Note: this flag currently does not  disable
+       balance assignments, described below).
+
+   Assertions and ordering
+       hledger  calculates  and checks an account's balance assertions in date
+       order (and when there are multiple assertions on the same day, in parse
+       order).  Note this is different from Ledger,  which  checks  assertions
+       always in parse order, ignoring dates.
+
+       This means in hledger you can freely reorder transactions, postings, or
+       files, and balance assertions will usually keep working.  The exception
+       is  when you reorder multiple postings on the same day, to the same ac-
+       count, which have balance assertions; those will likely need updating.
+
+   Assertions and multiple included files
+       Multiple files included with the include directive are processed as  if
+       concatenated  into one file, preserving their order and the posting or-
+       der within each file.  It means that balance assertions in later  files
+       will see balance from earlier files.
+
+       And  if you have multiple postings to an account on the same day, split
+       across multiple files, and you want to assert the account's balance  on
+       that day, you'll need to put the assertion in the right file - the last
+       one in the sequence, probably.
+
+   Assertions and multiple -f files
+       Unlike  include,  when multiple files are specified on the command line
+       with multiple -f/--file options, balance assertions will not  see  bal-
+       ance from earlier files.  This can be useful when you do not want prob-
+       lems in earlier files to disrupt valid assertions in later files.
+
+       If  you  do  want assertions to see balance from earlier files, use in-
+       clude, or concatenate the files temporarily.
+
+   Assertions and costs
+       Balance assertions ignore costs, and should normally be written without
+       one:
+
+              2019/1/1
+                (a)     $1 @ 1 = $1
+
+       We do allow costs to be written in balance assertion amounts,  however,
+       and  print  shows  them,  but  they  don't affect whether the assertion
+       passes or fails.  This is for backward compatibility  (hledger's  close
+       command  used  to  generate balance assertions with costs), and because
+       balance assignments do use costs (see below).
+
+   Assertions and commodities
+       The balance assertions described so far are "single  commodity  balance
+       assertions": they assert and check the balance in one commodity, ignor-
+       ing  any  others  that  may be present.  This is how balance assertions
+       work in Ledger also.
+
+       If an account contains multiple commodities, you can assert their  bal-
+       ances  by  writing  multiple  postings with balance assertions, one for
+       each commodity:
+
+              2013/1/1
+                usd   $-1
+                eur   -1
+                both
+
+              2013/1/2
+                both    0 = $1
+                both    0 = 1
+
+       In hledger you can make a stronger "sole commodity  balance  assertion"
+       by  writing  two  equals signs (== EXPECTEDBALANCE).  This also asserts
+       that there are no other commodities in the account besides the asserted
+       one (or at least, that their current balance is zero):
+
+              2013/1/1
+                usd   $-1  == $-1  ; these sole commodity assertions succeed
+                eur   -1  == -1
+                both      ;==  $1  ; this one would fail because 'both' contains $ and
+
+       It's less easy to make a "sole commodities balance assertion" (note the
+       plural) - ie, asserting that an account contains two or more  specified
+       commodities and no others.  It can be done by
+
+       1. isolating each commodity in a subaccount, and asserting those
+
+       2. and  also  asserting  there are no commodities in the parent account
+          itself:
+
+          2013/1/1
+            usd       $-1
+            eur       -1
+            both        0 == 0   ; nothing up my sleeve
+            both:usd   $1 == $1  ; a dollar here
+            both:eur   1 == 1  ; a euro there
+
+   Assertions and subaccounts
+       All of the balance assertions above (both = and ==) are "subaccount-ex-
+       clusive balance assertions"; they ignore any  balances  that  exist  in
+       deeper subaccounts.
+
+       In  hledger  you  can make "subaccount-inclusive balance assertions" by
+       adding a star after the equals (=* or ==*):
+
+              2019/1/1
+                equity:start
+                assets:checking  $10
+                assets:savings   $10
+                assets            $0 ==* $20  ; assets + subaccounts contains $20 and nothing else
+
+   Assertions and status
+       Balance assertions always consider postings of all statuses  (unmarked,
+       pending,  or  cleared);  they  are  not affected by the -U/--unmarked /
+       -P/--pending / -C/--cleared flags or the status: query.
+
+   Assertions and virtual postings
+       Balance assertions always consider both real and virtual postings; they
+       are not affected by the --real/-R flag or real: query.
+
+   Assertions and auto postings
+       Balance assertions are affected by the  --auto  flag,  which  generates
+       auto postings, which can alter account balances.  Because auto postings
+       are optional in hledger, accounts affected by them effectively have two
+       balances.   But  balance  assertions  can only test one or the other of
+       these.  So to avoid making fragile assertions, either:
+
+       o assert the balance calculated with --auto, and always use --auto with
+         that file
+
+       o or assert the balance calculated without --auto, and never use --auto
+         with that file
+
+       o or avoid balance assertions on accounts affected by auto postings (or
+         avoid auto postings entirely).
+
+   Assertions and precision
+       Balance assertions compare the exactly calculated  amounts,  which  are
+       not  always  what  is  shown  by reports.  Eg a commodity directive may
+       limit the display precision, but this will not  affect  balance  asser-
+       tions.  Balance assertion failure messages show exact amounts.
+
+   Posting comments
+       Text  following  ;,  at  the  end of a posting line, and/or on indented
+       lines immediately below it, form comments for that posting.   They  are
+       reproduced  by  print  but  otherwise  ignored, except they may contain
+       tags, which are not ignored.
+
+              2012-01-01
+                  expenses   1  ; a comment for posting 1
+                  assets
+                  ; a comment for posting 2
+                  ; a second comment line for posting 2
+
+   Transaction balancing
+       How exactly does hledger decide when a transaction is balanced  ?   The
+       general goal is that if you look at the journal entry and calculate the
+       amounts' sum perfectly with pencil and paper, hledger should agree with
+       you.
+
+       Real  world  transactions,  especially for investments or cryptocurren-
+       cies, often involve imprecise costs,  complex  decimals,  and/or  infi-
+       nitely-recurring  decimals, which are difficult or inconvenient to han-
+       dle on a computer.  So to be a practical accounting system, hledger al-
+       lows some imprecision  when  checking  transaction  balancedness.   The
+       question is, how much imprecision should be allowed ?
+
+       hledger  currently decides it based on the commodity display styles: if
+       the postings' sum would appear to be zero when displayed with the stan-
+       dard display precisions, the transaction is considered balanced.
+
+       Or equivalently: if the journal entry is displayed with amounts rounded
+       to the standard display precisions (with hledger  print  --round=hard),
+       and  a  human  with  pencil  and paper would agree that those displayed
+       amounts add up to zero, the transaction is considered balanced.
+
+       This  has  some  advantages:  it  is  fairly  intuitive,  general   not
+       hard-coded,  yet  configurable  when  needed.  On the downside it means
+       that transaction balancedness is related to  commodity  display  preci-
+       sions,  so  eg  when  using -c/--commodity-style to display things with
+       more than usual precision, you might need to fix some of  your  journal
+       entries (ie, add decimal digits to make them balance more precisely).
+
+       Other PTA tools (Ledger, Beancount..)  have their own ways of doing it.
+       Possible improvements are discussed at #1964.
+
+       Note:  if you have multiple journal files, and are relying on commodity
+       directives to make imprecise journal entries balance,  the  directives'
+       placement might be important - see commodity directive.
+
+   Tags
+       Tags  are  a  way  to  add extra labels or data fields to transactions,
+       postings, or accounts.  They are usually a word or hyphenated word, im-
+       mediately followed by a full colon, written within  the  comment  of  a
+       transaction, a posting, or an account directive.  (Yes, storing data in
+       comments is slightly weird!)
+
+       You can write each tag on its own comment line, or multiple tags on one
+       line,  separated  by  commas.  Tags can also have a value, which is any
+       text after the colon until the next comma or  end  of  line,  excluding
+       surrounding whitespace.  (hledger tag values can't contain commas.)  If
+       the  same tag name appears multiple times in a comment, each name:value
+       pair is preserved.
+
+       An example: in this journal there are six tags,  one  of  them  with  a
+       value:
+
+              account assets:checking         ; accounttag:
+              account expenses:food
+
+              2017/1/16 bought groceries      ; transactiontag:
+                  ; transactiontag2:
+                  assets:checking        $-1
+                   ; posting-tag-1:, (belongs to the posting above)
+                  expenses:food           $1  ; posting-tag-2:, posting-tag-3: with a value
+
+   Querying with tags
+       Tags  are  most  often  used  to select a subset of data; you can match
+       tagged things by tag name and or tag value with  a  tag:  query.   (See
+       queries below.)
+
+       When  querying for tag names or values, note that postings inherit tags
+       from their transaction and from their account, and transactions acquire
+       tags from their postings.  So in the example above, - the assets:check-
+       ing posting effectively has four tags (one of its own, one from the ac-
+       count, two from the transaction) -  the  expenses:food  posting  effec-
+       tively  has  four tags (two of its own, two from the transaction) - the
+       transaction effectively has all six tags (two of its own, and two  from
+       each posting)
+
+   Displaying tags
+       You can use the tags command to list tag names or values.
+
+       The print command also shows tags.
+
+       You  can use --pivot to display tag values in other reports, in various
+       ways (eg appended to account names, like pseudo subaccounts).
+
+   When to use tags ?
+       Tags provide more dimensions of categorisation, complementing  accounts
+       and  transaction descriptions.  When to use each of these is somewhat a
+       matter of taste.  Accounts have the most built-in  support,  and  regex
+       queries  on  descriptions are also quite powerful.  So you may not need
+       tags at all.  But if you want to  track  multiple  cross-cutting  cate-
+       gories,  they  can  be a good fit.  For example, you could tag trip-re-
+       lated transactions with trip: YEAR:PLACE, without disturbing your usual
+       account categories.
+
+   Tag names
+       What is allowed in a tag name ?  Currently, most non-whitespace charac-
+       ters.  Eg : is a valid tag.
+
+       For extra error checking, you can declare valid tag names with the  tag
+       directive, and then enforce these with the check command.
+
+       But  note  that  tags  are detected quite loosely at present, sometimes
+       where you didn't intend them.  Eg  ;  see  https://foo.com  contains  a
+       https tag with value //foo.com.
+
+   Special tags
+       Some  tag  names  have  special  significance to hledger.  They are ex-
+       plained elsewhere, but here's a quick reference:
+
+               type                   -- declares an account's type
+               date                   -- overrides a posting's date
+               date2                  -- overrides a posting's secondary date
+               assert                 -- appears on txns generated by close --assert
+               retain                 -- appears on txns generated by close --retain
+               start                  -- appears on txns generated by close --migrate/--close/--open/--assign
+               t                      -- appears on postings generated from timedot letters
+
+               generated-transaction  -- appears on txns generated by a periodic rule
+               modified-transaction   -- appears on txns which have had auto postings added
+               generated-posting      -- appears on generated postings
+               cost-posting           -- appears on postings which have (or could have) a cost,
+                                         and which have equivalent conversion postings in the transaction
+               conversion-posting     -- appears on postings which are to a V/Conversion account
+                                         and which have an equivalent cost posting in the transaction
+
+       The second group above (generated-transaction, etc.)  are normally hid-
+       den, with a _ prefix added.  This means print doesn't show them by  de-
+       fault;  but  you can still use them in queries.  You can add the --ver-
+       bose-tags flag to make them visible, which  can  be  useful  for  trou-
+       bleshooting.
+
+   Directives
+       Besides  transactions, there is something else you can put in a journal
+       file: directives.  These are declarations, beginning  with  a  keyword,
+       that  modify  hledger's  behaviour.  Some directives can have more spe-
+       cific subdirectives, indented below  them.   hledger's  directives  are
+       similar to Ledger's in many cases, but there are also many differences.
+       Directives  are not required, but can be useful.  Here are the main di-
+       rectives:
+
+       purpose                                    directive
+       --------------------------------------------------------------------------
+       READING DATA:
+       Rewrite account names                      alias
+       Comment out sections of the file           comment
+       Declare file's  decimal  mark,  to  help   decimal-mark
+       parse amounts accurately
+       Include other data files                   include
+       GENERATING DATA:
+       Generate  recurring transactions or bud-   ~
+       get goals
+       Generate  extra  postings  on   existing   =
+       transactions
+       CHECKING FOR ERRORS:
+       Define  valid  entities  to provide more   account, commodity, payee, tag
+       error checking
+       REPORTING:
+       Declare accounts' type and display order   account
+       Declare commodity display styles           commodity
+       Declare market prices                      P
+
+   Directives and multiple files
+       Directives vary in their scope, ie which journal entries and which  in-
+       put files they affect.  Most often, a directive will affect the follow-
+       ing  entries  and  included  files if any, until the end of the current
+       file - and no further.  You might find this inconvenient!  For example,
+       alias directives do not affect parent or sibling files.  But there  are
+       usually workarounds; for example, put alias directives in your top-most
+       file, before including other files.
+
+       The  restriction,  though  it  may  be  annoying at first, is in a good
+       cause; it allows reports to be stable and deterministic, independent of
+       the order of input.  Without it, reports could show  different  numbers
+       depending  on  the order of -f options, or the positions of include di-
+       rectives in your files.
+
+   Directive effects
+       Here are all hledger's directives, with their effects  and  scope  sum-
+       marised  -  nine  main  directives,  plus four others which we consider
+       non-essential:
+
+       di-        what it does                                                       ends
+       rec-                                                                          at
+       tive                                                                          file
+                                                                                     end?
+       --------------------------------------------------------------------------------------
+       ac-        Declares an account, for checking all entries in all files;  and   N
+       count      its display order and type.  Subdirectives: any text, ignored.
+       alias      Rewrites  account  names, in following entries until end of cur-   Y
+                  rent file or end aliases.  Command line equivalent: --alias
+       com-       Ignores part of the journal file, until end of current  file  or   Y
+       ment       end comment.
+       com-       Declares up to four things: 1.  a commodity symbol, for checking   N,N,Y,Y
+       mod-       all  amounts  in all files 2.  the display style for all amounts
+       ity        of this commodity 3.  the decimal mark for  parsing  amounts  of
+                  this  commodity,  in  the rest of this file and its children, if
+                  there is no decimal-mark directive 4.  the precision to use  for
+                  balanced-transaction  checking  in  this commodity, in this file
+                  and its children.   Takes  precedence  over  D.   Subdirectives:
+                  format (ignored).  Command line equivalent: -c/--commodity-style
+       deci-      Declares  the  decimal mark, for parsing amounts of all commodi-   Y
+       mal-mark   ties in following entries until next decimal-mark or end of cur-
+                  rent file.  Included files can override.  Takes precedence  over
+                  commodity and D.
+       include    Includes  entries  and  directives from another file, as if they   N
+                  were  written  inline.   Command  line   alternative:   multiple
+                  -f/--file
+       payee      Declares a payee name, for checking all entries in all files.      N
+       P          Declares the market price of a commodity on some date, for value   N
+                  reports.
+       ~          Declares  a  periodic  transaction  rule  that  generates future   N
+       (tilde)    transactions with  --forecast  and  budget  goals  with  balance
+                  --budget.
+       Other
+       syntax:
+       apply      Prepends  a  common parent account to all account names, in fol-   Y
+       account    lowing entries until end of current file or end apply account.
+       D          Sets a default commodity to use for  no-symbol  amounts;and,  if   Y,Y,N,N
+                  there  is no commodity directive for this commodity: its decimal
+                  mark, balancing precision, and display style, as above.
+       Y          Sets a default year to use for any yearless dates, in  following   Y
+                  entries until end of current file.
+       =          Declares  an  auto posting rule that generates extra postings on   partly
+       (equals)   matched transactions with --auto, in current, parent, and  child
+                  files (but not sibling files, see #1212).
+       Other      Other  directives from Ledger's file format are accepted but ig-
+       Ledger     nored.
+       direc-
+       tives
+
+   account directive
+       account directives can be used to declare accounts (ie, the places that
+       amounts are transferred from and to).  Though not required, these  dec-
+       larations can provide several benefits:
+
+       o They can document your intended chart of accounts, providing a refer-
+         ence.
+
+       o They can store additional account information as comments, or as tags
+         which can be used to filter or pivot reports.
+
+       o They can restrict which accounts may be posted to by transactions, eg
+         in strict mode, which helps prevent errors.
+
+       o They  influence account display order in reports, allowing non-alpha-
+         betic sorting (eg Revenues to appear above Expenses).
+
+       o They can help hledger know your accounts'  types  (asset,  liability,
+         equity, revenue, expense), enabling reports like balancesheet and in-
+         comestatement.
+
+       o They  help with account name completion (in hledger add, hledger-web,
+         hledger-iadd, ledger-mode, etc.)
+
+       They are written as the word account followed by  a  hledger-style  ac-
+       count name.  Eg:
+
+              account assets:bank:checking
+
+       Ledger-style indented subdirectives are also accepted, but ignored:
+
+              account assets:bank:checking
+                format subdirective  ; currently ignored
+
+   Account comments
+       Text following two or more spaces and ; at the end of an account direc-
+       tive  line,  and/or following ; on indented lines immediately below it,
+       form comments for that account.  They are ignored except they may  con-
+       tain tags, which are not ignored.
+
+       The  two-space  requirement for same-line account comments is because ;
+       is allowed in account names.
+
+              account assets:bank:checking    ; same-line comment, at least 2 spaces before the semicolon
+                ; next-line comment
+                ; some tags - type:A, acctnum:12345
+
+   Account error checking
+       By default, accounts need not be declared;  they  come  into  existence
+       when  a  posting  references  them.   This  is convenient, but it means
+       hledger can't warn you when you mis-spell an account name in the  jour-
+       nal.  Usually you'll find that error later, as an extra account in bal-
+       ance reports, or an incorrect balance when reconciling.
+
+       In  strict  mode,  enabled  with  the -s/--strict flag, or when you run
+       hledger check accounts, hledger will report an error if any transaction
+       uses an account name that has not been declared by  an  account  direc-
+       tive.  Some notes:
+
+       o The  declaration is case-sensitive; transactions must use the correct
+         account name capitalisation.
+
+       o The account directive's scope is "whole file and below"  (see  direc-
+         tives).  This means it affects all of the current file, and any files
+         it  includes,  but  not parent or sibling files.  The position of ac-
+         count directives within the file does not matter, though  it's  usual
+         to put them at the top.
+
+       o Accounts  can  only be declared in journal files, but will affect in-
+         cluded files of all types.
+
+       o It's currently not possible to  declare  "all  possible  subaccounts"
+         with a wildcard; every account posted to must be declared.
+
+       o If  you  use the --infer-equity flag, you will also need declarations
+         for the account names it generates.
+
+   Account display order
+       Account directives also cause hledger to display accounts in a particu-
+       lar order, not just alphabetically.  Eg, here is a conventional  order-
+       ing for the top-level accounts:
+
+              account assets
+              account liabilities
+              account equity
+              account revenues
+              account expenses
+
+       Now hledger displays them in that order:
+
+              $ hledger accounts
+              assets
+              liabilities
+              equity
+              revenues
+              expenses
+
+       If  there are undeclared accounts, those will be displayed last, in al-
+       phabetical order.
+
+       Sorting is done within each group of sibling accounts, at each level of
+       the account tree.  Eg, a declaration like account  parent:child  influ-
+       ences child's position among its siblings.
+
+       Note,  it  does not affect parent's position; for that, you need an ac-
+       count parent declaration.
+
+       Sibling accounts are always displayed together; hledger  won't  display
+       x:y in between a:b and a:c.
+
+       An  account  directive both declares an account as a valid posting tar-
+       get, and declares its display order; you can't easily  do  one  without
+       the other.
+
+   Account types
+       hledger knows that accounts come in several types: assets, liabilities,
+       expenses  and  so  on.  This enables easy reports like balancesheet and
+       incomestatement, and filtering by account type with the type: query.
+
+       As a convenience, hledger will detect these account types automatically
+       if you are using common english-language top-level account  names  (de-
+       scribed  below).   But  it's more robust to declare accounts' types ex-
+       plicitly, by adding type: tags to their account directives.  The  tag's
+       value should be one of the five main account types:
+
+       o A or Asset (things you own)
+
+       o L or Liability (things you owe)
+
+       o E  or  Equity (investment/ownership; balanced counterpart of assets &
+         liabilities)
+
+       o R or Revenue (what you received money from, AKA  income;  technically
+         part of Equity)
+
+       o X or Expense (what you spend money on; technically part of Equity)
+
+       or, it can be (these are used less often):
+
+       o C or Cash (a subtype of Asset, indicating liquid assets for the cash-
+         flow report)
+
+       o V  or  Conversion (a subtype of Equity, for conversions (see Cost re-
+         porting).)
+
+       Subaccounts inherit their parent's type, or they can override it.  Here
+       is a typical set of account type declarations:
+
+              account assets             ; type: A
+              account liabilities        ; type: L
+              account equity             ; type: E
+              account revenues           ; type: R
+              account expenses           ; type: X
+
+              account assets:bank        ; type: C
+              account assets:cash        ; type: C
+
+              account equity:conversion  ; type: V
+
+       Here are some tips for working with account types.
+
+       o The rules for inferring types from  account  names  are  as  follows.
+         These are just a convenience that sometimes help new users get going;
+         if they don't work for you, just ignore them and declare your account
+         types.  See also Regular expressions.
+
+                If account's name contains this (CI) regular expression:            | its type is:
+                --------------------------------------------------------------------|-------------
+                ^assets?(:.+)?:(cash|bank|che(ck|que?)(ing)?|savings?|current)(:|$) | Cash
+                ^assets?(:|$)                                                       | Asset
+                ^(debts?|liabilit(y|ies))(:|$)                                      | Liability
+                ^equity:(trad(e|ing)|conversion)s?(:|$)                             | Conversion
+                ^equity(:|$)                                                        | Equity
+                ^(income|revenue)s?(:|$)                                            | Revenue
+                ^expenses?(:|$)                                                     | Expense
+
+       o If  you declare any account types, it's a good idea to declare an ac-
+         count for all of the account types, because a mixture of declared and
+         name-inferred types can disrupt certain reports.
+
+       o Certain uses of account  aliases  can  disrupt  account  types.   See
+         Rewriting accounts > Aliases and account types.
+
+       o As mentioned above, subaccounts will inherit a type from their parent
+         account.   More  precisely, an account's type is decided by the first
+         of these that exists:
+
+         1. A type: declaration for this account.
+
+         2. A type: declaration in the parent accounts  above  it,  preferring
+            the nearest.
+
+         3. An account type inferred from this account's name.
+
+         4. An  account type inferred from a parent account's name, preferring
+            the nearest parent.
+
+         5. Otherwise, it will have no type.
+
+       o For troubleshooting, you can list accounts and their types with:
+
+                $ hledger accounts --types [ACCTPAT] [-DEPTH] [type:TYPECODES]
+
+   alias directive
+       You can define account alias rules which rewrite your account names, or
+       parts of them, before generating reports.  This can be useful for:
+
+       o expanding shorthand account names to their full form, allowing easier
+         data entry and a less verbose journal
+
+       o adapting old journals to your current chart of accounts
+
+       o experimenting with new account organisations, like a new hierarchy
+
+       o combining two accounts into one, eg to see their sum or difference on
+         one line
+
+       o customising reports
+
+       Account aliases also rewrite account names in account directives.  They
+       do  not  affect  account  names  being  entered  via  hledger  add   or
+       hledger-web.
+
+       Account aliases are very powerful.  They are generally easy to use cor-
+       rectly, but you can also generate invalid account names with them; more
+       on this below.
+
+       See also Rewrite account names.
+
+   Basic aliases
+       To  set an account alias, use the alias directive in your journal file.
+       This affects all subsequent journal entries in the current file or  its
+       included  files  (but  note:  not sibling or parent files).  The spaces
+       around the = are optional:
+
+              alias OLD = NEW
+
+       Or, you can use the --alias 'OLD=NEW' option on the command line.  This
+       affects all entries.  It's useful for trying out aliases interactively.
+
+       OLD and NEW are case sensitive full account names.   hledger  will  re-
+       place  any occurrence of the old account name with the new one.  Subac-
+       counts are also affected.  Eg:
+
+              alias checking = assets:bank:wells fargo:checking
+              ; rewrites "checking" to "assets:bank:wells fargo:checking", or "checking:a" to "assets:bank:wells fargo:checking:a"
+
+   Regex aliases
+       There is also a more powerful variant that uses a  regular  expression,
+       indicated  by  wrapping  the  pattern in forward slashes.  (This is the
+       only place where hledger requires forward slashes around a regular  ex-
+       pression.)
+
+       Eg:
+
+              alias /REGEX/ = REPLACEMENT
+
+       or:
+
+              $ hledger --alias '/REGEX/=REPLACEMENT' ...
+
+       Any  part  of  an account name matched by REGEX will be replaced by RE-
+       PLACEMENT.  REGEX is case-insensitive as usual.
+
+       If you need to match a forward slash, escape it with  a  backslash,  eg
+       /\/=:.
+
+       If  REGEX  contains parenthesised match groups, these can be referenced
+       by the usual backslash and number in REPLACEMENT:
+
+              alias /^(.+):bank:([^:]+):(.*)/ = \1:\2 \3
+              ; rewrites "assets:bank:wells fargo:checking" to  "assets:wells fargo checking"
+
+       REPLACEMENT continues to the end of line (or on command line, to end of
+       option argument), so it can contain trailing whitespace.
+
+   Combining aliases
+       You can define as many aliases as you like,  using  journal  directives
+       and/or command line options.
+
+       Recursive  aliases  -  where an account name is rewritten by one alias,
+       then by another alias, and so on - are allowed.  Each  alias  sees  the
+       effect of previously applied aliases.
+
+       In  such  cases it can be important to understand which aliases will be
+       applied and in which order.  For (each account name  in)  each  journal
+       entry, we apply:
+
+       1. alias  directives  preceding the journal entry, most recently parsed
+          first (ie, reading upward from the journal entry, bottom to top)
+
+       2. --alias options, in the order they  appeared  on  the  command  line
+          (left to right).
+
+       In other words, for (an account name in) a given journal entry:
+
+       o the nearest alias declaration before/above the entry is applied first
+
+       o the next alias before/above that will be be applied next, and so on
+
+       o aliases defined after/below the entry do not affect it.
+
+       This  gives nearby aliases precedence over distant ones, and helps pro-
+       vide semantic stability - aliases will keep working the same way  inde-
+       pendent of which files are being read and in which order.
+
+       In  case  of  trouble,  adding  --debug=6 to the command line will show
+       which aliases are being applied when.
+
+   Aliases and multiple files
+       As explained at Directives and multiple files, alias directives do  not
+       affect parent or sibling files.  Eg in this command,
+
+              hledger -f a.aliases -f b.journal
+
+       account  aliases  defined  in a.aliases will not affect b.journal.  In-
+       cluding the aliases doesn't work either:
+
+              include a.aliases
+
+              2023-01-01  ; not affected by a.aliases
+                foo  1
+                bar
+
+       This means that account aliases should usually be declared at the start
+       of your top-most file, like this:
+
+              alias foo=Foo
+              alias bar=Bar
+
+              2023-01-01  ; affected by aliases above
+                foo  1
+                bar
+
+              include c.journal  ; also affected
+
+   end aliases directive
+       You can clear (forget) all currently defined aliases (seen in the jour-
+       nal so far, or defined on the command line) with this directive:
+
+              end aliases
+
+   Aliases can generate bad account names
+       Be aware that account aliases  can  produce  malformed  account  names,
+       which could cause confusing reports or invalid print output.  For exam-
+       ple, you could erase all account names:
+
+              2021-01-01
+                a:aa     1
+                b
+
+              $ hledger print --alias '/.*/='
+              2021-01-01
+                                 1
+
+       The  above print output is not a valid journal.  Or you could insert an
+       illegal double space, causing print output that would give a  different
+       journal when reparsed:
+
+              2021-01-01
+                old    1
+                other
+
+              $ hledger print --alias old="new  USD" | hledger -f- print
+              2021-01-01
+                  new             USD 1
+                  other
+
+   Aliases and account types
+       If an account with a type declaration (see Declaring accounts > Account
+       types) is renamed by an alias, normally the account type remains in ef-
+       fect.
+
+       However,  renaming in a way that reshapes the account tree (eg renaming
+       parent accounts but not their children, or vice  versa)  could  prevent
+       child accounts from inheriting the account type of their parents.
+
+       Secondly,  if an account's type is being inferred from its name, renam-
+       ing it by an alias could prevent or alter that.
+
+       If you are using account aliases and the type: query  is  not  matching
+       accounts  as you expect, try troubleshooting with the accounts command,
+       eg something like:
+
+              $ hledger accounts --types -1 --alias assets=bassetts
+
+   commodity directive
+       The commodity directive performs several functions:
+
+       1. It declares which commodity symbols may be used in the journal,  en-
+          abling  useful error checking with strict mode or the check command.
+          See Commodity error checking below.
+
+       2. It declares how all amounts in this commodity should  be  displayed,
+          eg how many decimals to show.  See Commodity display style above.
+
+       3. (If  no  decimal-mark  directive  is in effect:) It sets the decimal
+          mark to expect (period or comma) when parsing amounts in  this  com-
+          modity, in this file and files it includes, from the directive until
+          end of current file.  See Decimal marks above.
+
+       4. It declares the precision with which this commodity's amounts should
+          be  compared  when  checking  for balanced transactions, anywhere in
+          this file and files it includes, until end of current file.
+
+       Declaring commodities solves several common  parsing/display  problems,
+       so we recommend it.
+
+       Note that effects 3 and 4 above end at the end of the directive's file,
+       and  will not affect sibling or parent files.  So if you are relying on
+       them (especially 4) and using multiple files,  placing  your  commodity
+       directives  in  a  top-level  parent file might be important.  Or, keep
+       your decimal marks unambiguous and your entries well balanced and  pre-
+       cise.
+
+       (Related: #793)
+
+   Commodity directive syntax
+       A commodity directive is normally the word commodity followed by a sam-
+       ple  amount  (and  optionally a comment).  Only the amount's symbol and
+       the number's format is significant.  Eg:
+
+              commodity $1000.00
+              commodity 1.000,00 EUR
+              commodity 1 000 000.0000   ; the no-symbol commodity
+
+       Commodities do not have tags (tags in the comment will be ignored).
+
+       A commodity directive's sample amount must always include a  period  or
+       comma  decimal  mark  (this  rule  helps disambiguate decimal marks and
+       digit group marks).  If you don't want  to  show  any  decimal  digits,
+       write the decimal mark at the end:
+
+              commodity 1000. AAAA       ; show AAAA with no decimals
+
+       Commodity  symbols  containing  spaces, numbers, or punctuation must be
+       enclosed in double quotes, as usual:
+
+              commodity 1.0000 "AAAA 2023"
+
+       Commodity directives normally include a sample amount, but can  declare
+       only a symbol (ie, just function 1 above):
+
+              commodity $
+              commodity INR
+              commodity "AAAA 2023"
+              commodity ""               ; the no-symbol commodity
+
+       Commodity directives may also be written with an indented format subdi-
+       rective,  as in Ledger.  The symbol is repeated and must be the same in
+       both places.  Other subdirectives are currently ignored:
+
+              ; display indian rupees with currency name on the left,
+              ; thousands, lakhs and crores comma-separated,
+              ; period as decimal point, and two decimal places.
+              commodity INR
+                format INR 1,00,00,000.00
+                an unsupported subdirective  ; ignored by hledger
+
+   Commodity error checking
+       In strict mode (-s/--strict) (or when you run  hledger  check  commodi-
+       ties),  hledger  will report an error if an undeclared commodity symbol
+       is used.  (With one exception: zero amounts are always allowed to  have
+       no  commodity symbol.)  It works like account error checking (described
+       above).
+
+   decimal-mark directive
+       You can use a decimal-mark directive - usually one per file, at the top
+       of the file - to declare which character represents a decimal mark when
+       parsing amounts in this file.  It can look like
+
+              decimal-mark .
+
+       or
+
+              decimal-mark ,
+
+       This prevents any ambiguity when parsing numbers in  the  file,  so  we
+       recommend  it,  especially  if  the file contains digit group marks (eg
+       thousands separators).
+
+   include directive
+       You can pull in the content of additional files by writing  an  include
+       directive, like this:
+
+              include FILEPATH
+
+       Only  journal files can include, and only journal, timeclock or timedot
+       files can be included (not CSV files, currently).
+
+       If the file path does not begin with a slash, it  is  relative  to  the
+       current file's folder.
+
+       A tilde means home directory, eg: include ~/main.journal.
+
+       The path may contain glob patterns to match multiple files, eg: include
+       *.journal.
+
+       There is limited support for recursive wildcards: **/ (the slash is re-
+       quired)  matches  0  or more subdirectories.  It's not super convenient
+       since you have to avoid include cycles and including  directories,  but
+       this can be done, eg: include */**/*.journal.
+
+       The path may also be prefixed to force a specific file format, overrid-
+       ing  the  file  extension (as described in Data formats): include time-
+       dot:~/notes/2023*.md.
+
+   P directive
+       The P directive declares a market price, which is a conversion rate be-
+       tween two commodities on a certain date.  This allows value reports  to
+       convert amounts of one commodity to their value in another, on or after
+       that  date.   These  prices  are  often obtained from a stock exchange,
+       cryptocurrency exchange, the or foreign exchange market.
+
+       The format is:
+
+              P DATE COMMODITY1SYMBOL COMMODITY2AMOUNT
+
+       DATE is a simple date, COMMODITY1SYMBOL is the symbol of the  commodity
+       being  priced, and COMMODITY2AMOUNT is the amount (symbol and quantity)
+       of commodity 2 that one unit of commodity 1 is worth on this date.  Ex-
+       amples:
+
+              # one euro was worth $1.35 from 2009-01-01 onward:
+              P 2009-01-01  $1.35
+
+              # and $1.40 from 2010-01-01 onward:
+              P 2010-01-01  $1.40
+
+       The -V, -X and --value flags use these market  prices  to  show  amount
+       values in another commodity.  See Value reporting.
+
+   payee directive
+       payee PAYEE NAME
+
+       This directive can be used to declare a limited set of payees which may
+       appear  in transaction descriptions.  The "payees" check will report an
+       error if any transaction refers to a payee that has not been  declared.
+       Eg:
+
+              payee Whole Foods    ; a comment
+
+       Payees do not have tags (tags in the comment will be ignored).
+
+       To declare the empty payee name, use "".
+
+              payee ""
+
+       Ledger-style indented subdirectives, if any, are currently ignored.
+
+   tag directive
+       tag TAGNAME
+
+       This  directive  can  be used to declare a limited set of tag names al-
+       lowed in tags.  TAGNAME should be a valid tag name (no spaces).  Eg:
+
+              tag  item-id
+
+       Any indented subdirectives are currently ignored.
+
+       The "tags" check will report an error if any  undeclared  tag  name  is
+       used.  It is quite easy to accidentally create a tag through normal use
+       of colons in comments; if you want to prevent this, you can declare and
+       check your tags .
+
+   Periodic transactions
+       The  ~  directive  declares a "periodic rule" which generates temporary
+       extra transactions, usually recurring at some interval, when hledger is
+       run with the --forecast flag.  These "forecast transactions" are useful
+       for forecasting future activity.  They exist only for the  duration  of
+       the report, and only when --forecast is used; they are not saved in the
+       journal file by hledger.
+
+       Periodic  rules also have a second use: with the --budget flag they set
+       budget goals for budgeting.
+
+       Periodic rules can be a little tricky, so before  you  use  them,  read
+       this whole section, or at least the following tips:
+
+       1. Two  spaces  accidentally  added or omitted will cause you trouble -
+          read about this below.
+
+       2. For troubleshooting, show the generated  transactions  with  hledger
+          print   --forecast  tag:generated  or  hledger  register  --forecast
+          tag:generated.
+
+       3. Forecasted transactions will begin only  after  the  last  non-fore-
+          casted transaction's date.
+
+       4. Forecasted  transactions  will  end 6 months from today, by default.
+          See below for the exact start/end rules.
+
+       5. period expressions can be tricky.   Their  documentation  needs  im-
+          provement, but is worth studying.
+
+       6. Some  period  expressions  with a repeating interval must begin on a
+          natural boundary of that interval.  Eg in  weekly  from  DATE,  DATE
+          must  be a monday.  ~ weekly from 2019/10/1 (a tuesday) will give an
+          error.
+
+       7. Other period expressions with an interval are automatically expanded
+          to cover a whole number of that interval.  (This is done to  improve
+          reports, but it also affects periodic transactions.  Yes, it's a bit
+          inconsistent  with  the above.)  Eg:  ~ every 10th day of month from
+          2023/01, which is equivalent to  ~ every  10th  day  of  month  from
+          2023/01/01, will be adjusted to start on 2019/12/10.
+
+   Periodic rule syntax
+       A periodic transaction rule looks like a normal journal entry, with the
+       date replaced by a tilde (~) followed by a period expression (mnemonic:
+       ~ looks like a recurring sine wave.):
+
+              # every first of month
+              ~ monthly
+                  expenses:rent          $2000
+                  assets:bank:checking
+
+              # every 15th of month in 2023's first quarter:
+              ~ monthly from 2023-04-15 to 2023-06-16
+                  expenses:utilities          $400
+                  assets:bank:checking
+
+       The  period expression is the same syntax used for specifying multi-pe-
+       riod reports, just interpreted differently; there, it specifies  report
+       periods; here it specifies recurrence dates (the periods' start dates).
+
+   Periodic rules and relative dates
+       Partial  or  relative  dates (like 12/31, 25, tomorrow, last week, next
+       quarter) are usually not recommended in periodic rules, since  the  re-
+       sults  will  change  as time passes.  If used, they will be interpreted
+       relative to, in order of preference:
+
+       1. the first day of the default year specified by a recent Y directive
+
+       2. or the date specified with --today
+
+       3. or the date on which you are running the report.
+
+       They will not be affected at all by report period  or  forecast  period
+       dates.
+
+   Two spaces between period expression and description!
+       If  the  period  expression  is  followed by a transaction description,
+       these must be separated by two or more spaces.  This helps hledger know
+       where the period expression ends, so that descriptions can not acciden-
+       tally alter their meaning, as in this example:
+
+              ; 2 or more spaces needed here, so the period is not understood as "every 2 months in 2023"
+              ;               ||
+              ;               vv
+              ~ every 2 months  in 2023, we will review
+                  assets:bank:checking   $1500
+                  income:acme inc
+
+       So,
+
+       o Do write two spaces between your period expression and your  transac-
+         tion description, if any.
+
+       o Don't  accidentally write two spaces in the middle of your period ex-
+         pression.
+
+   Auto postings
+       The = directive declares an "auto posting rule", which adds extra post-
+       ings to existing transactions.  (Remember,  postings  are  the  account
+       name & amount lines below a transaction's date & description.)
+
+       In  the  journal,  an auto posting rule looks quite like a transaction,
+       but instead of date and description it has = (mnemonic: "match") and  a
+       query, like this:
+
+              = QUERY
+                  ACCOUNT    AMOUNT
+                  ...
+
+       Queries  are  just like command line queries; an account name substring
+       is most common.  Query terms containing spaces should  be  enclosed  in
+       single or double quotes.
+
+       Each  = rule works like this: when hledger is run with the --auto flag,
+       wherever the QUERY matches a posting in the journal, the  rule's  post-
+       ings are added to that transaction, immediately below the matched post-
+       ing.   Note  these  generated postings are temporary, existing only for
+       the duration of the report, and only when --auto is used; they are  not
+       saved in the journal file by hledger.
+
+       Generated postings' amounts can depend on the matched posting's amount.
+       So  auto  postings  can  be  useful for, eg, adding tax postings with a
+       standard percentage.  AMOUNT can be:
+
+       o a number with no commodity symbol, like  2.   The  matched  posting's
+         commodity symbol will be added to this.
+
+       o a  normal amount with a commodity symbol, like $2.  This will be used
+         as-is.
+
+       o an asterisk followed by a number, like *2.  This  will  multiply  the
+         matched posting's amount (and total price, if any) by the number.
+
+       o an  asterisk  followed  by an amount with commodity symbol, like *$2.
+         This multiplies and also replaces the commodity symbol with this  new
+         one.
+
+       Some examples:
+
+              ; every time I buy food, schedule a dollar donation
+              = expenses:food
+                  (liabilities:charity)   $-1
+
+              ; when I buy a gift, also deduct that amount from a budget envelope subaccount
+              = expenses:gifts
+                  assets:checking:gifts  *-1
+                  assets:checking         *1
+
+              2017/12/1
+                expenses:food    $10
+                assets:checking
+
+              2017/12/14
+                expenses:gifts   $20
+                assets:checking
+
+              $ hledger print --auto
+              2017-12-01
+                  expenses:food              $10
+                  assets:checking
+                  (liabilities:charity)      $-1
+
+              2017-12-14
+                  expenses:gifts             $20
+                  assets:checking
+                  assets:checking:gifts     -$20
+                  assets:checking            $20
+
+       Note that depending fully on generated data such as this has some draw-
+       backs  -  it's less portable, less future-proof, less auditable by oth-
+       ers, and less robust (eg your balance assertions will depend on whether
+       you use or don't use --auto).  An alternative is to use  auto  postings
+       in "one time" fashion - use them to help build a complex journal entry,
+       view  it  with hledger print --auto, and then copy that output into the
+       journal file to make it permanent.
+
+   Auto postings and multiple files
+       An auto posting rule can affect any transaction in the current file, or
+       in any parent file or child file.  Note, currently it will  not  affect
+       sibling files (when multiple -f/--file are used - see #1212).
+
+   Auto postings and dates
+       A  posting  date (or secondary date) in the matched posting, or (taking
+       precedence) a posting date in the auto posting rule itself,  will  also
+       be used in the generated posting.
+
+   Auto postings and transaction balancing / inferred amounts / balance asser-
+       tions
+       Currently, auto postings are added:
+
+       o after  missing amounts are inferred, and transactions are checked for
+         balancedness,
+
+       o but before balance assertions are checked.
+
+       Note this means that journal entries must be balanced both  before  and
+       after auto postings are added.  This changed in hledger 1.12+; see #893
+       for background.
+
+       This  also means that you cannot have more than one auto-posting with a
+       missing amount applied to a given transaction, as it will be unable  to
+       infer amounts.
+
+   Auto posting tags
+       Automated postings will have some extra tags:
+
+       o generated-posting:= QUERY - shows this was generated by an auto post-
+         ing rule, and the query
+
+       o _generated-posting:=  QUERY  - a hidden tag, which does not appear in
+         hledger's output.  This can be used to match postings generated "just
+         now", rather than generated in the past and saved to the journal.
+
+       Also, any transaction that has been changed by auto posting rules  will
+       have these tags added:
+
+       o modified: - this transaction was modified
+
+       o _modified: - a hidden tag not appearing in the comment; this transac-
+         tion was modified "just now".
+
+   Auto postings on forecast transactions only
+       Tip:  you can can make auto postings that will apply to forecast trans-
+       actions but not recorded transactions, by adding  tag:_generated-trans-
+       action  to their QUERY.  This can be useful when generating new journal
+       entries to be saved in the journal.
+
+   Other syntax
+       hledger journal format supports quite a few other features,  mainly  to
+       make  interoperating  with or converting from Ledger easier.  Note some
+       of the features below are powerful and can be useful in special  cases,
+       but  in general, features in this section are considered less important
+       or even not recommended for most users.   Downsides  are  mentioned  to
+       help you decide if you want to use them.
+
+   Balance assignments
+       Ledger-style  balance  assignments  are also supported.  These are like
+       balance assertions, but with no posting amount on the left side of  the
+       equals  sign;  instead  it is calculated automatically so as to satisfy
+       the assertion.  This can be a convenience during data  entry,  eg  when
+       setting opening balances:
+
+              ; starting a new journal, set asset account balances
+              2016/1/1 opening balances
+                assets:checking            = $409.32
+                assets:savings             = $735.24
+                assets:cash                 = $42
+                equity:opening balances
+
+       or when adjusting a balance to reality:
+
+              ; no cash left; update balance, record any untracked spending as a generic expense
+              2016/1/15
+                assets:cash    = $0
+                expenses:misc
+
+       The calculated amount depends on the account's balance in the commodity
+       at  that  point  (which depends on the previously-dated postings of the
+       commodity to that account since the last balance assertion  or  assign-
+       ment).
+
+       Downsides:  using balance assignments makes your journal less explicit;
+       to know the exact amount posted, you have to run hledger or do the cal-
+       culations yourself, instead of just reading it.  Also  balance  assign-
+       ments' forcing of balances can hide errors.  These things make your fi-
+       nancial  data less portable, less future-proof, and less trustworthy in
+       an audit.
+
+   Balance assignments and costs
+       A cost in a balance assignment will cause the calculated amount to have
+       that cost attached:
+
+              2019/1/1
+                (a)             = $1 @ 2
+
+              $ hledger print --explicit
+              2019-01-01
+                  (a)         $1 @ 2 = $1 @ 2
+
+   Balance assignments and multiple files
+       Balance assignments handle  multiple  files  like  balance  assertions.
+       They  see balance from other files previously included from the current
+       file, but not from previous sibling or parent files.
+
+   Bracketed posting dates
+       For setting posting dates and secondary posting dates, Ledger's  brack-
+       eted date syntax is also supported: [DATE], [DATE=DATE2] or [=DATE2] in
+       posting  comments.   hledger will attempt to parse any square-bracketed
+       sequence of the 0123456789/-.= characters in this way.  With this  syn-
+       tax,  DATE  infers  its  year from the transaction and DATE2 infers its
+       year from DATE.
+
+       Downsides:  another  syntax  to   learn,   redundant   with   hledger's
+       date:/date2: tags, and confusingly similar to Ledger's lot date syntax.
+
+   D directive
+       D AMOUNT
+
+       This  directive sets a default commodity, to be used for any subsequent
+       commodityless amounts (ie, plain numbers) seen while parsing the  jour-
+       nal.   This  effect lasts until the next D directive, or the end of the
+       current file.
+
+       For compatibility/historical reasons, D also acts like a commodity  di-
+       rective  (setting  the commodity's decimal mark for parsing and display
+       style for output).  So its argument is not just a commodity symbol, but
+       a full amount demonstrating the style.  The amount must include a deci-
+       mal mark (either period or comma).  Eg:
+
+              ; commodity-less amounts should be treated as dollars
+              ; (and displayed with the dollar sign on the left, thousands separators and two decimal places)
+              D $1,000.00
+
+              1/1
+                a     5  ; <- commodity-less amount, parsed as $5 and displayed as $5.00
+                b
+
+       Interactions with other directives:
+
+       For setting a commodity's display  style,  a  commodity  directive  has
+       highest priority, then a D directive.
+
+       For  detecting  a commodity's decimal mark during parsing, decimal-mark
+       has highest priority, then commodity, then D.
+
+       For checking commodity symbols with the check command, a commodity  di-
+       rective is required (hledger check commodities ignores D directives).
+
+       Downsides:  omitting  commodity  symbols makes your financial data less
+       explicit, less portable, and less trustworthy in an audit.  It is  usu-
+       ally  an unsustainable shortcut; sooner or later you will want to track
+       multiple commodities.  D is overloaded with  functions  redundant  with
+       commodity and decimal-mark.  And it works differently from Ledger's D.
+
+   apply account directive
+       This  directive  sets a default parent account, which will be prepended
+       to all accounts in following entries, until an end apply account direc-
+       tive or end of current file.  Eg:
+
+              apply account home
+
+              2010/1/1
+                  food    $10
+                  cash
+
+              end apply account
+
+       is equivalent to:
+
+              2010/01/01
+                  home:food           $10
+                  home:cash          $-10
+
+       account directives are also affected, and so is any included content.
+
+       Account names entered via hledger add or hledger-web are not affected.
+
+       Account aliases, if any,  are  applied  after  the  parent  account  is
+       prepended.
+
+       Downsides:  this  can  make  your  financial  data  less explicit, less
+       portable, and less trustworthy in an audit.
+
+   Y directive
+       Y YEAR
+
+       or (deprecated backward-compatible forms):
+
+       year YEAR apply year YEAR
+
+       The space is optional.  This sets a default year to be used for  subse-
+       quent dates which don't specify a year.  Eg:
+
+              Y2009  ; set default year to 2009
+
+              12/15  ; equivalent to 2009/12/15
+                expenses  1
+                assets
+
+              year 2010  ; change default year to 2010
+
+              2009/1/30  ; specifies the year, not affected
+                expenses  1
+                assets
+
+              1/31   ; equivalent to 2010/1/31
+                expenses  1
+                assets
+
+       Downsides: omitting the year (from primary transaction dates, at least)
+       makes your financial data less explicit, less portable, and less trust-
+       worthy  in  an  audit.   Such dates can get separated from their corre-
+       sponding Y directive, eg when evaluating a region  of  the  journal  in
+       your  editor.  A missing Y directive makes reports dependent on today's
+       date.
+
+   Secondary dates
+       A secondary date is written after the primary date, following an equals
+       sign: DATE1=DATE2.  If the year is omitted, the primary date's year  is
+       assumed.  When running reports, the primary (left side) date is used by
+       default, but with the --date2 flag (--aux-date or--effective also work,
+       for  Ledger  users),  the  secondary (right side) date will be used in-
+       stead.
+
+       The meaning of secondary dates is up to you.  Eg it could  be  "primary
+       is  the bank's clearing date, secondary is the date the transaction was
+       initiated, if different".
+
+       In practice, this feature usually adds confusion:
+
+       o You have to remember the primary and secondary  dates'  meaning,  and
+         follow that consistently.
+
+       o It  splits  your bookkeeping into two modes, and you have to remember
+         which mode is appropriate for a given report.
+
+       o Usually your balance assertions will work  with  only  one  of  these
+         modes.
+
+       o It  makes  your  financial  data more complicated, less portable, and
+         less clear in an audit.
+
+       o It interacts with every feature, creating an ongoing cost for  imple-
+         mentors.
+
+       o It distracts new users and supporters.
+
+       o Posting dates are simpler and work better.
+
+       So secondary dates are officially deprecated in hledger, remaining only
+       as  a  Ledger  compatibility  aid; we recommend using posting dates in-
+       stead.
+
+   Star comments
+       Lines beginning with * (star/asterisk) are also  comment  lines.   This
+       feature allows Emacs users to insert org headings in their journal, al-
+       lowing them to fold/unfold/navigate it like an outline when viewed with
+       org mode.
+
+       Downsides:  another, unconventional comment syntax to learn.  Decreases
+       your journal's portability.  And switching to Emacs org mode  just  for
+       folding/unfolding  meant  losing  the benefits of ledger mode; nowadays
+       you can add outshine mode to ledger mode to get folding without  losing
+       ledger mode's features.
+
+   Valuation expressions
+       Ledger  allows  a  valuation  function or value to be written in double
+       parentheses after an amount.  hledger ignores these.
+
+   Virtual postings
+       A posting with parentheses around the account name, like (some:account)
+       10, is called an unbalanced virtual posting.   These  postings  do  not
+       participate  in  transaction balancing.  (And if you write them without
+       an amount, a zero amount is always inferred.)  These  can  occasionally
+       be  convenient for special circumstances, but they violate double entry
+       bookkeeping and make your data less portable  across  applications,  so
+       many people avoid using them at all.
+
+       A  posting  with  brackets  around the account name ([some:account]) is
+       called a balanced virtual posting.  The balanced virtual postings in  a
+       transaction must add up to zero, just like ordinary postings, but sepa-
+       rately  from  them.  These are not part of double entry bookkeeping ei-
+       ther, but they are at least balanced.  An example:
+
+              2022-01-01 buy food with cash, update budget envelope subaccounts, & something else
+                assets:cash                    $-10  ; <- these balance each other
+                expenses:food                    $7  ; <-
+                expenses:food                    $3  ; <-
+                [assets:checking:budget:food]  $-10  ;   <- and these balance each other
+                [assets:checking:available]     $10  ;   <-
+                (something:else)                 $5  ;     <- this is not required to balance
+
+       Ordinary postings, whose account names are  neither  parenthesised  nor
+       bracketed,  are called real postings.  You can exclude virtual postings
+       from reports with the -R/--real flag or a real:1 query.
+
+   Other Ledger directives
+       These other Ledger directives are currently accepted but ignored.  This
+       allows hledger to read more Ledger files, but be aware  that  hledger's
+       reports may differ from Ledger's if you use these.
+
+              apply fixed COMM AMT
+              apply tag   TAG
+              assert      EXPR
+              bucket / A  ACCT
+              capture     ACCT REGEX
+              check       EXPR
+              define      VAR=EXPR
+              end apply fixed
+              end apply tag
+              end apply year
+              end tag
+              eval / expr EXPR
+              python
+                PYTHONCODE
+              tag         NAME
+              value       EXPR
+              --command-line-flags
+
+       See  also https://hledger.org/ledger.html for a detailed hledger/Ledger
+       syntax comparison.
+
+   Other cost/lot notations
+       A slight digression for Ledger and Beancount users.
+
+       Ledger has a number of cost/lot-related notations:
+
+       o @ UNITCOST and @@ TOTALCOST
+
+         o expresses a conversion rate, as in hledger
+
+         o when buying, also creates a lot that can  be  selected  at  selling
+           time
+
+       o (@) UNITCOST and (@@) TOTALCOST (virtual cost)
+
+         o like  the  above,  but also means "this cost was exceptional, don't
+           use it when inferring market prices".
+
+       o {=UNITCOST} and {{=TOTALCOST}} (fixed price)
+
+         o when buying, means "this cost is also the fixed value, don't let it
+           fluctuate in value reports"
+
+       o {UNITCOST} and {{TOTALCOST}} (lot price)
+
+         o can be used identically to @ UNITCOST and @@ TOTALCOST,  also  cre-
+           ates a lot
+
+         o when  selling,  combined with @ ..., selects an existing lot by its
+           cost basis.  Does not check if that lot is present.
+
+       o [YYYY/MM/DD] (lot date)
+
+         o when buying, attaches this acquisition date to the lot
+
+         o when selling, selects a lot by its acquisition date
+
+       o (SOME TEXT) (lot note)
+
+         o when buying, attaches this note to the lot
+
+         o when selling, selects a lot by its note
+
+       Currently, hledger
+
+       o accepts any or all of the above in any order after the posting amount
+
+       o supports @ and @@
+
+       o treats (@) and (@@) as synonyms for @ and @@
+
+       o and ignores the rest.  (This can break transaction balancing.)
+
+       Beancount has simpler notation and different behaviour:
+
+       o @ UNITCOST and @@ TOTALCOST
+
+         o expresses a cost without creating a lot, as in hledger
+
+         o when buying (acquiring) or selling (disposing of) a lot,  and  com-
+           bined  with  {...}: is not used except to document the cost/selling
+           price
+
+       o {UNITCOST} and {{TOTALCOST}}
+
+         o when buying, expresses the cost for transaction balancing, and also
+           creates a lot with this cost basis attached
+
+         o when selling,
+
+           o selects a lot by its cost basis
+
+           o raises an error if that lot is not present or can not be selected
+             unambiguously (depending on booking method configured)
+
+           o expresses the selling price for transaction balancing
+
+       o {},  {YYYY-MM-DD},   {"LABEL"},   {UNITCOST,   "LABEL"},   {UNITCOST,
+         YYYY-MM-DD, "LABEL"}
+
+         o when  selling,  other  combinations  of  date/cost/label,  like the
+           above, are accepted for selecting the lot.
+
+       Currently, hledger
+
+       o supports @ and @@
+
+       o accepts the {UNITCOST}/{{TOTALCOST}} notation, but ignores it
+
+       o and rejects the rest.
+
+CSV
+       hledger can read CSV files (Character Separated Value - usually  comma,
+       semicolon,  or  tab) containing dated records, automatically converting
+       each record into a transaction.
+
+       (To learn about writing CSV, see CSV output.)
+
+       For best error messages when reading CSV/TSV/SSV files, make sure  they
+       have a corresponding .csv, .tsv or .ssv file extension or use a hledger
+       file prefix (see File Extension below).
+
+       Each CSV file must be described by a corresponding rules file.
+       This  contains  rules describing the CSV data (header line, fields lay-
+       out, date format etc.), how to construct hledger transactions from  it,
+       and  how  to  categorise transactions based on description or other at-
+       tributes.
+
+       By default, hledger expects this rules file to be named  like  the  CSV
+       file,  with an extra .rules extension added, in the same directory.  Eg
+       when asked to read foo/FILE.csv, hledger looks for  foo/FILE.csv.rules.
+       You can specify a different rules file with the --rules option.
+
+       At  minimum,  the  rules file must identify the date and amount fields,
+       and often it also specifies the date format and how many  header  lines
+       there are.  Here's a simple CSV file and a rules file for it:
+
+              Date, Description, Id, Amount
+              12/11/2019, Foo, 123, 10.23
+
+              # basic.csv.rules
+              skip         1
+              fields       date, description, , amount
+              date-format  %d/%m/%Y
+
+              $ hledger print -f basic.csv
+              2019-11-12 Foo
+                  expenses:unknown           10.23
+                  income:unknown            -10.23
+
+       There's an introductory Importing CSV data tutorial on hledger.org, and
+       more   CSV   rules   examples   below,   and  a  larger  collection  at
+       https://github.com/simonmichael/hledger/tree/master/examples/csv.
+
+   CSV rules cheatsheet
+       The following kinds of rule can appear in the rules file, in any order.
+       (Blank lines and lines beginning with # or ; or * are ignored.)
+
+       source                     optionally declare which  file  to  read  data
+                                  from
+       encoding                   optionally  declare  which  text  encoding the
+                                  data has
+       separator                  declare the field separator, instead of  rely-
+                                  ing on file extension
+       skip                       skip one or more header lines at start of file
+       date-format                declare how to parse CSV dates/date-times
+       timezone                   declare   the   time  zone  of  ambiguous  CSV
+                                  date-times
+       newest-first               improve txn order  when:  there  are  multiple
+                                  records, newest first, all with the same date
+       intra-day-reversed         improve  txn  order when: same-day txns are in
+                                  opposite order to the overall file
+       decimal-mark               declare the decimal mark used in CSV  amounts,
+                                  when ambiguous
+       fields list                name  CSV  fields  for easy reference, and op-
+                                  tionally assign their values to hledger fields
+       Field assignment           assign a CSV value or interpolated text  value
+                                  to a hledger field
+       if block                   conditionally assign values to hledger fields,
+                                  or skip a record or end (skip rest of file)
+       if table                   conditionally assign values to hledger fields,
+                                  using compact syntax
+       balance-type               select  which  type  of balance assertions/as-
+                                  signments to generate
+       include                    inline another CSV rules file
+
+       Working with CSV tips can be found below, including How CSV  rules  are
+       evaluated.
+
+   source
+       If  you  tell  hledger to read a csv file with -f foo.csv, it will look
+       for rules in foo.csv.rules.  Or, you can tell  it  to  read  the  rules
+       file,  with  -f  foo.csv.rules,  and  it  will look for data in foo.csv
+       (since 1.30).
+
+       These are mostly equivalent, but the second method provides some  extra
+       features.   For  one,  the data file can be missing, without causing an
+       error; it is just considered empty.  And, you can specify  a  different
+       data file by adding a "source" rule:
+
+              source ./Checking1.csv
+
+       If  you specify just a file name with no path, hledger will look for it
+       in your system's downloads directory (~/Downloads, currently):
+
+              source Checking1.csv
+
+       And if you specify a glob pattern, hledger will read the most recent of
+       the matched files (useful with repeated downloads):
+
+              source Checking1*.csv
+
+       See also "Working with CSV > Reading files specified by rule".
+
+   encoding
+              encoding ENCODING
+
+       hledger normally expects non-ascii text to  be  UTF8-encoded.   If  you
+       need to read CSV files which have some other encoding, you can do it by
+       adding encoding ENCODING to your CSV rules.  Eg: encoding ISO88591.
+
+       The  following  encodings  are supported (these names are case-insensi-
+       tive, and can be written with inner spaces or hyphens if  you  prefer):
+       ASCII,  UTF8,  UTF16,  UTF32,  ISO88591,  ISO88592, ISO88593, ISO88594,
+       ISO88595, ISO88596, ISO88597, ISO88598, ISO88599, ISO885910, ISO885911,
+       ISO885913, ISO885914, ISO885915,  ISO885916,  CP1250,  CP1251,  CP1252,
+       CP1253,  CP1254, CP1255, CP1256, CP1257, CP1258, KOI8R, KOI8U, GB18030,
+       MacOSRoman, JISX0201,  JISX0208,  ISO2022JP,  ShiftJIS,  CP437,  CP737,
+       CP775,  CP850,  CP852, CP855, CP857, CP860, CP861, CP862, CP863, CP864,
+       CP865, CP866, CP869, CP874, CP932.
+
+   separator
+       You can use the separator rule to read other kinds  of  character-sepa-
+       rated  data.   The  argument  is any single separator character, or the
+       words tab or space (case insensitive).  Eg, for comma-separated  values
+       (CSV):
+
+              separator ,
+
+       or for semicolon-separated values (SSV):
+
+              separator ;
+
+       or for tab-separated values (TSV):
+
+              separator TAB
+
+       If  the  input file has a .csv, .ssv or .tsv file extension (or a csv:,
+       ssv:, tsv: prefix), the appropriate separator will be inferred automat-
+       ically, and you won't need this rule.
+
+   skip
+              skip N
+
+       The word skip followed by a number (or  no  number,  meaning  1)  tells
+       hledger  to  ignore this many non-empty lines at the start of the input
+       data.  You'll need this whenever your CSV data contains  header  lines.
+       Note,  empty  and  blank  lines are skipped automatically, so you don't
+       need to count those.
+
+       skip has a second meaning: it can be used inside if  blocks  (described
+       below),  to  skip  one  or more records whenever the condition is true.
+       Records skipped in this way are ignored, except they are still required
+       to be valid CSV.
+
+   date-format
+              date-format DATEFMT
+
+       This is a helper for the date (and date2) fields.  If  your  CSV  dates
+       are  not  formatted  like  YYYY-MM-DD, YYYY/MM/DD or YYYY.MM.DD, you'll
+       need to add a date-format rule describing them  with  a  strptime-style
+       date    parsing   pattern   -   see   https://hackage.haskell.org/pack-
+       age/time/docs/Data-Time-Format.html#v:formatTime.   The  pattern   must
+       parse the CSV date value completely.  Some examples:
+
+              # MM/DD/YY
+              date-format %m/%d/%y
+
+              # D/M/YYYY
+              # The - makes leading zeros optional.
+              date-format %-d/%-m/%Y
+
+              # YYYY-Mmm-DD
+              date-format %Y-%h-%d
+
+              # M/D/YYYY HH:MM AM some other junk
+              # Note the time and junk must be fully parsed, though only the date is used.
+              date-format %-m/%-d/%Y %l:%M %p some other junk
+
+   timezone
+              timezone TIMEZONE
+
+       When  CSV  contains  date-times  that  are implicitly in some time zone
+       other than yours, but containing no explicit time zone information, you
+       can use this rule to declare the CSV's native time  zone,  which  helps
+       prevent off-by-one dates.
+
+       When  the  CSV  date-times  do contain time zone information, you don't
+       need this rule; instead, use %Z in date-format (or %z,  %EZ,  %Ez;  see
+       the formatTime link above).
+
+       In either of these cases, hledger will do a time-zone-aware conversion,
+       localising the CSV date-times to your current system time zone.  If you
+       prefer to localise to some other time zone, eg for reproducibility, you
+       can  (on unix at least) set the output timezone with the TZ environment
+       variable, eg:
+
+              $ TZ=-1000 hledger print -f foo.csv  # or TZ=-1000 hledger import foo.csv
+
+       timezone currently does not understand timezone  names,  except  "UTC",
+       "GMT",  "EST", "EDT", "CST", "CDT", "MST", "MDT", "PST", or "PDT".  For
+       others, use numeric format: +HHMM or -HHMM.
+
+   newest-first
+       hledger tries to ensure that the generated transactions will be ordered
+       chronologically,  including  same-day  transactions.   Usually  it  can
+       auto-detect  how the CSV records are ordered.  But if it encounters CSV
+       where all records are on the same date, it assumes that the records are
+       oldest first.  If in fact the CSV's records are normally newest  first,
+       like:
+
+              2022-10-01, txn 3...
+              2022-10-01, txn 2...
+              2022-10-01, txn 1...
+
+       you can add the newest-first rule to help hledger generate the transac-
+       tions in correct order.
+
+              # same-day CSV records are newest first
+              newest-first
+
+   intra-day-reversed
+       If  CSV records within a single day are ordered opposite to the overall
+       record order, you can add the intra-day-reversed rule  to  improve  the
+       order  of journal entries.  Eg, here the overall record order is newest
+       first, but same-day records are oldest first:
+
+              2022-10-02, txn 3...
+              2022-10-02, txn 4...
+              2022-10-01, txn 1...
+              2022-10-01, txn 2...
+
+              # transactions within each day are reversed with respect to the overall date order
+              intra-day-reversed
+
+   decimal-mark
+              decimal-mark .
+
+       or:
+
+              decimal-mark ,
+
+       hledger automatically accepts either period or comma as a decimal  mark
+       when  parsing  numbers (cf Amounts).  However if any numbers in the CSV
+       contain digit group marks,  such  as  thousand-separating  commas,  you
+       should  declare  the  decimal  mark explicitly with this rule, to avoid
+       misparsed numbers.
+
+   fields list
+              fields FIELDNAME1, FIELDNAME2, ...
+
+       A fields list (the word fields followed by comma-separated field names)
+       is optional, but convenient.  It does two things:
+
+       1. It names the CSV field in each column.  This can  be  convenient  if
+          you  are  referencing them in other rules, so you can say %SomeField
+          instead of remembering %13.
+
+       2. Whenever you use one of the special hledger field  names  (described
+          below),  it  assigns  the CSV value in this position to that hledger
+          field.  This is the quickest way to populate  hledger's  fields  and
+          build a transaction.
+
+       Here's  an  example  that  says "use the 1st, 2nd and 4th fields as the
+       transaction's date, description and amount; name the  last  two  fields
+       for later reference; and ignore the others":
+
+              fields date, description, , amount, , , somefield, anotherfield
+
+       In a fields list, the separator is always comma; it is unrelated to the
+       CSV file's separator.  Also:
+
+       o There must be least two items in the list (at least one comma).
+
+       o Field  names may not contain spaces.  Spaces before/after field names
+         are optional.
+
+       o Field names may contain _ (underscore) or - (hyphen).
+
+       o Fields you don't care about can be given a dummy  name  or  an  empty
+         name.
+
+       If  the  CSV contains column headings, it's convenient to use these for
+       your field names, suitably modified (eg  lower-cased  with  spaces  re-
+       placed by underscores).
+
+       Sometimes  you may want to alter a CSV field name to avoid assigning to
+       a hledger field with the same name.  Eg you could call the CSV's  "bal-
+       ance"  field balance_ to avoid directly setting hledger's balance field
+       (and generating a balance assertion).
+
+   Field assignment
+              HLEDGERFIELD FIELDVALUE
+
+       Field assignments are the more flexible way to  assign  CSV  values  to
+       hledger fields.  They can be used instead of or in addition to a fields
+       list (see above).
+
+       To  assign a value to a hledger field, write the field name (any of the
+       standard hledger field/pseudo-field names,  defined  below),  a  space,
+       followed  by a text value on the same line.  This text value may inter-
+       polate CSV fields, referenced either by their 1-based position  in  the
+       CSV  record  (%N)  or  by  the  name they were given in the fields list
+       (%CSVFIELD), and regular expression match groups (\N).
+
+       Some examples:
+
+              # set the amount to the 4th CSV field, with " USD" appended
+              amount %4 USD
+
+              # combine three fields to make a comment, containing note: and date: tags
+              comment note: %somefield - %anotherfield, date: %1
+
+       Tips:
+
+       o Interpolation strips outer whitespace (so a CSV value like " 1 "  be-
+         comes 1 when interpolated) (#1051).
+
+       o Interpolations  always refer to a CSV field - you can't interpolate a
+         hledger field.  (See Referencing other fields below).
+
+   Field names
+       Note the two kinds of field names mentioned  here,  and  used  only  in
+       hledger CSV rules files:
+
+       1. CSV  field  names  (CSVFIELD in these docs): you can optionally name
+          the CSV columns for easy reference (since hledger doesn't yet  auto-
+          matically recognise column headings in a CSV file), by writing arbi-
+          trary names in a fields list, eg:
+
+                  fields When, What, Some_Id, Net, Total, Foo, Bar
+
+       2. Special  hledger  field names (HLEDGERFIELD in these docs): you must
+          set at least some of these to generate the hledger transaction  from
+          a  CSV  record, by writing them as the left hand side of a field as-
+          signment, eg:
+
+                  date        %When
+                  code        %Some_Id
+                  description %What
+                  comment     %Foo %Bar
+                  amount1     $ %Total
+
+           or directly in a fields list:
+
+                  fields date, description, code, , amount1, Foo, Bar
+                  currency $
+                  comment  %Foo %Bar
+
+       Here are all the special hledger field names available, and  what  hap-
+       pens when you assign values to them:
+
+   date field
+       Assigning to date sets the transaction date.
+
+   date2 field
+       date2 sets the transaction's secondary date, if any.
+
+   status field
+       status sets the transaction's status, if any.
+
+   code field
+       code sets the transaction's code, if any.
+
+   description field
+       description sets the transaction's description, if any.
+
+   comment field
+       comment sets the transaction's comment, if any.
+
+       commentN, where N is a number, sets the Nth posting's comment.
+
+       You  can  assign multi-line comments by writing literal \n in the code.
+       A comment starting with \n will begin on a new line.
+
+       Comments can contain tags, as usual.
+
+       Posting comments can also contain a posting date.  A secondary date, or
+       a year-less date, will be ignored.
+
+   account field
+       Assigning to accountN, where N is 1 to 99, sets the account name of the
+       Nth posting, and causes that posting to be generated.
+
+       Most often there are two postings, so you'll want to set  account1  and
+       account2.   Typically  account1 is associated with the CSV file, and is
+       set once with a top-level assignment, while account2 is  set  based  on
+       each transaction's description, in conditional rules.
+
+       If  a  posting's  account name is left unset but its amount is set (see
+       below), a default account name will be chosen (like  "expenses:unknown"
+       or "income:unknown").
+
+   amount field
+       There  are several ways to set posting amounts from CSV, useful in dif-
+       ferent situations.
+
+       1. amount is the oldest and  simplest.   Assigning  to  this  sets  the
+          amount of the first and second postings.  In the second posting, the
+          amount  will be negated; also, if it has a cost attached, it will be
+          converted to cost.
+
+       2. amount-in and amount-out work exactly like the above, but should  be
+          used  when  the  CSV  has  two  amount  fields  (such as "Debit" and
+          "Credit",  or  "Inflow"  and  "Outflow").   Whichever  field  has  a
+          non-zero  value  will  be used as the amount of the first and second
+          postings.  Here are some tips to avoid confusion:
+
+           o It's not "amount-in for posting 1 and amount-out for posting  2",
+             it  is  "extract a single amount from the amount-in or amount-out
+             field, and use that for posting 1 and (negated) for posting 2".
+
+           o Don't use both amount and amount-in/amount-out in the same  rules
+             file; choose based on whether the amount is in a single CSV field
+             or spread across two fields.
+
+           o In  each record, at most one of the two CSV fields should contain
+             a non-zero amount; the other field must contain a zero  or  noth-
+             ing.
+
+           o hledger  assumes both CSV fields contain unsigned numbers, and it
+             automatically negates the amount-out values.
+
+           o If the data doesn't fit these requirements, you'll probably  need
+             an if rule (see below).
+
+       3. amountN (where N is a number from 1 to 99) sets the amount of only a
+          single  posting: the Nth posting in the transaction.  You'll usually
+          need at least two such assignments to make a  balanced  transaction.
+          You can also generate more than two postings, to represent more com-
+          plex  transactions.   The  posting numbers don't have to be consecu-
+          tive; with if rules, higher posting numbers can be useful to  ensure
+          a certain order of postings.
+
+       4. amountN-in  and  amountN-out work exactly like the above, but should
+          be used when the CSV has two amount fields.  This  is  analogous  to
+          amount-in and amount-out, and those tips also apply here.
+
+       5. Remember that a fields list can also do assignments.  So in a fields
+          list  if  you name a CSV field "amount", that counts as assigning to
+          amount.  (If you don't want that, call  it  something  else  in  the
+          fields list, like "amount_".)
+
+       6. The  above  don't handle every situation; if you need more flexibil-
+          ity, use an if rule to set amounts conditionally.  See "Working with
+          CSV > Setting amounts" below for more on this and on  amount-setting
+          generally.
+
+   currency field
+       currency  sets  a  currency  symbol,  to  be prepended to all postings'
+       amounts.  You can use this if the CSV amounts do not  have  a  currency
+       symbol, eg if it is in a separate column.
+
+       currencyN prepends a currency symbol to just the Nth posting's amount.
+
+   balance field
+       balanceN  sets  a balance assertion amount (or if the posting amount is
+       left empty, a balance assignment) on posting N.
+
+       balance is a compatibility spelling for hledger <1.17; it is equivalent
+       to balance1.
+
+       You can adjust the type of assertion/assignment with  the  balance-type
+       rule (see below).
+
+       See  the Working with CSV tips below for more about setting amounts and
+       currency.
+
+   if block
+       Rules can be applied conditionally, depending on patterns  in  the  CSV
+       data.   This allows flexibility; in particular, it is how you can cate-
+       gorise transactions, selecting an appropriate  account  name  based  on
+       their  description  (for  example).  There are two ways to write condi-
+       tional rules: "if blocks", described here, and "if  tables",  described
+       below.
+
+       An  if  block is the word if and one or more "matcher" expressions (can
+       be a word or phrase), one per line, starting either on the same or next
+       line; followed by one or more indented rules.  Eg,
+
+              if MATCHER
+               RULE
+
+       or
+
+              if
+              MATCHER
+              MATCHER
+              MATCHER
+               RULE
+               RULE
+
+       If any of the matchers succeeds, all of the indented rules will be  ap-
+       plied.   They  are usually field assignments, but the following special
+       rules may also be used within an if block:
+
+       o skip - skips the matched CSV record (generating no  transaction  from
+         it)
+
+       o end - skips the rest of the current CSV file.
+
+       Some examples:
+
+              # if the record contains "groceries", set account2 to "expenses:groceries"
+              if groceries
+               account2 expenses:groceries
+
+              # if the record contains any of these phrases, set account2 and a transaction comment as shown
+              if
+              monthly service fee
+              atm transaction fee
+              banking thru software
+               account2 expenses:business:banking
+               comment  XXX deductible ? check it
+
+              # if an empty record is seen (assuming five fields), ignore the rest of the CSV file
+              if ,,,,
+               end
+
+   Matchers
+       There are two kinds of matcher:
+
+       1. A  whole  record matcher is simplest: it is just a word, single-line
+          text fragment, or other regular expression, which hledger  will  try
+          to match case-insensitively anywhere within the CSV record.
+       Eg: whole foods.
+
+       2. A  field matcher has a percent-prefixed CSV field number or name be-
+          fore the pattern.
+       Eg: %3 whole foods or %description whole foods.
+       hledger will try to match the pattern just within the named CSV field.
+
+       When using these, there's two things to be aware of:
+
+       1. Whole record matchers don't see the exact original record; they  see
+          a  reconstruction  of  it,  in which values are comma-separated, and
+          quotes enclosing values and whitespace outside those quotes are  re-
+          moved.
+       Eg when reading an SSV record like: 2023-01-01 ; "Acme, Inc. " ;  1,000
+       the whole record matcher sees instead: 2023-01-01,Acme, Inc. ,1,000
+
+       2. Field matchers expect either a CSV field number, or a CSV field name
+          declared  with fields.  (Don't use a hledger field name here, unless
+          it is also a CSV field name.)  A non-CSV field name will  cause  the
+          matcher  to  match against "" (the empty string), and does not raise
+          an error, allowing easier reuse of common rules with  different  CSV
+          files.
+
+       You can also prefix a matcher with ! (and optional space) to negate it.
+       Eg  !  whole  foods,  !  %3 whole foods, !%description whole foods will
+       match if "whole foods" is NOT present.  Added in 1.32.
+
+       The pattern is, as usual in hledger, a POSIX extended  regular  expres-
+       sion  that also supports GNU word boundaries (\b, \B, \<, \>) and noth-
+       ing else.  If you have trouble with it, see  "Regular  expressions"  in
+       the  hledger  manual  (https://hledger.org/hledger.html#regular-expres-
+       sions).
+
+   Multiple matchers
+       When an if block has multiple matchers, each on its own line,
+
+       o By default they are OR'd (any of them can match).
+
+       o Matcher lines beginning with & (or &&, since 1.42)  are  AND'ed  with
+         the matcher above (all in the AND'ed group must match).
+
+       o Matcher  lines  beginning  with & ! (since 1.41, or && !, since 1.42)
+         are first negated and then AND'ed with the matcher above.
+
+       You can also combine multiple matchers one the same line  separated  by
+       && (AND) or && ! (AND NOT).  Eg %description amazon && %date 2025-01-01
+       will  match  only  when the description field contains "amazon" and the
+       date field contains "2025-01-01".  Added in 1.42.
+
+   Match groups
+       Added in 1.32
+
+       Matchers can define match groups: parenthesised portions of the regular
+       expression which are available  for  reference  in  field  assignments.
+       Groups are enclosed in regular parentheses (( and )) and can be nested.
+       Each  group is available in field assignments using the token \N, where
+       N is an index into the match groups for this  conditional  block  (e.g.
+       \1, \2, etc.).
+
+       Example:  Warp  credit  card  payment  postings to the beginning of the
+       billing period (Month start), to match how they are presented in state-
+       ments, using posting dates:
+
+              if %date (....-..)-..
+                comment2 date:\1-01
+
+       Another example: Read the expense account from the CSV field, but throw
+       away a prefix:
+
+              if %account1 liabilities:family:(expenses:.*)
+                  account1 \1
+
+   if table
+       "if tables" are an alternative to if  blocks;  they  can  express  many
+       matchers  and  field assignments in a more compact tabular format, like
+       this:
+
+              if,HLEDGERFIELD1,HLEDGERFIELD2,...
+              MATCHERA,VALUE1,VALUE2,...
+              MATCHERB && MATCHERC,VALUE1,VALUE2,...  (*since 1.42*)
+              ; Comment line that explains MATCHERD
+              MATCHERD,VALUE1,VALUE2,...
+              <empty line>
+
+       The first character after if is taken to be this if table's field sepa-
+       rator.  It is unrelated to the separator used  in  the  CSV  file.   It
+       should be a non-alphanumeric character like , or | that does not appear
+       anywhere  else  in  the  table (it should not be used in field names or
+       matchers or values, and it cannot be escaped with a backslash).
+
+       Each line must contain the same number of separators; empty values  are
+       allowed.   Whitespace  can be used in the matcher lines for readability
+       (but not in the if line, currently).  You can use the comment lines  in
+       the  table body.  The table must be terminated by an empty line (or end
+       of file).
+
+       An if table like the above is interpreted as follows: try  all  of  the
+       lines with matchers; whenever a line with matchers succeeds, assign all
+       of the values on that line to the corresponding hledger fields; If mul-
+       tiple  lines  match,  later  lines will override fields assigned by the
+       earlier ones - just like the sequence of if blocks would behave.
+
+       If table presented above is equivalent to this sequence of if blocks:
+
+              if MATCHERA
+                HLEDGERFIELD1 VALUE1
+                HLEDGERFIELD2 VALUE2
+                ...
+
+              if MATCHERB && MATCHERC
+                HLEDGERFIELD1 VALUE1
+                HLEDGERFIELD2 VALUE2
+                ...
+
+              ; Comment line which explains MATCHERD
+              if MATCHERD
+                HLEDGERFIELD1 VALUE1
+                HLEDGERFIELD2 VALUE2
+                ...
+
+       Example:
+
+              if,account2,comment
+              atm transaction fee,expenses:business:banking,deductible? check it
+              %description groceries,expenses:groceries,
+              ;; Comment line that desribes why this particular date is special
+              2023/01/12.*Plumbing LLC,expenses:house:upkeep,emergency plumbing call-out
+
+   balance-type
+       Balance assertions generated by assigning to balanceN are of the simple
+       = type by default, which is  a  single-commodity,  subaccount-excluding
+       assertion.  You may find the subaccount-including variants more useful,
+       eg  if  you  have  created some virtual subaccounts of checking to help
+       with budgeting.  You can select a different type of assertion with  the
+       balance-type rule:
+
+              # balance assertions will consider all commodities and all subaccounts
+              balance-type ==*
+
+       Here are the balance assertion types for quick reference:
+
+              =    single commodity, exclude subaccounts
+              =*   single commodity, include subaccounts
+              ==   multi commodity,  exclude subaccounts
+              ==*  multi commodity,  include subaccounts
+
+   include
+              include RULESFILE
+
+       This  includes  the  contents  of another CSV rules file at this point.
+       RULESFILE is an absolute file path or a path relative  to  the  current
+       file's  directory.  This can be useful for sharing common rules between
+       several rules files, eg:
+
+              # someaccount.csv.rules
+
+              ## someaccount-specific rules
+              fields   date,description,amount
+              account1 assets:someaccount
+              account2 expenses:misc
+
+              ## common rules
+              include categorisation.rules
+
+   Working with CSV
+       Some tips:
+
+   Rapid feedback
+       It's a good idea to get rapid feedback  while  creating/troubleshooting
+       CSV rules.  Here's a good way, using entr from eradman.com/entrproject:
+
+              $ ls foo.csv* | entr bash -c 'echo ----; hledger -f foo.csv print desc:SOMEDESC'
+
+       A  desc:  query (eg) is used to select just one, or a few, transactions
+       of interest.  "bash -c" is used to run multiple  commands,  so  we  can
+       echo  a  separator  each  time the command re-runs, making it easier to
+       read the output.
+
+   Valid CSV
+       Note that hledger will only accept valid CSV conforming  to  RFC  4180,
+       and equivalent SSV and TSV formats (like RFC 4180 but with semicolon or
+       tab as separators).  This means, eg:
+
+       o Values may be enclosed in double quotes, or not.  Enclosing in single
+         quotes is not allowed.  (Eg 'A','B' is rejected.)
+
+       o When  values are enclosed in double quotes, spaces outside the quotes
+         are not allowed.  (Eg "A", "B" is rejected.)
+
+       o When values are not enclosed in quotes, they may not  contain  double
+         quotes.  (Eg A"A, B is rejected.)
+
+       If  your  CSV/SSV/TSV is not valid in this sense, you'll need to trans-
+       form it before reading with hledger.  Try using sed, or a more  permis-
+       sive CSV parser like python's csv lib.
+
+   File Extension
+       To  help  hledger  choose  the CSV file reader and show the right error
+       messages (and choose the right field separator character  by  default),
+       it's  best  if  CSV/SSV/TSV  files  are named with a .csv, .ssv or .tsv
+       filename extension.  (More about this at Data formats.)
+
+       When reading files with the "wrong" extension, you can ensure  the  CSV
+       reader  (and  the  default  field separator) by prefixing the file path
+       with csv:, ssv: or tsv:: Eg:
+
+              $ hledger -f ssv:foo.dat print
+
+       You can also override the default field separator with a separator rule
+       if needed.
+
+   Reading CSV from standard input
+       You'll need the file format prefix when reading CSV  from  stdin  also,
+       since hledger assumes journal format by default.  Eg:
+
+              $ cat foo.dat | hledger -f ssv:- print
+
+   Reading multiple CSV files
+       If  you  use  multiple  -f  options to read multiple CSV files at once,
+       hledger will look for a correspondingly-named rules file for  each  CSV
+       file.   But  if  you specify a rules file with --rules, that rules file
+       will be used for all the CSV files.
+
+   Reading files specified by rule
+       Instead of specifying a CSV file in the command line, you can specify a
+       rules file, as in hledger -f foo.csv.rules CMD.  By default  this  will
+       read  data from foo.csv in the same directory, but you can add a source
+       rule to specify a different data file,  perhaps  located  in  your  web
+       browser's download directory.
+
+       This feature was added in hledger 1.30, so you won't see it in most CSV
+       rules  examples.   But it helps remove some of the busywork of managing
+       CSV downloads.  Most of your financial institutions's default CSV file-
+       names are different and can be recognised by a glob  pattern.   So  you
+       can  put  a  rule like source Checking1*.csv in foo-checking.csv.rules,
+       and then periodically follow a workflow like:
+
+       1. Download CSV from Foo's website, using your browser's defaults
+
+       2. Run hledger import foo-checking.csv.rules to import any new transac-
+          tions
+
+       After import, you can: discard the CSV, or leave it where it is  for  a
+       while,  or  move it into your archives, as you prefer.  If you do noth-
+       ing, next time your browser will save something  like  Checking1-2.csv,
+       and  hledger will use that because of the * wild card and because it is
+       the most recent.
+
+   Valid transactions
+       After reading a CSV file, hledger post-processes and validates the gen-
+       erated journal entries as it would for a journal file - balancing them,
+       applying balance assignments, and canonicalising  amount  styles.   Any
+       errors  at this stage will be reported in the usual way, displaying the
+       problem entry.
+
+       There is one exception: balance assertions, if you have generated them,
+       will not be checked, since normally these will work only when  the  CSV
+       data  is part of the main journal.  If you do need to check balance as-
+       sertions generated from CSV right away, pipe into another hledger:
+
+              $ hledger -f file.csv print | hledger -f- print
+
+   Deduplicating, importing
+       When you download a CSV file periodically, eg to get your  latest  bank
+       transactions,  the  new  file  may overlap with the old one, containing
+       some of the same records.
+
+       The import command will (a) detect the new transactions, and (b) append
+       just those transactions to your main journal.  It is idempotent, so you
+       don't have to remember how many times you ran it or with which  version
+       of  the CSV.  (It keeps state in a hidden .latest.FILE.csv file.)  This
+       is the easiest way to import CSV data.  Eg:
+
+              # download the latest CSV files, then run this command.
+              # Note, no -f flags needed here.
+              $ hledger import *.csv [--dry]
+
+       This method works for most CSV files.  (Where  records  have  a  stable
+       chronological order, and new records appear only at the new end.)
+
+       A  number of other tools and workflows, hledger-specific and otherwise,
+       exist for converting, deduplicating, classifying and managing CSV data.
+       See:
+
+       o https://hledger.org/cookbook.html#setups-and-workflows
+
+       o https://plaintextaccounting.org -> data import/conversion
+
+   Setting amounts
+       Continuing from amount field above, here are more tips for  amount-set-
+       ting:
+
+       1. If the amount is in a single CSV field:
+           a. If its sign indicates direction of flow:
+           Assign  it  to amountN, to set the Nth posting's amount.  N is usu-
+           ally 1 or 2 but can go up to 99.
+
+           b. If another field indicates direction of flow:
+           Use one or more conditional rules to  set  the  appropriate  amount
+           sign.  Eg:
+
+                  # assume a withdrawal unless Type contains "deposit":
+                  amount1  -%Amount
+                  if %Type deposit
+                    amount1  %Amount
+
+       2. If  the amount is in two CSV fields (such as Debit and Credit, or In
+          and Out):
+           a. If both fields are unsigned:
+           Assign one field  to  amountN-in  and  the  other  to  amountN-out.
+           hledger  will  automatically  negate  the "out" field, and will use
+           whichever field value is non-zero as posting N's amount.
+
+           b. If either field is signed:
+           You will probably need to override hledger's sign for  one  or  the
+           other field, as in the following example:
+
+                  # Negate the -out value, but only if it is not empty:
+                  fields date, description, amount1-in, amount1-out
+                  if %amount1-out [1-9]
+                   amount1-out -%amount1-out
+
+           c. If  both  fields  can  contain  a non-zero value (or both can be
+              empty):
+           The  -in/-out  rules   normally   choose   the   value   which   is
+           non-zero/non-empty.   Some  value pairs can be ambiguous, such as 1
+           and none.  For such cases, use conditional rules to help select the
+           amount.  Eg, to handle the above you could select  the  value  con-
+           taining non-zero digits:
+
+                  fields date, description, in, out
+                  if %in [1-9]
+                   amount1 %in
+                  if %out [1-9]
+                   amount1 %out
+
+       3. If you want posting 2's amount converted to cost:
+       Use the unnumbered amount (or amount-in and amount-out) syntax.
+
+       4. If the CSV has only balance amounts, not transaction amounts:
+       Assign  to  balanceN,  to  set a balance assignment on the Nth posting,
+       causing the posting's amount to be calculated  automatically.   balance
+       with no number is equivalent to balance1.  In this situation hledger is
+       more likely to guess the wrong default account name, so you may need to
+       set that explicitly.
+
+   Amount signs
+       There is some special handling making it easier to parse and to reverse
+       amount signs.  (This only works for whole amounts, not for cost amounts
+       such as COST in amount1  AMT @ COST):
+
+       o If an amount value begins with a plus sign:
+       that will be removed: +AMT becomes AMT
+
+       o If an amount value is parenthesised:
+       it will be de-parenthesised and sign-flipped: (AMT) becomes -AMT
+
+       o If  an  amount value has two minus signs (or two sets of parentheses,
+         or a minus sign and parentheses):
+       they cancel out and will be removed: --AMT or -(AMT) becomes AMT
+
+       o If an amount value contains just a sign (or just a set  of  parenthe-
+         ses):
+       that  is removed, making it an empty value.  "+" or "-" or "()" becomes
+       "".
+
+       It's not possible (without preprocessing the CSV) to set an  amount  to
+       its absolute value, ie discard its sign.
+
+   Setting currency/commodity
+       If  the  currency/commodity  symbol  is  included  in  the CSV's amount
+       field(s):
+
+              2023-01-01,foo,$123.00
+
+       you don't have to do anything special for the commodity symbol, it will
+       be assigned as part of the amount.  Eg:
+
+              fields date,description,amount
+
+              2023-01-01 foo
+                  expenses:unknown         $123.00
+                  income:unknown          $-123.00
+
+       If the currency is provided as a separate CSV field:
+
+              2023-01-01,foo,USD,123.00
+
+       You can assign that to the currency pseudo-field, which has the special
+       effect of prepending itself to every amount in the transaction (on  the
+       left, with no separating space):
+
+              fields date,description,currency,amount
+
+              2023-01-01 foo
+                  expenses:unknown       USD123.00
+                  income:unknown        USD-123.00
+
+       Or,  you  can  use a field assignment to construct the amount yourself,
+       with more control.  Eg to put the symbol on the right, and separated by
+       a space:
+
+              fields date,description,cur,amt
+              amount %amt %cur
+
+              2023-01-01 foo
+                  expenses:unknown        123.00 USD
+                  income:unknown         -123.00 USD
+
+       Note we used a temporary field name (cur) that is not currency  -  that
+       would trigger the prepending effect, which we don't want here.
+
+   Amount decimal places
+       When  you  are  reading  CSV  data,  eg  with a command like hledger -f
+       foo.csv print, hledger will infer each  commodity's  decimal  precision
+       (and  other  commodity  display styles) from the amounts - much as when
+       reading a journal file without commodity directives (see the link).
+
+       Note, the commodity styles are not inferred from  the  numbers  in  the
+       original CSV data; rather, they are inferred from the amounts generated
+       by the CSV rules.
+
+       When you are importing CSV data with the import command, eg hledger im-
+       port  foo.csv,  there's  another step: import tries to make the new en-
+       tries conform to the journal's existing styles.  So for each  commodity
+       - let's say it's EUR - import will choose:
+
+       1. the style declared for EUR by a commodity directive in the journal
+
+       2. otherwise, the style inferred from EUR amounts in the journal
+
+       3. otherwise,  the style inferred from EUR amounts generated by the CSV
+          rules.
+
+       TLDR: if import is not generating the precisions or  styles  you  want,
+       add a commodity directive to specify them.
+
+   Referencing other fields
+       In  field assignments, you can interpolate only CSV fields, not hledger
+       fields.  In the example below, there's both a CSV field and  a  hledger
+       field  named  amount1, but %amount1 always means the CSV field, not the
+       hledger field:
+
+              # Name the third CSV field "amount1"
+              fields date,description,amount1
+
+              # Set hledger's amount1 to the CSV amount1 field followed by USD
+              amount1 %amount1 USD
+
+              # Set comment to the CSV amount1 (not the amount1 assigned above)
+              comment %amount1
+
+       Here, since there's no CSV amount1 field, %amount1 will produce a  lit-
+       eral "amount1":
+
+              fields date,description,csvamount
+              amount1 %csvamount USD
+              # Can't interpolate amount1 here
+              comment %amount1
+
+       When  there  are  multiple field assignments to the same hledger field,
+       only the last one takes effect.  Here, comment's value will be be B, or
+       C if "something" is matched, but never A:
+
+              comment A
+              comment B
+              if something
+               comment C
+
+   How CSV rules are evaluated
+       Here's how to think of CSV rules being evaluated (if  you  really  need
+       to).  First,
+
+       o include  - all includes are inlined, from top to bottom, depth first.
+         (At each include point the file is inlined and  scanned  for  further
+         includes, recursively, before proceeding.)
+
+       Then  "global"  rules  are  evaluated, top to bottom.  If a rule is re-
+       peated, the last one wins:
+
+       o skip (at top level)
+
+       o date-format
+
+       o newest-first
+
+       o fields - names the CSV fields, optionally sets up initial assignments
+         to hledger fields
+
+       Then for each CSV record in turn:
+
+       o test all if blocks.  If any of them contain a end rule, skip all  re-
+         maining  CSV  records.  Otherwise if any of them contain a skip rule,
+         skip that many CSV records.   If  there  are  multiple  matched  skip
+         rules, the first one wins.
+
+       o collect  all field assignments at top level and in matched if blocks.
+         When there are multiple assignments for a field, keep only  the  last
+         one.
+
+       o compute  a value for each hledger field - either the one that was as-
+         signed to it (and interpolate the %CSVFIELD references), or a default
+
+       o generate a hledger transaction (journal entry) from these values.
+
+       This is all part of the CSV reader, one of several readers hledger  can
+       use  to parse input files.  When all files have been read successfully,
+       the transactions are passed as input to whichever hledger  command  the
+       user specified.
+
+   Well factored rules
+       Some  things  than  can help reduce duplication and complexity in rules
+       files:
+
+       o Extracting common rules usable with multiple CSV files  into  a  com-
+         mon.rules, and adding include common.rules to each CSV's rules file.
+
+       o Splitting if blocks into smaller if blocks, extracting the frequently
+         used parts.
+
+   CSV rules examples
+   Bank of Ireland
+       Here's  a  CSV with two amount fields (Debit and Credit), and a balance
+       field, which we can use to add balance assertions, which is not  neces-
+       sary but provides extra error checking:
+
+              Date,Details,Debit,Credit,Balance
+              07/12/2012,LODGMENT       529898,,10.0,131.21
+              07/12/2012,PAYMENT,5,,126
+
+              # bankofireland-checking.csv.rules
+
+              # skip the header line
+              skip
+
+              # name the csv fields, and assign some of them as journal entry fields
+              fields  date, description, amount-out, amount-in, balance
+
+              # We generate balance assertions by assigning to "balance"
+              # above, but you may sometimes need to remove these because:
+              #
+              # - the CSV balance differs from the true balance,
+              #   by up to 0.0000000000005 in my experience
+              #
+              # - it is sometimes calculated based on non-chronological ordering,
+              #   eg when multiple transactions clear on the same day
+
+              # date is in UK/Ireland format
+              date-format  %d/%m/%Y
+
+              # set the currency
+              currency  EUR
+
+              # set the base account for all txns
+              account1  assets:bank:boi:checking
+
+              $ hledger -f bankofireland-checking.csv print
+              2012-12-07 LODGMENT       529898
+                  assets:bank:boi:checking         EUR10.0 = EUR131.2
+                  income:unknown                  EUR-10.0
+
+              2012-12-07 PAYMENT
+                  assets:bank:boi:checking         EUR-5.0 = EUR126.0
+                  expenses:unknown                  EUR5.0
+
+       The  balance assertions don't raise an error above, because we're read-
+       ing directly from CSV, but they will be checked if  these  entries  are
+       imported into a journal file.
+
+   Coinbase
+       A  simple  example  with  some  CSV  from  Coinbase.  The spot price is
+       recorded using cost notation.  The  legacy  amount  field  name  conve-
+       niently sets amount 2 (posting 2's amount) to the total cost.
+
+              # Timestamp,Transaction Type,Asset,Quantity Transacted,Spot Price Currency,Spot Price at Transaction,Subtotal,Total (inclusive of fees and/or spread),Fees and/or Spread,Notes
+              # 2021-12-30T06:57:59Z,Receive,USDC,100,GBP,0.740000,"","","","Received 100.00 USDC from an external account"
+
+              # coinbase.csv.rules
+              skip         1
+              fields       Timestamp,Transaction_Type,Asset,Quantity_Transacted,Spot_Price_Currency,Spot_Price_at_Transaction,Subtotal,Total,Fees_Spread,Notes
+              date         %Timestamp
+              date-format  %Y-%m-%dT%T%Z
+              description  %Notes
+              account1     assets:coinbase:cc
+              amount       %Quantity_Transacted %Asset @ %Spot_Price_at_Transaction %Spot_Price_Currency
+
+              $ hledger print -f coinbase.csv
+              2021-12-30 Received 100.00 USDC from an external account
+                  assets:coinbase:cc    100 USDC @ 0.740000 GBP
+                  income:unknown                 -74.000000 GBP
+
+   Amazon
+       Here we convert amazon.com order history, and use an if block to gener-
+       ate  a third posting if there's a fee.  (In practice you'd probably get
+       this data from your bank instead, but it's an example.)
+
+              "Date","Type","To/From","Name","Status","Amount","Fees","Transaction ID"
+              "Jul 29, 2012","Payment","To","Foo.","Completed","$20.00","$0.00","16000000000000DGLNJPI1P9B8DKPVHL"
+              "Jul 30, 2012","Payment","To","Adapteva, Inc.","Completed","$25.00","$1.00","17LA58JSKRD4HDGLNJPI1P9B8DKPVHL"
+
+              # amazon-orders.csv.rules
+
+              # skip one header line
+              skip 1
+
+              # name the csv fields, and assign the transaction's date, amount and code.
+              # Avoided the "status" and "amount" hledger field names to prevent confusion.
+              fields date, _, toorfrom, name, amzstatus, amzamount, fees, code
+
+              # how to parse the date
+              date-format %b %-d, %Y
+
+              # combine two fields to make the description
+              description %toorfrom %name
+
+              # save the status as a tag
+              comment     status:%amzstatus
+
+              # set the base account for all transactions
+              account1    assets:amazon
+              # leave amount1 blank so it can balance the other(s).
+              # I'm assuming amzamount excludes the fees, don't remember
+
+              # set a generic account2
+              account2    expenses:misc
+              amount2     %amzamount
+              # and maybe refine it further:
+              #include categorisation.rules
+
+              # add a third posting for fees, but only if they are non-zero.
+              if %fees [1-9]
+               account3    expenses:fees
+               amount3     %fees
+
+              $ hledger -f amazon-orders.csv print
+              2012-07-29 (16000000000000DGLNJPI1P9B8DKPVHL) To Foo.  ; status:Completed
+                  assets:amazon
+                  expenses:misc          $20.00
+
+              2012-07-30 (17LA58JSKRD4HDGLNJPI1P9B8DKPVHL) To Adapteva, Inc.  ; status:Completed
+                  assets:amazon
+                  expenses:misc          $25.00
+                  expenses:fees           $1.00
+
+   Paypal
+       Here's a real-world rules file for (customised) Paypal CSV,  with  some
+       Paypal-specific rules, and a second rules file included:
+
+              "Date","Time","TimeZone","Name","Type","Status","Currency","Gross","Fee","Net","From Email Address","To Email Address","Transaction ID","Item Title","Item ID","Reference Txn ID","Receipt ID","Balance","Note"
+              "10/01/2019","03:46:20","PDT","Calm Radio","Subscription Payment","Completed","USD","-6.99","0.00","-6.99","simon@joyful.com","memberships@calmradio.com","60P57143A8206782E","MONTHLY - $1 for the first 2 Months: Me - Order 99309. Item total: $1.00 USD first 2 months, then $6.99 / Month","","I-R8YLY094FJYR","","-6.99",""
+              "10/01/2019","03:46:20","PDT","","Bank Deposit to PP Account ","Pending","USD","6.99","0.00","6.99","","simon@joyful.com","0TU1544T080463733","","","60P57143A8206782E","","0.00",""
+              "10/01/2019","08:57:01","PDT","Patreon","PreApproved Payment Bill User Payment","Completed","USD","-7.00","0.00","-7.00","simon@joyful.com","support@patreon.com","2722394R5F586712G","Patreon* Membership","","B-0PG93074E7M86381M","","-7.00",""
+              "10/01/2019","08:57:01","PDT","","Bank Deposit to PP Account ","Pending","USD","7.00","0.00","7.00","","simon@joyful.com","71854087RG994194F","Patreon* Membership","","2722394R5F586712G","","0.00",""
+              "10/19/2019","03:02:12","PDT","Wikimedia Foundation, Inc.","Subscription Payment","Completed","USD","-2.00","0.00","-2.00","simon@joyful.com","tle@wikimedia.org","K9U43044RY432050M","Monthly donation to the Wikimedia Foundation","","I-R5C3YUS3285L","","-2.00",""
+              "10/19/2019","03:02:12","PDT","","Bank Deposit to PP Account ","Pending","USD","2.00","0.00","2.00","","simon@joyful.com","3XJ107139A851061F","","","K9U43044RY432050M","","0.00",""
+              "10/22/2019","05:07:06","PDT","Noble Benefactor","Subscription Payment","Completed","USD","10.00","-0.59","9.41","noble@bene.fac.tor","simon@joyful.com","6L8L1662YP1334033","Joyful Systems","","I-KC9VBGY2GWDB","","9.41",""
+
+              # paypal-custom.csv.rules
+
+              # Tips:
+              # Export from Activity -> Statements -> Custom -> Activity download
+              # Suggested transaction type: "Balance affecting"
+              # Paypal's default fields in 2018 were:
+              # "Date","Time","TimeZone","Name","Type","Status","Currency","Gross","Fee","Net","From Email Address","To Email Address","Transaction ID","Shipping Address","Address Status","Item Title","Item ID","Shipping and Handling Amount","Insurance Amount","Sales Tax","Option 1 Name","Option 1 Value","Option 2 Name","Option 2 Value","Reference Txn ID","Invoice Number","Custom Number","Quantity","Receipt ID","Balance","Address Line 1","Address Line 2/District/Neighborhood","Town/City","State/Province/Region/County/Territory/Prefecture/Republic","Zip/Postal Code","Country","Contact Phone Number","Subject","Note","Country Code","Balance Impact"
+              # This rules file assumes the following more detailed fields, configured in "Customize report fields":
+              # "Date","Time","TimeZone","Name","Type","Status","Currency","Gross","Fee","Net","From Email Address","To Email Address","Transaction ID","Item Title","Item ID","Reference Txn ID","Receipt ID","Balance","Note"
+
+              fields date, time, timezone, description_, type, status_, currency, grossamount, feeamount, netamount, fromemail, toemail, code, itemtitle, itemid, referencetxnid, receiptid, balance, note
+
+              skip  1
+
+              date-format  %-m/%-d/%Y
+
+              # ignore some paypal events
+              if
+              In Progress
+              Temporary Hold
+              Update to
+               skip
+
+              # add more fields to the description
+              description %description_ %itemtitle
+
+              # save some other fields as tags
+              comment  itemid:%itemid, fromemail:%fromemail, toemail:%toemail, time:%time, type:%type, status:%status_
+
+              # convert to short currency symbols
+              if %currency USD
+               currency $
+              if %currency EUR
+               currency E
+              if %currency GBP
+               currency P
+
+              # generate postings
+
+              # the first posting will be the money leaving/entering my paypal account
+              # (negative means leaving my account, in all amount fields)
+              account1 assets:online:paypal
+              amount1  %netamount
+
+              # the second posting will be money sent to/received from other party
+              # (account2 is set below)
+              amount2  -%grossamount
+
+              # if there's a fee, add a third posting for the money taken by paypal.
+              if %feeamount [1-9]
+               account3 expenses:banking:paypal
+               amount3  -%feeamount
+               comment3 business:
+
+              # choose an account for the second posting
+
+              # override the default account names:
+              # if the amount is positive, it's income (a debit)
+              if %grossamount ^[^-]
+               account2 income:unknown
+              # if negative, it's an expense (a credit)
+              if %grossamount ^-
+               account2 expenses:unknown
+
+              # apply common rules for setting account2 & other tweaks
+              include common.rules
+
+              # apply some overrides specific to this csv
+
+              # Transfers from/to bank. These are usually marked Pending,
+              # which can be disregarded in this case.
+              if
+              Bank Account
+              Bank Deposit to PP Account
+               description %type for %referencetxnid %itemtitle
+               account2 assets:bank:wf:pchecking
+               account1 assets:online:paypal
+
+              # Currency conversions
+              if Currency Conversion
+               account2 equity:currency conversion
+
+              # common.rules
+
+              if
+              darcs
+              noble benefactor
+               account2 revenues:foss donations:darcshub
+               comment2 business:
+
+              if
+              Calm Radio
+               account2 expenses:online:apps
+
+              if
+              electronic frontier foundation
+              Patreon
+              wikimedia
+              Advent of Code
+               account2 expenses:dues
+
+              if Google
+               account2 expenses:online:apps
+               description google | music
+
+              $ hledger -f paypal-custom.csv  print
+              2019-10-01 (60P57143A8206782E) Calm Radio MONTHLY - $1 for the first 2 Months: Me - Order 99309. Item total: $1.00 USD first 2 months, then $6.99 / Month  ; itemid:, fromemail:simon@joyful.com, toemail:memberships@calmradio.com, time:03:46:20, type:Subscription Payment, status:Completed
+                  assets:online:paypal          $-6.99 = $-6.99
+                  expenses:online:apps           $6.99
+
+              2019-10-01 (0TU1544T080463733) Bank Deposit to PP Account for 60P57143A8206782E  ; itemid:, fromemail:, toemail:simon@joyful.com, time:03:46:20, type:Bank Deposit to PP Account, status:Pending
+                  assets:online:paypal               $6.99 = $0.00
+                  assets:bank:wf:pchecking          $-6.99
+
+              2019-10-01 (2722394R5F586712G) Patreon Patreon* Membership  ; itemid:, fromemail:simon@joyful.com, toemail:support@patreon.com, time:08:57:01, type:PreApproved Payment Bill User Payment, status:Completed
+                  assets:online:paypal          $-7.00 = $-7.00
+                  expenses:dues                  $7.00
+
+              2019-10-01 (71854087RG994194F) Bank Deposit to PP Account for 2722394R5F586712G Patreon* Membership  ; itemid:, fromemail:, toemail:simon@joyful.com, time:08:57:01, type:Bank Deposit to PP Account, status:Pending
+                  assets:online:paypal               $7.00 = $0.00
+                  assets:bank:wf:pchecking          $-7.00
+
+              2019-10-19 (K9U43044RY432050M) Wikimedia Foundation, Inc. Monthly donation to the Wikimedia Foundation  ; itemid:, fromemail:simon@joyful.com, toemail:tle@wikimedia.org, time:03:02:12, type:Subscription Payment, status:Completed
+                  assets:online:paypal             $-2.00 = $-2.00
+                  expenses:dues                     $2.00
+                  expenses:banking:paypal      ; business:
+
+              2019-10-19 (3XJ107139A851061F) Bank Deposit to PP Account for K9U43044RY432050M  ; itemid:, fromemail:, toemail:simon@joyful.com, time:03:02:12, type:Bank Deposit to PP Account, status:Pending
+                  assets:online:paypal               $2.00 = $0.00
+                  assets:bank:wf:pchecking          $-2.00
+
+              2019-10-22 (6L8L1662YP1334033) Noble Benefactor Joyful Systems  ; itemid:, fromemail:noble@bene.fac.tor, toemail:simon@joyful.com, time:05:07:06, type:Subscription Payment, status:Completed
+                  assets:online:paypal                       $9.41 = $9.41
+                  revenues:foss donations:darcshub         $-10.00  ; business:
+                  expenses:banking:paypal                    $0.59  ; business:
+
+Timeclock
+       The time logging format of timeclock.el, as read by hledger.
+
+       hledger  can read time logs in timeclock format.  As with Ledger, these
+       are (a  subset  of)  timeclock.el's  format,  containing  clock-in  and
+       clock-out  entries as in the example below.  The date is a simple date.
+       The time format is HH:MM[:SS][+-ZZZZ].  Seconds and  timezone  are  op-
+       tional.   The  timezone, if present, must be four digits and is ignored
+       (currently the time is always interpreted as a local time).  Lines  be-
+       ginning with # or ; or *, and blank lines, are ignored.
+
+              i 2015/03/30 09:00:00 some account  optional description after 2 spaces ; optional comment, tags:
+              o 2015/03/30 09:20:00
+              i 2015/03/31 22:21:45 another:account
+              o 2015/04/01 02:00:34
+
+       hledger  treats  each  clock-in/clock-out pair as a transaction posting
+       some number of hours to an account.  Or if the session spans more  than
+       one  day, it is split into several transactions, one for each day.  For
+       the above time log, hledger print generates these journal entries:
+
+              $ hledger -f t.timeclock print
+              2015-03-30 * optional description after 2 spaces   ; optional comment, tags:
+                  (some account)           0.33h
+
+              2015-03-31 * 22:21-23:59
+                  (another:account)           1.64h
+
+              2015-04-01 * 00:00-02:00
+                  (another:account)           2.01h
+
+       Here is a sample.timeclock to download and some queries to try:
+
+              $ hledger -f sample.timeclock balance                               # current time balances
+              $ hledger -f sample.timeclock register -p 2009/3                    # sessions in march 2009
+              $ hledger -f sample.timeclock register -p weekly --depth 1 --empty  # time summary by week
+
+       To generate time logs, ie to clock in and clock out, you could:
+
+       o use these shell aliases at the command line:
+
+                alias ti='echo i `date "+%Y-%m-%d %H:%M:%S"` $* >>$TIMELOG'
+                alias to='echo o `date "+%Y-%m-%d %H:%M:%S"` >>$TIMELOG'
+
+       o or Emacs's built-in timeclock.el, or the extended timeclock-x.el, and
+         perhaps the extras in ledgerutils.el
+
+       o or use the old ti and to scripts in the ledger 2.x repository.  These
+         rely on a "timeclock" executable which I think is just the  ledger  2
+         executable renamed.
+
+Timedot
+       timedot  format  is hledger's human-friendly time logging format.  Com-
+       pared to timeclock format, it is more convenient  for  quick,  approxi-
+       mate,  and  retroactive  time logging, and more human-readable (you can
+       see at a glance where time was spent).  A quick example:
+
+              2023-05-01
+              hom:errands          .... ....  ; two hours; the space is ignored
+              fos:hledger:timedot  ..         ; half an hour
+              per:admin:finance               ; no time spent yet
+
+       hledger reads this as a transaction on this day with three (unbalanced)
+       postings, where each dot represents "0.25".  No commodity symbol is as-
+       sumed, but we typically interpret it as hours.
+
+              $ hledger -f a.timedot print   # .timedot file extension (or timedot: prefix) is required
+              2023-05-01 *
+                  (hom:errands)                    2.00  ; two hours
+                  (fos:hledger:timedot)            0.50  ; half an hour
+                  (per:admin:finance)                 0
+
+       A timedot file contains a series of transactions (usually one per day).
+       Each begins with a simple date (Y-M-D, Y/M/D, or Y.M.D), optionally  be
+       followed on the same line by a transaction description, and/or a trans-
+       action comment following a semicolon.
+
+       After the date line are zero or more time postings, consisting of:
+
+       o An  account  name  -  any  hledger-style account name, optionally in-
+         dented.
+
+       o Two or more spaces - required if there is an amount  (as  in  journal
+         format).
+
+       o A timedot amount, which can be
+
+         o empty (representing zero)
+
+         o a  number,  optionally  followed by a unit s, m, h, d, w, mo, or y,
+           representing a precise number  of  seconds,  minutes,  hours,  days
+           weeks, months or years (hours is assumed by default), which will be
+           converted  to hours according to 60s = 1m, 60m = 1h, 24h = 1d, 7d =
+           1w, 30d = 1mo, 365d = 1y.
+
+         o one or more  dots  (period  characters),  each  representing  0.25.
+           These  are  the  dots  in "timedot".  Spaces are ignored and can be
+           used for grouping/alignment.
+
+         o Added in 1.32 one or more letters.  These are like  dots  but  they
+           also  generate  a  tag t: (short for "type") with the letter as its
+           value, and a separate posting for each of the  values.   This  pro-
+           vides  a  second  dimension  of categorisation, viewable in reports
+           with --pivot t.
+
+       o An optional comment following a semicolon  (a  hledger-style  posting
+         comment).
+
+       There  is some flexibility to help with keeping time log data and notes
+       in the same file:
+
+       o Blank lines and lines beginning with # or ; are ignored.
+
+       o After the first date line, lines which do not contain a double  space
+         are parsed as postings with zero amount.  (hledger's register reports
+         will show these if you add -E).
+
+       o Before  the first date line, lines beginning with * (eg org headings)
+         are ignored.  And from the first date line  onward,  Emacs  org  mode
+         heading prefixes at the start of lines (one or more *'s followed by a
+         space)  will  be  ignored.  This means the time log can also be a org
+         outline.
+
+       Timedot files don't support directives like journal files.  So a common
+       pattern is to have a main journal file (eg time.journal) that  contains
+       any  needed  directives,  and  then  includes the timedot file (include
+       time.timedot).
+
+   Timedot examples
+       Numbers:
+
+              2016/2/3
+              inc:client1   4
+              fos:hledger   3h
+              biz:research  60m
+
+       Dots:
+
+              # on this day, 6h was spent on client work, 1.5h on haskell FOSS work, etc.
+              2016/2/1
+              inc:client1   .... .... .... .... .... ....
+              fos:haskell   .... ..
+              biz:research  .
+
+              2016/2/2
+              inc:client1   .... ....
+              biz:research  .
+
+              $ hledger -f a.timedot print date:2016/2/2
+              2016-02-02 *
+                  (inc:client1)          2.00
+
+              2016-02-02 *
+                  (biz:research)          0.25
+
+              $ hledger -f a.timedot bal --daily --tree
+              Balance changes in 2016-02-01-2016-02-03:
+
+                          ||  2016-02-01d  2016-02-02d  2016-02-03d
+              ============++========================================
+               biz        ||         0.25         0.25         1.00
+                 research ||         0.25         0.25         1.00
+               fos        ||         1.50            0         3.00
+                 haskell  ||         1.50            0            0
+                 hledger  ||            0            0         3.00
+               inc        ||         6.00         2.00         4.00
+                 client1  ||         6.00         2.00         4.00
+              ------------++----------------------------------------
+                          ||         7.75         2.25         8.00
+
+       Letters:
+
+              # Activity types:
+              #  c cleanup/catchup/repair
+              #  e enhancement
+              #  s support
+              #  l learning/research
+
+              2023-11-01
+              work:adm  ccecces
+
+              $ hledger -f a.timedot print
+              2023-11-01
+                  (work:adm)  1     ; t:c
+                  (work:adm)  0.5   ; t:e
+                  (work:adm)  0.25  ; t:s
+
+              $ hledger -f a.timedot bal
+                              1.75  work:adm
+              --------------------
+                              1.75
+
+              $ hledger -f a.timedot bal --pivot t
+                              1.00  c
+                              0.50  e
+                              0.25  s
+              --------------------
+                              1.75
+
+       Org:
+
+              * 2023 Work Diary
+              ** Q1
+              *** 2023-02-29
+              **** DONE
+              0700 yoga
+              **** UNPLANNED
+              **** BEGUN
+              hom:chores
+               cleaning  ...
+               water plants
+                outdoor - one full watering can
+                indoor - light watering
+              **** TODO
+              adm:planning: trip
+              *** LATER
+
+       Using . as account name separator:
+
+              2016/2/4
+              fos.hledger.timedot  4h
+              fos.ledger           ..
+
+              $ hledger -f a.timedot --alias '/\./=:' bal -t
+                              4.50  fos
+                              4.00    hledger:timedot
+                              0.50    ledger
+              --------------------
+                              4.50
+
+PART 3: REPORTING CONCEPTS
+Time periods
+   Report start & end date
+       Most hledger reports will by default show the full time  period  repre-
+       sented  by  the  journal.   The  report start date will be the earliest
+       transaction or posting date, and the report end date will be the latest
+       transaction, posting, or market price date.
+
+       Often you will want to see a shorter period, such as the current month.
+       You can specify a start and/or end date with the -b/--begin,  -e/--end,
+       or  -p/--period  options,  or  a date: query argument, described below.
+       All of these accept the smart date syntax, also described below.
+
+       End dates are exclusive; specify the day after the last day you want to
+       see in the report.
+
+       When dates are specified by multiple options, the last (right-most) op-
+       tion wins.  And when date: queries and date options are  combined,  the
+       report period will be their intersection.
+
+       Examples:
+
+       -b 2016/3/17
+              beginning on St.  Patrick's day 2016
+
+       -e 12/1
+              ending at the start of December 1st in the current year
+
+       -p 'this month'
+              during the current month
+
+       -p thismonth
+              same as above, spaces are optional
+
+       -b 2023
+              beginning on the first day of 2023
+
+       date:2023.. or date:2023-
+              same as above
+
+       -b 2024 -e 2025 -p '2000 to 2030' date:2020-01 date:2020 :
+       during January 2020 (the smallest common period, with the -p overriding
+       -b and -e)
+
+   Smart dates
+       In  hledger's user interfaces (though not in the journal file), you can
+       optionally use "smart date" syntax.  Smart dates can  be  written  with
+       english  words,  can  be relative, and can have parts omitted.  Missing
+       parts are inferred as 1, when needed.  Smart dates can  be  interpreted
+       as dates or periods depending on context.
+
+       Examples:
+
+       2004-01-01, 2004/10/1, 2004.9.1, 20240504 :
+       Exact  dates.   The year must have at least four digits, the month must
+       be 1-12, the day must be 1-31, the separator can be -  or  /  or  .  or
+       nothing.
+
+       2004-10
+              start of month
+
+       2004   start of year
+
+       10/1 or oct or october
+              October 1st in current year
+
+       21     21st day in current month
+
+       yesterday, today, tomorrow
+              -1, 0, 1 days from today
+
+       last/this/next day/week/month/quarter/year
+              -1, 0, 1 periods from the current period
+
+       in n days/weeks/months/quarters/years
+              n periods from the current period
+
+       n days/weeks/months/quarters/years ahead
+              n periods from the current period
+
+       n days/weeks/months/quarters/years ago
+              -n periods from the current period
+
+       20181201
+              8 digit YYYYMMDD with valid year month and day
+
+       201812 6 digit YYYYMM with valid year and month
+
+       Dates  with no separators are allowed but might give surprising results
+       if mistyped:
+
+       o 20181301 (YYYYMMDD with an invalid month) is parsed as an eight-digit
+         year
+
+       o 20181232 (YYYYMMDD with an invalid day) gives a parse error
+
+       o 201801012 (a valid YYYYMMDD followed by additional  digits)  gives  a
+         parse error
+
+       The  meaning of relative dates depends on today's date.  If you need to
+       test or reproduce old reports, you can use the --today option to  over-
+       ride  that.   (Except for periodic transaction rules, which are not af-
+       fected by --today.)
+
+   Report intervals
+       A report interval can be specified so that reports like register,  bal-
+       ance or activity become multi-period, showing each subperiod as a sepa-
+       rate row or column.
+
+       The  following  standard  intervals  can  be  enabled with command-line
+       flags:
+
+       o -D/--daily
+
+       o -W/--weekly
+
+       o -M/--monthly
+
+       o -Q/--quarterly
+
+       o -Y/--yearly
+
+       More complex intervals can be specified  using  -p/--period,  described
+       below.
+
+   Date adjustments
+   Start date adjustment
+       If you let hledger infer a report's start date, it will adjust the date
+       to the previous natural boundary of the report interval, for convenient
+       periodic reports.  (If you don't want that, specify a start date.)
+
+       For example, if the journal's first transaction is on january 10th,
+
+       o hledger  register (no report interval) will start the report on janu-
+         ary 10th.
+
+       o hledger register --monthly will start  the  report  on  the  previous
+         month boundary, january 1st.
+
+       o hledger register --monthly --begin 1/5 will start the report on janu-
+         ary 5th [1].
+
+       Also  if  you are generating transactions or budget goals with periodic
+       transaction rules, their start date may be adjusted in  a  similar  way
+       (in certain situations).
+
+   End date adjustment
+       A report's end date is always adjusted to include a whole number of in-
+       tervals, so that the last subperiod has the same length as the others.
+
+       For example, if the journal's last transaction is on february 20th,
+
+       o hledger register will end the report on february 20th.
+
+       o hledger  register  --monthly will end the report at the end of febru-
+         ary.
+
+       o hledger register --monthly --end 2/14 also will end the report at the
+         end of february.
+
+       o hledger register --monthly --begin 1/5 --end 2/14 will end the report
+         on march 4th [1].
+
+       [1] Since hledger 1.29.
+
+   Period headings
+       With non-standard subperiods, hledger  will  show  "STARTDATE..ENDDATE"
+       headings.  With standard subperiods (ie, starting on a natural interval
+       boundary),  you'll see more compact headings, which are usually prefer-
+       able.  (Though month names will be in english, currently.)
+
+       So if you are specifying a start date and you  want  compact  headings:
+       choose a start of year for yearly reports, a start of quarter for quar-
+       terly  reports,  a start of month for monthly reports, etc.  (Remember,
+       you can write eg -b 2024 or 1/1 as a shortcut for a start of  year,  or
+       2024-04 or 202404 or Apr for a start of month or quarter.)
+
+       For  weekly  reports, choose a date that's a Monday.  (You can try dif-
+       ferent dates until you see the short headings, or write eg -b '3  weeks
+       ago'.)
+
+   Period expressions
+       The  -p/--period  option specifies a period expression, which is a com-
+       pact way of expressing a start date, end date, and/or report interval.
+
+       Here's a period expression with a start and end  date  (specifying  the
+       first quarter of 2009):
+
+       -p "from 2009/1/1 to 2009/4/1"
+
+       Several  keywords  like  "from" and "to" are supported for readability;
+       these are optional.  "to" can also be written  as  ".."  or  "-".   The
+       spaces  are also optional, as long as you don't run two dates together.
+       So the following are equivalent to the above:
+
+       -p "2009/1/1 2009/4/1"
+       -p2009/1/1to2009/4/1
+       -p2009/1/1..2009/4/1
+
+       Dates are smart dates, so if the current year is 2009, these  are  also
+       equivalent to the above:
+
+       -p "1/1 4/1"
+       -p "jan-apr"
+       -p "this year to 4/1"
+
+       If you specify only one date, the missing start or end date will be the
+       earliest or latest transaction date in the journal:
+
+       -p "from 2009/1/1"   everything  after  january
+                            1, 2009
+       -p "since 2009/1"    the same, since is a  syn-
+                            onym
+       -p "from 2009"       the same
+       -p "to 2009"         everything  before january
+                            1, 2009
+
+       You can also specify a period by writing a single partial or full date:
+
+       -p "2009"        the year 2009; equivalent to "2009/1/1 to 2010/1/1"
+       -p "2009/1"      the month of january 2009; equivalent to  "2009/1/1  to
+                        2009/2/1"
+       -p "2009/1/1"    the  first  day  of  2009;  equivalent  to "2009/1/1 to
+                        2009/1/2"
+
+       or by using the "Q" quarter-year syntax (case insensitive):
+
+       -p "2009Q1"       first quarter  of  2009,  equivalent  to  "2009/1/1  to
+                         2009/4/1"
+       -p "q4"           fourth quarter of the current year
+
+   Period expressions with a report interval
+       A  period  expression  can also begin with a report interval, separated
+       from the start/end dates (if any) by a space or the word in:
+
+       -p "weekly from 2009/1/1 to 2009/4/1"
+       -p "monthly in 2008"
+       -p "quarterly"
+
+   More complex report intervals
+       Some more complex intervals can be specified within period expressions,
+       such as:
+
+       o biweekly (every two weeks)
+
+       o fortnightly
+
+       o bimonthly (every two months)
+
+       o every day|week|month|quarter|year
+
+       o every N days|weeks|months|quarters|years
+
+       Weekly on a custom day:
+
+       o every Nth day of week (th, nd, rd, or st are all accepted  after  the
+         number)
+
+       o every  WEEKDAYNAME  (full  or three-letter english weekday name, case
+         insensitive)
+
+       Monthly on a custom day:
+
+       o every Nth day [of month] (31st day will be adjusted to  each  month's
+         last day)
+
+       o every Nth WEEKDAYNAME [of month]
+
+       Yearly on a custom month and day:
+
+       o every MM/DD [of year] (month number and day of month number)
+
+       o every  MONTHNAME  DDth  [of year] (full or three-letter english month
+         name, case insensitive, and day of month number)
+
+       o every DDth MONTHNAME [of year] (equivalent to the above)
+
+       Examples:
+
+       -p "bimonthly from 2008"
+       -p "every 2 weeks"
+       -p  "every  5  months  from
+       2009/03"
+       -p "every 2nd day of week"    periods will go from Tue to Tue
+       -p "every Tue"                same
+       -p "every 15th day"           period  boundaries  will be on 15th of each
+                                     month
+       -p "every 2nd Monday"         period boundaries will be on second  Monday
+                                     of each month
+       -p "every 11/05"              yearly  periods  with  boundaries on 5th of
+                                     November
+       -p "every 5th November"       same
+       -p "every Nov 5th"            same
+
+       Show historical balances at end of the 15th day of each month (N is  an
+       end date, exclusive as always):
+
+              $ hledger balance -H -p "every 16th day"
+
+       Group  postings  from  the  start  of wednesday to end of the following
+       tuesday (N is both (inclusive) start date and (exclusive) end date):
+
+              $ hledger register checking -p "every 3rd day of week"
+
+   Multiple weekday intervals
+       This special form is also supported:
+
+       o every WEEKDAYNAME,WEEKDAYNAME,... (full or three-letter english week-
+         day names, case insensitive)
+
+       Also, weekday and weekendday are shorthand for mon,tue,wed,thu,fri  and
+       sat,sun.
+
+       This  is  mainly intended for use with --forecast, to generate periodic
+       transactions on arbitrary days of the week.  It may be less useful with
+       -p, since it divides each week into subperiods of unequal length, which
+       is unusual.  (Related: #1632)
+
+       Examples:
+
+       -p          "every   dates  will  be  Mon,  Wed,  Fri;  periods  will  be
+       mon,wed,fri"         Mon-Tue, Wed-Thu, Fri-Sun
+       -p "every weekday"   dates will be Mon, Tue, Wed, Thu, Fri; periods  will
+                            be Mon, Tue, Wed, Thu, Fri-Sun
+       -p "every weekend-   dates will be Sat, Sun; periods will be Sat, Sun-Fri
+       day"
+
+Depth
+       With  the  --depth NUM option (short form: -NUM), reports will show ac-
+       counts only to the specified depth,  hiding  deeper  subaccounts.   Use
+       this  when you want a summary with less detail.  This flag has the same
+       effect as a depth: query argument: depth:2, --depth=2 or -2 are equiva-
+       lent.
+
+       In place of a single number which limits the depth  for  all  accounts,
+       you can also provide separate depth limits for different accounts using
+       regular expressions (since 1.41).
+
+       For  example,  --depth assets=2 (or, equivalently: depth:assets=2) will
+       collapse accounts matching the regular expression assets  to  depth  2.
+       So assets:bank:savings would be collapsed to assets:bank, while liabil-
+       ities:bank:credit  card  would  not  be affected.  This can be combined
+       with a flat depth to collapse other accounts not matching  the  regular
+       expression,   so   --depth   assets=2  --depth  1  would  collapse  as-
+       sets:bank:savings to assets:bank and  liabilities:bank:credit  card  to
+       liabilities.
+
+       You  can  supply multiple depth arguments and they will all be applied,
+       so --depth assets=2 --depth liabilities=3 --depth 1 would collapse:
+
+       o accounts matching assets to depth 2,
+
+       o accounts matching liabilities to depth 3,
+
+       o all other accounts to depth 1.
+
+       If an account is matched by more than one regular expression depth  ar-
+       gument  then  the more specific one will used.  For example, if --depth
+       assets=1  --depth   assets:bank:savings=2   is   provided,   then   as-
+       sets:bank:savings  will  be  collapsed  to depth 2 rather than depth 1.
+       This is because assets:bank:savings matches at level 3 in  the  account
+       name, while assets matches at level 1.  The same would be true with the
+       argument --depth assets=1 --depth savings=2.
+
+Queries
+       One of hledger's strengths is being able to quickly report on a precise
+       subset  of your data.  Most hledger commands accept query arguments, to
+       restrict their scope.  Multiple query terms can be provided to build up
+       a more complex query.
+
+       o By default, a query term is interpreted as  a  case-insensitive  sub-
+         string pattern for matching account names:
+
+         car:fuel
+         dining groceries
+       o Patterns  containing  spaces  or other special characters must be en-
+         closed in single or double quotes:
+
+         'personal care'
+       o These patterns are actually regular expressions, so you can add  reg-
+         exp  metacharacters  for  more  precision  (see "Regular expressions"
+         above for details):
+
+         '^expenses\b'
+         'food$'
+         'fuel|repair'
+         'accounts (payable|receivable)'
+       o To match something other than account name, add one of the query type
+         prefixes described in "Query types" below:
+
+         date:202312-
+         status:
+         desc:amazon
+         cur:USD
+         cur:\\$
+         amt:'>0'
+       o Add a not: prefix to negate a term:
+
+         not:status:'*'
+         not:desc:'opening|closing'
+         not:cur:USD
+       o Terms with different types are AND-ed, terms with the same  type  are
+         OR-ed  (mostly;  see  "Combining  query terms" below).  The following
+         query:
+
+         date:2022 desc:amazon desc:amzn
+
+         is interpreted as:
+
+         date is in 2022 AND ( transaction description  contains  "amazon"  OR
+         "amzn" )
+
+   Query types
+       Here are the types of query term available.
+
+   acct: query
+       acct:REGEX, or just REGEX
+       Match  account  names  containing this case insensitive regular expres-
+       sion.
+       This is the default query type, so we usually don't bother writing  the
+       "acct:" prefix.
+
+   amt: query
+       amt:N, amt:'<N', amt:'<=N', amt:'>N', amt:'>=N'
+       Match  postings  with a single-commodity amount equal to, less than, or
+       greater than N. (Postings with multi-commodity amounts are  not  tested
+       and will always match.)  The comparison has two modes: if N is preceded
+       by  a + or - sign (or is 0), the two signed numbers are compared.  Oth-
+       erwise, the absolute magnitudes  are  compared,  ignoring  sign.   amt:
+       needs  quotes  to hide the less than/greater than sign from the command
+       line shell.
+
+   code: query
+       code:REGEX
+       Match by transaction code (eg check number).
+
+   cur: query
+       cur:REGEX
+       Match  postings  or  transactions  including  any  amounts  whose  cur-
+       rency/commodity  symbol  is  fully  matched  by  REGEX.   (Contrary  to
+       hledger's  usual  infix  matching.   To  do   infix   matching,   write
+       .*REGEX.*.)  Note, to match special characters which are regex-signifi-
+       cant,  you  need  to  escape them with \.  And for characters which are
+       significant to your shell you will usually need one more level  of  es-
+       caping.  Eg to match the dollar sign: cur:\\$ or cur:'\$'
+
+   desc: query
+       desc:REGEX
+       Match transaction descriptions.
+
+   date: query
+       date:PERIODEXPR
+       Match  dates  (or  with  the  --date2 flag, secondary dates) within the
+       specified period.  PERIODEXPR is a period expression with no report in-
+       terval.  Examples:
+       date:2016, date:thismonth, date:2/1-2/15, date:2021-07-27..nextquarter.
+
+   date2: query
+       date2:PERIODEXPR
+       If you use secondary dates: this matches  secondary  dates  within  the
+       specified period.  It is not affected by the --date2 flag.
+
+   depth: query
+       depth:[REGEXP=]N
+       Match  (or  display,  depending  on  command) accounts at or above this
+       depth, optionally only for accounts matching a provided regular expres-
+       sion.  See Depth for detailed rules.
+
+   expr: query
+       expr:'QUERYEXPR'
+       expr lets you write more complicated query expressions  with  AND,  OR,
+       NOT, and parentheses.
+       Eg: expr:'date:lastmonth and not (food or rent)'
+       The expression should be enclosed in quotes.  See Combining query terms
+       below.
+
+   not: query
+       not:QUERYTERM
+       You can prepend not: to any other query term to negate the match.
+       Eg: not:equity, not:desc:apple
+       (Also,  a  trick: not:not:... can sometimes solve query problems conve-
+       niently..)
+
+   note: query
+       note:REGEX
+       Match transaction notes (the part of the description right of |, or the
+       whole description if there's no |).
+
+   payee: query
+       payee:REGEX
+       Match transaction payee/payer names (the part of the  description  left
+       of |, or the whole description if there's no |).
+
+   real: query
+       real:, real:0
+       Match real or virtual postings respectively.
+
+   status: query
+       status:, status:!, status:*
+       Match unmarked, pending, or cleared transactions respectively.
+
+   type: query
+       type:TYPECODES
+       Match  by account type (see Declaring accounts > Account types).  TYPE-
+       CODES is one or more of the single-letter account type  codes  ALERXCV,
+       case insensitive.  Note type:A and type:E will also match their respec-
+       tive  subtypes  C  (Cash) and V (Conversion).  Certain kinds of account
+       alias can disrupt account types, see Rewriting accounts >  Aliases  and
+       account types.
+
+   tag: query
+       tag:NAMEREGEX[=VALREGEX]
+       Match by tag name, and optionally also by tag value.  Note:
+
+       o Both  regular  expressions do infix matching.  If you need a complete
+         match, use ^ and $.
+       Eg: tag:'^fullname$', tag:'^fullname$=^fullvalue$
+
+       o To match values, ignoring names, do tag:.=VALREGEX
+
+       o Accounts also inherit the tags of their parent accounts.
+
+       o Postings also inherit the tags of their account and their transaction
+         .
+
+       o Transactions also acquire the tags of their postings.
+
+   Combining query terms
+       When given multiple space-separated query terms, most  commands  select
+       things which match:
+
+       o any of the description terms AND
+
+       o any of the account terms AND
+
+       o any of the status terms AND
+
+       o all the other terms.
+
+       The print command is a little different, showing transactions which:
+
+       o match any of the description terms AND
+
+       o have any postings matching any of the positive account terms AND
+
+       o have no postings matching any of the negative account terms AND
+
+       o match all the other terms.
+
+       We  also  support  more  complex boolean queries with the expr: prefix.
+       This allows one to combine query terms  using  and,  or,  not  keywords
+       (case insensitive), and to group them by enclosing in parentheses.
+
+       Some examples:
+
+       o Exclude account names containing 'food':
+
+         expr:"not food" (not:food is equivalent)
+
+       o Match things which have 'cool' in the description and the 'A' tag:
+
+         expr:"desc:cool and tag:A" (expr:"desc:cool tag:A" is equivalent)
+
+       o Match  things  which  either do not reference the 'expenses:food' ac-
+         count, or do have the 'A' tag:
+
+         expr:"not expenses:food or tag:A"
+
+       o Match things which either do not reference  the  'expenses:food'  ac-
+         count,  or which reference the 'expenses:drink' account and also have
+         the 'A' tag:
+
+         expr:"expenses:food or (expenses:drink and tag:A)"
+
+       expr: has a restriction: date: queries may not be used  inside  or  ex-
+       pressions.  That would allow disjoint report periods or disjoint result
+       sets, with unclear semantics for our reports.
+
+   Queries and command options
+       Some  queries can also be expressed as command-line options: depth:2 is
+       equivalent to --depth 2, date:2023 is equivalent to -p 2023, etc.  When
+       you mix command options and query arguments,  generally  the  resulting
+       query is their intersection.
+
+   Queries and account aliases
+       When  account  names  are  rewritten  with --alias or alias, acct: will
+       match either the old or the new account name.
+
+   Queries and valuation
+       When amounts are converted to other commodities in cost  or  value  re-
+       ports,  cur: and amt: match the old commodity symbol and the old amount
+       quantity, not the new ones.  (Except in hledger 1.22, #1625.)
+
+Pivoting
+       Normally, hledger groups amounts and displays their totals  by  account
+       (name).   With  --pivot  PIVOTEXPR,  some  other  field's  (or multiple
+       fields') value is used as a synthetic account name,  causing  different
+       grouping and display.  PIVOTEXPR can be
+
+       o any  of  these standard transaction or posting fields (their value is
+         substituted): status, code, desc, payee, note, acct,  comm/cur,  amt,
+         cost
+
+       o or a tag name
+
+       o or any combination of these, colon-separated.
+
+       Some special cases:
+
+       o Colons appearing in PIVOTEXPR or in a pivoted tag value will generate
+         account hierarchy.
+
+       o When  pivoting  a  posting has multiple values for a tag, the pivoted
+         value of that tag will be the first value.
+
+       o When a  posting  has  multiple  commodities,  the  pivoted  value  of
+         "comm"/"cur" will be "".  Also when an unrecognised tag name or field
+         is provided, its pivoted value will be "".  (If this causes confusing
+         output, consider excluding those postings from the report.)
+
+       Examples:
+
+              2016/02/16 Yearly Dues Payment
+                  assets:bank account                 2 EUR
+                  income:dues                        -2 EUR  ; member: John Doe, kind: Lifetime
+
+       Normal balance report showing account names:
+
+              $ hledger balance
+                             2 EUR  assets:bank account
+                            -2 EUR  income:dues
+              --------------------
+                                 0
+
+       Pivoted balance report, using member: tag values instead:
+
+              $ hledger balance --pivot member
+                             2 EUR
+                            -2 EUR  John Doe
+              --------------------
+                                 0
+
+       One way to show only amounts with a member: value (using a query):
+
+              $ hledger balance --pivot member tag:member=.
+                            -2 EUR  John Doe
+              --------------------
+                            -2 EUR
+
+       Another  way  (the  acct:  query  matches  against the pivoted "account
+       name"):
+
+              $ hledger balance --pivot member acct:.
+                            -2 EUR  John Doe
+              --------------------
+                            -2 EUR
+
+       Hierarchical reports can be generated with multiple pivot values:
+
+              $ hledger balance Income:Dues --pivot kind:member
+                            -2 EUR  Lifetime:John Doe
+              --------------------
+                            -2 EUR
+
+Generating data
+       hledger can enrich the data provided to it, or generate new data, in  a
+       number of ways.  Mostly, this is done only if you request it:
+
+       o Missing  amounts  or missing costs in transactions are inferred auto-
+         matically when possible.
+
+       o The --infer-equity flag infers  missing  conversion  equity  postings
+         from @/@@ costs.
+
+       o The  --infer-costs  flag  infers missing costs from conversion equity
+         postings.
+
+       o The --infer-market-prices flag infers P price directives from costs.
+
+       o The --auto flag adds extra postings to transactions matched  by  auto
+         posting rules.
+
+       o The  --forecast  option generates transactions from periodic transac-
+         tion rules.
+
+       o The balance --budget report infers budget goals from periodic  trans-
+         action rules.
+
+       o Commands  like close, rewrite, and hledger-interest generate transac-
+         tions or postings.
+
+       o CSV data is converted to  transactions  by  applying  CSV  conversion
+         rules..  etc.
+
+       Such  generated  data  is temporary, existing only at report time.  You
+       can convert it to permanent recorded data by, eg, capturing the  output
+       of  hledger  print  and saving it in your journal file.  This can some-
+       times be useful as a data entry aid.
+
+       If you are curious what data is being generated and  why,  run  hledger
+       print  -x  --verbose-tags.   -x/--explicit  shows  inferred amounts and
+       --verbose-tags adds  tags  like  generated-transaction  (from  periodic
+       rules) and generated-posting, modified (from auto posting rules).  Sim-
+       ilar  hidden tags (with an underscore prefix) are always present, also,
+       so you can always match such data with queries  like  tag:generated  or
+       tag:modified.
+
+Forecasting
+       Forecasting,  or  speculative future reporting, can be useful for esti-
+       mating future balances, or for exploring different future scenarios.
+
+       The simplest and most flexible way to do it with hledger is to manually
+       record a bunch of future-dated transactions.  You could keep these in a
+       separate future.journal and include that with -f only when you want  to
+       see them.
+
+   --forecast
+       There  is another way: with the --forecast option, hledger can generate
+       temporary "forecast transactions" for reporting purposes, according  to
+       periodic  transaction rules defined in the journal.  Each rule can gen-
+       erate multiple recurring transactions, so by changing one rule you  can
+       change many forecasted transactions.
+
+       Forecast  transactions  usually  start after ordinary transactions end.
+       By default, they begin after your latest-dated ordinary transaction, or
+       today, whichever is later, and they end six months  from  today.   (The
+       exact rules are a little more complicated, and are given below.)
+
+       This is the "forecast period", which need not be the same as the report
+       period.   You can override it - eg to forecast farther into the future,
+       or to force forecast transactions to overlap your ordinary transactions
+       - by giving the --forecast option a period  expression  argument,  like
+       --forecast=..2099  or  --forecast=2023-02-15...  Note that the = is re-
+       quired.
+
+   Inspecting forecast transactions
+       print is the best command for inspecting and  troubleshooting  forecast
+       transactions.  Eg:
+
+              ~ monthly from 2022-12-20    rent
+                  assets:bank:checking
+                  expenses:rent           $1000
+
+              $ hledger print --forecast --today=2023/4/21
+              2023-05-20 rent
+                  ; generated-transaction: ~ monthly from 2022-12-20
+                  assets:bank:checking
+                  expenses:rent                  $1000
+
+              2023-06-20 rent
+                  ; generated-transaction: ~ monthly from 2022-12-20
+                  assets:bank:checking
+                  expenses:rent                  $1000
+
+              2023-07-20 rent
+                  ; generated-transaction: ~ monthly from 2022-12-20
+                  assets:bank:checking
+                  expenses:rent                  $1000
+
+              2023-08-20 rent
+                  ; generated-transaction: ~ monthly from 2022-12-20
+                  assets:bank:checking
+                  expenses:rent                  $1000
+
+              2023-09-20 rent
+                  ; generated-transaction: ~ monthly from 2022-12-20
+                  assets:bank:checking
+                  expenses:rent                  $1000
+
+       Here there are no ordinary transactions, so the forecasted transactions
+       begin  on the first occurrence after today's date.  (You won't normally
+       use --today; it's just to make these examples reproducible.)
+
+   Forecast reports
+       Forecast transactions affect all reports, as you would expect.  Eg:
+
+              $ hledger areg rent --forecast --today=2023/4/21
+              Transactions in expenses:rent and subaccounts:
+              2023-05-20 rent                 as:ba:checking               $1000         $1000
+              2023-06-20 rent                 as:ba:checking               $1000         $2000
+              2023-07-20 rent                 as:ba:checking               $1000         $3000
+              2023-08-20 rent                 as:ba:checking               $1000         $4000
+              2023-09-20 rent                 as:ba:checking               $1000         $5000
+
+              $ hledger bal -M expenses --forecast --today=2023/4/21
+              Balance changes in 2023-05-01..2023-09-30:
+
+                             ||   May    Jun    Jul    Aug    Sep
+              ===============++===================================
+               expenses:rent || $1000  $1000  $1000  $1000  $1000
+              ---------------++-----------------------------------
+                             || $1000  $1000  $1000  $1000  $1000
+
+   Forecast tags
+       Forecast transactions generated by --forecast have a hidden tag,  _gen-
+       erated-transaction.   So  if  you  ever need to match forecast transac-
+       tions, you could use tag:_generated-transaction (or just tag:generated)
+       in a query.
+
+       For troubleshooting, you can add the --verbose-tags flag.  Then,  visi-
+       ble generated-transaction tags will be added also, so you can view them
+       with  the print command.  Their value indicates which periodic rule was
+       responsible.
+
+   Forecast period, in detail
+       Forecast start/end dates are chosen so as to do something useful by de-
+       fault in almost all situations, while also being  flexible.   Here  are
+       (with luck) the exact rules, to help with troubleshooting:
+
+       The forecast period starts on:
+
+       o the later of
+
+         o the start date in the periodic transaction rule
+
+         o the start date in --forecast's argument
+
+       o otherwise (if those are not available): the later of
+
+         o the report start date specified with -b/-p/date:
+
+         o the day after the latest ordinary transaction in the journal
+
+       o otherwise (if none of these are available): today.
+
+       The forecast period ends on:
+
+       o the earlier of
+
+         o the end date in the periodic transaction rule
+
+         o the end date in --forecast's argument
+
+       o otherwise: the report end date specified with -e/-p/date:
+
+       o otherwise: 180 days (~6 months) from today.
+
+   Forecast troubleshooting
+       When  --forecast is not doing what you expect, one of these tips should
+       help:
+
+       o Remember to use the --forecast option.
+
+       o Remember to have at least one periodic transaction rule in your jour-
+         nal.
+
+       o Test with print --forecast.
+
+       o Check for typos or too-restrictive start/end dates in  your  periodic
+         transaction rule.
+
+       o Leave  at least 2 spaces between the rule's period expression and de-
+         scription fields.
+
+       o Check for future-dated ordinary transactions  suppressing  forecasted
+         transactions.
+
+       o Try setting explicit report start and/or end dates with -b, -e, -p or
+         date:
+
+       o Try  adding  the  -E  flag to encourage display of empty periods/zero
+         transactions.
+
+       o Try setting explicit forecast start and/or  end  dates  with  --fore-
+         cast=START..END
+
+       o Consult Forecast period, in detail, above.
+
+       o Check inside the engine: add --debug=2 (eg).
+
+Budgeting
+       With  the  balance command's --budget report, each periodic transaction
+       rule generates recurring budget goals in specified accounts, and  goals
+       and  actual performance can be compared.  See the balance command's doc
+       below.
+
+       You can generate budget goals and forecast  transactions  at  the  same
+       time,  from  the  same or different periodic transaction rules: hledger
+       bal -M --budget --forecast ...
+
+       See also: Budgeting and Forecasting.
+
+Amount formatting
+   Commodity display style
+       For the amounts in each commodity, hledger chooses a consistent display
+       style (symbol placement, decimal mark and digit group marks, number  of
+       decimal digits) to use in most reports.  This is inferred as follows:
+
+       First,  if  there's  a  D directive declaring a default commodity, that
+       commodity symbol and amount format is applied to all no-symbol  amounts
+       in the journal.
+
+       Then  each  commodity's  display style is determined from its commodity
+       directive.  We recommend always declaring  commodities  with  commodity
+       directives, since they help ensure consistent display styles and preci-
+       sions,  and  bring  other benefits such as error checking for commodity
+       symbols.  Here's an example:
+
+              # Set display styles (and decimal marks, for parsing, if there is no decimal-mark directive)
+              # for the $, EUR, INR and no-symbol commodities:
+              commodity $1,000.00
+              commodity EUR 1.000,00
+              commodity INR 9,99,99,999.00
+              commodity 1 000 000.9455
+
+       But for convenience, if a commodity directive is not  present,  hledger
+       infers  a commodity's display styles from its amounts as they are writ-
+       ten in the journal (excluding cost  amounts  and  amounts  in  periodic
+       transaction rules or auto posting rules).  It uses
+
+       o the symbol placement and decimal mark of the first amount seen
+
+       o the digit group marks of the first amount with digit group marks
+
+       o and the maximum number of decimal digits seen across all amounts.
+
+       And  as fallback if no applicable amounts are found, it would use a de-
+       fault style, like $1000.00 (symbol on the left with no space, period as
+       decimal mark, and two decimal digits).
+
+       Finally, commodity styles can be overridden by the -c/--commodity-style
+       command line option.
+
+   Rounding
+       Amounts are stored internally as decimal numbers with up to 255 decimal
+       places.  They are displayed with their original journal  precisions  by
+       print  and  print-like  reports, and rounded to their display precision
+       (the number of decimal digits specified by the commodity display style)
+       by other reports.  When rounding, hledger uses  banker's  rounding  (it
+       rounds to the nearest even digit).  So eg 0.5 displayed with zero deci-
+       mal digits appears as "0".
+
+   Trailing decimal marks
+       If you're wondering why your print report sometimes shows trailing dec-
+       imal  marks,  with no decimal digits; it does this when showing amounts
+       that have digit group marks but no decimal digits, to disambiguate them
+       and allow them to be re-parsed reliably (see Decimal marks).  Eg:
+
+              commodity $1,000.00
+
+              2023-01-02
+                  (a)      $1000
+
+              $ hledger print
+              2023-01-02
+                  (a)        $1,000.
+
+       If this is a problem (eg when exporting to Ledger), you can avoid it by
+       disabling digit group marks, eg with -c/--commodity (for each  affected
+       commodity):
+
+              $ hledger print -c '$1000.00'
+              2023-01-02
+                  (a)          $1000
+
+       or by forcing print to always show decimal digits, with --round:
+
+              $ hledger print -c '$1,000.00' --round=soft
+              2023-01-02
+                  (a)      $1,000.00
+
+   Amount parseability
+       More generally, hledger output falls into three rough categories, which
+       format amounts a little bit differently to suit different consumers:
+
+       1.   "hledger-readable  output" - should be readable by hledger (and by
+       humans)
+
+       o This is produced by reports that show full  journal  entries:  print,
+         import, close, rewrite etc.
+
+       o It  shows  amounts  with their original journal precisions, which may
+         not be consistent.
+
+       o It adds a trailing decimal mark when needed to avoid showing  ambigu-
+         ous amounts.
+
+       o It  can be parsed reliably (by hledger and ledger2beancount at least,
+         but perhaps not by Ledger..)
+
+       2.  "human-readable output" - usually for humans
+
+       o This is produced by all other reports.
+
+       o It shows amounts with standard display precisions, which will be con-
+         sistent within each commodity.
+
+       o It shows ambiguous amounts unmodified.
+
+       o It can be parsed reliably in the context of a known report (when  you
+         know decimals are consistently not being shown, you can assume a sin-
+         gle mark is a digit group mark).
+
+       3.  "machine-readable output" - usually for other software
+
+       o This  is produced by all reports when an output format like csv, tsv,
+         json, or sql is selected.
+
+       o It shows amounts as 1 or 2 do, but without digit group marks.
+
+       o It can be parsed reliably (if needed, the decimal mark can be changed
+         with -c/--commodity-style).
+
+Cost reporting
+       In some transactions - for example a currency conversion, or a purchase
+       or sale of stock - one commodity is exchanged for  another.   In  these
+       transactions  there  is  a  conversion rate, also called the cost (when
+       buying) or selling price (when selling).  (In hledger docs we just  say
+       "cost"  generically for convenience.)  With the -B/--cost flag, hledger
+       can show amounts "at cost", converted to the cost's commodity.
+
+   Recording costs
+       We'll explore several ways of recording transactions  involving  costs.
+       These are also summarised at hledger Cookbook > Cost notation.
+
+       Costs  can  be recorded explicitly in the journal, using the @ UNITCOST
+       or @@ TOTALCOST notation described in Journal > Costs:
+
+       Variant 1
+
+              2022-01-01
+                assets:dollars    $-135
+                assets:euros       100 @ $1.35   ; $1.35 per euro (unit cost)
+
+       Variant 2
+
+              2022-01-01
+                assets:dollars    $-135
+                assets:euros       100 @@ $135   ; $135 total cost
+
+       Typically, writing the unit cost (variant 1) is preferable; it  can  be
+       more effort, requiring more attention to decimal digits; but it reveals
+       the per-unit cost basis, and makes stock sales easier.
+
+       Costs  can  also be left implicit, and hledger will infer the cost that
+       is consistent with a balanced transaction:
+
+       Variant 3
+
+              2022-01-01
+                assets:dollars    $-135
+                assets:euros       100
+
+       Here, hledger will attach a @@ 100 cost to the first  amount  (you  can
+       see  it  with hledger print -x).  This form looks convenient, but there
+       are downsides:
+
+       o It sacrifices some error checking.  For example, if you  accidentally
+         wrote 10 instead of 100, hledger would not be able to detect the mis-
+         take.
+
+       o It  is  sensitive to the order of postings - if they were reversed, a
+         different entry would be inferred and reports would be different.
+
+       o The per-unit cost basis is not easy to read.
+
+       So generally this kind of entry is not recommended.  You can make  sure
+       you have none of these by using -s (strict mode), or by running hledger
+       check balanced.
+
+   Reporting at cost
+       Now  when  you  add the -B/--cost flag to reports ("B" is from Ledger's
+       -B/--basis/--cost flag), any amounts which  have  been  annotated  with
+       costs  will  be converted to their cost's commodity (in the report out-
+       put).  Ie they will be displayed "at cost" or "at sale price".
+
+       Some things to note:
+
+       o Costs are attached to specific posting amounts in  specific  transac-
+         tions,  and  once  recorded  they do not change.  This contrasts with
+         market prices, which are ambient and fluctuating.
+
+       o Conversion to cost is performed before  conversion  to  market  value
+         (described below).
+
+   Equity conversion postings
+       There  is  a problem with the entries above - they are not conventional
+       Double Entry Bookkeeping (DEB) notation, and because of  the  "magical"
+       transformation  of  one commodity into another, they cause an imbalance
+       in the Accounting Equation.  This shows up as a non-zero grand total in
+       balance reports like hledger bse.
+
+       For most hledger users, this doesn't matter in practice and can  safely
+       be ignored !  But if you'd like to learn more, keep reading.
+
+       Conventional  DEB  uses an extra pair of equity postings to balance the
+       transaction.  Of course you can do this in hledger as well:
+
+       Variant 4
+
+              2022-01-01
+                  assets:dollars      $-135
+                  assets:euros         100
+                  equity:conversion    $135
+                  equity:conversion   -100
+
+       Now the transaction is perfectly balanced according  to  standard  DEB,
+       and hledger bse's total will not be disrupted.
+
+       And,  hledger can still infer the cost for cost reporting, but it's not
+       done by default - you must add the --infer-costs flag like so:
+
+              $ hledger print --infer-costs
+              2022-01-01 one hundred euros purchased at $1.35 each
+                  assets:dollars       $-135 @@ 100
+                  assets:euros                  100
+                  equity:conversion             $135
+                  equity:conversion            -100
+
+              $ hledger bal --infer-costs -B
+                             -100  assets:dollars
+                              100  assets:euros
+              --------------------
+                                 0
+
+       Here are some downsides of this kind of entry:
+
+       o The per-unit cost basis is not easy to read.
+
+       o Instead of -B you must remember to type -B --infer-costs.
+
+       o --infer-costs works only where  hledger  can  identify  the  two  eq-
+         uity:conversion  postings  and  match them up with the two non-equity
+         postings.  So writing the journal entry in a  particular  format  be-
+         comes more important.  More on this below.
+
+   Inferring equity conversion postings
+       Can we go in the other direction ?  Yes, if you have transactions writ-
+       ten  with  the @/@@ cost notation, hledger can infer the missing equity
+       postings, if you add the --infer-equity flag.  Eg:
+
+              2022-01-01
+                assets:dollars  -$135
+                assets:euros     100 @ $1.35
+
+              $ hledger print --infer-equity
+              2022-01-01
+                  assets:dollars                    $-135
+                  assets:euros               100 @ $1.35
+                  equity:conversion:$-:           -100
+                  equity:conversion:$-:$         $135.00
+
+       The equity account names will  be  "equity:conversion:A-B:A"  and  "eq-
+       uity:conversion:A-B:B"  where  A  is the alphabetically first commodity
+       symbol.  You can customise the "equity:conversion" part by declaring an
+       account with the V/Conversion account type.
+
+       Note you will need to add account declarations for these to your  jour-
+       nal, if you use check accounts or check --strict.
+
+   Combining costs and equity conversion postings
+       Finally, you can use both the @/@@ cost notation and equity postings at
+       the  same time.  This in theory gives the best of all worlds - preserv-
+       ing the accounting equation, revealing the  per-unit  cost  basis,  and
+       providing more flexibility in how you write the entry:
+
+       Variant 5
+
+              2022-01-01 one hundred euros purchased at $1.35 each
+                  assets:dollars      $-135
+                  equity:conversion    $135
+                  equity:conversion   -100
+                  assets:euros         100 @ $1.35
+
+       All  the  other variants above can (usually) be rewritten to this final
+       form with:
+
+              $ hledger print -x --infer-costs --infer-equity
+
+       Downsides:
+
+       o The precise format of the journal entry becomes more  important.   If
+         hledger  can't  detect  and match up the cost and equity postings, it
+         will give a transaction balancing error.
+
+       o The add command does not yet accept this kind of entry (#2056).
+
+       o This is the most verbose form.
+
+   Requirements for detecting equity conversion postings
+       --infer-costs has certain requirements  (unlike  --infer-equity,  which
+       always works).  It will infer costs only in transactions with:
+
+       o Two  non-equity  postings,  in different commodities.  Their order is
+         significant: the cost will be added to the first of them.
+
+       o Two postings to equity conversion  accounts,  next  to  one  another,
+         which balance the two non-equity postings.  This balancing is checked
+         to  the same precision (number of decimal places) used in the conver-
+         sion posting's amount.  Equity conversion accounts are:
+
+         o any accounts declared with account type V/Conversion, or their sub-
+           accounts
+
+         o otherwise, accounts named equity:conversion, equity:trade,  or  eq-
+           uity:trading, or their subaccounts.
+
+       And  multiple  such  four-posting  groups  can  coexist within a single
+       transaction.  When --infer-costs fails, it does not  infer  a  cost  in
+       that  transaction,  and  does  not  raise an error (ie, it infers costs
+       where it can).
+
+       Reading variant 5 journal entries, combining cost notation  and  equity
+       postings,  has  all  the same requirements.  When reading such an entry
+       fails, hledger raises an "unbalanced transaction" error.
+
+   Infer cost and equity by default ?
+       Should --infer-costs and --infer-equity be enabled by  default  ?   Try
+       using them always, eg with a shell alias:
+
+              alias h="hledger --infer-equity --infer-costs"
+
+       and let us know what problems you find.
+
+Value reporting
+       hledger  can  also  show  amounts  "at market value", converted to some
+       other commodity using the market price or conversion rate on a  certain
+       date.
+
+       This  is  controlled  by  the --value=TYPE[,COMMODITY] option.  We also
+       provide simpler -V and -X COMMODITY aliases for this, which  are  often
+       sufficient.  The market prices are declared with a special P directive,
+       and/or they can be inferred from the costs recorded in transactions, by
+       using the --infer-market-prices flag.
+
+   -V: Value
+       The  -V/--market flag converts amounts to market value in their default
+       valuation commodity, using the market prices in effect on the valuation
+       date(s), if any.  More on these in a minute.
+
+   -X: Value in specified commodity
+       The -X/--exchange=COMM option is like -V, except you tell it which cur-
+       rency you want to convert to, and it tries  to  convert  everything  to
+       that.
+
+   Valuation date
+       Market  prices can change from day to day.  hledger will use the prices
+       on a particular valuation date (or on more than one date).  By  default
+       hledger uses "end" dates for valuation.  More specifically:
+
+       o For  single  period  reports (including normal print and register re-
+         ports):
+
+         o If an explicit report end date is specified, that is used
+
+         o Otherwise the latest transaction date or P directive date  is  used
+           (even if it's in the future)
+
+       o For multiperiod reports, each period is valued on its last day.
+
+       This  can  be customised with the --value option described below, which
+       can select either "then", "end", "now", or "custom" dates.  (Note, this
+       has a bug in hledger-ui <=1.31: turning on valuation with the V key al-
+       ways resets it to "end".)
+
+   Finding market price
+       To convert a commodity A to its market value in  another  commodity  B,
+       hledger  looks  for a suitable market price (exchange rate) as follows,
+       in this order of preference:
+
+       1. A declared market price or inferred market price: A's latest  market
+          price in B on or before the valuation date as declared by a P direc-
+          tive, or (with the --infer-market-prices flag) inferred from costs.
+
+       2. A reverse market price: the inverse of a declared or inferred market
+          price from B to A.
+
+       3. A  forward  chain of market prices: a synthetic price formed by com-
+          bining the shortest chain of "forward" (only 1 above) market prices,
+          leading from A to B.
+
+       4. Any chain of market prices: a chain of any market prices,  including
+          both  forward  and reverse prices (1 and 2 above), leading from A to
+          B.
+
+       There is a limit to the  length  of  these  price  chains;  if  hledger
+       reaches  that length without finding a complete chain or exhausting all
+       possibilities, it will give up (with a "gave  up"  message  visible  in
+       --debug=2 output).  That limit is currently 1000.
+
+       Amounts  for  which no suitable market price can be found, are not con-
+       verted.
+
+   --infer-market-prices: market prices from transactions
+       Normally, market value in hledger is fully controlled by, and requires,
+       P directives in your journal.  Since adding and updating those can be a
+       chore, and since transactions usually take place  at  close  to  market
+       value,  why  not use the recorded costs as additional market prices (as
+       Ledger does) ?  Adding the --infer-market-prices  flag  to  -V,  -X  or
+       --value enables this.
+
+       So  for  example,  hledger  bs -V --infer-market-prices will get market
+       prices both from P directives and from transactions.  If both occur  on
+       the same day, the P directive takes precedence.
+
+       There is a downside: value reports can sometimes be affected in confus-
+       ing/undesired  ways  by  your journal entries.  If this happens to you,
+       read all of this Value reporting  section  carefully,  and  try  adding
+       --debug or --debug=2 to troubleshoot.
+
+       --infer-market-prices can infer market prices from:
+
+       o multicommodity transactions with explicit prices (@/@@)
+
+       o multicommodity  transactions with implicit prices (no @, two commodi-
+         ties, unbalanced).  (With  these,  the  order  of  postings  matters.
+         hledger print -x can be useful for troubleshooting.)
+
+       o multicommodity transactions with equity postings, if cost is inferred
+         with --infer-costs.
+
+       There  is  a  limitation (bug) currently: when a valuation commodity is
+       not specified, prices inferred with --infer-market-prices do  not  help
+       select a default valuation commodity, as P prices would.  So conversion
+       might not happen because no valuation commodity was detected (--debug=2
+       will show this).  To be safe, specify the valuation commmodity, eg:
+
+       o -X EUR --infer-market-prices, not -V --infer-market-prices
+
+       o --value=then,EUR --infer-market-prices, not --value=then --infer-mar-
+         ket-prices
+
+       Signed  costs  and market prices can be confusing.  For reference, here
+       is the current behaviour, since hledger 1.25.  (If you think it  should
+       work differently, see #1870.)
+
+              2022-01-01 Positive Unit prices
+                  a        A 1
+                  b        B -1 @ A 1
+
+              2022-01-01 Positive Total prices
+                  a        A 1
+                  b        B -1 @@ A 1
+
+
+              2022-01-02 Negative unit prices
+                  a        A 1
+                  b        B 1 @ A -1
+
+              2022-01-02 Negative total prices
+                  a        A 1
+                  b        B 1 @@ A -1
+
+
+              2022-01-03 Double Negative unit prices
+                  a        A -1
+                  b        B -1 @ A -1
+
+              2022-01-03 Double Negative total prices
+                  a        A -1
+                  b        B -1 @@ A -1
+
+       All of the transactions above are considered balanced (and on each day,
+       the  two  transactions are considered equivalent).  Here are the market
+       prices inferred for B:
+
+              $ hledger -f- --infer-market-prices prices
+              P 2022-01-01 B A 1
+              P 2022-01-01 B A 1.0
+              P 2022-01-02 B A -1
+              P 2022-01-02 B A -1.0
+              P 2022-01-03 B A -1
+              P 2022-01-03 B A -1.0
+
+   Valuation commodity
+       When you specify a valuation commodity (-X COMM or --value TYPE,COMM):
+       hledger will convert all amounts to COMM, wherever it can find a  suit-
+       able market price (including by reversing or chaining prices).
+
+       When  you  leave  the  valuation  commodity  unspecified (-V or --value
+       TYPE):
+       For each commodity A, hledger picks a default  valuation  commodity  as
+       follows, in this order of preference:
+
+       1. The price commodity from the latest P-declared market price for A on
+          or before valuation date.
+
+       2. The price commodity from the latest P-declared market price for A on
+          any  date.   (Allows  conversion  to proceed when there are inferred
+          prices before the valuation date.)
+
+       3. If there are no P directives at all (any commodity or date) and  the
+          --infer-market-prices  flag  is  used:  the price commodity from the
+          latest transaction-inferred price for A on or before valuation date.
+
+       This means:
+
+       o If you have P directives, they determine which  commodities  -V  will
+         convert, and to what.
+
+       o If  you have no P directives, and use the --infer-market-prices flag,
+         costs determine it.
+
+       Amounts for which no valuation commodity can  be  found  are  not  con-
+       verted.
+
+   --value: Flexible valuation
+       -V and -X are special cases of the more general --value option:
+
+               --value=TYPE[,COMM]  TYPE is then, end, now or YYYY-MM-DD.
+                                    COMM is an optional commodity symbol.
+                                    Shows amounts converted to:
+                                    - default valuation commodity (or COMM) using market prices at posting dates
+                                    - default valuation commodity (or COMM) using market prices at period end(s)
+                                    - default valuation commodity (or COMM) using current market prices
+                                    - default valuation commodity (or COMM) using market prices at some date
+
+       The TYPE part selects cost or value and valuation date:
+
+       --value=then
+              Convert  amounts to their value in the default valuation commod-
+              ity, using market prices on each posting's date.
+
+       --value=end
+              Convert amounts to their value in the default valuation  commod-
+              ity,  using  market  prices on the last day of the report period
+              (or if unspecified, the journal's end date); or  in  multiperiod
+              reports, market prices on the last day of each subperiod.
+
+       --value=now
+              Convert  amounts to their value in the default valuation commod-
+              ity using current market prices (as of  when  report  is  gener-
+              ated).
+
+       --value=YYYY-MM-DD
+              Convert  amounts to their value in the default valuation commod-
+              ity using market prices on this date.
+
+       To select a different valuation commodity, add the optional ,COMM part:
+       a comma, then the  target  commodity's  symbol.   Eg:  --value=now,EUR.
+       hledger will do its best to convert amounts to this commodity, deducing
+       market prices as described above.
+
+   Valuation examples
+       Here are some quick examples of -V:
+
+              ; one euro is worth this many dollars from nov 1
+              P 2016/11/01  $1.10
+
+              ; purchase some euros on nov 3
+              2016/11/3
+                  assets:euros        100
+                  assets:checking
+
+              ; the euro is worth fewer dollars by dec 21
+              P 2016/12/21  $1.03
+
+       How many euros do I have ?
+
+              $ hledger -f t.j bal -N euros
+                              100  assets:euros
+
+       What are they worth at end of nov 3 ?
+
+              $ hledger -f t.j bal -N euros -V -e 2016/11/4
+                           $110.00  assets:euros
+
+       What  are they worth after 2016/12/21 ?  (no report end date specified,
+       defaults to today)
+
+              $ hledger -f t.j bal -N euros -V
+                           $103.00  assets:euros
+
+       Here are some examples showing the effect  of  --value,  as  seen  with
+       print:
+
+              P 2000-01-01 A  1 B
+              P 2000-02-01 A  2 B
+              P 2000-03-01 A  3 B
+              P 2000-04-01 A  4 B
+
+              2000-01-01
+                (a)      1 A @ 5 B
+
+              2000-02-01
+                (a)      1 A @ 6 B
+
+              2000-03-01
+                (a)      1 A @ 7 B
+
+       Show the cost of each posting:
+
+              $ hledger -f- print --cost
+              2000-01-01
+                  (a)             5 B
+
+              2000-02-01
+                  (a)             6 B
+
+              2000-03-01
+                  (a)             7 B
+
+       Show the value as of the last day of the report period (2000-02-29):
+
+              $ hledger -f- print --value=end date:2000/01-2000/03
+              2000-01-01
+                  (a)             2 B
+
+              2000-02-01
+                  (a)             2 B
+
+       With  no  report  period specified, that shows the value as of the last
+       day of the journal (2000-03-01):
+
+              $ hledger -f- print --value=end
+              2000-01-01
+                  (a)             3 B
+
+              2000-02-01
+                  (a)             3 B
+
+              2000-03-01
+                  (a)             3 B
+
+       Show the current value (the 2000-04-01 price is still in effect today):
+
+              $ hledger -f- print --value=now
+              2000-01-01
+                  (a)             4 B
+
+              2000-02-01
+                  (a)             4 B
+
+              2000-03-01
+                  (a)             4 B
+
+       Show the value on 2000/01/15:
+
+              $ hledger -f- print --value=2000-01-15
+              2000-01-01
+                  (a)             1 B
+
+              2000-02-01
+                  (a)             1 B
+
+              2000-03-01
+                  (a)             1 B
+
+   Interaction of valuation and queries
+       When matching postings based on queries in the presence  of  valuation,
+       the following happens:
+
+       1. The query is separated into two parts:
+
+           1. the currency (cur:) or amount (amt:).
+
+           2. all other parts.
+
+       2. The postings are matched to the currency and amount queries based on
+          pre-valued amounts.
+
+       3. Valuation is applied to the postings.
+
+       4. The  postings  are  matched to the other parts of the query based on
+          post-valued amounts.
+
+       Related: #1625
+
+   Effect of valuation on reports
+       Here is a reference for how valuation is supposed to affect  each  part
+       of  hledger's  reports.   (It's wide, you may need to scroll sideways.)
+       It may be useful when troubleshooting.  If you  find  problems,  please
+       report  them,  ideally  with  a  reproducible  example.  Related: #329,
+       #1083.
+
+       First, a quick glossary:
+
+       cost   calculated using price(s) recorded in the transaction(s).
+
+       value  market value using available market price declarations,  or  the
+              unchanged amount if no conversion rate can be found.
+
+       report start
+              the  first  day  of the report period specified with -b or -p or
+              date:, otherwise today.
+
+       report or journal start
+              the first day of the report period specified with -b  or  -p  or
+              date:,  otherwise  the earliest transaction date in the journal,
+              otherwise today.
+
+       report end
+              the last day of the report period specified with  -e  or  -p  or
+              date:, otherwise today.
+
+       report or journal end
+              the  last  day  of  the report period specified with -e or -p or
+              date:, otherwise the latest transaction  date  in  the  journal,
+              otherwise today.
+
+       report interval
+              a  flag (-D/-W/-M/-Q/-Y) or period expression that activates the
+              report's multi-period mode (whether showing one or many subperi-
+              ods).
+
+       Report      -B, --cost     -V, -X         --value=then         --value=end    --value=DATE,
+       type                                                                          --value=now
+       --------------------------------------------------------------------------------------------
+       print
+       posting     cost           value at re-   value  at posting    value at re-   value      at
+       amounts                    port end  or   date                 port      or   DATE/today
+                                  today                               journal end
+       balance     unchanged      unchanged      unchanged            unchanged      unchanged
+       asser-
+       tions/as-
+       signments
+
+       register
+       starting    cost           value at re-   valued   at   day    value at re-   value      at
+       balance                    port      or   each   historical    port      or   DATE/today
+       (-H)                       journal end    posting was made     journal end
+       starting    cost           value at day   valued   at   day    value at day   value      at
+       balance                    before   re-   each   historical    before   re-   DATE/today
+       (-H) with                  port      or   posting was made     port      or
+       report                     journal                             journal
+       interval                   start                               start
+       posting     cost           value at re-   value  at posting    value at re-   value      at
+       amounts                    port      or   date                 port      or   DATE/today
+                                  journal end                         journal end
+       summary     summarised     value at pe-   sum  of  postings    value at pe-   value      at
+       posting     cost           riod ends      in interval, val-    riod ends      DATE/today
+       amounts                                   ued  at  interval
+       with  re-                                 start
+       port  in-
+       terval
+       running     sum/average    sum/average    sum/average    of    sum/average    sum/average
+       total/av-   of displayed   of displayed   displayed values     of displayed   of  displayed
+       erage       values         values                              values         values
+
+       balance
+       (bs, bse,
+       cf, is)
+       balance     sums      of   value at re-   value  at posting    value at re-   value      at
+       changes     costs          port end  or   date                 port      or   DATE/today of
+                                  today     of                        journal  end   sums of post-
+                                  sums      of                        of  sums  of   ings
+                                  postings                            postings
+       budget      like balance   like balance   like      balance    like    bal-   like  balance
+       amounts     changes        changes        changes              ances          changes
+       (--bud-
+       get)
+       grand to-   sum  of dis-   sum  of dis-   sum  of displayed    sum of  dis-   sum  of  dis-
+       tal         played  val-   played  val-   valued               played  val-   played values
+                   ues            ues                                 ues
+
+       balance
+       (bs, bse,
+       cf,   is)
+       with  re-
+       port  in-
+       terval
+       starting    sums      of   value at re-   sums of values of    value at re-   sums of post-
+       balances    costs     of   port   start   postings   before    port   start   ings   before
+       (-H)        postings be-   of  sums  of   report  start  at    of  sums  of   report start
+                   fore  report   all postings   respective  post-    all postings
+                   start          before   re-   ing dates            before   re-
+                                  port start                          port start
+       balance     sums      of   same      as   sums of values of    balance        value      at
+       changes     costs     of   --value=end    postings  in  pe-    change    in   DATE/today of
+       (bal, is,   postings  in                  riod  at  respec-    each period,   sums of post-
+       bs          period                        tive      posting    valued    at   ings
+       --change,                                 dates                period ends
+       cf
+       --change)
+       end  bal-   sums      of   same      as   sums of values of    period   end   value      at
+       ances       costs     of   --value=end    postings from be-    balances,      DATE/today of
+       (bal  -H,   postings                      fore period start    valued    at   sums of post-
+       is   --H,   from  before                  to  period end at    period ends    ings
+       bs, cf)     report start                  respective  post-
+                   to    period                  ing dates
+                   end
+       budget      like balance   like balance   like      balance    like    bal-   like  balance
+       amounts     changes/end    changes/end    changes/end  bal-    ances          changes/end
+       (--bud-     balances       balances       ances                               balances
+       get)
+       row   to-   sums,  aver-   sums,  aver-   sums, averages of    sums,  aver-   sums,   aver-
+       tals, row   ages of dis-   ages of dis-   displayed values     ages of dis-   ages of  dis-
+       averages    played  val-   played  val-                        played  val-   played values
+       (-T, -A)    ues            ues                                 ues
+       column      sums of dis-   sums of dis-   sums of displayed    sums of dis-   sums of  dis-
+       totals      played  val-   played  val-   values               played  val-   played values
+                   ues            ues                                 ues
+       grand to-   sum, average   sum, average   sum,  average  of    sum, average   sum,  average
+       tal,        of    column   of    column   column totals        of    column   of column to-
+       grand av-   totals         totals                              totals         tals
+       erage
+
+
+       --cumulative is omitted to save space, it works like -H but with a zero
+       starting balance.
+
+PART 4: COMMANDS
+       Here are the standard commands, which you can list by running  hledger.
+       If you have installed more add-on commands, they also will be listed.
+
+       Help commands
+
+       o help - show the hledger manual with info/man/pager
+
+       o demo - show small hledger demos in the terminal
+
+       User interface commands
+
+       o ui - (if installed) run hledger's terminal UI
+
+       o web - (if installed) run hledger's web UI
+
+       Data entry commands
+
+       o add - add transactions using terminal prompts
+
+       o import - add new transactions from other files, eg CSV files
+
+       Basic report commands
+
+       o accounts - show account names
+
+       o codes - show transaction codes
+
+       o commodities - show commodity/currency symbols
+
+       o descriptions - show transaction descriptions
+
+       o files - show input file paths
+
+       o notes - show note parts of transaction descriptions
+
+       o payees - show payee parts of transaction descriptions
+
+       o prices - show market prices
+
+       o stats - show journal statistics
+
+       o tags - show tag names
+
+       Standard report commands
+
+       o print - show transactions or export journal data
+
+       o aregister (areg) - show transactions in a particular account
+
+       o register  (reg) - show postings in one or more accounts & running to-
+         tal
+
+       o balancesheet (bs) - show assets, liabilities and net worth
+
+       o balancesheetequity (bse) - show assets, liabilities and equity
+
+       o cashflow (cf) - show changes in liquid assets
+
+       o incomestatement (is) - show revenues and expenses
+
+       Advanced report commands
+
+       o balance (bal) - show balance changes, end balances, budgets, gains..
+
+       o roi - show return on investments
+
+       Chart commands
+
+       o activity - show bar charts of posting counts per period
+
+       Data generation commands
+
+       o close - generate balance-zeroing/restoring transactions
+
+       o rewrite - generate auto postings, like print --auto
+
+       Maintenance commands
+
+       o check - check for various kinds of error in the data
+
+       o diff - compare account transactions in two journal files
+
+       o test - run self tests
+
+       Next, these commands are described in detail.
+
+Help commands
+   commands
+       Show the hledger commands list.
+
+              Flags:
+                   --builtin             show only builtin commands, not addons
+
+   demo
+       Play demos of hledger usage in the terminal, if asciinema is installed.
+
+              Flags:
+                -s --speed=SPEED         playback speed (1 is original speed, .5 is half, 2
+                                         is double, etc (default: 2))
+
+       Run this command with no argument to list the demos.  To play  a  demo,
+       write its number or a prefix or substring of its title.  Tips:
+
+       Make your terminal window large enough to see the demo clearly.
+
+       Use  the  -s/--speed SPEED option to set your preferred playback speed,
+       eg -s4 to play at 4x original speed or -s.5 to play at half speed.  The
+       default speed is 2x.
+
+       Other asciinema options can be added following a  double  dash,  eg  --
+       -i.1 to limit pauses or -- -h to list asciinema's other options.
+
+       During  playback, several keys are available: SPACE to pause/unpause, .
+       to step forward (while paused), CTRL-c quit.
+
+       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.
+
+   help
+       Show the hledger user manual with info, man, or a pager.  With a  (case
+       insensitive) TOPIC argument, try to open it at that section heading.
+
+              Flags:
+                -i                       show the manual with info
+                -m                       show the manual with man
+                -p                       show the manual with $PAGER or less
+                                         (less is always used if TOPIC is specified)
+
+       This  command  shows  the  hledger manual built in to your hledger exe-
+       cutable.  It can be useful when offline, or when you prefer the  termi-
+       nal to a web browser, or when the appropriate hledger manual or viewers
+       are not installed properly on your system.
+
+       By  default  it  chooses the best viewer found in $PATH, trying in this
+       order: info, man, $PAGER, less, more, stdout.  (If a  TOPIC  is  speci-
+       fied,  $PAGER  and more are not tried.)  You can force the use of info,
+       man, or a pager with the -i, -m, or -p flags.   If  no  viewer  can  be
+       found,  or  if  running non-interactively, it just prints the manual to
+       stdout.
+
+       When using info, TOPIC can match either the full heading or  a  prefix.
+       If your info --version is < 6, you'll need to upgrade it, eg with 'brew
+       install texinfo' on mac.
+
+       When  using man or less, TOPIC must match the full heading.  For a pre-
+       fix match, you can write 'TOPIC.*'.
+
+       Examples
+
+              $ hledger help -h                 # show the help command's usage
+              $ hledger help                    # show the manual with info, man or $PAGER
+              $ hledger help 'time periods'     # show the manual's "Time periods" topic
+              $ hledger help 'time periods' -m  # use man, even if info is installed
+
+User interface commands
+   repl
+       Start an interactive prompt, where you can run any  of  hledger's  com-
+       mands.  Data files are parsed just once, so the commands run faster.
+
+              Flags:
+              no command-specific flags
+
+       This command is experimental and could change in the future.
+
+       hledger  repl  starts a read-eval-print loop (REPL) where you can enter
+       commands interactively.  As with the run command, each input  file  (or
+       each input file/input options combination) is parsed just once, so com-
+       mands  will  run  more quickly than if you ran them individually at the
+       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, and com-
+       mands  will  not  see any changes made to input files (eg by add) until
+       you exit and restart the REPL.
+
+       The command syntax is the same as with run:
+
+       o enter one hledger command at a time, without the usual hledger  first
+         word
+
+       o empty lines and comment text from # to end of line are ignored
+
+       o use single or double quotes to quote arguments when needed
+
+       o 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:
+
+       o Keypad or Emacs navigation keys to edit the current command line
+
+       o UP/DOWN or control-P/control-N to step back/forward through history
+
+       o control-R to search for a past command
+
+       o 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 useful.
+
+       You can type control-C to cancel a long-running command (but only once;
+       typing it a second time will exit the REPL).
+
+       And  in  most  shells you can type control-Z to exit temporarily to the
+       shell (and fg to return to the REPL).
+
+       You may find some differences in behaviour between  run  command  lines
+       and normal hledger command lines.  For example, in the REPL,
+
+       o the command name must be written first, options afterward
+
+       o full command names or official abbreviations (as in the command list)
+         must be used
+
+       o options  parsing  with addon commands might be less flexible than the
+         CLI
+
+       o the stats command gives false timings, currently
+
+   Examples
+       Start the REPL and enter some commands:
+
+              $ 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:
+
+              $ 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
+              ...
+
+   run
+       Run a sequence of hledger commands, provided as files or  command  line
+       arguments.   Data  files  are  parsed  just  once,  so the commands run
+       faster.
+
+              Flags:
+              no command-specific flags
+
+       This command is experimental and could change in the future.
+
+       You can use run in three ways:
+
+       o hledger run -- CMD1 -- CMD2 -- CMD3 - read commands from the  command
+         line, separated by --
+
+       o hledger  run SCRIPTFILE1 SCRIPTFILE2 - read commands from one or more
+         files
+
+       o cat SCRIPTFILE1 | hledger run - read commands from standard input.
+
+       run first loads the input file(s) specified by LEDGER_FILE or by -f op-
+       tions, in the usual way.  Then it runs each command in turn, each using
+       the same input data.  But if you want a particular command to use  dif-
+       ferent  input,  you can specify an -f option within that command.  This
+       will override (not add to) the default input, just for that command.
+
+       Each input file (more precisely, each combination of input file and in-
+       put options) is parsed only once.  This means that  commands  will  not
+       see  any changes made to these files, until the next run.  But the com-
+       mands will run more quickly than if run individually  (typically  about
+       twice as fast).
+
+       Command scripts, whether in a file or written on the command line, have
+       a simple syntax:
+
+       o each  line  may  contain  a single hledger command and its arguments,
+         without the usual hledger first word
+
+       o empty lines are ignored
+
+       o text from # to end of line is a comment, and ignored
+
+       o you can use single or double quotes to quote arguments  when  needed,
+         as on the command line
+
+       o these  extra  commands are available: echo TEXT prints some text, and
+         exit or quit ends the run.
+
+       On unix systems you can use #!/usr/bin/env hledger  run  in  the  first
+       line  of a command file to make it a runnable script.  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.
+
+       You may find some differences in behaviour between  run  command  lines
+       and normal hledger command lines.  For example, with run,
+
+       o the command name must be written first, options afterward
+
+       o full command names or official abbreviations (as in the command list)
+         must be used
+
+   Examples
+       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
+
+       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 run stats on some.journal
+
+       Run commands from standard input:
+
+              (echo "files"; echo "stats") | hledger -f some.journal run
+
+       Run commands as a script:
+
+              $ cat report
+              #!/usr/bin/env -S hledger run -f some.journal
+
+              echo "List of accounts in some.journal"
+              accounts
+
+              echo "Assets of some.journal"
+              balance assets --depth 2
+
+              echo "Liabilities from /some/other.journal"
+              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
+              ...
+
+   ui
+       Runs hledger-ui (if installed).
+
+   web
+       Runs hledger-web (if installed).
+
+Data entry commands
+   add
+       Record new transactions with interactive prompting in the console.
+
+              Flags:
+                   --no-new-accounts      don't allow creating new accounts
+
+       Many  hledger users edit their journals directly with a text editor, or
+       generate them from CSV.  For more interactive data entry, there is  the
+       add  command, which prompts interactively on the console for new trans-
+       actions, and appends them to the main journal file (which should be  in
+       journal  format).   Existing transactions are not changed.  This is one
+       of the few hledger commands that writes to the journal file  (see  also
+       import).
+
+       To use it, just run hledger add and follow the prompts.  You can add as
+       many  transactions as you like; when you are finished, enter . or press
+       control-d or control-c to exit.
+
+       Features:
+
+       o add tries to provide useful defaults, using the most similar (by  de-
+         scription)  recent  transaction  (filtered by the query, if any) as a
+         template.
+
+       o You can also set the initial defaults with command line arguments.
+
+       o Readline-style edit keys can be used during data entry.
+
+       o The tab key will auto-complete whenever  possible  -  accounts,  pay-
+         ees/descriptions,  dates  (yesterday, today, tomorrow).  If the input
+         area is empty, it will insert the default value.
+
+       o A parenthesised transaction code may be entered following a date.
+
+       o Comments and tags may be entered following a description or amount.
+
+       o If you make a mistake, enter < at any prompt to go one step backward.
+
+       o Input prompts are displayed in a different colour when  the  terminal
+         supports it.
+
+       Notes:
+
+       o If you enter a number with no commodity symbol, and you have declared
+         a  default  commodity with a D directive, you might expect add to add
+         this symbol for you.  It does not do this; we assume that if you  are
+         using  a  D  directive you prefer not to see the commodity symbol re-
+         peated on amounts in the journal.
+
+       Examples:
+
+       o Record new transactions, saving to the default journal file:
+
+         hledger add
+
+       o Add transactions to 2024.journal, but also load 2023.journal for com-
+         pletions:
+
+         hledger add --file 2024.journal --file 2023.journal
+
+       o Provide answers for the first four prompts:
+
+         hledger add today 'best buy' expenses:supplies '$20'
+
+       There is a detailed tutorial at https://hledger.org/add.html.
+
+   import
+       Import new transactions from one or more data files to the  main  jour-
+       nal.
+
+              Flags:
+                   --catchup              just mark all transactions as already imported
+                   --dry-run              just show the transactions to be imported
+
+       This  command detects new transactions in one or more data files speci-
+       fied as arguments, and appends them to the main journal.
+
+       You can import  from  any  input  file  format  hledger  supports,  but
+       CSV/SSV/TSV files, downloaded from financial institutions, are the most
+       common import source.
+
+       The  import  destination is the default journal file, or another speci-
+       fied in the usual way with $LEDGER_FILE or -f/--file.  It should be  in
+       journal format.
+
+       Examples:
+
+              $ hledger import bank1-checking.csv bank1-savings.csv
+
+              $ hledger import *.csv
+
+   Import preview
+       It's  useful  to preview the import by running first with --dry-run, to
+       sanity check the range of dates being imported, and to check the effect
+       of your conversion rules if converting from CSV.  Eg:
+
+              $ hledger import bank.csv --dry-run
+
+       The dry run output is valid journal format, so hledger can re-parse it.
+       If the output is large, you could show just the uncategorised  transac-
+       tions like so:
+
+              $ hledger import --dry-run bank.csv | hledger -f- -I print unknown
+
+       You  could  also run this repeatedly to see the effect of edits to your
+       conversion rules:
+
+              $ watchexec -- 'hledger import --dry-run bank.csv | hledger -f- -I print unknown'
+
+       Once the conversion and dates look good enough to import to your  jour-
+       nal, perhaps with some manual fixups to follow, you would do the actual
+       import:
+
+              $ hledger import bank.csv
+
+   Overlap detection
+       Reading  CSV  files is built in to hledger, and not specific to import;
+       so  you  could  also  import  by  doing  hledger  -f   bank.csv   print
+       >>$LEDGER_FILE.
+
+       But  import  is  easier  and provides some advantages.  The main one is
+       that it avoids re-importing transactions it has seen on previous  runs.
+       This means you don't have to worry about overlapping data in successive
+       downloads  of  your  bank CSV; just download and import as often as you
+       like, and only the new transactions will be imported each time.
+
+       We don't call this "deduplication", as it's generally not  possible  to
+       reliably  detect duplicates in bank CSV.  Instead, import remembers the
+       latest date processed previously in each CSV file (saving it in a  hid-
+       den  file),  and skips any records prior to that date.  This works well
+       for most real-world CSV, where:
+
+       1. the data file name is stable (does not change) across imports
+
+       2. the item dates are stable across imports
+
+       3. the order of same-date items is stable across imports
+
+       4. the newest items have the newest dates
+
+       (Occasional violations of 2-4 are often harmless; you  can  reduce  the
+       chance of disruption by downloading and importing more often.)
+
+       Overlap  detection  is  automatic, and shouldn't require much attention
+       from you, except perhaps at first import (see below).  But  here's  how
+       it works:
+
+       o For each FILE being imported from:
+
+         1. hledger  reads  a  file named .latest.FILE file in the same direc-
+            tory, if any.  This file contains the latest  record  date  previ-
+            ously  imported  from  FILE,  in  YYYY-MM-DD  format.  If multiple
+            records with that date were imported, the date is  repeated  on  N
+            lines.
+
+         2. hledger  reads  records  from FILE.  If a latest date was found in
+            step 1, any records before that date, and the first N  records  on
+            that date, are skipped.
+
+       o After  a  successful import from all FILEs, without error and without
+         --dry-run, hledger updates each FILE's .latest.FILE for next time.
+
+       If this goes wrong, it's relatively easy to repair:
+
+       o You'll  notice  it  before  import  when  you  preview  with   import
+         --dry-run.
+
+       o Or  after  import when you try to reconcile your hledger account bal-
+         ances with your bank.
+
+       o hledger print -f FILE.csv will show all recently downloaded  transac-
+         tions.  Compare these with your journal.  Copy/paste if needed.
+
+       o Update your conversion rules and print again, if needed.
+
+       o You  can  manually  update  or remove the .latest file, or use import
+         --catchup FILE.
+
+       o Download and import more often, eg twice a week, at least  while  you
+         are  learning.  It's easier to review and troubleshoot when there are
+         fewer transactions.
+
+   First import
+       The first time you import from a file, when  no  corresponding  .latest
+       file has been created yet, all of the records will be imported.
+
+       But  perhaps you have been entering the data manually, so you know that
+       all of these transactions are already recorded in the journal.  In this
+       case you can run hledger import --catchup once.   This  will  create  a
+       .latest  file  containing  the  latest CSV record date, so that none of
+       those records will be re-imported.
+
+       Or, if you know that some but not all of the transactions  are  in  the
+       journal,  you  can create the .latest file yourself.  Eg, let's say you
+       previously recorded foobank transactions up to 2024-10-31 in the  jour-
+       nal.   Then  in  the  directory where you'll be saving foobank.csv, you
+       would create a .latest.foobank.csv file containing
+
+              2024-10-31
+
+       Or if you had three foobank transactions recorded with that  date,  you
+       would repeat the date that many times:
+
+              2024-10-31
+              2024-10-31
+              2024-10-31
+
+       Then  hledger import foobank.csv [--dry-run] will import only the newer
+       records.
+
+   Importing balance assignments
+       Journal entries added by import will have all posting amounts made  ex-
+       plicit (like print -x).
+
+       This  means  that any balance assignments in the imported entries would
+       need to be evaluated.  But this generally isn't possible, as  the  main
+       file's account balances are not visible during import.  So try to avoid
+       generating balance assignments with your CSV rules, or importing from a
+       journal  that  contains  balance assignments.  (Balance assignments are
+       best avoided anyway.)
+
+       But if you must use them, eg because your CSV includes  only  balances:
+       you  can  import  with  print,  which leaves implicit amounts implicit.
+       (print can also do overlap detection like import, with the --new flag):
+
+              $ hledger print --new -f bank.csv >> $LEDGER_FILE
+
+       (If you think import should preserve  implicit  balances,  please  test
+       that and send a pull request.)
+
+   Import and commodity styles
+       Amounts  in  entries added by import will be formatted according to the
+       journal's canonical commodity styles, as declared by  commodity  direc-
+       tives or inferred from the journal's amounts.
+
+       Related: CSV > Amount decimal places.
+
+   Import special cases
+       If you have a download whose file name varies, you could rename it to a
+       fixed  name  after  each  download.  Or you could use a CSV source rule
+       with a suitable glob pattern, and import from the .rules  file  instead
+       of the data file.
+
+       Here's  a  situation  where you would need to run import with care: say
+       you download bank.csv, but forget to import it or delete it.  And  next
+       month you download it again.  This time your web browser may save it as
+       bank  (2).csv.   So now each of these may have data not included in the
+       other.  And a source rule with a glob pattern would match only the most
+       recent file.  So in this case you should import from each one in  turn,
+       in the correct order, taking care to use the same filename each time:
+
+              $ hledger import bank.csv
+              $ mv 'bank (2).csv' bank.csv
+              $ hledger import bank.csv
+
+       Here are two kinds of "deduplication" which import does not handle (and
+       generally  should not, since these can happen legitimately in financial
+       data):
+
+       o Two or more of the new CSV records are identical, and generate  iden-
+         tical new journal entries.
+
+       o A  new  CSV  record generates a journal entry identical to one(s) al-
+         ready in the journal.
+
+Basic report commands
+   accounts
+       List account names.
+
+              Flags:
+                -u --used                 show only accounts used by transactions
+                -d --declared             show only accounts declared by account directive
+                   --unused               show only accounts declared but not used
+                   --undeclared           show only accounts used but not declared
+                   --types                also show account types when known
+                   --positions            also show where accounts were declared
+                   --directives           show as account directives, for use in journals
+                   --find                 find the first account matched by the first
+                                          argument (a case-insensitive infix regexp or
+                                          account name)
+                -l --flat                 show accounts as a flat list (default)
+                -t --tree                 show accounts as a tree
+                   --drop=N               flat mode: omit N leading account name parts
+
+       This command lists account names.  By default it shows  all  known  ac-
+       counts,  either  used  in  transactions or declared with account direc-
+       tives.
+
+       With query arguments, only matched account names and account names ref-
+       erenced by matched postings are shown.
+
+       Or it can show just the used accounts  (--used/-u),  the  declared  ac-
+       counts  (--declared/-d), the accounts declared but not used (--unused),
+       the accounts used but not declared (--undeclared), or the first account
+       matched by an account name pattern, if any (--find).
+
+       It shows a flat list by default.  With --tree, it uses  indentation  to
+       show  the account hierarchy.  In flat mode you can add --drop N to omit
+       the  first  few  account  name  components.   Account  names   can   be
+       depth-clipped with depth:N or --depth N or -N.
+
+       With  --types,  it also shows each account's type, if it's known.  (See
+       Declaring accounts > Account types.)
+
+       With --positions, it also shows the file and line number  of  each  ac-
+       count's  declaration, if any, and the account's overall declaration or-
+       der; these may be useful when troubleshooting account display order.
+
+       With --directives, it adds the account keyword, showing  valid  account
+       directives which can be pasted into a journal file.  This is useful to-
+       gether  with  --undeclared  when  updating your account declarations to
+       satisfy hledger check accounts.
+
+       The --find flag can be used to look up a single account  name,  in  the
+       same  way that the aregister command does.  It returns the alphanumeri-
+       cally-first matched account name, or if none can  be  found,  it  fails
+       with a non-zero exit code.
+
+       Examples:
+
+              $ hledger accounts
+              assets:bank:checking
+              assets:bank:saving
+              assets:cash
+              expenses:food
+              expenses:supplies
+              income:gifts
+              income:salary
+              liabilities:debts
+
+              $ hledger accounts --undeclared --directives >> $LEDGER_FILE
+              $ hledger check accounts
+
+   codes
+       List the codes seen in transactions, in the order parsed.
+
+              Flags:
+              no command-specific flags
+
+       This  command prints the value of each transaction's code field, in the
+       order transactions were parsed.  The transaction code  is  an  optional
+       value  written  in  parentheses between the date and description, often
+       used to store a cheque number, order number or similar.
+
+       Transactions aren't required to have a code, and missing or empty codes
+       will not be shown by default.  With the -E/--empty flag, they  will  be
+       printed as blank lines.
+
+       You can add a query to select a subset of transactions.
+
+       Examples:
+
+              2022/1/1 (123) Supermarket
+               Food       $5.00
+               Checking
+
+              2022/1/2 (124) Post Office
+               Postage    $8.32
+               Checking
+
+              2022/1/3 Supermarket
+               Food      $11.23
+               Checking
+
+              2022/1/4 (126) Post Office
+               Postage    $3.21
+               Checking
+
+              $ hledger codes
+              123
+              124
+              126
+
+              $ hledger codes -E
+              123
+              124
+
+              126
+
+   commodities
+       List all commodity/currency symbols used or declared in the journal.
+
+              Flags:
+              no command-specific flags
+
+   descriptions
+       List the unique descriptions that appear in transactions.
+
+              Flags:
+              no command-specific flags
+
+       This command lists the unique descriptions that appear in transactions,
+       in  alphabetic order.  You can add a query to select a subset of trans-
+       actions.
+
+       Example:
+
+              $ hledger descriptions
+              Store Name
+              Gas Station | Petrol
+              Person A
+
+   files
+       List all files included in the journal.  With a  REGEX  argument,  only
+       file names matching the regular expression (case sensitive) are shown.
+
+              Flags:
+              no command-specific flags
+
+   notes
+       List the unique notes that appear in transactions.
+
+              Flags:
+              no command-specific flags
+
+       This command lists the unique notes that appear in transactions, in al-
+       phabetic  order.   You  can  add a query to select a subset of transac-
+       tions.  The note is the part of the transaction description after  a  |
+       character (or if there is no |, the whole description).
+
+       Example:
+
+              $ hledger notes
+              Petrol
+              Snacks
+
+   payees
+       List the unique payee/payer names that appear in transactions.
+
+              Flags:
+                   --declared             show payees declared with payee directives
+                   --used                 show payees referenced by transactions
+
+       This  command  lists  unique payee/payer names which have been declared
+       with payee directives (--declared), used  in  transaction  descriptions
+       (--used), or both (the default).
+
+       The  payee/payer  is the part of the transaction description before a |
+       character (or if there is no |, the whole description).
+
+       You can add query arguments to select a subset of  transactions.   This
+       implies --used.
+
+       Example:
+
+              $ hledger payees
+              Store Name
+              Gas Station
+              Person A
+
+   prices
+       Print  the market prices declared with P directives.  With --infer-mar-
+       ket-prices, also show any additional prices inferred from costs.   With
+       --show-reverse, also show additional prices inferred by reversing known
+       prices.
+
+              Flags:
+                   --show-reverse         also show the prices inferred by reversing known
+                                          prices
+
+       Price  amounts  are  always displayed with their full precision, except
+       for reverse prices which are limited to 8 decimal digits.
+
+       Prices can be filtered by a date:, cur: or amt: query.
+
+       Generally if you run this command with --infer-market-prices --show-re-
+       verse, it will show the same prices used internally to calculate  value
+       reports.   But  if  in doubt, you can inspect those directly by running
+       the value report with --debug=2.
+
+   stats
+       Show journal and performance statistics.
+
+              Flags:
+                -v --verbose              show more detailed output
+                -o --output-file=FILE     write output to FILE.
+
+       The stats command shows summary information for the whole journal, or a
+       matched part of it.  With a reporting interval, it shows a  report  for
+       each report period.
+
+       The  default  output  is  fairly impersonal, though it reveals the main
+       file name.  With -v/--verbose, more details are shown, like file paths,
+       included files, and commodity names.
+
+       It also shows some run time statistics:
+
+       o elapsed time
+
+       o throughput: the number of transactions processed per second
+
+       o live: the peak memory in use by the program to do its work
+
+       o alloc: the peak memory allocation from the OS as seen by  GHC.   Mea-
+         suring  this  externally, eg with GNU time, is more accurate; usually
+         that will be a larger number; sometimes (with swapping?)  smaller.
+
+       The stats command's run time is similar to that of a balance report.
+
+       Example:
+
+              $ hledger stats -f examples/1ktxns-1kaccts.journal
+              Main file           : .../1ktxns-1kaccts.journal
+              Included files      : 0
+              Txns span           : 2000-01-01 to 2002-09-27 (1000 days)
+              Last txn            : 2002-09-26 (7827 days ago)
+              Txns                : 1000 (1.0 per day)
+              Txns last 30 days   : 0 (0.0 per day)
+              Txns last 7 days    : 0 (0.0 per day)
+              Payees/descriptions : 1000
+              Accounts            : 1000 (depth 10)
+              Commodities         : 26
+              Market prices       : 1000
+              Runtime stats       : 0.12 s elapsed, 8266 txns/s, 4 MB live, 16 MB alloc
+
+       This command supports the -o/--output-file option  (but  not  -O/--out-
+       put-format).
+
+   tags
+       List the tags used in the journal, or their values.
+
+              Flags:
+                   --values               list tag values instead of tag names
+                   --parsed               show tags/values in the order they were parsed,
+                                          including duplicates
+
+       This command lists the tag names used in the journal, whether on trans-
+       actions, postings, or account declarations.
+
+       With  a TAGREGEX argument, only tag names matching this regular expres-
+       sion (case insensitive, infix matched) are shown.
+
+       With QUERY arguments, only  transactions  and  accounts  matching  this
+       query are considered.  If the query involves transaction fields (date:,
+       desc:, amt:, ...), the search is restricted to the matched transactions
+       and their accounts.
+
+       With  the  --values  flag, the tags' unique non-empty values are listed
+       instead.  With -E/--empty, blank/empty values are also shown.
+
+       With --parsed, tags or values are shown in the order they were  parsed,
+       with  duplicates included.  (Except, tags from account declarations are
+       always shown first.)
+
+       Tip: remember, accounts also acquire tags from their parents,  postings
+       also acquire tags from their account and transaction, transactions also
+       acquire tags from their postings.
+
+Standard report commands
+   print
+       Show full journal entries, representing transactions.
+
+              Flags:
+                -x --explicit             show all amounts explicitly
+                   --show-costs           show transaction prices even with conversion
+                                          postings
+                   --round=TYPE           how much rounding or padding should be done when
+                                          displaying amounts ?
+                                          none - show original decimal digits,
+                                                 as in journal (default)
+                                          soft - just add or remove decimal zeros
+                                                 to match precision
+                                          hard - round posting amounts to precision
+                                                 (can unbalance transactions)
+                                          all  - also round cost amounts to precision
+                                                 (can unbalance transactions)
+                   --invert               display all amounts with reversed sign
+                   --new                  show only newer-dated transactions added in each
+                                          file since last run
+                -m --match=DESC           fuzzy search for one recent transaction with
+                                          description closest to DESC
+                   --base-url=URLPREFIX   in html output, generate links to hledger-web,
+                                          with this prefix. (Usually the base url shown by
+                                          hledger-web; can also be relative.)
+                -O --output-format=FMT    select the output format. Supported formats:
+                                          txt, beancount, csv, tsv, html, fods, json, sql.
+                -o --output-file=FILE     write output to FILE. A file extension matching
+                                          one of the above formats selects that format.
+
+       The print command displays full journal entries (transactions) from the
+       journal file, sorted by date (or with --date2, by secondary date).
+
+       Directives  and  inter-transaction  comments  are not shown, currently.
+       This means the print command is somewhat lossy, and if you are using it
+       to reformat/regenerate your journal you should take care to  also  copy
+       over the directives and inter-transaction comments.
+
+       Eg:
+
+              $ hledger print -f examples/sample.journal date:200806
+              2008/06/01 gift
+                  assets:bank:checking            $1
+                  income:gifts                   $-1
+
+              2008/06/02 save
+                  assets:bank:saving              $1
+                  assets:bank:checking           $-1
+
+              2008/06/03 * eat & shop
+                  expenses:food                $1
+                  expenses:supplies            $1
+                  assets:cash                 $-2
+
+   print explicitness
+       Normally,  whether  posting  amounts  are  implicit or explicit is pre-
+       served.  For example, when an amount is omitted in the journal, it will
+       not appear in the output.  Similarly, if a conversion cost  is  implied
+       but not written, it will not appear in the output.
+
+       You  can  use  the  -x/--explicit flag to force explicit display of all
+       amounts and costs.  This can be useful for troubleshooting or for  mak-
+       ing  your  journal  more readable and robust against data entry errors.
+       -x is also implied by using any of -B,-V,-X,--value.
+
+       The -x/--explicit flag will cause any postings with  a  multi-commodity
+       amount  (which  can arise when a multi-commodity transaction has an im-
+       plicit amount) to be split  into  multiple  single-commodity  postings,
+       keeping the output parseable.
+
+   print amount style
+       Amounts  are  shown  right-aligned  within  each  transaction  (but not
+       aligned across all transactions; you can do that  with  ledger-mode  in
+       Emacs).
+
+       Amounts  will  be (mostly) normalised to their commodity display style:
+       their symbol placement, decimal mark, and digit  group  marks  will  be
+       made  consistent.   By  default,  decimal  digits are shown as they are
+       written in the journal.
+
+       With the --round (Added in 1.32) option, print  will  try  increasingly
+       hard  to  display  decimal  digits  according  to the commodity display
+       styles:
+
+       o --round=none show amounts with original precisions (default)
+
+       o --round=soft add/remove decimal zeros in amounts (except costs)
+
+       o --round=hard round amounts (except costs), possibly  hiding  signifi-
+         cant digits
+
+       o --round=all round all amounts and costs
+
+       soft  is  good  for  non-lossy cleanup, formatting amounts more consis-
+       tently where it's safe to do so.
+
+       hard and all can cause print to show  invalid  unbalanced  journal  en-
+       tries;  they  may be useful eg for stronger cleanup, with manual fixups
+       when needed.
+
+   print parseability
+       print's output is usually a valid hledger journal, and you can  process
+       it again with a second hledger command.  This can be useful for certain
+       kinds  of  search  (though  the same can be achieved with expr: queries
+       now):
+
+              # Show running total of food expenses paid from cash.
+              # -f- reads from stdin. -I/--ignore-assertions is sometimes needed.
+              $ hledger print assets:cash | hledger -f- -I reg expenses:food
+
+       There are some situations where print's output can become unparseable:
+
+       o Value reporting affects posting amounts but not balance assertion  or
+         balance assignment amounts, potentially causing those to fail.
+
+       o Auto postings can generate postings with too many missing amounts.
+
+       o Account aliases can generate bad account names.
+
+   print, other features
+       With -B/--cost, amounts with costs are shown converted to cost.
+
+       With  --invert,  posting amounts are shown with their sign flipped.  It
+       could be useful if you have  accidentally  recorded  some  transactions
+       with the wrong signs.
+
+       With --new, print shows only transactions it has not seen on a previous
+       run.   This  uses  the same deduplication system as the import command.
+       (See import's docs for details.)
+
+       With -m DESC/--match=DESC, print shows one recent transaction whose de-
+       scription is most similar to DESC.  DESC should contain  at  least  two
+       characters.   If  there is no similar-enough match, no transaction will
+       be shown and the program exit code will be non-zero.
+
+   print output format
+       This command also supports the output destination and output format op-
+       tions The output formats supported are txt, beancount (Added in  1.32),
+       csv, tsv (Added in 1.32), json and sql.
+
+       The  beancount  format tries to produce Beancount-compatible output, as
+       follows:
+
+       o Transaction and  postings  with  unmarked  status  are  converted  to
+         cleared (*) status.
+
+       o Transactions'   payee   and   note  are  backslash-escaped  and  dou-
+         ble-quote-escaped and wrapped in double quotes.
+
+       o Transaction tags are copied to Beancount #tag format.
+
+       o Commodity symbols are converted to upper case, and a small number  of
+         currency  symbols  like $ are converted to the corresponding currency
+         names.
+
+       o Account name parts are capitalised and unsupported characters are re-
+         placed with -.  If an account name part does not begin with a letter,
+         or if the first part is not Assets, Liabilities, Equity,  Income,  or
+         Expenses, an error is raised.  (Use --alias options to bring your ac-
+         counts into compliance.)
+
+       o An open directive is generated for each account used, on the earliest
+         transaction date.
+
+       Some limitations:
+
+       o Balance assertions are removed.
+
+       o Balance assignments become missing amounts.
+
+       o Virtual and balanced virtual postings become regular postings.
+
+       o Directives are not converted.
+
+       Here's an example of print's CSV output:
+
+              $ hledger print -Ocsv
+              "txnidx","date","date2","status","code","description","comment","account","amount","commodity","credit","debit","posting-status","posting-comment"
+              "1","2008/01/01","","","","income","","assets:bank:checking","1","$","","1","",""
+              "1","2008/01/01","","","","income","","income:salary","-1","$","1","","",""
+              "2","2008/06/01","","","","gift","","assets:bank:checking","1","$","","1","",""
+              "2","2008/06/01","","","","gift","","income:gifts","-1","$","1","","",""
+              "3","2008/06/02","","","","save","","assets:bank:saving","1","$","","1","",""
+              "3","2008/06/02","","","","save","","assets:bank:checking","-1","$","1","","",""
+              "4","2008/06/03","","*","","eat & shop","","expenses:food","1","$","","1","",""
+              "4","2008/06/03","","*","","eat & shop","","expenses:supplies","1","$","","1","",""
+              "4","2008/06/03","","*","","eat & shop","","assets:cash","-2","$","2","","",""
+              "5","2008/12/31","","*","","pay off","","liabilities:debts","1","$","","1","",""
+              "5","2008/12/31","","*","","pay off","","assets:bank:checking","-1","$","1","","",""
+
+       o There  is  one  CSV record per posting, with the parent transaction's
+         fields repeated.
+
+       o The "txnidx" (transaction index) field shows which postings belong to
+         the same transaction.  (This number might change if transactions  are
+         reordered  within  the file, files are parsed/included in a different
+         order, etc.)
+
+       o The amount is separated into "commodity" (the  symbol)  and  "amount"
+         (numeric quantity) fields.
+
+       o The numeric amount is repeated in either the "credit" or "debit" col-
+         umn,  for convenience.  (Those names are not accurate in the account-
+         ing sense; it just puts negative amounts under  credit  and  zero  or
+         greater amounts under debit.)
+
+   aregister
+       (areg)
+
+       Show  the  transactions  and running balances in one account, with each
+       transaction on one line.
+
+              Flags:
+                   --txn-dates            filter strictly by transaction date, not posting
+                                          date. Warning: this can show a wrong running
+                                          balance.
+                   --no-elide             don't show only 2 commodities per amount
+                   --cumulative           show running total from report start date
+                -H --historical           show historical running total/balance (includes
+                                          postings before report start date) (default)
+                   --invert               display all amounts with reversed sign
+                   --heading=YN           show heading row above table: yes (default) or no
+                -w --width=N              set output width (default: terminal width). -wN,M
+                                          sets description width as well.
+                   --align-all            guarantee alignment across all lines (slower)
+                -O --output-format=FMT    select the output format. Supported formats:
+                                          txt, html, csv, tsv, json.
+                -o --output-file=FILE     write output to FILE. A file extension matching
+                                          one of the above formats selects that format.
+
+       aregister shows the overall transactions affecting a particular account
+       (and any subaccounts).  Each report line represents one transaction  in
+       this  account.   Transactions before the report start date are included
+       in the running balance (--historical mode is  the  default).   You  can
+       suppress this behaviour using the --cumulative option.
+
+       This  is  a more "real world", bank-like view than the register command
+       (which shows individual postings, possibly from multiple accounts,  not
+       necessarily in historical mode).  As a quick rule of thumb: - use areg-
+       ister for reviewing and reconciling real-world asset/liability accounts
+       - use register for reviewing detailed revenues/expenses.
+
+       aregister  requires  one  argument:  the account to report on.  You can
+       write either the full account name, or a case-insensitive  regular  ex-
+       pression which will select the alphabetically first matched account.
+
+       When there are multiple matches, the alphabetically-first choice can be
+       surprising;  eg if you have assets:per:checking 1 and assets:biz:check-
+       ing 2 accounts, hledger areg checking would select  assets:biz:checking
+       2.   It's  just a convenience to save typing, so if in doubt, write the
+       full account name, or a distinctive substring that matches uniquely.
+
+       Transactions involving subaccounts of this account will also be  shown.
+       aregister  ignores depth limits, so its final total will always match a
+       balance report with similar arguments.
+
+       Any additional arguments form a query which will  filter  the  transac-
+       tions shown.  Note some queries will disturb the running balance, caus-
+       ing it to be different from the account's real-world running balance.
+
+       An  example: this shows the transactions and historical running balance
+       during july, in the first account whose name contains "checking":
+
+              $ hledger areg checking date:jul
+
+       Each aregister line item shows:
+
+       o the transaction's date (or the relevant posting's date if  different,
+         see below)
+
+       o the  names  of  all the other account(s) involved in this transaction
+         (probably abbreviated)
+
+       o the total change to this account's balance from this transaction
+
+       o the account's historical running balance after this transaction.
+
+       Transactions making a net change of zero are not shown by default;  add
+       the -E/--empty flag to show them.
+
+       For  performance  reasons,  column widths are chosen based on the first
+       1000 lines; this means unusually wide values in later lines  can  cause
+       visual  discontinuities  as column widths are adjusted.  If you want to
+       ensure perfect alignment, at the cost of more time and memory, use  the
+       --align-all flag.
+
+       By  default,  aregister  shows a heading above the data.  However, when
+       reporting in a language different from English, it is  easier  to  omit
+       this  heading  and  prepend  your  own  one.  For this purpose, use the
+       --heading=no option.
+
+       This command also supports the output destination and output format op-
+       tions.  The output formats supported are txt, csv, tsv (Added in 1.32),
+       html, fods (Added in 1.41) and json.
+
+   aregister and posting dates
+       aregister always shows one line (and date and amount) per  transaction.
+       But  sometimes  transactions have postings with different dates.  Also,
+       not all of a transaction's postings may be within  the  report  period.
+       To resolve this, aregister shows the earliest of the transaction's date
+       and posting dates that is in-period, and the sum of the in-period post-
+       ings.   In  other words it will show a combined line item with just the
+       earliest date, and the running balance  will  (temporarily,  until  the
+       transaction's last posting) be inaccurate.  Use register -H if you need
+       to see the individual postings.
+
+       There is also a --txn-dates flag, which filters strictly by transaction
+       date, ignoring posting dates.  This too can cause an inaccurate running
+       balance.
+
+   register
+       (reg)
+
+       Show postings and their running total.
+
+              Flags:
+                   --cumulative           show running total from report start date
+                                          (default)
+                -H --historical           show historical running total/balance (includes
+                                          postings before report start date)
+                -A --average              show running average of posting amounts instead
+                                          of total (implies --empty)
+                -m --match=DESC           fuzzy search for one recent posting with
+                                          description closest to DESC
+                -r --related              show postings' siblings instead
+                   --invert               display all amounts with reversed sign
+                   --sort=FIELDS          sort by: date, desc, account, amount, absamount,
+                                          or a comma-separated combination of these. For a
+                                          descending sort, prefix with -. (Default: date)
+                -w --width=N              set output width (default: terminal width). -wN,M
+                                          sets description width as well.
+                   --align-all            guarantee alignment across all lines (slower)
+                   --base-url=URLPREFIX   in html output, generate links to hledger-web,
+                                          with this prefix. (Usually the base url shown by
+                                          hledger-web; can also be relative.)
+                -O --output-format=FMT    select the output format. Supported formats:
+                                          txt, csv, tsv, html, fods, json.
+                -o --output-file=FILE     write output to FILE. A file extension matching
+                                          one of the above formats selects that format.
+
+       The register command displays matched postings, across all accounts, in
+       date  order,  with  their  running total or running historical balance.
+       (See also the aregister command, which shows matched transactions in  a
+       specific account.)
+
+       register normally shows line per posting, but note that multi-commodity
+       amounts will occupy multiple lines (one line per commodity).
+
+       It  is  typically  used with a query selecting a particular account, to
+       see that account's activity:
+
+              $ hledger register checking
+              2008/01/01 income               assets:bank:checking            $1           $1
+              2008/06/01 gift                 assets:bank:checking            $1           $2
+              2008/06/02 save                 assets:bank:checking           $-1           $1
+              2008/12/31 pay off              assets:bank:checking           $-1            0
+
+       With --date2, it shows and sorts by secondary date instead.
+
+       For performance reasons, column widths are chosen based  on  the  first
+       1000  lines;  this means unusually wide values in later lines can cause
+       visual discontinuities as column widths are adjusted.  If you  want  to
+       ensure  perfect alignment, at the cost of more time and memory, use the
+       --align-all flag.
+
+       The --historical/-H flag adds the balance from  any  undisplayed  prior
+       postings  to  the  running  total.  This is useful when you want to see
+       only recent activity, with a historically accurate running balance:
+
+              $ hledger register checking -b 2008/6 --historical
+              2008/06/01 gift                 assets:bank:checking            $1           $2
+              2008/06/02 save                 assets:bank:checking           $-1           $1
+              2008/12/31 pay off              assets:bank:checking           $-1            0
+
+       The --depth option limits the amount of sub-account detail displayed.
+
+       The --average/-A flag shows the running average posting amount  instead
+       of the running total (so, the final number displayed is the average for
+       the  whole  report period).  This flag implies --empty (see below).  It
+       is affected by --historical.  It works best when showing just  one  ac-
+       count and one commodity.
+
+       The  --related/-r  flag shows the other postings in the transactions of
+       the postings which would normally be shown.
+
+       The --invert flag negates all amounts.  For example, it can be used  on
+       an income account where amounts are normally displayed as negative num-
+       bers.   It's  also  useful to show postings on the checking account to-
+       gether with the related account:
+
+       The --sort=FIELDS flag sorts by the fields given, which can be  any  of
+       account, amount, absamount, date, or desc/description, optionally sepa-
+       rated  by  commas.   For  example, --sort account,amount will group all
+       transactions in each account, sorted by transaction amount.  Each field
+       can be negated by a preceding -, so --sort -amount will  show  transac-
+       tions ordered from smallest amount to largest amount.
+
+              $ hledger register --related --invert assets:checking
+
+       With a reporting interval, register shows summary postings, one per in-
+       terval, aggregating the postings to each account:
+
+              $ hledger register --monthly income
+              2008/01                 income:salary                          $-1          $-1
+              2008/06                 income:gifts                           $-1          $-2
+
+       Periods  with no activity, and summary postings with a zero amount, are
+       not shown by default; use the --empty/-E flag to see them:
+
+              $ hledger register --monthly income -E
+              2008/01                 income:salary                          $-1          $-1
+              2008/02                                                          0          $-1
+              2008/03                                                          0          $-1
+              2008/04                                                          0          $-1
+              2008/05                                                          0          $-1
+              2008/06                 income:gifts                           $-1          $-2
+              2008/07                                                          0          $-2
+              2008/08                                                          0          $-2
+              2008/09                                                          0          $-2
+              2008/10                                                          0          $-2
+              2008/11                                                          0          $-2
+              2008/12                                                          0          $-2
+
+       Often, you'll want to see just one line per interval.  The --depth  op-
+       tion helps with this, causing subaccounts to be aggregated:
+
+              $ hledger register --monthly assets --depth 1h
+              2008/01                 assets                                  $1           $1
+              2008/06                 assets                                 $-1            0
+              2008/12                 assets                                 $-1          $-1
+
+       Note  when using report intervals, if you specify start/end dates these
+       will be adjusted outward if necessary to contain a whole number of  in-
+       tervals.   This  ensures  that  the  first  and last intervals are full
+       length and comparable to the others in the report.
+
+       With -m DESC/--match=DESC, register does a fuzzy search for one  recent
+       posting whose description is most similar to DESC.  DESC should contain
+       at least two characters.  If there is no similar-enough match, no post-
+       ing will be shown and the program exit code will be non-zero.
+
+   Custom register output
+       register  normally  uses  the  full terminal width (or 80 columns if it
+       can't detect that).  You can override this with 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 de-
+       scription width as part of --width's argument, comma-separated: --width
+       W,D .  Here's a diagram (won't display correctly in --help):
+
+              <--------------------------------- width (W) ---------------------------------->
+              date (10)  description (D)       account (W-41-D)     amount (12)   balance (12)
+              DDDDDDDDDD dddddddddddddddddddd  aaaaaaaaaaaaaaaaaaa  AAAAAAAAAAAA  AAAAAAAAAAAA
+
+       and some examples:
+
+              $ hledger reg                     # use terminal width (or 80 on windows)
+              $ hledger reg -w 100              # use width 100
+              $ hledger reg -w 100,40           # set overall width 100, description width 40
+
+       This command also supports the output destination and output format op-
+       tions  The  output formats supported are txt, csv, tsv (Added in 1.32),
+       and json.
+
+   balancesheet
+       (bs)
+
+       Show the end balances in asset and  liability  accounts.   Amounts  are
+       shown  with  normal  positive sign, as in conventional financial state-
+       ments.
+
+              Flags:
+                   --sum                  show sum of posting amounts (default)
+                   --valuechange          show total change of period-end historical
+                                          balance value (caused by deposits, withdrawals,
+                                          market price fluctuations)
+                   --gain                 show unrealised capital gain/loss (historical
+                                          balance value minus cost basis)
+                   --count                show the count of postings
+                   --change               accumulate amounts from column start to column
+                                          end (in multicolumn reports)
+                   --cumulative           accumulate amounts from report start (specified
+                                          by e.g. -b/--begin) to column end
+                -H --historical           accumulate amounts from journal start to column
+                                          end (includes postings before report start date)
+                                          (default)
+                -l --flat                 show accounts as a flat list (default). Amounts
+                                          exclude subaccount amounts, except where the
+                                          account is depth-clipped.
+                -t --tree                 show accounts as a tree. Amounts include
+                                          subaccount amounts.
+                   --drop=N               flat mode: omit N leading account name parts
+                   --declared             include non-parent declared accounts (best used
+                                          with -E)
+                -A --average              show a row average column (in multicolumn
+                                          reports)
+                -T --row-total            show a row total column (in multicolumn reports)
+                   --summary-only         display only row summaries (e.g. row total,
+                                          average) (in multicolumn reports)
+                -N --no-total             omit the final total row
+                   --no-elide             don't squash boring parent accounts (in tree
+                                          mode)
+                   --format=FORMATSTR     use this custom line format (in simple reports)
+                -S --sort-amount          sort by amount instead of account code/name
+                -% --percent              express values in percentage of each column's
+                                          total
+                   --layout=ARG           how to show multi-commodity amounts:
+                                          'wide[,WIDTH]': all commodities on one line
+                                          'tall'        : each commodity on a new line
+                                          'bare'        : bare numbers, symbols in a column
+                   --base-url=URLPREFIX   in html output, generate hyperlinks to
+                                          hledger-web, with this prefix. (Usually the base
+                                          url shown by hledger-web; can also be relative.)
+                -O --output-format=FMT    select the output format. Supported formats:
+                                          txt, html, csv, tsv, json.
+                -o --output-file=FILE     write output to FILE. A file extension matching
+                                          one of the above formats selects that format.
+
+       This command displays a balance sheet, showing historical  ending  bal-
+       ances of asset and liability accounts.  (To see equity as well, use the
+       balancesheetequity command.)
+
+       Accounts declared with the Asset, Cash or Liability type are shown (see
+       account  types).   Or  if  no  such  accounts  are  declared,  it shows
+       top-level accounts named asset or liability (case insensitive,  plurals
+       allowed) and their subaccounts.
+
+       Example:
+
+              $ hledger balancesheet
+              Balance Sheet 2008-12-31
+
+                                  || 2008-12-31
+              ====================++============
+               Assets             ||
+              --------------------++------------
+               assets:bank:saving ||         $1
+               assets:cash        ||        $-2
+              --------------------++------------
+                                  ||        $-1
+              ====================++============
+               Liabilities        ||
+              --------------------++------------
+               liabilities:debts  ||        $-1
+              --------------------++------------
+                                  ||        $-1
+              ====================++============
+               Net:               ||          0
+
+       This command is a higher-level variant of the balance command, and sup-
+       ports  many  of  that command's features, such as multi-period reports.
+       It is similar to  hledger  balance  -H  assets  liabilities,  but  with
+       smarter  account  detection,  and liabilities displayed with their sign
+       flipped.
+
+       This command also supports the output destination and output format op-
+       tions The output formats supported are txt, csv, tsv (Added  in  1.32),
+       html, and json.
+
+   balancesheetequity
+       (bse)
+
+       This  command  displays a balance sheet, showing historical ending bal-
+       ances of asset, liability and equity accounts.  Amounts are shown  with
+       normal positive sign, as in conventional financial statements.
+
+              Flags:
+                   --sum                  show sum of posting amounts (default)
+                   --valuechange          show total change of period-end historical
+                                          balance value (caused by deposits, withdrawals,
+                                          market price fluctuations)
+                   --gain                 show unrealised capital gain/loss (historical
+                                          balance value minus cost basis)
+                   --count                show the count of postings
+                   --change               accumulate amounts from column start to column
+                                          end (in multicolumn reports)
+                   --cumulative           accumulate amounts from report start (specified
+                                          by e.g. -b/--begin) to column end
+                -H --historical           accumulate amounts from journal start to column
+                                          end (includes postings before report start date)
+                                          (default)
+                -l --flat                 show accounts as a flat list (default). Amounts
+                                          exclude subaccount amounts, except where the
+                                          account is depth-clipped.
+                -t --tree                 show accounts as a tree. Amounts include
+                                          subaccount amounts.
+                   --drop=N               flat mode: omit N leading account name parts
+                   --declared             include non-parent declared accounts (best used
+                                          with -E)
+                -A --average              show a row average column (in multicolumn
+                                          reports)
+                -T --row-total            show a row total column (in multicolumn reports)
+                   --summary-only         display only row summaries (e.g. row total,
+                                          average) (in multicolumn reports)
+                -N --no-total             omit the final total row
+                   --no-elide             don't squash boring parent accounts (in tree
+                                          mode)
+                   --format=FORMATSTR     use this custom line format (in simple reports)
+                -S --sort-amount          sort by amount instead of account code/name
+                -% --percent              express values in percentage of each column's
+                                          total
+                   --layout=ARG           how to show multi-commodity amounts:
+                                          'wide[,WIDTH]': all commodities on one line
+                                          'tall'        : each commodity on a new line
+                                          'bare'        : bare numbers, symbols in a column
+                   --base-url=URLPREFIX   in html output, generate hyperlinks to
+                                          hledger-web, with this prefix. (Usually the base
+                                          url shown by hledger-web; can also be relative.)
+                -O --output-format=FMT    select the output format. Supported formats:
+                                          txt, html, csv, tsv, json.
+                -o --output-file=FILE     write output to FILE. A file extension matching
+                                          one of the above formats selects that format.
+
+       This  report shows accounts declared with the Asset, Cash, Liability or
+       Equity type (see account types).  Or if no such accounts are  declared,
+       it  shows top-level accounts named asset, liability or equity (case in-
+       sensitive, plurals allowed) and their subaccounts.
+
+       Example:
+
+              $ hledger balancesheetequity
+              Balance Sheet With Equity 2008-12-31
+
+                                  || 2008-12-31
+              ====================++============
+               Assets             ||
+              --------------------++------------
+               assets:bank:saving ||         $1
+               assets:cash        ||        $-2
+              --------------------++------------
+                                  ||        $-1
+              ====================++============
+               Liabilities        ||
+              --------------------++------------
+               liabilities:debts  ||        $-1
+              --------------------++------------
+                                  ||        $-1
+              ====================++============
+               Equity             ||
+              --------------------++------------
+              --------------------++------------
+                                  ||          0
+              ====================++============
+               Net:               ||          0
+
+       This command is a higher-level variant of the balance command, and sup-
+       ports many of that command's features, such  as  multi-period  reports.
+       It is similar to hledger balance -H assets liabilities equity, but with
+       smarter  account detection, and liabilities/equity displayed with their
+       sign flipped.
+
+       This report is the easiest way to see if the accounting equation (A+L+E
+       = 0) is satisfied (after you have done a close --retain to  merge  rev-
+       enues  and  expenses  with  equity, and perhaps added --infer-equity to
+       balance your commodity conversions).
+
+       This command also supports the output destination and output format op-
+       tions The output formats supported are txt, csv, tsv, html, and json.
+
+   cashflow
+       (cf)
+
+       This command displays a (simple) cashflow statement,  showing  the  in-
+       flows  and  outflows  affecting "cash" (ie, liquid, easily convertible)
+       assets.  Amounts are shown with normal positive  sign,  as  in  conven-
+       tional financial statements.
+
+              Flags:
+                   --sum                  show sum of posting amounts (default)
+                   --valuechange          show total change of period-end historical
+                                          balance value (caused by deposits, withdrawals,
+                                          market price fluctuations)
+                   --gain                 show unrealised capital gain/loss (historical
+                                          balance value minus cost basis)
+                   --count                show the count of postings
+                   --change               accumulate amounts from column start to column
+                                          end (in multicolumn reports) (default)
+                   --cumulative           accumulate amounts from report start (specified
+                                          by e.g. -b/--begin) to column end
+                -H --historical           accumulate amounts from journal start to column
+                                          end (includes postings before report start date)
+                -l --flat                 show accounts as a flat list (default). Amounts
+                                          exclude subaccount amounts, except where the
+                                          account is depth-clipped.
+                -t --tree                 show accounts as a tree. Amounts include
+                                          subaccount amounts.
+                   --drop=N               flat mode: omit N leading account name parts
+                   --declared             include non-parent declared accounts (best used
+                                          with -E)
+                -A --average              show a row average column (in multicolumn
+                                          reports)
+                -T --row-total            show a row total column (in multicolumn reports)
+                   --summary-only         display only row summaries (e.g. row total,
+                                          average) (in multicolumn reports)
+                -N --no-total             omit the final total row
+                   --no-elide             don't squash boring parent accounts (in tree
+                                          mode)
+                   --format=FORMATSTR     use this custom line format (in simple reports)
+                -S --sort-amount          sort by amount instead of account code/name
+                -% --percent              express values in percentage of each column's
+                                          total
+                   --layout=ARG           how to show multi-commodity amounts:
+                                          'wide[,WIDTH]': all commodities on one line
+                                          'tall'        : each commodity on a new line
+                                          'bare'        : bare numbers, symbols in a column
+                   --base-url=URLPREFIX   in html output, generate hyperlinks to
+                                          hledger-web, with this prefix. (Usually the base
+                                          url shown by hledger-web; can also be relative.)
+                -O --output-format=FMT    select the output format. Supported formats:
+                                          txt, html, csv, tsv, json.
+                -o --output-file=FILE     write output to FILE. A file extension matching
+                                          one of the above formats selects that format.
+
+       This  report  shows  accounts  declared with the Cash type (see account
+       types).  Or if no such accounts are declared, it shows accounts
+
+       o under a top-level account named asset (case insensitive,  plural  al-
+         lowed)
+
+       o whose name contains some variation of cash, bank, checking or saving.
+
+       More precisely: all accounts matching this case insensitive regular ex-
+       pression:
+
+       ^assets?(:.+)?:(cash|bank|che(ck|que?)(ing)?|savings?|currentcash)(:|$)
+
+       and their subaccounts.
+
+       An example cashflow report:
+
+              $ hledger cashflow
+              Cashflow Statement 2008
+
+                                  || 2008
+              ====================++======
+               Cash flows         ||
+              --------------------++------
+               assets:bank:saving ||   $1
+               assets:cash        ||  $-2
+              --------------------++------
+                                  ||  $-1
+
+       This command is a higher-level variant of the balance command, and sup-
+       ports  many  of  that command's features, such as multi-period reports.
+       It is  similar  to  hledger  balance  assets  not:fixed  not:investment
+       not:receivable, but with smarter account detection.
+
+       This command also supports the output destination and output format op-
+       tions  The  output formats supported are txt, csv, tsv (Added in 1.32),
+       html, and json.
+
+   incomestatement
+       (is)
+
+       Show revenue inflows and expense outflows  during  the  report  period.
+       Amounts  are shown with normal positive sign, as in conventional finan-
+       cial statements.
+
+              Flags:
+                   --sum                  show sum of posting amounts (default)
+                   --valuechange          show total change of period-end historical
+                                          balance value (caused by deposits, withdrawals,
+                                          market price fluctuations)
+                   --gain                 show unrealised capital gain/loss (historical
+                                          balance value minus cost basis)
+                   --count                show the count of postings
+                   --change               accumulate amounts from column start to column
+                                          end (in multicolumn reports) (default)
+                   --cumulative           accumulate amounts from report start (specified
+                                          by e.g. -b/--begin) to column end
+                -H --historical           accumulate amounts from journal start to column
+                                          end (includes postings before report start date)
+                -l --flat                 show accounts as a flat list (default). Amounts
+                                          exclude subaccount amounts, except where the
+                                          account is depth-clipped.
+                -t --tree                 show accounts as a tree. Amounts include
+                                          subaccount amounts.
+                   --drop=N               flat mode: omit N leading account name parts
+                   --declared             include non-parent declared accounts (best used
+                                          with -E)
+                -A --average              show a row average column (in multicolumn
+                                          reports)
+                -T --row-total            show a row total column (in multicolumn reports)
+                   --summary-only         display only row summaries (e.g. row total,
+                                          average) (in multicolumn reports)
+                -N --no-total             omit the final total row
+                   --no-elide             don't squash boring parent accounts (in tree
+                                          mode)
+                   --format=FORMATSTR     use this custom line format (in simple reports)
+                -S --sort-amount          sort by amount instead of account code/name
+                -% --percent              express values in percentage of each column's
+                                          total
+                   --layout=ARG           how to show multi-commodity amounts:
+                                          'wide[,WIDTH]': all commodities on one line
+                                          'tall'        : each commodity on a new line
+                                          'bare'        : bare numbers, symbols in a column
+                   --base-url=URLPREFIX   in html output, generate hyperlinks to
+                                          hledger-web, with this prefix. (Usually the base
+                                          url shown by hledger-web; can also be relative.)
+                -O --output-format=FMT    select the output format. Supported formats:
+                                          txt, html, csv, tsv, json.
+                -o --output-file=FILE     write output to FILE. A file extension matching
+                                          one of the above formats selects that format.
+
+       This command displays an income statement,  showing  revenues  and  ex-
+       penses during one or more periods.
+
+       It  shows  accounts  declared with the Revenue or Expense type (see ac-
+       count types).  Or if no such accounts are declared, it shows  top-level
+       accounts  named revenue or income or expense (case insensitive, plurals
+       allowed) and their subaccounts.
+
+       Example:
+
+              $ hledger incomestatement
+              Income Statement 2008
+
+                                 || 2008
+              ===================++======
+               Revenues          ||
+              -------------------++------
+               income:gifts      ||   $1
+               income:salary     ||   $1
+              -------------------++------
+                                 ||   $2
+              ===================++======
+               Expenses          ||
+              -------------------++------
+               expenses:food     ||   $1
+               expenses:supplies ||   $1
+              -------------------++------
+                                 ||   $2
+              ===================++======
+               Net:              ||    0
+
+       This command is a higher-level variant of the balance command, and sup-
+       ports many of that command's features, such  as  multi-period  reports.
+       It is similar to hledger balance '(revenues|income)' expenses, but with
+       smarter  account  detection,  and  revenues/income displayed with their
+       sign flipped.
+
+       This command also supports the output destination and output format op-
+       tions The output formats supported are txt, csv, tsv (Added  in  1.32),
+       html, and json.
+
+Advanced report commands
+   balance
+       (bal)
+
+       A  flexible,  general purpose "summing" report that shows accounts with
+       some kind of numeric data.  This can be balance changes per period, end
+       balances, budget performance, unrealised capital gains, etc.
+
+              Flags:
+                   --sum                  show sum of posting amounts (default)
+                   --valuechange          show total change of value of period-end
+                                          historical balances (caused by deposits,
+                                          withdrawals, market price fluctuations)
+                   --gain                 show unrealised capital gain/loss (historical
+                                          balance value minus cost basis)
+                   --budget[=DESCPAT]     show sum of posting amounts together with budget
+                                          goals defined by periodic
+                                          transactions. With a DESCPAT argument (must be
+                                          separated by = not space),
+                                          use only periodic transactions with matching
+                                          description
+                                          (case insensitive substring match).
+                   --count                show the count of postings
+                   --change               accumulate amounts from column start to column
+                                          end (in multicolumn reports, default)
+                   --cumulative           accumulate amounts from report start (specified
+                                          by e.g. -b/--begin) to column end
+                -H --historical           accumulate amounts from journal start to column
+                                          end (includes postings before report start date)
+                -l --flat                 show accounts as a flat list (default). Amounts
+                                          exclude subaccount amounts, except where the
+                                          account is depth-clipped.
+                -t --tree                 show accounts as a tree. Amounts include
+                                          subaccount amounts.
+                   --drop=N               omit N leading account name parts (in flat mode)
+                   --declared             include non-parent declared accounts (best used
+                                          with -E)
+                -A --average              show a row average column (in multicolumn
+                                          reports)
+                -T --row-total            show a row total column (in multicolumn reports)
+                   --summary-only         display only row summaries (e.g. row total,
+                                          average) (in multicolumn reports)
+                -N --no-total             omit the final total row
+                   --no-elide             don't squash boring parent accounts (in tree
+                                          mode)
+                   --format=FORMATSTR     use this custom line format (in simple reports)
+                -S --sort-amount          sort by amount instead of account code/name (in
+                                          flat mode). With multiple columns, sorts by the row
+                                          total, or by row average if that is displayed.
+                -% --percent              express values in percentage of each column's
+                                          total
+                -r --related              show the other accounts transacted with, instead
+                   --invert               display all amounts with reversed sign
+                   --transpose            switch rows and columns (use vertical time axis)
+                   --layout=ARG           how to lay out multi-commodity amounts and the
+                                          overall table:
+                                          'wide[,W]': commodities on same line, up to W wide
+                                          'tall'    : commodities on separate lines
+                                          'bare'    : commodity symbols in a separate column
+                                          'tidy'    : each data field in its own column
+                   --base-url=URLPREFIX   in html output, generate links to hledger-web,
+                                          with this prefix. (Usually the base url shown by
+                                          hledger-web; can also be relative.)
+                -O --output-format=FMT    select the output format. Supported formats:
+                                          txt, html, csv, tsv, json, fods.
+                -o --output-file=FILE     write output to FILE. A file extension matching
+                                          one of the above formats selects that format.
+
+       balance is one of hledger's oldest and  most  versatile  commands,  for
+       listing  account  balances,  balance changes, values, value changes and
+       more, during one time period or many.  Generally it shows a table, with
+       rows representing accounts, and columns representing periods.
+
+       Note there are some higher-level variants of the balance  command  with
+       convenient  defaults,  which  can be simpler to use: balancesheet, bal-
+       ancesheetequity, cashflow and incomestatement.  When you need more con-
+       trol, then use balance.
+
+   balance features
+       Here's a quick overview of the balance command's features, followed  by
+       more  detailed  descriptions and examples.  Many of these work with the
+       higher-level commands as well.
+
+       balance can show..
+
+       o accounts as a list (-l) or a tree (-t)
+
+       o optionally depth-limited (-[1-9])
+
+       o sorted by declaration order and name, or by amount
+
+       ..and their..
+
+       o balance changes (the default)
+
+       o or actual and planned balance changes (--budget)
+
+       o or value of balance changes (-V)
+
+       o or change of balance values (--valuechange)
+
+       o or unrealised capital gain/loss (--gain)
+
+       o or balance changes from sibling postings (--related/-r)
+
+       o or postings count (--count)
+
+       ..in..
+
+       o one time period (the whole journal period by default)
+
+       o or multiple periods (-D, -W, -M, -Q, -Y, -p INTERVAL)
+
+       ..either..
+
+       o per period (the default)
+
+       o or accumulated since report start date (--cumulative)
+
+       o or accumulated since account creation (--historical/-H)
+
+       ..possibly converted to..
+
+       o cost (--value=cost[,COMM]/--cost/-B)
+
+       o or market value, as of transaction dates (--value=then[,COMM])
+
+       o or at period ends (--value=end[,COMM])
+
+       o or now (--value=now)
+
+       o or at some other date (--value=YYYY-MM-DD)
+
+       ..with..
+
+       o totals (-T), averages (-A), percentages (-%),  inverted  sign  (--in-
+         vert)
+
+       o rows and columns swapped (--transpose)
+
+       o another field used as account name (--pivot)
+
+       o custom-formatted line items (single-period reports only) (--format)
+
+       o commodities displayed on the same line or multiple lines (--layout)
+
+       This command supports the output destination and output format options,
+       with output formats txt, csv, tsv (Added in 1.32), json, and (multi-pe-
+       riod  reports  only:)  html,  fods (Added in 1.40).  In txt output in a
+       colour-supporting terminal, negative amounts are shown in red.
+
+   Simple balance report
+       With no arguments, balance shows a  list  of  all  accounts  and  their
+       change  of  balance  - ie, the sum of posting amounts, both inflows and
+       outflows - during the entire period of  the  journal.   ("Simple"  here
+       means  just  one  column of numbers, covering a single period.  You can
+       also have multi-period reports, described later.)
+
+       For real-world accounts, these numbers will normally be their end  bal-
+       ance at the end of the journal period; more on this below.
+
+       Accounts  are  sorted  by declaration order if any, and then alphabeti-
+       cally by account name.  For instance (using examples/sample.journal):
+
+              $ hledger -f examples/sample.journal bal
+                                $1  assets:bank:saving
+                               $-2  assets:cash
+                                $1  expenses:food
+                                $1  expenses:supplies
+                               $-1  income:gifts
+                               $-1  income:salary
+                                $1  liabilities:debts
+              --------------------
+                                 0
+
+       Accounts with a zero balance (and no non-zero subaccounts, in tree mode
+       - see below) are hidden by default.  Use -E/--empty to show  them  (re-
+       vealing assets:bank:checking here):
+
+              $ hledger -f examples/sample.journal bal  -E
+                                 0  assets:bank:checking
+                                $1  assets:bank:saving
+                               $-2  assets:cash
+                                $1  expenses:food
+                                $1  expenses:supplies
+                               $-1  income:gifts
+                               $-1  income:salary
+                                $1  liabilities:debts
+              --------------------
+                                 0
+
+       The  total  of  the amounts displayed is shown as the last line, unless
+       -N/--no-total is used.
+
+   Balance report line format
+       For single-period balance reports displayed in the terminal (only), you
+       can use --format FMT to customise the format and content of each  line.
+       Eg:
+
+              $ hledger -f examples/sample.journal balance --format "%20(account) %12(total)"
+                            assets          $-1
+                       bank:saving           $1
+                              cash          $-2
+                          expenses           $2
+                              food           $1
+                          supplies           $1
+                            income          $-2
+                             gifts          $-1
+                            salary          $-1
+                 liabilities:debts           $1
+              ---------------------------------
+                                              0
+
+       The  FMT  format  string  specifies  the formatting applied to each ac-
+       count/balance pair.  It may contain any suitable text, with data fields
+       interpolated like so:
+
+       %[MIN][.MAX](FIELDNAME)
+
+       o MIN pads with spaces to at least this width (optional)
+
+       o MAX truncates at this width (optional)
+
+       o FIELDNAME must be enclosed in parentheses, and can be one of:
+
+         o depth_spacer - a number of spaces equal to the account's depth,  or
+           if MIN is specified, MIN * depth spaces.
+
+         o account - the account's name
+
+         o total - the account's balance/posted total, right justified
+
+       Also,  FMT  can begin with an optional prefix to control how multi-com-
+       modity amounts are rendered:
+
+       o %_ - render on multiple lines, bottom-aligned (the default)
+
+       o %^ - render on multiple lines, top-aligned
+
+       o %, - render on one line, comma-separated
+
+       There are some quirks.  Eg in one-line mode, %(depth_spacer) has no ef-
+       fect, instead %(account) has indentation  built  in.    Experimentation
+       may be needed to get pleasing results.
+
+       Some example formats:
+
+       o %(total) - the account's total
+
+       o %-20.20(account)  -  the account's name, left justified, padded to 20
+         characters and clipped at 20 characters
+
+       o %,%-50(account)  %25(total) - account name padded to  50  characters,
+         total  padded to 20 characters, with multiple commodities rendered on
+         one line
+
+       o %20(total)  %2(depth_spacer)%-(account) - the default format for  the
+         single-column balance report
+
+   Filtered balance report
+       You  can  show  fewer  accounts,  a  different time period, totals from
+       cleared transactions only, etc.  by using query arguments or options to
+       limit the postings being matched.  Eg:
+
+              $ hledger -f examples/sample.journal bal --cleared assets date:200806
+                               $-2  assets:cash
+              --------------------
+                               $-2
+
+   List or tree mode
+       By default, or with -l/--flat, accounts are shown as a flat  list  with
+       their full names visible, as in the examples above.
+
+       With  -t/--tree,  the  account  hierarchy  is  shown, with subaccounts'
+       "leaf" names indented below their parent:
+
+              $ hledger -f examples/sample.journal balance
+                               $-1  assets
+                                $1    bank:saving
+                               $-2    cash
+                                $2  expenses
+                                $1    food
+                                $1    supplies
+                               $-2  income
+                               $-1    gifts
+                               $-1    salary
+                                $1  liabilities:debts
+              --------------------
+                                 0
+
+       Notes:
+
+       o "Boring" accounts are combined with their subaccount for more compact
+         output, unless --no-elide is used.  Boring accounts have  no  balance
+         of  their own and just one subaccount (eg assets:bank and liabilities
+         above).
+
+       o All balances shown are "inclusive", ie including  the  balances  from
+         all  subaccounts.   Note  this  means  some repetition in the output,
+         which requires explanation when sharing reports with non-plaintextac-
+         counting-users.  A tree mode report's final total is the sum  of  the
+         top-level balances shown, not of all the balances shown.
+
+       o Each  group of sibling accounts (ie, under a common parent) is sorted
+         separately.
+
+   Depth limiting
+       With a depth:NUM query, or --depth NUM option, or just  -NUM  (eg:  -3)
+       balance  reports will show accounts only to the specified depth, hiding
+       the deeper subaccounts.  This can be useful  for  getting  an  overview
+       without too much detail.
+
+       Account  balances  at  the depth limit always include the balances from
+       any deeper subaccounts (even in list mode).  Eg, limiting to depth 1:
+
+              $ hledger -f examples/sample.journal balance -1
+                               $-1  assets
+                                $2  expenses
+                               $-2  income
+                                $1  liabilities
+              --------------------
+                                 0
+
+   Dropping top-level accounts
+       You can also hide one or  more  top-level  account  name  parts,  using
+       --drop NUM.  This can be useful for hiding repetitive top-level account
+       names:
+
+              $ hledger -f examples/sample.journal bal expenses --drop 1
+                                $1  food
+                                $1  supplies
+              --------------------
+                                $2
+
+   Showing declared accounts
+       With  --declared, accounts which have been declared with an account di-
+       rective will be included in the balance report, even if  they  have  no
+       transactions.  (Since they will have a zero balance, you will also need
+       -E/--empty to see them.)
+
+       More  precisely,  leaf  declared accounts (with no subaccounts) will be
+       included, since those are usually the more useful in reports.
+
+       The idea of this is to be able to see a useful "complete"  balance  re-
+       port, even when you don't have transactions in all of your declared ac-
+       counts yet.
+
+   Sorting by amount
+       With  -S/--sort-amount,  accounts with the largest (most positive) bal-
+       ances are shown first.   Eg:  hledger  bal  expenses  -MAS  shows  your
+       biggest  averaged monthly expenses first.  When more than one commodity
+       is present, they will be sorted by the alphabetically earliest  commod-
+       ity  first, and then by subsequent commodities (if an amount is missing
+       a commodity, it is treated as 0).
+
+       Revenues and liability balances are typically negative, however, so  -S
+       shows  these  in reverse order.  To work around this, you can add --in-
+       vert to flip the signs.  (Or, use  one  of  the  higher-level  reports,
+       which flip the sign automatically.  Eg: hledger incomestatement -MAS).
+
+   Percentages
+       With  -%/--percent, balance reports show each account's value expressed
+       as a percentage of the (column) total.
+
+       Note it is not useful to calculate percentages if the amounts in a col-
+       umn have mixed signs.  In this case, make a separate  report  for  each
+       sign, eg:
+
+              $ hledger bal -% amt:`>0`
+              $ hledger bal -% amt:`<0`
+
+       Similarly,  if  the amounts in a column have mixed commodities, convert
+       them to one commodity with -B, -V, -X or --value, or  make  a  separate
+       report for each commodity:
+
+              $ hledger bal -% cur:\\$
+              $ hledger bal -% cur:
+
+   Multi-period balance report
+       With   a   report   interval   (set  by  the  -D/--daily,  -W/--weekly,
+       -M/--monthly, -Q/--quarterly, -Y/--yearly, or -p/--period  flag),  bal-
+       ance  shows a tabular report, with columns representing successive time
+       periods (and a title):
+
+              $ hledger -f examples/sample.journal bal --quarterly income expenses -E
+              Balance changes in 2008:
+
+                                 ||  2008q1  2008q2  2008q3  2008q4
+              ===================++=================================
+               expenses:food     ||       0      $1       0       0
+               expenses:supplies ||       0      $1       0       0
+               income:gifts      ||       0     $-1       0       0
+               income:salary     ||     $-1       0       0       0
+              -------------------++---------------------------------
+                                 ||     $-1      $1       0       0
+
+       Notes:
+
+       o The report's start/end dates will be expanded, if necessary, to fully
+         encompass the displayed subperiods (so that the first and last subpe-
+         riods have the same duration as the others).
+
+       o Leading and trailing periods (columns) containing all zeroes are  not
+         shown, unless -E/--empty is used.
+
+       o Accounts   (rows)   containing  all  zeroes  are  not  shown,  unless
+         -E/--empty is used.
+
+       o Amounts with many commodities are shown in abbreviated  form,  unless
+         --no-elide is used.
+
+       o Average  and/or  total columns can be added with the -A/--average and
+         -T/--row-total flags.
+
+       o The --transpose flag can be used to exchange rows and columns.
+
+       o The --pivot FIELD option causes a different transaction field  to  be
+         used as "account name".  See PIVOTING.
+
+       o The  --summary-only flag (--summary also works) hides all but the To-
+         tal and Average columns (those should be enabled with --row-total and
+         -A/--average).
+
+       Multi-period reports with many periods can be too wide for easy viewing
+       in the terminal.  Here are some ways to handle that:
+
+       o Hide the totals row with -N/--no-total
+
+       o Filter to a single currency with cur:
+
+       o Convert to a single currency with -V [--infer-market-price]
+
+       o Use a more compact layout like --layout=bare
+
+       o Maximize the terminal window
+
+       o Reduce the terminal's font size
+
+       o View with a pager like less, eg: hledger bal -D  --color=yes  |  less
+         -RS
+
+       o Output  as  CSV and use a CSV viewer like visidata (hledger bal -D -O
+         csv | vd -f csv), Emacs' csv-mode  (M-x  csv-mode,  C-c  C-a),  or  a
+         spreadsheet (hledger bal -D -o a.csv && open a.csv)
+
+       o Output  as  HTML and view with a browser: hledger bal -D -o a.html &&
+         open a.html
+
+   Balance change, end balance
+       It's important to be clear on the meaning of the numbers shown in  bal-
+       ance reports.  Here is some terminology we use:
+
+       A  balance  change  is the net amount added to, or removed from, an ac-
+       count during some period.
+
+       An end balance is the amount accumulated in an account as of some  date
+       (and  some  time,  but hledger doesn't store that; assume end of day in
+       your timezone).  It is the sum of previous balance changes.
+
+       We call it a historical end balance if it includes all balance  changes
+       since the account was created.  For a real world account, this means it
+       will  match  the  "historical record", eg the balances reported in your
+       bank statements or bank web UI.  (If they are correct!)
+
+       In general, balance changes are what you want  to  see  when  reviewing
+       revenues and expenses, and historical end balances are what you want to
+       see when reviewing or reconciling asset, liability and equity accounts.
+
+       balance  shows  balance changes by default.  To see accurate historical
+       end balances:
+
+       1. Initialise account starting  balances  with  an  "opening  balances"
+          transaction  (a  transfer  from  equity  to the account), unless the
+          journal covers the account's full lifetime.
+
+       2. Include all of of the account's prior postings in the report, by not
+          specifying a report start date,  or  by  using  the  -H/--historical
+          flag.  (-H causes report start date to be ignored when summing post-
+          ings.)
+
+   Balance report types
+       The  balance  command is quite flexible; here is the full detail on how
+       to control what it reports.  If the following seems complicated,  don't
+       worry  -  this is for advanced reporting, and it does take time and ex-
+       perimentation to get familiar with all the report modes.
+
+       There are three important option groups:
+
+       hledger balance  [CALCULATIONTYPE]  [ACCUMULATIONTYPE]  [VALUATIONTYPE]
+       ...
+
+   Calculation type
+       The basic calculation to perform for each table cell.  It is one of:
+
+       o --sum : sum the posting amounts (default)
+
+       o --budget : sum the amounts, but also show the budget goal amount (for
+         each account/period)
+
+       o --valuechange : show the change in period-end historical balance val-
+         ues  (caused  by  deposits, withdrawals, and/or market price fluctua-
+         tions)
+
+       o --gain : show the unrealised capital gain/loss, (the  current  valued
+         balance minus each amount's original cost)
+
+       o --count : show the count of postings
+
+   Accumulation type
+       How  amounts  should  accumulate  across a report's subperiods/columns.
+       Another way to say it: which time period's postings  should  contribute
+       to each cell's calculation.  It is one of:
+
+       o --change  :  calculate with postings from column start to column end,
+         ie "just this column".   Typically  used  to  see  revenues/expenses.
+         (default for balance, cashflow, incomestatement)
+
+       o --cumulative  :  calculate  with postings from report start to column
+         end, ie "previous columns plus this column".  Typically used to  show
+         changes accumulated since the report's start date.  Not often used.
+
+       o --historical/-H  : calculate with postings from journal start to col-
+         umn end, ie "all postings from before report start  date  until  this
+         column's  end".  Typically used to see historical end balances of as-
+         sets/liabilities/equity.  (default for  balancesheet,  balancesheete-
+         quity)
+
+   Valuation type
+       Which  kind  of value or cost conversion should be applied, if any, be-
+       fore displaying the report.  It is one of:
+
+       o no valuation type : don't convert to cost or value (default)
+
+       o --value=cost[,COMM] : convert amounts to  cost  (then  optionally  to
+         some other commodity)
+
+       o --value=then[,COMM]  : convert amounts to market value on transaction
+         dates
+
+       o --value=end[,COMM] : convert amounts to market value  on  period  end
+         date(s)
+       (default with --valuechange, --gain)
+
+       o --value=now[,COMM] : convert amounts to market value on today's date
+
+       o --value=YYYY-MM-DD[,COMM]  :  convert  amounts to market value on an-
+         other date
+
+       or one of the equivalent simpler flags:
+
+       o -B/--cost : like --value=cost (though, note --cost  and  --value  are
+         independent options which can both be used at once)
+
+       o -V/--market : like --value=end
+
+       o -X COMM/--exchange COMM : like --value=end,COMM
+
+       See Cost reporting and Value reporting for more about these.
+
+   Combining balance report types
+       Most  combinations  of these options should produce reasonable reports,
+       but if you find any that seem wrong or misleading, let  us  know.   The
+       following restrictions are applied:
+
+       o --valuechange implies --value=end
+
+       o --valuechange  makes  --change  the  default  when used with the bal-
+         ancesheet/balancesheetequity commands
+
+       o --cumulative or --historical disables --row-total/-T
+
+       For reference, here is what the combinations of accumulation and valua-
+       tion show:
+
+       Valua-     no valuation       --value= then       --value= end      --value=
+       tion:>                                                              YYYY-MM-DD
+       Accumu-                                                             /now
+       lation:v
+       -----------------------------------------------------------------------------------
+       --change   change in period   sum   of    post-   period-end        DATE-value  of
+                                     ing-date   market   value of change   change  in pe-
+                                     values in period    in period         riod
+       --cumu-    change from  re-   sum   of    post-   period-end        DATE-value  of
+       lative     port   start  to   ing-date   market   value of change   change    from
+                  period end         values  from  re-   from     report   report   start
+                                     port start to pe-   start to period   to period end
+                                     riod end            end
+       --his-     change      from   sum   of    post-   period-end        DATE-value  of
+       torical    journal start to   ing-date   market   value of change   change    from
+       /-H        period end (his-   values from jour-   from    journal   journal  start
+                  torical end bal-   nal start to  pe-   start to period   to period end
+                  ance)              riod end            end
+
+   Budget report
+       The --budget report type is like a regular balance report, but with two
+       main differences:
+
+       o Budget goals and performance percentages are also shown, in brackets
+
+       o Accounts which don't have budget goals are hidden by default.
+
+       This  is useful for comparing planned and actual income, expenses, time
+       usage, etc.
+
+       Periodic transaction rules are used to define budget goals.  For  exam-
+       ple,  here's  a periodic rule defining monthly goals for bus travel and
+       food expenses:
+
+              ;; Budget
+              ~ monthly
+                (expenses:bus)              $30
+                (expenses:food)            $400
+
+       After recording some actual expenses,
+
+              ;; Two months worth of expenses
+              2017-11-01
+                income                   $-1950
+                expenses:bus                $35
+                expenses:food:groceries    $310
+                expenses:food:dining        $42
+                expenses:movies             $38
+                assets:bank:checking
+
+              2017-12-01
+                income                   $-2100
+                expenses:bus                $53
+                expenses:food:groceries    $380
+                expenses:food:dining        $32
+                expenses:gifts             $100
+                assets:bank:checking
+
+       we can see a budget report like this:
+
+              $ hledger bal -M --budget
+              Budget performance in 2017-11-01..2017-12-31:
+
+                             ||                  Nov                   Dec
+              ===============++============================================
+               <unbudgeted>  || $-425                 $-565
+               expenses      ||  $425 [ 99% of $430]   $565 [131% of $430]
+               expenses:bus  ||   $35 [117% of  $30]    $53 [177% of  $30]
+               expenses:food ||  $352 [ 88% of $400]   $412 [103% of $400]
+              ---------------++--------------------------------------------
+                             ||     0 [  0% of $430]      0 [  0% of $430]
+
+       This is "goal-based budgeting"; you define goals for accounts and peri-
+       ods, often recurring, and hledger shows  performance  relative  to  the
+       goals.   This  contrasts  with  "envelope budgeting", which is more de-
+       tailed and strict - useful when cash is tight, but  also  quite  a  bit
+       more  work.  https://plaintextaccounting.org/Budgeting has more on this
+       topic.
+
+   Using the budget report
+       Historically this report has been  confusing  and  fragile.   hledger's
+       version  should  be  relatively robust and intuitive, but you may still
+       find surprises.  Here are more notes to help with  learning  and  trou-
+       bleshooting.
+
+       o In  the  above  example, expenses:bus and expenses:food are shown be-
+         cause they have budget goals during the report period.
+
+       o Their parent expenses is also shown,  with  budget  goals  aggregated
+         from the children.
+
+       o The  subaccounts expenses:food:groceries and expenses:food:dining are
+         not shown since they have no budget goal of their own, but they  con-
+         tribute to expenses:food's actual amount.
+
+       o Unbudgeted  accounts  expenses:movies and expenses:gifts are also not
+         shown, but they contribute to expenses's actual amount.
+
+       o The other unbudgeted accounts  income  and  assets:bank:checking  are
+         grouped as <unbudgeted>.
+
+       o --depth  or depth: can be used to limit report depth in the usual way
+         (but will not reveal unbudgeted subaccounts).
+
+       o Amounts are always inclusive of subaccounts (even in -l/--list mode).
+
+       o Numbers displayed in a --budget report will not always agree with the
+         totals, because  of  hidden  unbudgeted  accounts;  this  is  normal.
+         -E/--empty can be used to reveal the hidden accounts.
+
+       o In the periodic rules used for setting budget goals, unbalanced post-
+         ings are convenient.
+
+       o You  can filter budget reports with the usual queries, eg to focus on
+         particular accounts.  It's common to restrict them to just  expenses.
+         (The  <unbudgeted>  account  is occasionally hard to exclude; this is
+         because of date surprises, discussed below.)
+
+       o When you have multiple currencies, you may want to  convert  them  to
+         one  (-X  COMM  --infer-market-prices) and/or show just one at a time
+         (cur:COMM).  If you do need to  show  multiple  currencies  at  once,
+         --layout bare can be helpful.
+
+       o You  can "roll over" amounts (actual and budgeted) to the next period
+         with --cumulative.
+
+       See also: https://hledger.org/budgeting.html.
+
+   Budget date surprises
+       With small data, or when starting out, some  of  the  generated  budget
+       goal  transaction dates might fall outside the report periods.  Eg with
+       the following journal and report, the first period appears to  have  no
+       expenses:food  budget.   (Also  the  <unbudgeted> account should be ex-
+       cluded by the expenses query, but isn't.):
+
+              ~ monthly in 2020
+                (expenses:food)  $500
+
+              2020-01-15
+                expenses:food    $400
+                assets:checking
+
+              $ hledger bal --budget expenses
+              Budget performance in 2020-01-15:
+
+                             ||         2020-01-15
+              ===============++====================
+               <unbudgeted>  || $400
+               expenses:food ||    0 [ 0% of $500]
+              ---------------++--------------------
+                             || $400 [80% of $500]
+
+       In this case, the budget goal transactions are generated on first  days
+       of  of month (this can be seen with hledger print --forecast tag:gener-
+       ated expenses).  Whereas the report period defaults to  just  the  15th
+       day  of  january (this can be seen from the report table's column head-
+       ings).
+
+       To fix this kind of thing, be more explicit  about  the  report  period
+       (and/or  the periodic rules' dates).  In this case, adding -b 2020 does
+       the trick.
+
+   Selecting budget goals
+       By default, the budget report uses all available  periodic  transaction
+       rules  to  generate goals.  This includes rules with a different report
+       interval from your report.  Eg if you have daily,  weekly  and  monthly
+       periodic  rules, all of these will contribute to the goals in a monthly
+       budget report.
+
+       You can select a subset of periodic rules by providing an  argument  to
+       the  --budget  flag.   --budget=DESCPAT  will  match all periodic rules
+       whose description contains DESCPAT, a case-insensitive substring (not a
+       regular expression or query).  This means you can  give  your  periodic
+       rules  descriptions (remember that two spaces are needed between period
+       expression and description), and then select from multiple budgets  de-
+       fined in your journal.
+
+   Budgeting vs forecasting
+       --forecast  and --budget both use the periodic transaction rules in the
+       journal to generate  temporary  transactions  for  reporting  purposes.
+       However  they  are  separate  features - though you can use both at the
+       same time if you want.  Here are some differences between them:
+
+       --forecast                               --budget
+       --------------------------------------------------------------------------
+       is a general option; it enables  fore-   is  a balance command option; it
+       casting with all reports                 selects  the  balance   report's
+                                                budget mode
+       generates  visible  transactions which   generates invisible transactions
+       appear in reports                        which produce goal amounts
+       generates forecast  transactions  from   generates  budget  goal transac-
+       after the last regular transaction, to   tions throughout the report  pe-
+       the  end of the report period; or with   riod,  optionally  restricted by
+       an argument --forecast=PERIODEXPR gen-   periods specified in  the  peri-
+       erates them throughout  the  specified   odic transaction rules
+       period,  both optionally restricted by
+       periods  specified  in  the   periodic
+       transaction rules
+       uses all periodic rules                  uses all periodic rules; or with
+                                                an   argument   --budget=DESCPAT
+                                                uses just the rules  matched  by
+                                                DESCPAT
+
+   Balance report layout
+       The --layout option affects how balance and the other balance-like com-
+       mands  show  multi-commodity amounts and commodity symbols.  It can im-
+       prove readability, for humans and/or machines (other software).  It has
+       four possible values:
+
+       o --layout=wide[,WIDTH]: commodities are shown on a  single  line,  op-
+         tionally elided to WIDTH
+
+       o --layout=tall: each commodity is shown on a separate line
+
+       o --layout=bare: commodity symbols are in their own column, amounts are
+         bare numbers
+
+       o --layout=tidy:  data  is  normalised  to easily-consumed "tidy" form,
+         with one row per data value.  (This one is currently  supported  only
+         by the balance command.)
+
+       Here  are  the  --layout modes supported by each output format Only CSV
+       output supports all of them:
+
+       -      txt   csv   html   json   sql
+       -------------------------------------
+       wide   Y     Y     Y
+       tall   Y     Y     Y
+       bare   Y     Y     Y
+       tidy         Y
+
+       Examples:
+
+   Wide layout
+       With many commodities, reports can be very wide:
+
+              $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=wide
+              Balance changes in 2012-01-01..2014-12-31:
+
+                                ||                                          2012                                                     2013                                             2014                                                      Total
+              ==================++====================================================================================================================================================================================================================
+               Assets:US:ETrade || 10.00 ITOT, 337.18 USD, 12.00 VEA, 106.00 VHT  70.00 GLD, 18.00 ITOT, -98.12 USD, 10.00 VEA, 18.00 VHT  -11.00 ITOT, 4881.44 USD, 14.00 VEA, 170.00 VHT  70.00 GLD, 17.00 ITOT, 5120.50 USD, 36.00 VEA, 294.00 VHT
+              ------------------++--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+                                || 10.00 ITOT, 337.18 USD, 12.00 VEA, 106.00 VHT  70.00 GLD, 18.00 ITOT, -98.12 USD, 10.00 VEA, 18.00 VHT  -11.00 ITOT, 4881.44 USD, 14.00 VEA, 170.00 VHT  70.00 GLD, 17.00 ITOT, 5120.50 USD, 36.00 VEA, 294.00 VHT
+
+       A width limit reduces the width, but some commodities will be hidden:
+
+              $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=wide,32
+              Balance changes in 2012-01-01..2014-12-31:
+
+                                ||                             2012                             2013                   2014                            Total
+              ==================++===========================================================================================================================
+               Assets:US:ETrade || 10.00 ITOT, 337.18 USD, 2 more..  70.00 GLD, 18.00 ITOT, 3 more..  -11.00 ITOT, 3 more..  70.00 GLD, 17.00 ITOT, 3 more..
+              ------------------++---------------------------------------------------------------------------------------------------------------------------
+                                || 10.00 ITOT, 337.18 USD, 2 more..  70.00 GLD, 18.00 ITOT, 3 more..  -11.00 ITOT, 3 more..  70.00 GLD, 17.00 ITOT, 3 more..
+
+   Tall layout
+       Each commodity gets a new line (may be different in each  column),  and
+       account names are repeated:
+
+              $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=tall
+              Balance changes in 2012-01-01..2014-12-31:
+
+                                ||       2012        2013         2014        Total
+              ==================++==================================================
+               Assets:US:ETrade || 10.00 ITOT   70.00 GLD  -11.00 ITOT    70.00 GLD
+               Assets:US:ETrade || 337.18 USD  18.00 ITOT  4881.44 USD   17.00 ITOT
+               Assets:US:ETrade ||  12.00 VEA  -98.12 USD    14.00 VEA  5120.50 USD
+               Assets:US:ETrade || 106.00 VHT   10.00 VEA   170.00 VHT    36.00 VEA
+               Assets:US:ETrade ||              18.00 VHT                294.00 VHT
+              ------------------++--------------------------------------------------
+                                || 10.00 ITOT   70.00 GLD  -11.00 ITOT    70.00 GLD
+                                || 337.18 USD  18.00 ITOT  4881.44 USD   17.00 ITOT
+                                ||  12.00 VEA  -98.12 USD    14.00 VEA  5120.50 USD
+                                || 106.00 VHT   10.00 VEA   170.00 VHT    36.00 VEA
+                                ||              18.00 VHT                294.00 VHT
+
+   Bare layout
+       Commodity  symbols  are  kept in one column, each commodity has its own
+       row, amounts are bare numbers, account names are repeated:
+
+              $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -T -Y --layout=bare
+              Balance changes in 2012-01-01..2014-12-31:
+
+                                || Commodity    2012    2013     2014    Total
+              ==================++=============================================
+               Assets:US:ETrade || GLD             0   70.00        0    70.00
+               Assets:US:ETrade || ITOT        10.00   18.00   -11.00    17.00
+               Assets:US:ETrade || USD        337.18  -98.12  4881.44  5120.50
+               Assets:US:ETrade || VEA         12.00   10.00    14.00    36.00
+               Assets:US:ETrade || VHT        106.00   18.00   170.00   294.00
+              ------------------++---------------------------------------------
+                                || GLD             0   70.00        0    70.00
+                                || ITOT        10.00   18.00   -11.00    17.00
+                                || USD        337.18  -98.12  4881.44  5120.50
+                                || VEA         12.00   10.00    14.00    36.00
+                                || VHT        106.00   18.00   170.00   294.00
+
+       Bare layout also affects CSV output, which is useful for producing data
+       that is easier to consume, eg for making charts:
+
+              $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -O csv --layout=bare
+              "account","commodity","balance"
+              "Assets:US:ETrade","GLD","70.00"
+              "Assets:US:ETrade","ITOT","17.00"
+              "Assets:US:ETrade","USD","5120.50"
+              "Assets:US:ETrade","VEA","36.00"
+              "Assets:US:ETrade","VHT","294.00"
+              "Total:","GLD","70.00"
+              "Total:","ITOT","17.00"
+              "Total:","USD","5120.50"
+              "Total:","VEA","36.00"
+              "Total:","VHT","294.00"
+
+       Bare layout will sometimes display an extra row for the no-symbol  com-
+       modity,  because  of  zero  amounts  (hledger  treats zeroes as commod-
+       ity-less,   usually).    This   can   break   hledger-bar   confusingly
+       (workaround: add a cur: query to exclude the no-symbol row).
+
+   Tidy layout
+       This       produces       normalised       "tidy       data"       (see
+       https://cran.r-project.org/web/packages/tidyr/vignettes/tidy-data.html)
+       where every variable has its own column and each row represents a  sin-
+       gle data point.  This is the easiest kind of data for other software to
+       consume:
+
+              $ hledger -f examples/bcexample.hledger bal assets:us:etrade -3 -Y -O csv --layout=tidy
+              "account","period","start_date","end_date","commodity","value"
+              "Assets:US:ETrade","2012","2012-01-01","2012-12-31","GLD","0"
+              "Assets:US:ETrade","2012","2012-01-01","2012-12-31","ITOT","10.00"
+              "Assets:US:ETrade","2012","2012-01-01","2012-12-31","USD","337.18"
+              "Assets:US:ETrade","2012","2012-01-01","2012-12-31","VEA","12.00"
+              "Assets:US:ETrade","2012","2012-01-01","2012-12-31","VHT","106.00"
+              "Assets:US:ETrade","2013","2013-01-01","2013-12-31","GLD","70.00"
+              "Assets:US:ETrade","2013","2013-01-01","2013-12-31","ITOT","18.00"
+              "Assets:US:ETrade","2013","2013-01-01","2013-12-31","USD","-98.12"
+              "Assets:US:ETrade","2013","2013-01-01","2013-12-31","VEA","10.00"
+              "Assets:US:ETrade","2013","2013-01-01","2013-12-31","VHT","18.00"
+              "Assets:US:ETrade","2014","2014-01-01","2014-12-31","GLD","0"
+              "Assets:US:ETrade","2014","2014-01-01","2014-12-31","ITOT","-11.00"
+              "Assets:US:ETrade","2014","2014-01-01","2014-12-31","USD","4881.44"
+              "Assets:US:ETrade","2014","2014-01-01","2014-12-31","VEA","14.00"
+              "Assets:US:ETrade","2014","2014-01-01","2014-12-31","VHT","170.00"
+
+   Balance report output
+       As  noted in Output format, if you choose HTML output (by using -O html
+       or -o somefile.html), it will use the UTF-8 text encoding, And you  can
+       create  a  hledger.css  file in the same directory to customise the re-
+       port's appearance.
+
+       The  HTML  and  FODS  output  formats  can  generate  hyperlinks  to  a
+       hledger-web  register  view for each account and period.  E.g.  if your
+       hledger-web server is reachable at http://localhost:5000 then you might
+       run the balance command with the extra option  --base-url=http://local-
+       host:5000.     You    can    also    produce   relative   links,   like
+       --base-url="some/path" or --base-url="".)
+
+   Some useful balance reports
+       Some frequently used balance options/reports are:
+
+       o bal -M revenues expenses
+       Show revenues/expenses in each month.  Also available as  the  incomes-
+       tatement command.
+
+       o bal -M -H assets liabilities
+       Show  historical  asset/liability  balances  at  each  month end.  Also
+       available as the balancesheet command.
+
+       o bal -M -H assets liabilities equity
+       Show historical asset/liability/equity  balances  at  each  month  end.
+       Also available as the balancesheetequity command.
+
+       o bal -M assets not:receivable
+       Show  changes  to  liquid  assets in each month.  Also available as the
+       cashflow command.
+
+       Also:
+
+       o bal -M expenses -2 -SA
+       Show monthly expenses summarised to  depth  2  and  sorted  by  average
+       amount.
+
+       o bal -M --budget expenses
+       Show monthly expenses and budget goals.
+
+       o bal -M --valuechange investments
+       Show monthly change in market value of investment assets.
+
+       o bal  investments  --valuechange  -D  date:lastweek  amt:'>1000'  -STA
+         [--invert]
+       Show top gainers [or losers] last week
+
+   roi
+       Shows the time-weighted (TWR) and money-weighted (IRR) rate  of  return
+       on your investments.
+
+              Flags:
+                   --cashflow                 show all amounts that were used to compute
+                                              returns
+                   --investment=QUERY         query to select your investment transactions
+                   --profit-loss=QUERY --pnl  query to select profit-and-loss or
+                                              appreciation/valuation transactions
+
+       At  a  minimum,  you need to supply a query (which could be just an ac-
+       count name) to select your investment(s) with --inv, and another  query
+       to identify your profit and loss transactions with --pnl.
+
+       If  you do not record changes in the value of your investment manually,
+       or do not require computation  of  time-weighted  return  (TWR),  --pnl
+       could be an empty query (--pnl "" or --pnl STR where STR does not match
+       any of your accounts).
+
+       This  command  will compute and display the internalized rate of return
+       (IRR, also known as money-weighted rate of  return)  and  time-weighted
+       rate  of  return  (TWR)  for  your  investments for the time period re-
+       quested.  IRR is always annualized due to the way it is  computed,  but
+       TWR  is reported both as a rate over the chosen reporting period and as
+       an annual rate.
+
+       Price directives will be taken into account if you  supply  appropriate
+       --cost or --value flags (see VALUATION).
+
+       Note, in some cases this report can fail, for these reasons:
+
+       o Error  (NotBracketed): No solution for Internal Rate of Return (IRR).
+         Possible causes: IRR is huge (>1000000%), balance of  investment  be-
+         comes negative at some point in time.
+
+       o Error  (SearchFailed):  Failed  to find solution for Internal Rate of
+         Return (IRR).  Either search does not converge to a solution, or con-
+         verges too slowly.
+
+       Examples:
+
+       o Using  roi  to  compute  total  return  of  investment   in   stocks:
+         https://github.com/simonmichael/hledger/blob/master/examples/invest-
+         ing/roi-unrealised.ledger
+
+       o Cookbook > Return on Investment: https://hledger.org/roi.html
+
+   Spaces and special characters in --inv and --pnl
+       Note that --inv and --pnl's argument is a query, and queries could have
+       several space-separated terms (see QUERIES).
+
+       To  indicate  that  all search terms form single command-line argument,
+       you will need to put them in quotes (see Special characters):
+
+              $ hledger roi --inv 'term1 term2 term3 ...'
+
+       If any query terms contain spaces themselves, you will  need  an  extra
+       level of nested quoting, eg:
+
+              $ hledger roi --inv="'Assets:Test 1'" --pnl="'Equity:Unrealized Profit and Loss'"
+
+   Semantics of --inv and --pnl
+       Query  supplied to --inv has to match all transactions that are related
+       to your investment.  Transactions not matching --inv will be ignored.
+
+       In these transactions, ROI will conside postings that match --inv to be
+       "investment postings" and other postings (not matching --inv)  will  be
+       sorted  into  two categories: "cash flow" and "profit and loss", as ROI
+       needs to know which part of the investment value is your  contributions
+       and which is due to the return on investment.
+
+       o "Cash flow" is depositing or withdrawing money, buying or selling as-
+         sets,  or  otherwise converting between your investment commodity and
+         any other commodity.  Example:
+
+                2019-01-01 Investing in Snake Oil
+                  assets:cash          -$100
+                  investment:snake oil
+
+                2020-01-01 Selling my Snake Oil
+                  assets:cash           $10
+                  investment:snake oil  = 0
+
+       o "Profit and loss" is change in the value of your investment:
+
+                2019-06-01 Snake Oil falls in value
+                  investment:snake oil  = $57
+                  equity:unrealized profit or loss
+
+       All non-investment postings are assumed to be "cash flow", unless  they
+       match  --pnl query.  Changes in value of your investment due to "profit
+       and loss" postings will be considered as part of  your  investment  re-
+       turn.
+
+       Example:  if you use --inv snake --pnl equity:unrealized, then postings
+       in the example below would be classifed as:
+
+              2019-01-01 Snake Oil #1
+                assets:cash          -$100   ; cash flow posting
+                investment:snake oil         ; investment posting
+
+              2019-03-01 Snake Oil #2
+                equity:unrealized pnl  -$100 ; profit and loss posting
+                snake oil                    ; investment posting
+
+              2019-07-01 Snake Oil #3
+                equity:unrealized pnl        ; profit and loss posting
+                cash          -$100          ; cash flow posting
+                snake oil     $50            ; investment posting
+
+   IRR and TWR explained
+       "ROI" stands for "return on investment".  Traditionally this  was  com-
+       puted  as a difference between current value of investment and its ini-
+       tial value, expressed in percentage of the initial value.
+
+       However, this approach is only practical in simple cases, where invest-
+       ments receives no in-flows or out-flows of money,  and  where  rate  of
+       growth is fixed over time.  For more complex scenarios you need differ-
+       ent  ways to compute rate of return, and this command implements two of
+       them: IRR and TWR.
+
+       Internal rate of return, or "IRR" (also called "money-weighted rate  of
+       return")  takes into account effects of in-flows and out-flows, and the
+       time between them.  Investment at a particular fixed interest  rate  is
+       going  to  give  you more interest than the same amount invested at the
+       same interest rate, but made later in time.   If  you  are  withdrawing
+       from  your  investment, your future gains would be smaller (in absolute
+       numbers), and will be a smaller percentage of your initial  investment,
+       so your IRR will be smaller.  And if you are adding to your investment,
+       you will receive bigger absolute gains, which will be a bigger percent-
+       age of your initial investment, so your IRR will be larger.
+
+       As  mentioned before, in-flows and out-flows would be any cash that you
+       personally put in or withdraw, and for the "roi" command, these are the
+       postings that match the query in the--inv argument and  NOT  match  the
+       query in the--pnl argument.
+
+       If  you  manually  record  changes  in  the value of your investment as
+       transactions that balance them against "profit and loss"  (or  "unreal-
+       ized  gains") account or use price directives, then in order for IRR to
+       compute the precise effect of your in-flows and out-flows on  the  rate
+       of  return, you will need to record the value of your investement on or
+       close to the days when in- or out-flows occur.
+
+       In technical terms, IRR uses the same approach as  computation  of  net
+       present value, and tries to find a discount rate that makes net present
+       value of all the cash flows of your investment to add up to zero.  This
+       could  be hard to wrap your head around, especially if you haven't done
+       discounted cash flow analysis before.  Implementation of IRR in hledger
+       should produce results that match the =XIRR formula in Excel.
+
+       Second way to compute rate of return that  roi  command  implements  is
+       called  "time-weighted rate of return" or "TWR".  Like IRR, it will ac-
+       count for the effect of your in-flows and out-flows, but unlike IRR  it
+       will  try  to  compute the true rate of return of the underlying asset,
+       compensating for the effect that deposits and withdrawas  have  on  the
+       apparent rate of growth of your investment.
+
+       TWR  represents  your  investment  as  an  imaginary  "unit fund" where
+       in-flows/ out-flows lead to buying or selling "units" of  your  invest-
+       ment  and  changes  in its value change the value of "investment unit".
+       Change in "unit price" over the reporting period gives you rate of  re-
+       turn  of  your  investment, and make TWR less sensitive than IRR to the
+       effects of cash in-flows and out-flows.
+
+       References:
+
+       o Explanation of rate of return
+
+       o Explanation of IRR
+
+       o Explanation of TWR
+
+       o IRR vs TWR
+
+       o Examples of computing IRR and TWR and discussion of  the  limitations
+         of both metrics
+
+Chart commands
+   activity
+       Show an ascii barchart of posting counts per interval.
+
+              Flags:
+              no command-specific flags
+
+       The  activity  command  displays an ascii histogram showing transaction
+       counts by day, week, month or other reporting interval (by day  is  the
+       default).  With query arguments, it counts only matched transactions.
+
+       Examples:
+
+              $ hledger activity --quarterly
+              2008-01-01 **
+              2008-04-01 *******
+              2008-07-01
+              2008-10-01 **
+
+Data generation commands
+   close
+       (equity)
+
+       close  prints several kinds of "closing" and/or "opening" transactions,
+       useful in various situations: migrating balances to a new journal file,
+       retaining earnings into equity,  consolidating  balances,  viewing  lot
+       costs..   Like  print,  it  prints valid journal entries.  You can copy
+       these into your journal file(s) when you are happy with how they look.
+
+              Flags:
+                   --clopen[=TAGVAL]      show closing and opening balances transactions,
+                                          for AL accounts by default
+                   --close[=TAGVAL]       show just a closing balances transaction
+                   --open[=TAGVAL]        show just an opening balances transaction
+                   --assert[=TAGVAL]      show a balance assertions transaction
+                   --assign[=TAGVAL]      show a balance assignments transaction
+                   --retain[=TAGVAL]      show a retain earnings transaction, for RX
+                                          accounts by default
+                -x --explicit             show all amounts explicitly
+                   --show-costs           show amounts with different costs separately
+                   --interleaved          show source and destination postings together
+                   --assertion-type=TYPE  =, ==, =* or ==*
+                   --close-desc=DESC      set closing transaction's description
+                   --close-acct=ACCT      set closing transaction's destination account
+                   --open-desc=DESC       set opening transaction's description
+                   --open-acct=ACCT       set opening transaction's source account
+                   --round=TYPE           how much rounding or padding should be done when
+                                          displaying amounts ?
+                                          none - show original decimal digits,
+                                                 as in journal (default)
+                                          soft - just add or remove decimal zeros
+                                                 to match precision
+                                          hard - round posting amounts to precision
+                                                 (can unbalance transactions)
+                                          all  - also round cost amounts to precision
+                                                 (can unbalance transactions)
+
+       close has six modes,  selected  by  choosing  one  of  the  mode  flags
+       (--close  is  the  default).   They all do much the same operation, but
+       with different defaults, useful in different situations.
+
+   close --clopen
+       This is useful if migrating balances to a new journal file at the start
+       of a new year.  It prints a "closing balances" transaction that  zeroes
+       out account balances (Asset and Liability accounts, by default), and an
+       opposite "opening balances" transaction that restores them again.  Typ-
+       ically, you would run
+
+              hledger close --clopen -e NEWYEAR >> $LEDGER_FILE
+
+       and then move the opening transaction from the old file to the new file
+       (and probably also update your LEDGER_FILE environment variable).
+
+       Why might you do this ?  If your reports are fast, you may not need it.
+       But  at  some  point  you  will probably want to partition your data by
+       time, for performance or data integrity or regulatory reasons.   A  new
+       file  or set of files per year is common.  Then, having each file/file-
+       set "bookended" with opening and closing balance transactions will  al-
+       low  you  to freely pick and choose which files to read - just the cur-
+       rent year, any past year, any sequence of years, or all of them - while
+       showing correct account balances in each case.   The  earliest  opening
+       balances  transaction  sets  correct  starting  balances, and any later
+       closing/opening pairs will harmlessly cancel each other out.
+
+       The balances will be transferred  to  and  from  equity:opening/closing
+       balances  by  default.   You  can  override  this by using --close-acct
+       and/or --open-acct.
+
+       You can select a different set of accounts to close/open  by  providing
+       an  account  query.   Eg to add Equity accounts, provide arguments like
+       assets liabilities equity or type:ALE.  When migrating to a  new  file,
+       you'll  usually want to bring along the AL or ALE accounts, but not the
+       RX accounts (Revenue, Expense).
+
+       Assertions will be added indicating and checking the  new  balances  of
+       the closed/opened accounts.
+
+       The  generated transactions will have a clopen: tag.  If the main jour-
+       nal's base file name contains a number (eg a year  number),  the  tag's
+       value  will be that base file name with the number incremented.  Or you
+       can choose the tag value yourself, by using --clopen=TAGVAL.
+
+   close --close
+       This prints just the closing balances transaction of --clopen.   It  is
+       the default if you don't specify a mode.
+
+       More  customisation  options  are described below.  Among other things,
+       you can use close --close to generate a transaction moving the balances
+       from any set of accounts, to a different account.  (If you need to move
+       just a portion of the balance, see hledger-move.)
+
+   close --open
+       This prints just the opening balances transaction of --clopen.  (It  is
+       similar to Ledger's equity command.)
+
+   close --assert
+       This prints a transaction that asserts the account balances as they are
+       on the end date (and adds an assert: tag).  It could be useful as docu-
+       mention and to guard against changes.
+
+   close --assign
+       This prints a transaction that assigns the account balances as they are
+       on  the  end  date  (and adds an "assign:" tag).  Unlike balance asser-
+       tions, assignments will post changes to balances as needed to reach the
+       specified amounts.
+
+       This is another way to set starting balances when migrating  to  a  new
+       file,  and  it  will set them correctly even in the presence of earlier
+       files which do not have a closing balances  transaction.   However,  it
+       can  hide  errors,  and disturb the accounting equation, so --clopen is
+       usually recommended.
+
+   close --retain
+       This is like --close, but it closes Revenue and  Expense  account  bal-
+       ances  by  default.   They will be transferred to equity:retained earn-
+       ings, or another account specified with --close-acct.
+
+       Revenues and expenses correspond to changes in equity.  They are  cate-
+       gorised separately for reporting purposes, but traditionally at the end
+       of  each  accounting  period,  businesses consolidate them into equity,
+       This is called "retaining earnings", or "closing the books".
+
+       In personal accounting, there's not much reason to do  this,  and  most
+       people  don't.   (One reason to do it is to help the balancesheetequity
+       report show a zero total, demonstrating that  the  accounting  equation
+       (A-L=E) is satisfied.)
+
+   close customisation
+       In all modes, the following things can be overridden:
+
+       o the accounts to be closed/opened, with account query arguments
+
+       o the balancing account, with --close-acct=ACCT and/or --open-acct=ACCT
+
+       o the    transaction    descriptions,    with   --close-desc=DESC   and
+         --open-desc=DESC
+
+       o the transaction's tag value, with a --MODE=NEW option argument
+
+       o the closing/opening dates, with -e OPENDATE
+
+       By default, the closing date is yesterday, or the journal's  end  date,
+       whichever  is  later;  and the opening date is always one day after the
+       closing date.  You can change these by specifying a  report  end  date;
+       the closing date will be the last day of the report period.  Eg -e 2024
+       means "close on 2023-12-31, open on 2024-01-01".
+
+       With --x/--explicit, the balancing amount will be shown explicitly, and
+       if  it involves multiple commodities, a separate posting will be gener-
+       ated for each of them (similar to print -x).
+
+       With --interleaved, each individual transfer is shown with  source  and
+       destination  postings  next  to  each  other  (perhaps useful for trou-
+       bleshooting).
+
+       With --show-costs, balances' costs are also shown, with different costs
+       kept separate.  This may generate very large journal  entries,  if  you
+       have  many  currency  conversions  or  investment  transactions.  close
+       --show-costs is currently the best way to  view  investment  lots  with
+       hledger.    (To   move  or  dispose  of  lots,  see  the  more  capable
+       hledger-move script.)
+
+   close and balance assertions
+       close adds balance assertions verifying that the accounts have been re-
+       set to zero in a closing transaction or restored to their previous bal-
+       ances in an opening transaction.  These provide useful error  checking,
+       but you can ignore them temporarily with -I, or remove them if you pre-
+       fer.
+
+       Single-commodity,  subaccount-exclusive balance assertions (=) are gen-
+       erated by default.  This can  be  changed  with  --assertion-type='==*'
+       (eg).
+
+       When  running  close  you  should  probably avoid using -C, -R, status:
+       (filtering by status or  realness)  or  --auto  (generating  postings),
+       since the generated balance assertions would then require these.
+
+       Transactions  with  multiple dates (eg posting dates) spanning the file
+       boundary also can disrupt the balance assertions:
+
+              2023-12-30 a purchase made in december, cleared in january
+                  expenses:food          5
+                  assets:bank:checking  -5  ; date: 2023-01-02
+
+       To solve this you can transfer the money to and from  a  temporary  ac-
+       count, splitting the multi-day transaction into two single-day transac-
+       tions:
+
+              ; in 2022.journal:
+              2022-12-30 a purchase made in december, cleared in january
+                  expenses:food          5
+                  equity:pending        -5
+
+              ; in 2023.journal:
+              2023-01-02 last year's transaction cleared
+                  equity:pending         5 = 0
+                  assets:bank:checking  -5
+
+   close examples
+   Retain earnings
+       Record 2022's revenues/expenses as retained earnings on 2022-12-31, ap-
+       pending the generated transaction to the journal:
+
+              $ hledger close --retain -f 2022.journal -p 2022 >> 2022.journal
+
+       After  this,  to  see 2022's revenues and expenses you must exclude the
+       retain earnings transaction:
+
+              $ hledger -f 2022.journal is not:desc:'retain earnings'
+
+   Migrate balances to a new file
+       Close assets/liabilities on 2022-12-31 and re-open them on 2023-01-01:
+
+              $ hledger close --clopen -f 2022.journal -p 2022
+              # copy/paste the closing transaction to the end of 2022.journal
+              # copy/paste the opening transaction to the start of 2023.journal
+
+       After this, to see 2022's end-of-year balances  you  must  exclude  the
+       closing balances transaction:
+
+              $ hledger -f 2022.journal bs not:desc:'closing balances'
+
+       For  more flexibility, it helps to tag closing and opening transactions
+       with eg clopen:NEWYEAR, then you can ensure correct balances by exclud-
+       ing all opening/closing transactions except the first, like so:
+
+              $ hledger bs -Y -f 2021.j -f 2022.j -f 2023.j expr:'tag:clopen=2021 or not tag:clopen'
+              $ hledger bs -Y -f 2021.j -f 2022.j           expr:'tag:clopen=2021 or not tag:clopen'
+              $ hledger bs -Y -f 2022.j -f 2023.j           expr:'tag:clopen=2022 or not tag:clopen'
+              $ hledger bs -Y -f 2021.j                     expr:'tag:clopen=2021 or not tag:clopen'
+              $ hledger bs -Y -f 2022.j                     expr:'tag:clopen=2022 or not tag:clopen'
+              $ hledger bs -Y -f 2023.j                     # unclosed file, no query needed
+
+   More detailed close examples
+       See examples/multi-year.
+
+   rewrite
+       Print all transactions, rewriting the postings of matched transactions.
+       For now the only rewrite available is adding new postings,  like  print
+       --auto.
+
+              Flags:
+                   --add-posting='ACCT  AMTEXPR'  add a posting to ACCT, which may be
+                                                  parenthesised. AMTEXPR is either a literal
+                                                  amount, or *N which means the transaction's
+                                                  first matched amount multiplied by N (a
+                                                  decimal number). Two spaces separate ACCT
+                                                  and AMTEXPR.
+                   --diff                         generate diff suitable as an input for
+                                                  patch tool
+
+       This is a start at a generic rewriter of transaction entries.  It reads
+       the  default  journal and prints the transactions, like print, but adds
+       one or more specified postings to any transactions matching QUERY.  The
+       posting amounts can be fixed, or a multiplier of the existing  transac-
+       tion's first posting amount.
+
+       Examples:
+
+              $ hledger-rewrite.hs ^income --add-posting '(liabilities:tax)  *.33  ; income tax' --add-posting '(reserve:gifts)  $100'
+              $ hledger-rewrite.hs expenses:gifts --add-posting '(reserve:gifts)  *-1"'
+              $ hledger-rewrite.hs -f rewrites.hledger
+
+       rewrites.hledger may consist of entries like:
+
+              = ^income amt:<0 date:2017
+                (liabilities:tax)  *0.33  ; tax on income
+                (reserve:grocery)  *0.25  ; reserve 25% for grocery
+                (reserve:)  *0.25  ; reserve 25% for grocery
+
+       Note  the  single  quotes to protect the dollar sign from bash, and the
+       two spaces between account and amount.
+
+       More:
+
+              $ hledger rewrite -- [QUERY]        --add-posting "ACCT  AMTEXPR" ...
+              $ hledger rewrite -- ^income        --add-posting '(liabilities:tax)  *.33'
+              $ hledger rewrite -- expenses:gifts --add-posting '(budget:gifts)  *-1"'
+              $ hledger rewrite -- ^income        --add-posting '(budget:foreign currency)  *0.25 JPY; diversify'
+
+       Argument for --add-posting option is a  usual  posting  of  transaction
+       with  an  exception  for amount specification.  More precisely, you can
+       use '*' (star symbol) before the amount to indicate that that this is a
+       factor for an amount of original matched posting.  If  the  amount  in-
+       cludes a commodity name, the new posting amount will be in the new com-
+       modity;  otherwise,  it will be in the matched posting amount's commod-
+       ity.
+
+   Re-write rules in a file
+       During the run this tool will execute  so  called  "Automated  Transac-
+       tions" found in any journal it process.  I.e instead of specifying this
+       operations in command line you can put them in a journal file.
+
+              $ rewrite-rules.journal
+
+       Make contents look like this:
+
+              = ^income
+                  (liabilities:tax)  *.33
+
+              = expenses:gifts
+                  budget:gifts  *-1
+                  assets:budget  *1
+
+       Note  that '=' (equality symbol) that is used instead of date in trans-
+       actions you usually write.  It indicates the query by which you want to
+       match the posting to add new ones.
+
+              $ hledger rewrite -- -f input.journal -f rewrite-rules.journal > rewritten-tidy-output.journal
+
+       This is something similar to the commands pipeline:
+
+              $ hledger rewrite -- -f input.journal '^income' --add-posting '(liabilities:tax)  *.33' \
+                | hledger rewrite -- -f - expenses:gifts      --add-posting 'budget:gifts  *-1'       \
+                                                              --add-posting 'assets:budget  *1'       \
+                > rewritten-tidy-output.journal
+
+       It is important to understand that relative order of  such  entries  in
+       journal  is important.  You can re-use result of previously added post-
+       ings.
+
+   Diff output format
+       To use this tool for batch modification of your journal files  you  may
+       find useful output in form of unified diff.
+
+              $ hledger rewrite -- --diff -f examples/sample.journal '^income' --add-posting '(liabilities:tax)  *.33'
+
+       Output might look like:
+
+              --- /tmp/examples/sample.journal
+              +++ /tmp/examples/sample.journal
+              @@ -18,3 +18,4 @@
+               2008/01/01 income
+              -    assets:bank:checking  $1
+              +    assets:bank:checking            $1
+                   income:salary
+              +    (liabilities:tax)                0
+              @@ -22,3 +23,4 @@
+               2008/06/01 gift
+              -    assets:bank:checking  $1
+              +    assets:bank:checking            $1
+                   income:gifts
+              +    (liabilities:tax)                0
+
+       If you'll pass this through patch tool you'll get transactions contain-
+       ing the posting that matches your query be updated.  Note that multiple
+       files  might  be  update according to list of input files specified via
+       --file options and include directives inside of these files.
+
+       Be careful.  Whole transaction being re-formatted in a style of  output
+       from hledger print.
+
+       See also:
+
+       https://github.com/simonmichael/hledger/issues/99
+
+   rewrite vs. print --auto
+       This  command  predates  print --auto, and currently does much the same
+       thing, but with these differences:
+
+       o with multiple files, rewrite lets rules in any file affect all  other
+         files.   print  --auto  uses standard directive scoping; rules affect
+         only child files.
+
+       o rewrite's query limits which transactions can be rewritten;  all  are
+         printed.  print --auto's query limits which transactions are printed.
+
+       o rewrite  applies  rules  specified on command line or in the journal.
+         print --auto applies rules specified in the journal.
+
+Maintenance commands
+   check
+       Check for various kinds of errors in your data.
+
+              Flags:
+              no command-specific flags
+
+       hledger provides a number of built-in correctness checks to help  vali-
+       date  your  data  and prevent errors.  Some are run automatically, some
+       when you enable --strict mode; or you can run any of them on demand  by
+       providing  them  as  arguments to the check command.  check produces no
+       output and a zero exit code if all is well.  Eg:
+
+              hledger check                      # run basic checks
+              hledger check -s                   # run basic and strict checks
+              hledger check ordereddates payees  # run basic checks and two others
+
+       If you are an Emacs user, you can also  configure  flycheck-hledger  to
+       run these checks, providing instant feedback as you edit the journal.
+
+       Here are the checks currently available.  Generally, they are performed
+       in  the  order  they  are shown here (and only the first failure is re-
+       ported).
+
+   Basic checks
+       These important checks are performed by default, by almost all  hledger
+       commands:
+
+       o parseable  - data files are in a supported format, with no syntax er-
+         rors and no invalid include directives.  This ensures that all  files
+         exist and are readable.
+
+       o autobalanced - all transactions are balanced, after inferring missing
+         amounts  and  conversion costs where possible, and then converting to
+         cost.  This ensures that each individual transaction is well formed.
+
+       o assertions - all balance assertions in the journal are passing.  Bal-
+         ance assertions are like canaries in your journal,  they  catch  many
+         problems.   They  can  get in the way sometimes; you can disable them
+         temporarily  with  -I/--ignore-assertions  (unless  overridden   with
+         -s/--strict or hledger check assertions).
+
+   Strict checks
+       These   additional  checks  are  performed  by  any  command  when  the
+       -s/--strict flag is used (strict mode).  Strict mode always enables the
+       balance assertions check, also.   These  provide  extra  error-catching
+       power  when  you  are serious about keeping your data clean and free of
+       typos:
+
+       o balanced - like autobalanced, but in conversion  transactions,  costs
+         must  be written explicitly.  This ensures some redundancy in the en-
+         try, which helps prevent typos.
+
+       o commodities - all commodity symbols  used  must  be  declared.   This
+         guards against mistyping or omitting commodity symbols.
+
+       o accounts  -  all  account names used must be declared.  This prevents
+         the use of mis-spelled or outdated account names.
+
+   Other checks
+       These other checks are not wanted by everyone, but can be run using the
+       check command:
+
+       o ordereddates - within each file, transactions are  ordered  by  date.
+         This  is a simple and effective error catcher, and you should use it.
+         Alas!  not everyone wants it.  If you do, use hledger  check  -s  or-
+         dereddates.  When enabled, this check is performed early, before bal-
+         ance  assertions  (because copy-pasted dates are often the root cause
+         of balance assertion failures).
+
+       o payees - all payees used by transactions must be declared.  This will
+         force you to always use known/declared payee names.  For most  people
+         this is a bit too restrictive.
+
+       o tags - all tags used by transactions must be declared.  This prevents
+         mistyped tag names.
+
+       o recentassertions  -  all accounts with balance assertions must have a
+         balance assertion within the last 7 days before their latest posting.
+         This encourages you to add balance assertions  fairly  regularly  for
+         your  active asset/liability accounts, which in turn should encourage
+         you to check and reconcile with their real world balances fairly reg-
+         ularly.  close --assert can be helpful.  (The  older  balance  asser-
+         tions  become  redundant;  you can remove them periodically, or leave
+         them in place, perhaps commented, as documentation.)
+
+       o uniqueleafnames - no two accounts may have the same leaf  name.   The
+         leaf  name  is  the  last colon-separated part of an account name, eg
+         checking in assets:bank:checking.  This encourages you to keep  those
+         unique,  effectively giving each account a short name which is easier
+         to remember and to type in reporting commands.
+
+   Custom checks
+       You can build your own custom checks with add-on command scripts.   See
+       also Cookbook > Scripting.  Here are some examples from hledger/bin/:
+
+       o hledger-check-tagfiles  -  all  tag  values  containing  / (a forward
+         slash) exist as file paths
+
+       o hledger-check-fancyassertions - more complex balance  assertions  are
+         passing
+
+   diff
+       Compares  a  particular  account's transactions in two input files.  It
+       shows any transactions to this account which are in one file but not in
+       the other.
+
+              Flags:
+              no command-specific flags
+
+       More precisely: for each posting affecting this account in either file,
+       this command looks for a corresponding posting in the other file  which
+       posts  the same amount to the same account (ignoring date, description,
+       etc).
+
+       Since it compares postings, not transactions, this also works when mul-
+       tiple bank transactions have been combined into a single journal entry.
+
+       This command is useful eg if you have downloaded an account's  transac-
+       tions  from your bank (eg as CSV data): when hledger and your bank dis-
+       agree about the account balance, you can compare  the  bank  data  with
+       your journal to find out the cause.
+
+       Examples:
+
+              $ hledger diff -f $LEDGER_FILE -f bank.csv assets:bank:giro
+              These transactions are in the first file only:
+
+              2014/01/01 Opening Balances
+                  assets:bank:giro              EUR ...
+                  ...
+                  equity:opening balances       EUR -...
+
+              These transactions are in the second file only:
+
+   test
+       Run built-in unit tests.
+
+              Flags:
+              no command-specific flags
+
+       This  command  runs the unit tests built in to hledger and hledger-lib,
+       printing the results on stdout.  If any test fails, the exit code  will
+       be non-zero.
+
+       This  is  mainly used by hledger developers, but you can also use it to
+       sanity-check the installed hledger executable on  your  platform.   All
+       tests  are  expected to pass - if you ever see a failure, please report
+       as a bug!
+
+       This command also accepts tasty test runner options, written after a --
+       (double hyphen).  Eg to run only the tests in Hledger.Data.Amount, with
+       ANSI colour codes disabled:
+
+              $ hledger test -- -pData.Amount --color=never
+
+       For help on these, see  https://github.com/feuerbach/tasty#options  (--
+       --help currently doesn't show them).
+
+PART 5: COMMON TASKS
+       Here  are  some  quick  examples  of  how  to  do some basic tasks with
+       hledger.
+
+Getting help
+       Here's how to list commands and view options and command docs:
+
+              $ hledger                # show available commands
+              $ hledger --help         # show common options
+              $ hledger CMD --help     # show CMD's options, common options and CMD's documentation
+
+       You can also view your hledger version's manual in several  formats  by
+       using the help command.  Eg:
+
+              $ hledger help           # show the hledger manual with info, man or $PAGER (best available)
+              $ hledger help journal   # show the journal topic in the hledger manual
+              $ hledger help --help    # find out more about the help command
+
+       To   view   manuals   and   introductory   docs   on   the  web,  visit
+       https://hledger.org.   Chat  and  mail  list  support  and   discussion
+       archives can be found at https://hledger.org/support.
+
+Constructing command lines
+       hledger  has  a  flexible command line interface.  We strive to keep it
+       simple and ergonomic, but if you run into one of the  sharp  edges  de-
+       scribed in OPTIONS, here are some tips that might help:
+
+       o command-specific  options must go after the command (it's fine to put
+         common options there too: hledger CMD OPTS ARGS)
+
+       o running add-on executables directly simplifies command  line  parsing
+         (hledger-ui OPTS ARGS)
+
+       o enclose "problematic" args in single quotes
+
+       o if  needed, also add a backslash to hide regular expression metachar-
+         acters from the shell
+
+       o to see how a misbehaving command line is being parsed, add --debug=2.
+
+Starting a journal file
+       hledger  looks  for  your  accounting   data   in   a   journal   file,
+       $HOME/.hledger.journal by default:
+
+              $ hledger stats
+              The hledger journal file "/Users/simon/.hledger.journal" was not found.
+              Please create it first, eg with "hledger add" or a text editor.
+              Or, specify an existing journal file with -f or LEDGER_FILE.
+
+       You  can  override this by setting the LEDGER_FILE environment variable
+       (see below).  It's a good practice to keep this  important  file  under
+       version  control,  and  to start a new file each year.  So you could do
+       something like this:
+
+              $ mkdir ~/finance
+              $ cd ~/finance
+              $ git init
+              Initialized empty Git repository in /Users/simon/finance/.git/
+              $ touch 2023.journal
+              $ echo "export LEDGER_FILE=$HOME/finance/2023.journal" >> ~/.profile
+              $ source ~/.profile
+              $ hledger stats
+              Main file                : /Users/simon/finance/2023.journal
+              Included files           :
+              Transactions span        :  to  (0 days)
+              Last transaction         : none
+              Transactions             : 0 (0.0 per day)
+              Transactions last 30 days: 0 (0.0 per day)
+              Transactions last 7 days : 0 (0.0 per day)
+              Payees/descriptions      : 0
+              Accounts                 : 0 (depth 0)
+              Commodities              : 0 ()
+              Market prices            : 0 ()
+
+Setting LEDGER_FILE
+       How to set LEDGER_FILE permanently depends on your setup:
+
+       On unix and mac, running these commands in the terminal will  work  for
+       many people; adapt as needed:
+
+              $ echo 'export LEDGER_FILE=~/finance/2023.journal' >> ~/.profile
+              $ source ~/.profile
+
+       When  correctly  configured,  in  a  new  terminal  window  env  | grep
+       LEDGER_FILE will show your file, and so will hledger files.
+
+       On mac, this additional step might  be  helpful  for  GUI  applications
+       (like  Emacs started from the dock): add an entry to ~/.MacOSX/environ-
+       ment.plist like
+
+              {
+                "LEDGER_FILE" : "~/finance/2023.journal"
+              }
+
+       and then run killall Dock in a terminal  window  (or  restart  the  ma-
+       chine).
+
+       On Windows, see https://www.java.com/en/download/help/path.html, or try
+       running  these  commands in a powershell window (let us know if it per-
+       sists across a reboot, and if you need to be an Administrator):
+
+              > CD
+              > MKDIR finance
+              > SETX LEDGER_FILE "C:\Users\USERNAME\finance\2023.journal"
+
+       When correctly configured, in a new  terminal  window  $env:LEDGER_FILE
+       will show the file path, and so will hledger files.
+
+Setting opening balances
+       Pick  a  starting  date  for which you can look up the balances of some
+       real-world assets (bank accounts, wallet..)   and  liabilities  (credit
+       cards..).
+
+       To  avoid  a  lot of data entry, you may want to start with just one or
+       two accounts, like your checking account or cash wallet; and pick a re-
+       cent starting date, like today or the start of the week.  You  can  al-
+       ways  come  back later and add more accounts and older transactions, eg
+       going back to january 1st.
+
+       Add an opening balances transaction to the journal, declaring the  bal-
+       ances on this date.  Here are two ways to do it:
+
+       o The  first way: open the journal in any text editor and save an entry
+         like this:
+
+                2023-01-01 * opening balances
+                    assets:bank:checking                $1000   = $1000
+                    assets:bank:savings                 $2000   = $2000
+                    assets:cash                          $100   = $100
+                    liabilities:creditcard               $-50   = $-50
+                    equity:opening/closing balances
+
+         These are start-of-day balances, ie whatever was in  the  account  at
+         the end of the previous day.
+
+         The  *  after  the  date  is  an optional status flag.  Here it means
+         "cleared & confirmed".
+
+         The currency symbols are optional, but usually a good idea as  you'll
+         be dealing with multiple currencies sooner or later.
+
+         The  = amounts are optional balance assertions, providing extra error
+         checking.
+
+       o The second way: run hledger add and follow the prompts  to  record  a
+         similar transaction:
+
+                $ hledger add
+                Adding transactions to journal file /Users/simon/finance/2023.journal
+                Any command line arguments will be used as defaults.
+                Use tab key to complete, readline keys to edit, enter to accept defaults.
+                An optional (CODE) may follow transaction dates.
+                An optional ; COMMENT may follow descriptions or amounts.
+                If you make a mistake, enter < at any prompt to go one step backward.
+                To end a transaction, enter . when prompted.
+                To quit, enter . at a date prompt or press control-d or control-c.
+                Date [2023-02-07]: 2023-01-01
+                Description: * opening balances
+                Account 1: assets:bank:checking
+                Amount  1: $1000
+                Account 2: assets:bank:savings
+                Amount  2 [$-1000]: $2000
+                Account 3: assets:cash
+                Amount  3 [$-3000]: $100
+                Account 4: liabilities:creditcard
+                Amount  4 [$-3100]: $-50
+                Account 5: equity:opening/closing balances
+                Amount  5 [$-3050]:
+                Account 6 (or . or enter to finish this transaction): .
+                2023-01-01 * opening balances
+                    assets:bank:checking                      $1000
+                    assets:bank:savings                       $2000
+                    assets:cash                                $100
+                    liabilities:creditcard                     $-50
+                    equity:opening/closing balances          $-3050
+
+                Save this transaction to the journal ? [y]:
+                Saved.
+                Starting the next transaction (. or ctrl-D/ctrl-C to quit)
+                Date [2023-01-01]: .
+
+       If  you're  using  version control, this could be a good time to commit
+       the journal.  Eg:
+
+              $ git commit -m 'initial balances' 2023.journal
+
+Recording transactions
+       As you spend or receive money, you can record these transactions  using
+       one  of  the  methods  above (text editor, hledger add) or by using the
+       hledger-iadd or hledger-web add-ons, or by using the import command  to
+       convert CSV data downloaded from your bank.
+
+       Here  are  some  simple transactions, see the hledger_journal(5) manual
+       and hledger.org for more ideas:
+
+              2023/1/10 * gift received
+                assets:cash   $20
+                income:gifts
+
+              2023.1.12 * farmers market
+                expenses:food    $13
+                assets:cash
+
+              2023-01-15 paycheck
+                income:salary
+                assets:bank:checking    $1000
+
+Reconciling
+       Periodically you should reconcile - compare your hledger-reported  bal-
+       ances  against  external sources of truth, like bank statements or your
+       bank's website - to be sure that your ledger accurately represents  the
+       real-world  balances  (and,  that  the real-world institutions have not
+       made a mistake!).  This gets easy and fast with (1)  practice  and  (2)
+       frequency.   If  you do it daily, it can take 2-10 minutes.  If you let
+       it pile up, expect it to take longer as you hunt down errors  and  dis-
+       crepancies.
+
+       A typical workflow:
+
+       1. Reconcile  cash.   Count  what's  in your wallet.  Compare with what
+          hledger reports (hledger bal cash).  If they are different,  try  to
+          remember  the  missing transaction, or look for the error in the al-
+          ready-recorded transactions.   A  register  report  can  be  helpful
+          (hledger  reg cash).  If you can't find the error, add an adjustment
+          transaction.  Eg if you have $105 after the above, and can't explain
+          the missing $2, it could be:
+
+                  2023-01-16 * adjust cash
+                      assets:cash    $-2 = $105
+                      expenses:misc
+
+       2. Reconcile checking.  Log in to your bank's website.  Compare today's
+          (cleared) balance with hledger's cleared balance (hledger bal check-
+          ing -C).  If they are different, track down the error or record  the
+          missing  transaction(s) or add an adjustment transaction, similar to
+          the above.  Unlike the cash case, you can usually compare the trans-
+          action history and running balance from your bank with the  one  re-
+          ported  by hledger reg checking -C.  This will be easier if you gen-
+          erally record transaction dates quite similar to your bank's  clear-
+          ing dates.
+
+       3. Repeat for other asset/liability accounts.
+
+       Tip:  instead of the register command, use hledger-ui to see a live-up-
+       dating register while you edit the journal: hledger-ui --watch --regis-
+       ter checking -C
+
+       After reconciling, it could be a  good  time  to  mark  the  reconciled
+       transactions'  status  as "cleared and confirmed", if you want to track
+       that, by adding the * marker.  Eg in the  paycheck  transaction  above,
+       insert * between 2023-01-15 and paycheck
+
+       If  you're using version control, this can be another good time to com-
+       mit:
+
+              $ git commit -m 'txns' 2023.journal
+
+Reporting
+       Here are some basic reports.
+
+       Show all transactions:
+
+              $ hledger print
+              2023-01-01 * opening balances
+                  assets:bank:checking                      $1000
+                  assets:bank:savings                       $2000
+                  assets:cash                                $100
+                  liabilities:creditcard                     $-50
+                  equity:opening/closing balances          $-3050
+
+              2023-01-10 * gift received
+                  assets:cash              $20
+                  income:gifts
+
+              2023-01-12 * farmers market
+                  expenses:food             $13
+                  assets:cash
+
+              2023-01-15 * paycheck
+                  income:salary
+                  assets:bank:checking           $1000
+
+              2023-01-16 * adjust cash
+                  assets:cash               $-2 = $105
+                  expenses:misc
+
+       Show account names, and their hierarchy:
+
+              $ hledger accounts --tree
+              assets
+                bank
+                  checking
+                  savings
+                cash
+              equity
+                opening/closing balances
+              expenses
+                food
+                misc
+              income
+                gifts
+                salary
+              liabilities
+                creditcard
+
+       Show all account totals:
+
+              $ hledger balance
+                             $4105  assets
+                             $4000    bank
+                             $2000      checking
+                             $2000      savings
+                              $105    cash
+                            $-3050  equity:opening/closing balances
+                               $15  expenses
+                               $13    food
+                                $2    misc
+                            $-1020  income
+                              $-20    gifts
+                            $-1000    salary
+                              $-50  liabilities:creditcard
+              --------------------
+                                 0
+
+       Show only asset and liability balances, as  a  flat  list,  limited  to
+       depth 2:
+
+              $ hledger bal assets liabilities -2
+                             $4000  assets:bank
+                              $105  assets:cash
+                              $-50  liabilities:creditcard
+              --------------------
+                             $4055
+
+       Show  the  same  thing  without negative numbers, formatted as a simple
+       balance sheet:
+
+              $ hledger bs -2
+              Balance Sheet 2023-01-16
+
+                                      || 2023-01-16
+              ========================++============
+               Assets                 ||
+              ------------------------++------------
+               assets:bank            ||      $4000
+               assets:cash            ||       $105
+              ------------------------++------------
+                                      ||      $4105
+              ========================++============
+               Liabilities            ||
+              ------------------------++------------
+               liabilities:creditcard ||        $50
+              ------------------------++------------
+                                      ||        $50
+              ========================++============
+               Net:                   ||      $4055
+
+       The final total is your "net worth" on the end date.  (Or use bse for a
+       full balance sheet with equity.)
+
+       Show income and expense totals, formatted as an income statement:
+
+              hledger is
+              Income Statement 2023-01-01-2023-01-16
+
+                             || 2023-01-01-2023-01-16
+              ===============++=======================
+               Revenues      ||
+              ---------------++-----------------------
+               income:gifts  ||                   $20
+               income:salary ||                 $1000
+              ---------------++-----------------------
+                             ||                 $1020
+              ===============++=======================
+               Expenses      ||
+              ---------------++-----------------------
+               expenses:food ||                   $13
+               expenses:misc ||                    $2
+              ---------------++-----------------------
+                             ||                   $15
+              ===============++=======================
+               Net:          ||                 $1005
+
+       The final total is your net income during this period.
+
+       Show transactions affecting your wallet, with running total:
+
+              $ hledger register cash
+              2023-01-01 opening balances     assets:cash                   $100          $100
+              2023-01-10 gift received        assets:cash                    $20          $120
+              2023-01-12 farmers market       assets:cash                   $-13          $107
+              2023-01-16 adjust cash          assets:cash                    $-2          $105
+
+       Show weekly posting counts as a bar chart:
+
+              $ hledger activity -W
+              2019-12-30 *****
+              2023-01-06 ****
+              2023-01-13 ****
+
+Migrating to a new file
+       At the end of the year, you may want to continue your journal in a  new
+       file, so that old transactions don't slow down or clutter your reports,
+       and  to  help ensure the integrity of your accounting history.  See the
+       close command.
+
+       If using version control, don't forget to git add the new file.
+
+BUGS
+       We  welcome  bug  reports  in  the  hledger  issue  tracker  (shortcut:
+       https://bugs.hledger.org),   or  on  the  hledger  chat  or  mail  list
+       (https://hledger.org/support).
+
+       Some known issues and limitations:
+
+       The need to precede add-on command options with --  when  invoked  from
+       hledger is awkward.  (See Command options, Constructing command lines.)
+
+       A  UTF-8-aware  system locale must be configured to work with non-ascii
+       data.  (See Unicode characters, Troubleshooting.)
+
+       On Microsoft Windows, depending whether you are running in a CMD window
+       or a Cygwin/MSYS/Mintty window and how you installed hledger, non-ascii
+       characters and colours may not be supported, and the tab key may not be
+       supported by hledger add.  (Running in  a  WSL  window  should  resolve
+       these.)
+
+       When processing large data files, hledger uses more memory than Ledger.
+
+   Troubleshooting
+       Here  are  some common issues you might encounter when you run hledger,
+       and how to resolve them (and remember also you can  usually  get  quick
+       Support):
+
+       PATH issues: I get an error like "No command 'hledger' found"
+       Depending how you installed hledger, the executables may not be in your
+       shell's  PATH.   Eg  on  unix systems, stack installs hledger in ~/.lo-
+       cal/bin and cabal installs it in ~/.cabal/bin.  You may need to add one
+       of these directories to your shell's PATH, and/or open a  new  terminal
+       window.
+
+       LEDGER_FILE  issues:  I configured LEDGER_FILE but hledger is not using
+       it
+       o LEDGER_FILE should be a real environment variable, not just  a  shell
+         variable.  Eg on unix, the command env | grep LEDGER_FILE should show
+         it.    You   may   need   to   use   export  (see  https://stackover-
+         flow.com/a/7411509).  On Windows, $env:LEDGER_FILE should show it.
+
+       o You may need to force your shell to see  the  new  configuration.   A
+         simple way is to close your terminal window and open a new one.
+
+       LANG  issues:  I get errors like "Illegal byte sequence" or "Invalid or
+       incomplete multibyte or wide character" or "commitAndReleaseBuffer: in-
+       valid argument (invalid character)"
+       Programs compiled with GHC (hledger, haskell build tools,  etc.)   need
+       the  system  locale  to be UTF-8-aware, or they will fail when they en-
+       counter non-ascii characters.  To fix  it,  set  the  LANG  environment
+       variable  to  a  locale  which supports UTF-8 and which is installed on
+       your system.
+
+       On unix, locale -a lists the installed locales.   Look  for  one  which
+       mentions  utf8, UTF-8 or similar.  Some examples: C.UTF-8, en_US.utf-8,
+       fr_FR.utf8.  If necessary, use your system package manager  to  install
+       one.   Then  select it by setting the LANG environment variable.  Note,
+       exact spelling and capitalisation of the locale name may be  important:
+       Here's one common way to configure this permanently for your shell:
+
+              $ echo "export LANG=en_US.utf8" >>~/.profile
+              # close and re-open terminal window
+
+       If you are using Nix (not NixOS) for GHC and Hledger, you might need to
+       set the LOCALE_ARCHIVE variable:
+
+              $ echo "export LOCALE_ARCHIVE=${glibcLocales}/lib/locale/locale-archive" >>~/.profile
+              # close and re-open terminal window
+
+       COMPATIBILITY ISSUES: hledger gives an error with my Ledger file
+       Not  all  of  Ledger's journal file syntax or feature set is supported.
+       See hledger and Ledger for full details.
+
+
+
+AUTHORS
+       Simon Michael <simon@joyful.com> and contributors.
+       See http://hledger.org/CREDITS.html
+
+
+COPYRIGHT
+       Copyright 2007-2023 Simon Michael and contributors.
+
+
+LICENSE
+       Released under GNU GPL v3 or later.
+
+
+SEE ALSO
+       hledger(1), hledger-ui(1), hledger-web(1), ledger(1)
+
+hledger-1.42                      March 2025                        HLEDGER(1)
diff --git a/hledger.cabal b/hledger.cabal
--- a/hledger.cabal
+++ b/hledger.cabal
@@ -5,7 +5,7 @@
 -- see: https://github.com/sol/hpack
 
 name:           hledger
-version:        1.41
+version:        1.42
 synopsis:       Command-line interface for the hledger accounting system
 description:    The command-line interface for the hledger accounting system.
                 Its basic function is to read a plain text file describing
@@ -69,6 +69,7 @@
     Hledger/Cli/Commands/Check.txt
     Hledger/Cli/Commands/Close.txt
     Hledger/Cli/Commands/Codes.txt
+    Hledger/Cli/Commands/Commands.txt
     Hledger/Cli/Commands/Commodities.txt
     Hledger/Cli/Commands/Demo.txt
     Hledger/Cli/Commands/Descriptions.txt
@@ -83,7 +84,9 @@
     Hledger/Cli/Commands/Print.txt
     Hledger/Cli/Commands/Register.txt
     Hledger/Cli/Commands/Rewrite.txt
+    Hledger/Cli/Commands/Repl.txt
     Hledger/Cli/Commands/Roi.txt
+    Hledger/Cli/Commands/Run.txt
     Hledger/Cli/Commands/Stats.txt
     Hledger/Cli/Commands/Tags.txt
     Hledger/Cli/Commands/Test.txt
@@ -97,11 +100,6 @@
   manual: True
   default: False
 
-flag terminfo
-  description: On POSIX systems, build with the terminfo lib for detecting terminal width
-  manual: False
-  default: True
-
 flag threaded
   description: Build with support for multithreaded execution
   manual: False
@@ -140,6 +138,7 @@
       Hledger.Cli.Commands.Register
       Hledger.Cli.Commands.Rewrite
       Hledger.Cli.Commands.Roi
+      Hledger.Cli.Commands.Run
       Hledger.Cli.Commands.Stats
       Hledger.Cli.Commands.Tags
       Hledger.Cli.CompoundBalanceCommand
@@ -151,7 +150,7 @@
   other-modules:
       Paths_hledger
   ghc-options: -Wall -Wno-incomplete-uni-patterns -Wno-missing-signatures -Wno-orphans -Wno-type-defaults -Wno-unused-do-bind -optP-Wno-nonportable-include-path
-  cpp-options: -DVERSION="1.41"
+  cpp-options: -DVERSION="1.42"
   build-depends:
       Decimal >=0.5.1
     , Diff >=0.2
@@ -168,7 +167,7 @@
     , githash >=0.1.6.2
     , hashable >=1.2.4
     , haskeline >=0.6
-    , hledger-lib ==1.41.*
+    , hledger-lib ==1.42.*
     , lucid
     , math-functions >=0.3.3.0
     , megaparsec >=7.0.0 && <9.8
@@ -193,9 +192,6 @@
     , utility-ht >=0.0.13
     , wizards >=1.0
   default-language: Haskell2010
-  if (!(os(windows))) && (flag(terminfo))
-    build-depends:
-        terminfo
   if (flag(debug))
     cpp-options: -DDEBUG
 
@@ -206,7 +202,7 @@
   hs-source-dirs:
       app
   ghc-options: -Wall -Wno-incomplete-uni-patterns -Wno-missing-signatures -Wno-orphans -Wno-type-defaults -Wno-unused-do-bind -optP-Wno-nonportable-include-path
-  cpp-options: -DVERSION="1.41"
+  cpp-options: -DVERSION="1.42"
   build-depends:
       Decimal >=0.5.1
     , aeson >=1 && <2.3
@@ -222,7 +218,7 @@
     , githash >=0.1.6.2
     , haskeline >=0.6
     , hledger
-    , hledger-lib ==1.41.*
+    , hledger-lib ==1.42.*
     , math-functions >=0.3.3.0
     , megaparsec >=7.0.0 && <9.8
     , microlens >=0.4
@@ -245,9 +241,6 @@
     , utility-ht >=0.0.13
     , wizards >=1.0
   default-language: Haskell2010
-  if (!(os(windows))) && (flag(terminfo))
-    build-depends:
-        terminfo
   if (flag(debug))
     cpp-options: -DDEBUG
   if flag(threaded)
@@ -259,7 +252,7 @@
   hs-source-dirs:
       test
   ghc-options: -Wall -Wno-incomplete-uni-patterns -Wno-missing-signatures -Wno-orphans -Wno-type-defaults -Wno-unused-do-bind -optP-Wno-nonportable-include-path
-  cpp-options: -DVERSION="1.41"
+  cpp-options: -DVERSION="1.42"
   build-depends:
       Decimal >=0.5.1
     , aeson >=1 && <2.3
@@ -275,7 +268,7 @@
     , githash >=0.1.6.2
     , haskeline >=0.6
     , hledger
-    , hledger-lib ==1.41.*
+    , hledger-lib ==1.42.*
     , math-functions >=0.3.3.0
     , megaparsec >=7.0.0 && <9.8
     , microlens >=0.4
@@ -298,9 +291,6 @@
     , utility-ht >=0.0.13
     , wizards >=1.0
   default-language: Haskell2010
-  if (!(os(windows))) && (flag(terminfo))
-    build-depends:
-        terminfo
   if (flag(debug))
     cpp-options: -DDEBUG
 
@@ -326,7 +316,7 @@
     , githash >=0.1.6.2
     , haskeline >=0.6
     , hledger
-    , hledger-lib ==1.41.*
+    , hledger-lib ==1.42.*
     , html
     , math-functions >=0.3.3.0
     , megaparsec >=7.0.0 && <9.8
@@ -351,8 +341,5 @@
     , wizards >=1.0
   buildable: False
   default-language: Haskell2010
-  if (!(os(windows))) && (flag(terminfo))
-    build-depends:
-        terminfo
   if (flag(debug))
     cpp-options: -DDEBUG
diff --git a/test/unittest.hs b/test/unittest.hs
--- a/test/unittest.hs
+++ b/test/unittest.hs
@@ -3,9 +3,6 @@
 (by running the test command limited to Hledger.Cli tests).
 -}
 
--- cabal missing-home-modules workaround from hledger-lib, seems not needed here
--- {-# LANGUAGE PackageImports #-}
--- import "hledger" Hledger.Cli (tests_Hledger_Cli)
 import Hledger.Cli (tests_Hledger_Cli)
 import System.Environment (setEnv)
 import Test.Tasty (defaultMain)