Findosg*: Update documentation

- Modules documentation updated and synced.
- Internal comments about headers moved to the modules introduction
  section.
- Added examples sections.
- Used the `<PackageName>_FOUND` variables (CMake 3.3). The uppercased
  `<PACKAGENAME>_FOUND` are also set to the same value.
- Mention of CMake 2.6.3 removed as these version notes are now being
  cleaned in the CMake 4 documentation (CMake docs are at this point
  considering the 2.8.12.2 as the initial state upon which new and
  changed items are documented through versions).
- Added notes that these modules are not intended anymore to be used
  directly except for advanced case scenarios. The FindOpenSceneGraph
  module should be used.
- Fixed osgQt description in FindOpenSceneGraph and synced it a bit.

Modules/FindOpenSceneGraph.cmake

@@ -21,6 +21,7 @@ When working with OpenSceneGraph, its core library headers are intended to be
 included in C++ project source code as:
 
 .. code-block:: c++
+  :caption: ``example.cxx``
 
   #include <osg/PositionAttitudeTransform>
 
@@ -28,6 +29,7 @@ Headers for the OpenSceneGraph libraries and NodeKits follow a similar inclusion
 structure, for example:
 
 .. code-block:: c++
+  :caption: ``example.cxx``
 
   #include <osgAnimation/Animation>
   #include <osgDB/DatabasePager>
@@ -105,11 +107,11 @@ Supported components include:
     toolkit 1.x, and has been superseded by the osgViewer library.
 
 ``osgQt``
-  Finds the osgQt NodeKit, which provides various classes to aid the integration
-  of Qt.
+  Finds the osgQt utility library, which provides various classes to aid the
+  integration of Qt.
 
   .. note::
-    As of OpenSceneGraph version 3.6, this NodeKit has been moved to its own
+    As of OpenSceneGraph version 3.6, this library has been moved to its own
     repository.
 
 ``osgShadow``
@@ -216,9 +218,9 @@ that encapsulates its usage requirements for linking to a project target:
     )
   endif()
 
-  add_executable(foo foo.cc)
+  add_executable(example example.cxx)
 
-  target_link_libraries(foo PRIVATE OpenSceneGraph::OpenSceneGraph)
+  target_link_libraries(example PRIVATE OpenSceneGraph::OpenSceneGraph)
 
 See Also
 ^^^^^^^^

Modules/FindOpenThreads.cmake

@@ -7,8 +7,12 @@ FindOpenThreads
 
 Finds the OpenThreads C++ based threading library.
 
-OpenThreads header files are intended to be included as
-``#include <OpenThreads/Thread>``.
+OpenThreads header files are intended to be included as:
+
+.. code-block:: c++
+  :caption: ``example.cxx``
+
+  #include <OpenThreads/Thread>
 
 Result Variables
 ^^^^^^^^^^^^^^^^
@@ -84,7 +88,7 @@ project target:
     )
   endif()
 
-  target_link_libraries(project_target PRIVATE OpenThreads::OpenThreads)
+  target_link_libraries(example PRIVATE OpenThreads::OpenThreads)
 #]=======================================================================]
 
 include(${CMAKE_CURRENT_LIST_DIR}/SelectLibraryConfigurations.cmake)

Modules/FindProducer.cmake

@@ -21,6 +21,7 @@ Producer library headers are intended to be included in C++ project source code
 as:
 
 .. code-block:: c++
+  :caption: ``example.cxx``
 
   #include <Producer/CameraGroup>
 
@@ -88,7 +89,7 @@ project target:
     )
   endif()
 
-  target_link_libraries(project_target PRIVATE Producer::Producer)
+  target_link_libraries(example PRIVATE Producer::Producer)
 #]=======================================================================]
 
 # Try the user's environment request before anything else.

Modules/Findosg.cmake

@@ -5,49 +5,107 @@
 Findosg
 -------
 
-
+Finds the core OpenSceneGraph osg library (``libosg``).
 
 .. note::
-  It is highly recommended that you use the new
-  :module:`FindOpenSceneGraph` introduced in CMake 2.6.3 and not use this
-  Find module directly.
-
-This is part of the ``Findosg*`` suite used to find OpenSceneGraph
-components.  Each component is separate and you must opt in to each
-module.  You must also opt into OpenGL and OpenThreads (and Producer
-if needed) as these modules won't do it for you.  This is to allow you
-control over your own system piece by piece in case you need to opt
-out of certain components or change the Find behavior for a particular
-module (perhaps because the default :module:`FindOpenGL` module doesn't
-work with your system as an example).  If you want to use a more
-convenient module that includes everything, use the
-:module:`FindOpenSceneGraph` instead of the ``Findosg*.cmake`` modules.
-
-Locate osg This module defines:
-
-``OSG_FOUND``
-  Was the Osg found?
-``OSG_INCLUDE_DIR``
-  Where to find theheaders
+
+  In most cases, it's recommended to use the :module:`FindOpenSceneGraph` module
+  instead, which automatically finds the osg core library along with its
+  required dependencies like OpenThreads:
+
+  .. code-block:: cmake
+
+    find_package(OpenSceneGraph)
+
+This module is used internally by :module:`FindOpenSceneGraph` to find the osg
+library.  It is not intended to be included directly during typical use of the
+:command:`find_package` command.  However, it is available as a standalone
+module for advanced use cases where finer control over detection is needed, such
+as explicitly finding osg library or bypassing automatic component detection:
+
+.. code-block:: cmake
+
+  find_package(osg)
+
+OpenSceneGraph core library headers are intended to be included in C++ project
+source code as:
+
+.. code-block:: c++
+  :caption: ``example.cxx``
+
+  #include <osg/PositionAttitudeTransform>
+
+When working with the OpenSceneGraph toolkit, other libraries such as OpenGL may
+also be required.
+
+Result Variables
+^^^^^^^^^^^^^^^^
+
+This module defines the following variables:
+
+``osg_FOUND``
+  Boolean indicating whether osg library is found.  For backward
+  compatibility, the ``OSG_FOUND`` variable is also set to the same value.
+
 ``OSG_LIBRARIES``
-  The libraries to link against for the OSG (use this)
+  The libraries needed to link against to use osg library.
+
 ``OSG_LIBRARY``
-  The OSG library
+  A result variable that is set to the same value as the ``OSG_LIBRARIES``
+  variable.
+
+Cache Variables
+^^^^^^^^^^^^^^^
+
+The following cache variables may also be set:
+
+``OSG_INCLUDE_DIR``
+  The include directory containing headers needed to use osg library.
+
 ``OSG_LIBRARY_DEBUG``
-  The OSG debug library
+  The path to the osg debug library.
+
+Hints
+^^^^^
+
+This module accepts the following variables:
+
+``OSGDIR``
+  Environment variable that can be set to help locate the OpenSceneGraph
+  toolkit, including its osg library, when installed in a custom
+  location.  It should point to the OpenSceneGraph installation prefix used when
+  it was configured, built, and installed: ``./configure --prefix=$OSGDIR``.
+
+Examples
+^^^^^^^^
+
+Finding the osg library explicitly with this module and creating an interface
+:ref:`imported target <Imported Targets>` that encapsulates its usage
+requirements for linking it to a project target:
+
+.. code-block:: cmake
+
+  find_package(osg)
 
-``$OSGDIR`` is an environment variable that would correspond to::
+  if(osg_FOUND AND NOT TARGET osg::osg)
+    add_library(osg::osg INTERFACE IMPORTED)
+    set_target_properties(
+      osg::osg
+      PROPERTIES
+        INTERFACE_INCLUDE_DIRECTORIES "${OSG_INCLUDE_DIR}"
+        INTERFACE_LINK_LIBRARIES "${OSG_LIBRARIES}"
+    )
+  endif()
 
-  ./configure --prefix=$OSGDIR
+  target_link_libraries(example PRIVATE osg::osg)
 
-used in building osg.
+See Also
+^^^^^^^^
 
-Created by Eric Wing.
+* The :module:`FindOpenSceneGraph` module to find OpenSceneGraph toolkit.
 #]=======================================================================]
 
-# Header files are presumed to be included like
-# #include <osg/PositionAttitudeTransform>
-# #include <osgUtil/SceneView>
+# Created by Eric Wing.
 
 include(${CMAKE_CURRENT_LIST_DIR}/Findosg_functions.cmake)
 OSG_FIND_PATH   (OSG osg/PositionAttitudeTransform)

Modules/FindosgAnimation.cmake

@@ -5,43 +5,111 @@
 FindosgAnimation
 ----------------
 
+Finds the osgAnimation library from the OpenSceneGraph toolkit.
 
+.. note::
 
-This is part of the ``Findosg*`` suite used to find OpenSceneGraph
-components.  Each component is separate and you must opt in to each
-module.  You must also opt into OpenGL and OpenThreads (and Producer
-if needed) as these modules won't do it for you.  This is to allow you
-control over your own system piece by piece in case you need to opt
-out of certain components or change the Find behavior for a particular
-module (perhaps because the default :module:`FindOpenGL` module doesn't
-work with your system as an example).  If you want to use a more
-convenient module that includes everything, use the
-:module:`FindOpenSceneGraph` instead of the ``Findosg*.cmake`` modules.
+  In most cases, it's recommended to use the :module:`FindOpenSceneGraph` module
+  instead and list osgAnimation as a component.  This will automatically handle
+  dependencies such as the OpenThreads and core osg libraries:
 
-Locate osgAnimation This module defines:
+  .. code-block:: cmake
+
+    find_package(OpenSceneGraph COMPONENTS osgAnimation)
+
+This module is used internally by :module:`FindOpenSceneGraph` to find the
+osgAnimation library.  It is not intended to be included directly during typical
+use of the :command:`find_package` command.  However, it is available as a
+standalone module for advanced use cases where finer control over detection is
+needed.  For example, to find the osgAnimation explicitly or bypass automatic
+component detection:
+
+.. code-block:: cmake
+
+  find_package(osgAnimation)
+
+OpenSceneGraph and osgAnimation headers are intended to be included in C++
+project source code as:
+
+.. code-block:: c++
+  :caption: ``example.cxx``
+
+  #include <osg/PositionAttitudeTransform>
+  #include <osgAnimation/Animation>
+  // ...
+
+When working with the OpenSceneGraph toolkit, other libraries such as OpenGL may
+also be required.
+
+Result Variables
+^^^^^^^^^^^^^^^^
+
+This module defines the following variables:
+
+``osgAnimation_FOUND``
+  Boolean indicating whether the osgAnimation library of the OpenSceneGraph
+  toolkit is found.  For backward compatibility, the ``OSGANIMATION_FOUND``
+  variable is also set to the same value.
 
-``OSGANIMATION_FOUND``
-  Was osgAnimation found?
-``OSGANIMATION_INCLUDE_DIR``
-  Where to find the headers
 ``OSGANIMATION_LIBRARIES``
-  The libraries to link against for the OSG (use this)
+  The libraries needed to link against to use osgAnimation.
+
 ``OSGANIMATION_LIBRARY``
-  The OSG library
+  A result variable that is set to the same value as the
+  ``OSGANIMATION_LIBRARIES`` variable.
+
+Cache Variables
+^^^^^^^^^^^^^^^
+
+The following cache variables may also be set:
+
+``OSGANIMATION_INCLUDE_DIR``
+  The include directory containing headers needed to use osgAnimation.
+
 ``OSGANIMATION_LIBRARY_DEBUG``
-  The OSG debug library
+  The path to the osgAnimation debug library.
+
+Hints
+^^^^^
+
+This module accepts the following variables:
+
+``OSGDIR``
+  Environment variable that can be set to help locate the OpenSceneGraph
+  toolkit, including its osgAnimation library, when installed in a custom
+  location.  It should point to the OpenSceneGraph installation prefix used when
+  it was configured, built, and installed: ``./configure --prefix=$OSGDIR``.
+
+Examples
+^^^^^^^^
+
+Finding the osgAnimation library explicitly with this module and creating an
+interface :ref:`imported target <Imported Targets>` that encapsulates its usage
+requirements for linking it to a project target:
+
+.. code-block:: cmake
+
+  find_package(osgAnimation)
+
+  if(osgAnimation_FOUND AND NOT TARGET osgAnimation::osgAnimation)
+    add_library(osgAnimation::osgAnimation INTERFACE IMPORTED)
+    set_target_properties(
+      osgAnimation::osgAnimation
+      PROPERTIES
+        INTERFACE_INCLUDE_DIRECTORIES "${OSGANIMATION_INCLUDE_DIR}"
+        INTERFACE_LINK_LIBRARIES "${OSGANIMATION_LIBRARIES}"
+    )
+  endif()
 
