Skip to content

Commit e73c3c8

Browse files
committed
📝 [docs] Improve ANSI Color Script Guide with additional clarity and formatting
- Added spacing for better readability in sections on backtick escape sequences and here-string vs write-host lines - Clarified common mistakes with backslash-backtick usage - Enhanced quick reference table formatting for easier understanding Signed-off-by: Nick2bad4u <20943337+Nick2bad4u@users.noreply.github.com>
1 parent 5853372 commit e73c3c8

1 file changed

Lines changed: 20 additions & 11 deletions

File tree

‎ANSI-COLOR-GUIDE.md‎

Lines changed: 20 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@
1919
### 2. **Backtick Escape Sequences**
2020

2121
**Problem:** Backticks (`` ` ``) before certain letters create escape sequences:
22+
2223
- `` `b `` = backspace
2324
- `` `d `` = (not defined but causes issues)
2425
- `` `t `` = tab
@@ -61,11 +62,13 @@
6162
### 5. **Here-String vs Write-Host Lines**
6263

6364
**Here-String Issues:**
65+
6466
- Variable interpolation happens all at once
6567
- Harder to debug specific lines
6668
- Can have unexpected escape sequence interactions
6769

6870
**Write-Host Line-by-Line:**
71+
6972
- Each line is independent
7073
- Easier to debug
7174
- Better control over color transitions
@@ -92,14 +95,16 @@ Write-Host "$red`$`$`$$reset${gray}P^*^T$reset$red`$`$$reset"
9295
```
9396

9497
This ensures:
98+
9599
- No variable name collisions
96100
- Clean color boundaries
97101
- Predictable output
98102

99103
### 7. **Special Characters That Need Backticks**
100104

101105
Characters that need escaping in double-quoted strings:
102-
- `` ` `` (backtick itself) - ``` `` ```
106+
107+
- `` ` `` (backtick itself) - ` `` `
103108
- `$` (dollar) - `` `$ ``
104109
- `"` (quote) - `` `" ``
105110
- Newlines/tabs if you DON'T want them - `` `n ``, `` `t ``
@@ -125,11 +130,13 @@ Write-Host "`$dollar" # Outputs: $dollar
125130
```
126131

127132
**Common Pattern Mistakes:**
133+
128134
- `\`` - This is backslash + escaped-backtick (outputs: \`)
129135
- `\.` - This is just backslash + period (outputs: \.)
130136
- `\-` - This is just backslash + dash (outputs: \-)
131137

132138
**When working with ASCII art containing backslashes:**
139+
133140
- Use `\\` to output a single backslash (PowerShell string literal, not escaping)
134141
- Use `\` followed by any character that's not special
135142
- Never use `` \` `` unless you specifically want backslash-backtick output
@@ -153,11 +160,12 @@ Write-Host "``*TP*" # Outputs: `*TP*
153160
**Common Mistakes with Backslash-Backtick (`\```):**
154161

155162
The pattern `\``` appears to work but causes subtle parser errors:
163+
156164
- `\``` means: backslash + backtick-escape-for-backtick
157165
- This creates ambiguous parsing situations
158166
- Can cause "Unexpected token" errors at seemingly random positions
159167

160-
**Always use double-backtick (``` `` ```) for literal backticks, never `\```**
168+
**Always use double-backtick (` `` `) for literal backticks, never `\```**
161169

162170
```powershell
163171
# ❌ WRONG - All of these use incorrect \` pattern
@@ -199,6 +207,7 @@ If output is misaligned:
199207
7. **Watch for incorrect backslash escaping** - Don't use `` \` `` when you mean `\.` or `\-`
200208

201209
**Character Counting Tips:**
210+
202211
- Count each literal `$` in the original ASCII (each becomes `` `$ `` in code)
203212
- Verify spaces match exactly
204213
- Check that backslashes are literal `\`, not escaped with backtick
@@ -242,15 +251,15 @@ Write-Host "${gray} .sd$red`$`$`$`$`$`$`$$reset${gray}P^*^T${reset}$r
242251

243252
## Quick Reference
244253

245-
| Issue | Wrong | Right |
246-
|-------|-------|-------|
247-
| Letter after color | `${gray}P` | `$reset${gray}P` |
248-
| Backtick + letter | ``` ${white}`bug ``` | `$reset${white}bug` |
249-
| Dollar signs | `$$$` | `` `$`$`$ `` |
250-
| Color transitions | `$red$$$${gray}P` | `$red`$`$`$$reset${gray}P` |
251-
| Complex strings | Here-string | Write-Host lines |
252-
| Backslash escaping | `` \`. `` or `` \`- `` | `\.` or `\-` |
253-
| Missing dollars | Count mismatch | Count each $ in original |
254+
| Issue | Wrong | Right |
255+
| ------------------ | ------------------ | -------------------------- |
256+
| Letter after color | `${gray}P` | `$reset${gray}P` |
257+
| Backtick + letter | ``${white}`bug`` | `$reset${white}bug` |
258+
| Dollar signs | `$$$` | `` `$`$`$ `` |
259+
| Color transitions | `$red$$$${gray}P` | `$red`$`$`$$reset${gray}P` |
260+
| Complex strings | Here-string | Write-Host lines |
261+
| Backslash escaping | ``\`.`` or ``\`-`` | `\.` or `\-` |
262+
| Missing dollars | Count mismatch | Count each $ in original |
254263

255264
## Testing Checklist
256265

0 commit comments

Comments
 (0)