Regenerate man page HTML renders

2025-11-21 10:42:07 +00:00 · 2020-04-03 12:03:59 +02:00
parent bdad1499fe
commit 80170eb6eb
9 changed files with 2362 additions and 1613 deletions
--- a/docs/rgblink.1.html
+++ b/docs/rgblink.1.html
@@ -3,13 +3,15 @@
 <!-- This is an automatically generated file.  Do not edit.
   This file is part of RGBDS.
  
-   Copyright (c) 2010-2018, Anthony J. Bentley and RGBDS contributors.
+   Copyright (c) 2010-2019, Anthony J. Bentley and RGBDS contributors.
  
   SPDX-License-Identifier: MIT
   -->
 <head>
+  <meta name="viewport" content="width=device-width, initial-scale=1">
  <meta charset="utf-8"/>
  <link rel="stylesheet" href="mandoc.css" type="text/css" media="all"/>
+  <link rel="stylesheet" href="rgbds.css" type="text/css" media="all"/>
  <title>RGBLINK(1)</title>
 </head>
 <body>
@@ -24,81 +26,114 @@
 <section class="Sh">
 <h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1>
 <code class="Nm">rgblink</code> &#x2014;
-<div class="Nd">Game Boy linker</div>
+<span class="Nd">Game Boy linker</span>
 </section>
 <section class="Sh">
 <h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1>
 <table class="Nm">
  <tr>
    <td><code class="Nm">rgblink</code></td>
-    <td>[<code class="Fl">-dtVw</code>] [<code class="Fl">-m</code>
-      <var class="Ar">mapfile</var>] [<code class="Fl">-n</code>
-      <var class="Ar">symfile</var>] [<code class="Fl">-O</code>
-      <var class="Ar">overlayfile</var>] [<code class="Fl">-o</code>
-      <var class="Ar">outfile</var>] [<code class="Fl">-p</code>
-      <var class="Ar">pad_value</var>] [<code class="Fl">-s</code>
-      <var class="Ar">symbol</var>] [<code class="Fl">-l</code>
-      <var class="Ar">linkerscript</var>] <var class="Ar">file ...</var></td>
+    <td>[<code class="Fl"><a href="#d">-d</a><a href="#t">t</a><a href="#V">V</a><a href="#v">v</a><a href="#w">w</a></code>] [<code class="Fl"><a href="#l">-l</a></code>
+      <var class="Ar">linker_script</var>] [<code class="Fl"><a href="#m">-m</a></code>
+      <var class="Ar">map_file</var>] [<code class="Fl"><a href="#n">-n</a></code>
+      <var class="Ar">sym_file</var>] [<code class="Fl"><a href="#O">-O</a></code>
+      <var class="Ar">overlay_file</var>] [<code class="Fl"><a href="#o">-o</a></code>
+      <var class="Ar">out_file</var>] [<code class="Fl"><a href="#p">-p</a></code>
+      <var class="Ar">pad_value</var>] [<code class="Fl"><a href="#s">-s</a></code>
+      <var class="Ar">symbol</var>] <var class="Ar">file ...</var></td>
  </tr>
 </table>
 </section>
 <section class="Sh">
 <h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1>
