OS-1354 need tool to check for missing manual pages for binaries

tools/checks/mancheck

@@ -0,0 +1,203 @@
+#!/bin/bash
+#
+# CDDL HEADER START
+#
+# The contents of this file are subject to the terms of the
+# Common Development and Distribution License (the "License").
+# You may not use this file except in compliance with the License.
+#
+# You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
+# or http://www.opensolaris.org/os/licensing.
+# See the License for the specific language governing permissions
+# and limitations under the License.
+#
+# When distributing Covered Code, include this CDDL HEADER in each
+# file and include the License file at usr/src/OPENSOLARIS.LICENSE.
+# If applicable, add the following below this CDDL HEADER, with the
+# fields enclosed by brackets "[]" replaced with your own identifying
+# information: Portions Copyright [yyyy] [name of copyright owner]
+#
+# CDDL HEADER END
+#
+# Copyright (c) 2012 Joyent, Inc.
+#
+
+#
+# This tool ensures that no man page is left behind. We want to audit the
+# traditional paths where user binaries are delivered and ensure that we section
+# 1 and section 1m man pages for all of them.
+#
+
+unalias -a
+
+cm_arg0=$(basename $0)
+cm_root="$(dirname $0)/../.."
+
+#
+# Location of the manifest file
+#
+cm_manifest=
+
+#
+# List of paths to check for binaries
+#
+cm_bpaths="bin usr/bin sbin usr/sbin smartdc/bin"
+
+#
+# List of directories with man pages. Note the directory *must* end with a
+# trailing /.
+#
+cm_mpaths="$cm_root/proto/usr/share/man/ $cm_root/man/man/"
+
+#
+# The base dir that we expect man pages to be in. Note there is no leading /
+# because our manifest does not contain them.
+#
+cm_pdir="usr/share/man"
+
+#
+# Temporary variable for passing around manual pages
+#
+cm_mpages=
+
+cm_nenoent=0
+cm_nenoship=0
+
+function usage
+{
+	local msg="$*"
+	[[ -z "$msg" ]] && echo "$msg"
+	cat <<USAGE >&2
+Usage: $cm_arg0 -f manifest
+
+Validate that all binaries mentioned in \`manifest\` have man pages and that they
+are present in \`manifest\`.
+
+	-f manifest	Manifest file to search
+	-h		Show this message
+USAGE
+	exit 2
+}
+
+function fail
+{
+	local msg="$*"
+	[[ -z "$msg" ]] && msg="failed"
+	echo "$cm_arg0: $msg" >&2
+	exit 1
+}
+
+#
+# Validate if we have the binary
+#
+function valid_binary
+{
+	local mode file valid p
+	mode=$1
+	file=$2
+	valid=
+
+	if [[ "$mode" == "f" ]]; then
+		for p in $cm_bpaths; do
+			[[ ! "$file" =~ ^$p/[A-Za-z0-9_-]*$ ]] && continue
+			valid="y"
+		done
+	elif [[ "$mode" == "h" || "$mode" == "s" ]]; then
+		file=${file%=*}
+		for p in $cm_bpaths; do
+			[[ ! "$file" =~ ^$p/[A-Za-z0-9_-]*$ ]] && continue
+			valid="y"
+		done
+	fi
+
+	cm_bfile=$file	
+	[[ ! -z "$valid" ]]
+}
+
+#
+# See if the man page exists in our man page search path
+#
+function check_man
+{
+	local file=$1
+	local p m pages
+
+	file=${file##*/}
+
+	cm_mpages=""
+	for p in $cm_mpaths; do
+		pages=$(ls $p*/$file.1* 2>/dev/null)
+		if [[ $? -eq 0 ]]; then
+			for m in $pages; do
+				[[ ! $m =~ \.(1|1m)$ ]] && continue
+				cm_mpages="${m/$p} $cm_mpages"
+			done
+			break
+		fi
+	done
+
+	[[ ! -z "$cm_mpages" ]]
+}
+
+#
+# Validate that the files are actually being shipped
+#
+function check_ship
+{
+	local pages=$1
+	local p
+
+	cm_mpages=""
+	for p in $pages; do
+		grep "$cm_pdir/$p" $cm_manifest 2>/dev/null >/dev/null
+		if [[ $? -ne 0 ]]; then
+			cm_mpages="$p $cm_mpages"
+		fi
+	done
+
+	[[ -z "$cm_mpages" ]]
+}
+
+while getopts "f:i" c $@; do
+	case "$c" in
+	f)
+		cm_manifest=$OPTARG
+		;;
+	h)
+		usage
+		;;
+	:)
+		usage "missing required argument -- $OPTARG"
+		;;
+	*)
+		usage "invalid option: $OPTARG"
+		;;
+	esac
+done
+
+[[ -z "$cm_manifest" ]] && fail "missing manifest file"
+[[ -f "$cm_manifest" ]] || fail "unable to read $cm_manifest"
+
+while read mode file rest; do
+	valid_binary $mode $file || continue
+	file=${file%=*}
+	if ! check_man $file; then
+		echo "missing manual page for: /$file"
+		((cm_nenoent++))
+		continue
+	fi
+	if ! check_ship $cm_mpages; then
+		for p in $cm_mpages; do
+			echo "binary /$file has unshipped manual page: $p"
+			((cm_nenoship++))
+		done
+	fi
+done < $cm_manifest
+
+if [[ $cm_nenoent -gt 0 || $cm_nenoship -gt 0 ]]; then
+	echo "missing manual pages: $cm_nenoent"
+	echo "unshipped manual pages: $cm_nenoship"
+	exit 1
+fi
+
+exit 0