-``$OSGDIR`` is an environment variable that would correspond to::
+  target_link_libraries(example PRIVATE osgAnimation::osgAnimation)
 
-  ./configure --prefix=$OSGDIR
+See Also
+^^^^^^^^
 
-used in building osg.
-Created by Eric Wing.
+* The :module:`FindOpenSceneGraph` module to find OpenSceneGraph toolkit.
 #]=======================================================================]
 
-# Header files are presumed to be included like
-# #include <osg/PositionAttitudeTransform>
-# #include <osgAnimation/Animation>
+# Created by Eric Wing.
 
 include(${CMAKE_CURRENT_LIST_DIR}/Findosg_functions.cmake)
 OSG_FIND_PATH   (OSGANIMATION osgAnimation/Animation)

Modules/FindosgDB.cmake

@@ -5,47 +5,109 @@
 FindosgDB
 ---------
 
+Finds the osgDB library from the OpenSceneGraph toolkit.
 
+.. note::
 
-This is part of the ``Findosg*`` suite used to find OpenSceneGraph
-components.  Each component is separate and you must opt in to each
-module.  You must also opt into OpenGL and OpenThreads (and Producer
-if needed) as these modules won't do it for you.  This is to allow you
-control over your own system piece by piece in case you need to opt
-out of certain components or change the Find behavior for a particular
-module (perhaps because the default :module:`FindOpenGL` module doesn't
-work with your system as an example).  If you want to use a more
-convenient module that includes everything, use the
-:module:`FindOpenSceneGraph` instead of the ``Findosg*.cmake`` modules.
+  In most cases, it's recommended to use the :module:`FindOpenSceneGraph` module
+  instead and list osgDB as a component.  This will automatically handle
+  dependencies such as the OpenThreads and core osg libraries:
 
-Locate osgDB This module defines:
+  .. code-block:: cmake
 
-``OSGDB_FOUND``
-  Was osgDB found?
+    find_package(OpenSceneGraph COMPONENTS osgDB)
 
-``OSGDB_INCLUDE_DIR``
-  Where to find the headers
+This module is used internally by :module:`FindOpenSceneGraph` to find the
+osgDB library.  It is not intended to be included directly during typical
+use of the :command:`find_package` command.  However, it is available as a
+standalone module for advanced use cases where finer control over detection is
+needed.  For example, to find the osgDB explicitly or bypass automatic
+component detection:
+
+.. code-block:: cmake
+
+  find_package(osgDB)
+
+OpenSceneGraph and osgDB headers are intended to be included in C++ project
+source code as:
+
+.. code-block:: c++
+  :caption: ``example.cxx``
+
+  #include <osg/PositionAttitudeTransform>
+  #include <osgDB/DatabasePager>
+  // ...
+
+When working with the OpenSceneGraph toolkit, other libraries such as OpenGL may
+also be required.
+
+Result Variables
+^^^^^^^^^^^^^^^^
+
+This module defines the following variables:
+
+``osgDB_FOUND``
+  Boolean indicating whether the osgDB library of the OpenSceneGraph toolkit is
+  found.  For backward compatibility, the ``OSGDB_FOUND`` variable is also set
+  to the same value.
 
 ``OSGDB_LIBRARIES``
-  The libraries to link against for the osgDB
+  The libraries needed to link against to use osgDB.
 
 ``OSGDB_LIBRARY``
-  The osgDB library
+  A result variable that is set to the same value as the ``OSGDB_LIBRARIES``
+  variable.
+
+Cache Variables
+^^^^^^^^^^^^^^^
+
+The following cache variables may also be set:
+
+``OSGDB_INCLUDE_DIR``
+  The include directory containing headers needed to use osgDB.
 
 ``OSGDB_LIBRARY_DEBUG``
-  The osgDB debug library
+  The path to the osgDB debug library.
 
-``$OSGDIR`` is an environment variable that would correspond to::
+Hints
+^^^^^
 
-  ./configure --prefix=$OSGDIR
+This module accepts the following variables:
 
-used in building osg.
+``OSGDIR``
+  Environment variable that can be set to help locate the OpenSceneGraph
+  toolkit, including its osgDB library, when installed in a custom
+  location.  It should point to the OpenSceneGraph installation prefix used when
+  it was configured, built, and installed: ``./configure --prefix=$OSGDIR``.
 
-#]=======================================================================]
+Examples
+^^^^^^^^
+
+Finding osgDB explicitly with this module and creating an interface
+:ref:`imported target <Imported Targets>` that encapsulates its usage
+requirements for linking it to a project target:
+
+.. code-block:: cmake
 
-# Header files are presumed to be included like
-# #include <osg/PositionAttitudeTransform>
-# #include <osgDB/DatabasePager>
+  find_package(osgDB)
+
+  if(osgDB_FOUND AND NOT TARGET osgDB::osgDB)
+    add_library(osgDB::osgDB INTERFACE IMPORTED)
+    set_target_properties(
+      osgDB::osgDB
+      PROPERTIES
+        INTERFACE_INCLUDE_DIRECTORIES "${OSGDB_INCLUDE_DIR}"
+        INTERFACE_LINK_LIBRARIES "${OSGDB_LIBRARIES}"
+    )
+  endif()
+
+  target_link_libraries(example PRIVATE osgDB::osgDB)
+
+See Also
+^^^^^^^^
+
+* The :module:`FindOpenSceneGraph` module to find OpenSceneGraph toolkit.
+#]=======================================================================]
 
 include(${CMAKE_CURRENT_LIST_DIR}/Findosg_functions.cmake)
 OSG_FIND_PATH   (OSGDB osgDB/DatabasePager)

Modules/FindosgFX.cmake

@@ -5,44 +5,111 @@
 FindosgFX
 ---------
 
+Finds the osgFX NodeKit from the OpenSceneGraph toolkit.
 
+.. note::
 
-This is part of the ``Findosg*`` suite used to find OpenSceneGraph
-components.  Each component is separate and you must opt in to each
-module.  You must also opt into OpenGL and OpenThreads (and Producer
-if needed) as these modules won't do it for you.  This is to allow you
-control over your own system piece by piece in case you need to opt
-out of certain components or change the Find behavior for a particular
-module (perhaps because the default :module:`FindOpenGL` module doesn't
-work with your system as an example).  If you want to use a more
-convenient module that includes everything, use the
-:module:`FindOpenSceneGraph` instead of the ``Findosg*.cmake`` modules.
+  In most cases, it's recommended to use the :module:`FindOpenSceneGraph` module
+  instead and list osgFX as a component.  This will automatically handle
+  dependencies such as the OpenThreads and core osg libraries:
 
-Locate osgFX This module defines:
+  .. code-block:: cmake
+
+    find_package(OpenSceneGraph COMPONENTS osgFX)
+
+This module is used internally by :module:`FindOpenSceneGraph` to find the
+osgFX NodeKit.  It is not intended to be included directly during typical
+use of the :command:`find_package` command.  However, it is available as a
+standalone module for advanced use cases where finer control over detection is
+needed.  For example, to find the osgFX explicitly or bypass automatic
+component detection:
+
+.. code-block:: cmake
+
+  find_package(osgFX)
+
+OpenSceneGraph and osgFX headers are intended to be included in C++ project
+source code as:
+
+.. code-block:: c++
+  :caption: ``example.cxx``
+
+  #include <osg/PositionAttitudeTransform>
+  #include <osgFX/BumpMapping>
+  // ...
+
+When working with the OpenSceneGraph toolkit, other libraries such as OpenGL may
+also be required.
+
+Result Variables
+^^^^^^^^^^^^^^^^
+
+This module defines the following variables:
+
+``osgFX_FOUND``
+  Boolean indicating whether the osgFX NodeKit of the OpenSceneGraph toolkit
+  is found.  For backward compatibility, the ``OSGFX_FOUND`` variable is also
+  set to the same value.
 
-``OSGFX_FOUND``
-  Was osgFX found?
-``OSGFX_INCLUDE_DIR``
-  Where to find the headers
 ``OSGFX_LIBRARIES``
-  The libraries to link against for the osgFX (use this)
+  The libraries needed to link against to use osgFX.
+
 ``OSGFX_LIBRARY``
-  The osgFX library
+  A result variable that is set to the same value as the ``OSGFX_LIBRARIES``
+  variable.
+
+Cache Variables
+^^^^^^^^^^^^^^^
+
+The following cache variables may also be set:
+
+``OSGFX_INCLUDE_DIR``
+  The include directory containing headers needed to use osgFX.
+
 ``OSGFX_LIBRARY_DEBUG``
-  The osgFX debug library
+  The path to the osgFX debug library.
+
+Hints
+^^^^^
+
+This module accepts the following variables:
+
+``OSGDIR``
+  Environment variable that can be set to help locate the OpenSceneGraph
+  toolkit, including its osgFX NodeKit, when installed in a custom
+  location.  It should point to the OpenSceneGraph installation prefix used when
+  it was configured, built, and installed: ``./configure --prefix=$OSGDIR``.
+
+Examples
+^^^^^^^^
+
+Finding osgFX explicitly with this module and creating an interface
+:ref:`imported target <Imported Targets>` that encapsulates its usage
+requirements for linking it to a project target:
+
+.. code-block:: cmake
+
+  find_package(osgFX)
 
-``$OSGDIR`` is an environment variable that would correspond to::
+  if(osgFX_FOUND AND NOT TARGET osgFX::osgFX)
+    add_library(osgFX::osgFX INTERFACE IMPORTED)
+    set_target_properties(
+      osgFX::osgFX
+      PROPERTIES
+        INTERFACE_INCLUDE_DIRECTORIES "${OSGFX_INCLUDE_DIR}"
+        INTERFACE_LINK_LIBRARIES "${OSGFX_LIBRARIES}"
+    )
+  endif()
 
-  ./configure --prefix=$OSGDIR
+  target_link_libraries(example PRIVATE osgFX::osgFX)
 
-used in building osg.
+See Also
+^^^^^^^^
 
-Created by Eric Wing.
+* The :module:`FindOpenSceneGraph` module to find OpenSceneGraph toolkit.
 #]=======================================================================]
 
-# Header files are presumed to be included like
-# #include <osg/PositionAttitudeTransform>
-# #include <osgFX/BumpMapping>
+# Created by Eric Wing.
 
 include(${CMAKE_CURRENT_LIST_DIR}/Findosg_functions.cmake)
 OSG_FIND_PATH   (OSGFX osgFX/BumpMapping)

Modules/FindosgGA.cmake

@@ -5,44 +5,111 @@
 FindosgGA
 ---------
 
+Finds the osgGA library from the OpenSceneGraph toolkit.
 
+.. note::
 
-This is part of the ``Findosg*`` suite used to find OpenSceneGraph
-components.  Each component is separate and you must opt in to each
-module.  You must also opt into OpenGL and OpenThreads (and Producer
-if needed) as these modules won't do it for you.  This is to allow you
-control over your own system piece by piece in case you need to opt
-out of certain components or change the Find behavior for a particular
-module (perhaps because the default :module:`FindOpenGL` module doesn't
-work with your system as an example).  If you want to use a more
-convenient module that includes everything, use the
-:module:`FindOpenSceneGraph` instead of the ``Findosg*.cmake`` modules.
+  In most cases, it's recommended to use the :module:`FindOpenSceneGraph` module
+  instead and list osgGA as a component.  This will automatically handle
+  dependencies such as the OpenThreads and core osg libraries:
 
-Locate osgGA This module defines:
+  .. code-block:: cmake
+
+    find_package(OpenSceneGraph COMPONENTS osgGA)
+
+This module is used internally by :module:`FindOpenSceneGraph` to find the
+osgGA library.  It is not intended to be included directly during typical
+use of the :command:`find_package` command.  However, it is available as a
+standalone module for advanced use cases where finer control over detection is
+needed.  For example, to find the osgGA explicitly or bypass automatic
+component detection:
+
+.. code-block:: cmake
+
+  find_package(osgGA)
+
+OpenSceneGraph and osgGA headers are intended to be included in C++ project
+source code as:
+
+.. code-block:: c++
+  :caption: ``example.cxx``
+
+  #include <osg/PositionAttitudeTransform>
+  #include <osgGA/FlightManipulator>
+  // ...
+
+When working with the OpenSceneGraph toolkit, other libraries such as OpenGL may
+also be required.
+
+Result Variables
+^^^^^^^^^^^^^^^^
+
+This module defines the following variables:
+
+``osgGA_FOUND``
+  Boolean indicating whether the osgGA library of the OpenSceneGraph toolkit
+  is found.  For backward compatibility, the ``OSGGA_FOUND`` variable is also
+  set to the same value.
 
