ref: a4049a3f1b58bbc699b86808bb2fe6dcb692fefc
parent: 8a75cc50518d3d7bad9f7110fa2d13bf3ccc74a4
author: dannye <[email protected]>
date: Sat Feb 27 06:29:53 EST 2021
rgbasm(5): Clarify charmap behavior (#558)
--- a/src/asm/rgbasm.5
+++ b/src/asm/rgbasm.5
@@ -391,17 +391,22 @@
.Pq So %% Sc is replaced by the So % Sc character .
.El
.Ss Character maps
-When writing text that is meant to be displayed in the Game Boy, the characters used in the source code may have a different encoding than the default of ASCII.
-For example, the tiles used for uppercase letters may be placed starting at tile index 128, which makes it difficult to add text strings to the ROM.
+When writing text that is meant to be displayed on the Game Boy, the characters used in the source code may need to have a different encoding than the rest of the source code.
+For example, the tiles used for uppercase letters may be placed starting at tile index 128, which would make it difficult to add text strings to the ROM.
.Pp
-Character maps allow mapping strings up to 16 characters long to an abitrary 8-bit value:
+Character maps allow mapping strings to arbitrary 8-bit values:
.Bd -literal -offset indent
CHARMAP "<LF>", 10
CHARMAP "í", 20
CHARMAP "A", 128
.Ed
-By default, a character map contains ASCII encoding.
+This would result in
+.Ql db \(dqAmen<LF>\(dq
+being equivalent to
+.Ql db 128, 109, 101, 110, 10 .
.Pp
+Any characters in a string without defined mappings will be copied directly, using the source file's encoding of characters to bytes.
+.Pp
It is possible to create multiple character maps and then switch between them as desired.
This can be used to encode debug information in ASCII and use a different encoding for other purposes, for example.
Initially, there is one character map called
@@ -410,8 +415,8 @@
There is also a character map stack that can be used to save and restore which character map is currently active.
.Bl -column "NEWCHARMAP name, basename"
.It Sy Command Ta Sy Meaning
-.It Ic NEWCHARMAP Ar name Ta Creates a new, empty character map called Ar name .
-.It Ic NEWCHARMAP Ar name , basename Ta Creates a new character map called Ar name , No copied from character map Ar basename .
+.It Ic NEWCHARMAP Ar name Ta Creates a new, empty character map called Ar name No and switches to it.
+.It Ic NEWCHARMAP Ar name , basename Ta Creates a new character map called Ar name , No copied from character map Ar basename , No and switches to it.
.It Ic SETCHARMAP Ar name Ta Switch to character map Ar name .
.It Ic PUSHC Ta Push the current character map onto the stack.
.It Ic POPC Ta Pop a character map off the stack and switch to it.
@@ -418,12 +423,7 @@
.El
.Pp
.Sy Note:
-Character maps affect all strings in the file from the point in which they are defined, until switching to a different character map.
-This means that any string that the code may want to print as debug information will also be affected by it.
-.Pp
-.Sy Note:
-The output value of a mapping can be 0.
-If this happens, the assembler will treat this as the end of the string and the rest of it will be trimmed.
+Modifications to a character map take effect immediately from that point onward.
.Ss Other functions
There are a few other functions that do various useful things:
.Bl -column "DEF(symbol)"