shithub: rgbds

Info  •  Files  •  Log  •  Branches

Fix mistakes in RGBDS man pages

As reported by `mandoc -Wall`

--- a/src/asm/rgbasm.5

+++ b/src/asm/rgbasm.5

@@ -12,7 +12,6 @@

 .Nm rgbasm

 .Nd language documentation

 .Sh DESCRIPTION

-.Pp

 This is the full description of the language used by

 .Xr rgbasm 1 .

 The description of the instructions supported by the Game Boy CPU is in

@@ -30,7 +29,6 @@

 .Xr rgbds 5 )

 can be used in its place.

 .Sh SYNTAX

-.Pp

 The syntax is line‐based, just as in any other assembler, meaning that you do one instruction or pseudo‐op per line:

 .Pp

 .Dl Oo Ar label Oc Oo Ar instruction Oc Oo Ar ;\ comment Oc

@@ -47,7 +45,8 @@

 .Em always

 ignores comments and their contents.

 .Pp

-There are three syntaxes for comments. The most common is that anything that follows a semicolon

+There are three syntaxes for comments.

+The most common is that anything that follows a semicolon

 .Ql \&;

 not inside a string, is a comment until the end of the line.

 The second is a block comment, beginning with

@@ -81,7 +80,6 @@

               "world!")

 .Ed

 .Sh EXPRESSIONS

-.Pp

 An expression can be composed of many things.

 Numerical expressions are always evaluated using signed 32-bit math.

 Zero is considered to be the only "false" number, all non-zero numbers (including negative) are "true".

@@ -95,9 +93,7 @@

 .Pp

 The instructions in the macro-language generally require constant expressions.

 .Ss Numeric Formats

-.Pp

 There are a number of numeric formats.

-.Pp

 .Bl -column -offset indent "Fixed point (16.16)" "Prefix"

 .It Sy Format type Ta Sy Prefix Ta Sy Accepted characters

 .It Hexadecimal Ta $ Ta 0123456789ABCDEF

@@ -128,9 +124,7 @@

 .Pp

 You can also use symbols, which are implicitly replaced with their value.

 .Ss Operators

-.Pp

 A great number of operators you can use in expressions are available (listed from highest to lowest precedence):

-.Pp

 .Bl -column -offset indent "!= == <= >= < >"

 .It Sy Operator Ta Sy Meaning

 .It Li \&( \&) Ta Precedence override

@@ -176,7 +170,6 @@

 .Pp

 ! returns 1 if the operand was 0, and 0 otherwise.

 .Ss Fixed‐point Expressions

-.Pp

 Fixed-point numbers are basically normal (32-bit) integers, which count 65536th's instead of entire units, offering better precision than integers but limiting the range of values.

 The upper 16 bits are used for the integer part and the lower 16 bits are used for the fraction (65536ths).

 Since they are still akin to integers, you can use them in normal integer expressions, and some integer operators like

@@ -191,7 +184,6 @@

 .EQ

 delim $$

 .EN

-.Pp

 .Bl -column -offset indent "ATAN2(x, y)"

 .It Sy Name Ta Sy Operation

 .It Fn DIV x y Ta $x \[di] y$

@@ -222,7 +214,6 @@

       ENDR

 .Ed

 .Ss String Expressions

-.Pp

 The most basic string expression is any number of characters contained in double quotes

 .Pq Ql \&"for instance" .

 The backslash character

@@ -231,8 +222,7 @@

 .Dq escaped ,

 meaning that it is treated differently from normal.

 There are a number of escape sequences you can use within a string:

-.Pp

-.Bl -column -offset indent "'\1' - '\9'"

+.Bl -column -offset indent "Qo \[rs]1 Qc \[en] Qo \[rs]9 Qc"

 .It Sy String Ta Sy Meaning

 .It Ql \[rs]\[rs] Ta Produces a backslash

 .It Ql \[rs]" Ta Produces a double quote without terminating

@@ -287,7 +277,6 @@

 .Pp

 The following functions operate on string expressions.

 Most of them return a string, however some of these functions actually return an integer and can be used as part of an integer expression!

-.Pp

 .Bl -column "STRSUB(str, pos, len)"

 .It Sy Name Ta Sy Operation

 .It Fn STRLEN string Ta Returns the number of characters in Ar string .

@@ -299,7 +288,6 @@

 .It Fn STRLWR str Ta Converts all characters in Ar str No to lower case and returns the new string.

 .El

 .Ss Character maps

-.Pp

 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.

 .Pp

@@ -334,9 +322,7 @@

 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.

 .Ss Other functions

-.Pp

 There are a few other functions that do various useful things:

-.Pp

 .Bl -column "DEF(label)"

 .It Sy Name Ta Sy Operation

 .It Fn BANK arg Ta Returns a bank number.

@@ -365,7 +351,6 @@

 or 0 if only RGBLINK can compute its value.

 .El

 .Sh SECTIONS

-.Pp

 Before you can start writing code, you must define a section.

 This tells the assembler what kind of information follows and, if it is code, where to put it.

 .Pp

@@ -382,7 +367,6 @@

 Possible section

 .Ar type Ns s

 are as follows:

-.Pp

 .Bl -tag

 .It Ic ROM0

 A ROM section.

@@ -568,7 +552,6 @@

 .Ed

 .El

 .Ss Section Stack

-.Pp

 .Ic POPS

 and

 .Ic PUSHS

@@ -581,7 +564,6 @@

 can then later be used to restore it.

 Useful for defining sections in included files when you don't want to override the section context at the point the file was included.

 .Ss RAM Code

-.Pp

 Sometimes you want to have some code in RAM.

 But then you can't simply put it in a RAM section, you have to store it in ROM and copy it to RAM at some point.

 .Pp

@@ -642,7 +624,6 @@

 .Ic LOAD

 blocks, nor can you change the current section within them.

 .Ss Unionized Sections

-.Pp

 When you're tight on RAM, you may want to define overlapping blocks of variables, as explained in the

 .Sx Unions

 section.

@@ -736,12 +717,11 @@

 .Ql bar.o

 last.

 .Sh SYMBOLS

-.Pp

 RGBDS supports several types of symbols:

-.Pp

 .Bl -hang

 .It Sy Label

-Numerical symbol designating a memory location. May or may not have a value known at assembly time.

+Numerical symbol designating a memory location.

+May or may not have a value known at assembly time.

 .It Sy Constant

 Numerical symbol whose value has to be known at assembly time.

 .It Sy Macro

@@ -861,7 +841,6 @@

 .Ed

 .Pp

 There are five commands in the RS group of commands:

-.Pp

 .Bl -column "RSSET constexpr"

 .It Sy Command Ta Sy Meaning

 .It Ic RSRESET Ta Equivalent to Ql RSSET 0 .

@@ -940,7 +919,6 @@

 Macros can't be exported or imported.

 .El

 .Ss Exporting and importing symbols

-.Pp

 Importing and exporting of symbols is a feature that is very useful when your project spans many source files and, for example, you need to jump to a routine defined in another file.

 .Pp

 Exporting of symbols has to be done manually, importing is done automatically if

@@ -960,7 +938,6 @@

 Note also that only exported symbols will appear in symbol and map files produced by

 .Xr rgblink 1 .

 .Ss Purging symbols

-.Pp

 .Ic PURGE

 allows you to completely remove a symbol from the symbol table as if it had never existed.

 .Em USE WITH EXTREME CAUTION!!!

@@ -979,9 +956,7 @@

 command

 .Em will not be expanded .

 .Ss Predeclared Symbols

-.Pp

 The following symbols are defined by the assembler:

-.Pp

 .Bl -column -offset indent "EQUS" "__ISO_8601_LOCAL__"

 .It Sy Type Ta Sy Name Ta Sy Contents

 .It Ic EQU Ta Dv @ Ta PC value (essentially, the current memory address)

@@ -1006,7 +981,6 @@

 .El

 .Sh DEFINING DATA

 .Ss Declaring variables in a RAM section

-.Pp

 .Ic DS

 allocates a number of empty bytes.

 This is the preferred method of allocating space in a RAM section.

@@ -1027,7 +1001,6 @@

 command-line option, except when using overlays with

 .Fl O .

 .Ss Defining constant data

-.Pp

 .Ic DB

 defines a list of bytes that will be stored in the final image.

 Ideal for tables and text.

@@ -1079,7 +1052,6 @@

 .Ic SRAM

 section.

 .Ss Including binary files

-.Pp

 You probably have some graphics, level data, etc. you'd like to include.

 Use

 .Ic INCBIN

@@ -1101,9 +1073,9 @@

 INCBIN "data.bin",78,256

 .Ed

 .Pp

-The length argument is optional. If only the start position is specified, the bytes from the start position until the end of the file will be included.

+The length argument is optional.

+If only the start position is specified, the bytes from the start position until the end of the file will be included.

 .Ss Unions

-.Pp

 Unions allow multiple memory allocations to overlap, like unions in C.

 This does not increase the amount of memory available, but allows re-using the same memory region for different purposes.

 .Pp