-``OSGGA_FOUND``
-  Was osgGA found?
-``OSGGA_INCLUDE_DIR``
-  Where to find the headers
 ``OSGGA_LIBRARIES``
-  The libraries to link against for the osgGA (use this)
+  The libraries needed to link against to use osgGA.
+
 ``OSGGA_LIBRARY``
-  The osgGA library
+  A result variable that is set to the same value as the ``OSGGA_LIBRARIES``
+  variable.
+
+Cache Variables
+^^^^^^^^^^^^^^^
+
+The following cache variables may also be set:
+
+``OSGGA_INCLUDE_DIR``
+  The include directory containing headers needed to use osgGA.
+
 ``OSGGA_LIBRARY_DEBUG``
-  The osgGA debug library
+  The path to the osgGA debug library.
+
+Hints
+^^^^^
+
+This module accepts the following variables:
+
+``OSGDIR``
+  Environment variable that can be set to help locate the OpenSceneGraph
+  toolkit, including its osgGA library, when installed in a custom
+  location.  It should point to the OpenSceneGraph installation prefix used when
+  it was configured, built, and installed: ``./configure --prefix=$OSGDIR``.
+
+Examples
+^^^^^^^^
+
+Finding osgGA explicitly with this module and creating an interface
+:ref:`imported target <Imported Targets>` that encapsulates its usage
+requirements for linking it to a project target:
+
+.. code-block:: cmake
+
+  find_package(osgGA)
 
-``$OSGDIR`` is an environment variable that would correspond to::
+  if(osgGA_FOUND AND NOT TARGET osgGA::osgGA)
+    add_library(osgGA::osgGA INTERFACE IMPORTED)
+    set_target_properties(
+      osgGA::osgGA
+      PROPERTIES
+        INTERFACE_INCLUDE_DIRECTORIES "${OSGGA_INCLUDE_DIR}"
+        INTERFACE_LINK_LIBRARIES "${OSGGA_LIBRARIES}"
+    )
+  endif()
 
-  ./configure --prefix=$OSGDIR
+  target_link_libraries(example PRIVATE osgGA::osgGA)
 
-used in building osg.
+See Also
+^^^^^^^^
 
-Created by Eric Wing.
+* The :module:`FindOpenSceneGraph` module to find OpenSceneGraph toolkit.
 #]=======================================================================]
 
-# Header files are presumed to be included like
-# #include <osg/PositionAttitudeTransform>
-# #include <osgGA/FlightManipulator>
+# Created by Eric Wing.
 
 include(${CMAKE_CURRENT_LIST_DIR}/Findosg_functions.cmake)
 OSG_FIND_PATH   (OSGGA osgGA/FlightManipulator)

Modules/FindosgIntrospection.cmake

@@ -5,44 +5,116 @@
 FindosgIntrospection
 --------------------
 
+Finds the osgIntrospection library from the OpenSceneGraph toolkit.
 
+.. note::
 
-This is part of the ``Findosg*`` suite used to find OpenSceneGraph
-components.  Each component is separate and you must opt in to each
-module.  You must also opt into OpenGL and OpenThreads (and Producer
-if needed) as these modules won't do it for you.  This is to allow you
-control over your own system piece by piece in case you need to opt
-out of certain components or change the Find behavior for a particular
-module (perhaps because the default :module:`FindOpenGL` module doesn't
-work with your system as an example).  If you want to use a more
-convenient module that includes everything, use the
-:module:`FindOpenSceneGraph` instead of the ``Findosg*.cmake`` modules.
+  The osgIntrospection library has been removed from the OpenSceneGraph toolkit
+  as of OpenSceneGraph version 3.0.
 
-Locate osgINTROSPECTION This module defines:
+.. note::
+
+  In most cases, it's recommended to use the :module:`FindOpenSceneGraph` module
+  instead and list osgIntrospection as a component.  This will automatically
+  handle dependencies such as the OpenThreads and core osg libraries:
+
+  .. code-block:: cmake
+
+    find_package(OpenSceneGraph COMPONENTS osgIntrospection)
+
+This module is used internally by :module:`FindOpenSceneGraph` to find the
+osgIntrospection library.  It is not intended to be included directly during
+typical use of the :command:`find_package` command.  However, it is available as
+a standalone module for advanced use cases where finer control over detection is
+needed.  For example, to find the osgIntrospection explicitly or bypass
+automatic component detection:
+
+.. code-block:: cmake
+
+  find_package(osgIntrospection)
+
+OpenSceneGraph and osgIntrospection headers are intended to be included in C++
+project source code as:
+
+.. code-block:: c++
+  :caption: ``example.cxx``
+
+  #include <osg/PositionAttitudeTransform>
+  #include <osgIntrospection/Reflection>
+  // ...
+
+When working with the OpenSceneGraph toolkit, other libraries such as OpenGL may
+also be required.
+
+Result Variables
+^^^^^^^^^^^^^^^^
+
+This module defines the following variables:
+
+``osgIntrospection_FOUND``
+  Boolean indicating whether the osgIntrospection library of the OpenSceneGraph
+  toolkit is found.  For backward compatibility, the ``OSGINTROSPECTION_FOUND``
+  variable is also set to the same value.
 
-``OSGINTROSPECTION_FOUND``
-  Was osgIntrospection found?
-``OSGINTROSPECTION_INCLUDE_DIR``
-  Where to find the headers
 ``OSGINTROSPECTION_LIBRARIES``
-  The libraries to link for osgIntrospection (use this)
+  The libraries needed to link against to use osgIntrospection.
+
 ``OSGINTROSPECTION_LIBRARY``
-  The osgIntrospection library
+  A result variable that is set to the same value as the
+  ``OSGINTROSPECTION_LIBRARIES`` variable.
+
+Cache Variables
+^^^^^^^^^^^^^^^
+
+The following cache variables may also be set:
+
+``OSGINTROSPECTION_INCLUDE_DIR``
+  The include directory containing headers needed to use osgIntrospection.
+
 ``OSGINTROSPECTION_LIBRARY_DEBUG``
-  The osgIntrospection debug library
+  The path to the osgIntrospection debug library.
+
+Hints
+^^^^^
+
+This module accepts the following variables:
+
+``OSGDIR``
+  Environment variable that can be set to help locate the OpenSceneGraph
+  toolkit, including its osgIntrospection library, when installed in a custom
+  location.  It should point to the OpenSceneGraph installation prefix used when
+  it was configured, built, and installed: ``./configure --prefix=$OSGDIR``.
+
+Examples
+^^^^^^^^
+
+Finding osgIntrospection explicitly with this module and creating an interface
+:ref:`imported target <Imported Targets>` that encapsulates its usage
+requirements for linking it to a project target:
+
+.. code-block:: cmake
+
+  find_package(osgIntrospection)
 
-``$OSGDIR`` is an environment variable that would correspond to::
+  if(osgIntrospection_FOUND AND NOT TARGET osgIntrospection::osgIntrospection)
+    add_library(osgIntrospection::osgIntrospection INTERFACE IMPORTED)
+    set_target_properties(
+      osgIntrospection::osgIntrospection
+      PROPERTIES
+        INTERFACE_INCLUDE_DIRECTORIES "${OSGINTROSPECTION_INCLUDE_DIR}"
+        INTERFACE_LINK_LIBRARIES "${OSGINTROSPECTION_LIBRARIES}"
+    )
+  endif()
 
-  ./configure --prefix=$OSGDIR
+  target_link_libraries(example PRIVATE osgIntrospection::osgIntrospection)
 
-used in building osg.
+See Also
+^^^^^^^^
 
-Created by Eric Wing.
+* The :module:`FindOpenSceneGraph` module to find OpenSceneGraph toolkit.
 #]=======================================================================]
 
-# Header files are presumed to be included like
-# #include <osg/PositionAttitudeTransform>
-# #include <osgIntrospection/Reflection>
+# Created by Eric Wing.
 
 include(${CMAKE_CURRENT_LIST_DIR}/Findosg_functions.cmake)
 OSG_FIND_PATH   (OSGINTROSPECTION osgIntrospection/Reflection)

Modules/FindosgManipulator.cmake

@@ -5,44 +5,111 @@
 FindosgManipulator
 ------------------
 
+Finds the osgManipulator NodeKit from the OpenSceneGraph toolkit.
 
+.. note::
 
-This is part of the ``Findosg*`` suite used to find OpenSceneGraph
-components.  Each component is separate and you must opt in to each
-module.  You must also opt into OpenGL and OpenThreads (and Producer
-if needed) as these modules won't do it for you.  This is to allow you
-control over your own system piece by piece in case you need to opt
-out of certain components or change the Find behavior for a particular
-module (perhaps because the default :module:`FindOpenGL` module doesn't
-work with your system as an example).  If you want to use a more
-convenient module that includes everything, use the
-:module:`FindOpenSceneGraph` instead of the ``Findosg*.cmake`` modules.
+  In most cases, it's recommended to use the :module:`FindOpenSceneGraph` module
+  instead and list osgManipulator as a component.  This will automatically
+  handle dependencies such as the OpenThreads and core osg libraries:
 
-Locate osgManipulator This module defines:
+  .. code-block:: cmake
+
+    find_package(OpenSceneGraph COMPONENTS osgManipulator)
+
+This module is used internally by :module:`FindOpenSceneGraph` to find the
+osgManipulator NodeKit.  It is not intended to be included directly during
+typical use of the :command:`find_package` command.  However, it is available as
+a standalone module for advanced use cases where finer control over detection is
+needed.  For example, to find the osgManipulator explicitly or bypass
+automatic component detection:
+
+.. code-block:: cmake
+
+  find_package(osgManipulator)
+
+OpenSceneGraph and osgManipulator headers are intended to be included in C++
+project source code as:
+
+.. code-block:: c++
+  :caption: ``example.cxx``
+
+  #include <osg/PositionAttitudeTransform>
+  #include <osgManipulator/TrackballDragger>
+  // ...
+
+When working with the OpenSceneGraph toolkit, other libraries such as OpenGL may
+also be required.
+
+Result Variables
+^^^^^^^^^^^^^^^^
+
+This module defines the following variables:
+
+``osgManipulator_FOUND``
+  Boolean indicating whether the osgManipulator NodeKit of the
+  OpenSceneGraph toolkit is found.  For backward compatibility, the
+  ``OSGMANIPULATOR_FOUND`` variable is also set to the same value.
 
-``OSGMANIPULATOR_FOUND``
-  Was osgManipulator found?
-``OSGMANIPULATOR_INCLUDE_DIR``
-  Where to find the headers
 ``OSGMANIPULATOR_LIBRARIES``
-  The libraries to link for osgManipulator (use this)
+  The libraries needed to link against to use osgManipulator.
+
 ``OSGMANIPULATOR_LIBRARY``
-  The osgManipulator library
+  A result variable that is set to the same value as the
+  ``OSGMANIPULATOR_LIBRARIES`` variable.
+
+Cache Variables
+^^^^^^^^^^^^^^^
+
+The following cache variables may also be set:
+
+``OSGMANIPULATOR_INCLUDE_DIR``
+  The include directory containing headers needed to use osgManipulator.
+
 ``OSGMANIPULATOR_LIBRARY_DEBUG``
-  The osgManipulator debug library
+  The path to the osgManipulator debug library.
+
+Hints
+^^^^^
+
+This module accepts the following variables:
+
+``OSGDIR``
+  Environment variable that can be set to help locate the OpenSceneGraph
+  toolkit, including its osgManipulator NodeKit, when installed in a custom
+  location.  It should point to the OpenSceneGraph installation prefix used when
+  it was configured, built, and installed: ``./configure --prefix=$OSGDIR``.
+
+Examples
+^^^^^^^^
+
+Finding osgManipulator explicitly with this module and creating an interface
+:ref:`imported target <Imported Targets>` that encapsulates its usage
+requirements for linking it to a project target:
+
+.. code-block:: cmake
+
+  find_package(osgManipulator)
 
