ManScript

Now that groff has been ported to MinGW, (as a mingwPORT), it is easy to view the man pages shipped with MinGW by means of a rather long command line. To automate this a little, some short scripts may be helpful.

Although the functionality is quite limited, these at least facilitate running, say`man gcc', in the interim, pending the formal release of a complete `man' package. (Do note, however, that a development snapshot of the full package is already available, for those who are willing to compile it themselves).


Shell Script for MSYS Users

This should be copied to a script file, stored as /usr/local/bin/man, in your MSYS file system hierarchy:

#! /bin/sh
# man.sh -- simple manpage reader script for MSYS
#
# Written by Keith Marshall <keithmarshall@users.sourceforge.net>
#        and Wu Yongwei     <adah@users.sourceforge.net>
#
# Last update: 2005-11-14 10:30 GMT
#
# Public domain: install as /usr/local/bin/man

USAGE='Usage: man [-adw] [-C config-file] [-M path] [section] name ...'

# Adjust these defaults, to suit your configuration...

MANSECT_DEFAULT=1:1p:8:2:3:3p:4:5:6:7:9:0p:tcl:n:l:p:o
MANPATH_DEFAULT=/mingw/man:/usr/local/man:/usr/local/share/man

# Some manpages may require filtering through any subset
# of the following `groff' preprocessors...
# ( p = pic, e = eqn, t = tbl )
#
MANROFFSEQ_ALLOWED='p:e:t'

# You should not need to change anything, from here onward...
# These set defaults for the command line options.
#
MANDEBUG=no
MANCONFIG=''
SHOWPATH=no
ALLPAGES=no

# Parse command line options...
#
while getopts aC:dM:w opt
do
  case $opt in
    a) ALLPAGES=yes ;;
    C) MANCONFIG=$OPTARG ;;
    d) MANDEBUG=yes ;;
    M) MANPATH=$OPTARG ;;
    w) SHOWPATH=yes ;;
    *) exec >&2; echo $USAGE; exit 1 ;;
  esac
done

# $OPTIND always ends up being too big by one...
# Adjust, and discard option arguments, (already parsed).
#
set dummy "$@"; shift $OPTIND

# Try to locate a configuration file...
# Prefer `-C config-file' option, then these common locations, in order.
#
for name in /usr/local/lib/man.conf /usr/share/lib/man.conf /etc/man.conf
do
  [ -n "$MANCONFIG" ] && break
  [ -r $name ] && MANCONFIG=$name
done
if [ -n "$MANCONFIG" ] && [ $MANDEBUG = yes ]; then
  echo >&2 "Reading configuration file $MANCONFIG"
fi

# Establish the search order for manual sections...
# Prefer user's $MANSECT, config-file setting, $MANSECT_DEFAULT,
# in that order.
#
if [ -z "$MANSECT" ]; then
  CONFIG_KEY='/^[[:space:]]*MANSECT[[:space:]]*/s///p'
  [ -n "$MANCONFIG" ] && MANSECT=`sed -n $CONFIG_KEY $MANCONFIG 2>/dev/null`
  [ -z "$MANSECT" ] && MANSECT=$MANSECT_DEFAULT
  if [ $MANDEBUG = yes ]; then
    echo >&2
    echo >&2 "Searching manual sections $MANSECT"
  fi
fi

# Construct the MANPATH file system search path...
# Prefer user's $MANPATH, config-file settings, $MANPATH_DEFAULT,
# in that order.
#
if [ -z "$MANPATH" ]; then
  CONFIG_KEY='/^[[:space:]]*MANPATH[[:space:]]\+/{s///;s/%/%25/g;s/ /%20/g;p;}'
  for name in `[ -n "$MANCONFIG" ] && sed -n "$CONFIG_KEY" $MANCONFIG 2>/dev/null`
  do
    name=`echo "$name" | sed 's/%20/ /g;s/%25/%/g' 2>/dev/null`
    [ -n "$name" ] && name=`exec 2>/dev/null; cd "$name" && pwd`
    if [ -n "$name" ]; then
      if [ $MANDEBUG = yes ]; then
        [ -z "$MANPATH" ] && echo >&2
        echo >&2 "Adding $name to MANPATH"
      fi
      name=`echo $name | sed 's/%/%25/g;s/ /%20/g' 2>/dev/null`
      [ -n "$MANPATH" ] && MANPATH="$MANPATH:$name" || MANPATH="$name"
    fi
  done
  [ -z "$MANPATH" ] && MANPATH="$MANPATH_DEFAULT"
