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 overlay'
  52 KNOWN_REPEATS[hexdump.1]='l'
  53 KNOWN_REPEATS[flock.1]='"$0"'
  54 KNOWN_REPEATS[switch_root.8]='$DIR'
  55 KNOWN_REPEATS[logger.1]='-'
  56
  57 remove_repeats()
  58 {
  59         set +u
  60         for KN in ${KNOWN_REPEATS[${I##*/}]}; do
  61                 if [ "${KN}" = "${REPEATS[$1]}" ]; then
  62                         if $VERBOSE; then
  63                                 echo "info: ${I} removing repeat: ${REPEATS[$1]}"
  64                         fi
  65                         unset REPEATS[$1]
  66                 fi
  67         done
  68         set -u
  69 }
  70
  71 cd $(git rev-parse --show-toplevel)
  72
  73 for I in $(
  74         find . -type f -name '*[[:alpha:]].[1-8]' |grep -v "autom4te.cache\|\.libs/\|\.git"
  75 ); do
  76         MAN_FILE=${I##*/}
  77         MAN_LIST[${MAN_FILE%%.[0-9]}]=1
  78         if awk '{if (1 < NR) {exit 1}; if ($1 ~ /^.so$/) {exit 0}}' ${I}; then
  79                 # Some manuals, such as x86_64, call inclusion and they
  80                 # should not be tested any further.
  81                 if ${VERBOSE}; then
  82                         printf "skipping: ${I}: includes "
  83                         awk '{print $2}' ${I}
  84                 fi
  85                 continue
  86         fi
  87         if ${VERBOSE}; then
  88                 echo "testing: ${I}"
  89         fi
  90         RET=1
  91         cat ${I} | troff -mandoc -ww -z |& grep "<" && RET=$?
  92         if [ $RET = 0 ]; then
  93         echo "From: cat ${I} | troff -mandoc -ww -z"
  94         echo "=================================================="
  95         ((++COUNT_TROFF))
  96         fi
  97         GROG=1
  98         if command -v lexgrog &> /dev/null; then
  99                 if ! lexgrog ${I} >/dev/null; then
 100                         echo "error: run: lexgrog ${I}"
 101                         echo "=================================================="
 102                         ((++COUNT_GROG))
 103                 fi
 104         elif command -v grog &> /dev/null; then
 105                 if ! grog ${I} | grep man >/dev/null; then
 106                         echo "error: grog ${I} is not a man file"
 107                         echo "=================================================="
 108                         ((++COUNT_GROG))
 109                 fi
 110         else
 111                 GROG=0
 112         fi
 113         REPEATS=( $(cat ${I} | troff -mandoc -Tascii 2>/dev/null | grotty |
 114                 col -b |
 115                 sed  -e 's/\s\+/\n/g; /^$/d' |
 116                 awk 'BEGIN { p="" } { if (0 < length($0)) { if (p == $0) { print } } p = $0 }') )
 117         if [ 0 -lt "${#REPEATS[@]}" ]; then
 118                 ITER=${#REPEATS[@]}+1
 119                 while ((ITER--)); do
 120                         remove_repeats ${ITER}
 121                 done
 122                 if [ 0 -lt "${#REPEATS[@]}" ]; then
 123                         echo "warning: ${I} has repeating words: ${REPEATS[@]}"
 124                         echo "=================================================="
 125                         ((++COUNT_REPEATS))
 126                 fi
 127         fi
 128 done
 129
 130 # Create a list of build targets.
 131 for I in $(find $(git rev-parse --show-toplevel) -name 'Make*.am' | xargs awk '
 132 $1 ~ /_SOURCES/ {
 133         if ($1 ~ /^test/ ||
 134             $1 ~ /^no(inst|dist)/ ||
 135             $1 ~ /^sample/ ||
 136             $1 ~ /^BUILT/) {
 137                 next
 138         }
 139         sub(/_SOURCES/, "")
 140         if ($1 ~ /^lib.*_la/) {
 141                 next
 142         }
 143         sub(/_static/, "")
 144         gsub(/_/, ".")
 145         sub(/switch.root/, "switch_root")
 146         sub(/pivot.root/, "pivot_root")
 147         print $1
 148 }'); do
 149         BIN_LIST[$I]=1
 150 done
 151
 152 # Find if build target does not have manual.
 153 set +u
 154 for I in ${!BIN_LIST[@]}; do
 155         if [ -v ${MAN_LIST[$I]} ]; then
 156                 echo "warning: ${SCRIPT_INVOCATION_SHORT_NAME}: ${I} does not have man page"
 157         fi
 158 done
 159 set -u
 160
 161 echo "${SCRIPT_INVOCATION_SHORT_NAME}: ${#BIN_LIST[*]} build targets were found"
 162 echo "${SCRIPT_INVOCATION_SHORT_NAME}: ${#MAN_LIST[*]} files were tested"
 163
 164 if [ ${GROG} = 0 ]; then
 165 echo "warning: neither grog nor lexgrog commands were found"
 166 fi
 167
 168 if [ ${COUNT_GROG} -ne 0 ]; then
 169         echo "error: ${SCRIPT_INVOCATION_SHORT_NAME}: ${COUNT_GROG} files failed (lex)grog man-page test"
 170 fi
 171 if [ ${COUNT_TROFF} -ne 0 ]; then
 172         echo "error: ${SCRIPT_INVOCATION_SHORT_NAME}: ${COUNT_TROFF} files failed troff parsing test"
 173 fi
 174 if [ ${COUNT_REPEATS} -ne 0 ]; then
 175         echo "error: ${SCRIPT_INVOCATION_SHORT_NAME}: ${COUNT_REPEATS} files have repeating words"
 176 fi
 177 ITER=${#MAN_LIST[*]}-${COUNT_GROG}-${COUNT_TROFF}-${COUNT_REPEATS}
 178 echo "${SCRIPT_INVOCATION_SHORT_NAME}: ${ITER} man-pages approved"
 179
 180 if [ ${COUNT_GROG} -ne 0 -o ${COUNT_TROFF} -ne 0 -o ${COUNT_REPEATS} -ne 0 ]; then
 181         exit 1
 182 fi
 183
 184 if ! ${VERBOSE}; then
 185         echo "${SCRIPT_INVOCATION_SHORT_NAME}: success"
 186 fi
 187 exit 0