-``$OSGDIR`` is an environment variable that would correspond to::
+  if(osgManipulator_FOUND AND NOT TARGET osgManipulator::osgManipulator)
+    add_library(osgManipulator::osgManipulator INTERFACE IMPORTED)
+    set_target_properties(
+      osgManipulator::osgManipulator
+      PROPERTIES
+        INTERFACE_INCLUDE_DIRECTORIES "${OSGMANIPULATOR_INCLUDE_DIR}"
+        INTERFACE_LINK_LIBRARIES "${OSGMANIPULATOR_LIBRARIES}"
+    )
+  endif()
 
-  ./configure --prefix=$OSGDIR
+  target_link_libraries(example PRIVATE osgManipulator::osgManipulator)
 
-used in building osg.
+See Also
+^^^^^^^^
 
-Created by Eric Wing.
+* The :module:`FindOpenSceneGraph` module to find OpenSceneGraph toolkit.
 #]=======================================================================]
 
-# Header files are presumed to be included like
-# #include <osg/PositionAttitudeTransform>
-# #include <osgManipulator/TrackballDragger>
+# Created by Eric Wing.
 
 include(${CMAKE_CURRENT_LIST_DIR}/Findosg_functions.cmake)
 OSG_FIND_PATH   (OSGMANIPULATOR osgManipulator/TrackballDragger)

Modules/FindosgParticle.cmake

@@ -5,44 +5,111 @@
 FindosgParticle
 ---------------
 
+Finds the osgParticle NodeKit from the OpenSceneGraph toolkit.
 
+.. note::
 
-This is part of the ``Findosg*`` suite used to find OpenSceneGraph
-components.  Each component is separate and you must opt in to each
-module.  You must also opt into OpenGL and OpenThreads (and Producer
-if needed) as these modules won't do it for you.  This is to allow you
-control over your own system piece by piece in case you need to opt
-out of certain components or change the Find behavior for a particular
-module (perhaps because the default :module:`FindOpenGL` module doesn't
-work with your system as an example).  If you want to use a more
-convenient module that includes everything, use the
-:module:`FindOpenSceneGraph` instead of the ``Findosg*.cmake`` modules.
+  In most cases, it's recommended to use the :module:`FindOpenSceneGraph` module
+  instead and list osgParticle as a component.  This will automatically handle
+  dependencies such as the OpenThreads and core osg libraries:
 
-Locate osgParticle This module defines:
+  .. code-block:: cmake
+
+    find_package(OpenSceneGraph COMPONENTS osgParticle)
+
+This module is used internally by :module:`FindOpenSceneGraph` to find the
+osgParticle NodeKit.  It is not intended to be included directly during typical
+use of the :command:`find_package` command.  However, it is available as a
+standalone module for advanced use cases where finer control over detection is
+needed.  For example, to find the osgParticle explicitly or bypass automatic
+component detection:
+
+.. code-block:: cmake
+
+  find_package(osgParticle)
+
+OpenSceneGraph and osgParticle headers are intended to be included in C++
+project source code as:
+
+.. code-block:: c++
+  :caption: ``example.cxx``
+
+  #include <osg/PositionAttitudeTransform>
+  #include <osgParticle/FireEffect>
+  // ...
+
+When working with the OpenSceneGraph toolkit, other libraries such as OpenGL may
+also be required.
+
+Result Variables
+^^^^^^^^^^^^^^^^
+
+This module defines the following variables:
+
+``osgParticle_FOUND``
+  Boolean indicating whether the osgParticle NodeKit of the OpenSceneGraph
+  toolkit is found.  For backward compatibility, the ``OSGPARTICLE_FOUND``
+  variable is also set to the same value.
 
-``OSGPARTICLE_FOUND``
-  Was osgParticle found?
-``OSGPARTICLE_INCLUDE_DIR``
-  Where to find the headers
 ``OSGPARTICLE_LIBRARIES``
-  The libraries to link for osgParticle (use this)
+  The libraries needed to link against to use the osgParticle NodeKit
+
 ``OSGPARTICLE_LIBRARY``
-  The osgParticle library
+  A result variable that is set to the same value as the
+  ``OSGPARTICLE_LIBRARIES`` variable.
+
+Cache Variables
+^^^^^^^^^^^^^^^
+
+The following cache variables may also be set:
+
+``OSGPARTICLE_INCLUDE_DIR``
+  The include directory containing headers needed to use osgParticle NodeKit.
+
 ``OSGPARTICLE_LIBRARY_DEBUG``
-  The osgParticle debug library
+  The path to the osgParticle debug library.
+
+Hints
+^^^^^
+
+This module accepts the following variables:
+
+``OSGDIR``
+  Environment variable that can be set to help locate the OpenSceneGraph
+  toolkit, including its osgParticle NodeKit, when installed in a custom
+  location.  It should point to the OpenSceneGraph installation prefix used when
+  it was configured, built, and installed: ``./configure --prefix=$OSGDIR``.
+
+Examples
+^^^^^^^^
+
+Finding osgParticle explicitly with this module and creating an interface
+:ref:`imported target <Imported Targets>` that encapsulates its usage
+requirements for linking it to a project target:
+
+.. code-block:: cmake
+
+  find_package(osgParticle)
 
-``$OSGDIR`` is an environment variable that would correspond to::
+  if(osgParticle_FOUND AND NOT TARGET osgParticle::osgParticle)
+    add_library(osgParticle::osgParticle INTERFACE IMPORTED)
+    set_target_properties(
+      osgParticle::osgParticle
+      PROPERTIES
+        INTERFACE_INCLUDE_DIRECTORIES "${OSGPARTICLE_INCLUDE_DIR}"
+        INTERFACE_LINK_LIBRARIES "${OSGPARTICLE_LIBRARIES}"
+    )
+  endif()
 
-  ./configure --prefix=$OSGDIR
+  target_link_libraries(example PRIVATE osgParticle::osgParticle)
 
-used in building osg.
+See Also
+^^^^^^^^
 
-Created by Eric Wing.
+* The :module:`FindOpenSceneGraph` module to find OpenSceneGraph toolkit.
 #]=======================================================================]
 
-# Header files are presumed to be included like
-# #include <osg/PositionAttitudeTransform>
-# #include <osgParticle/FireEffect>
+# Created by Eric Wing.
 
 include(${CMAKE_CURRENT_LIST_DIR}/Findosg_functions.cmake)
 OSG_FIND_PATH   (OSGPARTICLE osgParticle/FireEffect)

Modules/FindosgPresentation.cmake

@@ -5,44 +5,113 @@
 FindosgPresentation
 -------------------
 
+Finds the osgPresentation NodeKit from the OpenSceneGraph toolkit, available
+since OpenSceneGraph version 3.0.0.
 
+.. note::
 
-This is part of the ``Findosg*`` suite used to find OpenSceneGraph
-components.  Each component is separate and you must opt in to each
-module.  You must also opt into OpenGL and OpenThreads (and Producer
-if needed) as these modules won't do it for you.  This is to allow you
-control over your own system piece by piece in case you need to opt
-out of certain components or change the Find behavior for a particular
-module (perhaps because the default :module:`FindOpenGL` module doesn't
-work with your system as an example).  If you want to use a more
-convenient module that includes everything, use the
-:module:`FindOpenSceneGraph` instead of the ``Findosg*.cmake`` modules.
+  In most cases, it's recommended to use the :module:`FindOpenSceneGraph` module
+  instead and list osgPresentation as a component.  This will automatically
+  handle dependencies such as the OpenThreads and core osg libraries:
 
-Locate osgPresentation This module defines:
+  .. code-block:: cmake
+
+    find_package(OpenSceneGraph COMPONENTS osgPresentation)
+
+This module is used internally by :module:`FindOpenSceneGraph` to find the
+osgPresentation NodeKit.  It is not intended to be included directly during
+typical use of the :command:`find_package` command.  However, it is available as
+a standalone module for advanced use cases where finer control over detection is
+needed.  For example, to find the osgPresentation explicitly or bypass automatic
+component detection:
+
+.. code-block:: cmake
+
+  find_package(osgPresentation)
+
+OpenSceneGraph and osgPresentation headers are intended to be included in C++
+project source code as:
+
+.. code-block:: c++
+  :caption: ``example.cxx``
+
+  #include <osg/PositionAttitudeTransform>
+  #include <osgPresentation/SlideEventHandler>
+  // ...
+
+When working with the OpenSceneGraph toolkit, other libraries such as OpenGL may
+also be required.
+
+Result Variables
+^^^^^^^^^^^^^^^^
+
+This module defines the following variables:
+
+``osgPresentation_FOUND``
+  Boolean indicating whether the osgPresentation NodeKit of the
+  OpenSceneGraph toolkit is found.  For backward compatibility, the
+  ``OSGPRESENTATION_FOUND`` variable is also set to the same value.
 
-``OSGPRESENTATION_FOUND``
-  Was osgPresentation found?
-``OSGPRESENTATION_INCLUDE_DIR``
-  Where to find the headers
 ``OSGPRESENTATION_LIBRARIES``
-  The libraries to link for osgPresentation (use this)
+  The libraries needed to link against to use osgPresentation.
+
 ``OSGPRESENTATION_LIBRARY``
-  The osgPresentation library
+  A result variable that is set to the same value as the
+  ``OSGPRESENTATION_LIBRARIES`` variable.
+
+Cache Variables
+^^^^^^^^^^^^^^^
+
+The following cache variables may also be set:
+
+``OSGPRESENTATION_INCLUDE_DIR``
+  The include directory containing headers needed to use osgPresentation.
+
 ``OSGPRESENTATION_LIBRARY_DEBUG``
-  The osgPresentation debug library
+  The path to the osgPresentation debug library.
+
+Hints
+^^^^^
+
+This module accepts the following variables:
+
+``OSGDIR``
+  Environment variable that can be set to help locate the OpenSceneGraph
+  toolkit, including its osgPresentation NodeKit, when installed in a custom
+  location.  It should point to the OpenSceneGraph installation prefix used when
+  it was configured, built, and installed: ``./configure --prefix=$OSGDIR``.
+
+Examples
+^^^^^^^^
+
+Finding osgPresentation explicitly with this module and creating an interface
+:ref:`imported target <Imported Targets>` that encapsulates its usage
+requirements for linking it to a project target:
+
+.. code-block:: cmake
+
+  find_package(osgPresentation)
+
+  if(osgPresentation_FOUND AND NOT TARGET osgPresentation::osgPresentation)
+    add_library(osgPresentation::osgPresentation INTERFACE IMPORTED)
+    set_target_properties(
+      osgPresentation::osgPresentation
+      PROPERTIES
+        INTERFACE_INCLUDE_DIRECTORIES "${OSGPRESENTATION_INCLUDE_DIR}"
+        INTERFACE_LINK_LIBRARIES "${OSGPRESENTATION_LIBRARIES}"
+    )
+  endif()
 
-``$OSGDIR`` is an environment variable that would correspond to::
+  target_link_libraries(example PRIVATE osgPresentation::osgPresentation)
 
-  ./configure --prefix=$OSGDIR
+See Also
+^^^^^^^^
 
-used in building osg.
-Created by Eric Wing.  Modified to work with osgPresentation by Robert
-Osfield, January 2012.
+* The :module:`FindOpenSceneGraph` module to find OpenSceneGraph toolkit.
 #]=======================================================================]
 
-# Header files are presumed to be included like
-# #include <osg/PositionAttitudeTransform>
-# #include <osgPresentation/SlideEventHandler>
+# Created by Eric Wing.
+# Modified to work with osgPresentation by Robert Osfield, January 2012.
 
 include(${CMAKE_CURRENT_LIST_DIR}/Findosg_functions.cmake)
 OSG_FIND_PATH   (OSGPRESENTATION osgPresentation/SlideEventHandler)

Modules/FindosgProducer.cmake

@@ -5,44 +5,120 @@
 FindosgProducer
 ---------------
 
+Finds the osgProducer utility library from the OpenSceneGraph toolkit.
 
+.. note::
 
-This is part of the ``Findosg*`` suite used to find OpenSceneGraph
-components.  Each component is separate and you must opt in to each
-module.  You must also opt into OpenGL and OpenThreads (and Producer
-if needed) as these modules won't do it for you.  This is to allow you
-control over your own system piece by piece in case you need to opt
-out of certain components or change the Find behavior for a particular
-module (perhaps because the default :module:`FindOpenGL` module doesn't
-work with your system as an example).  If you want to use a more
-convenient module that includes everything, use the
-:module:`FindOpenSceneGraph` instead of the ``Findosg*.cmake`` modules.
+  The osgProducer library has been removed from the OpenSceneGraph toolkit in
+  early OpenSceneGraph versions (pre 1.0 release) and replaced with osgViewer.
+  Its development has shifted at time to a standalone project and repository
+  Producer, which can be found with :module:`FindProducer` module.
 