fi

# From here on...
# We need `IFS=:', so we can split $MANSECT and $MANPATH.
#
IFS=:

# If first non-option argument matches any $MANSECT component,
# then set up to perform a restricted search, for just that section,
# and establish `not found' message format appropriately.
#
NOTFOUND='No manual entry for $name'
for MSECT in $MANSECT
do
  [ "$1" = "$MANSECT" ] && break
  if [ "$1" = "$MSECT" ]; then
    MANSECT="$1"
    NOTFOUND='No entry for $name in section'" $1 of the manual"
    shift
  fi
done

# Ensure we have at least one topic name to search for,
# unless we are just using the `-w' option to show the MANPATH.
#
if [ $# -lt 1 ]; then
  if [ $SHOWPATH = yes ]; then
    echo 2>&- "MANPATH=$MANPATH"
    exit 0
  else
    echo >&2 "What manual page do you want?"
    echo >&2 "$USAGE"
    exit 1
  fi
fi

# Establish PAGER command to be used...
# Prefer $MANPAGER, $PAGER, config-file setting, `less -irs',
# in that order.
#
[ -n "$MANPAGER" ] && PAGER="$MANPAGER"
if [ -z "$PAGER" ]; then
  CONFIG_KEY='/^[[:space:]]*PAGER[[:space:]]*/s///p'
  [ -n "$MANCONFIG" ] && PAGER=`sed -n "$CONFIG_KEY" $MANCONFIG 2>/dev/null`
  [ -z "$PAGER" ] && PAGER="less -irs"
fi

# Establish NROFF command to be used...
# Prefer config-file setting, `groff -Tascii -mandoc -P-c',
# in that order.
#
CONFIG_KEY='/^[[:space:]]*NROFF[[:space:]]*/s///p'
[ -n "$MANCONFIG" ] && NROFF=`sed -n "$CONFIG_KEY" $MANCONFIG 2>/dev/null`
[ -z "$NROFF" ] && NROFF="groff -Tascii -mandoc -P-c"

# Establish the default sequence of NROFF filters to deploy...
# Prefer $MANROFFSEQ, config-file setting, `t' (tbl), in that order.
#
if [ -z "$MANROFFSEQ" ]; then
  CONFIG_KEY='/^[[:space:]]*MANROFFSEQ[[:space:]]*/s///p'
  [ -n "$MANCONFIG" ] && MANROFFSEQ=`sed -n "$CONFIG_KEY" $MANCONFIG 2>/dev/null`
  [ -z "$MANROFFSEQ" ] && MANROFFSEQ=t
fi

# Establish display width for manpages...
# Prefer $MANWIDTH, $COLS, `mandoc' default, in that order.
#
[ -n "$MANWIDTH" ] && COLS=$MANWIDTH
[ -n "$COLS" ] && NROFF="$NROFF -rLL=${COLS}m"

# For each specified topic name argument...
# Walk the MANPATH, looking in each effective MANSECT directory,
# for a matching topic file, and display the first matching entry.
# If the `-a' option is in effect, continue for any other MANSECTs,
# otherwise, move on to next topic, if any, after first match.
#
ERRNO=0
for name
do
  COMPLAIN='echo >&2'
  for MPATH in $MANPATH
  do
    for MSECT in $MANSECT
    do
      # Normalise the file name.
      #
      MFILE=`echo "$MPATH/man$MSECT/$name.$MSECT" | sed 's/%20/ /g;s/%25/%/g'`
      if [ -f "$MFILE" ]; then
        COMPLAIN='false'
        if [ "$SHOWPATH" = yes ]; then
          echo 2>&- "$MFILE"
        else
          # Establish the list of preprocessors to deploy...
          # Prefer any list specified in the manpage file itself,
          # falling back to $MANROFFSEQ, if none.
          #
          MSEQ=""
          FILTERS=`sed -n "/^'"'\\\\"[[:space:]]\+\([A-Za-z]\+\)$/s//\1/p;1q' "$MFILE"`
          [ -z "$FILTERS" ] && FILTERS="$MANROFFSEQ"
          for filter in $MANROFFSEQ_ALLOWED
          do
            echo $FILTERS | grep $filter >/dev/null 2>&1 && MSEQ=$MSEQ$filter
          done
          [ -n "$MSEQ" ] && MSEQ=" -$MSEQ"

          # Display the selected manpage,
          # or its appropriate formatting command, if debugging.
          #
          if [ $MANDEBUG = yes ]; then
            echo >&2
            echo >&2 "Not executing command:"
            echo >&2 " $NROFF$MSEQ \"$MFILE\" | $PAGER"
          else
            eval $NROFF$MSEQ "\"$MFILE\"" | eval $PAGER
          fi
        fi

        # If `-a' option given,
        # keep looking for other pages related to the given topic,
        # otherwise, break out to try a new topic.
        #
        [ $ALLPAGES = yes ] || break 2
      fi
    done
  done

  # Handle diagnostics, and error code, for missing topics.
  #
  [ "$COMPLAIN" = "false" ] || ERRNO=1
  eval $COMPLAIN $NOTFOUND
done

# All done...
# Exit with appropriate error code.
#
exit $ERRNO

# man.sh: end of file.

Configuration File for Preceding Shell Script

Copy this to a file called man.conf, and save it in any of the directories, /usr/local/lib, /usr/local/share/lib or /etc:

# man.conf
#
# Simplified configuration file, for use with Wu Yongwei's
# and Keith Marshall's MSYS `man' script.
#
# Install as /usr/local/lib/man.conf, /usr/local/share/lib/man.conf
# or /etc/man.conf, according to your preferred file system configuration.
# Modify as required, to suit your configuration.

# Commands for formatting manpages:--
#
PAGER           less -irs
NROFF           groff -Tascii -mandoc -P-c

# Mandatory `groff' preprocessors:--
# (uncomment if you want to force `groff' to use a specific set of filters)
# (this example adds `-pet' to the `groff' command line).
#
# MANROFFSEQ    pet

# Standard manual sections to be searched:--
#
MANSECT         1:1p:8:2:3:3p:4:5:6:7:9:0p:tcl:n:l:p:o

# Directories where manpages may be found:--
# (add any additional ones you may need, one per line)
#
MANPATH         /usr/man
MANPATH         /usr/local/man
MANPATH         /usr/local/share/man
MANPATH         /mingw/man

# Other less conventional entries are allowed, and don't hurt,
# even if they don't exist.
#
MANPATH         /E/groff-1.19.2-i686-mingw/kits/man

# man.conf: end of file.

Batch File for cmd.exe Users

This is suitable for use with cmd.exe only, and cannot be used on Windows-9x/ME; it should be copied to a file called man.bat, in some convenient directory in your PATH:

@echo off
setlocal

set MSECT=1
set MPATH=C:\mingw\man

if "%1" == "" (
  echo Usage: man [-M path] [section] name
  goto end
)

if "%1" == "-M" (
  set MPATH=%2
  shift
  shift
)

if not "%2" == "" (
  set MSECT=%1
  shift
)

set MFILE=%MPATH%/man%MSECT%/%1.%MSECT%

if not exist %MFILE% (
  echo Man entry not found
  goto end
)

groff -Tascii -pet -mandoc -P-c %MFILE% | less -irs

:end
endlocal

Site Status

Site maintenance completed May 25th, 2012 at 12:38 UTC