From 514c4e72c9d629f8bb8255307feb7fcd0d533e42 Mon Sep 17 00:00:00 2001
From: Peter Kokot <peterkokot@gmail.com>
Date: Sun, 6 Apr 2025 20:18:50 +0200
Subject: [PATCH] FindOpenSP: Update documentation

- Added examples section.
- Synced descriptions a bit with other find modules.
- Moved imported targets to top.
- Updated project URL to https.
---
 Modules/FindOpenSP.cmake | 97 +++++++++++++++++++++++-----------------
 1 file changed, 55 insertions(+), 42 deletions(-)

diff --git a/Modules/FindOpenSP.cmake b/Modules/FindOpenSP.cmake
index 605c294a3a..3ff6a99a48 100644
--- a/Modules/FindOpenSP.cmake
+++ b/Modules/FindOpenSP.cmake
@@ -7,60 +7,73 @@ FindOpenSP
 
 .. versionadded:: 3.25
 
-Try to find the OpenSP library.
-
-Result Variables
-^^^^^^^^^^^^^^^^
-
-This will define the following variables:
-
-``OpenSP_FOUND``
-  True if (the requested version of) ``OpenSP`` is available
-
-``OpenSP_VERSION``
-  The version of ``OpenSP``
-
-``OpenSP_VERSION_MAJOR``
-  The major version of ``OpenSP``
-
-``OpenSP_VERSION_MINOR``
-  The minor version of ``OpenSP``
-
-``OpenSP_VERSION_PATCH``
-  The patch version of ``OpenSP``
-
-``OpenSP_INCLUDE_DIRS``
-  The include dirs of ``OpenSP`` with its headers
-
-``OpenSP_LIBRARIES``
-  The OpenSP library for use with target_link_libraries().
-  This can be passed to target_link_libraries() instead of
-  the :prop_tgt:`IMPORTED` ``OpenSP::OpenSP`` target
-
-``OpenSP_MULTI_BYTE``
-  True if ``SP_MULTI_BYTE`` was found to be defined in OpenSP's ``config.h``
-  header file, which indicates that the ``OpenSP`` library was compiled with
-  support for multi-byte characters. The consuming target needs to define the
-  ``SP_MULTI_BYTE`` to match this value in order to avoid issues with character
-  decoding.
+Finds the OpenSP library.  OpenSP is an open-source implementation of the SGML
+(Standard Generalized Markup Language) parser.
 
 Imported Targets
 ^^^^^^^^^^^^^^^^
 
-This module defines the :prop_tgt:`IMPORTED` target ``OpenSP::OpenSP``, if
-OpenSP has been found.
+This module provides the following :ref:`Imported Targets`:
 
-Cache variables
+``OpenSP::OpenSP``
+  Target encapsulating the OpenSP library usage requirements, available only if
+  the OpenSP is found.
+
+Result Variables
+^^^^^^^^^^^^^^^^
+
+This module defines the following variables:
+
+``OpenSP_FOUND``
+  Boolean indicating whether the (requested version of) OpenSP is available.
+
+``OpenSP_VERSION``
+  The version of found OpenSP.
+
+``OpenSP_VERSION_MAJOR``
+  The major version of OpenSP.
+
+``OpenSP_VERSION_MINOR``
+  The minor version of OpenSP.
+
+``OpenSP_VERSION_PATCH``
+  The patch version of OpenSP.
+
+``OpenSP_INCLUDE_DIRS``
+  The include directories containing headers needed to use the OpenSP library.
+
+``OpenSP_LIBRARIES``
+  Libraries required to link against to use OpenSP.  These can be passed to the
+  :command:`target_link_libraries` command when not using the ``OpenSP::OpenSP``
+  imported target.
+
+Cache Variables
 ^^^^^^^^^^^^^^^
 
 The following cache variables may also be set:
 
 ``OpenSP_INCLUDE_DIR``
-  the OpenSP include directory
+  The OpenSP include directory.
 
 ``OpenSP_LIBRARY``
-  the absolute path of the osp library
+  The absolute path of the ``osp`` library.
 
+``OpenSP_MULTI_BYTE``
+  True if ``SP_MULTI_BYTE`` was found to be defined in OpenSP's ``config.h``
+  header file, which indicates that the OpenSP library was compiled with support
+  for multi-byte characters.  The consuming target needs to define the
+  ``SP_MULTI_BYTE`` preprocessor macro to match this value in order to avoid
+  issues with character decoding.
+
+Examples
+^^^^^^^^
+
+Finding the OpenSP library and linking it to a project target:
+
+.. code-block:: cmake
+
+  find_package(OpenSP)
+  target_link_libraries(project_target PRIVATE OpenSP::OpenSP)
 #]=======================================================================]
 
 cmake_policy(PUSH)
@@ -157,7 +170,7 @@ endif ()
 
 include(FeatureSummary)
 set_package_properties(OpenSP PROPERTIES
-  URL "http://openjade.sourceforge.net/doc/index.htm"
+  URL "https://openjade.sourceforge.net/doc/index.htm"
   DESCRIPTION "An SGML System Conforming to International Standard ISO 8879"
   )