Implement -Wpurge= (#1443)

man/rgbasm.1

@@ -309,6 +309,18 @@ or just
 warns about strings longer than four characters, since four or fewer characters fit within a 32-bit integer.
 .Fl Wnumeric-string=2
 warns about any multi-character string.
+.It Fl Wpurge=
+Warn when purging symbols which are likely to have been necessary.
+.Fl Wpurge=0
+or
+.Fl Wno-purge
+disables this warning.
+.Fl Wpurge=1
+or just
+.Fl Wpurge
+warns when purging any exported symbol (regardless of type).
+.Fl Wpurge=2
+also warns when purging any label (even if not exported).
 .It Fl Wshift
 Warn when shifting right a negative value.
 Use a division by 2**N instead.

man/rgbasm.5

@@ -1383,16 +1383,15 @@ Note also that only exported symbols will appear in symbol and map files produce
 .Xr rgblink 1 .
 .Ss Purging symbols
 .Ic PURGE
-allows you to completely remove a symbol from the symbol table as if it had never existed.
-.Em USE WITH EXTREME CAUTION !
-I can't stress this enough,
-.Sy you seriously need to know what you are doing .
-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 variables, numeric or string constants, or macros.
+allows you to completely remove a symbol from the symbol table, as if it had never been defined.
+Be
+.Em very
+careful when purging symbols, especially labels, because it could result in unpredictable errors if something depends on the missing symbol (for example, expressions the linker needs to calculate).
 .Bd -literal -offset indent
-DEF Kamikaze EQUS  "I don't want to live anymore"
-DEF AOLer    EQUS  "Me too"
-         PURGE Kamikaze, AOLer
+DEF Kamikaze EQUS "I don't want to live anymore"
+AOLer: DB "Me too lol"
+PURGE Kamikaze, AOLer
+ASSERT !DEF(Kamikaze) && !DEF(AOLer)
 .Ed
 .Pp
 String constants are not expanded within the symbol names.