Document character maps

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

docs/rgbasm.5.html

@@ -1309,6 +1309,32 @@ Whenever the macro-language expects a string you can actually use a string
       returns the new string.</td>
   </tr>
 </table>
+<h2 class="Ss" title="Ss" id="Character_maps"><a class="selflink" href="#Character_maps">Character
+  maps</a></h2>
+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.
+<div class="Pp"></div>
+Character maps allow the code to map strings up to 16 characters long to an
+  abitrary 8-bit value:
+<div class="Pp"></div>
+<div class="Bd" style="margin-left: 5.00ex;">
+<pre class="Li">
+CHARMAP &quot;&lt;LF&gt;&quot;, 10 
+CHARMAP &quot;&amp;iacute&quot;, 20 
+CHARMAP &quot;A&quot;, 128
+</pre>
+</div>
+<div class="Pp"></div>
+<b class="Sy" title="Sy">Note:</b> 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.
+<div class="Pp"></div>
+<b class="Sy" title="Sy">Note:</b> 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.
 <h2 class="Ss" title="Ss" id="Other_functions"><a class="selflink" href="#Other_functions">Other
   functions</a></h2>
 There are a few other functions that do various useful things:
@@ -1429,6 +1455,8 @@ The options that OPT can modify are currently: <b class="Sy" title="Sy">b</b>,
   <dd class="It-inset"></dd>
   <dt class="It-inset"><a class="Sx" title="Sx" href="#BANK">BANK</a></dt>
   <dd class="It-inset"></dd>
+  <dt class="It-inset"><a class="Sx" title="Sx" href="#CHARMAP">CHARMAP</a></dt>
+  <dd class="It-inset"></dd>
   <dt class="It-inset"><a class="Sx" title="Sx" href="#COS">COS</a></dt>
   <dd class="It-inset"></dd>
   <dt class="It-inset"><a class="Sx" title="Sx" href="#DB">DB</a></dt>
@@ -1563,7 +1591,7 @@ The options that OPT can modify are currently: <b class="Sy" title="Sy">b</b>,
   <a class="Lk" title="Lk" href="https://github.com/rednex/rgbds">https://github.com/rednex/rgbds</a>.</div>
 <table class="foot">
   <tr>
-    <td class="foot-date">February 26, 2018</td>
+    <td class="foot-date">March 13, 2018</td>
     <td class="foot-os">RGBDS Manual</td>
   </tr>
 </table>

docs/rgbfix.1.html

@@ -28,6 +28,8 @@
   <tr>
     <td><b class="Nm" title="Nm">rgbfix</b></td>
     <td>[<span class="Op"><b class="Fl" title="Fl">-CcjsVv</b></span>]
