doc improvements

CONTRIBUTING.md

@@ -99,13 +99,16 @@ Also, please bear the following coding guidelines in mind:
 
   can be replaced by:
 
-  ```shell
+  ```bash
   bar=${foo//bar/baz}
   ```
 
   These forms of parameter substitutions can also be used on arrays,
   which makes them very powerful (if a little slow).
 
+  See ["Pure Bash"](https://github.com/dylanaraps/pure-bash-bible)
+  for more examples.
+
 - We want our completions to work in `posix` and `nounset` modes.
 
   Unfortunately due to a bash < 5.1 bug, toggling POSIX mode
@@ -132,7 +135,7 @@ Also, please bear the following coding guidelines in mind:
   expansions will be unexpectedly performed, which becomes a vulnerability.  In
   the latter case, checks by shellcheck and shfmt will not be performed inside
   `'...'`.  Also, `_comp_compgen_split` is `IFS`-safe.
-  
+
   Avoid using `_comp_compgen -- -G "pattern"` to generate completions.  The
   result is not filtered by the current word `cur` due to the Bash design of
   `compgen`.  Also, this cannot be used to generate filenames with a specified

README.md

@@ -21,11 +21,19 @@ need to source it from either `/etc/bashrc` or `~/.bashrc` (or any
 other file sourcing those). If you have _only_ bash >= 4.2 installed, you can
 do this by simply using:
 
-```shell
+```bash
 # Use bash-completion, if available
 [[ $PS1 && -f /usr/share/bash-completion/bash_completion ]] && \
     . /usr/share/bash-completion/bash_completion
 ```
+or if your `bashrc` will be shared across distros (and major upgrades):
+```bash
+# Use bash-completion, if available, and avoid double-sourcing
+[[ $PS1 && \
+  -z ${BASH_COMPLETION_VERSINFO:-} && \
+  -f /usr/share/bash-completion/bash_completion ]] && \
+    . /usr/share/bash-completion/bash_completion
+```
 
 If you have older bash versions in use, their loading of `bash_completion`
 should be prevented. See further for more info.
@@ -70,7 +78,7 @@ standard way is to configure `~/.bash_profile` to source `~/.bashrc` and write
 interactive settings in `~/.bashrc`.  You can source `~/.bashrc` in
 `~/.bash_profile` in the following way:
 
-```shell
+```bash
 # ~/.bash_profile
 
 if [[ -f ~/.bashrc ]]; then
@@ -90,7 +98,7 @@ the entry point of `bash-completion` to
 `$HOMEBREW_PREFIX/etc/profile.d/bash_completion.sh`.  We can source it by
 adding the following to our startup file `~/.bashrc`:
 
-```shell
+```bash
 if [[ -s $HOMEBREW_PREFIX/etc/profile.d/bash_completion.sh ]]; then
   . "$HOMEBREW_PREFIX/etc/profile.d/bash_completion.sh"
 fi