Better Documentation

[Misterio77]

I think flavours is pretty easy to use, but that's probably biased as i wrote it.
Would love to hear docs suggestions, and am accepting help documenting as well.

Let me know how you use flavours and what features aren't very clear.

[gingkapls]

I love this project. Speed had been the major issue for me with other similar applications.
I think a more detailed explanation on the whole template stuff would be pretty helpful.

For example, this is how pywal explains their templates.
It's pretty straightforward with how you just have to put {color#.rgb/hex} and pywal will insert that respective color.

For starters, you can create a sample template, where is the default directory for templates i.e. $HOME/.local/share/flavours/base16/templates

Actually, when you know where to look, it isn't much different from pywal templates. Just a sample template and the default template directory would be more than enough.

Many people who stumble upon your project may already be familiar with creating base16 templates, this'll help those like me who aren't familiar with it get started.

[Misterio77]

Thanks for the feedback!

I think the general ideia would be to take a look at the official base16 templates (that can be downloaded with flavours update templates) and their docs on how to make a template.

I will try to write a bit about this and link to the correct references.

[snide]

Hey @Misterio77 I'm a designer by trade and generally find I'm good at spoting flaws in documentation, because I'm not as good of an engineer as most of you fine folks.

I've been documenting how to use flavours in a series of videos. This last one is a pretty good summary of what Flavours can do. The previous video in the series was a better practical tutorial on making your own templates.

If you need help documenting things, I'm happy to take a stab at cleaning up your readme or wiki with some diagrams and examples. It's the least I can do to help you for making this FANTASTIC tool. It took me a week or two to really learn it, but it's been able to handle pretty much everything I wanted as far as theming Linux systems. Anyways, just wanted to say thanks!

https://www.youtube.com/watch?v=y-GERsrhTkA

[Misterio77]

I've just finished watching your 3 episodes, @snide, and i absolutely loved them. They're really clear and informative. Definitively a must watch, specially for people building schemes (i'll for sure use these tips in future schemes i build).

Thank you so much for taking the time to give flavours a try and making these great resources.

I'd absolutely love to have your help with the README and docs. I've been trying to tackle this problem for a few weeks now, but i found it pretty hard to write conscise and detailed documentation in English (not my native language), and specially from a user's perspective.

I'll add you as contributer to the repo, please feel free to edit anything as you see fit. And let me know if there's anything i can help with, or even any suggestions to the program itself.

Thanks again!

[snide]

Excellent. I'll find some time to so some cleanup. I'll set them up as PRs for review. Again, thanks for making such an awesome little tool.

[RichardBronosky]

I know how hard it is to document your own project to be consumable for others. I think "better" isn't a good request. We should consider this ticket an Epic and drop specific Stories under it. I'll start with:

Shell Completion #31

It's clear that you put a lot of work into shell completion for 5 shells!!. To move that past the goal post, I see at least 2 things missing.

• Any mention of --completions in the --help
• examples of how to use each of these in their respective *rc file

❯ flavours -V
flavours 0.4.0


❯ flavours --help
flavours 0.4.0
Gabriel Fontes (Misterio77) <[email protected]>
A simple way to manage and use base16 standard schemes and templates

USAGE:
    flavours [OPTIONS] [SUBCOMMAND]

OPTIONS:
    -c, --config <FILE>            Specify a configuration file (Defaults to ~/.config/flavours/config.toml on Linux)
    -d, --directory <DIRECTORY>    Specify a data directory (Defaults to ~/.local/share/flavours on Linux)
    -h, --help                     Prints help information
    -v, --verbose                  Be more verbose
    -V, --version                  Prints version information

SUBCOMMANDS:
    apply       Applies scheme, according to user configuration
    current     Prints last applied scheme name
    generate    Generates a scheme based on an image
    info        Shows scheme colors for all schemes matching pattern. Optionally uses truecolor
    list        Prints a list with all matching schemes
    update      Downloads schemes, templates, or updates their lists (from repos specified in sources.yml)

[RichardBronosky]

I've been trying to tackle this problem for a few weeks now, but i found it pretty hard to write concise and detailed documentation in English (not my native language), and specially from a user's perspective.

Holy CARP, Brother! I'd be glad to help out any way I can. I use both macOS and Arch (BTW). I will add some input on how to make a consistent setup to share between those 2.

[Misterio77]

I think i'll add a heads up on the readme on how to manually install completions. These are mostly intended to be installed through a package manager (AUR does), though.

[Pound-Hash]

Thanks for your work as well as for asking for better documentation!

Questions

1. What is meant by the light parameter? How could a hook be light?
   1.1 Is the qutebrowser hook hook='bash -c "pgrep -x qutebrowser && qutebrowser :config-source"' light?
   1.2 The sentence, "flavours apply --light will skip running hooks marked with light=false" is confusing to me. This seems to mean, if we disable light by declaring false, then explicitly call the argument --light, then light will not be applied. I'm not sure how to understand that. If light is not applied, then perhaps it would be clearer to use a --dark argument?
2. How do we know if "a specific app supports including colors from another file, or if the template provides the entire file" thus allowing us to "forgo the comments altogether and use the rewrite=true on flavours config"? For example, sway allows for configs to be placed in /etc/sway/config.d/. If we set rewrite=true, will flavours write its configuration here?

---

Suggestions

1. How about a wiki page for cataloging template configurations? For example, qutebrowser can use the hook hook='bash -c "pgrep -x qutebrowser && qutebrowser :config-source"' to facilitate application of the schemes, but I had to find this information on qutebrowser's issues page. Instead, users can simply find such relevant information on the wiki here.
2. I'm an English teacher as well as an avid reader and scholar. I can help you with the README if you like. I see some area for improvement in terms of English mechanics (grammar, punctuation, style, diction).

[Misterio77]

Hello!

Questions

1. light currently means "a hook that is (acceptably) lightweight to execute". You might have hooks that do more heavy (as in "take long to execute" or "block your desktop while running") tasks, such as recompilling a GTK scheme, or reloading your WM. The idea is you can explicitly mark these as light=false, and they will not be executed when you're applying with the --light flag. The usecase is pretty much for realtime preview (you can, for example, build a rofi or fzf menu that runs flavours apply --light when you scroll through the schemes, allowing you to preview them before fully applying). I have an idea for abstracting over this a bit, which might be some sort of "hook groups" which could be selectively applied.
2. Yes, pretty much. If the program has some sort of include functionality, that means you can have a file "just for the colors", which can be entirely rewritten. For an example, on your ~/.config/sway/config you might have a include ~/.config/sway/colors line. Then, instead of applying the sway base16 template on your main config (using the delimiter comments), you just apply to the colors file (replacing everything there).

Suggestions

1. I've actually thought about it in the past, I think it could be a great addition :). I'll see if i can set one up.
2. I'd absolutely love your help. While I try my best, English is not my first language and thus I'm sure the README could use some improvements. Please feel free to open up PRs for anything you'd like to change.

Thanks a lot for the (very relevant) questions and useful suggestions. Let me know if there's anything i can do to help out!

[mipimipi]

Maybe starting a wiki would make sense. Willing to contribute to that.