-The <code class="Nm">rgblink</code> program links objects created by
-  <a class="Xr">rgbasm(1)</a> into a single Game Boy ROM file.
-<p class="Pp">By default, ROM0 sections created by the assembler are placed in
-    the 16KiB bank 0, and ROMX sections are placed in any bank except bank 0. If
-    your ROM will only be 32KiB, you can use the <code class="Fl">-t</code>
-    option to override this.</p>
-<p class="Pp">Similarly, WRAM0 sections are placed in the first 4KiB of WRAM
-    bank 0 and WRAMX sections are placed in any bank except bank 0. If your ROM
-    doesn't use banked WRAM you can use option <code class="Fl">-w</code> option
-    to override this.</p>
-<p class="Pp">Also, if your ROM is designed for DMG, you can make sure that you
-    don't use any prohibited section by using the option
-    <code class="Fl">-d</code>, which implies <code class="Fl">-w</code> but
-    also prohibits the use of VRAM bank 1.</p>
-<p class="Pp">The arguments are as follows:</p>
+The <code class="Nm">rgblink</code> program links RGB object files, typically
+  created by <a class="Xr" href="rgbasm.1.html">rgbasm(1)</a>, into a single Game Boy ROM file. The
+  format is documented in <a class="Xr" href="rgbds.5.html">rgbds(5)</a>.
+<p class="Pp">ROM0 sections are placed in the first 16 KiB of the output ROM,
+    and ROMX sections are placed in any 16 KiB &#x201C;bank&#x201D; except the
+    first. If your ROM will only be 32 KiB, you can use the
+    <code class="Fl">-t</code> option to change this.</p>
+<p class="Pp">Similarly, WRAM0 sections are placed in the first 4 KiB of WRAM
+    (&#x201C;bank 0&#x201D;), and WRAMX sections are placed in any bank of the
+    last 4 KiB. If your ROM doesn't use banked WRAM, you can use the
+    <code class="Fl">-w</code> option to change this.</p>
+<p class="Pp">Also, if your ROM is designed for a monochrome Game Boy, you can
+    make sure that you don't use any incompatible section by using the
+    <code class="Fl">-d</code> option, which implies <code class="Fl">-w</code>
+    but also prohibits the use of banked VRAM.</p>
+<p class="Pp">Note that options can be abbreviated as long as the abbreviation
+    is unambiguous: <code class="Fl">--verb</code> is
+    <code class="Fl">--verbose</code>, but
+    <code class="Fl">--ver</code> is invalid because it
+    could also be <code class="Fl">--version</code>. The
+    arguments are as follows:</p>
 <dl class="Bl-tag">
-  <dt><a class="permalink" href="#m"><code class="Fl" id="m">-m</code></a>
-    <var class="Ar">mapfile</var></dt>
-  <dd>Write a mapfile to the given filename.</dd>
-  <dt><a class="permalink" href="#n"><code class="Fl" id="n">-n</code></a>
-    <var class="Ar">symfile</var></dt>
-  <dd>Write a symbol file to the given filename.</dd>
-  <dt><a class="permalink" href="#O"><code class="Fl" id="O">-O</code></a>
-    <var class="Ar">overlayfile</var></dt>
-  <dd>The ROM image to overlay sections over. When an overlay ROM is provided,
-      all sections must be fixed. This may be used to patch an existing
-    binary.</dd>
-  <dt><a class="permalink" href="#o"><code class="Fl" id="o">-o</code></a>
-    <var class="Ar">outfile</var></dt>
-  <dd>Write ROM image to the given filename.</dd>
-  <dt><a class="permalink" href="#p"><code class="Fl" id="p">-p</code></a>
-    <var class="Ar">pad_value</var></dt>
-  <dd>When padding an image, pad with this value. The default is 0x00.</dd>
-  <dt><a class="permalink" href="#s"><code class="Fl" id="s">-s</code></a>
-    <var class="Ar">symbol</var></dt>
-  <dd>???</dd>
-  <dt><a class="permalink" href="#w"><code class="Fl" id="w">-w</code></a></dt>
-  <dd>Expand the WRAM0 section size from 4KiB to the full 8KiB assigned to WRAM
-      and prohibit the use of WRAMX sections.</dd>
-  <dt><a class="permalink" href="#d"><code class="Fl" id="d">-d</code></a></dt>
+  <dt><a class="permalink" href="#d"><code class="Fl" id="d">-d</code></a>,
+    <code class="Fl">--dmg</code></dt>
  <dd>Enable DMG mode. Prohibit the use of sections that doesn't exist on a DMG,
      such as WRAMX and VRAM bank 1. This option automatically enables
      <code class="Fl">-w</code>.</dd>
-  <dt><a class="permalink" href="#t"><code class="Fl" id="t">-t</code></a></dt>
-  <dd>Expand the ROM0 section size from 16KiB to the full 32KiB assigned to ROM
-      and prohibit the use of ROMX sections. Useful for ROMs that fit in 32
-    KiB.</dd>
  <dt><a class="permalink" href="#l"><code class="Fl" id="l">-l</code></a>
-    <var class="Ar">linkerscript</var></dt>
-  <dd>Specify a linkerscript file that tells the linker how sections must be
-      placed in the ROM. This file has priority over the attributes assigned in
-      the source code, but they have to be consistent. See
-      <a class="Xr">rgblink(5)</a> for more information about its format.</dd>
-  <dt><a class="permalink" href="#V"><code class="Fl" id="V">-V</code></a></dt>
+    <var class="Ar">linker_script,</var>
+    <code class="Fl">--linkerscript</code>
+    <var class="Ar">linker_script</var></dt>
+  <dd>Specify a linker script file that tells the linker how sections must be
+      placed in the ROM. The attributes assigned in the linker script must be
+      consistent with any assigned in the code. See <a class="Xr" href="rgblink.5.html">rgblink(5)</a>
+      for more information about the linker script format.</dd>
+  <dt><a class="permalink" href="#m"><code class="Fl" id="m">-m</code></a>
+    <var class="Ar">map_file</var>,
+    <code class="Fl">--map</code>
+    <var class="Ar">map_file</var></dt>
+  <dd>Write a map file to the given filename, listing how sections and symbols
+      were assigned.</dd>
+  <dt><a class="permalink" href="#n"><code class="Fl" id="n">-n</code></a>
+    <var class="Ar">sym_file</var>,
+    <code class="Fl">--sym</code>
+    <var class="Ar">sym_file</var></dt>
+  <dd>Write a symbol file to the given filename, listing the address of all
+      exported symbols. Several external programs can use this information, for
+      example to help debugging ROMs.</dd>
+  <dt><a class="permalink" href="#O"><code class="Fl" id="O">-O</code></a>
+    <var class="Ar">overlay_file</var>,
+    <code class="Fl">--overlay</code>
+    <var class="Ar">overlay_file</var></dt>
+  <dd>If specified, sections will be overlaid &quot;on top&quot; of the provided
+      ROM image. In that case, all sections must be fixed. This may be used to
+      patch an existing binary.</dd>
+  <dt><a class="permalink" href="#o"><code class="Fl" id="o">-o</code></a>
+    <var class="Ar">out_file</var>,
+    <code class="Fl">--output</code>
+    <var class="Ar">out_file</var></dt>
+  <dd>Write the ROM image to the given file.</dd>
+  <dt><a class="permalink" href="#p"><code class="Fl" id="p">-p</code></a>
+    <var class="Ar">pad_value</var>,
+    <code class="Fl">--pad</code>
+    <var class="Ar">pad_value</var></dt>
+  <dd>When inserting padding between sections, pad with this value. Has no
+      effect if <code class="Fl">-O</code> is specified. The default is 0.</dd>
+  <dt><a class="permalink" href="#s"><code class="Fl" id="s">-s</code></a>
+    <var class="Ar">symbol</var>,
+    <code class="Fl">--smart</code>
+    <var class="Ar">symbol</var></dt>
+  <dd>This option is ignored. It was supposed to perform smart linking but fell
+      into disrepair, and so has been removed. It will be reimplemented at some
+      point.</dd>
+  <dt><a class="permalink" href="#t"><code class="Fl" id="t">-t</code></a>,
+    <code class="Fl">--tiny</code></dt>
+  <dd>Expand the ROM0 section size from 16 KiB to the full 32 KiB assigned to
+      ROM and prohibit the use of ROMX sections. Useful for ROMs that fit in 32
+      KiB.</dd>
+  <dt><a class="permalink" href="#V"><code class="Fl" id="V">-V</code></a>,
+    <code class="Fl">--version</code></dt>
  <dd>Print the version of the program and exit.</dd>
+  <dt><a class="permalink" href="#v"><code class="Fl" id="v">-v</code></a>,
+    <code class="Fl">--verbose</code></dt>
+  <dd>Verbose: enable printing more information to standard error.</dd>
+  <dt><a class="permalink" href="#w"><code class="Fl" id="w">-w</code></a>,
+    <code class="Fl">--wramx</code></dt>
+  <dd>Expand the WRAM0 section size from 4 KiB to the full 8 KiB assigned to
+      WRAM and prohibit the use of WRAMX sections.</dd>
 </dl>
 </section>
 <section class="Sh">
@@ -107,18 +142,28 @@ All you need for a basic ROM is an object file, which can be made into a ROM
  image like so:
 <p class="Pp"></p>
 <div class="Bd Bd-indent">$ rgblink -o bar.gb foo.o</div>
-<p class="Pp">The resulting bar.gb will not have correct checksums (unless you
-    put them in the assembly source). You should use <a class="Xr">rgbfix(1)</a>
-    to fix these so that the program will actually run in a Game Boy:</p>
+<p class="Pp">The resulting <var class="Ar">bar.gb</var> will not have correct
+    checksums (unless you put them in the assembly source). You should use
+    <a class="Xr" href="rgbfix.1.html">rgbfix(1)</a> to fix these so that the program will actually
+    run in a Game Boy:</p>
 <p class="Pp"></p>
-<div class="Bd Bd-indent">$ rgbfix -v bar.gb</div>
+<div class="Bd Bd-indent"><code class="Li">$ rgbfix -v bar.gb</code></div>
+<p class="Pp">Here is a more complete example:</p>
+<p class="Pp"></p>
+<div class="Bd Bd-indent"><code class="Li">$ rgblink -o bin/game.gb -n
+  bin/game.sym -p 0xFF obj/title.o obj/engine.o</code></div>
+</section>
+<section class="Sh">
+<h1 class="Sh" id="BUGS"><a class="permalink" href="#BUGS">BUGS</a></h1>
+Please report bugs on
+  <a class="Lk" href="https://github.com/rednex/rgbds/issues">GitHub</a>.
 </section>
 <section class="Sh">
 <h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE
  ALSO</a></h1>
-<a class="Xr">rgbasm(1)</a>, <a class="Xr">rgblink(5)</a>,
-  <a class="Xr">rgbfix(1)</a>, <a class="Xr">rgbds(5)</a>,
-  <a class="Xr">rgbds(7)</a>
+<a class="Xr" href="rgbasm.1.html">rgbasm(1)</a>, <a class="Xr" href="rgblink.5.html">rgblink(5)</a>,
+  <a class="Xr" href="rgbfix.1.html">rgbfix(1)</a>, <a class="Xr" href="rgbds.5.html">rgbds(5)</a>,
+  <a class="Xr" href="rgbds.7.html">rgbds(7)</a>
 </section>
 <section class="Sh">
 <h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1>
@@ -130,8 +175,8 @@ All you need for a basic ROM is an object file, which can be made into a ROM
 </div>
 <table class="foot">
  <tr>
-    <td class="foot-date">January 26, 2018</td>
-    <td class="foot-os">RGBDS Manual</td>
+    <td class="foot-date">November 26, 2019</td>
+    <td class="foot-os">General</td>
  </tr>
 </table>
 </body>