From 9bb6d3ee8a1bfc66a709c88b0b2f2006e9b8dc0e Mon Sep 17 00:00:00 2001 From: Tommaso Negri Date: Mon, 10 Aug 2026 22:55:16 +0200 Subject: improve docs --- Sources/bar/bar.docc/bar.md | 1 + Sources/bar/bar.docc/command.md | 12 ++++++++++ Sources/bar/bar.docc/highlighting.md | 4 ++++ Sources/bar/bar.docc/how-it-works.md | 2 +- Sources/bar/bar.docc/installation.md | 3 +++ Sources/bar/bar.docc/patches.md | 4 ++++ Sources/bar/bar.docc/patches/patch-font-offset.md | 6 +++++ .../bar/bar.docc/patches/patch-screen-hotplug.md | 26 ++++++++++++++++++++++ Sources/bar/bar.docc/screens.md | 18 +++++++++++++++ 9 files changed, 75 insertions(+), 1 deletion(-) create mode 100644 Sources/bar/bar.docc/patches/patch-screen-hotplug.md create mode 100644 Sources/bar/bar.docc/screens.md diff --git a/Sources/bar/bar.docc/bar.md b/Sources/bar/bar.docc/bar.md index 0788349..ae515a0 100644 --- a/Sources/bar/bar.docc/bar.md +++ b/Sources/bar/bar.docc/bar.md @@ -32,6 +32,7 @@ If you specify the interval, the block will re-run the command with such frequen ### Bar +- - ### Blocks diff --git a/Sources/bar/bar.docc/command.md b/Sources/bar/bar.docc/command.md index c94862e..da1a71f 100644 --- a/Sources/bar/bar.docc/command.md +++ b/Sources/bar/bar.docc/command.md @@ -22,3 +22,15 @@ Each command inherits the `bar` process environment plus a `BLOCK` variable that > Important: Since the environment is inherited by the `bar` process, there is no guarantee that the script will always receive the same set of variables. For example, if you run `bar` from your shell, you'll probably have available the custom `PATH` you set. On the contrary, if you run `bar` from a launch agent, you'll probably not have the same custom `PATH` set. + +## Error handling + +If the command exits with a non-zero status or cannot be launched, the block displays a single cell containing the text `ERROR`. +The command's stderr is forwarded to the `bar` process stderr, which you can inspect for the actual failure. + +```shell +# Example: simulate a command failure +some-command-that-fails && echo "&!1 success" +``` + +> Tip: If you see `ERROR` in the bar, run the command manually in your terminal to diagnose the issue. diff --git a/Sources/bar/bar.docc/highlighting.md b/Sources/bar/bar.docc/highlighting.md index 8bd737c..aa2ad0d 100644 --- a/Sources/bar/bar.docc/highlighting.md +++ b/Sources/bar/bar.docc/highlighting.md @@ -34,4 +34,8 @@ echo "&!2 workspace 2" # highlighted with Config.highlights[1] echo "workspace 3" # no highlight ``` +> Important: The `&!` notation is stripped before rendering, so only the text after it is displayed. +> For example, `&!1 workspace 1` renders as `workspace 1` on a highlighted background. + > Important: The highlight level is a positive integer that indexes into ``Config-swift.enum/highlights`` (1-based). +> If the level exceeds the number of defined highlights, the cell is treated as unhighlighted. diff --git a/Sources/bar/bar.docc/how-it-works.md b/Sources/bar/bar.docc/how-it-works.md index b6efbd8..e81e40a 100644 --- a/Sources/bar/bar.docc/how-it-works.md +++ b/Sources/bar/bar.docc/how-it-works.md @@ -29,7 +29,7 @@ The way to install *bar* is simply to download or clone the repository on your s What if you need a specific feature that is not available? Well, you can build it or patch it yourself. -*bar* aims to stay focused and minimal, so it can be read through and understood in roughly half an hour. +*bar* aims to stay focused and minimal, so it can be read through and understood in roughly an hour. You're more than encouraged to apply to extend the software, write your own features, and ultimately publish them for the entire community. This approach is far more powerful than a plugin/extension ecosystem because you're not limited to what we, as the main developers, decide you can customise or change. diff --git a/Sources/bar/bar.docc/installation.md b/Sources/bar/bar.docc/installation.md index 272882e..6475aa1 100644 --- a/Sources/bar/bar.docc/installation.md +++ b/Sources/bar/bar.docc/installation.md @@ -33,6 +33,9 @@ make install > make install PREFIX=/usr/local/bin > ``` +> Tip: While iterating on the configuration, use `make run` instead. +> It builds and runs the program in one step without copying the binary, which speeds up the edit-compare loop. + ### Without make If you don't have `make`, build directly with the Swift Package Manager: diff --git a/Sources/bar/bar.docc/patches.md b/Sources/bar/bar.docc/patches.md index 1a356c9..e2646f3 100644 --- a/Sources/bar/bar.docc/patches.md +++ b/Sources/bar/bar.docc/patches.md @@ -88,3 +88,7 @@ To publish, upload the patch somewhere publicly accessible (e.g., the *bar* GitH ### Appearance - + +### Functionality + +- diff --git a/Sources/bar/bar.docc/patches/patch-font-offset.md b/Sources/bar/bar.docc/patches/patch-font-offset.md index 9b2d841..3c1e0ad 100644 --- a/Sources/bar/bar.docc/patches/patch-font-offset.md +++ b/Sources/bar/bar.docc/patches/patch-font-offset.md @@ -21,6 +21,12 @@ enum Config { curl -sL https://raw.githubusercontent.com/paninihouse/bar/refs/heads/master/patches/bar-font_offset-20260810-11d813c.patch | patch -p1 ``` +After applying, rebuild the program: + +```shell +make install +``` + ## Author Tommaso Negri [@tommasongr](https://github.com/tommasongr) diff --git a/Sources/bar/bar.docc/patches/patch-screen-hotplug.md b/Sources/bar/bar.docc/patches/patch-screen-hotplug.md new file mode 100644 index 0000000..b1aee91 --- /dev/null +++ b/Sources/bar/bar.docc/patches/patch-screen-hotplug.md @@ -0,0 +1,26 @@ +# Screen hot-plug + +Recreate bars when a display is connected or disconnected at runtime. + +Without this patch, *bar* only creates windows for the screens connected at launch. +If you plug in or unplug a display while the program is running, nothing changes. +This patch observes the system notification for display configuration changes and rebuilds the bar windows to match the new screen layout. + +All windows are closed and reopened, so every bar picks up the correct position and size for its screen. +The block content is preserved during the rebuild — there is no need to re-run commands. + +## Installation + +```shell +curl -sL https://raw.githubusercontent.com/paninihouse/bar/refs/heads/master/patches/bar-screen_hotplug-20260810-f6805c9.patch | patch -p1 +``` + +After applying, rebuild the program: + +```shell +make install +``` + +## Author + +Tommaso Negri [@tommasongr](https://github.com/tommasongr) diff --git a/Sources/bar/bar.docc/screens.md b/Sources/bar/bar.docc/screens.md new file mode 100644 index 0000000..99d9385 --- /dev/null +++ b/Sources/bar/bar.docc/screens.md @@ -0,0 +1,18 @@ +# Multi-screen + +How the bar behaves when more than one display is connected. + +At launch, *bar* creates one bar for **each screen** connected to your Mac. +Every bar spans the full width of its own screen and is anchored at the top or bottom edge, depending on the ``Config-swift.enum/position`` setting. +All bars display the same set of ``Block``, so each screen mirrors the others. + +You don't need to configure anything per-display: every bar is built from the same ``Config``, and the ``Screen`` type sizes it automatically to fit its screen's frame. +This also means that bars on displays with different resolutions are sized to match each screen. + +## Adding or removing displays + +Bars are created when the program starts, based on the screens connected at that moment. +If you connect or disconnect a display while the program is already running, *bar* does **not** automatically add or remove a bar for it. +To pick up the new screen layout, restart the program. + +> Note: Handling display hot-plugging at runtime is not part of the core, but the screen code is small and self-contained, which makes it a good candidate for a custom . \ No newline at end of file -- cgit v1.2.3