+      [<span class="Op"><b class="Fl" title="Fl">-f</b>
+      <var class="Ar" title="Ar">fix_spec</var></span>]
       [<span class="Op"><b class="Fl" title="Fl">-i</b>
       <var class="Ar" title="Ar">game_id</var></span>]
       [<span class="Op"><b class="Fl" title="Fl">-k</b>
@@ -67,6 +69,32 @@ The <b class="Nm" title="Nm">rgbfix</b> program changes headers of Game Boy ROM
       <b class="Fl" title="Fl">-C</b> takes precedence.</dd>
   <dt class="It-tag">&#x00A0;</dt>
   <dd class="It-tag">&#x00A0;</dd>
+  <dt class="It-tag"><a class="selflink" href="#f"><b class="Fl" title="Fl" id="f">-f</b></a>
+    <var class="Ar" title="Ar">fix_spec</var></dt>
+  <dd class="It-tag">Fix certain header values that the Game Boy checks for
+      correctness. Alternatively, intentionally trash these values by writing
+      their binary inverse instead. <var class="Ar" title="Ar">fix_spec</var> is
+      a string containing any combination of the following characters:
+    <div class="Pp"></div>
+    <dl class="Bl-tag Bl-compact" style="margin-left: 5.40ex;">
+      <dt class="It-tag" style="margin-left: -5.40ex;"><a class="selflink" href="#l"><b class="Cm" title="Cm" id="l">l</b></a></dt>
+      <dd class="It-tag">Fix the Nintendo logo
+          (<i class="Ad">0x104</i>&#x2013;<i class="Ad">0x133</i>).</dd>
+      <dt class="It-tag" style="margin-left: -5.40ex;"><a class="selflink" href="#L"><b class="Cm" title="Cm" id="L">L</b></a></dt>
+      <dd class="It-tag">Trash the Nintendo logo.</dd>
+      <dt class="It-tag" style="margin-left: -5.40ex;"><a class="selflink" href="#h"><b class="Cm" title="Cm" id="h">h</b></a></dt>
+      <dd class="It-tag">Fix the header checksum (<i class="Ad">0x14D</i>).</dd>
+      <dt class="It-tag" style="margin-left: -5.40ex;"><a class="selflink" href="#H"><b class="Cm" title="Cm" id="H">H</b></a></dt>
+      <dd class="It-tag">Trash the header checksum.</dd>
+      <dt class="It-tag" style="margin-left: -5.40ex;"><a class="selflink" href="#g"><b class="Cm" title="Cm" id="g">g</b></a></dt>
+      <dd class="It-tag">Fix the global checksum
+          (<i class="Ad">0x14E</i>&#x2013;<i class="Ad">0x14F</i>).</dd>
+      <dt class="It-tag" style="margin-left: -5.40ex;"><a class="selflink" href="#G"><b class="Cm" title="Cm" id="G">G</b></a></dt>
+      <dd class="It-tag">Trash the global checksum.</dd>
+    </dl>
+  </dd>
+  <dt class="It-tag">&#x00A0;</dt>
+  <dd class="It-tag">&#x00A0;</dd>
   <dt class="It-tag"><a class="selflink" href="#i"><b class="Fl" title="Fl" id="i">-i</b></a>
     <var class="Ar" title="Ar">game_id</var></dt>
   <dd class="It-tag">Set the game ID string
@@ -141,10 +169,8 @@ The <b class="Nm" title="Nm">rgbfix</b> program changes headers of Game Boy ROM
   <dt class="It-tag">&#x00A0;</dt>
   <dd class="It-tag">&#x00A0;</dd>
   <dt class="It-tag"><a class="selflink" href="#v"><b class="Fl" title="Fl" id="v">-v</b></a></dt>
-  <dd class="It-tag">Validate the header and fix checksums: the Nintendo
+  <dd class="It-tag">Equivalent to <b class="Fl" title="Fl">-f</b>
-      character area (<i class="Ad">0x104</i>&#x2013;<i class="Ad">0x133</i>),
+      <b class="Cm" title="Cm">lhg</b>.</dd>
-      the header checksum (<i class="Ad">0x14D</i>), and the global checksum
-      (<i class="Ad">0x14E</i>&#x2013;<i class="Ad">0x14F</i>).</dd>
 </dl>
 <h1 class="Sh" title="Sh" id="EXAMPLES"><a class="selflink" href="#EXAMPLES">EXAMPLES</a></h1>
 Most values in the ROM header are only cosmetic. The bare minimum requirements
@@ -179,7 +205,7 @@ The following will duplicate the header (sans global checksum) of the game
   <a class="Lk" title="Lk" href="https://github.com/rednex/rgbds">https://github.com/rednex/rgbds</a>.</div>
 <table class="foot">
   <tr>
-    <td class="foot-date">January 26, 2018</td>
+    <td class="foot-date">March 11, 2018</td>
     <td class="foot-os">RGBDS Manual</td>
   </tr>
 </table>

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

src/fix/rgbfix.1

@@ -5,7 +5,7 @@
 .\"
 .\" SPDX-License-Identifier: MIT
 .\"
-.Dd January 26, 2018
+.Dd March 11, 2018
 .Dt RGBFIX 1
 .Os RGBDS Manual
 .Sh NAME