From 8c0468f07ed3cc787f2fc790ed3b616bf48f01c6 Mon Sep 17 00:00:00 2001
From: Peter Kokot <peterkokot@gmail.com>
Date: Wed, 26 Mar 2025 00:35:54 +0100
Subject: [PATCH] FindCABLE: Update documentation

---
 Modules/FindCABLE.cmake | 42 ++++++++++++++++++++++++++++++-----------
 1 file changed, 31 insertions(+), 11 deletions(-)

diff --git a/Modules/FindCABLE.cmake b/Modules/FindCABLE.cmake
index 4d72897577..6e530c3a1e 100644
--- a/Modules/FindCABLE.cmake
+++ b/Modules/FindCABLE.cmake
@@ -5,23 +5,43 @@
 FindCABLE
 ---------
 
-Find CABLE
+Finds the CABLE installation and determines its include paths and libraries.
 
-This module finds if CABLE is installed and determines where the
-include files and libraries are.  This code sets the following
-variables:
+Package called CABLE (CABLE Automates Bindings for Language Extension) was
+initially developed by Kitware to generate bindings to C++ classes for use in
+interpreted languages, such as Tcl.  It worked in conjunction with packages like
+GCC-XML.  The CABLE package has since been superseded by the ITK CableSwig
+package.
 
-::
+.. note::
 
-  CABLE             the path to the cable executable
-  CABLE_TCL_LIBRARY the path to the Tcl wrapper library
-  CABLE_INCLUDE_DIR the path to the include directory
+  When building wrappers for interpreted languages, these packages are no longer
+  necessary.  The CastXML package now serves as the recommended tool for this
+  purpose and can be found directly using the :command:`find_program` command.
 
+Cache Variables
+^^^^^^^^^^^^^^^
 
+The following cache variables may be set when using this module:
 
-To build Tcl wrappers, you should add shared library and link it to
-${CABLE_TCL_LIBRARY}.  You should also add ${CABLE_INCLUDE_DIR} as an
-include directory.
+``CABLE``
+  Path to the ``cable`` executable.
+``CABLE_INCLUDE_DIR``
+  Path to the include directory.
+``CABLE_TCL_LIBRARY``
+  Path to the Tcl wrapper library.
+
+Examples
+^^^^^^^^
+
+Finding CABLE to build Tcl wrapper, by linking library and adding the include
+directories:
+
+.. code-block:: cmake
+
+  find_package(CABLE)
+  target_link_libraries(tcl_wrapper_target PRIVATE ${CABLE_TCL_LIBRARY})
+  target_include_directories(tcl_wrapper_target PRIVATE ${CABLE_INCLUDE_DIR})
 #]=======================================================================]
 
 if(NOT CABLE)