From 0f4413f011370e8134f9b8cb4be5db37b8cc9fde Mon Sep 17 00:00:00 2001
From: Simon Michael <simon@joyful.com>
Date: Fri, 24 Mar 2023 12:44:53 -1000
Subject: [PATCH] doc: ui: note transaction screen's inability to update; code
 cleanup

---
 hledger-ui/Hledger/UI/TransactionScreen.hs | 17 ++++++++++-------
 hledger-ui/Hledger/UI/UIScreens.hs         |  6 ++++--
 hledger-ui/hledger-ui.m4.md                | 10 ++++++++++
 3 files changed, 24 insertions(+), 9 deletions(-)

diff --git a/hledger-ui/Hledger/UI/TransactionScreen.hs b/hledger-ui/Hledger/UI/TransactionScreen.hs
index bab6d246c..bfe550f04 100644
--- a/hledger-ui/Hledger/UI/TransactionScreen.hs
+++ b/hledger-ui/Hledger/UI/TransactionScreen.hs
@@ -30,7 +30,7 @@ import Hledger.UI.UIUtils
 import Hledger.UI.UIScreens
 import Hledger.UI.Editor
 import Brick.Widgets.Edit (editorText, renderEditor)
-import Hledger.UI.ErrorScreen (uiReloadJournalIfChanged, uiCheckBalanceAssertions)
+import Hledger.UI.ErrorScreen (uiReloadJournalIfChanged, uiCheckBalanceAssertions, uiReloadJournal)
 
 tsDraw :: UIState -> [Widget Name]
 tsDraw UIState{aopts=UIOpts{uoCliOpts=copts@CliOpts{reportspec_=rspec@ReportSpec{_rsReportOpts=ropts}}}
@@ -145,12 +145,15 @@ tsHandle ev = do
               put' $ regenerateScreens j d $ setReportPeriod (DayPeriod d) ui
               where
                 p = reportPeriod ui
-            e | e `elem` [VtyEvent (EvKey (KChar 'g') []), AppEvent FileChange] -> do
-              -- plog (if e == AppEvent FileChange then "file change" else "manual reload") "" `seq` return ()
-              ej <- liftIO . runExceptT $ journalReload copts
-              case ej of
-                Left err -> put' $ pushScreen (esNew err) ui
-                Right j' -> put' $ regenerateScreens j' d ui
+
+            -- Reload. Warning, this updates parent screens but not the transaction screen itself (see tsUpdate).
+            -- To see the updated transaction, one must exit and re-enter the transaction screen.
+            e | e `elem` [VtyEvent (EvKey (KChar 'g') []), AppEvent FileChange] ->
+              liftIO (uiReloadJournal copts d ui) >>= put'
+                -- debugging.. leaving these here because they were hard to find
+                -- \u -> dbguiEv (pshow u) >> put' u  -- doesn't log
+                -- \UIState{aScreen=TS tss} -> error $ pshow $ _tssTransaction tss
+
             VtyEvent (EvKey (KChar 'I') []) -> put' $ uiCheckBalanceAssertions d (toggleIgnoreBalanceAssertions ui)
 
             -- for toggles that may change the current/prev/next transactions,
diff --git a/hledger-ui/Hledger/UI/UIScreens.hs b/hledger-ui/Hledger/UI/UIScreens.hs
index 9fc086bb2..73c1d529b 100644
--- a/hledger-ui/Hledger/UI/UIScreens.hs
+++ b/hledger-ui/Hledger/UI/UIScreens.hs
@@ -352,8 +352,10 @@ tsNew acct nts nt =
     ,_tssTransaction  = nt
     }
 
--- | Update a transaction screen. Currently a no-op since transaction screen
--- depends only on its screen-specific state.
+-- | Update a transaction screen. 
+-- This currently does nothing because the initialisation in rsHandle is not so easy to extract.
+-- To see the updated transaction, one must exit and re-enter the transaction screen.
+-- See also tsHandle.
 tsUpdate :: TransactionScreenState -> TransactionScreenState
 tsUpdate = dbgui "tsUpdate"
 
diff --git a/hledger-ui/hledger-ui.m4.md b/hledger-ui/hledger-ui.m4.md
index 3e2ca5093..cf5c65675 100644
--- a/hledger-ui/hledger-ui.m4.md
+++ b/hledger-ui/hledger-ui.m4.md
@@ -307,6 +307,16 @@ preceding them is the transaction's position within the complete
 unfiltered journal, which is a more stable id (at least until the next
 reload).
 
+On this screen (and the register screen), the `E` key will open your text editor
+with the cursor positioned at the current transaction if possible.
+
+This screen has a limitation with showing file updates:
+it will not show them until you exit and re-enter it.
+So eg to see the effect of using the `E` key, currently you must:
+- press `E`, edit and save the file, then exit the editor, returning to hledger-ui
+- press `g` to reload the file (or use `-w/--watch` mode)
+- press `LEFT` then `RIGHT` to exit and re-enter the transaction screen.
+
 ## Error
 
 This screen will appear if there is a problem, such as a parse error,