Support -P/--preinclude to pre-INCLUDE a file (#1043)

Fixes #1041

Co-authored-by: ISSOtm <eldredhabert0@gmail.com>

man/rgbasm.1

@@ -24,21 +24,21 @@
 .Op Fl MT Ar target_file
 .Op Fl MQ Ar target_file
 .Op Fl o Ar out_file
+.Op Fl P Ar include_file
 .Op Fl p Ar pad_value
 .Op Fl Q Ar fix_precision
 .Op Fl r Ar recursion_depth
 .Op Fl W Ar warning
-.Ar
+.Ar asmfile
 .Sh DESCRIPTION
 The
 .Nm
 program creates an RGB object file from an assembly source file.
 The input
-.Ar file
-can be a file path, or
+.Ar asmfile
+can be a path to a file, or
 .Cm \-
-denoting
-.Cm stdin .
+to read from standard input.
 .Pp
 Note that options can be abbreviated as long as the abbreviation is unambiguous:
 .Fl Fl verb
@@ -87,7 +87,19 @@ instruction immediately after any
 .Ic halt
 instruction.
 .It Fl i Ar path , Fl Fl include Ar path
-Add an include path.
+Add a new
+.Dq include path ; Ar path
+must point to a directory.
+When a
+.Ic INCLUDE
+.Pq including the implicit one from Fl P
+or
+.Ic INCBIN
+is attempted,
+.Nm
+first looks up the provided path from its working directory; if this fails, it tries again from each of the
+.Dq include path
+directories, in the order they were provided.
 .It Fl L , Fl Fl preserve-ld
 By default,
 .Nm
@@ -116,6 +128,7 @@ This makes
 .Nm
 assume that missing files are auto-generated: when
 .Ic INCLUDE
+.Pq including the implicit one from Fl P
 or
 .Ic INCBIN
 is attempted on a non-existent file, it is added as a dependency, then
@@ -146,6 +159,12 @@ characters, essentially
 .Sq $ .
 .It Fl o Ar out_file , Fl Fl output Ar out_file
 Write an object file to the given filename.
+.It Fl P Ar include_file , Fl Fl preinclude Ar include_file
+Pre-include a file.
+This acts as if a
+.Ql Ic INCLUDE Qq Ar include_file
+was read before the input
+.Ar asmfile .
 .It Fl p Ar pad_value , Fl Fl pad-value Ar pad_value
 When padding an image, pad with this value.
 The default is 0x00.