commit 9a6271bd92105775c3cbc021737af3acf26b5af3
from: Brett Fisher <code@brettfisher.xyz>
date: Mon Jun 15 23:19:03 2026 UTC

README.md, bxbar.1: Add user-facing documentation.

  - Create README.md detailing build, configuration, and pipeline.
  - Create bxbar.1 manual page with standard SEE ALSO references.

commit - a06c6f9c6bd86e19f139cf1a06738cbcf9c704a2
commit + 9a6271bd92105775c3cbc021737af3acf26b5af3
blob - /dev/null
blob + 4eeeda6f2a06d78681828b4a464c801d37571eff (mode 644)
--- /dev/null
+++ README.md
@@ -0,0 +1,82 @@
+# bxbar
+
+A very basic X status bar.
+
+## Just the Right Amount of Info
+
+Similar to my path with bxwm and bxhkd, I wanted a status bar that  
+did neither more nor less than what I needed. I wanted a program  
+that only renders text, leaving the logic of gathering system data  
+to more appropriate tools. bxbar is the result: a minimal, EWMH  
+compliant dock that simply renders a string from standard input.
+
+## Dependencies
+
+- Xlib
+- Xft
+- A C compiler compliant with the C11 standard.
+
+## Build
+
+Compile bxbar from source.
+
+```
+make
+```
+
+## Install
+
+Install the binary, man page, and run command script. Note that root  
+privileges are not required as the default destination is `~/.local/`.
+
+```
+make install
+```
+
+## Uninstall
+
+Remove the binary, man page, and run command script.
+
+```
+make uninstall
+```
+
+## Configuration
+
+__bxbar__ is configured at compile-time by editing config.def.h.  
+After making changes, the program must be recompiled and  
+reinstalled. See bxbar(1) for details.
+
+## Design & Functionality
+
+__bxbar__ is built around a set of opinionated primitives:
+
+  - Renderer, NOT an orchestrator
+    - Reads from stdin
+    - Splits output into two sections (left and right) using an invisible separator (\x01)
+    - Renders to the top of the screen adhering to EWMH docking standards
+  - Helper Binaries
+    - bxinfo: Queries EWMH atoms directly from the X server for workspace/window state
+    - bxnet: Queries /sys/class/net/ to provide network connection status
+  - Lua Orchestration
+    - bxbarrc.lua: The orchestrator that gathers data from helpers and system files, formats the output, and pipes the string to bxbar
+
+Add the following to your `/.xinitrc` to start __bxbar__.
+
+```
+"$HOME"/.local/bin/bxbarrc.lua | "$HOME"/.local/bin/bxbar &
+```
+
+When __bxbar__ is used with bxwm(1) and bxhkd(1), add the following  
+to your `~/.xinitrc`.
+
+```
+# Start bxwm in the background, give it a moment to initialize
+"$HOME"/.local/bin/bxwm &
+sleep 1
+# Now start the rest of the session
+"$HOME"/.local/bin/bxbarrc.lua | "$HOME"/.local/bin/bxbar &
+"$HOME"/.local/bin/bxhkd &
+wait
+```
+
blob - /dev/null
blob + ddbc6bc75068b5ec10e78dd0d971729c1ef52784 (mode 644)
--- /dev/null
+++ bxbar.1
@@ -0,0 +1,57 @@
+.Dd June 14, 2026
+.Dt BXBAR 1
+.Os
+.Sh NAME
+.Nm bxbar
+.Nd basic X status bar
+.Sh SYNOPSIS
+.Nm
+.Sh DESCRIPTION
+.Nm
+is a lightweight, minimal status bar for the X11 window system that reads text from standard input and renders it to a dock window.
+.Nm
+is designed to be a transparent renderer, delegating data collection and formatting entirely to external scripts or C helper binaries.
+.Sh OPERATION
+.Nm
+manages the status bar in the following manner:
+.Bl -tag -width indent
+.It Sy Input Processing
+.Nm
+reads from standard input. It expects a single line of text formatted with a delimiter character (defaulting to the SOH control character) to split the output into a left-aligned and right-aligned segment.
+.It Sy Window Placement
+.Nm
+asserts the
+.Sy _NET_WM_WINDOW_TYPE_DOCK
+atom and reserves screen space using
+.Sy _NET_WM_STRUT_PARTIAL ,
+ensuring it remains at the top of the screen across all workspaces without obstructing application windows.
+.It Sy Concurrency
+.Nm
+listens to both standard input and X11 events via
+.Xr poll 2 ,
+ensuring the bar updates immediately upon receiving new data or window exposure events.
+.El
+.Sh CONFIGURATION
+.Nm
+is configured at compile-time by modifying the 
+.Pa config.def.h 
+header file. 
+After modifying this file, 
+.Nm
+must be recompiled and reinstalled to apply changes.
+.Sh FILES
+.Bl -tag -width ".Pa ~/.local/var/log/bxbar.log" -compact
+.It Pa config.def.h
+The default configuration file (see CONFIGURATION).
+.It Pa ~/.local/var/log/bxbar.log
+The log file for runtime diagnostics of 
+.Nm ,
+when invoked via shell redirection.
+.El
+.Sh SEE ALSO
+.Xr bxwm 1 ,
+.Xr bxhkd 1 ,
+.Xr xinit 1
+.Sh AUTHOR
+.An "Brett Fisher <code@brettfisher.xyz>."
+