Document linkerscript format in manpage

Signed-off-by: AntonioND <antonio_nd@outlook.com>

Makefile

@@ -82,6 +82,7 @@ install: all
 	$Qinstall -m ${MANMODE} src/asm/rgbasm.1 ${MANPREFIX}/man1/rgbasm.1
 	$Qinstall -m ${MANMODE} src/fix/rgbfix.1 ${MANPREFIX}/man1/rgbfix.1
 	$Qinstall -m ${MANMODE} src/link/rgblink.1 ${MANPREFIX}/man1/rgblink.1
+	$Qinstall -m ${MANMODE} src/link/rgblink.5 ${MANPREFIX}/man1/rgblink.5
 	$Qinstall -m ${MANMODE} src/gfx/rgbgfx.1 ${MANPREFIX}/man1/rgbgfx.1
 
 rgbasm: ${rgbasm_obj}

src/link/rgblink.1

@@ -1,4 +1,4 @@
-.Dd February 26, 2015
+.Dd March 27, 2017
 .Dt RGBLINK 1
 .Os RGBDS Manual
 .Sh NAME
@@ -14,6 +14,7 @@
 .Op Fl o Ar outfile
 .Op Fl p Ar pad_value
 .Op Fl s Ar symbol
+.Op Fl l Ar linkerscript
 .Ar
 .Sh DESCRIPTION
 The
@@ -54,6 +55,14 @@ Write a tiny
 ROM file.
 This forces all ROMX sections to be of type ROM0, and increases the ROM0
 section size from 16KiB to 32KiB.
+.It Fl l Ar linkerscript
+Specify a linkerscript file that tells the linker how sections must be placed in
+the ROM.
+This file has priority over the attributes assigned in the source code, but they
+have to be consistent.
+See
+.Xr rgblink 5
+for more information about its format.
 .El
 .Sh EXAMPLES
 All you need for a basic ROM is an object file, which can be made into a ROM
@@ -70,9 +79,11 @@ to fix these so that the program will actually run in a Game Boy:
 .D1 $ rgbfix -v bar.gb
 .Sh SEE ALSO
 .Xr rgbasm 1 ,
+.Xr rgblink 5 ,
 .Xr rgbfix 1 ,
 .Xr rgbds 7
 .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.
+and was later packaged in RGBDS by Justin Lloyd. It is now maintained by a
+number of contributors at https://github.com/rednex/rgbds.

src/link/rgblink.5

@@ -0,0 +1,68 @@
+.Dd March 27, 2017
+.Dt RGBLINK 5
+.Os RGBDS Manual
+.Sh NAME
+.Nm rgblink
+.Nd linkerscript file format
+.Sh DESCRIPTION
+The linkerscript is an external file that allows the user to specify the
+order of sections without the need for doing so before assembling each object
+file.
+.Pp
+The placement of sections specified in the linkerscript is done before the
+sections whose placement is defined in the source code.
+.Pp
+A linkerscript consists on a series of banks followed by a list of sections
+and, optionally, commands.
+They can be lowercase or uppercase, it is ignored.
+Any line can contain a comment starting with
+.Ql \&;
+that ends at the end of the line:
+.Pp
+  ROMX $F ; This is a comment
+   "Functions to read array"
+   ALIGN 8
+   "Array aligned to 256 bytes"
+
+  WRAMX 2
+    "Some variables"
+.Pp
+Numbers can be in decimal or hexadecimal format (the prefix is
+.Ql $ ) .
+It is an error if any bank or command is found before setting a bank.
+.Pp
+The possible bank types are: ROM0, ROMX, VRAM, WRAM0, WRAMX, OAM and HRAM.
+Types ROMX, VRAM, WRAMX and SRAM are banked, which means that it is needed to
+specify a bank after the type.
+.Pp
+When a new bank statement is found, sections found after it will be placed
+right from the beginning of that bank.
+If the linkerscript switches to a different bank and then it comes back to the
+previous one it will continue from the last address that was used.
+.Pp
+The only two commands are ORG and ALIGN:
+.Bl -bullet
+.It
+ORG sets the address in which new sections will be placed.
+It can not be lower than the current address.
+.It
+ALIGN will increase the address until it is aligned to the specified boundary
+(it tries to set to 0 the number of bits specified after the command: ALIGN 8
+will align to $100).
+.El
+.Pp
+Note: The bank, alignment, address and type of sections can be specified both
+in the source code and in the linkerscript.
+For a section to be able to be placed with the linkerscript the bank must be
+left unassigned in the source code or be the same as the one specified in the
+linkerscript. The address and alignment musn't be set.
+.Sh SEE ALSO
+.Xr rgbasm 1 ,
+.Xr rgblink 1 ,
+.Xr rgbfix 1 ,
+.Xr rgbds 7
+.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 https://github.com/rednex/rgbds.