Doc: update src/tools/pginclude/README.

Commit f62975b2a made headerscheck and cpluspluscheck a little
smarter than this documentation gave them credit for.  Make
their docs match current reality.  Also add a warning about the
layer of dust that has settled on the rest of these scripts.

Discussion: https://postgr.es/m/769950.1684797558@sss.pgh.pa.us

diff --git a/src/tools/pginclude/README b/src/tools/pginclude/README
index 49eb4b69079960110d8f4d8477b2d09ec784d15a..712eca76fb33c759e17f8bba90e2a44d3de8d0ec 100644 (file)
--- a/src/tools/pginclude/README
+++ b/src/tools/pginclude/README
@@ -1,5 +1,12 @@
 src/tools/pginclude/README
 
+NOTE: headerscheck and cpluspluscheck are in current use, and any
+problems they find should generally get fixed.  The other scripts
+in this directory have not been used in some time, and have issues.
+pgrminclude in particular has a history of creating more problems
+than it fixes.  Be very wary of applying their results blindly.
+
+
 pginclude
 =========
 
@@ -71,10 +78,10 @@ the top-level build directory after completing a build.  You should
 have included "--with-perl --with-python" in your configure options,
 else you're likely to get errors about related headers not being found.
 
-A limitation of the current script is that it doesn't know which headers
-are for frontend or backend, so it tests everything with postgres.h
-as prerequisite, even if postgres_fe.h would be more appropriate.  Also
-note that the contents of macros are not checked; this is intentional.
+A limitation of the current script is that it doesn't know exactly which
+headers are for frontend or backend; when in doubt it uses postgres.h as
+prerequisite, even if postgres_fe.h or c.h would be more appropriate.
+Also note that the contents of macros are not checked; this is intentional.
 
 
 cpluspluscheck
@@ -97,7 +104,7 @@ If you are using a non-g++-compatible C++ compiler, you may need to
 override the script's CXXFLAGS setting by setting a suitable environment
 value.
 
-A limitation of the current script is that it doesn't know which headers
-are for frontend or backend, so it tests everything with postgres.h
-as prerequisite, even if postgres_fe.h would be more appropriate.  Also
-note that the contents of macros are not checked; this is intentional.
+A limitation of the current script is that it doesn't know exactly which
+headers are for frontend or backend; when in doubt it uses postgres.h as
+prerequisite, even if postgres_fe.h or c.h would be more appropriate.
+Also note that the contents of macros are not checked; this is intentional.