-Locate osgProducer This module defines:
+.. note::
+
+  In most cases, it's recommended to use the :module:`FindOpenSceneGraph` module
+  instead and list osgProducer as a component.  This will automatically handle
+  dependencies such as the OpenThreads and core osg libraries:
+
+  .. code-block:: cmake
+
+    find_package(OpenSceneGraph COMPONENTS osgProducer)
+
+This module is used internally by :module:`FindOpenSceneGraph` to find the
+osgProducer library.  It is not intended to be included directly during typical
+use of the :command:`find_package` command.  However, it is available as a
+standalone module for advanced use cases where finer control over detection is
+needed.  For example, to find the osgProducer explicitly or bypass automatic
+component detection:
+
+.. code-block:: cmake
+
+  find_package(osgProducer)
+
+OpenSceneGraph and osgProducer headers are intended to be included in C++
+project source code as:
+
+.. code-block:: c++
+  :caption: ``example.cxx``
+
+  #include <osg/PositionAttitudeTransform>
+  #include <osgProducer/OsgSceneHandler>
+  // ...
+
+When working with the OpenSceneGraph toolkit, other libraries such as OpenGL may
+also be required.
+
+Result Variables
+^^^^^^^^^^^^^^^^
+
+This module defines the following variables:
+
+``osgProducer_FOUND``
+  Boolean indicating whether the osgProducer library of the OpenSceneGraph
+  toolkit is found.  For backward compatibility, the ``OSGPRODUCER_FOUND``
+  variable is also set to the same value.
 
-``OSGPRODUCER_FOUND``
-  Was osgProducer found?
-``OSGPRODUCER_INCLUDE_DIR``
-  Where to find the headers
 ``OSGPRODUCER_LIBRARIES``
-  The libraries to link for osgProducer (use this)
+  The libraries needed to link against to use osgProducer.
+
 ``OSGPRODUCER_LIBRARY``
-  The osgProducer library
+  A result variable that is set to the same value as the
+  ``OSGPRODUCER_LIBRARIES`` variable.
+
+Cache Variables
+^^^^^^^^^^^^^^^
+
+The following cache variables may also be set:
+
+``OSGPRODUCER_INCLUDE_DIR``
+  The include directory containing headers needed to use osgProducer.
+
 ``OSGPRODUCER_LIBRARY_DEBUG``
-  The osgProducer debug library
+  The path to the osgProducer debug library.
+
+Hints
+^^^^^
+
+This module accepts the following variables:
+
+``OSGDIR``
+  Environment variable that can be set to help locate the OpenSceneGraph
+  toolkit, including its osgProducer library, when installed in a custom
+  location.  It should point to the OpenSceneGraph installation prefix used when
+  it was configured, built, and installed: ``./configure --prefix=$OSGDIR``.
+
+Examples
+^^^^^^^^
+
+Finding osgProducer explicitly with this module and creating an interface
+:ref:`imported target <Imported Targets>` that encapsulates its usage
+requirements for linking it to a project target:
+
+.. code-block:: cmake
+
+  find_package(osgProducer)
 
-``$OSGDIR`` is an environment variable that would correspond to::
+  if(osgProducer_FOUND AND NOT TARGET osgProducer::osgProducer)
+    add_library(osgProducer::osgProducer INTERFACE IMPORTED)
+    set_target_properties(
+      osgProducer::osgProducer
+      PROPERTIES
+        INTERFACE_INCLUDE_DIRECTORIES "${OSGPRODUCER_INCLUDE_DIR}"
+        INTERFACE_LINK_LIBRARIES "${OSGPRODUCER_LIBRARIES}"
+    )
+  endif()
 
-  ./configure --prefix=$OSGDIR
+  target_link_libraries(example PRIVATE osgProducer::osgProducer)
 
-used in building osg.
+See Also
+^^^^^^^^
 
-Created by Eric Wing.
+* The :module:`FindOpenSceneGraph` module to find OpenSceneGraph toolkit.
+* The :module:`FindProducer` module, which finds the standalone Producer library
+  that evolved from the legacy osgProducer.
 #]=======================================================================]
 
-# Header files are presumed to be included like
-# #include <osg/PositionAttitudeTransform>
-# #include <osgProducer/OsgSceneHandler>
+# Created by Eric Wing.
 
 include(${CMAKE_CURRENT_LIST_DIR}/Findosg_functions.cmake)
 OSG_FIND_PATH   (OSGPRODUCER osgProducer/OsgSceneHandler)

Modules/FindosgQt.cmake

@@ -5,45 +5,112 @@
 FindosgQt
 ---------
 
+Finds the osgQt utility library from the OpenSceneGraph toolkit.
 
+.. note::
 
-This is part of the ``Findosg*`` suite used to find OpenSceneGraph
-components.  Each component is separate and you must opt in to each
-module.  You must also opt into OpenGL and OpenThreads (and Producer
-if needed) as these modules won't do it for you.  This is to allow you
-control over your own system piece by piece in case you need to opt
-out of certain components or change the Find behavior for a particular
-module (perhaps because the default :module:`FindOpenGL` module doesn't
-work with your system as an example).  If you want to use a more
-convenient module that includes everything, use the
-:module:`FindOpenSceneGraph` instead of the ``Findosg*.cmake`` modules.
+  In most cases, it's recommended to use the :module:`FindOpenSceneGraph` module
+  instead and list osgQt as a component.  This will automatically handle
+  dependencies such as the OpenThreads and core osg libraries:
 
-Locate osgQt This module defines:
+  .. code-block:: cmake
+
+    find_package(OpenSceneGraph COMPONENTS osgQt)
+
+This module is used internally by :module:`FindOpenSceneGraph` to find the
+osgQt library.  It is not intended to be included directly during typical
+use of the :command:`find_package` command.  However, it is available as a
+standalone module for advanced use cases where finer control over detection is
+needed.  For example, to find the osgQt explicitly or bypass automatic
+component detection:
+
+.. code-block:: cmake
+
+  find_package(osgQt)
+
+OpenSceneGraph and osgQt headers are intended to be included in C++ project
+source code as:
+
+.. code-block:: c++
+  :caption: ``example.cxx``
+
+  #include <osg/PositionAttitudeTransform>
+  #include <osgQt/GraphicsWindowQt>
+  // ...
+
+When working with the OpenSceneGraph toolkit, other libraries such as OpenGL may
+also be required.
+
+Result Variables
+^^^^^^^^^^^^^^^^
+
+This module defines the following variables:
+
+``osgQt_FOUND``
+  Boolean indicating whether the osgQt library of the OpenSceneGraph toolkit
+  is found.  For backward compatibility, the ``OSGQT_FOUND`` variable is also
+  set to the same value.
 
-``OSGQT_FOUND``
-  Was osgQt found?
-``OSGQT_INCLUDE_DIR``
-  Where to find the headers
 ``OSGQT_LIBRARIES``
-  The libraries to link for osgQt (use this)
+  The libraries needed to link against to use osgQt.
+
 ``OSGQT_LIBRARY``
-  The osgQt library
+  A result variable that is set to the same value as the ``OSGQT_LIBRARIES``
+  variable.
+
+Cache Variables
+^^^^^^^^^^^^^^^
+
+The following cache variables may also be set:
+
+``OSGQT_INCLUDE_DIR``
+  The include directory containing headers needed to use osgQt.
+
 ``OSGQT_LIBRARY_DEBUG``
-  The osgQt debug library
+  The path to the osgQt debug library.
+
+Hints
+^^^^^
+
+This module accepts the following variables:
+
+``OSGDIR``
+  Environment variable that can be set to help locate the OpenSceneGraph
+  toolkit, including its osgQt library, when installed in a custom
+  location.  It should point to the OpenSceneGraph installation prefix used when
+  it was configured, built, and installed: ``./configure --prefix=$OSGDIR``.
+
+Examples
+^^^^^^^^
+
+Finding osgQt explicitly with this module and creating an interface
+:ref:`imported target <Imported Targets>` that encapsulates its usage
+requirements for linking it to a project target:
+
+.. code-block:: cmake
+
+  find_package(osgQt)
 
-``$OSGDIR`` is an environment variable that would correspond to::
+  if(osgQt_FOUND AND NOT TARGET osgQt::osgQt)
+    add_library(osgQt::osgQt INTERFACE IMPORTED)
+    set_target_properties(
+      osgQt::osgQt
+      PROPERTIES
+        INTERFACE_INCLUDE_DIRECTORIES "${OSGQT_INCLUDE_DIR}"
+        INTERFACE_LINK_LIBRARIES "${OSGQT_LIBRARIES}"
+    )
+  endif()
 
-  ./configure --prefix=$OSGDIR
+  target_link_libraries(example PRIVATE osgQt::osgQt)
 
-used in building osg.
+See Also
+^^^^^^^^
 
-Created by Eric Wing.  Modified to work with osgQt by Robert Osfield,
-January 2012.
+* The :module:`FindOpenSceneGraph` module to find OpenSceneGraph toolkit.
 #]=======================================================================]
 
-# Header files are presumed to be included like
-# #include <osg/PositionAttitudeTransform>
-# #include <osgQt/GraphicsWindowQt>
+# Created by Eric Wing.
+# Modified to work with osgQt by Robert Osfield, January 2012.
 
 include(${CMAKE_CURRENT_LIST_DIR}/Findosg_functions.cmake)
 OSG_FIND_PATH   (OSGQT osgQt/GraphicsWindowQt)

Modules/FindosgShadow.cmake

@@ -5,44 +5,111 @@
 FindosgShadow
 -------------
 
+Finds the osgShadow NodeKit from the OpenSceneGraph toolkit.
 
+.. note::
 
-This is part of the ``Findosg*`` suite used to find OpenSceneGraph
-components.  Each component is separate and you must opt in to each
-module.  You must also opt into OpenGL and OpenThreads (and Producer
-if needed) as these modules won't do it for you.  This is to allow you
-control over your own system piece by piece in case you need to opt
-out of certain components or change the Find behavior for a particular
-module (perhaps because the default :module:`FindOpenGL` module doesn't
-work with your system as an example).  If you want to use a more
-convenient module that includes everything, use the
-:module:`FindOpenSceneGraph` instead of the ``Findosg*.cmake`` modules.
+  In most cases, it's recommended to use the :module:`FindOpenSceneGraph` module
+  instead and list osgShadow as a component.  This will automatically handle
+  dependencies such as the OpenThreads and core osg libraries:
 
-Locate osgShadow This module defines:
+  .. code-block:: cmake
+
+    find_package(OpenSceneGraph COMPONENTS osgShadow)
+
+This module is used internally by :module:`FindOpenSceneGraph` to find the
+osgShadow NodeKit.  It is not intended to be included directly during typical
+use of the :command:`find_package` command.  However, it is available as a
+standalone module for advanced use cases where finer control over detection is
+needed.  For example, to find the osgShadow explicitly or bypass automatic
+component detection:
+
+.. code-block:: cmake
+
+  find_package(osgShadow)
+
+OpenSceneGraph and osgShadow headers are intended to be included in C++ project
+source code as:
+
+.. code-block:: c++
+  :caption: ``example.cxx``
+
+  #include <osg/PositionAttitudeTransform>
+  #include <osgShadow/ShadowTexture>
+  // ...
+
+When working with the OpenSceneGraph toolkit, other libraries such as OpenGL may
+also be required.
+
+Result Variables
+^^^^^^^^^^^^^^^^
+
+This module defines the following variables:
+
+``osgShadow_FOUND``
+  Boolean indicating whether the osgShadow NodeKit of the OpenSceneGraph
+  toolkit is found.  For backward compatibility, the ``OSGSHADOW_FOUND``
+  variable is also set to the same value.
 
-``OSGSHADOW_FOUND``
-  Was osgShadow found?
-``OSGSHADOW_INCLUDE_DIR``
-  Where to find the headers
 ``OSGSHADOW_LIBRARIES``
-  The libraries to link for osgShadow (use this)
+  The libraries needed to link against to use osgShadow.
+
 ``OSGSHADOW_LIBRARY``
