Improve docs

[murlakatamenka]

The current state is like this (my yesterday's experience of trying to convert KDEs Breeze Light to hyprcursor):

1. Open Hyprland wiki, Hyprcursor. It says go to github

2. Open this repo. It says go read ./docs

3. There are 3 files there. Okay, checking all of them

4. One says go read stuff of hyprcursor-util (why isn't the binary just hyprcursor btw?). Mkay, I guess, somewhat helpful.

5. Time to play with the binary. No -h/--help there. Okay, it's C++ after all, there are no CLI parsing libs and adding/mananaging dependencies is kinda pain in the arse (hi, cargo add clap --features derive).

In the end something like this works, but it's not user-freindly and is somewhat time consuming to get there:

hyprcursor-util --extract /usr/share/icons/breeze/<forgot-im-on-mobile-but-thatpath-is-important> -o /tmp/extracted-breeze-cursors

# edit theme meta
nvim /tmp/extracted.../manifest.hl

# optimize png, cause why not
oxipng -o max /tmp/extracted.../**.png

# actually create a hyprcursor theme
hyprcursor-util --create /tmp/extracted... -o my-supa-dupa-theme

mv my-supa-dupa-theme ~/.local/share/icons

hyprctl setcursor 'Theme name from manifest.hl' <cursor-size>

It's hard to expect any adoption if such basic scenario isn't trivial to find.

Can we add something like this to main README.md. I would carefully assume that this what an average Joe wants when he tries to switch to new cool hyprcursor. Converting an existing XCursor theme should be trivial, if no edits are needed (let's not talk about animations here). I didn't edit anything but name/description in the manifest file, as you can see.

[vaxerski]

well the thing is we don't want the "average joe" to convert his themes, because one of the key advantages of hyprcursor is that it supports svg. It's better to clearly direct them to #hyprcursor-themes (or maybe make a common repository of some themes?) and get their themes from there

[murlakatamenka]

well the thing is we don't want the "average joe" to convert his themes, because one of the key advantages of hyprcursor is that it supports svg

Well, okay. At the same time, even converting XCursor theme to its Hypr equivalent is much better due to PNG compression. That's what the util supports (--extract), so while not ideal, it's a fine use case hyprcursor-util for personal use. A single favorite style of Bibata takes 5- MiB as Hyprtheme, while AUR package bibata-cursor-theme-bin takes 321 MiB 😨 LGTM, right?

---

A quick search of hyprcursor on AUR and GitHub yields a single theme:

• AUR
• GitHub

Pretty lackluster, right? Of course, I understand it's new and all.

The point is, the docs don't make it easy to follow your steps:

You can convert an xcursor theme to a hyprcursor theme in 5 minutes using the hyprcursor-util
in the hyprcursor repo.

Took me waaay more time and creating the issue. Having reproducible example(s) in the docs would make them much better. Can we have one?

spoiler

Having examples is super helpful, especially compared to multiple `goto docs`:

https://github.com/hyprland-community/hyprland-rs/tree/master/examples

Even the wrapper around the fresh hyprcursor has an example, how cool is that for the starters?

https://github.com/morr0ne/rusty-hyprcursor/blob/main/examples/

[vaxerski]

feel free to make a MR. I am just a developer.

[0x2f0]

hey, @murlakatamenka where are you? I mean it's been around a year right?
Jokes apart, @vaxerski I successfully migrated a cursor to hyprcursor after a very long time of digging through the source and reading the logs.

The docs are not good. Is it ok if I create MR with some improvements that I think should be added with the help of my new view to the project and my recent experience?

[vaxerski]

it is absolutely ok