tools/checkmans.sh

   1 #!/bin/bash
   2 #
   3 # Find all man pages, and check they do not have groff syntax errors
   4 # or warnings.
   5 #
   6 # Sami Kerola <kerolasa@iki.fi>
   7
   8 set -e          # exit on errors
   9 set -o pipefail # exit if pipe writer fails
  10 set -u          # disallow usage of unset variables
  11 set -C          # disallow redirection file overwriting
  12 SCRIPT_INVOCATION_SHORT_NAME=$(basename ${0})
  13 trap 'echo "${SCRIPT_INVOCATION_SHORT_NAME}: exit on error"; exit 1' ERR
  14
  15 usage() {
  16         echo "Usage: ${0} [-vVh]"
  17         echo " -v  verbose messaging"
  18         echo " -V  print version and exit"
  19         echo " -h  print this help and exit"
  20 }
  21
  22 VERBOSE='false'
  23 while getopts vVh OPTIONS; do
  24         case ${OPTIONS} in
  25                 v)
  26                         VERBOSE='true'
  27                         ;;
  28                 V)
  29                         echo "util-linux: ${SCRIPT_INVOCATION_SHORT_NAME}: v2.1"
  30                         exit 0
  31                         ;;
  32                 h)
  33                         usage
  34                         exit 0
  35                         ;;
  36                 *)
  37                         usage
  38                         exit 1
  39         esac
  40 done
  41
  42 # Try to find missing manuals matching build targets with manual files.
  43 declare -A MAN_LIST BIN_LIST
  44
  45 declare -i ITER
  46 declare -i COUNT_GROG=0
  47 declare -i COUNT_TROFF=0
  48 declare -i COUNT_REPEATS=0
  49 declare -a REPEATS
  50 declare -A KNOWN_REPEATS
  51 KNOWN_REPEATS[mount.8]='foo l2 l c'
  52 KNOWN_REPEATS[hexdump.1]='l'
  53 KNOWN_REPEATS[flock.1]='"$0"'
  54 KNOWN_REPEATS[switch_root.8]='$DIR'
  55
  56 remove_repeats()
  57 {
  58         set +u
  59         for KN in ${KNOWN_REPEATS[${I##*/}]}; do
  60                 if [ "${KN}" = "${REPEATS[$1]}" ]; then
  61                         if $VERBOSE; then
  62                                 echo "info: ${I} removing repeat: ${REPEATS[$1]}"
  63                         fi
  64                         unset REPEATS[$1]
  65                 fi
  66         done
  67         set -u
  68 }
  69
  70 cd $(git rev-parse --show-toplevel)
  71
  72 for I in $(
  73         find . -type f -name '*[[:alpha:]].[1-8]' |grep -v "autom4te.cache\|\.libs/"
  74 ); do
  75         MAN_FILE=${I##*/}
  76         MAN_LIST[${MAN_FILE%%.[0-9]}]=1
  77         if awk '{if (1 < NR) {exit 1}; if ($1 ~ /^.so$/) {exit 0}}' ${I}; then
  78                 # Some manuals, such as x86_64, call inclusion and they
  79                 # should not be tested any further.
  80                 if ${VERBOSE}; then
  81                         printf "skipping: ${I}: includes "
  82                         awk '{print $2}' ${I}
  83                 fi
  84                 continue
  85         fi
  86         if ${VERBOSE}; then
  87                 echo "testing: ${I}"
  88         fi
  89         RET=1
  90         cat ${I} | troff -mandoc -ww -z |& grep "<" && RET=$?
  91         if [ $RET = 0 ]; then
  92         echo "From: cat ${I} | troff -mandoc -ww -z"
  93         echo "=================================================="
  94         ((++COUNT_TROFF))
  95         fi
  96         GROG=1
  97         if command -v lexgrog &> /dev/null; then
  98                 if ! lexgrog ${I} >/dev/null; then
  99                         echo "error: run: lexgrog ${I}"
 100                         echo "=================================================="
 101                         ((++COUNT_GROG))
 102                 fi
 103         elif command -v grog &> /dev/null; then
 104                 if ! grog ${I} | grep man >/dev/null; then
 105                         echo "error: grog ${I} is not a man file"
 106                         echo "=================================================="
 107                         ((++COUNT_GROG))
 108                 fi
 109         else
 110                 GROG=0
 111         fi
 112         REPEATS=( $(cat ${I} | troff -mandoc -Tascii 2>/dev/null | grotty |
 113                 col -b |
 114                 sed  -e 's/\s\+/\n/g; /^$/d' |
 115                 awk 'BEGIN { p="" } { if (0 < length($0)) { if (p == $0) { print } } p = $0 }') )
 116         if [ 0 -lt "${#REPEATS[@]}" ]; then
 117                 ITER=${#REPEATS[@]}+1
 118                 while ((ITER--)); do
 119                         remove_repeats ${ITER}
 120                 done
 121                 if [ 0 -lt "${#REPEATS[@]}" ]; then
 122                         echo "warning: ${I} has repeating words: ${REPEATS[@]}"
 123                         echo "=================================================="
 124                         ((++COUNT_REPEATS))
 125                 fi
 126         fi
 127 done
 128
 129 # Create a list of build targets.
 130 for I in $(find $(git rev-parse --show-toplevel) -name 'Make*.am' | xargs awk '
 131 $1 ~ /_SOURCES/ {
 132         if ($1 ~ /^test/ ||
 133             $1 ~ /^no(inst|dist)/ ||
 134             $1 ~ /^sample/ ||
 135             $1 ~ /^BUILT/) {
 136                 next
 137         }
 138         sub(/_SOURCES/, "")
 139         if ($1 ~ /^lib.*_la/) {
 140                 next
 141         }
 142         sub(/_static/, "")
 143         gsub(/_/, ".")
 144         sub(/switch.root/, "switch_root")
 145         sub(/pivot.root/, "pivot_root")
 146         print $1
 147 }'); do
 148         BIN_LIST[$I]=1
 149 done
 150
 151 # Find if build target does not have manual.
 152 set +u
 153 for I in ${!BIN_LIST[@]}; do
 154         if [ -v ${MAN_LIST[$I]} ]; then
 155                 echo "warning: ${SCRIPT_INVOCATION_SHORT_NAME}: ${I} does not have man page"
 156         fi
 157 done
 158 set -u
 159
 160 echo "${SCRIPT_INVOCATION_SHORT_NAME}: ${#BIN_LIST[*]} build targets were found"
 161 echo "${SCRIPT_INVOCATION_SHORT_NAME}: ${#MAN_LIST[*]} files were tested"
 162
 163 if [ ${GROG} = 0 ]; then
 164 echo "warning: neither grog nor lexgrog commands were found"
 165 fi
 166
 167 if [ ${COUNT_GROG} -ne 0 -o ${COUNT_TROFF} -ne 0 -o ${COUNT_REPEATS} -ne 0 ]; then
 168         echo "error: ${SCRIPT_INVOCATION_SHORT_NAME}: ${COUNT_GROG} files failed (lex)grog man-page test"
 169         echo "error: ${SCRIPT_INVOCATION_SHORT_NAME}: ${COUNT_TROFF} files failed troff parsing test"
 170         echo "error: ${SCRIPT_INVOCATION_SHORT_NAME}: ${COUNT_REPEATS} files have repeating words"
 171         ITER=${#MAN_LIST[*]}-${COUNT_GROG}-${COUNT_TROFF}-${COUNT_REPEATS}
 172         echo "${SCRIPT_INVOCATION_SHORT_NAME}: ${ITER} man-pages approved"
 173         exit 1
 174 fi
 175
 176 if ! ${VERBOSE}; then
 177         echo "${SCRIPT_INVOCATION_SHORT_NAME}: success"
 178 fi
 179
 180 exit 0