Clarify the linkerscript example
* Clarify the linkerscript example
* Explain that backslash escape sequences are supported
Fixes
.Sh DESCRIPTION
The linker script is an external file that allows the user to specify the order of sections at link time and in a centralized manner.
.Pp
-A linker script consists on a series of banks followed by a list of sections and, optionally, commands.
-They can be lowercase or uppercase, it is ignored.
+A linker script consists of a series of bank declarations, each optionally followed by a list of section names (in double quotes) or commands.
+All reserved keywords (bank types and command names) are case-insensitive; all section names are case-sensitive.
+.Pp
Any line can contain a comment starting with
.Ql \&;
-that ends at the end of the line:
+that ends at the end of the line.
+.Pp
.Bd -literal -offset indent
-ROMX $F ; This is a comment
- "Functions to read array"
- ALIGN 8
- "Array aligned to 256 bytes"
+; This line is a comment
+ROMX $F ; start a bank
+ "Some functions" ; a section name
+ ALIGN 8 ; a command
+ "Some array"
-WRAMX 2
+WRAMX 2 ; start another bank
+ org $d123 ; another command
"Some variables"
.Ed
.Pp
@@ -47,6 +51,19 @@ and
.Cm WRAMX ,
it is needed to specify a bank number after the type.
.Pp
+Section names in double quotes support the same character escape sequences as strings in
+.Xr rgbasm 5 ,
+specifically
+.Ql \[rs]\[rs] ,
+.Ql \[rs]" ,
+.Ql \[rs]n ,
+.Ql \[rs]r ,
+and
+.Ql \[rs]t .
+Other backslash escape sequences in
+.Xr rgbasm 5
+are only relevant to assembly code and do not apply in section names.
+.Pp
When a new bank statement is found, sections found after it will be placed right from the beginning of that bank.
If the linker script switches to a different bank and then comes back to a previous one, it will continue from the last address that was used.
.Pp
