In order to ease the job of keeping the documentations up to date, there is
a new script 'check-cmdline-options' that checks a program's options (with
the '--help' option) and compare them with its documentation (the manual
page) to make sure everything is aligned.
This is triggered with "make check" for wmaker.
Signed-off-by: Christophe CURIS <christophe.cu...@free.fr>
---
Makefile.am | 1 +
doc/Makefile.am | 13 +++
script/check-cmdline-options-doc.sh | 156 ++++++++++++++++++++++++++++++++++++
3 files changed, 170 insertions(+)
create mode 100755 script/check-cmdline-options-doc.sh
diff --git a/Makefile.am b/Makefile.am
index 2357d24..071d13f 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -38,6 +38,7 @@ EXTRA_DIST = TODO BUGS BUGFORM FAQ INSTALL \
The-perfect-Window-Maker-patch.txt \
README COPYING.WTFPL autogen.sh \
email-clients.txt checkpatch.pl update-changelog.pl \
+ script/check-cmdline-options-doc.sh \
script/check-translation-sources.sh \
script/generate-mapfile-from-header.sh \
script/generate-po-from-template.sh \
diff --git a/doc/Makefile.am b/doc/Makefile.am
index f39079c..db69f90 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -25,3 +25,16 @@ man_MANS = \
EXTRA_DIST = $(man_MANS)
+# Create a 'silent rule' for our make check the same way automake does
+AM_V_CHKOPTS = $(am__v_CHKOPTS_$(V))
+am__v_CHKOPTS_ = $(am__v_CHKOPTS_$(AM_DEFAULT_VERBOSITY))
+am__v_CHKOPTS_0 = @echo " CHK $@" ;
+am__v_CHKOPTS_1 =
+
+check-local: wmaker-args
+
+wmaker-args:
+ $(AM_V_CHKOPTS)$(top_srcdir)/script/check-cmdline-options-doc.sh \
+ --program "$(top_builddir)/src/wmaker" --man-page
"$(top_srcdir)/doc/wmaker.1x"
+
+.PHONY: wmaker-args
diff --git a/script/check-cmdline-options-doc.sh
b/script/check-cmdline-options-doc.sh
new file mode 100755
index 0000000..d2aa173
--- /dev/null
+++ b/script/check-cmdline-options-doc.sh
@@ -0,0 +1,156 @@
+#!/bin/sh
+###########################################################################
+#
+# Window Maker window manager
+#
+# Copyright (c) 2015 Christophe CURIS
+# Copyright (c) 2015 Window Maker Team
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License along
+# with this program; if not, write to the Free Software Foundation, Inc.,
+# 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+#
+###########################################################################
+#
+# check-cmdline-options-doc.sh:
+# Compare the options listed in a program's --help text against its
+# documentation, check that all options are described and that there are
+# not deprecated options in the doc.
+#
+# A know limitation is that it assumes the help text from the program is
+# in line with what the program actually supports, because it would be too
+# complicated to actually check also in the sources the supported options.
+#
+###########################################################################
+#
+# For portability, we stick to the same sh+sed constraint as Autotools to
+# limit problems, see for example:
+#
http://www.gnu.org/software/autoconf/manual/autoconf-2.69/html_node/Portable-Shell.html
+#
+###########################################################################
+
+# Report an error on stderr and exit with status 2 to tell make that we could
+# not do what we were asked
+arg_error() {
+ echo "`basename $0`: $@" >&2
+ exit 2
+}
+
+# print help and exit with success status
+print_help() {
+ echo "$0: check program's list of options against its documentation"
+ echo "Usage: $0 options..."
+ echo "valid options are:"
+ echo " --man-page file : program's documentation file, in man format"
+ echo " --program name : name of the program to run with '--help'"
+ exit 0
+}
+
+# Extract command line arguments
+while [ $# -gt 0 ]; do
+ case $1 in
+ --man-page)
+ shift
+ [ -z "$man_page" ] || arg_error "only 1 documentation file can be
used (option: --man-page)"
+ man_page="$1"
+ ;;
+
+ --program)
+ shift
+ [ -z "$prog_name" ] || arg_error "only 1 program can be used
(option: --program)"
+ prog_name="$1"
+ ;;
+
+ -h|-help|--help) print_help ;;
+ -*) arg_error "unknow option '$1'" ;;
+
+ *)
+ arg_error "argument '$1' is not understood"
+ ;;
+ esac
+ shift
+done
+
+# Check consistency of command-line
+[ -z "$prog_name" ] && arg_error "no program given (option: --program)"
+[ -z "$man_page" ] && arg_error "no documentation given"
+
+[ -z "$man_page" ] || [ -r "$man_page" ] || arg_error "man page file
'$man_page' is not readable (option: --man-page)"
+
+# Make sure the program will not be searched in $PATH
+if ! echo "$prog_name" | grep '/' > /dev/null ; then
+ prog_name="./$prog_name"
+fi
+
+[ -x "$prog_name" ] || arg_error "program '$prog_name' does not exist or is
not executable"
+
+# Get the list of options that the program claims it supports
+# -----------------------------------------------------------
+# We suppose (it is common practice) that the options are listed one per line
+# with no other text at the beginning of the line
+# If the line contains both a short option followed by a long option, we keep
only the long
+# option because it is better to check for it
+prog_options=`$prog_name --help | sed -n '/^[ \t]*-/ { s/^[ \t]*// ;
s/^-[^-],[ \t]*--/--/ ; s/[^-A-Z_a-z0-9].*$// ; p }' `
+
+[ "x$prog_options" = "x" ] && arg_error "program '$prog_name --help' did not
return any option"
+
+
+if [ -n "$man_page" ]; then
+ # In the man page format, the options must be grouped in the section
"OPTIONS"
+ # The name of the option is on the first line after the '.TP' command
+ # The format requires the use of a backslash before the dash ('\-')
+ sed_script='/^\.SH[ \t]*"*OPTIONS"*/,/^\.SH/ {
+ /^\.TP/ {
+ n
+ s/^\.[A-Z]*//
+ s/^[ \t]*//
+ s/^\([^ \t]*\)[ \t].*$/\1/
+ s/\\-/-/g
+ p
+ }
+ }'
+ doc_options=`sed -n "$sed_script" "$man_page" `
+fi
+
+# If no problem is found, we will exit with status OK
+exit_status=0
+
+# Check that all program options are documented
+for opt in $prog_options
+do
+ if ! echo "$doc_options" | grep "^$opt\$" > /dev/null ; then
+ echo "Error: program option '$opt' is not in the documentation '$man_page'"
+ exit_status=1
+ fi
+done
+
+# Check that all documentation options are listed by the program
+for opt in $doc_options
+do
+ if ! echo "$prog_options" | grep "^$opt\$" > /dev/null ; then
+ echo "Error: option '$opt' is documented, but not in '$prog_name --help'"
+ exit_status=1
+ fi
+done
+
+# It is recommended to list options in alphabetical order because it is then
+# easier to search for one
+if [ -n "$man_page" ]; then
+ if ! echo "$doc_options" | sed -e 's/^-*//' | sort -c ; then
+ echo "Error: options are not sorted alphabetically in '$man_page'"
+ exit_status=1
+ fi
+fi
+
+# exit with appropriate return code, wether discrepancies were found or not
+exit $exit_status
--
2.1.4
--
To unsubscribe, send mail to wmaker-dev-unsubscr...@lists.windowmaker.org.
