dotfiles/README.adoc

= dotfiles
:toc:

My dotfiles for my Linux-based system setup.
The structure of this repo is designed to be managed with https://www.gnu.org/software/stow/[GNU Stow], a symlinks farm manager.

I don't know what I'm doing most of the time in creating this setup so if you're brave (or suicidal) enough to take a look at my stuff, go ahead.

CAUTION: As they always say: "Don't blindly apply these dotfiles unless you know what you're doing."
Review the code first, change the setting accordingly, and apply it on your own if you want.




== Tour of my setup

Here's what the setup should look like (aside from the Stow packages which will be discussed later):

[source]
----
dotfiles
├── .vtsm/
├── docs/
├── LICENSE
├── makefile
├── README.adoc
└── vtsm
----

The big picture for my dotfiles setup have big goals and those are (according to priority):

* Easy to transfer and/or reproduce.
* Modularity, https://github.com/holman/dotfiles[@holman]-style.
* Looking cool (but not too cool or else my potato will weep).


=== How I maintain my dotfiles

The dotfiles are mostly intended to be used with GNU Stow.
If you're not familiar with it, you can read http://brandon.invergo.net/news/2012-05-26-using-gnu-stow-to-manage-your-dotfiles.html[this sweet short article] to get you started.

However, with Python 3 (specifically 3.8) installed, you have another option.
Behold, the link:./vtsm["Very Tiny Stow Manager"] (VTSM for short)!
The best way to describe VTSM is basically GNU Stow with a generic shell runner.
VTSM takes inspiration from GNU Stow (obviously) and https://github.com/holman/dotfiles[how Zach Holman's dotfiles are set].
When managing your dotfiles, VTSM is going to be your friend/workmate.

All VTSM needs is a directory containing a package list stored in a JSON file with the name of the packages and their target path.
By default, it searches for a file named `locations.json` but you can specify what JSON file to use with the `-m`/`--manifest` option.

.An example of what a manifest could contain
[source, json]
----
{
    "alacritty": "$HOME/.config/alacritty/",
    "bin": "$HOME/bin/",
    "bspwm": "$HOME/.config/bspwm/",
    "dunst": "$HOME/.config/dunst/",
    "emacs": "$HOME/.config/doom",
    "lf": "$HOME/.config/lf",
    "nvim": "$HOME/.config/nvim/",
    "picom": "$HOME/.config/picom",
    "polybar": "$HOME/.config/polybar",
    "rofi": "$HOME/.config/rofi/",
    "sxiv": "$HOME/.config/sxiv",
    "sxhkd": "$HOME/.config/sxhkd/",
    "wal": "$HOME/.config/wal",
    "xorg": "$HOME",
    "zsh": "$HOME"
}
----

With the tiny manager and the package list, we can then execute commands with all of the packages and its target path with one go.
Here are some examples of running commands with VTSM.

[source, shell]
----
# Take the setup as the filesystem structure.
# See the JSON files at .vtsm to see what packages to be installed and where to install them.

# Running the program without any arguments for a test run.
# There should be a bunch of `echo` commands being ran for all of the listed packages.
./vtsm

# Create the directories of the target path and install them with GNU Stow.
# Bada-bing, bada-boom, you have installed your setup or something.
./vtsm --manifest .vtsm/arch.json --commands "mkdir -p {location} && stow {package} --target {location}"

# Run commands only to Rofi and Emacs config files.
./vtsm --manifest .vtsm/arch.json --only "rofi" "emacs" --commands "stow --restow {package} --target {location}"
----

For the command string, it is a https://docs.python.org/3/library/string.html#string.Template[Python template] with `package` and `location` as the available objects.


=== Custom scripts

