From 6e6f804c08d10d19774870e3076d8d12dbd83347 Mon Sep 17 00:00:00 2001 From: Marty Oehme Date: Sat, 7 Jun 2025 09:38:37 +0200 Subject: [PATCH] repo: Format README --- README.md | 70 ++++++++++++++++++++++++++++--------------------------- 1 file changed, 36 insertions(+), 34 deletions(-) diff --git a/README.md b/README.md index 46cca40..588629c 100644 --- a/README.md +++ b/README.md @@ -1,19 +1,19 @@ # `~/🌹` -Note that the below screenshots still show the X configuration from [v0.1](https://gitlab.com/marty-oehme/dotfiles/-/tags/v0.1) which is *very* old by now. +Note that the below screenshots still show the X configuration from [v0.1](https://gitlab.com/marty-oehme/dotfiles/-/tags/v0.1) which is _very_ old by now. The current dotfiles are geared toward wayland for which the setup looks similar but not identical to the previews below. ## What's in these dotfiles -* [x] wayland setup using `riverwm` with quick access to many overlays and picking tools for styles, downloads, browsing history, passwords and more -* [x] vim configuration for simple programming tasks (especially python/bash/lua) and prose (markdown/quarto/latex) -* [x] academic workflow tools, to allow quick citation, pdf compilation, and preview -* [x] simple, efficient waybar with package update notification and mpris integration -* [x] system-wide color management (terminals, vim, qutebrowser, polybar, xresources) through [`flavours`](https://github.com/Misterio77/flavours) application using [base16](http://chriskempson.com/projects/base16/) themes -* [x] quick theme switching by activating `flavours` and fuzzy-searching themes with hot-key (default `=+S`) -* [x] quick directory jumping using `z`, with `fzf` integration -* [x] `fzf`-like integrations for bibtex citation, vim buffer management, most recently used switching, shell command history, and more -* [x] password management with `pass` and picking it with automatic typing into any window +- [x] wayland setup using `riverwm` with quick access to many overlays and picking tools for styles, downloads, browsing history, passwords and more +- [x] vim configuration for simple programming tasks (especially python/bash/lua) and prose (markdown/quarto/latex) +- [x] academic workflow tools, to allow quick citation, pdf compilation, and preview +- [x] simple, efficient waybar with package update notification and mpris integration +- [x] system-wide color management (terminals, vim, qutebrowser, polybar, xresources) through [`flavours`](https://github.com/Misterio77/flavours) application using [base16](http://chriskempson.com/projects/base16/) themes +- [x] quick theme switching by activating `flavours` and fuzzy-searching themes with hot-key (default `=+S`) +- [x] quick directory jumping using `z`, with `fzf` integration +- [x] `fzf`-like integrations for bibtex citation, vim buffer management, most recently used switching, shell command history, and more +- [x] password management with `pass` and picking it with automatic typing into any window [![Styler recoloring demo](https://gitlab.com/marty-oehme/dotfiles/-/wikis/uploads/bde87deda694590a2e08e21552e11309/styler.webp)](https://gitlab.com/marty-oehme/dotfiles/-/wikis/uploads/90894e53eff378db4d7f9f49e7a69fab/styler.mp4) @@ -25,17 +25,18 @@ I would recommend doing an initial `git clone --recursive` for this repository, Of course, you can do it non-recursively and then just pull those modules selectively which you actually want. Once in the repository directory, when you then run `./install.sh` it will install many of the packages I use (though they are probably slightly out-of-date) and link the dotfiles into the home directory. -I would mostly recommend this on fresh machines or a test machine first - it *will* link my personal dotfiles and, if you allow it, *will* install quite a few packages. +I would mostly recommend this on fresh machines or a test machine first - it _will_ link my personal dotfiles and, if you allow it, _will_ install quite a few packages. By default it will ask your consent for some steps -- use `./install.sh -f` to force yes to everything. -The dotfile installation procedure is based on `dotter`, it will generally *not overwrite* anything already in the home directory, but of course be observant when doing ptentially destructive operations. +The dotfile installation procedure is based on `dotter`, it will generally _not overwrite_ anything already in the home directory, but of course be observant when doing ptentially destructive operations. > **NOTE** -> The same non-destructive installation procedure does *not* apply to the package installation and system setting file linking, where it can potentially overwrite or remove existing files. +> The same non-destructive installation procedure does _not_ apply to the package installation and system setting file linking, where it can potentially overwrite or remove existing files. After all files are linked and you open a new shell session, the `dotlink` alias will allow you to re-link all dotfiles from anywhere on the system.[^1] -[^1]: This alias only works when the dotfiles are cloned into `~/.dotfiles`, mirroring my setup. +[^1]: + This alias only works when the dotfiles are cloned into `~/.dotfiles`, mirroring my setup. This is due to a hard-coded cd into this directory. If your dotfiles lie in another directory and you want to use the dotlink alias, simply change the corresponding line in `bootstrap/.config/sh/alias.d/dotlink.sh` @@ -48,29 +49,30 @@ Enjoy! ![Overview - an older image of the dotfile desktop with gaps, showing git logs, styler logs, duckduckgo in a browser, and a vifm view of the dotfiles themselves](https://gitlab.com/marty-oehme/dotfiles/-/wikis/uploads/aaf0319d575dc192ea0f4bd6eaf83c08/gaps.png) -* [`wayland`](https://github.com/wayland-project/wayland) - Containing basics for fully functional tiling wayland setup: - * [`river`](https://github.com/riverwm/river) - Tiling window manager for wayland - * [`waybar`](https://github.com/Alexays/Waybar) - Easily customizable statusbar for wayland - * [`bemenu`](https://github.com/Cloudef/bemenu) - Extended dmenu replacement for wayland, X11 and ncurses - * [`fontconfig`] - System-wide font replacements and styling settings -* [`wezterm`](https://wezfurlong.org/wezterm/) - Terminal emulator and multiplexer (fast, understandable and lua configurable) -* [`nvim`](https://neovim.io/) - Neovim configuration -* [`vifm`](https://github.com/vifm/vifm) - vim-like file-manager -* [`qutebrowser`](https://github.com/qutebrowser/qutebrowser) - vim-key enabled web browser -* [`pass`](pass/README.md) - Password management suite -* [`bibtex`] - LateX/BibteX/pandoc plaintext writing & reference suite (slowly migrating toward [typst](https://typst.app)) -* [`git`](git/README.md) - distributed version control system. -* [`office`](office/README.md) - office/productivity software for writing e-mail and setting appointments +- [`wayland`](https://github.com/wayland-project/wayland) - Containing basics for fully functional tiling wayland setup: + - [`river`](https://github.com/riverwm/river) - Tiling window manager for wayland + - [`waybar`](https://github.com/Alexays/Waybar) - Easily customizable statusbar for wayland + - [`bemenu`](https://github.com/Cloudef/bemenu) - Extended dmenu replacement for wayland, X11 and ncurses + - [`fontconfig`] - System-wide font replacements and styling settings +- [`wezterm`](https://wezfurlong.org/wezterm/) - Terminal emulator and multiplexer (fast, understandable and lua configurable) +- [`nvim`](https://neovim.io/) - Neovim configuration +- [`vifm`](https://github.com/vifm/vifm) - vim-like file-manager +- [`qutebrowser`](https://github.com/qutebrowser/qutebrowser) - vim-key enabled web browser +- [`pass`](pass/README.md) - Password management suite +- [`typst`] - LateX/BibteX/pandoc-like plaintext writing & reference suite +- [`jujutsu`](vcs/README.md) - distributed version control system, together with git. +- [`office`](office/README.md) - office/productivity software for writing e-mail and setting appointments ## Notes -* Generally, most configuration for applications attempts to follow the XDG specifications, keeping configuration in .config directory and supplementary files in .local/share directory. Over time, I am moving more applications to this standard: it keeps the home directory clean, and the separation of configuration, binaries, and data relatively clear. -* The `zsh` directory contains all setup for the z-shell, my daily work environment. It should not be required for working with any other module but will add additional functionality to many (such as command auto-completion and so on). `sh` sets some base functionality for any shell you may wish to work in. It is, for now, the only module that is required for some other modules to work.[^shreq] -* `rofi` contains additional scripts and a simple theming framework for rofi and should probably be reorganized to put the correct files into the correct directories (per xdg) at some point. -* Whereas `sh` module scripts are requirements for other scripts, `.local/bin` in the `scripts` module contains most executable user scripts. Most of these have been migrated to other corresponding modules (e.g. if a script exclusively targets git functionality, it will live there), some useful --- or left-over --- stand-alone scripts remain however. -* `.local/share/pandoc` contains configuration for academic latex writing (pandoc, really) and is of interest if you want to use this functionality. -* `.xinitrc` is used for x initialization and program startup. At some point, some of the consistently running applications may be moved to systemd/runit as supervised services. -* Generally, top-level directories starting with a . are only meaningful for the *repository* not for the functionality of the machine that these dotfiles are deployed on. That means `.gitlab-ci.yml`, `.assets/`, `.gitignore` and similar files and directories will not show up in the final deployment in any home directory. Perhaps they should be called dotdot-files since they're the dotfiles for my dotfiles. 🙂 (Also, '[dotfiles](https://en.wikipedia.org/wiki/Semantic_satiation)'.) +- This are a good sign. +- Generally, most configuration for applications attempts to follow the XDG specifications, keeping configuration in .config directory and supplementary files in .local/share directory. Over time, I am moving more applications to this standard: it keeps the home directory clean, and the separation of configuration, binaries, and data relatively clear. +- The `zsh` directory contains all setup for the z-shell, my daily work environment. It should not be required for working with any other module but will add additional functionality to many (such as command auto-completion and so on). `sh` sets some base functionality for any shell you may wish to work in. It is, for now, the only module that is required for some other modules to work.[^shreq] +- `rofi` contains additional scripts and a simple theming framework for rofi and should probably be reorganized to put the correct files into the correct directories (per xdg) at some point. +- Whereas `sh` module scripts are requirements for other scripts, `.local/bin` in the `scripts` module contains most executable user scripts. Most of these have been migrated to other corresponding modules (e.g. if a script exclusively targets git functionality, it will live there), some useful --- or left-over --- stand-alone scripts remain however. +- `.local/share/pandoc` contains configuration for academic latex writing (pandoc, really) and is of interest if you want to use this functionality. +- `.xinitrc` is used for x initialization and program startup. At some point, some of the consistently running applications may be moved to systemd/runit as supervised services. +- Generally, top-level directories starting with a . are only meaningful for the _repository_ not for the functionality of the machine that these dotfiles are deployed on. That means `.gitlab-ci.yml`, `.assets/`, `.gitignore` and similar files and directories will not show up in the final deployment in any home directory. Perhaps they should be called dotdot-files since they're the dotfiles for my dotfiles. 🙂 (Also, '[dotfiles](https://en.wikipedia.org/wiki/Semantic_satiation)'.) [^shreq]: I may remove this requirement in the future to make modules more self-contained. However, relying on some base utility scripts makes it easier to avoid duplicating such functionality for each individual script in other modules.