Implement ? suffix to "quiet" a context and exclude it from backtraces (#1800)

man/rgbasm.1

@@ -9,7 +9,7 @@
 .Sh SYNOPSIS
 .Nm
 .Op Fl EhVvw
-.Op Fl B Ar depth
+.Op Fl B Ar param
 .Op Fl b Ar chars
 .Op Fl \-color Ar when
 .Op Fl D Ar name Ns Op = Ns Ar value
@@ -53,15 +53,29 @@ is invalid because it could also be
 .Fl \-version .
 The arguments are as follows:
 .Bl -tag -width Ds
-.It Fl B Ar depth , Fl \-backtrace Ar depth
-Specifies the maximum depth for which
-.Nm
-will print location backtraces for warnings or errors.
-Deeper backtraces than that will be abbreviated.
-.Fl B Ar 0
-allows unlimited-depth backtraces.
-.Fl B Ar collapse
-will print the entire location trace on one line.
+.It Fl B Ar param , Fl \-backtrace Ar param
+Configures how location backtraces are printed if warnings or errors occur.
+This flag may be specified multiple times with different parameters that combine meaningfully.
+If
+.Ar param
+is a positive number, it specifies the maximum backtrace depth, abbreviating deeper ones.
+Other valid parameter values are the following:
+.Bl -tag -width Ds
+.It Cm 0
+Do not limit the maximum backtrace depth; this is the default.
+.It Cm all
+Force all locations to be printed, even "quiet" ones (see
+.Dq Excluding locations from backtraces
+in
+.Xr rgbasm 5
+for details).
+.It Cm no-all
+Do not print "quieted" locations in backtraces; this is the default.
+.It Cm collapse
+Print all locations on one line.
+.It Cm no-collapse
+Print one location per line; this is the default.
+.El
 .It Fl b Ar chars , Fl \-binary-digits Ar chars
 Allow two characters to be used for binary constants in addition to the default
 .Sq 0

man/rgbasm.5

@@ -1681,7 +1681,8 @@ $ rgbasm -o a.o a.asm
 $ rgbasm -o b.o b.asm
 $ rgbasm -o c.o c.asm
 $ rgblink a.o b.o c.o
-error: c.asm(2): Unknown symbol "LabelA"
+error: Undefined symbol "LabelA"
+    at c.asm(2)
 Linking failed with 1 error
 .Ed
 .Pp
@@ -2516,6 +2517,68 @@ PUSHO b.X, g.oOX
     DW `..ooOOXX
 POPO
 .Ed
+.Ss Excluding locations from backtraces
+Errors and warnings print
+.Em backtraces
+showing the location in the source file where the problem occurred, tracing the origin of the problem even through a chain of
+.Ic REPT ,
+.Ic FOR ,
+.Ic MACRO ,
+and
+.Ic INCLUDE
+locations.
+Sometimes there are locations you would like to ignore; for example, a common utility macro when you only care about the line where the macro is used, or an
+.Ic INCLUDE
+file that only serves to include other files and is just filler in the backtrace.
+.Pp
+In those cases, you can
+.Em silence
+a location with a question mark
+.Sq \&?
+after the token: all of the locations created by a
+.Sq REPT? ,
+.Sq FOR? ,
+or
+.Sq MACRO?
+will not be printed, and any location created by a
+.Sq INCLUDE? ,
+or a macro invocation whose name is immediately followed by a
+.Sq \&? ,
+will not be printed.
+For example, if this were assembled as
+.Ql example.asm :
+.Bd -literal -offset indent
+MACRO lb
+    assert -128 <= (\e2) && (\e2) < 256, "\e2 is not a byte"
+    assert -128 <= (\e3) && (\e3) < 256, "\e3 is not a byte"
+    ld \e1, (LOW(\e2) << 8) | LOW(\e3)
+ENDM
+SECTION "Code", ROM0
+    lb hl, $123, $45
+.Ed
+.Pp
+This would print an error backtrace:
+.Bd -literal -offset indent
+error: Assertion failed: $123 is not a byte
+    at example.asm::lb(2)
+    <- example.asm(7)
+.Ed
+.Pp
+But if
+.Ql MACRO
+were changed to
+.Ql MACRO? ,
+or
+.Ql lb hl
+were changed to
+.Ql lb? hl ,
+then the error backtrace would not mention the location within the
+.Ql lb
+macro:
+.Bd -literal -offset indent
+error: Assertion failed: $123 is not a byte
+    at example.asm(7)
+.Ed
 .Sh SEE ALSO
 .Xr rgbasm 1 ,
 .Xr rgblink 1 ,

man/rgbds.5

@@ -79,12 +79,16 @@ order, meaning the node with ID 0 is the last one in the list!
 .It Cm LONG Ar ParentLineNo
 Line at which the parent node's context was exited; meaningless for the root node.
 .It Cm BYTE Ar Type
+Bits 0\(en6 indicate the node's type:
 .Bl -column "Value" -compact
 .It Sy Value Ta Sy Meaning
 .It 0 Ta REPT node
 .It 1 Ta File node
 .It 2 Ta Macro node
 .El
+.Pp
+Bit\ 7 being set means that the node is "quieted"
+.Pq see Do Excluding locations from backtraces Dc in Xr rgbasm 5 .
 .It Cm IF Ar Type No \(!= 0
 If the node is not a REPT node...
 .Pp

man/rgblink.1

@@ -9,7 +9,7 @@
 .Sh SYNOPSIS
 .Nm
 .Op Fl dhMtVvwx
-.Op Fl B Ar depth
+.Op Fl B Ar param
 .Op Fl \-color Ar when
 .Op Fl l Ar linker_script
 .Op Fl m Ar map_file
@@ -65,15 +65,29 @@ is invalid because it could also be
 .Fl \-version .
 The arguments are as follows:
 .Bl -tag -width Ds
-.It Fl B Ar depth , Fl \-backtrace Ar depth
-Specifies the maximum depth for which
-.Nm
-will print location backtraces for warnings or errors.
-Deeper backtraces than that will be abbreviated.
-.Fl B Ar 0
-allows unlimited-depth backtraces.
-.Fl B Ar collapse
-will print the entire location trace on one line.
+.It Fl B Ar param , Fl \-backtrace Ar param
+Configures how location backtraces are printed if warnings or errors occur.
+This flag may be specified multiple times with different parameters that combine meaningfully.
+If
+.Ar param
+is a positive number, it specifies the maximum backtrace depth, abbreviating deeper ones.
+Other valid parameter values are the following:
+.Bl -tag -width Ds
+.It Cm 0
+Do not limit the maximum backtrace depth; this is the default.
+.It Cm all
+Force all locations to be printed, even "quiet" ones (see
+.Dq Excluding locations from backtraces
+in
+.Xr rgbasm 5
+for details).
+.It Cm no-all
+Do not print "quieted" locations in backtraces; this is the default.
+.It Cm collapse
+Print all locations on one line.
+.It Cm no-collapse
+Print one location per line; this is the default.
+.El
 .It Fl \-color Ar when
 Specify when to highlight warning and error messages with color:
 .Ql always ,