@@ -1155,7 +1127,6 @@

 .Sx Declaring variables in a RAM section ) .

 .Sh THE MACRO LANGUAGE

 .Ss Invoking macros

-.Pp

 You execute the macro by inserting its name.

 .Bd -literal -offset indent

          add a,b

@@ -1217,7 +1188,6 @@

 .Sy EQUS

 which references the same macro, which has the same problem.

 .Pp

-.Pp

 It's possible to pass arguments to macros as well!

 You retrieve the arguments by using the escape sequences

 .Ic \[rs]1

@@ -1306,7 +1276,6 @@

 .Ic SHIFT

 can optionally be given an integer parameter, and will apply the above shifting that number of times.

 .Ss Printing things during assembly

-.Pp

 The next four commands print text and values to the standard output.

 Useful for debugging macros, or wherever you may feel the need to tell yourself some important information.

 .Bd -literal -offset indent

@@ -1315,7 +1284,6 @@

 PRINTV $FF00 + $F0

 PRINTF MUL(3.14, 3987.0)

 .Ed

-.Pp

 .Bl -inset

 .It Ic PRINTT

 prints out a string.

@@ -1334,7 +1302,6 @@

 Be careful that none of those automatically print a line feed; if you need one, use

 .Ic PRINTT "\[rs]n" .

 .Ss Automatically repeating blocks of code

-.Pp

 Suppose you want to unroll a time consuming loop without copy-pasting it.

 .Ic REPT

 is here for that purpose.

@@ -1371,7 +1338,6 @@

 .Ic REPT

 blocks can be nested.

 .Ss Aborting the assembly process

-.Pp

 .Ic FAIL

 and

 .Ic WARN

@@ -1392,7 +1358,6 @@

 and

 .Ic STATIC_ASSERT .

 Syntax examples are given below:

-.Pp

 .Bd -literal -offset indent

 Function:

       xor a

@@ -1443,7 +1408,6 @@

 .Ic FATAL

 immediately aborts.

 .Ss Including other source files

-.Pp

 Use

 .Ic INCLUDE

 to process another assembler file and then return to the current file when done.

@@ -1459,7 +1423,6 @@

     INCLUDE "irq.inc"

 .Ed

 .Ss Conditional assembling

-.Pp

 The four commands

 .Ic IF , ELIF , ELSE ,

 and

@@ -1509,7 +1472,6 @@

 block, all of them but the first one are ignored.

 .Sh MISCELLANEOUS

 .Ss Changing options while assembling

-.Pp

 .Ic OPT

 can be used to change some of the options during assembling from within the source, instead of defining them on the command-line.

 .Pp

@@ -1539,7 +1501,6 @@

 Useful if you want to change some options in an include file and you don't want to destroy the options set by the program that included your file.

 The stack's number of entries is limited only by the amount of memory in your machine.

 .Ss Requesting alignment

-.Pp

 While

 .Ic ALIGN

 as presented in

@@ -1567,7 +1528,6 @@

 .Xr rgbds 7 ,

 .Xr gbz80 7

 .Sh HISTORY

