common/scripts/shman.sh

#!/usr/bin/ksh93

#
# 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) 2007, 2010, Oracle and/or its affiliates. All rights reserved.
#

# Solaris needs /usr/xpg6/bin:/usr/xpg4/bin because the tools in /usr/bin are not POSIX-conformant
export PATH=/usr/xpg6/bin:/usr/xpg4/bin:/bin:/usr/bin

# Make sure all math stuff runs in the "C" locale to avoid problems
# with alternative # radix point representations (e.g. ',' instead of
# '.' in de_DE.*-locales). This needs to be set _before_ any
# floating-point constants are defined in this script).
if [[ "${LC_ALL}" != "" ]] ; then
    export \
        LC_MONETARY="${LC_ALL}" \
        LC_MESSAGES="${LC_ALL}" \
        LC_COLLATE="${LC_ALL}" \
        LC_CTYPE="${LC_ALL}"
        unset LC_ALL
fi
export LC_NUMERIC=C

function fatal_error
{
    print -u2 "${progname}: $*"
    exit 1
}

function debug_print
{
    # don't use "--" here to allow "-f" for formatting
#   print -u2 "$@"
    return 0
}

# Build a list of compound variables calculated from MANPATH and
# locale which contain...
# "manpath_element" - the MANPATH element this entry belongs to
# "dir"             - physical directory of "manpath_element"
# "sect"            - section (if "manpath_element" is something like /usr/share/man,1b)
# ... and put the result in the array named by argv[1]
function enumerate_mandirs
{
    nameref md=$1
    typeset manpath_element dir sect manlang
    integer i=0

    if [[ "${LC_MESSAGES}" != "" ]] ; then
        manlang="${LC_MESSAGES}"
    else
        manlang="${LANG}"
    fi

    print -r -- "${MANPATH//:/$'\n'}" | while read manpath_element ; do
        # strip section from manpath elements like "/usr/share/man,1b"
        dir="${manpath_element/~(E)(.*),(.*)/\1}"
        sect="${manpath_element/~(E)(.*),(.*)/\2}"
        [[ "${sect}" == "${dir}" ]] && sect=""

        if [[ "${manlang}" != "" && -d "${dir}/${manlang}" ]] ; then
            md+=(
                manpath_element="${manpath_element}"
                dir="${dir}/${manlang}"
                sect="${sect}"
            )
        fi
        if [[ -d "${dir}" ]] ; then
            md+=(
                manpath_element="${manpath_element}"
                dir="${dir}"
                sect="${sect}"
            )
        fi
    done

    return 0
}

function enumerate_mansects
{
    nameref ms=$1
    nameref mandir_node=$2
    typeset mancf="${mandir_node.dir}/man.cf"
    typeset x s l

    if [[ "${mandir_node.sect}" != "" ]] ; then
        x="${mandir_node.sect}"
    elif [[ "${MANSECTS}" != "" ]] ; then
        x="${MANSECTS//,/$'\n'}"
    elif [[ -f "${mancf}" && -r "${mancf}" ]] ; then
        x="$(egrep -v '^#|^[[:space:]]*$' <"${mancf}" | egrep '^MANSECTS=')"
        x="${x/MANSECTS=}/"
        x="${x//,/$'\n'}"
    else
        x="$(cd "${mandir_node.dir}" ; \
            ls -1d ~(El)(sman|man).*/ | \
            while read s ; do \
                s="${s/~(El)(sman|man)/}" ; \
                s="${s/~(Er)\//}" ; \
                print -r -- "$s" ; \
            done)"
    fi

    while read l ; do
        [[ "${l}" != ~(Elr)[[:blank:]]* ]] && ms+=( "${l}" )
#       print -- "sect=$l"
    done <<<"${x}"

#   printf "enumerate_mansects: found %d entries.\n" ${#ms[@]}

    return 0
}

