docker: document option-stacking setting

Fixes #9266

README.md

@@ -139,10 +139,10 @@ ZSH_THEME_RANDOM_CANDIDATES=(
 )
 ```
 
-If you only know which themes you don't like, you can add them similarly to a blacklist:
+If you only know which themes you don't like, you can add them similarly to an ignored list:
 
 ```shell
-ZSH_THEME_RANDOM_BLACKLIST=(pygmalion tjkirch_mod)
+ZSH_THEME_RANDOM_IGNORED=(pygmalion tjkirch_mod)
 ```
 
 ### FAQ

plugins/docker/README.md

@@ -10,3 +10,25 @@ plugins=(... docker)
 
 A copy of the completion script from the docker/cli git repo:
 https://github.com/docker/cli/blob/master/contrib/completion/zsh/_docker
+
+## Settings
+
+By default, the completion doesn't allow option-stacking, meaning if you try to
+complete `docker run -it <TAB>` it won't work, because you're _stacking_ the
+`-i` and `-t` options.
+
+[You can enable it](https://github.com/docker/cli/commit/b10fb43048) by **adding
+the lines below to your zshrc file**, but be aware of the side effects:
+
+> This enables Zsh to understand commands like `docker run -it
+> ubuntu`. However, by enabling this, this also makes Zsh complete
+> `docker run -u<tab>` with `docker run -uapprox` which is not valid. The
+> users have to put the space or the equal sign themselves before trying
+> to complete.
+>
+> Therefore, this behavior is disabled by default. To enable it:
+>
+> ```
+> zstyle ':completion:*:*:docker:*' option-stacking yes
+> zstyle ':completion:*:*:docker-*:*' option-stacking yes
+> ```

themes/random.zsh-theme

@@ -1,3 +1,10 @@
+# Deprecate ZSH_THEME_RANDOM_BLACKLIST
+if [[ -n "$ZSH_THEME_RANDOM_BLACKLIST" ]]; then
+  echo '[oh-my-zsh] ZSH_THEME_RANDOM_BLACKLIST is deprecated. Use `ZSH_THEME_RANDOM_IGNORED` instead.'
+  ZSH_THEME_RANDOM_IGNORED=($ZSH_THEME_RANDOM_BLACKLIST)
+  unset ZSH_THEME_RANDOM_BLACKLIST
+fi
+
 # Make themes a unique array
 typeset -Ua themes
 
@@ -11,8 +18,8 @@ else
     "$ZSH_CUSTOM"/themes/*.zsh-theme(N:t:r)
     "$ZSH"/themes/*.zsh-theme(N:t:r)
   )
-  # Remove blacklisted themes from the list
-  for theme in random ${ZSH_THEME_RANDOM_BLACKLIST[@]}; do
+  # Remove ignored themes from the list
+  for theme in random ${ZSH_THEME_RANDOM_IGNORED[@]}; do
     themes=("${(@)themes:#$theme}")
   done
 fi