Fix CI

Examples: (...s are optional)

ld [b @:...] = "Dockerfile"
ld [b @:...] = "Dockerfile"[451:...]
ld [b @:...] = "Dockerfile"[23:5]
ld [b @:5] = "Dockerfile"[23:...]

.github.bak/actions/get-pages.sh

@@ -53,8 +53,8 @@ PAGES=(
 WWWPATH="/docs"
 mkdir -p "$1/_documentation/$2"
 
-# `mandoc` uses a different format for referring to man pages present in the **current** directory
+# `mandoc` uses a different format for referring to man pages present in the **current** directory.
-# We want that format for RGBDS man pages, and the other one for the t=rest;
+# We want that format for RGBDS man pages, and the other one for the rest;
 # we thus need to copy all pages to a temporary directory, and process them there.
 
 # Copy all pages to current dir
@@ -77,6 +77,7 @@ EOF
 		options+=,toc
 	fi
 	mandoc -Thtml -I os=Linux -O$options "${PAGES[$page]##*/}" | .github/actions/doc_postproc.awk >> "$1/_documentation/$2/$page"
+	groff -Tpdf -mdoc -wall "${PAGES[$page]##*/}" >"$1/_documentation/$2/$stem.pdf"
 	if [ $is_release -ne 0 ]; then
 		cat - >"$1/_documentation/$page" <<EOF
 ---
@@ -88,6 +89,7 @@ description: RGBDS latest stable — $descr
 EOF
 	fi
 done
+
 cat - >"$1/_documentation/$2/index.html" <<EOF
 ---
 layout: doc_index
@@ -97,6 +99,7 @@ description: RGBDS $2 - Online manual
 ---
 EOF
 
+
 # If making a release, add a new entry right after `master`
 if [ $is_release -ne 0 ]; then
 	awk '{ print }
@@ -105,5 +108,6 @@ if [ $is_release -ne 0 ]; then
 	mv "$1/_data/doc.json"{.tmp,}
 fi
 
+
 # Clean up
 rm "${PAGES[@]##*/}"

.github.bak/workflows/create-release-docs.yml

@@ -18,10 +18,10 @@ jobs:
           repository: ${{ github.repository_owner }}/rgbds-www
           path: rgbds-www
       # `-O toc` was added in 1.14.5, but the repos only have 1.14.4
-      - name: Build and install mandoc
+      - name: Build and install mandoc + install groff
         run: |
           sudo apt-get -qq update
-          sudo apt-get install -yq zlib1g-dev
+          sudo apt-get install -yq groff zlib1g-dev
           wget 'http://mandoc.bsd.lv/snapshots/mandoc-1.14.5.tar.gz'
           tar xf mandoc-1.14.5.tar.gz
           cd mandoc-1.14.5

.github.bak/workflows/update-master-docs.yml

@@ -31,10 +31,10 @@ jobs:
           repository: gbdev/rgbds-www
           ref: master
           path: rgbds-www
-      - name: Build and install mandoc
+      - name: Build and install mandoc + install groff
         run: |
           sudo apt-get -qq update
-          sudo apt-get install -yq zlib1g-dev
+          sudo apt-get install -yq groff zlib1g-dev
           wget 'http://mandoc.bsd.lv/snapshots/mandoc-1.14.5.tar.gz'
           tar xf mandoc-1.14.5.tar.gz
           cd mandoc-1.14.5
@@ -44,7 +44,7 @@ jobs:
       - name: Update pages
         working-directory: rgbds
         run: |
-          ./.github/actions/get-pages.sh ../rgbds-www/_documentation master
+          ./.github/actions/get-pages.sh ../rgbds-www master
       - name: Push new pages
         working-directory: rgbds-www
         run: |

include/asm/symbol.h

@@ -75,7 +75,7 @@ static inline bool sym_IsConstant(struct Symbol const *sym)
 	if (sym->type == SYM_LABEL) {
 		struct Section const *sect = sym_GetSection(sym);
 
-		return sect && sect->org != -1;
+		return sect && sect->org != (uint32_t)-1;
 	}
 	return sym->type == SYM_EQU || sym->type == SYM_SET;
 }

include/link/section.h

