envfor-emacs-for-man

# Sourced script: envfor-emacs-for-man  -*- mode: sh; -*-
#
# Purpose   : Set environment to use Emacs as the man reader.
# Created   : Wednesday, April 17 2024.
# Author    : Pierre Rouleau <prouleau001@gmail.com>
# Time-stamp: <2024-06-27 13:10:30 EDT, updated by Pierre Rouleau>
# ----------------------------------------------------------------------------
# Module Description
# ------------------
#
# Emacs is much more powerful and useful as man to read and navigate man pages
# that man is.  This scripts sets up the shell to use Emacs as the tool to
# view that man pages inside the current shell.
#
# By default it sets up the shell to use a shell instance of Emacs running
# in terminal mode.  A man command would then open a local instance of
# text-based Emacs.
#
# By specifying extra option arguments, it's also possible to open an
# independent Emacs GUI process or to launch it inside a client ofn already
# running emacs server.  These options can be passed to the setup script (this
# one), which sets the default, and to the man() function, allowing overriding
# the chosen default.  See print_man_usage() for more information.

# ----------------------------------------------------------------------------
# Dependencies
# ------------
#
# Presence of Emacs.
#
# Side Effects:
# - Set USRHOME_MAN_MODE variable.

# ----------------------------------------------------------------------------
# Code
# ----
#
#
# 0 - Check if shell is interactive
# ---------------------------------
case "$-" in
    *i*)
        SHELL_IS_INTERACTIVE=true
        ;;
    *)
        SHELL_IS_INTERACTIVE=false
        ;;
esac


print_man_usage()
{
    # arg 1: string: "use-emacs-for-man" | "man"

    printf "\
 Usage: %s [-g | -G | -s |-S | -t | -T] TOPIC
  -g : emacs started in graphics mode
  -G : same as -g, but start emacs faster with less initialization (using -Q)
  -s : using Emacs server: open man page in emacsclient
  -S : same as -s, except meant for issuing the man command
       in a shell running withing Emacs: does not delete any window.
  -t : start emacs in terminal mode in the current shell.
       This is the default if no option is specified.
  -T : same as -t, but start emacs faster with less initialization (using -Q)

  You can also specify the same options to man() to
  override the option passed to use-emacs-for-man.\n" "$1"

    if [ "$1" = "man" ]; then
        printf "\

  ATTENTION!!

   This shell has been instrumented with 'use-emacs-for-man':
   you are therefore executing USRHOME-supplied man() function,
   NOT the native man command!

   If you want to use the native man executable from this shell,
   then simply prepend the '-man' option (without the quotes)
   to the man command line.

    For example, to list all man pages for 'cc' with the man
    executable after activating use-emacs-for-man, do this:

     man -man -a -w cc
"
    fi
    printf "\n"
}

print_error()
{
    >&2 printf "\
***ERROR***
 %s
***********
" "$1"
}


# Initialize USRHOME_MAN_MODE to unknown if it is not already set from previous
# execution of the sourcing of the script.
if [ -z "$USRHOME_MAN_MODE" ]; then
    prefix_msg=". Using"
    USRHOME_MAN_MODE=
else
    prefix_msg="Now using"
fi
if [ -n "$1" ]; then
    case $1 in
        -g | -G)
            # This will use the 'ge' script.
            # That script is part of the templates.
            # Check if it is available and if not, inform the user that
            # the script will use the template code.  The user might want to
            # copy it inside a directory present on PATH and may want to
            # modify it to fit the user's needs better.
            # later.  Activate the mode only if the user accepts.
            if ! command -v ge > /dev/null 2>&1; then
                if [ "$SHELL_IS_INTERACTIVE" = "true" ]; then
                    printf "ATTENTION! The 'ge' script is not in your PATH!\n"
                    printf " USRHOME will use %s/template/bin/ge\n" "$USRHOME_DIR"
                    printf " You may want to copy it in a directory in your PATH\n"
                    printf " and possibly modify it to better suit you.\n\n"
                fi
            fi
            USRHOME_MAN_MODE="$1"
            if [ "$SHELL_IS_INTERACTIVE" = "true" ]; then
                case $1 in
                    -g)
                        printf "%s Emacs in graphics mode as man reader.\n" "$prefix_msg"
                        ;;
                    -G)
                        printf "%s Emacs quickly in graphics mode as man reader.\n" "$prefix_msg"
                        ;;
                esac
            fi
            ;;
        -s | -S)
            # Requesting to use Emacs client/server mechanism.
            # Check if the Emacs daemon is running.  If it is not, start it.
            if ! emacsclient -a false -e 't' > /dev/null 2>&1; then
                if [ "$SHELL_IS_INTERACTIVE" = "true" ]; then
                    printf -- "ATTENTION: Emacs Daemon was not running, starting it!\n"
                fi
                emacs --daemon
            fi
            USRHOME_MAN_MODE="$1"
            if [ "$SHELL_IS_INTERACTIVE" = "true" ]; then
                printf "%s Emacs server as man reader.\n" "$prefix_msg"
            fi
            ;;
        -t)
            USRHOME_MAN_MODE='-t'
            if [ "$SHELL_IS_INTERACTIVE" = "true" ]; then
                printf "%s Emacs in text mode as man reader.\n" "$prefix_msg"
            fi
            ;;

        -T)
            USRHOME_MAN_MODE='-T'
            if [ "$SHELL_IS_INTERACTIVE" = "true" ]; then
                printf "%s Emacs quickly in text mode as man reader.\n" "$prefix_msg"
            fi
            ;;

        -h | --help )
            unset prefix_msg
            if [ "$SHELL_IS_INTERACTIVE" = "true" ]; then
                print_man_usage "use-emacs-for-man"
            fi
            return 0
            ;;

        *)
            if [ "$SHELL_IS_INTERACTIVE" = "true" ]; then
                print_error "use-emacs-for-man invalid option: $1"
            fi
            unset prefix_msg
            return 2
    esac