Next are more custom scripts!
They're located in link:bin/[`bin/`] and ideally should be linked in `$HOME/.local/bin`.
footnote:[This is a part of the package list but I think it's appropriate to create a dedicated subsection for this.]

Here's a list of the top most useful scripts (at least for me):

* link:./bin/rofi-screenshot-menu[A Rofi menu for all of my screenshoting and screencasting needs].
The script is also a fork of https://github.com/ceuk/rofi-screenshot[`ceuk's` rofi-screenshot].
Big thanks to them for the idea!

* link:./bin/ocr[An image selection-to-text script using OCR].
Capture a region, process it through an OCR engine, and the content are then copied into the clipboard.
Useful for capturing links in images or videos usually found in lecture videos.

* link:./bin/user-prompt[Quick command prompts].
The script is based from https://github.com/LukeSmithxyz/voidrice/blob/master/.local/bin/prompt[Luke Smith's prompt script].

* link:./bin/toggle-process[Switching on/off programs].
Useful for situations where only one instance of the program is desirable.

* link:./bin/choose-emoji-menu[A universal emoji list] for easy copy-pasting and clear communication with those who speak Emojian.




== Inspirations

* https://github.com/addy-dclxvi/almighty-dotfiles/
* https://github.com/LukeSmithxyz/voidrice
* https://github.com/adi1090x
* https://github.com/jethrokuan/dots/ for his Emacs and Org Mode writing setup.
He also has a dedicated series on his https://blog.jethro.dev/[blog site] if you want the juicy details.
* https://www.reddit.com/r/unixporn/ obviously.
* Specifically for https://www.reddit.com/r/unixporn/comments/8ezsq7/bspwm_terminal_tabs_in_polybar_dark_and_dull_exam/[the tabbed terminals idea] and the https://github.com/Nikzt/dotfiles[linked dotfiles repo]) (not yet implemented, still cleaning up my stuff)
* https://www.reddit.com/r/unixporn/comments/edmb8b/awesome_gnawesome/[Just] https://github.com/ilovecookieee/Glorious-Dotfiles[saving] https://github.com/PapyElGringo/material-awesome[these] for an **awesome** future, hehehe.




== Wallpapers

Here's a list of some of the best wallpapers I've used throughout my ricing journey.
I've also tried to get the creators to show appreciation for their work.

* https://www.deviantart.com/rmradev/art/Alien-Moon-743912901[`alien-moon.jpg`]
** Creator: https://www.deviantart.com/rmradev[rmRadev]

* https://dribbble.com/shots/3713646-Small-Memory[`forest-bright.jpg`]
** Creator: https://dribbble.com/MikaelGustafsson[Mikael Gustafsson]

* https://dropr.com/mbdsgns/254740/hotline_miami_iv/+?p=1388845[`hotline-miami-alt-cover.png`]
** Creator: https://dropr.com/mbdsgns[Mbdsgns]

* https://www.artstation.com/artwork/wn8ng[`long-walk-home.jpg`]
** Creator: https://www.artstation.com/beaulamb[Beau Lamb]

* https://www.reddit.com/r/wallpapers/comments/g6tgst/night_landscape_mountain_and_milky_way_galaxy[`mountain-with-galaxy.jpg`]
** I was not able to track down the photographer of this one.

* https://www.reddit.com/r/wallpapers/comments/cckpj0/i_made_this_simple_and_clean_drawing_over_the/[`nebula.jpg`]
** Creator: https://www.reddit.com/user/datGryphon/[datGryphon]

* https://www.artstation.com/artwork/XOQdR[`the-core.jpg`]
** Creator: https://www.artstation.com/beaulamb[Beau Lamb]

* https://www.reddit.com/r/wallpapers/comments/ebvk0q/rocket_launch_1920x1080/[`rocket-launch.jpg`]

* https://www.artstation.com/artwork/XBlZbY[`scarecrow-field.jpg`]
** Creator: https://www.artstation.com/joejazz[Josef Bartoň]


=== Sources

My personal recommendations for looking out for more cool-looking photos.

* https://images.nasa.gov/[Images from NASA].
They also have a small collection of them in their https://unsplash.com/@nasa[Unsplash account].
* https://imgur.com/gallery/4BKvq[Firewatch] (or any style similar to Firewatch) wallpapers are top-notch ricing material.
* https://mantissa.artstation.com/[Midge "Mantissa" Sinnaeve]
* https://www.artstation.com/beaulamb[Beau Lamb]
* http://louie.co.nz/[Louis Coyle] and https://dribbble.com/louiscoyle[his illustrations].
* https://www.deviantart.com/rmradev[rmRadev]
* https://www.reddit.com/r/wallpapers/[/r/wallpapers]
* https://unsplash.com/s/photos/galaxy-landscape[Any image that features a landscape with stars, lel.]
* https://www.pexels.com/[Pexels]
* https://www.pixabay.com/[Pixabay]
* https://unsplash.com/[Unsplash]