diff options
| -rw-r--r-- | Sources/bar/bar.docc/bar.md | 1 | ||||
| -rw-r--r-- | Sources/bar/bar.docc/command.md | 12 | ||||
| -rw-r--r-- | Sources/bar/bar.docc/highlighting.md | 4 | ||||
| -rw-r--r-- | Sources/bar/bar.docc/how-it-works.md | 2 | ||||
| -rw-r--r-- | Sources/bar/bar.docc/installation.md | 3 | ||||
| -rw-r--r-- | Sources/bar/bar.docc/patches.md | 4 | ||||
| -rw-r--r-- | Sources/bar/bar.docc/patches/patch-font-offset.md | 6 | ||||
| -rw-r--r-- | Sources/bar/bar.docc/patches/patch-screen-hotplug.md | 26 | ||||
| -rw-r--r-- | Sources/bar/bar.docc/screens.md | 18 |
9 files changed, 75 insertions, 1 deletions
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 +- <doc:screens> - <doc:hide-show> ### 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 `&!<level>` 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 <doc:patches> 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 - <doc:patch-font-offset> + +### Functionality + +- <doc:patch-screen-hotplug> 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 <doc:patches>.
\ No newline at end of file |