[doc] CMake: generate man pages from Perl files

Generate manual pages from the Perl programs and modules in the scripts/
directory, thanks to pod2man.

cmake/Modules/FindPod2man.cmake

@@ -0,0 +1,22 @@
+# This file is part of the Owl Positioning System (OwlPS) project.
+# It is subject to the copyright notice and license terms in the
+# COPYRIGHT.t2t file found in the top-level directory of this
+# distribution and at
+#   http://code.lm7.fr/p/owlps/source/tree/master/COPYRIGHT.t2t
+# No part of the OwlPS Project, including this file, may be copied,
+# modified, propagated, or distributed except according to the terms
+# contained in the COPYRIGHT.t2t file; the COPYRIGHT.t2t file must be
+# distributed along with this file, either separately or by replacing
+# this notice by the COPYRIGHT.t2t file's contents.
+
+# This module tries to find the txt2tags executable and sets the
+# following variables:
+#   POD2MAN_EXECUTABLE
+#   POD2MAN_FOUND
+
+# Search for the executable
+find_program(POD2MAN_EXECUTABLE pod2man)
+
+# Did we find it?
+FIND_PACKAGE_HANDLE_STANDARD_ARGS(Pod2man DEFAULT_MSG
+  POD2MAN_EXECUTABLE)

doc/CMakeLists.txt

@@ -62,6 +62,60 @@ else()
 endif()
 
 
+### pod2man-generated man pages ###
+
+find_package(Pod2man)
+if (NOT POD2MAN_FOUND)
+  message(WARNING
+    "Couldn't find pod2man: disabling generation of man pages for Perl programs")
+else()
+
+  function(add_pod_manpage SOURCE PAGENAME SECTION)
+    set(OUTPUT_DIRECTORY "${MAN_OUTPUT_DIRECTORY}/man${SECTION}")
+    set(TARGETNAME "${PAGENAME}.${SECTION}")
+    # Change TARGETNAME so that the CMake target don't contain any ':'
+    string(REGEX REPLACE ":" "-" TARGETNAME ${TARGETNAME})
+    set(TARGET "${OUTPUT_DIRECTORY}/${TARGETNAME}")
+
+    # Create the output directory
+    # Note: this is done only when first calling cmake and when rebuilding
+    # cache; it would be nice if it could be called every time, but there
+    # doesn't seem to be any simple solution.
+    file(MAKE_DIRECTORY "${OUTPUT_DIRECTORY}")
+
+    # Get source file last modification date from the git history
+    execute_process(
+      COMMAND git log -1 --pretty=%ai "${SOURCE}"
+      WORKING_DIRECTORY "${CMAKE_SOURCE_DIR}"
+      RESULT_VARIABLE RET
+      OUTPUT_VARIABLE DATE
+      ERROR_QUIET
+      OUTPUT_STRIP_TRAILING_WHITESPACE)
+    # Take only the first field (the date without the time)
+    string(REGEX REPLACE " .*" "" DATE ${DATE})
+
+    # Command to generate the man page
+    add_custom_command(
+      OUTPUT "${TARGET}"
+      COMMAND "${POD2MAN_EXECUTABLE}" --center "OwlPS User Manual" --release "OwlPS ${OWLPS_VERSION}" --date "${DATE}" "${SOURCE}" "${TARGET}"
+      DEPENDS "${SOURCE}"
+      COMMENT "Generating ${TARGETNAME}")
+
+    # Set up the target
+    add_custom_target("${TARGETNAME}" true DEPENDS "${TARGET}")
+
+    # Add the target to the "doc" meta-target
+    add_dependencies(doc "${TARGETNAME}")
+  endfunction()
+
+  add_pod_manpage(${CMAKE_SOURCE_DIR}/scripts/owlps-aggcheck.pl owlps-aggcheck 1)
+  add_pod_manpage(${CMAKE_SOURCE_DIR}/scripts/owlps-aggsetcoord.pl owlps-aggsetcoord 1)
+  add_pod_manpage(${CMAKE_SOURCE_DIR}/scripts/OwlPS/CSV.pm OwlPS::CSV 3perl)
+  add_pod_manpage(${CMAKE_SOURCE_DIR}/scripts/OwlPS/TimeInterpolation.pm OwlPS::TimeInterpolation 3perl)
+
+endif()
+
+
 ### Doxygen-generated man pages ###
 
 if (NOT DOXYGEN_FOUND)