else
    USRHOME_MAN_MODE='-t'
    if [ "$SHELL_IS_INTERACTIVE" = "true" ]; then
        printf -- ". Using Emacs in text mode as man reader.\n"
    fi
fi
unset prefix_msg


man()
{
    # See print_man_usage() for arguments.
    # echo "man(): on entry: USRHOME_MAN_MODE := $USRHOME_MAN_MODE"

    case $1 in
        -h | --help)
            print_man_usage "man"
            return 1
            ;;
    esac

    man_mode="$USRHOME_MAN_MODE"

    topic="$1"

    # Check for the case where man was issued with a sole argument
    # that is a switch not supported by the function and not yet caught.
    if [ -n "$2" ]; then
        if [ "$1" = "-man" ]; then
            man_mode='-man'
        else
            man_mode="$1"
            topic="$2"
        fi
    fi
    if [[ "$topic" =~ ^- ]]; then
        if [ "$topic" = "-man" ]; then
            man_mode='-man'
        else
            print_man_usage "man"
            return 3
        fi
    fi

    #echo "man_mode:= $man_mode , topic:= $topic"

    man_emacs_opt=

    case $man_mode in
        -g | -s | -S | -t)
            ;;
        -G | -T)
            man_emacs_opt=-Q
            ;;

        -man)
            printf -- "Using man executable\n"
            ;;

        *)
            print_error "emacs-for-man invalid option: $1"
            print_man_usage "man"
            return 2
            ;;    esac

    #echo "man(): on use   : man_mode := $man_mode"
    case $man_mode in
        '-g' | '-G')
            # Launch GUI Emacs in separate process; don't wait.
            # The shell can continue to be used.
            # Start Emacs with the -Q options when -G is requested.
            if command -v ge > /dev/null 2>&1; then
                ge ${man_emacs_opt} --eval "(progn (man \"$topic\") (delete-window))"
            else
                # If the ge command is not found on the system use the one distributed in USRHOME template.
                "$USRHOME_DIR/template/bin/ge" ${man_emacs_opt} --eval "(progn (man \"$topic\") (delete-window))"
            fi
            ;;

        '-s' | '-S')
            # Use emacsclient to the running Emacs daemon
            # Check if the emacsclient is running, if not warn user
            # and exit.
            if ! lsof -c emacsclient > /dev/null; then
                echo "ERROR: Emacs client NOT running!"
                echo "Start emacsclient inside another window and try again."
                return 1
            else
                local found
                case $man_mode in
                    '-s')
                        found=$(emacsclient --eval "(progn (man \"$topic\") \
                                                           (delete-window) \
                                                           (with-current-buffer \"*Messages*\" \
                                                             (end-of-buffer) \
                                                             (when (search-backward (format \"%s man page formatted\" \"$topic\") nil :noerror) t)))")
                        ;;
                    '-S')
                        found=$(emacsclient --eval "(progn (man \"$topic\") \
                                                           (with-current-buffer \"*Messages*\" \
                                                             (end-of-buffer) \
                                                             (when (search-backward (format \"%s man page formatted\" \"$topic\") nil :noerror) t)))")
                        ;;
                esac
                if [ "$found" = "nil" ]; then
                    printf "ERROR: No man page found for %s\n" "$topic" >&2
                    return 4
                fi
            fi
            ;;

        '-t' | '-T')
            # Open a local terminal-based copy of Emacs in the current
            # terminal.
            emacs ${man_emacs_opt} -nw --eval "(progn (man \"$topic\") (delete-window))"
            ;;

        '-man')
            shift
            command man "$@"
            ;;
    esac
}

# Cleanup
# This leaves USRHOME_MAN_MODE in the shell.

# ----------------------------------------------------------------------------
#  Local Variables:
#  sh-shell: bash
#  End: