commit 912fd0ccffffa682b59d32ff58415fb3159261c8
from: Alexander Arkhipov <aa@manpager.net>
date: Mon May 29 01:33:57 2023 UTC

initial documentation and build system

commit - f1adc4ca44afccc5144df050a613b590cd8a4175
commit + 912fd0ccffffa682b59d32ff58415fb3159261c8
blob - /dev/null
blob + 712ab075be4ade6baf8513e86d1409f0553ad128 (mode 644)
--- /dev/null
+++ Makefile
@@ -0,0 +1,43 @@
+include config.mk
+include version.mk
+
+.SUFFIXES: .o .c
+
+BIN = xitems
+OBJ = $(BIN:=.o)
+SRC = $(BIN:=.c)
+MAN = $(BIN:=.1)
+
+all: $(BIN)
+
+$(BIN): $(OBJ)
+	$(CC) $(CFLAGS) $(PCCFLAGS) -o $@ $(OBJ) $(LDFLAGS)
+
+$(OBJ): config.mk
+
+.c.o:
+	$(CC) $(CFLAGS) $(CPPFLAGS) -c $<
+
+install: all
+	mkdir -p $(DESTDIR)$(PREFIX)/bin
+	install -m 755 $(BIN) $(DESTDIR)$(PREFIX)/bin
+	mkdir -p $(DESTDIR)$(MANPREFIX)/man1
+	install -m 644 $(MAN) $(DESTDIR)$(MANPREFIX)/man1
+
+uninstall:
+	cd $(DESTDIR)$(PREFIX)/bin && rm -f $(BIN)
+	cd $(DESTDIR)$(MANPREFIX)/man1 && rm -f $(MAN)
+
+clean:
+	-rm -rf $(BIN) $(OBJ) xitems$(V) *.tar.gz *.core
+
+dist: clean
+	mkdir xitems$(V)
+	cp $(SRC) $(MAN) README COPYING Makefile config.mk version.mk xitems$(V)
+	tar cf - xitems$(V) | gzip >xitems$(V).tar.gz
+	rm -rf xitems$(V)
+
+tags: $(SRC)
+	ctags $(SRC)
+
+.PHONY: all install uninstall clean dist
blob - /dev/null
blob + dc65172c8f693284530a5d6e94029e91838d5326 (mode 644)
--- /dev/null
+++ README
@@ -0,0 +1,10 @@
+xitems is a menu utility for X, it can be controled with keyboard and with
+mouse. A list of items, along with an optional list of keys for quick selection
+is read on stdin. The chosen item is printed on stdout.
+
+To install, please modify config.mk, as necessary and run `make', followed by
+`make install' (possibly as root):
+
+	$ $EDITOR config.mk
+	$ make
+	# make install
blob - /dev/null
blob + 117bed2c90dfa84804086314af1175f9300faebd (mode 644)
--- /dev/null
+++ config.mk
@@ -0,0 +1,9 @@
+PREFIX ?= /usr/local
+MANPREFIX ?= /usr/local/man
+
+CFLAGS = -std=c99 -Wall -pedantic
+CPPFLAGS = -I/usr/X11R6/include
+LDFLAGS = -L/usr/X11R6/lib -lX11
+
+# debug
+#CFLAGS = -std=c99 -Wall -pedantic -Wextra -O0 -g3
blob - /dev/null
blob + f623384ddf344ff6e3d37f96317242f142b00d31 (mode 644)
--- /dev/null
+++ version.mk
@@ -0,0 +1 @@
+V = 0.1
blob - /dev/null
blob + 1adf25493a4ab230b04053aabecdaed091f4ad81 (mode 644)
--- /dev/null
+++ xitems.1
@@ -0,0 +1,172 @@
+.Dd May 29, 2023
+.Dt XITEMS 1
+.Os
+.Sh NAME
+.Nm xitems
+.Nd menu for X
+.Sh SYNOPSIS
+.Nm
+.Op Fl font Ar font
+.Op Fl bg Ar colour
+.Op Fl fg Ar colour
+.Op Fl sbg Ar colour
+.Op Fl sfg Ar colour
+.Op Fl bc Ar colour
+.Op Fl bw Ar width
+.Op Fl hp Ar pad
+.Op Fl vp Ar pad
+.Op Fl x Ar x
+.Op Fl y Ar x
+.Sh DESCRIPTION
+The X utility
+.Nm
+draws a menu, based on stdin
+(here refer to a later section)
+and prints the user's choice to stdout.
+The options are as follows:
+.Bl -tag -width Ds
+.It Fl font Ar font
+The font to be used for displaying text.
+Corresponds to the resource font.
+Default is
+.Dq fixed .
+.It Fl bg Ar colour
+Specifies the normal background colour.
+Corresponds to the resource background.
+Default is
+.Dq white .
+.It Fl fg Ar colour
+Specifies the normal foreground colour.
+Corresponds to the resource foreground.
+Default is
+.Dq black .
+.It Fl sbg Ar colour
+Specifies the background colour for selected item.
+Corresponds to the resource selectedBackground.
+Default is
+.Dq black .
+.It Fl sfg Ar colour
+Specifies the foreground colour for selected item.
+Corresponds to the resource selectedForeground.
+Default is
+.Dq white .
+.It Fl bc Ar colour
+Specifies the border colour.
+Corresponds to the resource borderColour.
+Default is
+.Dq black .
+.It Fl bw Ar width
+Specifies the border width.
+Corresponds to the resource borderWidth.
+Default is 1.
+.It Fl hp Ar pad
+Specifies the horizontal padding.
+Corresponds to the resource horizontalPadding.
+Default is 2.
+.It Fl vp Ar pad
+Specifies the vertical padding.
+Corresponds to the resource verticalPadding.
+Default is 1.
+.It Fl x Ar x
+The horizontal position to spawn the window at.
+Default corresponds to the horizontal position of the pointer.
+.It Fl y Ar y
+The vertical position to spawn the window at.
+Default corresponds to the vertical position of the pointer.
+.El
+.Pp
+The options, which correspond to a resource take precedence over that
+resource.
+.Pp
+.Nm
+reads contents of the menu on stdin.
+The input consists of one, or several newline-separated entries (items).
+Each entry has the following format:
+.Pp
+.Dl ITEM := [KEYS] TAB LABEL
+.Pp
+The optional KEYS field consists of one or more space-separated key
+strings, such that can be used with
+.Xr XStringToKeysym 3 .
+Pressing any of these keys immediately select this item.
+Keys are configured case-insensitively.
+.Ss Key and button bindings
+.Nm
+can be intuitively controlled with mouse by bringing the pointer over
+the desired item and clicking.
+Additional key and button bindings are as follows:
+.Bl -tag -width Ds
+.It Scroll down , j , down , control-n
+Move selection one item down.
+.It Scroll up , k , up , control-p
+Move selection one item up.
+.It Escape , control-c
+Quit, outputting nothing.
+.It Return , control-m , control-j
+Quit, outputting the selected item.
+.It Button 1, button 2, button 3
+Quit.
+If the pointer is inside the window, output the selected item,
+otherwise output nothing.
+.El
+.Sh RESOURCES
+.Nm
+understands the following resources:
+.Bl -tag -width Ds
+.It Ic xitems.font
+Specifies the font to be used for displaying text.
+.It Ic xitems.foreground , xitems,background
+Specifies the normal foreground and background colours.
+.It Ic xitems.selectedForeground , xitems,selectedBackground
+Specifies the foreground and background colours for selected items.
+.It Ic xitems.borderColour
+Specifies the border colour.
+.It Ic xitems.borderWidth
+Specifies the border width.
+.It Ic xitems.verticalPadding , xitems.horizontalPadding
+Specifies the vertical and horizontal padding.
+.El
+.Sh EXAMPLES
+The following script displays a menu with items
+.Dq Monitor ,
+.Dq xTerm
+and
+.Dq xCalc .
+Each can be selected by pressing the key, corresponding to the capital
+letter, or the Cyrillic key, sharing the same position.
+Selecting
+.Dq Monitor
+creates a similar menu, and selecting anything else runs the
+corresponding command.
+.Bd -literal -offset indent
+#!/bin/sh
+
+topmenu() {
+	xitems <<-x
+m Cyrillic_softsign	Monitor
+t Cyrillic_e	xTerm
+e Cyrillic_u	xCalc
+	x
+}
+
+monitormenu() {
+	xitems <<-x
+b Cyrillic_i	xBiff
+c Cyrillic_es	xConsole
+	x
+}
+
+s=$(topmenu)
+
+[ -z "$s" ] && exit
+
+if [ "$s" = Monitor ]; then
+	monitormenu
+else
+	echo $s
+fi | tr '[A-Z]' '[a-z]' | sh
+.Ed
+.Sh AUTHORS
+.An Alexander Arkhipov Aq Mt aa@manpager.net .
+.Sh EXIT STATUS
+.Ex -std