# wrapper around more/less
function browse_manpage
{
    typeset tmpdirname
    typeset doc_filename="$1"
    typeset doc_title="$2"

    # squish characters in filename which are not allowed in a filesystem
    # (currently '/')
    doc_title="${doc_title//\//}"

    # check if we have "less" installed, if not fall back to /usr/xpg4/bin/more
    if which less >/dev/null 2>&1 ; then
        # use "cat" here to avoid that "less" may try funny things
        cat <"${doc_filename}" | less -I -M $"--prompt=MManual\ page\ ${doc_title}\ ?ltline\ %lt?L/%L.:"
    else
        tmpdirname="$(mktemp -t -d "shman_${PPID}_$$_XXXXXX")"

        mkdir -p "${tmpdirname}" || { print -u2 -f $"Couldn't create tmp. dir %s\n" "${tmpdirname}" ; return 1 ; }

        (
            cd "${tmpdirname}"

            # note: we need to support /dev/stdin
            cat <"${doc_filename}" >"./${doc_title}"

            /usr/xpg4/bin/more "${doc_title}"

            rm -f "${doc_title}"
        )

        rmdir "${tmpdirname}"
    fi

    return 0
}

# /usr/bin/man <keyword>
function show_manpage
{
    compound -a mandirs
    integer i
    integer j

    enumerate_mandirs mandirs
#   debug_print -- "${mandirs[@]}"

    integer num_mandirs=${#mandirs[@]}

    for ((i=0 ; i < num_mandirs ; i++ )) ; do
        typeset mandir="${mandirs[i].dir}"

        typeset -a mansects
        enumerate_mansects mansects "mandirs[$i]"

        integer num_mansects="${#mansects[@]}"
#       debug_print -- "mansects=${mansects[@]}"

        for ((j=0 ; j < num_mansects ; j++ )) ; do
            typeset mansect="${mansects[j]}"

            # try 1: SGML manpage
            typeset match="${mandir}/sman${mansect}/${manname}.${mansect}"
            if [[ -r "${match}" ]] ; then
                typeset note nlink

                # follow SGML links if needed (needs rework, including protection against link loops)
                while true ; do
                    debug_print -f "match: %s\n" "${match}"

                    tmp="$(cd "${mandir}" ; LC_MESSAGES=C /usr/lib/sgml/sgml2roff "${match}")"
                    read note nlink <<<"${tmp}"

                    if [[ "${note}" == ".so" ]] ; then
                        match="${nlink}"
                    else
                        break
                    fi
                done

                tbl <<<"${tmp}" | eqn | nroff -u0 -Tlp -man - | col -x | browse_manpage /dev/stdin "${manname}(${mansect})"
                return 0
            fi

            # try 2: troff manpage
            match="${mandir}/man${mansect}/${manname}.${mansect}"
            if [[ -r "${match}" ]] ; then
                debug_print -f "match: %s\n" "${match}"
                tbl <"${match}" | eqn | nroff -u0 -Tlp -man - | col -x | browse_manpage /dev/stdin "${manname}(${mansect})"
                return 0
            fi
        done
        unset mansects num_mansects
    done

    printf $"No manual entry for %s.\n" "${manname}"
    return 0
}

# /usr/bin/man -l <keyword>
function list_manpages
{
    compound -a mandirs

    enumerate_mandirs mandirs
    #debug_print -- "${mandirs[@]}"

    integer num_mandirs=${#mandirs[@]}

    for ((i=0 ; i < num_mandirs ; i++ )) ; do
        typeset mandir="${mandirs[i].dir}"

        typeset -a mansects
        enumerate_mansects mansects "mandirs[$i]"

        integer num_mansects="${#mansects[@]}"
#       debug_print -- "mansects=${mansects[@]}"

        for ((j=0 ; j < num_mansects ; j++ )) ; do
            mansect="${mansects[j]}"

            # try 1: SGML manpage
            match="${mandir}/sman${mansect}/${manname}.${mansect}"
            if [[ -r "${match}" ]] ; then
                printf "%s (%s)\t-M %s\n" "${manname}" "${mansect}" "${mandir}"
                continue
            fi

            # try 2: troff manpage
            match="${mandir}/man${mansect}/${manname}.${mansect}"
            if [[ -r "${match}" ]] ; then
                printf "%s (%s)\t-M %s\n" "${manname}" "${mansect}" "${mandir}"
                continue
            fi
        done
        unset mansects num_mansects
    done

    return 0
}

# /usr/bin/appropos
function list_keywords
{
    typeset -a mandirs
    typeset name namesec title

    enumerate_mandirs mandirs
    #debug_print -- "${mandirs[@]}"

    integer num_mandirs=${#mandirs[@]}

    for ((i=0 ; i < num_mandirs ; i++ )) ; do
        typeset mandir="${mandirs[i].dir}"
        typeset windexfile="${mandir}/windex"

        if [[ ! -r "${windexfile}" ]] ; then
            print -u2 -f $"%s: Can't open %s.\n" "${progname}" "${windexfile}"
            continue
        fi

        while IFS=$'\t' read name namesec title ; do
            if [[ "${name}${namesec}${title}" == ~(Fi)${manname} ]] ; then
                printf "%s\t%s\t%s\n" "${name}" "${namesec}" "${title}"
            fi
        done <"${windexfile}"
    done

    return 0
}

function usage
{
    OPTIND=0
    getopts -a "${progname}" "${man_usage}" OPT '-?'
    exit 2
}

# program start
builtin basename
builtin cat
builtin date

typeset progname="$(basename "${0}")"

typeset -r man_usage=$'+
[-?\n@(#)\$Id: shman (Roland Mainz) 2009-12-02 \$\n]
[-author?Roland Mainz <roland.mainz@nrubsig.org>]
[-author?Roland Mainz <roland.mainz@sun.com>]
[+NAME?man - find and display reference manual pages]
[+DESCRIPTION?The man command displays information from the reference
    manuals. It displays complete manual pages that you select
    by name, or one-line summaries selected  either  by  keyword
    (-k), or by the name of an associated file (-f). If no
    manual page is located, man prints an error message.]
[+?write me.]
[k:keyword?Prints out one-line summaries from the windex database (table of contents) that
    contain any of the given  keywords. The windex database is created using
    catman(1M).]
[l:list?Lists all manual  pages  found  matching name within the search path.]
[M:mpath?Specifies an alternate search  path  for manual  pages. path is a colon-separated
    list of directories that contain  manual page directory subtrees. For example, if
    path  is  /usr/share/man:/usr/local/man, man  searches  for  name in the standard
    location, and then /usr/local/man.  When used  with  the -k or -f options, the -M
    option must appear first. Each directory in  the  path is assumed to contain subdirectories of the form man* or sman*  ,
    one  for each section. This option overrides the MANPATH environment variable.]:[path]
[s:section?Specifies sections of the manual for man to search. The directories searched for
    name are limited to those specified by section. section can be a numerical
    digit, perhaps followed by one or more letters to match the desired section of
    the manual, for example,  "3libucb". Also, section can be a word, for example,
    local, new, old, public. section can also be a letter.
    To specify multiple sections, separate each section with
    a comma. This option overrides the MANPATH environment variable and the man.cf
    file.
    See Search Path below for an explanation of how man conducts its search.]:[section]

name

[+SEE ALSO?\bksh93\b(1), \bman\b(1)]
'

typeset do_list=false
typeset do_keyword=false

while getopts -a "${progname}" "${man_usage}" OPT ; do
#    printmsg "## OPT=|${OPT}|, OPTARG=|${OPTARG}|"
    case ${OPT} in
        M)  MANPATH="${OPTARG}" ;;
        l)  do_list=true        ;;
        k)  do_keyword=true     ;;
        s)  MANSECTS="${OPTARG}"    ;;
        *)  usage           ;;
    esac
done
shift $((OPTIND-1))

# cd /usr/man; LC_MESSAGES=C /usr/lib/sgml/sgml2roff /usr/man/sman1as/asadmin-list-timers.1as  | tbl | eqn | nroff -u0 -Tlp -man -  | col -x > /tmp/mpLQaqac

# prechecks
(( $# > 0 )) || usage

# process arguments
while (( $# > 0 )) ; do
    typeset manname="$1"
    shift

    debug_print -f "# searching for %s ...\n" "${manname}"

    if ${do_keyword} ; then
        list_keywords
    elif ${do_list} ; then
        list_manpages
    else
        show_manpage
    fi
done

# todo: better exit codes
exit 0
# EOF.