-.Pp

 .Nm

 was originally written by Carsten S\(/orensen as part of the ASMotor package,

 and was later packaged in RGBDS by Justin Lloyd.

--- a/src/gbz80.7

+++ b/src/gbz80.7

@@ -22,12 +22,10 @@

 .Sy A

 by default.

 The following two lines have the same effect:

-.Pp

 .Bd -literal -offset indent

 OR A,B

 OR B

 .Ed

-.Pp

 .Sh LEGEND

 List of abbreviations used in this document.

 .Bl -tag

--- a/src/gfx/rgbgfx.1

+++ b/src/gfx/rgbgfx.1

@@ -26,7 +26,7 @@

 The

 .Nm

 program converts PNG images into the Nintendo Game Boy's planar tile format.

-

+.Pp

 The resulting colors and their palette indices are determined differently depending on the input PNG file:

 .Bl -dash -width Ds

 .It

@@ -39,7 +39,7 @@

 .It

 If the image has color (or the grayscale method failed), the colors are sorted from lightest to darkest.

 .El

-

+.Pp

 The input image may not contain more colors than the selected bit depth allows.

 Transparent pixels are set to palette index 0.

 .Sh ARGUMENTS

@@ -53,7 +53,7 @@

 .Fl Fl version .

 The arguments are as follows:

 .Bl -tag -width Ds

-.It Fl a Ar attrmap, Fl Fl attr-map Ar attrmap

+.It Fl a Ar attrmap , Fl Fl attr-map Ar attrmap

 Generate a file of tile mirroring attributes for OAM or (CGB-only) background tiles.

 For each tile in the input file, a byte is written representing the dimensions that the associated tile in the output file should be mirrored.

 Useful in combination with

--- a/src/link/rgblink.1

+++ b/src/link/rgblink.1

@@ -66,7 +66,7 @@

 Prohibit the use of sections that doesn't exist on a DMG, such as VRAM bank 1.

 This option automatically enables

 .Fl w .

-.It Fl l Ar linker_script, Fl Fl linkerscript Ar linker_script

+.It Fl l Ar linker_script , Fl Fl linkerscript Ar linker_script

 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

@@ -116,7 +116,7 @@

 .Sh EXAMPLES

 All you need for a basic ROM is an object file, which can be made into a ROM image like so:

 .Pp

-.D1 $ rgblink -o bar.gb foo.o

+.Dl $ rgblink -o bar.gb foo.o

 .Pp

 The resulting

 .Ar bar.gb

@@ -126,12 +126,10 @@

 to fix these so that the program will actually run in a Game Boy:

 .Pp

 .Dl $ rgbfix -v bar.gb

-.Ed

 .Pp

 Here is a more complete example:

 .Pp

 .Dl $ rgblink -o bin/game.gb -n bin/game.sym -p 0xFF obj/title.o obj/engine.o

-.Ed

 .Sh BUGS

 Please report bugs on

 .Lk https://github.com/gbdev/rgbds/issues GitHub .

--- a/src/link/rgblink.5

+++ b/src/link/rgblink.5

@@ -19,7 +19,6 @@

 Any line can contain a comment starting with

 .Ql \&;

 that ends at the end of the line:

-.Pp

 .Bd -literal -offset indent

 ROMX $F ; This is a comment

   "Functions to read array"

@@ -86,6 +85,6 @@

 .Sh HISTORY

 .Nm

 was originally written by Carsten S\(/orensen as part of the ASMotor package,

-and was later packaged in RGBDS by Justin Lloyd. It is now maintained by a

-number of contributors at

+and was later packaged in RGBDS by Justin Lloyd.

+It is now maintained by a number of contributors at

 .Lk https://github.com/gbdev/rgbds .

--- a/src/rgbds.5

+++ b/src/rgbds.5

@@ -18,7 +18,6 @@

 .Xr rgblink 1 .

 .Em Please note that the specifications may change .

 This toolchain is in development and new features may require adding more information to the current format, or modifying some fields, which would break compatibility with older versions.

-.Pp

 .Sh FILE STRUCTURE

 The following types are used:

 .Pp

@@ -29,7 +28,6 @@

 .Ar STRING

 is a 0‐terminated string of

 .Ar BYTE .

-.Pp

 .Bd -literal

 ; Header

@@ -219,8 +217,7 @@

 In the RGB format, RPN expressions are stored as

 .Ar BYTE Ns s

 with some bytes being special prefixes for integers and symbols.

-.Pp

-.Bl -column -offset indent ".Sy String" ".Sy String"

+.Bl -column -offset indent "Sy String" "Sy String"

 .It Sy Value Ta Sy Meaning

 .It Li $00 Ta Li + operator

 .It Li $01 Ta Li - operator

@@ -259,7 +256,6 @@

 .It Li $81 Ta Ar LONG

 symbol ID follows.

 .El

-.Pp

 .Sh SEE ALSO

 .Xr rgbasm 1 ,

 .Xr rgblink 1 ,

--- a/src/rgbds.7

+++ b/src/rgbds.7

@@ -13,7 +13,6 @@

 .Nd Rednex Game Boy Development System

 .Sh EXAMPLES

 To get a working ROM image from a single assembly source file:

-.Pp

 .Bd -literal -offset indent

 $ rgbasm \-o bar.o foo.asm

 $ rgblink \-o baz.gb bar.o

@@ -26,7 +25,7 @@

 .Xr rgbds 5 ,

 .Xr gbz80 7

 .Sh HISTORY

-.Bl -ohang

+.Bl -item

 .It

 1997, Carsten S\(/orensen (AKA SurfSmurf) writes ASMotor as a general-purpose

 assembler/linker system for DOS/Win32.

@@ -37,8 +36,8 @@

 2009, Vegard Nossum adapts the code to be more UNIX-like and releases this

 version as rgbds-linux on GitHub.

 .It

-2010, Anthony J. Bentley forks that repository. The fork becomes the reference

-implementation of rgbds.

+2010, Anthony J. Bentley forks that repository.

+The fork becomes the reference implementation of rgbds.

 .It

 2017, Bentley's repository is moved to a neutral name.

 It is now maintained by a number of contributors at