From 391bd6fac9ba05b85a5040ec6cf1fb4582142008 Mon Sep 17 00:00:00 2001
From: Simon Michael <simon@joyful.com>
Date: Wed, 16 Oct 2024 15:01:57 -1000
Subject: [PATCH] ;doc: special characters: clarify windows differences

---
 hledger/hledger.m4.md | 22 +++++++++++++++++-----
 1 file changed, 17 insertions(+), 5 deletions(-)

diff --git a/hledger/hledger.m4.md b/hledger/hledger.m4.md
index 1a8a8ce4c..3bd788104 100644
--- a/hledger/hledger.m4.md
+++ b/hledger/hledger.m4.md
@@ -273,7 +273,7 @@ feel free to skip these until you need them.
 
 ## Special characters
 
-### Single escaping (shell metacharacters)
+### Single escaping (for shell metacharacters)
 
 In shell command lines, characters significant to your shell - such as
 spaces, `<`, `>`, `(`, `)`, `|`, `$` and `\` - should be
@@ -281,6 +281,12 @@ spaces, `<`, `>`, `(`, `)`, `|`, `$` and `\` - should be
 enclosing them in single or double quotes, or by writing a backslash
 before them. Eg to match an account name containing a space:
 
+```cli
+$ hledger register "credit card"
+```
+
+or:
+
 ```cli
 $ hledger register 'credit card'
 ```
@@ -291,11 +297,17 @@ or:
 $ hledger register credit\ card
 ```
 
-Windows users should keep in mind that `cmd` treats single quote as a
-regular character, so you should be using double quotes exclusively.
-PowerShell treats both single and double quotes as quotes.
+### Escaping on Windows
 
-### Double escaping (regular expression metacharacters)
+If you are using hledger on Microsoft Windows, unless you are using a Unix-like shell (such Windows Subsystem for Linux),
+be aware that the escaping rules are different. In particular:
+
+- 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 following sections assume a Unix-like shell, and will need to be adapted if you're using `cmd` or `powershell`. (Edits welcome.)
+
+### Double escaping (for regular expression metacharacters)
 
 Characters significant in [regular expressions]
 (described below) - such as `.`, `^`, `$`, `[`, `]`, `(`, `)`, `|`,