Wiki and Documentation requests #5
Replies: 66 comments
-
|
Wiki should be editable now, let me know if it still does not work. It's open for everyone for the time being, but may have to restrict to collaborators only in the future - we'll see. Feel free to mess around for now :) |
Beta Was this translation helpful? Give feedback.
-
|
Will do. So far I've written (but not yet published):
If there's anything else anyone reading this wishes for, now is the time. |
Beta Was this translation helpful? Give feedback.
-
|
The wiki looks great so far. Thanks again for all the time you put into this - it is much appreciated. |
Beta Was this translation helpful? Give feedback.
-
|
Thanks! I'm far from done yet, still being held back by that stupid keyboard repair aftermath (round two: the display they broke while repairing the keyboard) and the work that piled up in the meantime. I've written up some stuff for every command with an example and a small section on rules, but I'm still unsure how to sort them. Will probably need to do a custom sidebar of some sort, because the default one is alphabetically sorted. I also have a rework for the readme linking to the relevant articles and an issue template waiting to be written. I have also extended the update check on launch to include functionality for auto updating Do you think these things belong in the wiki as well, or should I remove them completely, or keep them in a separate section from "installing from HEAD"? (Edit: Got autoupdate working without having to click a notification) # The code below checks for updates asynchronously
# Do not change unless you're a shell script magician
# This requires your codesigning certificate to be named 'yabai-cert' exactly
function check_for_updates() {
set -o pipefail
installed="$(brew info koekeishiya/formulae/yabai | grep 'HEAD-' | awk '{print substr($1,length($1)-6)}')"
remote="$(git ls-remote 'https://github.com/koekeishiya/yabai.git' HEAD | awk '{print substr($1,1,7)}')"
[ ${?} -eq 0 ] && [[ "${installed}" != "${remote}" ]]
}
function install_updates() {
updatefile=$(mktemp)
cat > ${updatefile} <<- EOF
#! /usr/bin/env sh
clear
printf "\e[1mUpdating yabai. Authenticate to continue, Ctrl+C to cancel.\e[0m\n\n"
if sudo -v; then
brew services stop koekeishiya/formulae/yabai
brew reinstall koekeishiya/formulae/yabai
codesign -fs 'yabai-cert' "$(brew --prefix yabai)/bin/yabai"
sudo yabai --uninstall-sa
sudo yabai --install-sa
brew services start koekeishiya/formulae/yabai
killall Dock
fi
ps -eo pid,comm | grep -v grep | grep -i Terminal.app | tail -1 | awk '{print $1}' | xargs kill
EOF
chmod +x ${updatefile}
open -FWnb com.apple.Terminal ${updatefile}
rm -f ${updatefile}
}
(check_for_updates && install_updates) & |
Beta Was this translation helpful? Give feedback.
-
No worries. take all the time you need :)
That sounds great!
I think this is a cool idea and I'd be fine with having it in the "installing from HEAD" section. Feel free to put it where you think it makes the most sense. It would be sort of nice to have a similar system for the bundled version as well, but I believe that requires the actual formulae to be updated through |
Beta Was this translation helpful? Give feedback.
-
Yes, this is possible. I should be able to do some sort of selective Edit: the selective updating is not a thing, so I'd have to manually fetch the tag. Should still be possible, but will require more awk. Edit 2: Tested this with chunkwm because it has more than one tag, but this should work. The key was learning about -V for sort, which is version sorting. # get latest tag
git ls-remote --tags https://github.com/koekeishiya/chunkwm.git | sort -t '/' -k 3 -V | tail -1 | awk '{print substr($2,12)}'
# get version installed via brew
brew info --json koekeishiya/formulae/chunkwm | jq -r '.[0].versions.stable' |
Beta Was this translation helpful? Give feedback.
-
|
One thing I would love to see in the wiki is how yabai compares to chunkwm (I'm in no position to answer this). One question I'm looking to have answered is whether or not one should migrate off chunkwm at this time. |
Beta Was this translation helpful? Give feedback.
-
|
Noted. I agree this would be a useful chapter, that could even just be named "Comparison with other window managers" and include Amethyst and Hammerspoon as well. In general: yes, unless you're a) heavily invested into the chunkwm plugin architecture or b) cannot disable SIP whatsoever. |
Beta Was this translation helpful? Give feedback.
-
|
Would it make sense to add a clickable badge for the changelog in the wiki, next to the version or license badge? |
Beta Was this translation helpful? Give feedback.
-
|
Yes, I've actually thought of this as well. There's a big update coming tonight, I've finally finished the command section and there's a slight reorganisation for installation coming as well. I will then also add a link to the changelog to the wiki. ETA is within a day. |
Beta Was this translation helpful? Give feedback.
-
|
Sounds great. Thanks again for doing this! |
Beta Was this translation helpful? Give feedback.
-
|
Might as well ask before working on it: Would you accept a change to the README (linking to relevant sections of the wiki) and issue templates (categories: Ask a question, Propose a feature, Report a bug)? GitHub Flavored Markdown supports HTML comment blocks so you can put a lot of information in there that won't be visible in the issue post itself, but will be very visible to the person posting the issue. Also, do you have any plans for a logo for yabai? Both a wide banner (logo+text, for readme/wiki) and a square logo (for system notifications, Alfred etc.) would be nice-to-have. Maybe it'd be a good idea to create an issue asking the community for a logo, but requiring that any logos be made available under CC0 or something like that? |
Beta Was this translation helpful? Give feedback.
-
This would likely be better than the current version. Just make sure that important information that is currently in the README is not lost, I suppose.
I don't have any objections to this.
I haven't actually given this a thought. I agree that a banner would be nice for the readme/wiki, but I don't immediately see what would make sense for this software. |
Beta Was this translation helpful? Give feedback.
-
Which is why I think you should create an issue and just sticky it, asking for ideas and logos/banners, requiring that images are appropriately licensed. Maybe someone will come along and create something nice. There's no urgency in this, but it's a nice-to-have thing for making the repo look good. |
Beta Was this translation helpful? Give feedback.
-
Done. Thanks for the suggestion. |
Beta Was this translation helpful? Give feedback.
-
|
After the removal of borders and the status bar I needed some other way to (1) display the current space and layout, and (2) provide some visual cue when changing modes in skhd. Below is a combination of BitBar, yabai, and skhd that achieves this without having to run some script every 2 seconds. The key idea is to use yabais ability to register actions for events, and BitBars ability to nicely update individual plugins. Here is what the BitBar plugin looks like displaying the Layout | Current Space - Total Spaces in the status bar:
Here is the BitBar plugin script: !/bin/bash
# <bitbar.dependencies>bash</bitbar.dependencies>
yabai=/usr/local/bin/yabai
jq=/usr/local/bin/jq
# ---------------------------------------------------------
# font color default values
font_color=('')
# ---------------------------------------------------------
# color settings based skhd mode
is_window_mode_active=/tmp/skhd_$USER.mode.window.active
if [ -f $is_window_mode_active ] ; then
# -- window mode
font_color=( 'color=#227576' )
else
# -- default mode
fi
# ---------------------------------------------------------
# retrieve all info about spaces
spaces=$($yabai -m query --spaces)
# space symbols
space_sym=(0 1 2 3 4 5 6 7 8 9)
# determine active space
space_cur=$(echo ${spaces} | $jq '.[] | select(.visible == 1)')
# extract active space number
space_idx=$(echo ${space_cur} | $jq '.index')
# extract active space layout (remove double quotes -> extract first char -> convert lower to upper
space_lay=$(echo ${space_cur} | $jq '.type' | tr -d '\"' | cut -c 1 | tr '[:lower:]' '[:upper:]')
# determine total # of spaces
space_all=$(echo ${spaces} | $jq '. | max_by(.index) | .index')
# ---------------------------------------------------------
# produce output for bitbar
echo "${space_lay}⎜${space_sym[$space_idx]}-${space_all} | ${font_color}"To avoid running this periodically BitBar has the capability to refresh plugins upon request. Adding the following to ...
# signals
# -- update active space in menu bar
yabai -m signal --add event=space_changed \
action="open -g 'bitbar://refreshPlugin?name=space.sh'"
....If you use skhd with window modes you can change the colour of that text by doing something like this in # -- Yabai Keyboard Shortcuts
# Example dot.skhdrc can be found at:
# @ /usr/local/opt/yabai/share/yabai/examples/skhdrc
# -------------------------------------------------------------------
# Window Modes - [default|window]
# add an on_enter command to the default mode
:: default : yabai -m config active_window_opacity 1.0 ;\
yabai -m config normal_window_opacity 0.6 ;\
rm -f /tmp/skhd_$USER.mode.window.active ; \
open -g 'bitbar://refreshPlugin?name=space.sh'
:: window @ : yabai -m config active_window_opacity 0.4 ;\
yabai -m config normal_window_opacity 0.2 ;\
touch /tmp/skhd_$USER.mode.window.active ; \
open -g 'bitbar://refreshPlugin?name=space.sh'
# from 'default' mode, activate mode 'window' (`0x39` -> CAPS LOCK)
cmd - x ; window
# from 'window' mode, activate mode 'default'
window < cmd - x ; default
window < escape ; default
window < i ; defaultThat presence of the of a file will tell the BitBar plugin what mode is active (crude but works well 😄 ) Finally, we also want to refresh the plugin when we change the layout via skhd between bsp and float so we can see what is active right away. Add something like this to your window < b : yabai -m space --layout bsp ; open -g 'bitbar://refreshPlugin?name=space.sh'
window < f : yabai -m space --layout float ; open -g 'bitbar://refreshPlugin?name=space.sh'HTH |
Beta Was this translation helpful? Give feedback.
-
|
@1g0rb0hm In case you haven't seen. I did a full port of the yabai border system into https://github.com/koekeishiya/limelight |
Beta Was this translation helpful? Give feedback.
-
@koekeishiya: Thanks for pointing this out. Will definitely try this as borders and the capability to give them different colours as well as widths is a great way to provide visual cues for different modes. Thanks for putting in the work and porting it 👍 |
Beta Was this translation helpful? Give feedback.
-
|
The documentation is great, but unnecessarily discouraging for new users. The 'Integrity Protection' issue is too pronounced and listed as a Caveat in the main README.md. It's much better addressed as 'Recommendation' in the Wiki. |
Beta Was this translation helpful? Give feedback.
-
This is something I did very deliberately because I don't officially support running yabai with SIP enabled. It seems to work fine for some people depending on their needs, but if I at some point come up with a way to e.g make something more efficient, I will not hesitate to make that change even if it is breaking something that used to work with SIP enabled. As far as I know, there is no place that states multiple display/spaces won't work with SIP enabled; If so, can you link that page to me and I'll review it. I guess my last note is simply that I don't actually try to or care for marketing this tool at all. I am glad that I can help other people make their system more usable, but my mindset is simply that people who believe this will be beneficial to them will give it a try, and people who don't, won't. |
Beta Was this translation helpful? Give feedback.
-
|
Maybe I found a typo in the wiki page : At the mouse support section the |
Beta Was this translation helpful? Give feedback.
-
|
Installation instructions are practically inaccessible ATM. The quickstart section in the wiki is referencing itself. The sidebar goes back to this very section and without googling, the actual installation instructions can not be found. Problem:
|
Beta Was this translation helpful? Give feedback.
-
|
The link(s) in the sidebar is there:
|
Beta Was this translation helpful? Give feedback.
-
|
Sorry, I think I was sleep deprived 😂. Thank you for you work! I have been using your wms since before chunkwm. 🤘 |
Beta Was this translation helpful? Give feedback.
-
Should users re-enable SIP after installation on 10.14+ as well? |
Beta Was this translation helpful? Give feedback.
-
|
On 10.14+ SIP must stay disabled. In High Sierra, scripting additions stored in the /System directory tree could be loaded with SIP enabled, which is why that works, but they changed that in 10.14+. |
Beta Was this translation helpful? Give feedback.
-
|
But to clarify, on 10.14+ SIP only needs fs and debug disabled? I.e. running |
Beta Was this translation helpful? Give feedback.
-
|
Yeah, that is correct.
… On 15 Jun 2020, at 23:40, BlueDrink9 ***@***.***> wrote:
But to clarify, on 10.14+ SIP only needs fs and debug disabled? I.e. running csrutil enable --without fs --without debug is all that is needed?
—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub <https://github.com/koekeishiya/yabai/issues/5#issuecomment-644404813>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ABPDZV5RYCWEMYBZINI6GPDRW2IMLANCNFSM4HOOUJIA>.
|
Beta Was this translation helpful? Give feedback.
-
|
How should we contribute to the wiki? I found numerous little tips scattered about the web and in issues, but can't seem to find a way to edit the wiki. Specifically, I thought these snippets would be helpful for the Window Modifications section: diff --git a/Configuration.md b/Configuration.md
index 002c13c..a4c7c35 100644
--- a/Configuration.md
+++ b/Configuration.md
@@ -137,6 +137,13 @@ yabai -m config window_shadow float
yabai -m config window_opacity on
yabai -m config active_window_opacity 1.0
yabai -m config normal_window_opacity 0.9
+
+# window opacity transition duration (default: 0.2 seconds)
+# example: change opacity transition duration to 0.1 seconds
+yabai -m config window_opacity_duration 0.0
+
+# example: override opacity for an application
+yabai -m rule --add app="Chrome" opacity=1.0
\```
### Status bar |
Beta Was this translation helpful? Give feedback.
-
|
I've migrated this to discussions and locked this one individually. Further wiki/docs requests can just be posted as new discussions. |
Beta Was this translation helpful? Give feedback.
-
I've migrated this to discussions and locked this one individually. Further wiki/docs requests can just be posted as new discussions.
This thread is to discuss everything that should be in the wiki: Docs for the community, by the community. Feel free to request stuff or just ask any question that you think should be answered in the wiki.
Anything goes in this thread.
I'll personally do my best to update the wiki to be in line with current master, but it may take a few days for me to update it to recent changes.
Original post:
I've written up some initial documentation for commands, and I've been thinking that the Wiki is a good place for it. Having some reference that's easier to edit and link to than the manpage is a nice-to-have in my opinion. Additionally, I've been thinking about using it to create some sort of FAQ for common user errors and setup questions.
Beta Was this translation helpful? Give feedback.
All reactions