@@ -30,11 +30,11 @@ struct AttachedSymbol {
 struct Patch {
 	struct FileStackNode const *src;
 	uint32_t lineNo;
-	int32_t offset;
+	uint32_t offset;
 	uint32_t pcSectionID;
 	uint32_t pcOffset;
 	enum PatchType type;
-	int32_t rpnSize;
+	uint32_t rpnSize;
 	uint8_t *rpnExpression;
 
 	struct Section const *pcSection;

include/version.h

@@ -1,7 +1,7 @@
 /*
  * This file is part of RGBDS.
  *
- * Copyright (c) 2017-2018, Antonio Nino Diaz and RGBDS contributors.
+ * Copyright (c) 2017-2021, Antonio Nino Diaz and RGBDS contributors.
  *
  * SPDX-License-Identifier: MIT
  */
@@ -12,7 +12,7 @@
 #define PACKAGE_VERSION_MAJOR 0
 #define PACKAGE_VERSION_MINOR 5
 #define PACKAGE_VERSION_PATCH 0
-#define PACKAGE_VERSION_RC 1
+#define PACKAGE_VERSION_RC 2
 
 const char *get_package_version_string(void);
 

src/asm/fstack.c

@@ -175,8 +175,14 @@ bool fstk_FindFile(char const *path, char **fullPath, size_t *size)
 			char const *incPath = i ? includePaths[i - 1] : "";
 			int len = snprintf(*fullPath, *size, "%s%s", incPath, path);
 
+			if (len < 0) {
+				error("snprintf error during include path search: %s\n",
+				      strerror(errno));
+				break;
+			}
+
 			/* Oh how I wish `asnprintf` was standard... */
-			if (len >= *size) { /* `len` doesn't include the terminator, `size` does */
+			if ((size_t)len >= *size) { /* `len` doesn't include the terminator, `size` does */
 				*size = len + 1;
 				*fullPath = realloc(*fullPath, *size);
 				if (!*fullPath) {
@@ -187,10 +193,7 @@ bool fstk_FindFile(char const *path, char **fullPath, size_t *size)
 				len = sprintf(*fullPath, "%s%s", incPath, path);
 			}
 
-			if (len < 0) {
+			if (isPathValid(*fullPath)) {
-				error("snprintf error during include path search: %s\n",
-				      strerror(errno));
-			} else if (isPathValid(*fullPath)) {
 				printDep(*fullPath);
 				return true;
 			}
@@ -314,10 +317,14 @@ void fstk_RunInclude(char const *path)
 
 	if (!fstk_FindFile(path, &fullPath, &size)) {
 		free(fullPath);
-		if (oGeneratedMissingIncludes)
+		if (oGeneratedMissingIncludes) {
+			if (verbose)
+				printf("Aborting (-MG) on INCLUDE file '%s' (%s)\n",
+				       path, strerror(errno));
 			oFailedOnMissingInclude = true;
-		else
+		} else {
 			error("Unable to open included file '%s': %s\n", path, strerror(errno));
+		}
 		return;
 	}
 	dbgPrint("Full path: \"%s\"\n", fullPath);
@@ -532,6 +539,7 @@ void fstk_Init(char const *mainPath, size_t maxRecursionDepth)
 	context->fileInfo = (struct FileStackNode *)fileInfo;
 	/* lineNo and reptIter are unused on the top-level context */
 	context->fileInfo->parent = NULL;
+	context->fileInfo->lineNo = 0; // This still gets written to the object file, so init it
 	context->fileInfo->referenced = false;
 	context->fileInfo->type = NODE_FILE;
 	memcpy(fileInfo->name, fileName, len + 1);

src/asm/lexer.c

@@ -163,16 +163,20 @@ static struct KeywordMapping {
 	{"DE", T_MODE_DE},
 	{"HL", T_MODE_HL},
 	{"SP", T_MODE_SP},
+	{"PC", T_MODE_PC},
 	{"HLD", T_MODE_HL_DEC},
 	{"HLI", T_MODE_HL_INC},
+	{"IME", T_MODE_IME},
 
 	{"A", T_TOKEN_A},
+	{"F", T_TOKEN_F},
 	{"B", T_TOKEN_B},
 	{"C", T_TOKEN_C},
 	{"D", T_TOKEN_D},
 	{"E", T_TOKEN_E},
 	{"H", T_TOKEN_H},
 	{"L", T_TOKEN_L},
+	{"W", T_TOKEN_W},
 
 	{"DEF", T_OP_DEF},
 
@@ -275,10 +279,10 @@ static struct KeywordMapping {
 	{"RW", T_POP_RW},
 	/* Handled before as T_Z80_RL */
 	/* {"RL", T_POP_RL}, */
+
 	{"EQU", T_POP_EQU},
 	{"EQUS", T_POP_EQUS},
 	{"REDEF", T_POP_REDEF},
-
 	/* Handled before as T_Z80_SET */
 	/* {"SET", T_POP_SET}, */
 
@@ -290,6 +294,7 @@ static struct KeywordMapping {
 	{"OPT", T_POP_OPT},
 
 	{".", T_PERIOD},
+	{"...", T_ELLIPSIS},
 };
 
 static bool isWhitespace(int c)
@@ -350,6 +355,7 @@ struct LexerState {
 	uint32_t lineNo;
 	uint32_t colNo;
 	int lastToken;
+	int nextToken;
 
 	struct IfStack *ifStack;
 
@@ -374,6 +380,7 @@ static void initState(struct LexerState *state)
 	state->mode = LEXER_NORMAL;
 	state->atLineStart = true; /* yylex() will init colNo due to this */
 	state->lastToken = T_EOF;
+	state->nextToken = 0;
 
 	state->ifStack = NULL;
 
@@ -504,9 +511,15 @@ struct LexerState *lexer_OpenFile(char const *path)
 	}
 	if (!state->isMmapped) {
 		/* Sometimes mmap() fails or isn't available, so have a fallback */
-		if (verbose)
+		if (verbose) {
+			if (isStdin)
+				printf("Opening stdin\n");
+			else if (fileInfo.st_size == 0)
+				printf("File %s is empty\n", path);
+			else
 				printf("File %s opened as regular, errno reports \"%s\"\n",
 				       path, strerror(errno));
+		}
 		state->index = 0;
 		state->nbChars = 0;
 	}
@@ -580,7 +593,7 @@ struct KeywordDictNode {
 	uint16_t children[0x60 - ' '];
 	struct KeywordMapping const *keyword;
 /* Since the keyword structure is invariant, the min number of nodes is known at compile time */
-} keywordDict[351] = {0}; /* Make sure to keep this correct when adding keywords! */
+} keywordDict[356] = {0}; /* Make sure to keep this correct when adding keywords! */
 
 /* Convert a char into its index into the dict */
 static inline uint8_t dictIndex(char c)
@@ -866,8 +879,9 @@ static int peekInternal(uint8_t distance)
 			size_t nbExpectedChars = LEXER_BUF_SIZE - writeIndex;
 
 			readChars(nbExpectedChars);
-			/* If the read was incomplete, don't perform a second read */
+			// If the read was incomplete, don't perform a second read
-			if (nbCharsRead < nbExpectedChars)
+			// `nbCharsRead` cannot be negative, so it's fine to cast to `size_t`
+			if ((size_t)nbCharsRead < nbExpectedChars)
 				target = 0;
 		}
 		if (target != 0)
@@ -1849,10 +1863,20 @@ static char const *reportGarbageChar(unsigned char firstByte)
 
 /* Lexer core */
 
+static int yylex_SKIP_TO_ENDC(void); // forward declaration for yylex_NORMAL
+
 static int yylex_NORMAL(void)
 {
 	dbgPrint("Lexing in normal mode, line=%" PRIu32 ", col=%" PRIu32 "\n",
 		 lexer_GetLineNo(), lexer_GetColNo());
+
+	if (lexerState->nextToken) {
+		int token = lexerState->nextToken;
+
+		lexerState->nextToken = 0;
+		return token;
+	}
+
 	for (;;) {
 		int c = nextChar();
 		char secondChar;
@@ -1881,7 +1905,7 @@ static int yylex_NORMAL(void)
 		case '@':
 			yylval.tzSym[0] = '@';
 			yylval.tzSym[1] = '\0';
-			return T_ID;
+			return T_TOKEN_AT;
 
 		case '[':
 			return T_LBRACK;
@@ -1894,6 +1918,11 @@ static int yylex_NORMAL(void)
 		case ',':
 			return T_COMMA;
 
+		case '\'':
+			return T_PRIME;
+		case '?':
+			return T_QUESTION;
+
 		/* Handle ambiguous 1- or 2-char tokens */
 
 		case '*': /* Either MUL or EXP */
@@ -1944,6 +1973,10 @@ static int yylex_NORMAL(void)
 				return T_OP_LOGICGE;
 			case '>':
 				shiftChars(1);
+				if (peek(0) == '>') {
+					shiftChars(1);
+					return T_OP_SHRL;
+				}
 				return T_OP_SHR;
 			default:
 				return T_OP_LOGICGT;
@@ -1971,25 +2004,6 @@ static int yylex_NORMAL(void)
 		case '$':
 			yylval.nConstValue = 0;
 			readHexNumber();
-			/* Attempt to match `$ff00+c` */
-			if (yylval.nConstValue == 0xff00) {
-				/* Whitespace is ignored anyways */
-				while (isWhitespace(c = peek(0)))
-					shiftChars(1);
-				if (c == '+') {
-					/* FIXME: not great due to large lookahead */
-					uint8_t distance = 1;
-
-					do {
-						c = peek(distance++);
-					} while (isWhitespace(c));
-
-					if (c == 'c' || c == 'C') {
-						shiftChars(distance);
-						return T_MODE_HW_C;
-					}
-				}
-			}
 			return T_NUMBER;
 
 		case '0': /* Decimal number */
@@ -2050,34 +2064,101 @@ static int yylex_NORMAL(void)
 		case EOF:
 			return T_EOF;
 
-		/* Handle escapes */
+		/* Handle line continuations */
 
 		case '\\':
-			c = peek(0);
+			// Macro args were handled by `peek`, and character escapes do not exist
-
+			// outside of string literals, so this must be a line continuation.
-			switch (c) {
-			case ' ':
-			case '\r':
-			case '\n':
 			readLineContinuation();
 			break;
 
-			case EOF:
+		/* Handle 8-bit registers followed by a period */
-				error("Illegal character escape at end of input\n");
-				break;
 
-			default:
+		case 'A':
+		case 'a':
+			if (peek(0) == '.') {
 				shiftChars(1);
-				error("Illegal character escape '%s'\n", print(c));
+				lexerState->nextToken = T_PERIOD;
+				return T_TOKEN_A;
 			}
-			break;
+			goto normal_identifier;
 
-		/* Handle identifiers and escapes... or error out */
+		case 'F':
+		case 'f':
+			if (peek(0) == '.') {
+				shiftChars(1);
+				lexerState->nextToken = T_PERIOD;
+				return T_TOKEN_F;
+			}
+			goto normal_identifier;
 
+		case 'B':
+		case 'b':
+			if (peek(0) == '.') {
+				shiftChars(1);
+				lexerState->nextToken = T_PERIOD;
+				return T_TOKEN_B;
+			}
+			goto normal_identifier;
+
+		case 'C':
+		case 'c':
+			if (peek(0) == '.') {
+				shiftChars(1);
+				lexerState->nextToken = T_PERIOD;
+				return T_TOKEN_C;
+			}
+			goto normal_identifier;
+
+		case 'D':
+		case 'd':
+			if (peek(0) == '.') {
+				shiftChars(1);
+				lexerState->nextToken = T_PERIOD;
+				return T_TOKEN_D;
+			}
+			goto normal_identifier;
+
+		case 'E':
+		case 'e':
+			if (peek(0) == '.') {
+				shiftChars(1);
+				lexerState->nextToken = T_PERIOD;
+				return T_TOKEN_E;
+			}
+			goto normal_identifier;
+
+		case 'H':
+		case 'h':
+			if (peek(0) == '.') {
+				shiftChars(1);
+				lexerState->nextToken = T_PERIOD;
+				return T_TOKEN_H;
+			}
+			goto normal_identifier;
+
+		case 'L':
+		case 'l':
+			if (peek(0) == '.') {
+				shiftChars(1);
+				lexerState->nextToken = T_PERIOD;
+				return T_TOKEN_L;
+			}
+			/* fallthrough */
+
+		/* Handle identifiers... or report garbage characters */
+
+normal_identifier:
 		default:
 			if (startsIdentifier(c)) {
 				int tokenType = readIdentifier(c);
 
+				/* An ELIF after a taken IF needs to not evaluate its condition */
+				if (tokenType == T_POP_ELIF && lexerState->lastToken == T_NEWLINE
+				 && lexer_GetIFDepth() > 0 && lexer_RanIFBlock()
+				 && !lexer_ReachedELSEBlock())
+					return yylex_SKIP_TO_ENDC();
+
 				/* If a keyword, don't try to expand */
 				if (tokenType != T_ID && tokenType != T_LOCAL_ID)
 					return tokenType;
@@ -2258,7 +2339,7 @@ static int skipIfBlock(bool toEndc)
 {
 	dbgPrint("Skipping IF block (toEndc = %s)\n", toEndc ? "true" : "false");
 	lexer_SetMode(LEXER_NORMAL);
-	int startingDepth = lexer_GetIFDepth();
+	uint32_t startingDepth = lexer_GetIFDepth();
 	int token;
 	bool atLineStart = lexerState->atLineStart;
 

src/asm/macro.c

@@ -170,12 +170,12 @@ void macro_ShiftCurrentArgs(int32_t count)
 {
 	if (!macroArgs) {
 		error("Cannot shift macro arguments outside of a macro\n");
-	} else if (count > 0 && (count > macroArgs->nbArgs
+	} else if (count > 0 && ((uint32_t)count > macroArgs->nbArgs
 		   || macroArgs->shift > macroArgs->nbArgs - count)) {
 		warning(WARNING_MACRO_SHIFT,
 			"Cannot shift macro arguments past their end\n");
 		macroArgs->shift = macroArgs->nbArgs;
-	} else if (count < 0 && macroArgs->shift < -count) {
+	} else if (count < 0 && macroArgs->shift < (uint32_t)-count) {
 		warning(WARNING_MACRO_SHIFT,
 			"Cannot shift macro arguments past their beginning\n");
 		macroArgs->shift = 0;

src/asm/main.c

@@ -353,7 +353,8 @@ int main(int argc, char *argv[])
 	sect_CheckUnionClosed();
 
 	if (nbErrors != 0)
-		errx(1, "Assembly aborted (%u errors)!", nbErrors);
+		errx(1, "Assembly aborted (%u error%s)!", nbErrors,
+			nbErrors == 1 ? "" : "s");
 
 	// If parse aborted due to missing an include, and `-MG` was given, exit normally
 	if (oFailedOnMissingInclude)

src/asm/output.c

@@ -136,9 +136,9 @@ static uint32_t getNbFileStackNodes(void)
 void out_RegisterNode(struct FileStackNode *node)
 {
 	/* If node is not already registered, register it (and parents), and give it a unique ID */
-	while (node->ID == -1) {
+	while (node->ID == (uint32_t)-1) {
 		node->ID = getNbFileStackNodes();
-		if (node->ID == -1)
+		if (node->ID == (uint32_t)-1)
 			fatalerror("Reached too many file stack nodes; try splitting the file up\n");
 		node->next = fileStackNodes;
 		fileStackNodes = node;
@@ -266,7 +266,7 @@ static void registerSymbol(struct Symbol *sym)
 	*objectSymbolsTail = sym;
 	objectSymbolsTail = &sym->next;
 	out_RegisterNode(sym->src);
-	if (nbSymbols == -1)
+	if (nbSymbols == (uint32_t)-1)
 		fatalerror("Registered too many symbols (%" PRIu32
 			   "); try splitting up your files\n", (uint32_t)-1);
 	sym->ID = nbSymbols++;
@@ -278,7 +278,7 @@ static void registerSymbol(struct Symbol *sym)
  */
 static uint32_t getSymbolID(struct Symbol *sym)
 {
-	if (sym->ID == -1 && !sym_IsPC(sym))
+	if (sym->ID == (uint32_t)-1 && !sym_IsPC(sym))
 		registerSymbol(sym);
 	return sym->ID;
 }
@@ -474,7 +474,7 @@ static void registerUnregisteredSymbol(struct Symbol *symbol, void *arg)
 	(void)arg; // sym_ForEach requires a void* parameter, but we are not using it.
 
 	// Check for symbol->src, to skip any built-in symbol from rgbasm
-	if (symbol->src && symbol->ID == -1) {
+	if (symbol->src && symbol->ID == (uint32_t)-1) {
 		registerSymbol(symbol);
 	}
 }

src/asm/rgbasm.1

@@ -1,11 +1,11 @@
 .\"
 .\" This file is part of RGBDS.
 .\"
-.\" Copyright (c) 2010-2019, Anthony J. Bentley and RGBDS contributors.
+.\" Copyright (c) 2010-2021, Anthony J. Bentley and RGBDS contributors.
 .\"
 .\" SPDX-License-Identifier: MIT
 .\"
-.Dd July 8, 2019
+.Dd March 28, 2021
 .Dt RGBASM 1
 .Os
 .Sh NAME
@@ -83,7 +83,7 @@ Add an include path.
 Disable the optimization that turns loads of the form
 .Ic LD [$FF00+n8],A
 into the opcode
-.Ic LDH [$FF00+n8],A
+.Ic LD [H $FF00+n8],A
 in order to have full control of the result in the final ROM.
 .It Fl M Ar depend_file , Fl Fl dependfile Ar depend_file
 Print
@@ -244,7 +244,7 @@ Use a division by 2^N instead.
 Warn when a shift's operand is negative or greater than 32.
 .It Fl Wno-truncation
 Warn when an implicit truncation (for example,
-.Ic db )
+.Ic LD [B @] )
 loses some bits.
 .It Fl Wno-user
 Warn when the

src/asm/rgbasm.5

@@ -1,11 +1,11 @@
 .\"
 .\" This file is part of RGBDS.
 .\"
-.\" Copyright (c) 2017-2018, Antonio Nino Diaz and RGBDS contributors.
+.\" Copyright (c) 2017-2021, Antonio Nino Diaz and RGBDS contributors.
 .\"
 .\" SPDX-License-Identifier: MIT
 .\"
-.Dd December 5, 2019
+.Dd March 28, 2021
 .Dt RGBASM 5
 .Os
 .Sh NAME
@@ -25,11 +25,11 @@ Generally,
 .Dq the linker
 will refer to
 .Xr rgblink 1 ,
-but any program that processes RGB object files (described in
+but any program that processes RGBDS object files (described in
 .Xr rgbds 5 )
 can be used in its place.
 .Sh SYNTAX
-The syntax is line‐based, just as in any other assembler, meaning that you do one instruction or directive per line:
+The syntax is line-based, just as in any other assembler, meaning that you do one instruction or directive per line:
 .Pp
 .Dl Oo Ar label Oc Oo Ar instruction Oc Oo Ar ;\ comment Oc
 .Pp
@@ -38,7 +38,7 @@ Example:
 John: ld a,87 ;Weee
 .Ed
 .Pp
-All reserved keywords (directives, mnemonics, registers, etc.) are case‐insensitive;
+All reserved keywords (directives, mnemonics, registers, etc.) are case-insensitive;
 all identifiers (symbol names) are case-sensitive.
 .Pp
 Comments are used to give humans information about the code, such as explanations.
@@ -63,7 +63,7 @@ X = /* the value of x
 Sometimes lines can be too long and it may be necessary to split them.
 To do so, put a backslash at the end of the line:
 .Bd -literal -offset indent
-    DB 1, 2, 3,\ \[rs]
+    LD [B @:...], 1, 2, 3,\ \[rs]
                   4, 5, 6,\ \[rs]\ ;\ Put it before any comments
                   7, 8, 9
 .Ed
@@ -73,7 +73,7 @@ To split strings it is needed to use
 .Fn STRCAT
 like this:
 .Bd -literal -offset indent
-    db STRCAT("Hello ",\ \[rs]
+    LD [B @:], STRCAT("Hello ",\ \[rs]
                       "world!")
 .Ed
 .Sh EXPRESSIONS
@@ -177,8 +177,8 @@ and
 .Pp
 .Ic \&!
 returns 1 if the operand was 0, and 0 otherwise.
-.Ss Fixed‐point Expressions
+.Ss Fixed-point Expressions
-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.
+Fixed-point numbers are basically normal (32-bit) integers, which count 65536ths 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
 .Sq +
@@ -226,7 +226,7 @@ For example:
 ; (shifted and scaled from the range [-1.0, 1.0])
 ANGLE = 0.0
     REPT 256
-        db (MUL(64.0, SIN(ANGLE)) + 64.0) >> 16
+        ld [b @], (MUL(64.0, SIN(ANGLE)) + 64.0) >> 16
 ANGLE = ANGLE + 256.0 ; 256.0 = 65536 degrees / 256 entries
     ENDR
 .Ed
@@ -266,21 +266,37 @@ A funky feature is
 .Ql {symbol}
 within a string, called
 .Dq symbol interpolation .
-This will paste
+This will paste the contents of
-.Ar symbol Ap s
+.Ql symbol
-contents as a string.
+as if they were part of the source file.
-If it's a string symbol, the string is simply inserted.
+If it's a string symbol, its characters are simply inserted.
-If it's a numeric symbol, its value is converted to hexadecimal notation with a dollar sign
+If it's a numerical symbol, its value is converted to hexadecimal notation with a dollar sign
 .Sq $
 prepended.
-.Bd -literal -offset indent
+.Pp
-TOPIC equs "life, the universe, and \[rs]"everything\[rs]""
+Symbols can be
-ANSWER = 42
+.Em interpolated
-;\ Prints "The answer to life, the universe, and "everything" is $2A"
+even in the contexts that disable
-PRINTLN "The answer to {TOPIC} is {ANSWER}"
+.Em expansion
-.Ed
+of string equates:
+.Ql DEF({name}) ,
+.Ql DEF {name} EQU/SET/EQUS/etc ... ,
+.Ql PURGE {name} ,
+and
+.Ql MACRO {name}
+will all interpolate the contents of
+.Ql {name} .
 .Pp
 Symbol interpolations can be nested, too!
+.Bd -literal -offset indent
+DEF topic EQUS "life, the universe, and \[rs]"everything\[rs]""
+DEF meaning EQUS "answer"
+;\ Defines answer = 42
+DEF {meaning} = 42
+;\ Prints "The answer to life, the universe, and "everything" is 42"
+PRINTLN "The {meaning} to {topic} is {d:{meaning}}"
+PURGE topic, meaning, {meaning}
+.Ed
 .Pp
 It's possible to change the way symbols are converted by specifying a print format like so:
 .Ql {fmt:symbol} .
@@ -355,14 +371,14 @@ HINT: The
 construct can also be used outside strings.
 The symbol's value is again inserted directly.
 .Bd -literal -offset indent
-NAME equs "ITEM"
+def NAME equs "ITEM"
-FMT equs "d"
+def FMT equs "d"
-ZERO_NUM equ 0
+def ZERO_NUM equ 0
-ZERO_STR equs "0"
+def ZERO_STR equs "0"
 ;\ Defines INDEX as 100
 INDEX = 1{ZERO_STR}{{FMT}:ZERO_NUM}
 ;\ Defines ITEM_100 as "\[rs]"hundredth\[rs]""
-{NAME}_{d:INDEX} equs "\[rs]"hundredth\[rs]""
+def {NAME}_{d:INDEX} equs "\[rs]"hundredth\[rs]""
 ;\ Prints "ITEM_100 is hundredth"
 PRINTLN STRCAT("{NAME}_{d:INDEX} is ", {NAME}_{d:INDEX})
 ;\ Purges ITEM_100
@@ -401,9 +417,9 @@ CHARMAP "&iacute", 20
 CHARMAP "A", 128
 .Ed
 This would result in
-.Ql db \(dqAmen<LF>\(dq
+.Ql ld [b @:...], \(dqAmen<LF>\(dq
 being equivalent to
-.Ql db 128, 109, 101, 110, 10 .
+.Ql ld [b @:...], 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
@@ -446,7 +462,7 @@ is able to compute it.
 .It Fn DEF symbol Ta Returns TRUE (1) if
 .Ar symbol
 has been defined, FALSE (0) otherwise.
-String symbols are not expanded within the parentheses.
+String equates are not expanded within the parentheses.
 .It Fn HIGH arg Ta Returns the top 8 bits of the operand if Ar arg No is a label or constant, or the top 8-bit register if it is a 16-bit register.
 .It Fn LOW arg Ta Returns the bottom 8 bits of the operand if Ar arg No is a label or constant, or the bottom 8-bit register if it is a 16-bit register Pq Cm AF No isn't a valid register for this function .
 .It Fn ISCONST arg Ta Returns 1 if Ar arg Ap s value is known by RGBASM (e.g. if it can be an argument to
@@ -558,15 +574,15 @@ While
 will automatically optimize
 .Ic ld
 instructions to the smaller and faster
-.Ic ldh
+.Ic ld\ h
 (see
 .Xr gbz80 7 )
 whenever possible, it is generally unable to do so when a label is involved.
 Using the
-.Ic ldh
+.Ic ld\ h
 instruction directly is recommended.
 This forces the assembler to emit a
-.Ic ldh
+.Ic ld\ h
 instruction and the linker to check if the value is in the correct range.
 .El
 .Pp
@@ -590,7 +606,7 @@ depending on
 .It Ic ALIGN Ns Bq Ar align , offset
 Place the section at an address whose
 .Ar align
-least‐significant bits are equal to
+least-significant bits are equal to
 .Ar offset .
 (Note that
 .Ic ALIGN Ns Bq Ar align
@@ -683,11 +699,11 @@ CopyCode:
     ld c, RAMLocation.end - RAMLocation
 \&.loop
     ld a, [de]
-    inc de
+    ld de+
     ld [hli], a
-    dec c
+    ld c-
-    jr nz, .loop
+    ld nz pc, b .loop
-    ret
+    ld pc,[sp++]
 
 RAMCode:
   LOAD "RAM code", WRAM0
@@ -697,13 +713,13 @@ RAMLocation:
 \&.copy
     ld a, [hli]
     ld [de], a
-    inc de
+    ld de+
-    and a
+    ld a,a&a
-    jr nz, .copy
+    ld nz pc, b .copy
-    ret
+    ld pc,[sp++]
 
 \&.string
-    db "Hello World!", 0
+    ld [b @:...], "Hello World!", 0
 \&.end
   ENDL
 .Ed
@@ -853,16 +869,7 @@ Periods
 .Sq \&.
 are allowed exclusively in labels, as described below.
 A symbol cannot have the same name as a reserved keyword.
-.Pp
+.Ss Label declaration
-Constants and string equates
-.Em must not
-have any whitespace before their name when they are defined;
-otherwise
-.Nm
-will treat them as a macro invocation.
-Label and macro definitions may have whitespace before them, since a leading period or a following colon distinguishes them from invoking a macro.
-.Bl -tag -width indent
-.It Sy Label declaration
 One of the assembler's main tasks is to keep track of addresses for you, so you can work with meaningful names instead of "magic" numbers.
 .Pp
 This can be done in a number of ways:
@@ -922,14 +929,14 @@ references the one before the expression;
 and so on.
 .Bd -literal -offset indent
     ld hl, :++
-:   ld a, [hli] ; referenced by "jr nz"
+:   ld a, [hli] ; referenced by "ld nz pc"
-    ldh [c], a
+    ld [h c], a
-    dec c
+    ld c-
-    jr nz, :-
+    ld nz pc,b  :-
-    ret
+    ld pc,[sp++]
 
 :   ; referenced by "ld hl"
-    dw $7FFF, $1061, $03E0, $58A5
+    ld [w @:], $7FFF, $1061, $03E0, $58A5
 .Ed
 .Pp
 A label's location (and thus value) is usually not determined until the linking stage, so labels usually cannot be used as constants.
@@ -937,56 +944,57 @@ However, if the section in which the label is declared has a fixed base address,
 .Pp
 .Nm
 is able to compute the subtraction of two labels either if both are constant as described above, or if both belong to the same section.
-.It Ic EQU
+.Ss Immutable constants
 .Ic EQU
-allows defining constant symbols.
+is used to define numerical constant symbols.
 Unlike
 .Ic SET
 below, constants defined this way cannot be redefined.
 They can, for example, be used for things such as bit definitions of hardware registers.
 .Bd -literal -offset indent
-SCREEN_WIDTH   equ 160 ;\ In pixels
+def SCREEN_WIDTH  equ 160 ;\ In pixels
-SCREEN_HEIGHT  equ 144
+def SCREEN_HEIGHT equ 144
 .Ed
 .Pp
 Note that colons
 .Ql \&:
 following the name are not allowed.
-.It Ic SET
+.Ss Mutable constants
 .Ic SET ,
 or its synonym
 .Ic = ,
-defines constant symbols like
+is used to define numerical symbols like
 .Ic EQU ,
-but those constants can be redefined.
+but these symbols can be redefined.
 This is useful for variables in macros, for counters, etc.
 .Bd -literal -offset indent
-ARRAY_SIZE EQU 4
+DEF ARRAY_SIZE EQU 4
-COUNT      SET 2
+DEF   COUNT SET 2
-COUNT      SET ARRAY_SIZE+COUNT
+DEF   COUNT SET 3
-;\ COUNT now has the value 6
+REDEF COUNT SET ARRAY_SIZE+COUNT
-COUNT      = COUNT + 1
+COUNT = COUNT*2
+;\ COUNT now has the value 14
 .Ed
 .Pp
 Note that colons
 .Ql \&:
 following the name are not allowed.
-.It Ic RSSET , RSRESET , RB , RW
+.Ss Offset constants
-The RS group of commands is a handy way of defining structures:
+The RS group of commands is a handy way of defining structure offsets:
 .Bd -literal -offset indent
                RSRESET
-str_pStuff    RW   1
+DEF str_pStuff RW   1
-str_tData     RB   256
+DEF str_tData  RB   256
-str_bCount    RB   1
+DEF str_bCount RB   1
-str_SIZEOF    RB   0
+DEF str_SIZEOF RB   0
 .Ed
 .Pp
 The example defines four constants as if by:
 .Bd -literal -offset indent
-str_pStuff EQU 0
+DEF str_pStuff EQU 0
-str_tData  EQU 2
+DEF str_tData  EQU 2
-str_bCount EQU 258
+DEF str_bCount EQU 258
-str_SIZEOF EQU 259
+DEF str_SIZEOF EQU 259
 .Ed
 .Pp
 There are five commands in the RS group of commands:
@@ -1008,29 +1016,38 @@ is omitted, it's assumed to be 1.
 Note that colons
 .Ql \&:
 following the name are not allowed.
-.It Ic EQUS
+.Ss String equates
 .Ic EQUS
-is used to define string symbols.
+is used to define string equate symbols.
-Wherever the assembler meets a string symbol its name is replaced with its value.
+Wherever the assembler reads a string equate, it gets
-If you are familiar with C you can think of it as similar to
+.Em expanded :
+the symbol's name is replaced with its contents.
+If you are familiar with C, you can think of it as similar to
 .Fd #define .
+This expansion is disabled in a few contexts:
+.Ql DEF(name) ,
+.Ql DEF name EQU/SET/EQUS/etc ... ,
+.Ql PURGE name ,
+and
+.Ql MACRO name
+will not expand string equates in their names.
 .Bd -literal -offset indent
-COUNTREG EQUS "[hl+]"
+DEF COUNTREG EQUS "[hl+]"
     ld a,COUNTREG
 
-PLAYER_NAME EQUS "\[rs]"John\[rs]""
+DEF PLAYER_NAME EQUS "\[rs]"John\[rs]""
-    db PLAYER_NAME
+    ld [b @:], PLAYER_NAME
 .Ed
 .Pp
 This will be interpreted as:
 .Bd -literal -offset indent
     ld a,[hl+]
-    db "John"
+    ld [b @:], "John"
 .Ed
 .Pp
-String symbols can also be used to define small one-line macros:
+String equates can also be used to define small one-line macros:
 .Bd -literal -offset indent
-pusha EQUS "push af\[rs]npush bc\[rs]npush de\[rs]npush hl\[rs]n"
+DEF ld_de_hl EQUS "ld d,h\[rs]n ld e,l\[rs]n"
 .Ed
 .Pp
 Note that colons
@@ -1047,7 +1064,7 @@ However, the
 keyword will define or redefine a string symbol.
 For example:
 .Bd -literal -offset indent
-s EQUS "Hello, "
+DEF s EQUS "Hello, "
 REDEF s EQUS "{s}world!"
 ; prints "Hello, world!"
 PRINTT "{s}\n"
@@ -1070,7 +1087,47 @@ command-line option in
 Also, a macro can contain an
 .Ic EQUS
 which calls the same macro, which causes the same problem.
-.It Ic MACRO
+.Pp
+The examples above for
+.Ql EQU ,
+.Ql SET
+or
+.Ql = ,
+.Ql RB ,
+.Ql RW ,
+.Ql RL ,
+and
+.Ql EQUS
+all start with
+.Ql DEF .
+(A
+.Ql SET
+or
+.Ql =
+definition may start with
+.Ql REDEF
+instead, since they are redefinable.)
+You may use the older syntax without
+.Ql DEF ,
+but then the name being defined
+.Em must not
+have any whitespace before it;
+otherwise
+.Nm
+will treat it as a macro invocation.
+Furthermore, without the
+.Ql DEF
+keyword,
+string equates may be expanded for the name.
+This can lead to surprising results:
+.Bd -literal -offset indent
+X EQUS "Y"
+; this defines Y, not X!
+X EQU 42
+; prints "Y $2A"
+PRINTLN "{X} {Y}"
+.Ed
+.Ss Macros
 One of the best features of an assembler is the ability to write macros for it.
 Macros can be called with arguments, and can react depending on input using
 .Ic IF
@@ -1078,13 +1135,14 @@ constructs.
 .Bd -literal -offset indent
 MACRO MyMacro
          ld a, 80
-         call MyFunc
+         ld[--sp],pc, MyFunc
 ENDM
 .Ed
 .Pp
 The example above defines
 .Ql MyMacro
 as a new macro.
+String equates are not expanded within the name of the macro.
 You may use the older syntax
 .Ql MyMacro: MACRO
 instead of
@@ -1092,6 +1150,8 @@ instead of
 with a single colon
 .Ql \&:
 following the macro's name.
+With the older syntax, string equates may be expanded for the name.
+.Pp
 Macros can't be exported or imported.
 .Pp
 Plainly nesting macro definitions is not allowed, but this can be worked around using
@@ -1108,12 +1168,11 @@ ENDM
 But this will:
 .Bd -literal -offset indent
 MACRO outer
-definition EQUS "MACRO inner\[rs]nPRINTLN \[rs]"Hello!\[rs]"\[rs]nENDM"
+DEF definition EQUS "MACRO inner\[rs]nPRINTLN \[rs]"Hello!\[rs]"\[rs]nENDM"
     definition
     PURGE definition
 ENDM
 .Ed
-.El
 .Pp
 Macro arguments support all the escape sequences of strings, as well as
 .Ql \[rs],
@@ -1149,9 +1208,9 @@ ExportedLabelB2:
 .Ql c.asm :
 .Bd -literal -compact
 SECTION "C", ROM0[0]
-	dw LabelA
+	ld [w @], LabelA
-	dw ExportedLabelB1
+	ld [w @], ExportedLabelB1
-	dw ExportedLabelB2
+	ld [w @], ExportedLabelB2
 .Ed
 .Pp
 Then
@@ -1184,15 +1243,12 @@ I can't stress this enough,
 DON'T purge a symbol that you use in expressions the linker needs to calculate.
 When not sure, it's probably not safe to purge anything other than string symbols, macros, and constants.
 .Bd -literal -offset indent
-Kamikaze EQUS  "I don't want to live anymore"
+DEF Kamikaze EQUS  "I don't want to live anymore"
-AOLer    EQUS  "Me too"
+DEF AOLer    EQUS  "Me too"
          PURGE Kamikaze, AOLer
 .Ed
 .Pp
-Note that, as an exception, string symbols in the argument list of a
+String equates are not expanded within the symbol names.
-.Ic PURGE
-command
-.Em will not be expanded .
 .Ss Predeclared Symbols
 The following symbols are defined by the assembler:
 .Bl -column -offset indent "EQUS" "__ISO_8601_LOCAL__"
@@ -1225,18 +1281,20 @@ Refer to the spec at
 .Lk https://reproducible-builds.org/docs/source-date-epoch/ .
 .Sh DEFINING DATA
 .Ss Declaring variables in a RAM section
-.Ic DS
+.Ic LD [B @:<len>]
 allocates a number of empty bytes.
 This is the preferred method of allocating space in a RAM section.
 You can also use
-.Ic DB , DW
+.Ic LD [B @] , LD [W @]
 and
-.Ic DL
+.Ic LD [L @]
-without any arguments instead (see
+with
+.Ql \&?
+instead (see
 .Sx Defining constant data
 below).
 .Bd -literal -offset indent
-DS 42 ;\ Allocates 42 bytes
+LD [B @:42], ? ;\ Allocates 42 bytes
 .Ed
 .Pp
 Empty space in RAM sections will not be initialized.
@@ -1245,17 +1303,24 @@ In ROM sections, it will be filled with the value passed to the
 command-line option, except when using overlays with
 .Fl O .
 .Ss Defining constant data
-.Ic DB
+.Ic LD [B @]
 defines a list of bytes that will be stored in the final image.
 Ideal for tables and text.
 .Bd -literal -offset indent
-DB 1,2,3,4,"This is a string"
+LD [B @:...], 1,2,3,4,"This is a string"
 .Ed
 .Pp
+Python slice syntax is used: for a single byte, close the brackets immediately after
+.Ql @ ;
+if more than one entry follows, a colon must be added after the
+.Ql @ ,
+optionally followed by an ellipsis
+.Ql ... .
+.Pp
 Alternatively, you can use
-.Ic DW
+.Ic LD [W @]
 to store a list of words (16-bit) or
-.Ic DL
+.Ic LD [L @]
 to store a list of double-words/longs (32-bit).
 .Pp
 Strings are handled a little specially: they first undergo charmap conversion (see
@@ -1263,36 +1328,42 @@ Strings are handled a little specially: they first undergo charmap conversion (s
 then each resulting character is output individually.
 For example, under the default charmap, the following two lines are identical:
 .Bd -literal -offset indent
-DW "Hello!"
+LD [W @:], "Hello!"
-DW "H", "e", "l", "l", "o", "!"
+LD [W @:], "H", "e", "l", "l", "o", "!"
 .Ed
 .Pp
+Note that strings require a colon after the
+.Ql @
+in the directive.
+.Pp
 If you do not want this special handling, enclose the string in parentheses.
 .Pp
-.Ic DS
+.Ic LD [B @:<len>]
 can also be used to fill a region of memory with some repeated values.
 For example:
 .Bd -literal -offset indent
 ; outputs 3 bytes: $AA, $AA, $AA
-DS 3, $AA
+LD [B @:3], $AA
 ; outputs 7 bytes: $BB, $CC, $BB, $CC, $BB, $CC, $BB
-DS 7, $BB, $CC
+LD [B @:7], $BB, $CC
 .Ed
 .Pp
 You can also use
-.Ic DB , DW
+.Ic LD [B @] , LD [W @]
 and
-.Ic DL
+.Ic LD [L @]
-without arguments.
+with
+.Ql \&?
+as its sole argument (in which case neither the colon nor an ellipsis may be present).
 This works exactly like
-.Ic DS 1 , DS 2
+.Ic LD [B @:1] , LD [B @:2]
 and
-.Ic DS 4
+.Ic LD [B @:4]
 respectively.
-Consequently, no-argument
+Consequently, these forms of
-.Ic DB , DW
+.Ic LD [B @] , LD [W @]
 and
-.Ic DL
+.Ic LD [L @]
 can be used in a
 .Ic WRAM0
 /
@@ -1307,23 +1378,25 @@ section.
 .Ss Including binary files
 You probably have some graphics, level data, etc. you'd like to include.
 Use
-.Ic INCBIN
+.Ic LD [B @:...] =
 to include a raw binary file as it is.
+.Pq The ellipsis are optional.
 If the file isn't found in the current directory, the include-path list passed to
 .Xr rgbasm 1
 (see the
 .Fl i
 option) on the command line will be searched.
 .Bd -literal -offset indent
-INCBIN "titlepic.bin"
+LD [B @:] = "titlepic.bin"
-INCBIN "sprites/hero.bin"
+LD [B @:...] = "sprites/hero.bin"
 .Ed
 .Pp
 You can also include only part of a file with
-.Ic INCBIN .
+.Ic LD [B @:] .
-The example below includes 256 bytes from data.bin, starting from byte 78.
+The examples below include 256 bytes from data.bin, starting from byte 78.
 .Bd -literal -offset indent
-INCBIN "data.bin",78,256
+LD [B @:] = "data.bin"[78:256]
+LD [B @:256] = "data.bin"[78:]
 .Ed
 .Pp
 The length argument is optional.
@@ -1343,19 +1416,19 @@ separates each block of allocations, and you may use it as many times within a u
     ; Let's say PC = $C0DE here
     UNION
     ; Here, PC = $C0DE
-Name: ds 8
+Name:        ld [b @:8], ?
     ; PC = $C0E6
-Nickname: ds 8
+Nickname:    ld [b @:8], ?
     ; PC = $C0EE
     NEXTU
     ; PC is back to $C0DE
-Health: dw
+Health:      ld [w @], ?
     ; PC = $C0E0
-Something: ds 6
+Something:   ld [b @:6], ?
     ; And so on
-Lives: db
+Lives:       ld [b @], ?
     NEXTU
-VideoBuffer: ds 19
+VideoBuffer: ld [b @:19], ?
     ENDU
 .Ed
 .Pp
@@ -1375,17 +1448,17 @@ The size of this union is 19 bytes, as this is the size of the largest block (th
 Nesting unions is possible, with each inner union's size being considered as described above.
 .Pp
 Unions may be used in any section, but inside them may only be
-.Ic DS -
+.Ic LD\ [B\ @],\ ? Ns - Ns
 like commands (see
 .Sx Declaring variables in a RAM section ) .
 .Sh THE MACRO LANGUAGE
 .Ss Invoking macros
 You execute the macro by inserting its name.
 .Bd -literal -offset indent
-         add a,b
+         ld a,a+b
          ld sp,hl
          MyMacro ;\ This will be expanded
-         sub a,87
+         ld a,a-87
 .Ed
 .Pp
 It's valid to call a macro from a macro (yes, even the same one).
@@ -1402,10 +1475,10 @@ it will insert the macro definition (the code enclosed in
 Suppose your macro contains a loop.
 .Bd -literal -offset indent
 MACRO LoopyMacro
-            xor  a,a
+            ld   a,a^a
 \&.loop       ld   [hl+],a
-            dec  c
+            ld   c-
-            jr   nz,.loop
+            ld   nz pc,b .loop
 ENDM
 .Ed
 .Pp
@@ -1420,10 +1493,10 @@ also works in
 blocks.
 .Bd -literal -offset indent
 MACRO LoopyMacro
-            xor  a,a
+            ld   a,a^a
 \&.loop\[rs]@     ld   [hl+],a
-            dec  c
+            ld   c-
-            jr   nz,.loop\[rs]@
+            ld   nz pc,b .loop\[rs]@
 ENDM
 .Ed
 .Pp
@@ -1451,14 +1524,14 @@ being the first argument specified on the macro invocation.
 MACRO LoopyMacro
             ld   hl,\[rs]1
             ld   c,\[rs]2
-            xor  a,a
+            ld   a,a^a
 \&.loop\[rs]@     ld   [hl+],a
-            dec  c
+            ld   c-
-            jr   nz,.loop\[rs]@
+            ld   nz pc,b .loop\[rs]@
             ENDM
 .Ed
 .Pp
-Now I can call the macro specifying two arguments, the first being the address and the second being a byte count.
+Now you can call the macro specifying two arguments, the first being the address and the second being a byte count.
 The generated code will then reset all bytes in this range.
 .Bd -literal -offset indent
 LoopyMacro MyVars,54
@@ -1566,7 +1639,7 @@ The following example will assemble
 four times:
 .Bd -literal -offset indent
 REPT 4
-  add  a,c
+  ld  a,a+c
 ENDR
 .Ed
 .Pp
@@ -1578,7 +1651,7 @@ to generate tables on the fly:
 ; (shifted and scaled from the range [-1.0, 1.0])
 ANGLE = 0.0
     REPT 256
-        db (MUL(64.0, SIN(ANGLE)) + 64.0) >> 16
+        ld [b @], (MUL(64.0, SIN(ANGLE)) + 64.0) >> 16
 ANGLE = ANGLE + 256.0 ; 256.0 = 65536 degrees / 256 entries
     ENDR
 .Ed
@@ -1598,24 +1671,25 @@ Everything between
 and the matching
 .Ic ENDR
 will be repeated for each value of a given symbol.
+String equates are not expanded within the symbol name.
 For example, this code will produce a table of squared values from 0 to 255:
 .Bd -literal -offset indent
 FOR N, 256
-      dw N * N
+      ld [w @], N * N
 ENDR
 .Ed
 .Pp
 It acts just as if you had done:
 .Bd -literal -offset ident
 N = 0
-      dw N * N
+      ld [w @], N * N
 N = 1
-      dw N * N
+      ld [w @], N * N
 N = 2
-      dw N * N
+      ld [w @], N * N
 ; ...
 N = 255
-      dw N * N
+      ld [w @], N * N
 N = 256
 .Ed
 .Pp
@@ -1624,9 +1698,9 @@ You can customize the range of
 values:
 .Bl -column "FOR V, start, stop, step"
 .It Sy Code Ta Sy Range
-.It Ic FOR Ar V , stop Ta Ar V No increments from 0 to Ar stop No
+.It Ic FOR Ar V , stop Ta Ar V No increments from 0 to Ar stop
-.It Ic FOR Ar V , start , stop Ta Ar V No increments from Ar start No to Ar stop No
+.It Ic FOR Ar V , start , stop Ta Ar V No increments from Ar start No to Ar stop
-.It Ic FOR Ar V , start , stop , step Ta Ar V No goes from Ar start No to Ar stop No by Ar step No
+.It Ic FOR Ar V , start , stop , step Ta Ar V No goes from Ar start No to Ar stop No by Ar step
 .El
 .Pp
 The
@@ -1706,18 +1780,18 @@ and
 Syntax examples are given below:
 .Bd -literal -offset indent
 Function:
-      xor a
+      ld a,a^a
 ASSERT LOW(Variable) == 0
       ld h, HIGH(Variable)
       ld l, a
       ld a, [hli]
       ; You can also indent this!
       ASSERT BANK(OtherFunction) == BANK(Function)
-      call OtherFunction
+      ld [--sp], pc,OtherFunction
 ; Lowercase also works
 assert Variable + 1 == OtherVariable
       ld c, [hl]
-      ret
+      ld pc,[sp++]
 \&.end
       ; If you specify one, a message will be printed
       STATIC_ASSERT .end - Function < 256, "Function is too large!"
@@ -1826,9 +1900,9 @@ takes a comma-separated list of options as its argument:
 .Bd -literal -offset indent
 PUSHO
 OPT   g.oOX ;Set the GB graphics constants to use these characters
-DW    `..ooOOXX
+LD [W @],    `..ooOOXX
 POPO
-DW    `00112233
+LD [W @],    `00112233
 .Ed
 .Pp
 The options that OPT can modify are currently:

src/asm/rpn.c

@@ -139,7 +139,7 @@ void rpn_BankSelf(struct Expression *expr)
 	if (!pCurrentSection) {
 		error("PC has no bank outside a section\n");
 		expr->nVal = 1;
-	} else if (pCurrentSection->bank == -1) {
+	} else if (pCurrentSection->bank == (uint32_t)-1) {
 		makeUnknown(expr, "Current section's bank is not known");
 		expr->nRPNPatchSize++;
 		*reserveSpace(expr, 1) = RPN_BANK_SELF;
@@ -165,7 +165,7 @@ void rpn_BankSymbol(struct Expression *expr, char const *tzSym)
 		sym = sym_Ref(tzSym);
 		assert(sym); // If the symbol didn't exist, it should have been created
 
-		if (sym_GetSection(sym) && sym_GetSection(sym)->bank != -1) {
+		if (sym_GetSection(sym) && sym_GetSection(sym)->bank != (uint32_t)-1) {
 			/* Symbol's section is known and bank is fixed */
 			expr->nVal = sym_GetSection(sym)->bank;
 		} else {
@@ -186,7 +186,7 @@ void rpn_BankSection(struct Expression *expr, char const *tzSectionName)
 
 	struct Section *pSection = out_FindSectionByName(tzSectionName);
 
-	if (pSection && pSection->bank != -1) {
+	if (pSection && pSection->bank != (uint32_t)-1) {
 		expr->nVal = pSection->bank;
 	} else {
 		makeUnknown(expr, "Section \"%s\"'s bank is not known",

src/asm/section.c

@@ -114,9 +114,9 @@ static unsigned int mergeSectUnion(struct Section *sect, enum SectionType type,
 	if (sect_HasData(type))
 		fail("Cannot declare ROM sections as UNION\n");
 
-	if (org != -1) {
+	if (org != (uint32_t)-1) {
 		/* If both are fixed, they must be the same */
-		if (sect->org != -1 && sect->org != org)
+		if (sect->org != (uint32_t)-1 && sect->org != org)
 			fail("Section already declared as fixed at different address $%04"
 			     PRIx32 "\n", sect->org);
 		else if (sect->align != 0 && (mask(sect->align) & (org - sect->alignOfs)))
@@ -128,7 +128,7 @@ static unsigned int mergeSectUnion(struct Section *sect, enum SectionType type,
 
 	} else if (alignment != 0) {
 		/* Make sure any fixed address given is compatible */
-		if (sect->org != -1) {
+		if (sect->org != (uint32_t)-1) {
 			if ((sect->org - alignOffset) & mask(alignment))
 				fail("Section already declared as fixed at incompatible address $%04"
 				     PRIx32 "\n", sect->org);
@@ -160,11 +160,11 @@ static unsigned int mergeFragments(struct Section *sect, enum SectionType type,
 	 * combination of both.
 	 * The merging is however performed at the *end* of the original section!
 	 */
-	if (org != -1) {
+	if (org != (uint32_t)-1) {
 		uint16_t curOrg = org - sect->size;
 
 		/* If both are fixed, they must be the same */
-		if (sect->org != -1 && sect->org != curOrg)
+		if (sect->org != (uint32_t)-1 && sect->org != curOrg)
 			fail("Section already declared as fixed at incompatible address $%04"
 			     PRIx32 " (cur addr = %04" PRIx32 ")\n",
 			     sect->org, sect->org + sect->size);
@@ -182,7 +182,7 @@ static unsigned int mergeFragments(struct Section *sect, enum SectionType type,
 			curOfs += 1U << alignment;
 
 		/* Make sure any fixed address given is compatible */
-		if (sect->org != -1) {
+		if (sect->org != (uint32_t)-1) {
 			if ((sect->org - curOfs) & mask(alignment))
 				fail("Section already declared as fixed at incompatible address $%04"
 				     PRIx32 "\n", sect->org);
@@ -221,10 +221,10 @@ static void mergeSections(struct Section *sect, enum SectionType type, uint32_t
 			// Common checks
 
 			/* If the section's bank is unspecified, override it */
-			if (sect->bank == -1)
+			if (sect->bank == (uint32_t)-1)
 				sect->bank = bank;
 			/* If both specify a bank, it must be the same one */
-			else if (bank != -1 && sect->bank != bank)
+			else if (bank != (uint32_t)-1 && sect->bank != bank)
 				fail("Section already declared with different bank %" PRIu32 "\n",
 				     sect->bank);
 			break;
@@ -296,7 +296,7 @@ static struct Section *getSection(char const *name, enum SectionType type, uint3
 
 	// First, validate parameters, and normalize them if applicable
 
-	if (bank != -1) {
+	if (bank != (uint32_t)-1) {
 		if (type != SECTTYPE_ROMX && type != SECTTYPE_VRAM
 		 && type != SECTTYPE_SRAM && type != SECTTYPE_WRAMX)
 			error("BANK only allowed for ROMX, WRAMX, SRAM, or VRAM sections\n");
@@ -316,7 +316,7 @@ static struct Section *getSection(char const *name, enum SectionType type, uint3
 		alignOffset = 0;
 	}
 
-	if (org != -1) {
+	if (org != (uint32_t)-1) {
 		if (org < startaddr[type] || org > endaddr(type))
 			error("Section \"%s\"'s fixed address %#" PRIx32
 				" is outside of range [%#" PRIx16 "; %#" PRIx16 "]\n",
@@ -331,7 +331,7 @@ static struct Section *getSection(char const *name, enum SectionType type, uint3
 		/* It doesn't make sense to have both alignment and org set */
 		uint32_t mask = mask(alignment);
 
-		if (org != -1) {
+		if (org != (uint32_t)-1) {
 			if ((org - alignOffset) & mask)
 				error("Section \"%s\"'s fixed address doesn't match its alignment\n",
 					name);
@@ -453,7 +453,7 @@ void sect_AlignPC(uint8_t alignment, uint16_t offset)
 	struct Section *sect = sect_GetSymbolSection();
 	uint16_t alignSize = 1 << alignment; // Size of an aligned "block"
 
-	if (sect->org != -1) {
+	if (sect->org != (uint32_t)-1) {
 		if ((sym_GetPCValue() - offset) % alignSize)
 			error("Section's fixed address fails required alignment (PC = $%04" PRIx32
 			      ")\n", sym_GetPCValue());
@@ -761,6 +761,8 @@ void out_BinaryFile(char const *s, int32_t startPos)
 
 	if (!f) {
 		if (oGeneratedMissingIncludes) {
+			if (verbose)
+				printf("Aborting (-MG) on INCBIN file '%s' (%s)\n", s, strerror(errno));
 			oFailedOnMissingInclude = true;
 			return;
 		}
@@ -828,6 +830,8 @@ void out_BinaryFileSlice(char const *s, int32_t start_pos, int32_t length)
 	if (!f) {
 		free(fullPath);
 		if (oGeneratedMissingIncludes) {
+			if (verbose)
+				printf("Aborting (-MG) on INCBIN file '%s' (%s)\n", s, strerror(errno));
 			oFailedOnMissingInclude = true;
 			return;
 		}

src/asm/symbol.c

@@ -179,7 +179,7 @@ static void updateSymbolFilename(struct Symbol *sym)
 
 	setSymbolFilename(sym);
 	/* If the old node was referenced, ensure the new one is */
-	if (oldSrc && oldSrc->referenced && oldSrc->ID != -1)
+	if (oldSrc && oldSrc->referenced && oldSrc->ID != (uint32_t)-1)
 		out_RegisterNode(sym->src);
 	/* TODO: unref the old node, and use `out_ReplaceNode` instead if deleting it */
 }
@@ -277,7 +277,7 @@ struct Symbol const *sym_GetPC(void)
 
 static inline bool isReferenced(struct Symbol const *sym)
 {
-	return sym->ID != -1;
+	return sym->ID != (uint32_t)-1;
 }
 
 /*
@@ -315,7 +315,7 @@ uint32_t sym_GetPCValue(void)
 
 	if (!sect)
 		error("PC has no value outside a section\n");
-	else if (sect->org == -1)
+	else if (sect->org == (uint32_t)-1)
 		error("Expected constant PC but section is not fixed\n");
 	else
 		return CallbackPC();

src/asm/util.c

@@ -57,7 +57,7 @@ char const *print(int c)
 
 	default: /* Print as hex */
 		buf[1] = 'x';
-		sprintf(&buf[2], "%02hhx", c);
+		sprintf(&buf[2], "%02hhx", (uint8_t)c);
 		return buf;
 	}
 	buf[2] = '\0';

src/fix/main.c

@@ -870,11 +870,13 @@ static void processFile(int input, int output, char const *name, off_t fileSize)
 
 	// Output ROMX if it was buffered
 	if (romx) {
+		// The value returned is either -1, or smaller than `totalRomxLen`,
+		// so it's fine to cast to `size_t`
 		writeLen = writeBytes(output, romx, totalRomxLen);
 		if (writeLen == -1) {
 			report("FATAL: Failed to write \"%s\"'s ROMX: %s\n", name, strerror(errno));
 			goto free_romx;
-		} else if (writeLen < totalRomxLen) {
+		} else if ((size_t)writeLen < totalRomxLen) {
 			report("FATAL: Could only write %ld of \"%s\"'s %ld ROMX bytes\n",
 			       writeLen, name, totalRomxLen);
 			goto free_romx;
@@ -898,7 +900,9 @@ static void processFile(int input, int output, char const *name, off_t fileSize)
 			size_t thisLen = len > sizeof(bank) ? sizeof(bank) : len;
 			ssize_t ret = writeBytes(output, bank, thisLen);
 
-			if (ret != thisLen) {
+			// The return value is either -1, or at most `thisLen`,
+			// so it's fine to cast to `size_t`
+			if ((size_t)ret != thisLen) {
 				report("FATAL: Failed to write \"%s\"'s padding: %s\n",
 				       name, strerror(errno));
 				break;

src/fix/rgbfix.1

@@ -1,11 +1,11 @@
 .\"
 .\" This file is part of RGBDS.
 .\"
-.\" Copyright (c) 2010-2017, Anthony J. Bentley and RGBDS contributors.
+.\" Copyright (c) 2010-2021, Anthony J. Bentley and RGBDS contributors.
 .\"
 .\" SPDX-License-Identifier: MIT
 .\"
-.Dd December 5, 2019
+.Dd March 28, 2021
 .Dt RGBFIX 1
 .Os
 .Sh NAME

src/gfx/rgbgfx.1

@@ -1,11 +1,11 @@
 .\"
 .\" This file is part of RGBDS.
 .\"
-.\" Copyright (c) 2013-2018, stag019 and RGBDS contributors.
+.\" Copyright (c) 2013-2021, stag019 and RGBDS contributors.
 .\"
 .\" SPDX-License-Identifier: MIT
 .\"
-.Dd December 5, 2019
+.Dd March 28, 2021
 .Dt RGBGFX 1
 .Os
 .Sh NAME
@@ -78,7 +78,8 @@ Same as
 .Fl f ,
 but additionally, the supplied command line parameters are saved within the PNG and will be loaded and automatically used next time.
 .It Fl h , Fl Fl horizontal
-Lay out tiles horizontally rather than vertically.
+Lay out tiles in column-major order (column by column), instead of the default row-major order (line by line).
+Especially useful for "8x16" OBJ mode, if the input image is 16 pixels tall.
 .It Fl m , Fl Fl mirror-tiles
 Truncate tiles by checking for tiles that are mirrored versions of others and omitting these from the output file.
 Useful with tilemaps and attrmaps together to keep track of the duplicated tiles and the dimension mirrored.

src/link/assign.c

@@ -112,6 +112,13 @@ static inline void assignSection(struct Section *section,
 	section->org = location->address;
 	section->bank = location->bank;
 
+	// Propagate the assigned location to all UNIONs/FRAGMENTs
+	// so `jr` patches in them will have the correct offset
+	for (struct Section *next = section->nextu; next != NULL; next = next->nextu) {
+		next->org = section->org;
+		next->bank = section->bank;
+	}
+
 	nbSectionsToAssign--;
 
 	out_AddSection(section);

src/link/object.c

@@ -188,7 +188,7 @@ static void readFileStackNode(FILE *file, struct FileStackNode fileNodes[], uint
 
 	tryReadlong(parentID, file,
 		    "%s: Cannot read node #%" PRIu32 "'s parent ID: %s", fileName, i);
-	fileNodes[i].parent = parentID == -1 ? NULL : &fileNodes[parentID];
+	fileNodes[i].parent = parentID == (uint32_t)-1 ? NULL : &fileNodes[parentID];
 	tryReadlong(fileNodes[i].lineNo, file,
 		    "%s: Cannot read node #%" PRIu32 "'s line number: %s", fileName, i);
 	tryGetc(fileNodes[i].type, file, "%s: Cannot read node #%" PRIu32 "'s type: %s",
@@ -261,7 +261,7 @@ static void readSymbol(FILE *file, struct Symbol *symbol,
  * @param i The number of the patch to report in errors
  */
 static void readPatch(FILE *file, struct Patch *patch, char const *fileName, char const *sectName,
-		      uint32_t i, struct Section *fileSections[], struct FileStackNode fileNodes[])
+		      uint32_t i, struct FileStackNode fileNodes[])
 {
 	uint32_t nodeID;
 	uint8_t type;
@@ -279,7 +279,6 @@ static void readPatch(FILE *file, struct Patch *patch, char const *fileName, cha
 	tryReadlong(patch->pcSectionID, file,
 		    "%s: Unable to read \"%s\"'s patch #%" PRIu32 "'s PC offset: %s",
 		    fileName, sectName, i);
-	patch->pcSection = patch->pcSectionID == -1 ? NULL : fileSections[patch->pcSectionID];
 	tryReadlong(patch->pcOffset, file,
 		    "%s: Unable to read \"%s\"'s patch #%" PRIu32 "'s PC offset: %s",
 		    fileName, sectName, i);
@@ -304,6 +303,16 @@ static void readPatch(FILE *file, struct Patch *patch, char const *fileName, cha
 		     feof(file) ? "Unexpected end of file" : strerror(errno));
 }
 
+/**
+ * Sets a patch's pcSection from its pcSectionID.
+ * @param patch The struct to fix
+ */
+static void linkPatchToPCSect(struct Patch *patch, struct Section *fileSections[])
+{
+	patch->pcSection = patch->pcSectionID == (uint32_t)-1 ? NULL
+							      : fileSections[patch->pcSectionID];
+}
+
 /**
  * Reads a section from a file.
  * @param file The file to read from
@@ -311,7 +320,7 @@ static void readPatch(FILE *file, struct Patch *patch, char const *fileName, cha
  * @param fileName The filename to report in errors
  */
 static void readSection(FILE *file, struct Section *section, char const *fileName,
-			struct Section *fileSections[], struct FileStackNode fileNodes[])
+			struct FileStackNode fileNodes[])
 {
 	int32_t tmp;
 	uint8_t byte;
@@ -388,12 +397,9 @@ static void readSection(FILE *file, struct Section *section, char const *fileNam
 			malloc(sizeof(*patches) * section->nbPatches + 1);
 
 		if (!patches)
-			err(1, "%s: Unable to read \"%s\"'s patches", fileName,
+			err(1, "%s: Unable to read \"%s\"'s patches", fileName, section->name);
-			    section->name);
+		for (uint32_t i = 0; i < section->nbPatches; i++)
-		for (uint32_t i = 0; i < section->nbPatches; i++) {
+			readPatch(file, &patches[i], fileName, section->name, i, fileNodes);
-			readPatch(file, &patches[i], fileName, section->name,
-				  i, fileSections, fileNodes);
-		}
 		section->patches = patches;
 	}
 }
@@ -435,13 +441,13 @@ static void linkSymToSect(struct Symbol const *symbol, struct Section *section)
  */
 static void readAssertion(FILE *file, struct Assertion *assert,
 			  char const *fileName, uint32_t i,
-			  struct Section *fileSections[], struct FileStackNode fileNodes[])
+			  struct FileStackNode fileNodes[])
 {
 	char assertName[sizeof("Assertion #4294967295")]; // UINT32_MAX
 
 	snprintf(assertName, sizeof(assertName), "Assertion #%" PRIu32, i);
 
-	readPatch(file, &assert->patch, fileName, assertName, 0, fileSections, fileNodes);
+	readPatch(file, &assert->patch, fileName, assertName, 0, fileNodes);
 	tryReadstr(assert->message, file, "%s: Cannot read assertion's message: %s",
 		   fileName);
 }
@@ -549,7 +555,7 @@ void obj_ReadFile(char const *fileName, unsigned int fileID)
 			err(1, "%s: Couldn't create new section", fileName);
 
 		fileSections[i]->nextu = NULL;
-		readSection(file, fileSections[i], fileName, fileSections, nodes[fileID].nodes);
+		readSection(file, fileSections[i], fileName, nodes[fileID].nodes);
 		fileSections[i]->fileSymbols = fileSymbols;
 		if (nbSymPerSect[i]) {
 			fileSections[i]->symbols = malloc(nbSymPerSect[i]
@@ -567,7 +573,15 @@ void obj_ReadFile(char const *fileName, unsigned int fileID)
 
 	free(nbSymPerSect);
 
-	/* Give symbols pointers to their sections */
+	/* Give patches' PC section pointers to their sections */
+	for (uint32_t i = 0; i < nbSections; i++) {
+		if (sect_HasData(fileSections[i]->type)) {
+			for (uint32_t j = 0; j < fileSections[i]->nbPatches; j++)
+				linkPatchToPCSect(&fileSections[i]->patches[j], fileSections);
+		}
+	}
+
+	/* Give symbols' section pointers to their sections */
 	for (uint32_t i = 0; i < nbSymbols; i++) {
 		int32_t sectionID = fileSymbols[i]->sectionID;
 
@@ -599,7 +613,8 @@ void obj_ReadFile(char const *fileName, unsigned int fileID)
 
 		if (!assertion)
 			err(1, "%s: Couldn't create new assertion", fileName);
-		readAssertion(file, assertion, fileName, i, fileSections, nodes[fileID].nodes);
+		readAssertion(file, assertion, fileName, i, nodes[fileID].nodes);
+		linkPatchToPCSect(&assertion->patch, fileSections);
 		assertion->fileSymbols = fileSymbols;
 		assertion->next = assertions;
 		assertions = assertion;
@@ -635,7 +650,7 @@ static void freeSection(struct Section *section, void *arg)
 	free(section->name);
 	if (sect_HasData(section->type)) {
 		free(section->data);
-		for (int32_t i = 0; i < section->nbPatches; i++)
+		for (uint32_t i = 0; i < section->nbPatches; i++)
 			free(section->patches[i].rpnExpression);
 		free(section->patches);
 	}

src/link/output.c

@@ -336,7 +336,7 @@ static void writeSymBank(struct SortedSections const *bankSections)
 /**
  * Write a bank's contents to the map file
  * @param bankSections The bank's sections
- * @return The bank's slack space
+ * @return The bank's used space
  */
 static uint16_t writeMapBank(struct SortedSections const *sectList,
 			     enum SectionType type, uint32_t bank)
@@ -350,14 +350,14 @@ static uint16_t writeMapBank(struct SortedSections const *sectList,
 	fprintf(mapFile, "%s bank #%" PRIu32 ":\n", typeNames[type],
 		bank + bankranges[type][0]);
 
-	uint16_t slack = maxsize[type];
+	uint16_t used = 0;
 
 	while (section || zeroLenSection) {
 		struct SortedSection const **pickedSection =
 			nextSection(&section, &zeroLenSection);
 		struct Section const *sect = (*pickedSection)->section;
 
-		slack -= sect->size;
+		used += sect->size;
 
 		if (sect->size != 0)
 			fprintf(mapFile, "  SECTION: $%04" PRIx16 "-$%04" PRIx16 " ($%04" PRIx16 " byte%s) [\"%s\"]\n",
@@ -368,44 +368,54 @@ static uint16_t writeMapBank(struct SortedSections const *sectList,
 			fprintf(mapFile, "  SECTION: $%04" PRIx16 " (0 bytes) [\"%s\"]\n",
 				sect->org, sect->name);
 
+		uint16_t org = sect->org;
+
+		while (sect) {
 			for (size_t i = 0; i < sect->nbSymbols; i++)
 				fprintf(mapFile, "           $%04" PRIx32 " = %s\n",
-				sect->symbols[i]->offset + sect->org,
+					sect->symbols[i]->offset + org,
 					sect->symbols[i]->name);
 
+			sect = sect->nextu; // Also print symbols in the following "pieces"
+		}
+
 		*pickedSection = (*pickedSection)->next;
 	}
 
-	if (slack == maxsize[type])
+
+	if (used == 0) {
 		fputs("  EMPTY\n\n", mapFile);
-	else
+	} else {
+		uint16_t slack = maxsize[type] - used;
+
 		fprintf(mapFile, "    SLACK: $%04" PRIx16 " byte%s\n\n", slack,
 			slack == 1 ? "" : "s");
+	}
 
-	return slack;
+	return used;
 }
 
 /**
- * Write the total slack space by section type to the map file
+ * Write the total used space by section type to the map file
- * @param slackMap The total slack space by section type
+ * @param usedMap The total used space by section type
  */
-static void writeMapSlack(uint32_t slackMap[MIN_NB_ELMS(SECTTYPE_INVALID)])
+static void writeMapUsed(uint32_t usedMap[MIN_NB_ELMS(SECTTYPE_INVALID)])
 {
 	if (!mapFile)
 		return;
 
-	fputs("FREE:\n", mapFile);
+	fputs("USED:\n", mapFile);
 
 	for (uint8_t i = 0; i < SECTTYPE_INVALID; i++) {
 		enum SectionType type = typeMap[i];
 
-		// Do not output slack space for VRAM or OAM
+		// Do not output used space for VRAM or OAM
 		if (type == SECTTYPE_VRAM || type == SECTTYPE_OAM)
 			continue;
 
 		if (sections[type].nbBanks > 0) {
 			fprintf(mapFile, "    %s: $%04" PRIx32 " byte%s in %" PRIu32 " bank%s\n",
-				typeNames[type], slackMap[type], slackMap[type] == 1 ? "" : "s",
+				typeNames[type], usedMap[type], usedMap[type] == 1 ? "" : "s",
 				sections[type].nbBanks, sections[type].nbBanks == 1 ? "" : "s");
 		}
 	}
@@ -419,7 +429,7 @@ static void writeSymAndMap(void)
 	if (!symFileName && !mapFileName)
 		return;
 
-	uint32_t slackMap[SECTTYPE_INVALID] = {0};
+	uint32_t usedMap[SECTTYPE_INVALID] = {0};
 
 	symFile = openFile(symFileName, "w");
 	mapFile = openFile(mapFileName, "w");
@@ -434,11 +444,11 @@ static void writeSymAndMap(void)
 			struct SortedSections const *sect = &sections[type].banks[bank];
 
 			writeSymBank(sect);
-			slackMap[type] += writeMapBank(sect, type, bank);
+			usedMap[type] += writeMapBank(sect, type, bank);
 		}
 	}
 
-	writeMapSlack(slackMap);
+	writeMapUsed(usedMap);
 
 	closeFile(symFile);
 	closeFile(mapFile);

src/link/patch.c

@@ -400,7 +400,7 @@ static int32_t computeRPNExpr(struct Patch const *patch,
 
 void patch_CheckAssertions(struct Assertion *assert)
 {
-	verbosePrint("Checking assertions...");
+	verbosePrint("Checking assertions...\n");
 	initRPNStack();
 
 	while (assert) {

src/link/rgblink.1

@@ -1,11 +1,11 @@
 .\"
 .\" This file is part of RGBDS.
 .\"
-.\" Copyright (c) 2010-2019, Anthony J. Bentley and RGBDS contributors.
+.\" Copyright (c) 2010-2021, Anthony J. Bentley and RGBDS contributors.
 .\"
 .\" SPDX-License-Identifier: MIT
 .\"
-.Dd November 26, 2019
+.Dd March 28, 2021
 .Dt RGBLINK 1
 .Os
 .Sh NAME

src/link/rgblink.5

@@ -1,11 +1,11 @@
 .\"
 .\" This file is part of RGBDS.
 .\"
-.\" Copyright (c) 2017-2018, Antonio Nino Diaz and RGBDS contributors.
+.\" Copyright (c) 2017-2021, Antonio Nino Diaz and RGBDS contributors.
 .\"
 .\" SPDX-License-Identifier: MIT
 .\"
-.Dd November 26, 2019
+.Dd March 28, 2021
 .Dt RGBLINK 5
 .Os
 .Sh NAME

src/link/section.c

@@ -194,11 +194,7 @@ void sect_AddSection(struct Section *section)
 		     section->name, typeNames[section->type]);
 	} else {
 		/* If not, add it */
-		bool collided = hash_AddElement(sections, section->name,
+		hash_AddElement(sections, section->name, section);
-						section);
-
-		if (beVerbose && collided)
-			warnx("Section hashmap collision occurred!");
 	}
 }
 
@@ -248,7 +244,7 @@ static void doSanityChecks(struct Section *section, void *ptr)
 	 * Check if alignment is reasonable, this is important to avoid UB
 	 * An alignment of zero is equivalent to no alignment, basically
 	 */
-	if (section->isAlignFixed && section->alignMask == 1)
+	if (section->isAlignFixed && section->alignMask == 0)
 		section->isAlignFixed = false;
 
 	/* Too large an alignment may not be satisfiable */

src/rgbds.5

@@ -1,11 +1,11 @@
 .\"
 .\" This file is part of RGBDS.
 .\"
-.\" Copyright (c) 2017-2020, Antonio Nino Diaz and RGBDS contributors.
+.\" Copyright (c) 2017-2021, Antonio Nino Diaz and RGBDS contributors.
 .\"
 .\" SPDX-License-Identifier: MIT
 .\"
-.Dd January 26, 2018
+.Dd March 28, 2021
 .Dt RGBDS 5
 .Os
 .Sh NAME
@@ -22,11 +22,11 @@ This toolchain is in development and new features may require adding more inform
 The following types are used:
 .Pp
 .Ar LONG
-is a 32‐bit integer stored in little‐endian format.
+is a 32-bit integer stored in little-endian format.
 .Ar BYTE
-is an 8‐bit integer.
+is an 8-bit integer.
 .Ar STRING
-is a 0‐terminated string of
+is a 0-terminated string of
 .Ar BYTE .
 .Bd -literal
 ; Header

src/rgbds.7

@@ -1,11 +1,11 @@
 .\"
 .\" This file is part of RGBDS.
 .\"
-.\" Copyright (c) 2010-2018, Anthony J. Bentley and RGBDS contributors.
+.\" Copyright (c) 2010-2021, Anthony J. Bentley and RGBDS contributors.
 .\"
 .\" SPDX-License-Identifier: MIT
 .\"
-.Dd March 7, 2018
+.Dd March 28, 2021
 .Dt RGBDS 7
 .Os
 .Sh NAME

test/asm/align-large-ofs.err

@@ -1,3 +1,3 @@
 ERROR: align-large-ofs.asm(2):
     Alignment offset (2) must be smaller than alignment size (2)
-error: Assembly aborted (1 errors)!
+error: Assembly aborted (1 error)!

test/asm/assert-nosect-bank.err

@@ -1,3 +1,3 @@
 ERROR: assert-nosect-bank.asm(1):
     PC has no bank outside a section
-error: Assembly aborted (1 errors)!
+error: Assembly aborted (1 error)!

test/asm/assert@-no-sect.err

@@ -1,3 +1,3 @@
 ERROR: assert@-no-sect.asm(1):
     PC has no value outside a section
-error: Assembly aborted (1 errors)!
+error: Assembly aborted (1 error)!

test/asm/def.asm

@@ -0,0 +1,29 @@
+def variable = 1
+	println variable
+def variable set 2
+	println variable
+redef variable = 3
+	println variable
+redef variable set 4
+	println variable
+
+DEF constant EQU 42
+	println constant
+
+DEF string EQUS "here"
+	println "{string}"
+
+rsreset
+def _x rb
+def _y rw 2
+def _z rl
+def _size rb 0
+	println "{_x} {_y} {_z} {_size}"
+
+def constant equ 6*7 ; fails
+	println constant
+
+redef string equs "there"
+	println "{string}"
+
+redef constant equ 6*9 ; syntax error

test/asm/def.err

@@ -0,0 +1,5 @@
+ERROR: def.asm(23):
+    'constant' already defined at def.asm(10)
+ERROR: def.asm(29):
+    syntax error, unexpected EQU, expecting SET or = or EQUS
+error: Assembly aborted (2 errors)!

test/asm/def.out

@@ -0,0 +1,9 @@
+$1
+$2
+$3
+$4
+$2A
+here
+$0 $1 $5 $9
+$2A
+there

test/asm/def.simple.err

@@ -0,0 +1,5 @@
+ERROR: def.asm(23):
+    'constant' already defined at def.asm(10)
+ERROR: def.asm(29):
+    syntax error
+error: Assembly aborted (2 errors)!

test/asm/deprecated-pi.err

@@ -2,4 +2,4 @@ warning: deprecated-pi.asm(2): [-Wobsolete]
     `_PI` is deprecated; use 3.14159
 ERROR: deprecated-pi.asm(3):
     Built-in symbol '_PI' cannot be purged
-error: Assembly aborted (1 errors)!
+error: Assembly aborted (1 error)!

test/asm/ds-bad.err

@@ -2,4 +2,4 @@ ERROR: ds-bad.asm(3):
     Expected constant expression: 'unknown' is not constant at assembly time
 warning: ds-bad.asm(4): [-Wtruncation]
     Expression must be 8-bit
-error: Assembly aborted (1 errors)!
+error: Assembly aborted (1 error)!

test/asm/elif-after-taken-if.asm

@@ -0,0 +1,23 @@
+if 1
+	println "taken if"
+elif 2 / 0 ; avoided fatal "Division by zero" error
+	println "untaken elif"
+elif 3 / 0 ; avoided fatal "Division by zero" error
+	println "untaken after untaken"
+endc
+
+if 0
+	println "untaken if"
+elif 1
+	println "taken elif"
+elif !@#$ ; avoided fatal syntax error
+	println "untaken elif"
+elif %^&* ; avoided fatal syntax error
+	println "untaken after untaken"
+endc
+
+if 0
+	println "untaken if"
+elif 1 / 0 ; fatal "Division by zero" error
+	println "unreached elif"
+endc

test/asm/elif-after-taken-if.err

@@ -0,0 +1,2 @@
+FATAL: elif-after-taken-if.asm(21):
+    Division by zero

test/asm/elif-after-taken-if.out

@@ -0,0 +1,2 @@
+taken if
+taken elif

test/asm/for.asm

@@ -33,7 +33,7 @@ endr
 	println "-> {d:q}"
 
 s EQUS "x"
-for s, 3, 30, 3
+for {s}, 3, 30, 3
 	print "{d:x} "
 endr
 	println "-> {d:x}"

test/asm/fragment-align.err

@@ -1,3 +1,3 @@
 ERROR: fragment-align.asm(25):
     Section's alignment fails required alignment (offset from section start = $0004)
-error: Assembly aborted (1 errors)!
+error: Assembly aborted (1 error)!

test/asm/garbage_char.err

@@ -1,3 +1,3 @@
 ERROR: garbage_char.asm(1):
     Unknown character 0xFF
-error: Assembly aborted (1 errors)!
+error: Assembly aborted (1 error)!

test/asm/if@-no-sect.err

@@ -1,3 +1,3 @@
 ERROR: if@-no-sect.asm(1):
     PC has no value outside a section
-error: Assembly aborted (1 errors)!
+error: Assembly aborted (1 error)!

test/asm/incbin-empty-bad.err

@@ -1,3 +1,3 @@
 ERROR: incbin-empty-bad.asm(3):
     Specified range in INCBIN is out of bounds (0 + 1 > 0)
-error: Assembly aborted (1 errors)!
+error: Assembly aborted (1 error)!

test/asm/incbin-end-bad.err

@@ -1,3 +1,3 @@
 ERROR: incbin-end-bad.asm(3):
     Specified range in INCBIN is out of bounds (123 + 1 > 123)
-error: Assembly aborted (1 errors)!
+error: Assembly aborted (1 error)!

test/asm/label-outside-section.err

@@ -1,3 +1,3 @@
 ERROR: label-outside-section.asm(1):
     Label "bad" created outside of a SECTION
-error: Assembly aborted (1 errors)!
+error: Assembly aborted (1 error)!

test/asm/label-redefinition.err

@@ -1,3 +1,3 @@
 ERROR: label-redefinition.asm(7):
     'Sym' already defined at label-redefinition.asm(6) -> label-redefinition.asm::m(4)
-error: Assembly aborted (1 errors)!
+error: Assembly aborted (1 error)!

test/asm/line-continuation-whitespace.err

@@ -1,3 +1,3 @@
 ERROR: line-continuation-whitespace.asm(7):
     Label "foo" created outside of a SECTION
-error: Assembly aborted (1 errors)!
+error: Assembly aborted (1 error)!

test/asm/line-continuation.err

@@ -1,3 +1,3 @@
 ERROR: line-continuation.asm(7):
     Label "foo" created outside of a SECTION
-error: Assembly aborted (1 errors)!
+error: Assembly aborted (1 error)!

test/asm/load-rom.err

@@ -1,3 +1,3 @@
 ERROR: load-rom.asm(3):
     `LOAD` blocks cannot create a ROM section
-error: Assembly aborted (1 errors)!
+error: Assembly aborted (1 error)!

test/asm/local-purge.err

@@ -1,3 +1,3 @@
 ERROR: local-purge.asm(8):
     Interpolated symbol ".loc" does not exist
-error: Assembly aborted (1 errors)!
+error: Assembly aborted (1 error)!

test/asm/local-without-parent.err

@@ -1,3 +1,3 @@
 ERROR: local-without-parent.asm(2):
     Local label '.test' in main scope
-error: Assembly aborted (1 errors)!
+error: Assembly aborted (1 error)!

test/asm/local-wrong-parent.err

@@ -1,3 +1,3 @@
 ERROR: local-wrong-parent.asm(5):
     Not currently in the scope of 'WrongParent'
-error: Assembly aborted (1 errors)!
+error: Assembly aborted (1 error)!

test/asm/macro-arg-in-string.err

@@ -1,3 +1,3 @@
 ERROR: macro-arg-in-string.asm(12):
     Illegal character escape '!'
-error: Assembly aborted (1 errors)!
+error: Assembly aborted (1 error)!

test/asm/multi-line-strings.err

@@ -2,4 +2,4 @@ ERROR: multi-line-strings.asm(23):
     Unterminated string
 warning: multi-line-strings.asm(35): [-Wuser]
     check the line number
-error: Assembly aborted (1 errors)!
+error: Assembly aborted (1 error)!

test/asm/narg-nosect.err

@@ -1,3 +1,3 @@
 ERROR: narg-nosect.asm(1):
     _NARG does not make sense outside of a macro
-error: Assembly aborted (1 errors)!
+error: Assembly aborted (1 error)!

test/asm/nested-brackets.err

@@ -1,3 +1,3 @@
 ERROR: nested-brackets.asm(5):
     Missing }
-error: Assembly aborted (1 errors)!
+error: Assembly aborted (1 error)!

test/asm/null-in-macro.err

@@ -1,3 +1,3 @@
 ERROR: null-in-macro.asm(4) -> null-in-macro.asm::foo(2):
     Unknown character 0x00
-error: Assembly aborted (1 errors)!
+error: Assembly aborted (1 error)!

test/asm/period.err

@@ -1,3 +1,3 @@
 ERROR: period.asm(5):
     syntax error, unexpected .
-error: Assembly aborted (1 errors)!
+error: Assembly aborted (1 error)!

test/asm/period.simple.err

@@ -1,3 +1,3 @@
 ERROR: period.asm(5):
     syntax error
-error: Assembly aborted (1 errors)!
+error: Assembly aborted (1 error)!

test/asm/purge-refs.err

@@ -1,3 +1,3 @@
 ERROR: purge-refs.asm(6):
     Symbol "Floating" is referenced and thus cannot be purged
-error: Assembly aborted (1 errors)!
+error: Assembly aborted (1 error)!

test/asm/purge.err

@@ -1,3 +1,3 @@
 ERROR: purge.asm(9):
     Symbol "Referenced" is referenced and thus cannot be purged
-error: Assembly aborted (1 errors)!
+error: Assembly aborted (1 error)!

test/asm/redef-equs.err

@@ -1,3 +1,3 @@
 ERROR: redef-equs.asm(23):
     'N' already defined as non-EQUS at redef-equs.asm(22)
-error: Assembly aborted (1 errors)!
+error: Assembly aborted (1 error)!

test/asm/skip-elif-condition.asm

@@ -3,7 +3,7 @@ mac: MACRO
 		println "small \1"
 	elif (\1) > 100
 		println "large \1"
-	elif (\1) / 0 == 42 ; only evaluated if the "large" condition was taken
+	elif (\1) / 0 == 42 ; only evaluated if neither "small" nor "large" was taken
 		println "division by zero!?"
 	elif syntax! error?
 		println "X_X"
@@ -15,3 +15,4 @@ ENDM
 	mac 2 + 2
 	mac STRLEN("abcdef")
 	mac 101
+	mac 23

test/asm/skip-elif-condition.err

@@ -1,2 +1,2 @@
-FATAL: skip-elif-condition.asm(17) -> skip-elif-condition.asm::mac(6):
+FATAL: skip-elif-condition.asm(18) -> skip-elif-condition.asm::mac(6):
     Division by zero

test/asm/string-formatting.err

@@ -1,3 +1,3 @@
 ERROR: string-formatting.asm(10):
     Formatting string with prefix flag '#'
-error: Assembly aborted (1 errors)!
+error: Assembly aborted (1 error)!

test/asm/sym-collision.err

@@ -1,3 +1,3 @@
 ERROR: sym-collision.asm(26):
     Interpolated symbol "dork" does not exist
-error: Assembly aborted (1 errors)!
+error: Assembly aborted (1 error)!

test/asm/syntax-error-eof-newline.err

@@ -1,3 +1,3 @@
 ERROR: syntax-error-eof-newline.asm(5) -> syntax-error-eof-newline.inc(1):
     syntax error, unexpected newline
-error: Assembly aborted (1 errors)!
+error: Assembly aborted (1 error)!

test/asm/syntax-error-eof-newline.simple.err

@@ -1,3 +1,3 @@
 ERROR: syntax-error-eof-newline.asm(5) -> syntax-error-eof-newline.inc(1):
     syntax error
-error: Assembly aborted (1 errors)!
+error: Assembly aborted (1 error)!

test/asm/syntax-error.err

@@ -1,3 +1,3 @@
 ERROR: syntax-error.asm(2):
     syntax error, unexpected a
-error: Assembly aborted (1 errors)!
+error: Assembly aborted (1 error)!

test/asm/syntax-error.simple.err

@@ -1,3 +1,3 @@
 ERROR: syntax-error.asm(2):
     syntax error
-error: Assembly aborted (1 errors)!
+error: Assembly aborted (1 error)!

test/link/load-fragment-jr.asm

@@ -0,0 +1,12 @@
+SECTION "main", ROM0
+LOAD FRAGMENT "test", SRAM
+ENDL
+
+; The RPN patch for 'jr Label' in section "alt" refers to section "test",
+; but the object file puts section "test" after section "alt".
+; This case needs to be handled when identifying patches' PC sections.
+SECTION "alt", ROM0
+LOAD FRAGMENT "test", SRAM
+	jr Label
+Label:
+ENDL

test/link/load-fragment/a.asm

@@ -0,0 +1,4 @@
+SECTION "main", ROM0
+LOAD FRAGMENT "test", SRAM
+	db 0
+ENDL

test/link/load-fragment/b.asm

@@ -0,0 +1,6 @@
+SECTION "SECTION2", ROM0
+LOAD FRAGMENT "test", SRAM
+	jr Label
+Label:
+	dw Label
+ENDL

test/link/section-union/assert.out

@@ -3,4 +3,4 @@ Linking failed with 1 error
 ---
 ERROR: <stdin>(30):
     Assertion failed: Force failing the build
-error: Assembly aborted (1 errors)!
+error: Assembly aborted (1 error)!

test/link/test.sh

@@ -39,7 +39,7 @@ tryCmp () {
 	fi
 }
 
-rgblink() {
+rgblinkQuiet () {
 	out="$(env $RGBLINK "$@")" || return $?
 	if [[ -n "$out" ]]; then
 		echo "$bold${red}Linking shouldn't produce anything on stdout!$rescolors$resbold"
@@ -55,13 +55,13 @@ for i in *.asm; do
 	ran_flag=
 	for flag in '-d' '-t' '-w'; do
 		if [ -f ${i%.asm}-no${flag}.out ]; then
-			rgblink -o $gbtemp $otemp > $outtemp 2>&1
+			rgblinkQuiet -o $gbtemp $otemp > $outtemp 2>&1
 			tryDiff ${i%.asm}-no${flag}.out $outtemp
 			rc=$(($? || $rc))
 			ran_flag=1
 		fi
 		if [ -f ${i%.asm}${flag}.out ]; then
-			rgblink ${flag} -o $gbtemp $otemp > $outtemp 2>&1
+			rgblinkQuiet ${flag} -o $gbtemp $otemp > $outtemp 2>&1
 			tryDiff ${i%.asm}${flag}.out $outtemp
 			rc=$(($? || $rc))
 			ran_flag=1
@@ -73,7 +73,7 @@ for i in *.asm; do
 
 	# Other tests have several linker scripts
 	find . -name "${i%.asm}*.link" | while read script; do
-		rgblink -l $script -o $gbtemp $otemp > $outtemp 2>&1
+		rgblinkQuiet -l $script -o $gbtemp $otemp > $outtemp 2>&1
 		tryDiff ${script%.link}.out $outtemp
 		rc=$(($? || $rc))
 		ran_flag=1
@@ -83,7 +83,7 @@ for i in *.asm; do
 	fi
 
 	# The rest of the tests just links a file, and maybe checks the binary
-	rgblink -o $gbtemp $otemp > $outtemp 2>&1
+	rgblinkQuiet -o $gbtemp $otemp > $outtemp 2>&1
 	if [ -f ${i%.asm}.out ]; then
 		tryDiff ${i%.asm}.out $outtemp
 		rc=$(($? || $rc))
@@ -103,7 +103,7 @@ i="bank-const.asm"
 startTest
 $RGBASM -o $otemp bank-const/a.asm
 $RGBASM -o $gbtemp2 bank-const/b.asm
-rgblink -o $gbtemp $gbtemp2 $otemp > $outtemp 2>&1
+rgblinkQuiet -o $gbtemp $gbtemp2 $otemp > $outtemp 2>&1
 tryDiff bank-const/out.err $outtemp
 rc=$(($? || $rc))
 
@@ -111,7 +111,7 @@ for i in fragment-align/*; do
 	startTest
 	$RGBASM -o $otemp $i/a.asm
 	$RGBASM -o $gbtemp2 $i/b.asm
-	rgblink -o $gbtemp $otemp $gbtemp2 2>$outtemp
+	rgblinkQuiet -o $gbtemp $otemp $gbtemp2 2>$outtemp
 	tryDiff $i/out.err $outtemp
 	rc=$(($? || $rc))
 	if [[ -f $i/out.gb ]]; then
@@ -124,19 +124,30 @@ done
 i="high-low.asm"
 startTest
 $RGBASM -o $otemp high-low/a.asm
-rgblink -o $gbtemp $otemp
+rgblinkQuiet -o $gbtemp $otemp
 $RGBASM -o $otemp high-low/b.asm
-rgblink -o $gbtemp2 $otemp
+rgblinkQuiet -o $gbtemp2 $otemp
 tryCmp $gbtemp $gbtemp2
 rc=$(($? || $rc))
 
+i="load-fragment.asm"
+startTest
+$RGBASM -o $otemp load-fragment/a.asm
+$RGBASM -o $gbtemp2 load-fragment/b.asm
+rgblinkQuiet -o $gbtemp $otemp $gbtemp2 2>$outtemp
+tryDiff load-fragment/out.err $outtemp
+rc=$(($? || $rc))
+dd if=$gbtemp count=1 bs=$(printf %s $(wc -c < load-fragment/out.gb)) > $otemp 2>/dev/null
+tryCmp load-fragment/out.gb $otemp
+rc=$(($? || $rc))
+
 i="overlay.asm"
 startTest
 $RGBASM -o $otemp overlay/a.asm
-rgblink -o $gbtemp -t -O overlay/overlay.gb $otemp > $outtemp 2>&1
+rgblinkQuiet -o $gbtemp -t -O overlay/overlay.gb $otemp > $outtemp 2>&1
-# This test does not trim its output with 'dd' because it needs to verify the correct output size
 tryDiff overlay/out.err $outtemp
 rc=$(($? || $rc))
+# This test does not trim its output with 'dd' because it needs to verify the correct output size
 tryCmp overlay/out.gb $gbtemp
 rc=$(($? || $rc))
 
@@ -144,7 +155,7 @@ i="section-union/good.asm"
 startTest
 $RGBASM -o $otemp section-union/good/a.asm
 $RGBASM -o $gbtemp2 section-union/good/b.asm
-rgblink -o $gbtemp -l section-union/good/script.link $otemp $gbtemp2
+rgblinkQuiet -o $gbtemp -l section-union/good/script.link $otemp $gbtemp2
 dd if=$gbtemp count=1 bs=$(printf %s $(wc -c < section-union/good/ref.out.bin)) > $otemp 2>/dev/null
 tryCmp section-union/good/ref.out.bin $otemp
 rc=$(($? || $rc))
@@ -153,7 +164,7 @@ i="section-union/fragments.asm"
 startTest
 $RGBASM -o $otemp section-union/fragments/a.asm
 $RGBASM -o $gbtemp2 section-union/fragments/b.asm
-rgblink -o $gbtemp $otemp $gbtemp2
+rgblinkQuiet -o $gbtemp $otemp $gbtemp2
 dd if=$gbtemp count=1 bs=$(printf %s $(wc -c < section-union/fragments/ref.out.bin)) > $otemp 2>/dev/null
 tryCmp section-union/fragments/ref.out.bin $otemp
 rc=$(($? || $rc))
@@ -162,7 +173,7 @@ for i in section-union/*.asm; do
 	startTest
 	$RGBASM -o $otemp $i
 	$RGBASM -o $gbtemp2 $i -DSECOND
-	if rgblink $otemp $gbtemp2 2>$outtemp; then
+	if rgblinkQuiet $otemp $gbtemp2 2>$outtemp; then
 		echo -e "${bold}${red}$i didn't fail to link!${rescolors}${resbold}"
 		rc=1
 	fi