-  The osgShadow library
+  A result variable that is set to the same value as the ``OSGSHADOW_LIBRARIES``
+  variable.
+
+Cache Variables
+^^^^^^^^^^^^^^^
+
+The following cache variables may also be set:
+
+``OSGSHADOW_INCLUDE_DIR``
+  The include directory containing headers needed to use osgShadow.
+
 ``OSGSHADOW_LIBRARY_DEBUG``
-  The osgShadow debug library
+  The path to the osgShadow debug library.
+
+Hints
+^^^^^
+
+This module accepts the following variables:
+
+``OSGDIR``
+  Environment variable that can be set to help locate the OpenSceneGraph
+  toolkit, including its osgShadow NodeKit, when installed in a custom
+  location.  It should point to the OpenSceneGraph installation prefix used when
+  it was configured, built, and installed: ``./configure --prefix=$OSGDIR``.
+
+Examples
+^^^^^^^^
+
+Finding osgShadow explicitly with this module and creating an interface
+:ref:`imported target <Imported Targets>` that encapsulates its usage
+requirements for linking it to a project target:
+
+.. code-block:: cmake
+
+  find_package(osgShadow)
 
-``$OSGDIR`` is an environment variable that would correspond to::
+  if(osgShadow_FOUND AND NOT TARGET osgShadow::osgShadow)
+    add_library(osgShadow::osgShadow INTERFACE IMPORTED)
+    set_target_properties(
+      osgShadow::osgShadow
+      PROPERTIES
+        INTERFACE_INCLUDE_DIRECTORIES "${OSGSHADOW_INCLUDE_DIR}"
+        INTERFACE_LINK_LIBRARIES "${OSGSHADOW_LIBRARIES}"
+    )
+  endif()
 
-  ./configure --prefix=$OSGDIR
+  target_link_libraries(example PRIVATE osgShadow::osgShadow)
 
-used in building osg.
+See Also
+^^^^^^^^
 
-Created by Eric Wing.
+* The :module:`FindOpenSceneGraph` module to find OpenSceneGraph toolkit.
 #]=======================================================================]
 
-# Header files are presumed to be included like
-# #include <osg/PositionAttitudeTransform>
-# #include <osgShadow/ShadowTexture>
+# Created by Eric Wing.
 
 include(${CMAKE_CURRENT_LIST_DIR}/Findosg_functions.cmake)
 OSG_FIND_PATH   (OSGSHADOW osgShadow/ShadowTexture)

Modules/FindosgSim.cmake

@@ -5,44 +5,111 @@
 FindosgSim
 ----------
 
+Finds the osgSim NodeKit from the OpenSceneGraph toolkit.
 
+.. note::
 
-This is part of the ``Findosg*`` suite used to find OpenSceneGraph
-components.  Each component is separate and you must opt in to each
-module.  You must also opt into OpenGL and OpenThreads (and Producer
-if needed) as these modules won't do it for you.  This is to allow you
-control over your own system piece by piece in case you need to opt
-out of certain components or change the Find behavior for a particular
-module (perhaps because the default :module:`FindOpenGL` module doesn't
-work with your system as an example).  If you want to use a more
-convenient module that includes everything, use the
-:module:`FindOpenSceneGraph` instead of the ``Findosg*.cmake`` modules.
+  In most cases, it's recommended to use the :module:`FindOpenSceneGraph` module
+  instead and list osgSim as a component.  This will automatically handle
+  dependencies such as the OpenThreads and core osg libraries:
 
-Locate osgSim This module defines:
+  .. code-block:: cmake
+
+    find_package(OpenSceneGraph COMPONENTS osgSim)
+
+This module is used internally by :module:`FindOpenSceneGraph` to find the
+osgSim NodeKit.  It is not intended to be included directly during typical
+use of the :command:`find_package` command.  However, it is available as a
+standalone module for advanced use cases where finer control over detection is
+needed.  For example, to find the osgSim explicitly or bypass automatic
+component detection:
+
+.. code-block:: cmake
+
+  find_package(osgSim)
+
+OpenSceneGraph and osgSim headers are intended to be included in C++ project
+source code as:
+
+.. code-block:: c++
+  :caption: ``example.cxx``
+
+  #include <osg/PositionAttitudeTransform>
+  #include <osgSim/ImpostorSprite>
+  // ...
+
+When working with the OpenSceneGraph toolkit, other libraries such as OpenGL may
+also be required.
+
+Result Variables
+^^^^^^^^^^^^^^^^
+
+This module defines the following variables:
+
+``osgSim_FOUND``
+  Boolean indicating whether the osgSim NodeKit of the OpenSceneGraph
+  toolkit is found.  For backward compatibility, the ``OSGSIM_FOUND`` variable
+  is also set to the same value.
 
-``OSGSIM_FOUND``
-  Was osgSim found?
-``OSGSIM_INCLUDE_DIR``
-  Where to find the headers
 ``OSGSIM_LIBRARIES``
-  The libraries to link for osgSim (use this)
+  The libraries needed to link against to use osgSim.
+
 ``OSGSIM_LIBRARY``
-  The osgSim library
+  A result variable that is set to the same value as the ``OSGSIM_LIBRARIES``
+  variable.
+
+Cache Variables
+^^^^^^^^^^^^^^^
+
+The following cache variables may also be set:
+
+``OSGSIM_INCLUDE_DIR``
+  The include directory containing headers needed to use osgSim.
+
 ``OSGSIM_LIBRARY_DEBUG``
-  The osgSim debug library
+  The path to the osgSim debug library.
+
+Hints
+^^^^^
+
+This module accepts the following variables:
+
+``OSGDIR``
+  Environment variable that can be set to help locate the OpenSceneGraph
+  toolkit, including its osgSim NodeKit, when installed in a custom
+  location.  It should point to the OpenSceneGraph installation prefix used when
+  it was configured, built, and installed: ``./configure --prefix=$OSGDIR``.
+
+Examples
+^^^^^^^^
+
+Finding osgSim explicitly with this module and creating an interface
+:ref:`imported target <Imported Targets>` that encapsulates its usage
+requirements for linking it to a project target:
+
+.. code-block:: cmake
+
+  find_package(osgSim)
 
-``$OSGDIR`` is an environment variable that would correspond to::
+  if(osgSim_FOUND AND NOT TARGET osgSim::osgSim)
+    add_library(osgSim::osgSim INTERFACE IMPORTED)
+    set_target_properties(
+      osgSim::osgSim
+      PROPERTIES
+        INTERFACE_INCLUDE_DIRECTORIES "${OSGSIM_INCLUDE_DIR}"
+        INTERFACE_LINK_LIBRARIES "${OSGSIM_LIBRARIES}"
+    )
+  endif()
 
-  ./configure --prefix=$OSGDIR
+  target_link_libraries(example PRIVATE osgSim::osgSim)
 
-used in building osg.
+See Also
+^^^^^^^^
 
-Created by Eric Wing.
+* The :module:`FindOpenSceneGraph` module to find OpenSceneGraph toolkit.
 #]=======================================================================]
 
-# Header files are presumed to be included like
-# #include <osg/PositionAttitudeTransform>
-# #include <osgSim/ImpostorSprite>
+# Created by Eric Wing.
 
 include(${CMAKE_CURRENT_LIST_DIR}/Findosg_functions.cmake)
 OSG_FIND_PATH   (OSGSIM osgSim/ImpostorSprite)

Modules/FindosgTerrain.cmake

@@ -5,44 +5,111 @@
 FindosgTerrain
 --------------
 
+Finds the osgTerrain NodeKit from the OpenSceneGraph toolkit.
 
+.. note::
 
-This is part of the ``Findosg*`` suite used to find OpenSceneGraph
-components.  Each component is separate and you must opt in to each
-module.  You must also opt into OpenGL and OpenThreads (and Producer
-if needed) as these modules won't do it for you.  This is to allow you
-control over your own system piece by piece in case you need to opt
-out of certain components or change the Find behavior for a particular
-module (perhaps because the default :module:`FindOpenGL` module doesn't
-work with your system as an example).  If you want to use a more
-convenient module that includes everything, use the
-:module:`FindOpenSceneGraph` instead of the ``Findosg*.cmake`` modules.
+  In most cases, it's recommended to use the :module:`FindOpenSceneGraph` module
+  instead and list osgTerrain as a component.  This will automatically handle
+  dependencies such as the OpenThreads and core osg libraries:
 
-Locate osgTerrain This module defines:
+  .. code-block:: cmake
+
+    find_package(OpenSceneGraph COMPONENTS osgTerrain)
+
+This module is used internally by :module:`FindOpenSceneGraph` to find the
+osgTerrain NodeKit.  It is not intended to be included directly during typical
+use of the :command:`find_package` command.  However, it is available as a
+standalone module for advanced use cases where finer control over detection is
+needed.  For example, to find the osgTerrain explicitly or bypass automatic
+component detection:
+
+.. code-block:: cmake
+
+  find_package(osgTerrain)
+
+OpenSceneGraph and osgTerrain headers are intended to be included in C++ project
+source code as:
+
+.. code-block:: c++
+  :caption: ``example.cxx``
+
+  #include <osg/PositionAttitudeTransform>
+  #include <osgTerrain/Terrain>
+  // ...
+
+When working with the OpenSceneGraph toolkit, other libraries such as OpenGL may
+also be required.
+
+Result Variables
+^^^^^^^^^^^^^^^^
+
+This module defines the following variables:
+
+``osgTerrain_FOUND``
+  Boolean indicating whether the osgTerrain NodeKit of the OpenSceneGraph
+  toolkit is found.  For backward compatibility, the ``OSGTERRAIN_FOUND``
+  variable is also set to the same value.
 
-``OSGTERRAIN_FOUND``
-  Was osgTerrain found?
-``OSGTERRAIN_INCLUDE_DIR``
-  Where to find the headers
 ``OSGTERRAIN_LIBRARIES``
-  The libraries to link for osgTerrain (use this)
+  The libraries needed to link against to use osgTerrain.
+
 ``OSGTERRAIN_LIBRARY``
-  The osgTerrain library
+  A result variable that is set to the same value as the
+  ``OSGTERRAIN_LIBRARIES`` variable.
+
+Cache Variables
+^^^^^^^^^^^^^^^
+
+The following cache variables may also be set:
+
+``OSGTERRAIN_INCLUDE_DIR``
+  The include directory containing headers needed to use osgTerrain.
+
 ``OSGTERRAIN_LIBRARY_DEBUG``
-  The osgTerrain debug library
+  The path to the osgTerrain debug library.
+
+Hints
+^^^^^
+
+This module accepts the following variables:
+
+``OSGDIR``
+  Environment variable that can be set to help locate the OpenSceneGraph
+  toolkit, including its osgTerrain NodeKit, when installed in a custom
+  location.  It should point to the OpenSceneGraph installation prefix used when
+  it was configured, built, and installed: ``./configure --prefix=$OSGDIR``.
+
+Examples
+^^^^^^^^
+
+Finding osgTerrain explicitly with this module and creating an interface
+:ref:`imported target <Imported Targets>` that encapsulates its usage
+requirements for linking it to a project target:
+
+.. code-block:: cmake
+
+  find_package(osgTerrain)
 
-``$OSGDIR`` is an environment variable that would correspond to::
+  if(osgTerrain_FOUND AND NOT TARGET osgTerrain::osgTerrain)
+    add_library(osgTerrain::osgTerrain INTERFACE IMPORTED)
+    set_target_properties(
+      osgTerrain::osgTerrain
+      PROPERTIES
+        INTERFACE_INCLUDE_DIRECTORIES "${OSGTERRAIN_INCLUDE_DIR}"
+        INTERFACE_LINK_LIBRARIES "${OSGTERRAIN_LIBRARIES}"
+    )
+  endif()
 
-  ./configure --prefix=$OSGDIR
+  target_link_libraries(example PRIVATE osgTerrain::osgTerrain)
 
-used in building osg.
+See Also
+^^^^^^^^
 
-Created by Eric Wing.
+* The :module:`FindOpenSceneGraph` module to find OpenSceneGraph toolkit.
 #]=======================================================================]
 
-# Header files are presumed to be included like
-# #include <osg/PositionAttitudeTransform>
-# #include <osgTerrain/Terrain>
+# Created by Eric Wing.
 
 include(${CMAKE_CURRENT_LIST_DIR}/Findosg_functions.cmake)
 OSG_FIND_PATH   (OSGTERRAIN osgTerrain/Terrain)

Modules/FindosgText.cmake

