Add bash script to convert builtin help to reStructuredText

Create a convert-help.bash script to extract builtin documentation as
reStructuredText sources in a new Help directory.  Run each executable
with the --help-full option targeting a .rst file to extract the
documentation.  Generate Sphinx "toctree" directives to point each man
page at the corresponding documents it should contain.  Organize
cmake-commands(7), cmake-properties(7), and cmake-variables(7) man pages
into sections similar to those generated by --help-properties and
--help-variables output previously.

convert-help.bash

@@ -0,0 +1,306 @@
+#!/usr/bin/env bash
+
+if test $# -ne 1; then
+  echo 1>&2 'Specify cmake executable directory'
+  exit 1
+fi &&
+bin="$1" &&
+
+# Extract .rst documentation and generate man section 1 pages
+mkdir -p Help/manual &&
+cd Help &&
+mkdir tmp && cd tmp &&
+"$bin"/cmake --help-full ../manual/cmake.1.rst &&
+tar c * | (cd .. && tar x) &&
+cd .. && rm -rf tmp &&
+sed -i '1 i\
+cmake(1)\
+********\
+
+' manual/cmake.1.rst &&
+mkdir tmp && cd tmp &&
+"$bin"/ctest --help-full ../manual/ctest.1.rst &&
+mv command/ctest_*.rst ../command &&
+cd .. && rm -rf tmp &&
+sed -i '1 i\
+ctest(1)\
+********\
+
+' manual/ctest.1.rst &&
+mkdir tmp && cd tmp &&
+"$bin"/cpack --help-full ../manual/cpack.1.rst &&
+mv variable ../var_cpack &&
+cd .. && rm -rf tmp &&
+sed -i '1 i\
+cpack(1)\
+********\
+
+' manual/cpack.1.rst &&
+mkdir tmp && cd tmp &&
+"$bin"/ccmake --help-full ../manual/ccmake.1.rst &&
+cd .. && rm -rf tmp &&
+sed -i '1 i\
+ccmake(1)\
+*********\
+
+' manual/ccmake.1.rst &&
+mkdir tmp && cd tmp &&
+"$bin"/cmake-gui --help-full ../manual/cmake-gui.1.rst &&
+cd .. && rm -rf tmp &&
+sed -i '1 i\
+cmake-gui(1)\
+************\
+
+' manual/cmake-gui.1.rst &&
+
+# Remove trailing whitespace and blank lines
+find . -name '*.rst' |
+while read f; do
+  sed -e 's/[ \t]*$//' -i "$f" &&
+  sed -e ':a' -e '/^\n*$/ {$d;N;ba;}' -i "$f"
+done
+
+# Generate man section 7 pages
+{
+deprecated_commands=$(
+cat <<EOF
+   /command/build_name
+   /command/exec_program
+   /command/export_library_dependencies
+   /command/install_files
+   /command/install_programs
+   /command/install_targets
+   /command/link_libraries
+   /command/make_directory
+   /command/output_required_files
+   /command/remove
+   /command/subdir_depends
+   /command/subdirs
+   /command/use_mangled_mesa
+   /command/utility_source
+   /command/variable_requires
+   /command/write_file
+EOF
+) &&
+cat <<EOF &&
+cmake-commands(7)
+*****************
+
+.. only:: html or latex
+
+   .. contents::
+
+Normal Commands
+===============
+
+These commands may be used freely in CMake projects.
+
+.. toctree::
+EOF
+echo "$deprecated_commands" > tmp &&
+ls command/*.rst |sort|sed 's|^|   /|;s|\.rst$||' |
+grep -v /command/ctest_ | grep -v -x -F -f tmp &&
+rm tmp &&
+cat <<EOF &&
+
+Deprecated Commands
+===================
+
+These commands are available only for compatibility with older
+versions of CMake.  Do not use them in new code.
+
+.. toctree::
+$deprecated_commands
+
+CTest Commands
+==============
+
+These commands are available only in ctest scripts.
+
+.. toctree::
+EOF
+ls command/*.rst |sort|sed 's|^|   /|;s|\.rst$||' | grep /command/ctest_
+} > manual/cmake-commands.7.rst &&
+{
+cat <<EOF &&
+cmake-generators(7)
+*******************
+
+.. only:: html or latex
+
+   .. contents::
+
+All Generators
+==============
+
+.. toctree::
+EOF
+ls generator/*.rst |sort|sed 's|^|   /|;s|\.rst$||'
+} > manual/cmake-generators.7.rst &&
+{
+cat <<EOF &&
+cmake-modules(7)
+****************
+
+.. only:: html or latex
+
+   .. contents::
+
+All Modules
+===========
+
+.. toctree::
+EOF
+ls module/*.rst    |sort|sed 's|^|   /|;s|\.rst$||'
+} > manual/cmake-modules.7.rst &&
+{
+cat <<EOF &&
+cmake-policies(7)
+*****************
+
+.. only:: html or latex
+
+   .. contents::
+
+All Policies
+============
+
+.. toctree::
+EOF
+ls policy/*.rst    |sort|sed 's|^|   /|;s|\.rst$||'
+} > manual/cmake-policies.7.rst &&
+{
+cat <<EOF &&
+cmake-properties(7)
+*******************
+
+.. only:: html or latex
+
+   .. contents::
+
+Properties of Global Scope
+==========================
+
+.. toctree::
+EOF
+ls prop_gbl/*.rst  |sort|sed 's|^|   /|;s|\.rst$||' &&
+cat <<EOF &&
+
+Properties on Directories
+=========================
+
+.. toctree::
+EOF
+ls prop_dir/*.rst  |sort|sed 's|^|   /|;s|\.rst$||' &&
+cat <<EOF &&
+
+Properties on Targets
+=====================
+
+.. toctree::
+EOF
+ls prop_tgt/*.rst  |sort|sed 's|^|   /|;s|\.rst$||' &&
+cat <<EOF &&
+
+Properties on Tests
+===================
+
+.. toctree::
+EOF
+ls prop_test/*.rst |sort|sed 's|^|   /|;s|\.rst$||' &&
+cat <<EOF &&
+
+Properties on Source Files
+==========================
+
+.. toctree::
+EOF
+ls prop_sf/*.rst   |sort|sed 's|^|   /|;s|\.rst$||' &&
+cat <<EOF &&
+
+Properties on Cache Entries
+===========================
+
+.. toctree::
+EOF
+ls prop_cache/*.rst|sort|sed 's|^|   /|;s|\.rst$||'
+} > manual/cmake-properties.7.rst &&
+{
+cat <<EOF &&
+cmake-variables(7)
+******************
+
+.. only:: html or latex
+
+   .. contents::
+
+Variables that Provide Information
+==================================
+
+.. toctree::
+EOF
+ls var_info/*.rst  |sort|sed 's|^|   /|;s|var_info/|variable/|;s|\.rst$||' &&
+cat <<EOF &&
+
+Variables that Change Behavior
+==============================
+
+.. toctree::
+EOF
+ls var_cmake/*.rst |sort|sed 's|^|   /|;s|var_cmake/|variable/|;s|\.rst$||' &&
+cat <<EOF &&
+
+Variables that Describe the System
+==================================
+
+.. toctree::
+EOF
+ls var_sys/*.rst   |sort|sed 's|^|   /|;s|var_sys/|variable/|;s|\.rst$||' &&
+cat <<EOF &&
+
+Variables that Control the Build
+================================
+
+.. toctree::
+EOF
+ls var_build/*.rst |sort|sed 's|^|   /|;s|var_build/|variable/|;s|\.rst$||' &&
+cat <<EOF &&
+
+Variables for Languages
+=======================
+
+.. toctree::
+EOF
+ls var_lang/*.rst  |sort|sed 's|^|   /|;s|var_lang/|variable/|;s|\.rst$||' &&
+cat <<EOF &&
+
+Variables for CPack
+===================
+
+.. toctree::
+EOF
+ls var_cpack/*.rst |sort|sed 's|^|   /|;s|var_cpack/|variable/|;s|\.rst$||'
+} > manual/cmake-variables.7.rst &&
+mkdir variable &&
+mv var_*/* variable &&
+rmdir var_* &&
+cd .. &&
+
+# Move module help back into .cmake module file comments
+(cd Help/module && ls *.rst) |
+while read m; do
+  dm="Help/module/$m" &&
+  cm="Modules/${m%.rst}.cmake" &&
+  {
+    echo '#.rst:' &&
+    sed -e '
+    /^./ s/^/# /
+    /^$/ c #
+    s/  *$//
+    ' "$dm" &&
+    echo '' &&
+    sed -e '1,/^$/d' "$cm"
+  } >"$cm.new" &&
+  mv "$cm.new" "$cm" &&
+  echo ".. cmake-module:: ../../$cm" > "$dm"
+done