Document character maps

Signed-off-by: Antonio Niño Díaz <antonio_nd@outlook.com>

src/asm/rgbasm.5

@@ -5,7 +5,7 @@
 .\"
 .\" SPDX-License-Identifier: MIT
 .\"
-.Dd February 26, 2018
+.Dd March 13, 2018
 .Dt RGBASM 5
 .Os RGBDS Manual
 .Sh NAME
@@ -1041,6 +1041,34 @@ new string.
 the new string.
 .El
 .Pp
+.Ss Character maps
+.Pp
+When writing text that is meant to be displayed in the Game Boy, the ASCII
+characters used in the source code may not be the same ones used in the tileset
+used in the ROM.
+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.
+.Pp
+Character maps allow the code to map strings up to 16 characters long to an
+abitrary 8-bit value:
+.Pp
+.Bd -literal -offset indent
+CHARMAP "<LF>", 10
+CHARMAP "&iacute", 20
+CHARMAP "A", 128
+.Ed
+.Pp
+.Sy Note:
+Character maps affect all strings in the file from the point in which they are
+defined.
+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.
+.Pp
 .Ss Other functions
 There are a few other functions that do various useful things:
 .Pp
@@ -1123,6 +1151,7 @@ machine.
 .It Sx ATAN
 .It Sx ATAN2
 .It Sx BANK
+.It Sx CHARMAP
 .It Sx COS
 .It Sx DB
 .It Sx DEF