@@ -5,44 +5,111 @@
 FindosgText
 -----------
 
+Finds the osgText NodeKit from the OpenSceneGraph toolkit.
 
+.. note::
 
-This is part of the ``Findosg*`` suite used to find OpenSceneGraph
-components.  Each component is separate and you must opt in to each
-module.  You must also opt into OpenGL and OpenThreads (and Producer
-if needed) as these modules won't do it for you.  This is to allow you
-control over your own system piece by piece in case you need to opt
-out of certain components or change the Find behavior for a particular
-module (perhaps because the default :module:`FindOpenGL` module doesn't
-work with your system as an example).  If you want to use a more
-convenient module that includes everything, use the
-:module:`FindOpenSceneGraph` instead of the ``Findosg*.cmake`` modules.
+  In most cases, it's recommended to use the :module:`FindOpenSceneGraph` module
+  instead and list osgText as a component.  This will automatically handle
+  dependencies such as the OpenThreads and core osg libraries:
 
-Locate osgText This module defines:
+  .. code-block:: cmake
+
+    find_package(OpenSceneGraph COMPONENTS osgText)
+
+This module is used internally by :module:`FindOpenSceneGraph` to find the
+osgText NodeKit.  It is not intended to be included directly during typical
+use of the :command:`find_package` command.  However, it is available as a
+standalone module for advanced use cases where finer control over detection is
+needed.  For example, to find the osgText explicitly or bypass automatic
+component detection:
+
+.. code-block:: cmake
+
+  find_package(osgText)
+
+OpenSceneGraph and osgText headers are intended to be included in C++ project
+source code as:
+
+.. code-block:: c++
+  :caption: ``example.cxx``
+
+  #include <osg/PositionAttitudeTransform>
+  #include <osgText/Text>
+  // ...
+
+When working with the OpenSceneGraph toolkit, other libraries such as OpenGL may
+also be required.
+
+Result Variables
+^^^^^^^^^^^^^^^^
+
+This module defines the following variables:
+
+``osgText_FOUND``
+  Boolean indicating whether the osgText NodeKit of the OpenSceneGraph
+  toolkit is found.  For backward compatibility, the ``OSGTEXT_FOUND``
+  variable is also set to the same value.
 
-``OSGTEXT_FOUND``
-  Was osgText found?
-``OSGTEXT_INCLUDE_DIR``
-  Where to find the headers
 ``OSGTEXT_LIBRARIES``
-  The libraries to link for osgText (use this)
+  The libraries needed to link against to use osgText.
+
 ``OSGTEXT_LIBRARY``
-  The osgText library
+  A result variable that is set to the same value as the ``OSGTEXT_LIBRARIES``
+  variable.
+
+Cache Variables
+^^^^^^^^^^^^^^^
+
+The following cache variables may also be set:
+
+``OSGTEXT_INCLUDE_DIR``
+  The include directory containing headers needed to use osgText.
+
 ``OSGTEXT_LIBRARY_DEBUG``
-  The osgText debug library
+  The path to the osgText debug library.
+
+Hints
+^^^^^
+
+This module accepts the following variables:
+
+``OSGDIR``
+  Environment variable that can be set to help locate the OpenSceneGraph
+  toolkit, including its osgText NodeKit, when installed in a custom
+  location.  It should point to the OpenSceneGraph installation prefix used when
+  it was configured, built, and installed: ``./configure --prefix=$OSGDIR``.
+
+Examples
+^^^^^^^^
+
+Finding osgText explicitly with this module and creating an interface
+:ref:`imported target <Imported Targets>` that encapsulates its usage
+requirements for linking it to a project target:
+
+.. code-block:: cmake
+
+  find_package(osgText)
 
-``$OSGDIR`` is an environment variable that would correspond to::
+  if(osgText_FOUND AND NOT TARGET osgText::osgText)
+    add_library(osgText::osgText INTERFACE IMPORTED)
+    set_target_properties(
+      osgText::osgText
+      PROPERTIES
+        INTERFACE_INCLUDE_DIRECTORIES "${OSGTEXT_INCLUDE_DIR}"
+        INTERFACE_LINK_LIBRARIES "${OSGTEXT_LIBRARIES}"
+    )
+  endif()
 
-  ./configure --prefix=$OSGDIR
+  target_link_libraries(example PRIVATE osgText::osgText)
 
-used in building osg.
+See Also
+^^^^^^^^
 
-Created by Eric Wing.
+* The :module:`FindOpenSceneGraph` module to find OpenSceneGraph toolkit.
 #]=======================================================================]
 
-# Header files are presumed to be included like
-# #include <osg/PositionAttitudeTransform>
-# #include <osgText/Text>
+# Created by Eric Wing.
 
 include(${CMAKE_CURRENT_LIST_DIR}/Findosg_functions.cmake)
 OSG_FIND_PATH   (OSGTEXT osgText/Text)

Modules/FindosgUtil.cmake

@@ -5,44 +5,111 @@
 FindosgUtil
 -----------
 
+Finds the osgUtil library from the OpenSceneGraph toolkit.
 
+.. note::
 
-This is part of the ``Findosg*`` suite used to find OpenSceneGraph
-components.  Each component is separate and you must opt in to each
-module.  You must also opt into OpenGL and OpenThreads (and Producer
-if needed) as these modules won't do it for you.  This is to allow you
-control over your own system piece by piece in case you need to opt
-out of certain components or change the Find behavior for a particular
-module (perhaps because the default :module:`FindOpenGL` module doesn't
-work with your system as an example).  If you want to use a more
-convenient module that includes everything, use the
-:module:`FindOpenSceneGraph` instead of the ``Findosg*.cmake`` modules.
+  In most cases, it's recommended to use the :module:`FindOpenSceneGraph` module
+  instead and list osgUtil as a component.  This will automatically handle
+  dependencies such as the OpenThreads and core osg libraries:
 
-Locate osgUtil This module defines:
+  .. code-block:: cmake
+
+    find_package(OpenSceneGraph COMPONENTS osgUtil)
+
+This module is used internally by :module:`FindOpenSceneGraph` to find the
+osgUtil library.  It is not intended to be included directly during typical
+use of the :command:`find_package` command.  However, it is available as a
+standalone module for advanced use cases where finer control over detection is
+needed.  For example, to find the osgUtil explicitly or bypass automatic
+component detection:
+
+.. code-block:: cmake
+
+  find_package(osgUtil)
+
+OpenSceneGraph and osgUtil headers are intended to be included in C++ project
+source code as:
+
+.. code-block:: c++
+  :caption: ``example.cxx``
+
+  #include <osg/PositionAttitudeTransform>
+  #include <osgUtil/SceneView>
+  // ...
+
+When working with the OpenSceneGraph toolkit, other libraries such as OpenGL may
+also be required.
+
+Result Variables
+^^^^^^^^^^^^^^^^
+
+This module defines the following variables:
+
+``osgUtil_FOUND``
+  Boolean indicating whether the osgUtil library of the OpenSceneGraph
+  toolkit is found.  For backward compatibility, the ``OSGUTIL_FOUND`` variable
+  is also set to the same value.
 
-``OSGUTIL_FOUND``
-  Was osgUtil found?
-``OSGUTIL_INCLUDE_DIR``
-  Where to find the headers
 ``OSGUTIL_LIBRARIES``
-  The libraries to link for osgUtil (use this)
+  The libraries needed to link against to use osgUtil.
+
 ``OSGUTIL_LIBRARY``
-  The osgUtil library
+  A result variable that is set to the same value as the ``OSGUTIL_LIBRARIES``
+  variable.
+
+Cache Variables
+^^^^^^^^^^^^^^^
+
+The following cache variables may also be set:
+
+``OSGUTIL_INCLUDE_DIR``
+  The include directory containing headers needed to use osgUtil.
+
 ``OSGUTIL_LIBRARY_DEBUG``
-  The osgUtil debug library
+  The path to the osgUtil debug library.
+
+Hints
+^^^^^
+
+This module accepts the following variables:
+
+``OSGDIR``
+  Environment variable that can be set to help locate the OpenSceneGraph
+  toolkit, including its osgUtil library, when installed in a custom
+  location.  It should point to the OpenSceneGraph installation prefix used when
+  it was configured, built, and installed: ``./configure --prefix=$OSGDIR``.
+
+Examples
+^^^^^^^^
+
+Finding osgUtil explicitly with this module and creating an interface
+:ref:`imported target <Imported Targets>` that encapsulates its usage
+requirements for linking it to a project target:
+
+.. code-block:: cmake
+
+  find_package(osgUtil)
 
-``$OSGDIR`` is an environment variable that would correspond to::
+  if(osgUtil_FOUND AND NOT TARGET osgUtil::osgUtil)
+    add_library(osgUtil::osgUtil INTERFACE IMPORTED)
+    set_target_properties(
+      osgUtil::osgUtil
+      PROPERTIES
+        INTERFACE_INCLUDE_DIRECTORIES "${OSGUTIL_INCLUDE_DIR}"
+        INTERFACE_LINK_LIBRARIES "${OSGUTIL_LIBRARIES}"
+    )
+  endif()
 
-  ./configure --prefix=$OSGDIR
+  target_link_libraries(example PRIVATE osgUtil::osgUtil)
 
-used in building osg.
+See Also
+^^^^^^^^
 
-Created by Eric Wing.
+* The :module:`FindOpenSceneGraph` module to find OpenSceneGraph toolkit.
 #]=======================================================================]
 
-# Header files are presumed to be included like
-# #include <osg/PositionAttitudeTransform>
-# #include <osgUtil/SceneView>
+# Created by Eric Wing.
 
 include(${CMAKE_CURRENT_LIST_DIR}/Findosg_functions.cmake)
 OSG_FIND_PATH   (OSGUTIL osgUtil/SceneView)

Modules/FindosgViewer.cmake

@@ -5,44 +5,111 @@
 FindosgViewer
 -------------
 
+Finds the osgViewer library from the OpenSceneGraph toolkit.
 
+.. note::
 
-This is part of the ``Findosg*`` suite used to find OpenSceneGraph
-components.  Each component is separate and you must opt in to each
-module.  You must also opt into OpenGL and OpenThreads (and Producer
-if needed) as these modules won't do it for you.  This is to allow you
-control over your own system piece by piece in case you need to opt
-out of certain components or change the Find behavior for a particular
-module (perhaps because the default :module:`FindOpenGL` module doesn't
-work with your system as an example).  If you want to use a more
-convenient module that includes everything, use the
-:module:`FindOpenSceneGraph` instead of the ``Findosg*.cmake`` modules.
+  In most cases, it's recommended to use the :module:`FindOpenSceneGraph` module
+  instead and list osgViewer as a component.  This will automatically handle
+  dependencies such as the OpenThreads and core osg libraries:
 
-Locate osgViewer This module defines:
+  .. code-block:: cmake
+
+    find_package(OpenSceneGraph COMPONENTS osgViewer)
+
+This module is used internally by :module:`FindOpenSceneGraph` to find the
+osgViewer library.  It is not intended to be included directly during typical
+use of the :command:`find_package` command.  However, it is available as a
+standalone module for advanced use cases where finer control over detection is
+needed.  For example, to find the osgViewer explicitly or bypass automatic
+component detection:
+
+.. code-block:: cmake
+
+  find_package(osgViewer)
+
+OpenSceneGraph and osgViewer headers are intended to be included in C++ project
+source code as:
+
+.. code-block:: c++
+  :caption: ``example.cxx``
+
+  #include <osg/PositionAttitudeTransform>
+  #include <osgViewer/Viewer>
+  // ...
+
+When working with the OpenSceneGraph toolkit, other libraries such as OpenGL may
+also be required.
+
+Result Variables
+^^^^^^^^^^^^^^^^
+
+This module defines the following variables:
+
+``osgViewer_FOUND``
+  Boolean indicating whether the osgViewer library of the OpenSceneGraph
+  toolkit is found.  For backward compatibility, the ``OSGVIEWER_FOUND``
+  variable is also set to the same value.
 
-``OSGVIEWER_FOUND``
-  Was osgViewer found?
-``OSGVIEWER_INCLUDE_DIR``
-  Where to find the headers
 ``OSGVIEWER_LIBRARIES``
-  The libraries to link for osgViewer (use this)
+  The libraries needed to link against to use osgViewer.
+
 ``OSGVIEWER_LIBRARY``
