branch: externals/greenbar
commit 755163adea1480d3ee85ace02987456d92992d70
Author: Michael R. Mauger <mich...@mauger.com>
Commit: Michael R. Mauger <mich...@mauger.com>
* externals/greenbar/README.org: Add package description
* externals/greenbar/snapshots/: Add sample screenshots
---
README.org | 117 ++++++++++++++++
snapshots/gen-snapshots.sh | 264 +++++++++++++++++++++++++++++++++++++
snapshots/graybar-dark-long.png | Bin 0 -> 46472 bytes
snapshots/graybar-dark-short.png | Bin 0 -> 64541 bytes
snapshots/graybar-light-long.png | Bin 0 -> 47178 bytes
snapshots/graybar-light-short.png | Bin 0 -> 63920 bytes
snapshots/greenbar-dark-long.png | Bin 0 -> 44502 bytes
snapshots/greenbar-dark-short.png | Bin 0 -> 64524 bytes
snapshots/greenbar-light-long.png | Bin 0 -> 46947 bytes
snapshots/greenbar-light-short.png | Bin 0 -> 64506 bytes
snapshots/rainbow-dark-long.png | Bin 0 -> 44810 bytes
snapshots/rainbow-dark-short.png | Bin 0 -> 64810 bytes
snapshots/rainbow-light-long.png | Bin 0 -> 46051 bytes
snapshots/rainbow-light-short.png | Bin 0 -> 64852 bytes
14 files changed, 381 insertions(+)
diff --git a/README.org b/README.org
new file mode 100644
index 0000000000..afb20bd3b6
--- /dev/null
+++ b/README.org
@@ -0,0 +1,117 @@
+#+TITLE: GreenBar
+#+AUTHOR: Michael R. Mauger
+#+EMAIL: mich...@mauger.com
+
+#+DATE: [Tue May 27 19:35:08 EDT 2025]
+#+SPDX-License-Identifier: GPL-3.0-or-later
+#+SPDX-FileCopyrightText: Copyright 2025 Free Software Foundation, Inc.
+
+* Summary
+For us old neck beards, who learned to write software on punch cards
+and print out our code and output on wide line printers, it was
+helpful to have alternating bands of subtle background coloring to
+guide our eyes across the line on the page. Reading long rows of text
+across a 14 7/8" page, it was very easy to loose your place vertically
+while scanning the page horizontally. The subtle background shading
+was often done with pale bands of green alternating with the white of
+the paper.
+
+Paper pre-printed with the pale green bars was often referred to as
+"green bar" and the technique is also referred to as "zebra striping."
+In Emacs, in ~ps-print.el~ (PostScript print facility), the feature is
+enabling with the ~ps-zebra-stripes~ setting.
+
+To enable ~greenbar-mode~ in your ~comint-mode~ buffers, add the
+following to your Emacs configuration:
+
+#+BEGIN_SRC emacs-lisp
+ (add-hook 'comint-mode-hook #'greenbar-mode)
+#+END_SRC
+
+If you want to enable ~greenbar-mode~ only in a single mode derived
+from ~comint-mode~, then you need to add ~greenbar-mode~ only to the
+desired derived mode hook. Adding ~greenbar-mode~ to
+~comint-mode-hook~ enables it for all comint derived modes.
+
+The variable ~greenbar-color-theme~ is an Alist of predefined bar
+background colors. Each element of the Alist consists of a symbol
+that is the name of the theme; the rest of the list are color names
+which are used as background colors for successive bands of lines.
+
+The variable ~greenbar-color-list~ controls which set of color bars
+are to be applied. The value is either a name from color theme
+defined in ~greenbar-color-themes~ or it is a list of color names.
+
+The variable ~greenbar-lines-per-bar~ controls how many output lines
+are displayed using each band's background color.
+
+By default, input lines are not highlighted, but if
+~greenbar-highlight-input~ is set to a non-nil value, then input is
+also highlighted with green bars as well.
+
+Suggestions for other background color themes are always welcome.
+
+* Installation
+Since this package is part of ELPA, it can be easily installed, and
+then linking to ~comint~ buffers is easy.
+
+#+BEGIN_SRC emacs-lisp
+ (package-install 'greenbar)
+ (require 'greenbar)
+
+ (setopt greenbar-lines-per-bar 3
+ greenbar-background-colors 'greenbar
+ greenbar-highlight-input nil)
+
+ (add-hook 'comint-mode-hook #'greenbar-mode)
+#+END_SRC
+
+Or, with ~use-package~:
+#+BEGIN_SRC emacs-lisp
+ (use-package greenbar
+
+ :custom
+ (greenbar-lines-per-bar 3)
+ (greenbar-background-colors 'greenbar)
+ (greenbar-highlight-input nil)
+
+ :hook comint-mode)
+#+END_SRC
+
+* Examples
+** ~greenbar~ theme
+When you set ~greenbar-background-colors~ to ~greenbar~
+
+*** Light background display mode
+With a theme that has ~background-mode~ value of ~light~, here's what this
+package will do to comint buffers.
+[[file:./snapshots/greenbar-light-short.png]]
+And
+[[file:./snapshots/greenbar-light-long.png]]
+
+*** Dark background display theme
+[[file:./snapshots/greenbar-dark-short.png]]
+And
+[[file:./snapshots/greenbar-dark-long.png]]
+
+** ~graybar~
+*** Light
+[[file:./snapshots/graybar-light-short.png]]
+And
+[[file:./snapshots/graybar-light-long.png]]
+
+*** Dark
+[[file:./snapshots/graybar-dark-short.png]]
+And
+[[file:./snapshots/graybar-dark-long.png]]
+
+** ~rainbow~
+*** Light
+[[file:./snapshots/rainbow-light-short.png]]
+And
+[[file:./snapshots/rainbow-light-long.png]]
+
+*** Dark
+[[file:./snapshots/rainbow-dark-short.png]]
+And
+[[file:./snapshots/rainbow-dark-long.png]]
diff --git a/snapshots/gen-snapshots.sh b/snapshots/gen-snapshots.sh
new file mode 100755
index 0000000000..3f3d59d435
--- /dev/null
+++ b/snapshots/gen-snapshots.sh
@@ -0,0 +1,264 @@
+#! /usr/bin/env bash
+set -eu -o pipefail
+
+## gen-graphics.sh --- Generate screenshots for greenbar -*-
lexical-binding: t -*-
+
+# Copyright (C) 2025 Free Software Foundation, Inc.
+
+# Author: Michael R. Mauger <mich...@mauger.com>
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU General Public License for more details.
+
+# You should have received a copy of the GNU General Public License
+# along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+# Assumes GNOME Desktop Environment
+
+PROG="$( basename "$0" )"
+# shellcheck disable=SC2034 # PDIR not used (remove if actually used)
+PDIR="$( cd "$( dirname "$0" )" && pwd )"
+
+if ! type -f emacs >/dev/null; then
+ echo >&2 "${PROG}: \`emacs' executable not found"
+ exit 2
+fi
+
+# ========================================
+# Set the defaults for options
+ALL=false
+DARK=false
+LIGHT=false
+CMDS=(short long)
+BG_MODE=
+GB_THEME=
+
+# ========================================
+# Array. OPT, OPT: (reqd arg), OPT? (opt arg)
+SHORT_OPTIONS=( )
+LONG_OPTIONS=( all long short dark light )
+
+# ========================================
+# Usage help text
+function opt_usage {
+ cat >&2 << TAC
+usage: ${PROG} OPTIONS | bg-mode gb-theme
+Options:
+ * --all
+ If specified, run the script for all possible values of bg-mode and
gb-theme
+ * --long
+ Use long output lines
+ * --short
+ Use short output lines
+ * --dark
+ Use dark background
+ * --light
+ Use light background
+
+Parameters:
+ * bg-mode
+ Background Mode. Either \`dark' or \`light'
+ * gb-theme
+ Greenbar Theme. One of: greenbar, graybar, or rainbow
+TAC
+ exit 2
+}
+
+OPT_SHORT=$( IFS=''; : "${SHORT_OPTIONS[*]}"; : "${_//\?/::}"; : "${_}h";
echo "${_}" )
+OPT_LONG=$( IFS=','; : "${LONG_OPTIONS[*]}"; : "${_//\?/::}"; :
"${_}${_:+,}help"; echo "${_}" )
+
+OPTIONS=$( getopt --alternative \
+ --name "${PROG}" \
+ --options "${OPT_SHORT}" \
+ --longoptions "${OPT_LONG}" \
+ -- "$@" )
+eval set -- "${OPTIONS}"
+
+# ========================================
+# Handle command line options
+while true; do
+ case ${1} in
+ (--all) ALL=true ;;
+ (--dark) DARK=true ;;
+ (--light) LIGHT=true ;;
+ (--long) CMDS=(long) ;;
+ (--short) CMDS=(short) ;;
+
+ (-h | --help) opt_usage ;;
+ (--) shift; break ;;
+ (*)
+ echo >&2 "${PROG}: unrecognized option -- \"-${OPT}\""
+ exit 1
+ ;;
+ esac
+ shift
+done
+
+# echo "ALL='${ALL}'" "DARK='${DARK}'" "LIGHT='${LIGHT}'" "CMDS=(${CMDS[*]})"
"[*]=$*"
+
+# ========================================
+# Parse the command line parameters
+if ${ALL}; then
+ for BG_MODE in light dark; do
+ for GB_THEME in greenbar graybar rainbow; do
+ for CMD in "${CMDS[@]}"; do
+ "$0" "--${CMD}" "${BG_MODE}" "${GB_THEME}"
+ sleep 1
+ done
+ done
+ done
+
+ exit
+
+elif ${DARK}; then
+ for GB_THEME in greenbar graybar rainbow; do
+ for CMD in "${CMDS[@]}"; do
+ "$0" "--${CMD}" dark "${GB_THEME}"
+ sleep 1
+ done
+ done
+
+ exit
+
+elif ${LIGHT}; then
+ for GB_THEME in greenbar graybar rainbow; do
+ for CMD in "${CMDS[@]}"; do
+ "$0" "--${CMD}" light "${GB_THEME}"
+ sleep 1
+ done
+ done
+
+ exit
+
+elif (( ${#CMDS[*]} > 1 )); then
+ for CMD in "${CMDS[@]}"; do
+ "$0" "--${CMD}" "${@}"
+ sleep 1
+ done
+
+ exit
+
+else
+ CMD=${CMDS[0]}
+fi
+
+# ========================================
+# Parse BG-MODE and GB-THEME
+if (( $# != 2 )); then
+ echo >&2 "${PROG}: accepts 2 parameters: bg-mode gb-theme"
+ exit 1
+fi
+
+case $1 in
+ (dark | light) BG_MODE=$1 ;;
+ *)
+ echo >&2 "${PROG}: unrecognized background mode -- \"${1}\""
+ exit 1
+ ;;
+esac
+
+THEME=
+case ${BG_MODE} in
+ (dark) THEME='tango-dark' ;;
+ (light) THEME='tango' ;;
+esac
+
+case $2 in
+ (greenbar | graybar | rainbow) GB_THEME=$2 ;;
+ *)
+ echo >&2 "${PROG}: unrecognized greenbar theme -- \"${2}\""
+ exit 1
+ ;;
+esac
+
+NAME="${GB_THEME}-${BG_MODE}-${CMD}"
+#
+
+WIDTH=
+case ${CMD} in
+ (short) WIDTH=80 ;;
+ (long) WIDTH=140 ;;
+esac
+
+HEIGHT=
+case ${CMD} in
+ (short) HEIGHT=14 ;;
+ (long) HEIGHT=40 ;;
+esac
+
+FONT=
+case ${CMD} in
+ (short) FONT='Adwaita Mono 12' ;;
+ (long) FONT='Adwaita Mono 4' ;;
+esac
+
+COMINT_CMD=
+case ${CMD} in
+ (short)
+ COMINT_CMD='echo ls -lAF; ls -lAF .git* *.el *.elc\n'
+ ;;
+ (long)
+ COMINT_CMD='echo journalctl -u avahi-daemon; (journalctl -u
avahi-daemon | sed -E \"s/[[:xdigit:]]{3,4}([:. ])/####\1/g\" | tail -30 )\n'
+ ;;
+esac
+
+# ========================================
+# Make the script to generate the snapshot
+GEN_EL=$( mktemp --tmpdir --suffix .el "${PROG}.XXXXXXXXXX" )
+cat >"${GEN_EL}" <<TAC
+(set-face-font 'default "${FONT}" nil)
+(push '(width . ${WIDTH}) default-frame-alist)
+(push '(height . ${HEIGHT}) default-frame-alist)
+(push '(background-mode . ${BG_MODE}) default-frame-alist)
+(load-theme '${THEME})
+(load-file "./greenbar.el")
+(setopt greenbar-background-colors '${GB_THEME})
+
+(defun refresh-display ()
+ (while (and (not (sit-for 1))
+ (accept-process-output nil 1))
+ (redisplay)))
+
+(menu-bar-mode -1)
+(tool-bar-mode -1)
+(scroll-bar-mode -1)
+(let* ((fram (make-frame '((name . "GreenBar (${BG_MODE} ${GB_THEME})")
+ (minibuffer . nil))))
+ (shel (shell))
+ (proc (get-buffer-process shel)))
+ (select-frame fram)
+ (pop-to-buffer shel)
+ (delete-other-windows)
+ (greenbar-mode +1)
+ (refresh-display)
+ (comint-send-string proc "${COMINT_CMD}")
+ (refresh-display)
+ (call-process "gnome-screenshot" nil nil nil
+ "--window"
+ "--delay" "1"
+ "--file" "${PDIR}/${NAME}.png")
+ (comint-send-eof)
+ (refresh-display)
+ (kill-buffer shel)
+ (refresh-display)
+ (kill-emacs)
+ )
+TAC
+
+# ========================================
+# Produce the snapshot
+cd "${PDIR}"
+if [[ -e ../greenbar.el ]]; then
+ cd ..
+fi
+emacs --quick --load "${GEN_EL}"
+
+#
diff --git a/snapshots/graybar-dark-long.png b/snapshots/graybar-dark-long.png
new file mode 100644
index 0000000000..b29b498023
Binary files /dev/null and b/snapshots/graybar-dark-long.png differ
diff --git a/snapshots/graybar-dark-short.png b/snapshots/graybar-dark-short.png
new file mode 100644
index 0000000000..721b372c12
Binary files /dev/null and b/snapshots/graybar-dark-short.png differ
diff --git a/snapshots/graybar-light-long.png b/snapshots/graybar-light-long.png
new file mode 100644
index 0000000000..fde9645204
Binary files /dev/null and b/snapshots/graybar-light-long.png differ
diff --git a/snapshots/graybar-light-short.png
b/snapshots/graybar-light-short.png
new file mode 100644
index 0000000000..87cc7a3ce1
Binary files /dev/null and b/snapshots/graybar-light-short.png differ
diff --git a/snapshots/greenbar-dark-long.png b/snapshots/greenbar-dark-long.png
new file mode 100644
index 0000000000..51882f7d32
Binary files /dev/null and b/snapshots/greenbar-dark-long.png differ
diff --git a/snapshots/greenbar-dark-short.png
b/snapshots/greenbar-dark-short.png
new file mode 100644
index 0000000000..59df705488
Binary files /dev/null and b/snapshots/greenbar-dark-short.png differ
diff --git a/snapshots/greenbar-light-long.png
b/snapshots/greenbar-light-long.png
new file mode 100644
index 0000000000..2646e1d7c6
Binary files /dev/null and b/snapshots/greenbar-light-long.png differ
diff --git a/snapshots/greenbar-light-short.png
b/snapshots/greenbar-light-short.png
new file mode 100644
index 0000000000..19ba4243ea
Binary files /dev/null and b/snapshots/greenbar-light-short.png differ
diff --git a/snapshots/rainbow-dark-long.png b/snapshots/rainbow-dark-long.png
new file mode 100644
index 0000000000..35792782a1
Binary files /dev/null and b/snapshots/rainbow-dark-long.png differ
diff --git a/snapshots/rainbow-dark-short.png b/snapshots/rainbow-dark-short.png
new file mode 100644
index 0000000000..bd3c3524ea
Binary files /dev/null and b/snapshots/rainbow-dark-short.png differ
diff --git a/snapshots/rainbow-light-long.png b/snapshots/rainbow-light-long.png
new file mode 100644
index 0000000000..411833a8df
Binary files /dev/null and b/snapshots/rainbow-light-long.png differ
diff --git a/snapshots/rainbow-light-short.png
b/snapshots/rainbow-light-short.png
new file mode 100644
index 0000000000..2565240244
Binary files /dev/null and b/snapshots/rainbow-light-short.png differ
