Use Markdown in CMake module headers

For now Markdown is picked due to its syntax simplicity but can be
replaced in the future with RST if such need comes.

Module headers are parsed by script and Markdown files are generated
for easier documentation reading.

Author: petk

cmake/cmake/modules/PHP/ConfigureFile.cmake

@@ -2,28 +2,33 @@
 Wrapper built on top of CMake's configure_file().
 
 There is a common issue with installation prefix not being applied when using
---prefix command line option at the installation phase:
-  cmake --install <build-dir> --prefix <prefix>
+`--prefix` command-line option at the installation phase:
+
+```sh
+cmake --install <build-dir> --prefix <prefix>
+```
 
 The following function is exposed:
 
+```cmake
 php_configure_file(
   <template-file>
   <file-output>
   [INSTALL_DESTINATION <path>]
   [VARIABLES [<variable> <value>] ...]
 )
-
-  INSTALL_DESTINATION
-    Path to the directory where the generated file <file-output> will be
-    installed to. If not provided, <file-output> will not be installed.
-  VARIABLES
-    Pairs of variable names and values.
-
-    The $<INSTALL_PREFIX> generator expression can be used in variable values,
-    which is replaced with installation prefix either set via the
-    CMAKE_INSTALL_PREFIX variable at the configuration phase, or the
-    '--prefix' option at the 'cmake --install' phase.
+```
+
+* `INSTALL_DESTINATION`
+  Path to the directory where the generated file `<file-output>` will be
+  installed to. If not provided, `<file-output>` will not be installed.
+* `VARIABLES`
+  Pairs of variable names and values.
+
+  The `$<INSTALL_PREFIX>` generator expression can be used in variable values,
+  which is replaced with installation prefix either set via the
+  `CMAKE_INSTALL_PREFIX` variable at the configuration phase, or the `--prefix`
+  option at the `cmake --install` phase.
 #]=============================================================================]
 
 include_guard(GLOBAL)

cmake/cmake/modules/PHP/PkgConfigGenerator.cmake

@@ -6,11 +6,15 @@ pc files with getting clean linked libraries retrieved from the targets:
 https://gitlab.kitware.com/cmake/cmake/-/issues/22621
 
 Also there is a common issue with installation prefix not being applied when
-using --prefix command line option at the installation phase:
-  cmake --install <build-dir> --prefix <prefix>
+using `--prefix` command-line option at the installation phase:
+
+```sh
+cmake --install <build-dir> --prefix <prefix>
+```
 
 The following function is exposed:
 
+```cmake
 pkgconfig_generate_pc(
   <pc-template-file>
   <pc-file-output>
@@ -19,36 +23,40 @@ pkgconfig_generate_pc(
   [VARIABLES [<variable> <value>] [<variable_2>:BOOL <value_2>...] ...]
   [SKIP_BOOL_NORMALIZATION]
 )
-
-  Generate pkgconfig <pc-file-output> from the given pc <pc-template-file>
-  template.
-
-  TARGET
-    Name of the target for getting libraries.
-  INSTALL_DESTINATION
-    Path to the pkgconfig directory where generated .pc file will be installed
-    to. Usually it is '${CMAKE_INSTALL_LIBDIR}/pkgconfig'. If not provided, .pc
-    file will not be installed.
-  VARIABLES
-    Pairs of variable names and values. To pass booleans, append ':BOOL' to the
-    variable name. For example:
-      pkgconfig_generate_pc(
-        ...
-        VARIABLES
-          variable_name:BOOL "${variable_name}"
-      )
-
-    The $<INSTALL_PREFIX> generator expression can be used in variable values,
-    which is replaced with installation prefix either set via the
-    CMAKE_INSTALL_PREFIX variable at the configuration phase, or the
-    '--prefix' option at the 'cmake --install' phase.
-
-  SKIP_BOOL_NORMALIZATION
-    CMake booleans have values yes, no, true, false, on, off, 1, 0, they can
-    even be case insensitive and so on. By default, all booleans (var:BOOL see
-    above) are normalized to values "yes" or "no". If this option is given,
-    boolean values are replaced in .pc template with the CMake format instead
-    (they will be replaced to 'ON' or 'OFF' and similar).
+```
+
+Generate pkgconfig `<pc-file-output>` from the given pc `<pc-template-file>`
+template.
+
+* `TARGET`
+  Name of the target for getting libraries.
+* `INSTALL_DESTINATION`
+  Path to the pkgconfig directory where generated .pc file will be installed to.
+  Usually it is `${CMAKE_INSTALL_LIBDIR}/pkgconfig`. If not provided, .pc file
+  will not be installed.
+* `VARIABLES`
+  Pairs of variable names and values. To pass booleans, append ':BOOL' to the
+  variable name. For example:
+
+  ```cmake
+  pkgconfig_generate_pc(
+    ...
+    VARIABLES
+      variable_name:BOOL "${variable_name}"
+  )
+  ```
+
+  The `$<INSTALL_PREFIX>` generator expression can be used in variable values,
+  which is replaced with installation prefix either set via the
+  `CMAKE_INSTALL_PREFIX` variable at the configuration phase, or the `--prefix`
+  option at the `cmake --install` phase.
+
+* `SKIP_BOOL_NORMALIZATION`
+  CMake booleans have values `yes`, `no`, `true`, `false`, `on`, `off`, `1`,
+  `0`, they can even be case insensitive and so on. By default, all booleans
+  (`var:BOOL`, see above) are normalized to values `yes` or `no`. If this option
+  is given, boolean values are replaced in .pc template with the CMake format
+  instead (they will be replaced to `ON` or `OFF` and similar).
 #]=============================================================================]
 
 include_guard(GLOBAL)