-  The osgViewer library
+  A result variable that is set to the same value as the ``OSGVIEWER_LIBRARIES``
+  variable.
+
+Cache Variables
+^^^^^^^^^^^^^^^
+
+The following cache variables may also be set:
+
+``OSGVIEWER_INCLUDE_DIR``
+  The include directory containing headers needed to use osgViewer.
+
 ``OSGVIEWER_LIBRARY_DEBUG``
-  The osgViewer debug library
+  The path to the osgViewer debug library.
+
+Hints
+^^^^^
+
+This module accepts the following variables:
+
+``OSGDIR``
+  Environment variable that can be set to help locate the OpenSceneGraph
+  toolkit, including its osgViewer library, when installed in a custom
+  location.  It should point to the OpenSceneGraph installation prefix used when
+  it was configured, built, and installed: ``./configure --prefix=$OSGDIR``.
+
+Examples
+^^^^^^^^
+
+Finding osgViewer explicitly with this module and creating an interface
+:ref:`imported target <Imported Targets>` that encapsulates its usage
+requirements for linking it to a project target:
+
+.. code-block:: cmake
+
+  find_package(osgViewer)
 
-``$OSGDIR`` is an environment variable that would correspond to::
+  if(osgViewer_FOUND AND NOT TARGET osgViewer::osgViewer)
+    add_library(osgViewer::osgViewer INTERFACE IMPORTED)
+    set_target_properties(
+      osgViewer::osgViewer
+      PROPERTIES
+        INTERFACE_INCLUDE_DIRECTORIES "${OSGVIEWER_INCLUDE_DIR}"
+        INTERFACE_LINK_LIBRARIES "${OSGVIEWER_LIBRARIES}"
+    )
+  endif()
 
-  ./configure --prefix=$OSGDIR
+  target_link_libraries(example PRIVATE osgViewer::osgViewer)
 
-used in building osg.
+See Also
+^^^^^^^^
 
-Created by Eric Wing.
+* The :module:`FindOpenSceneGraph` module to find OpenSceneGraph toolkit.
 #]=======================================================================]
 
-# Header files are presumed to be included like
-# #include <osg/PositionAttitudeTransform>
-# #include <osgViewer/Viewer>
+# Created by Eric Wing.
 
 include(${CMAKE_CURRENT_LIST_DIR}/Findosg_functions.cmake)
 OSG_FIND_PATH   (OSGVIEWER osgViewer/Viewer)

Modules/FindosgVolume.cmake

@@ -5,44 +5,111 @@
 FindosgVolume
 -------------
 
+Finds the osgVolume NodeKit from the OpenSceneGraph toolkit.
 
+.. note::
 
-This is part of the ``Findosg*`` suite used to find OpenSceneGraph
-components.  Each component is separate and you must opt in to each
-module.  You must also opt into OpenGL and OpenThreads (and Producer
-if needed) as these modules won't do it for you.  This is to allow you
-control over your own system piece by piece in case you need to opt
-out of certain components or change the Find behavior for a particular
-module (perhaps because the default :module:`FindOpenGL` module doesn't
-work with your system as an example).  If you want to use a more
-convenient module that includes everything, use the
-:module:`FindOpenSceneGraph` instead of the ``Findosg*.cmake`` modules.
+  In most cases, it's recommended to use the :module:`FindOpenSceneGraph` module
+  instead and list osgVolume as a component.  This will automatically handle
+  dependencies such as the OpenThreads and core osg libraries:
 
-Locate osgVolume This module defines:
+  .. code-block:: cmake
+
+    find_package(OpenSceneGraph COMPONENTS osgVolume)
+
+This module is used internally by :module:`FindOpenSceneGraph` to find the
+osgVolume NodeKit.  It is not intended to be included directly during typical
+use of the :command:`find_package` command.  However, it is available as a
+standalone module for advanced use cases where finer control over detection is
+needed.  For example, to find the osgVolume explicitly or bypass automatic
+component detection:
+
+.. code-block:: cmake
+
+  find_package(osgVolume)
+
+OpenSceneGraph and osgVolume headers are intended to be included in C++ project
+source code as:
+
+.. code-block:: c++
+  :caption: ``example.cxx``
+
+  #include <osg/PositionAttitudeTransform>
+  #include <osgVolume/Volume>
+  // ...
+
+When working with the OpenSceneGraph toolkit, other libraries such as OpenGL may
+also be required.
+
+Result Variables
+^^^^^^^^^^^^^^^^
+
+This module defines the following variables:
+
+``osgVolume_FOUND``
+  Boolean indicating whether the osgVolume NodeKit of the OpenSceneGraph
+  toolkit is found.  For backward compatibility, the ``OSGVOLUME_FOUND``
+  variable is also set to the same value.
 
-``OSGVOLUME_FOUND``
-  Was osgVolume found?
-``OSGVOLUME_INCLUDE_DIR``
-  Where to find the headers
 ``OSGVOLUME_LIBRARIES``
-  The libraries to link for osgVolume (use this)
+  The libraries needed to link against to use osgVolume.
+
 ``OSGVOLUME_LIBRARY``
-  The osgVolume library
+  A result variable that is set to the same value as the ``OSGVOLUME_LIBRARIES``
+  variable.
+
+Cache Variables
+^^^^^^^^^^^^^^^
+
+The following cache variables may also be set:
+
+``OSGVOLUME_INCLUDE_DIR``
+  The include directory containing headers needed to use osgVolume.
+
 ``OSGVOLUME_LIBRARY_DEBUG``
-  The osgVolume debug library
+  The path to the osgVolume debug library.
+
+Hints
+^^^^^
+
+This module accepts the following variables:
+
+``OSGDIR``
+  Environment variable that can be set to help locate the OpenSceneGraph
+  toolkit, including its osgVolume NodeKit, when installed in a custom
+  location.  It should point to the OpenSceneGraph installation prefix used when
+  it was configured, built, and installed: ``./configure --prefix=$OSGDIR``.
+
+Examples
+^^^^^^^^
+
+Finding osgVolume explicitly with this module and creating an interface
+:ref:`imported target <Imported Targets>` that encapsulates its usage
+requirements for linking it to a project target:
+
+.. code-block:: cmake
+
+  find_package(osgVolume)
 
-``$OSGDIR`` is an environment variable that would correspond to::
+  if(osgVolume_FOUND AND NOT TARGET osgVolume::osgVolume)
+    add_library(osgVolume::osgVolume INTERFACE IMPORTED)
+    set_target_properties(
+      osgVolume::osgVolume
+      PROPERTIES
+        INTERFACE_INCLUDE_DIRECTORIES "${OSGVOLUME_INCLUDE_DIR}"
+        INTERFACE_LINK_LIBRARIES "${OSGVOLUME_LIBRARIES}"
+    )
+  endif()
 
-  ./configure --prefix=$OSGDIR
+  target_link_libraries(example PRIVATE osgVolume::osgVolume)
 
-used in building osg.
+See Also
+^^^^^^^^
 
-Created by Eric Wing.
+* The :module:`FindOpenSceneGraph` module to find OpenSceneGraph toolkit.
 #]=======================================================================]
 
-# Header files are presumed to be included like
-# #include <osg/PositionAttitudeTransform>
-# #include <osgVolume/Volume>
+# Created by Eric Wing.
 
 include(${CMAKE_CURRENT_LIST_DIR}/Findosg_functions.cmake)
 OSG_FIND_PATH   (OSGVOLUME osgVolume/Volume)

Modules/FindosgWidget.cmake

@@ -5,45 +5,111 @@
 FindosgWidget
 -------------
 
+Finds the osgWidget NodeKit from the OpenSceneGraph toolkit.
 
+.. note::
 
-This is part of the ``Findosg*`` suite used to find OpenSceneGraph
-components.  Each component is separate and you must opt in to each
-module.  You must also opt into OpenGL and OpenThreads (and Producer
-if needed) as these modules won't do it for you.  This is to allow you
-control over your own system piece by piece in case you need to opt
-out of certain components or change the Find behavior for a particular
-module (perhaps because the default :module:`FindOpenGL` module doesn't
-work with your system as an example).  If you want to use a more
-convenient module that includes everything, use the
-:module:`FindOpenSceneGraph` instead of the ``Findosg*.cmake`` modules.
+  In most cases, it's recommended to use the :module:`FindOpenSceneGraph` module
+  instead and list osgWidget as a component.  This will automatically handle
+  dependencies such as the OpenThreads and core osg libraries:
 
-Locate osgWidget This module defines:
+  .. code-block:: cmake
+
+    find_package(OpenSceneGraph COMPONENTS osgWidget)
+
+This module is used internally by :module:`FindOpenSceneGraph` to find the
+osgWidget NodeKit.  It is not intended to be included directly during typical
+use of the :command:`find_package` command.  However, it is available as a
+standalone module for advanced use cases where finer control over detection is
+needed.  For example, to find the osgWidget explicitly or bypass automatic
+component detection:
+
+.. code-block:: cmake
+
+  find_package(osgWidget)
+
+OpenSceneGraph and osgWidget headers are intended to be included in C++ project
+source code as:
+
+.. code-block:: c++
+  :caption: ``example.cxx``
+
+  #include <osg/PositionAttitudeTransform>
+  #include <osgWidget/Widget>
+  // ...
+
+When working with the OpenSceneGraph toolkit, other libraries such as OpenGL may
+also be required.
+
+Result Variables
+^^^^^^^^^^^^^^^^
+
+This module defines the following variables:
+
+``osgWidget_FOUND``
+  Boolean indicating whether the osgWidget NodeKit of the OpenSceneGraph
+  toolkit is found.  For backward compatibility, the ``OSGWIDGET_FOUND``
+  variable is also set to the same value.
 
-``OSGWIDGET_FOUND``
-  Was osgWidget found?
-``OSGWIDGET_INCLUDE_DIR``
-  Where to find the headers
 ``OSGWIDGET_LIBRARIES``
-  The libraries to link for osgWidget (use this)
+  The libraries needed to link against to use osgWidget.
+
 ``OSGWIDGET_LIBRARY``
-  The osgWidget library
+  A result variable that is set to the same value as the ``OSGWIDGET_LIBRARIES``
+  variable.
+
+Cache Variables
+^^^^^^^^^^^^^^^
+
+The following cache variables may also be set:
+
+``OSGWIDGET_INCLUDE_DIR``
+  The include directory containing headers needed to use osgWidget.
+
 ``OSGWIDGET_LIBRARY_DEBUG``
-  The osgWidget debug library
+  The path to the osgWidget debug library.
+
+Hints
+^^^^^
+
+This module accepts the following variables:
+
+``OSGDIR``
+  Environment variable that can be set to help locate the OpenSceneGraph
+  toolkit, including its osgWidget NodeKit, when installed in a custom
+  location.  It should point to the OpenSceneGraph installation prefix used when
+  it was configured, built, and installed: ``./configure --prefix=$OSGDIR``.
+
+Examples
+^^^^^^^^
+
+Finding osgWidget explicitly with this module and creating an interface
+:ref:`imported target <Imported Targets>` that encapsulates its usage
+requirements for linking it to a project target:
+
+.. code-block:: cmake
+
+  find_package(osgWidget)
 
-``$OSGDIR`` is an environment variable that would correspond to::
+  if(osgWidget_FOUND AND NOT TARGET osgWidget::osgWidget)
+    add_library(osgWidget::osgWidget INTERFACE IMPORTED)
+    set_target_properties(
+      osgWidget::osgWidget
+      PROPERTIES
+        INTERFACE_INCLUDE_DIRECTORIES "${OSGWIDGET_INCLUDE_DIR}"
+        INTERFACE_LINK_LIBRARIES "${OSGWIDGET_LIBRARIES}"
+    )
+  endif()
 
-  ./configure --prefix=$OSGDIR
+  target_link_libraries(example PRIVATE osgWidget::osgWidget)
 
-used in building osg.
+See Also
+^^^^^^^^
 
-FindosgWidget.cmake tweaked from Findosg* suite as created by Eric
-Wing.
+* The :module:`FindOpenSceneGraph` module to find OpenSceneGraph toolkit.
 #]=======================================================================]
 
-# Header files are presumed to be included like
-# #include <osg/PositionAttitudeTransform>
-# #include <osgWidget/Widget>
+# FindosgWidget.cmake tweaked from Findosg* suite as created by Eric Wing.
 
 include(${CMAKE_CURRENT_LIST_DIR}/Findosg_functions.cmake)
 OSG_FIND_PATH   (OSGWIDGET osgWidget/Widget)