git: 7344bc6cb7b4 - stable/13 - Rework documentation of OLD_*.

The branch stable/13 has been updated by jhb:

URL: https://cgit.FreeBSD.org/src/commit/?id=7344bc6cb7b45874bac85df67dd663cd5ffd81de

commit 7344bc6cb7b45874bac85df67dd663cd5ffd81de
Author:     John Baldwin <jhb@FreeBSD.org>
AuthorDate: 2022-01-20 20:46:29 +0000
Commit:     John Baldwin <jhb@FreeBSD.org>
CommitDate: 2022-07-13 15:34:26 +0000

    Rework documentation of OLD_*.
    
    - Be more explicit in the difference between OLD_DIRS and OLD_FILES
      (the former is only in delete-old-libs whereas the latter is in
      delete-old).
    
    - Document that debug symbols in /usr/lib/debug/ for files in
      OLD_FILES and OLD_LIBS are removed as well.
    
    Reviewed by:    emaste
    Sponsored by:   The University of Cambridge, Google Inc.
    Differential Revision:  https://reviews.freebsd.org/D33847
    
    (cherry picked from commit c96dfb2156fa8a83dd225d1a9b31070123469288)
---
 ObsoleteFiles.inc                        | 19 +++++++++++++------
 tools/build/mk/OptionalObsoleteFiles.inc |  4 ++--
 2 files changed, 15 insertions(+), 8 deletions(-)

diff --git a/ObsoleteFiles.inc b/ObsoleteFiles.inc
index 840aa8743dba..11269e9358b9 100644
--- a/ObsoleteFiles.inc
+++ b/ObsoleteFiles.inc
@@ -2,17 +2,24 @@
 # $FreeBSD$
 #
 # This file lists old files (OLD_FILES), libraries (OLD_LIBS) and
-# directories (OLD_DIRS) which should get removed at an update. Recently
-# removed entries first (with the date as a comment). Dynamic libraries are
-# special cased (OLD_LIBS). Static libraries or the generic links to
-# the dynamic libraries (lib*.so) should (if you don't know why to make an
-# exception, make this a "must") be viewed as normal files (OLD_FILES).
+# directories (OLD_DIRS) which should get removed after an update.
+# Recently removed entries should be listed first (with the date as a
+# comment). OLD_LIBS should only list dynamic libraries. Static libraries,
+# links to dynamic libraries (lib*.so), and linker scripts should be listed
+# in OLD_FILES. OLD_LIBS are removed by the delete-old-libs target, whereas
+# OLD_FILES and OLD_DIRS are removed by the delete-old target. This
+# separation allows users to avoid deleting old dynamic libraries still
+# required by existing binaries.
+#
+# For files listed in OLD_FILES and OLD_LIBS, the check-old* and
+# delete-old* targets will also delete associated debug symbols from
+# usr/lib/debug.
 #
 # In case of a complete directory hierarchy the sorting is in depth first
 # order.
 #
 # Files that are installed or removed depending on some build option
-# are to be listed in /usr/src/tools/build/mk/OptionalObsoleteFiles.inc
+# should be listed in /usr/src/tools/build/mk/OptionalObsoleteFiles.inc
 # instead of in this file.
 #
 # Before you commit changes to this file please check if any entries in
diff --git a/tools/build/mk/OptionalObsoleteFiles.inc b/tools/build/mk/OptionalObsoleteFiles.inc
index d7cdbec9cb87..fb5eed3fffbc 100644
--- a/tools/build/mk/OptionalObsoleteFiles.inc
+++ b/tools/build/mk/OptionalObsoleteFiles.inc
@@ -1,8 +1,8 @@
 #
 # $FreeBSD$
 #
-# This file add support for the WITHOUT_* and WITH_* knobs in src.conf(5) to
-# the check-old and delete-old* targets.
+# This file adds support for the WITHOUT_* and WITH_* knobs in src.conf(5) to
+# the check-old* and delete-old* targets.
 #
 
 .if ${MK_ACCT} == no