fix: miscellaneous fixes after separation of directories

README.md

@@ -176,18 +176,22 @@ A. [ Disclaimer: Here, how to make the completion code visible to
    Install it in one of the directories pointed to by bash-completion's
    `pkgconfig` file variables. There are two alternatives:
 
-   - The recommended directory is `completionsdir`, which you can get with
+   - The recommended directory is `<completionsdir>`, which you can get with
      `pkg-config --variable=completionsdir bash-completion`. From this
      directory, completions are automatically loaded on demand based on invoked
      commands' names, so be sure to name your completion file accordingly, and
      to include (for example) symbolic links in case the file provides
-     completions for more than one command. The completion filename for
-     command `foo` in this directory should be either `foo`, or `foo.bash`.
-     (Underscore prefixed `_foo` works too, but is reserved for
-     bash-completion internal use as a deprecation/fallback marker.)
-   - The other directory which is only present for backwards compatibility,
-     its usage is no longer recommended, is `compatdir` (get it with
-     `pkg-config --variable=compatdir bash-completion`). From this
+     completions for more than one command. The completion filename for command
+     `foo` in this directory should be `foo.bash`.  Unsuffixed `foo` also
+     works, but it is deprecated in >= 2.18.
+   - Helper scripts used by completions may be placed in the directory
+     `<helpersdir>`, which can be retrieved with `pkg-config
+     --variable=helpersdir bash-completion`.  The completion files in
+     `<completionsdir>` can reference the helper script `<helpersdir>/<helper>`
+     as `${BASH_SOURCE[0]%/*}/../helpers/<helper>`.
+   - The other directory, which is only present for backwards compatibility and
+     is not recommended to use, is `<compatdir>` (get it with
+     `pkg-config --variable=compatdir bash-completion`).  From this
      directory, files are loaded eagerly when `bash_completion` is loaded.
 
    For packages using GNU autotools the installation can be handled

bash_completion

@@ -3506,14 +3506,12 @@ _comp_load()
     shift
     local -a source_args=("$@")
 
-    local i prefix
-    for prefix in "" _; do # Regular from all dirs first, then fallbacks
-        for i in "${!dirs[@]}"; do
-            dir=${dirs[i]}/completions
-            [[ -d $dir ]] || continue
-            for compfile in "$prefix$cmdname" "$prefix$cmdname.bash"; do
-                _comp_load__visit_file "$dir/$compfile" && return 0
-            done
+    local i
+    for i in "${!dirs[@]}"; do
+        dir=${dirs[i]}/completions
+        [[ -d $dir ]] || continue
+        for compfile in "$cmdname.bash" "$cmdname"; do
+            _comp_load__visit_file "$dir/$compfile" && return 0
         done
     done
     _comp_load__visit_file "$_comp__base_directory/completions-core/$cmdname.bash" && return 0

completions-core/Makefile.am

@@ -169,7 +169,6 @@ cross_platform = 2to3.bash \
 		inject.bash \
 		inotifywait.bash \
 		installpkg.bash \
-		interdiff.bash \
 		invoke-rc.d.bash \
 		ip.bash \
 		ipcalc.bash \

completions-fallback/Makefile.am

@@ -17,6 +17,7 @@ cross_platform = adb.bash \
 		hexdump.bash \
 		hwclock.bash \
 		insmod.bash \
+		interdiff.bash \
 		ionice.bash \
 		jj.bash \
 		jungle.bash \

completions-core/interdiff.bash → completions-fallback/interdiff.bash

@@ -1,5 +1,8 @@
 # interdiff(1) completion                                  -*- shell-script -*-
 
+# Use of this file is deprecated.  Upstream completion is available in
+# patchutil >= 0.4.3, use that instead.
+
 _comp_cmd_interdiff()
 {
     local cur prev words cword was_split comp_args

completions/Makefile.am

@@ -1,7 +1,11 @@
 # We include all the files in the tarball
 
+scriptfiles =
+
 bashcompdir = $(datadir)/$(PACKAGE)/completions
-bashcomp_DATA =
+bashcomp_DATA = README.md $(scriptfiles)
+
+EXTRA_DIST = $(bashcomp_DATA)
 
 symlinks: $(DATA)
 .PHONY: symlinks
@@ -16,14 +20,8 @@ install-data-hook: symlinks
 
 check-local:
 	REPLY=0; \
-	for file in $(bashcomp_DATA); do \
+	for file in $(scriptfiles); do \
 		$${bashcomp_bash:-$${BASH:-bash}} \
 			-O extglob -n $(srcdir)/$$file || REPLY=$$?; \
 	done; \
 	exit $$REPLY
-
-install-data-local:
-	$(MKDIR_P) $(DESTDIR)$(datadir)/bash-completion/$(subdir)
-
-uninstall-local:
-	-rmdir $(DESTDIR)$(datadir)/bash-completion/$(subdir)

completions/README.md

@@ -0,0 +1,24 @@
+# Third-party completions directory - bash-completion
+
+This directory `completions` is the place to put **third-party completion
+files** that are loaded by
+[bash-completion](https://github.com/scop/bash-completion) on demand.
+
+> [!NOTE]
+>
+> The core `bash-completion` framework (<= 2.17) has provided also *completion
+> files bundled with the bash-completion framework itself* in this directory,
+> but we separated those files into `completions-core` and
+> `completions-fallback`.  However, external completion provider should
+> continue to install their completion files in `completions`.  The new
+> directories `completions-core` and `completions-fallback` are internal
+> directories intended to be used by the core `bash-completion`.
+
+The programmable completion for the command `<cmd>` is supposed to be provided
+as the file `completions/<cmd>.bash`.  The implementation examples are found in
+`completions-core`, which uses the latest bash-completion API (v3).  If you
+want to make the completion file to work also with an older version of
+`bash-completion`, you need to use the previous API of v2, which is contiuned
+to be supported.  For examples with API v2, please reference the completion
+files in `completions` of
+[bash-completion-2.11](https://github.com/scop/bash-completion/releases/tag/2.11).

helpers/Makefile.am

@@ -1,10 +1,4 @@
 helpersdir = $(datadir)/$(PACKAGE)/helpers
-helpers_DATA =
+helpers_DATA = README.md
 
 EXTRA_DIST = $(helpers_DATA)
-
-install-data-local:
-	$(MKDIR_P) $(DESTDIR)$(datadir)/bash-completion/$(subdir)
-
-uninstall-local:
-	-rmdir $(DESTDIR)$(datadir)/bash-completion/$(subdir)

helpers/README.md

@@ -0,0 +1,17 @@
+# Third-party helpers directory - bash-completion
+
+This directory `helpers` is the place to put **third-party helper scripts**
+that are used by third-party completion files in the `completions` directory,
+written for [bash-completion](https://github.com/scop/bash-completion).
+
+> [!NOTE]
+>
+> The core `bash-completion` framework (<= 2.17) has provided also *helper
+> scripts included in the bash-completion framework itself* in this directory,
+> but we separated those files into `helpers-core`.  However, external
+> completion provider should continue to install their helper scripts in
+> `helpers`.  The new directory `helpers-core` is an internal directory
+> intended to be used by the core `bash-completion`.
+
+The helper script may be referenced by a completion script in `completions`
+with `${BASH_COMPLETION[0]%/*}/../helpers/<helper>`.