[gnuastro-commits] master ef351da 56/62: TAB completion: now working for Arithmetic, better infrastructure

[Mohammad Akhlaghi]

branch: master
commit ef351da3921a276bc7b1a9a10667b8c995c6dc24
Author: Mohammad Akhlaghi <mohammad@akhlaghi.org>
Commit: Mohammad Akhlaghi <mohammad@akhlaghi.org>

    TAB completion: now working for Arithmetic, better infrastructure
    
    Until now, the Bash TAB completion was primarily designed around the table
    program and still needed some polishing to be generalized. There was also
    no documentation for the TAB completion in the book.
    
    With this commit, during the inclusion of the TAB completion for
    Arithmetic, things were generalized and are now also used in the Arithmetic
    program. Also, since the Arithmetic program takes operators as command-line
    arguments, it was necessary to also print the operators on the
    command-line. Finally, the book was also updated with a full section
    devoted to this.
    
    I also noticed that the '--help' output of the '--envseed' option in
    Arithmetic was based on the Table program! This has also been corrected.
---
 Makefile.am                                        |  94 ++++++++++++++-
 bin/arithmetic/Makefile.am                         |   3 +-
 bin/arithmetic/args.h                              |   2 +-
 .../astarithmetic-complete.bash}                   | 129 ++++++++++-----------
 bin/{gnuastro-complete.bash => completion.bash.in} |  54 ++++++---
 bin/table/Makefile.am                              |   3 +-
 bin/table/asttable-complete.bash                   |   9 +-
 doc/gnuastro.texi                                  |  45 ++++++-
 8 files changed, 238 insertions(+), 101 deletions(-)

diff --git a/Makefile.am b/Makefile.am
index 45b97af..17555a4 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -40,6 +40,8 @@ BUILT_SOURCES = $(top_srcdir)/AUTHORS
 
 
 
+
+
 ## Directories to check:
 ## =====================
 ##
@@ -49,6 +51,7 @@ BUILT_SOURCES = $(top_srcdir)/AUTHORS
 ## Gnulib tests have been done.
 if COND_ARITHMETIC
   MAYBE_ARITHMETIC = bin/arithmetic
+  MAYBE_ARITHMETIC_COMPLETE = bin/arithmetic/astarithmetic-complete.bash
 endif
 if COND_BUILDPROG
   MAYBE_BUILDPROG = bin/buildprog
@@ -94,6 +97,7 @@ if COND_STATISTICS
 endif
 if COND_TABLE
   MAYBE_TABLE = bin/table
+  MAYBE_TABLE_COMPLETE = bin/table/asttable-complete.bash
 endif
 #if COND_TEMPLATE
 #  MAYBE_TEMPLATE = bin/TEMPLATE
@@ -107,6 +111,8 @@ endif
 
 
 
+
+
 ## Subdirectories to build
 ## =======================
 ##
@@ -125,32 +131,102 @@ SUBDIRS = bootstrapped/lib $(MAYBE_GNULIBCHECK) lib 
$(MAYBE_ARITHMETIC) \
 
 
 
+
+
 ## Add m4/ to the list of directories to search for m4 files
 ## =========================================================
 ACLOCAL_AMFLAGS = -I bootstrapped/m4
 
 
 
+
+
 ## Files that are installed (and distributed)
 ## =========================================
 dist_doc_DATA = README
 
 
 
+
+
 # Installed system configuration files
 # ====================================
 dist_sysconf_DATA = bin/gnuastro.conf
 
 
 
+
+
 ## Files that are only distributed
 ## ===============================
 ##
 ## Note that 'COPYING' (containing the GNU GPL) is included in the
 ## distribution tarball by default in Automake, but not other license
 ## files, so we have to manually add 'COPYING.FDL'.
+##
+## The completion files for each program ('*-complete.bash') are added to
+## EXTRA_DIST within each program's directory.
 EXTRA_DIST = COPYING.FDL genauthors .dir-locals.el .version \
-             developer-build bootstrapped/README .autom4te.cfg
+             developer-build bootstrapped/README .autom4te.cfg \
+             bin/completion.bash.in
+
+
+
+
+
+## Bash auto-completion
+## ====================
+##
+## Besides the default '.bash.in' files, for some programs (like
+## Arithmetic), its necessary to parse the source (for list of all
+## operators).
+pkgdata_DATA = bin/completion.bash
+bin/completion.bash: $(top_srcdir)/bin/completion.bash.in
+        # Delete any existing output file.
+       rm -f $@ $@-arith.tmp $@.tmp
+
+        # Extract the arithmetic library operators into a '-arith.tmp' file (
+       echo "" > $@-arith.tmp
+       for op in $$($(AWK) '/^gal_arithmetic_operator_string/{parse=1} \
+                            /^\}/{parse=0} \
+                            parse==1 && /GAL_ARITHMETIC_OP/{print $$NF}' \
+                            $(top_srcdir)/lib/arithmetic.c \
+                           | $(SED) -e's|"||g' -e's|;||'); do \
+           ops="$$ops $$op"; \
+       done; \
+       echo "_gnuastro_autocomplete_compreply_arithmetic_lib(){" >> 
$@-arith.tmp; \
+       echo "arithmetic_lib_operators=\"$$ops\"" >> $@-arith.tmp; \
+       echo "}" >> $@-arith.tmp
+
+        # Extract the arithmetic program operators.
+       echo "" >> $@-arith.tmp
+       for op in $$($(AWK) '/^arithmetic_set_operator/{parse=1} \
+                            /^\}/{parse=0} \
+                            parse==1 && /strcmp\(string/{print $$NF}' \
+                            $(top_srcdir)/bin/arithmetic/arithmetic.c \
+                           | $(SED) -e's|"||g' -e's|))||'); do \
+           ops="$$ops $$op"; \
+       done; \
+       echo "_gnuastro_autocomplete_compreply_arithmetic_prog(){" >> 
$@-arith.tmp; \
+       echo "arithmetic_prog_operators=\"$$ops\"" >> $@-arith.tmp; \
+       echo "}" >> $@-arith.tmp
+
+        # Copy the low-level common functions to all programs, then put the
+        # arithmetic functions inside of it. We are keeping the arithmetic
+        # operators separate to help in debugging when necessary (they can
+        # be 'source'd into each program's completion script).
+       cp $(top_srcdir)/bin/completion.bash.in $@.tmp
+       cat $@-arith.tmp >> $@.tmp
+
+        # Copy each program's source.
+       for f in $(MAYBE_ARITHMETIC_COMPLETE) \
+                $(MAYBE_TABLE_COMPLETE); do \
+         $(SED) -e 's|@PREFIX[@]|$(bindir)|g' $(top_srcdir)/$$f >> $@.tmp; \
+       done
+       chmod a-w $@.tmp
+       mv $@.tmp $@
+
+
 
 
 
@@ -183,7 +259,7 @@ all-local:
        fi
 
         # Print a message if requested.
-       @if [ "X$(MAKECMDGOALS)" = "Xall-am" ] && [ x$(GUIDEMESSAGE) = xyes ]; 
then    \
+       @if [ "X$(MAKECMDGOALS)" = "Xall-am" ] && [ x$(GUIDEMESSAGE) = xyes ]; 
then  \
         echo;                                                                  
     \
         echo 
"==================================================================="; \
         echo 
"==================================================================="; \
@@ -199,6 +275,10 @@ all-local:
         echo;                                                                  
     \
        fi
 
+
+
+
+
 ## We cannot do the writing persmission test at configure time. Here is a
 ## quote from the generated ./configure script: The prefix variables...
 ##
@@ -239,6 +319,10 @@ check-local:
         echo;                                                                  
     \
        fi
 
+
+
+
+
 ## Note that the '\' characters in the GNU head here are not printed on the
 ## command line. So we have to consider them. The ASCII GNU head is taken
 ## from: https://www.gnu.org/graphics/gnu-ascii.html
@@ -272,11 +356,15 @@ install-exec-local:
         echo "(for an intro, run 'info gnuastro \"Installation directory\"')"; 
     \
         echo;                                                                  
     \
         echo;                                                                  
     \
+        echo "Bash completion (auto-fill arguments and options with TAB):";    
     \
+        echo "  - 'source $(pkgdatadir)/completion.bash' in '~/.bashrc':"; \
+        echo;                                                                  
     \
+        echo;                                                                  
     \
         echo "To stay up to date with future releases, please subscribe to: "; 
     \
         echo "    https://lists.gnu.org/mailman/listinfo/info-gnuastro";;       
     \
         echo;                                                                  
     \
         echo;                                                                  
     \
-        echo "(The following lines can be ignored.)";                          
     \
+        echo "(Any lines following this message can be ignored.)";             
     \
         echo 
"==================================================================="; \
         echo 
"==================================================================="; \
         echo;                                                                  
     \
diff --git a/bin/arithmetic/Makefile.am b/bin/arithmetic/Makefile.am
index c73400c..23266a9 100644
--- a/bin/arithmetic/Makefile.am
+++ b/bin/arithmetic/Makefile.am
@@ -36,7 +36,8 @@ astarithmetic_LDADD = 
$(top_builddir)/bootstrapped/lib/libgnu.la \
 
 astarithmetic_SOURCES = main.c ui.c arithmetic.c operands.c
 
-EXTRA_DIST = main.h authors-cite.h args.h ui.h arithmetic.h operands.h
+EXTRA_DIST = main.h authors-cite.h args.h ui.h arithmetic.h operands.h \
+             astarithmetic-complete.bash
 
 
 
diff --git a/bin/arithmetic/args.h b/bin/arithmetic/args.h
index 355fe9f..42ab796 100644
--- a/bin/arithmetic/args.h
+++ b/bin/arithmetic/args.h
@@ -74,7 +74,7 @@ struct argp_option program_options[] =
       UI_KEY_ENVSEED,
       0,
       0,
-      "Use GSL_RNG_SEED env. for '--rowrandom'.",
+      "Use GSL_RNG_SEED env. for mknoise operator.",
       GAL_OPTIONS_GROUP_INPUT,
       &p->envseed,
       GAL_OPTIONS_NO_ARG_TYPE,
diff --git a/bin/table/asttable-complete.bash 
b/bin/arithmetic/astarithmetic-complete.bash
similarity index 56%
copy from bin/table/asttable-complete.bash
copy to bin/arithmetic/astarithmetic-complete.bash
index b9e38a4..1bac637 100644
--- a/bin/table/asttable-complete.bash
+++ b/bin/arithmetic/astarithmetic-complete.bash
@@ -1,10 +1,9 @@
-# Bash autocompletion to Gnuastro's Table program. See the comments above
-# 'bin/gnuastro-complete.bash' for more.
+# Bash autocompletion to Gnuastro's Arithmetic program. See the comments
+# above 'bin/completion.bash.in' for more.
 #
 # Original author:
-#     Pedram Ashofteh Ardakani <pedramardakani@pm.me>
-# Contributing author(s):
 #     Mohammad Akhlaghi <mohammad@akhlaghi.org>
+# Contributing author(s):
 # Copyright (C) 2021 Free Software Foundation, Inc.
 #
 # Gnuastro is free software: you can redistribute it and/or modify it under
@@ -26,10 +25,9 @@
 
 # For debugging
 #
-# For debugging uncomment this line to load the generic Gnuastro
-# auto-completion functions, and correct the location (use an absolute
-# location).
-#source /PATH/TO/gnuastro-complete.bash
+# See the description in 'bin/completion.bash.in'.
+#source /PATH/TO/GNUASTRO/SRC/bin/completion.bash.in
+#source /PATH/TO/GNUASTRO/BUILD/bin/completion.bash-arith.tmp
 
 
 
@@ -39,15 +37,42 @@
 ############         Only for Table (this program)         ############
 #######################################################################
 
-# Dealing with arguments: Table only takes one argument/file. So if a table
-# has been previously given on the command-line only print option names.
-_gnuastro_autocomplete_asttable_arguments(){
-    local given_file=""
-    if _gnuastro_autocomplete_first_in_arguments table; then
-        _gnuastro_autocomplete_compreply_options_all ""
-    else
-        _gnuastro_autocomplete_compreply_tables "$argument"
-    fi
+# Dealing with arguments: Arithmetic only takes array/image files.
+_gnuastro_autocomplete_astarithmetic_arguments(){
+
+    # Local variables to be filled by functions.
+    local arithmetic_lib_operators=""
+    local arithmetic_prog_operators=""
+
+    # Print all accessible images.
+    _gnuastro_autocomplete_compreply_fits_images "$argument"
+
+    # If atleast one image has already been given, an then print the
+    # arithmetic operators with the file names.
+#    if _gnuastro_autocomplete_first_in_arguments image; then
+#
+#        # Get the list of operators as variables.
+#        _gnuastro_autocomplete_compreply_arithmetic_lib
+#        _gnuastro_autocomplete_compreply_arithmetic_prog
+#
+#        # Limit the operators to those that start with the already given
+#        # portion.
+#        if [ x"$argument" = x ]; then
+#            for f in $arithmetic_lib_operators $arithmetic_prog_operators; do
+#                COMPREPLY+=("$f");
+#            done
+#        else
+#            # We aren't using 'grep' because it can confuse the '--XXX' with
+#            # its own options on some systems (and placing a '--' before the
+#            # search string may not be portable).
+#            for f in $(echo $arithmetic_lib_operators 
$arithmetic_prog_operators \
+#                           | awk '{for(i=1;i<=NF;++i) \
+#                                     if($i ~ /^'$argument'/) print $i}'); do
+#                COMPREPLY+=("$f");
+#            done
+#        fi
+#
+#    fi
 }
 
 
@@ -55,7 +80,7 @@ _gnuastro_autocomplete_asttable_arguments(){
 
 
 # Fill option value (depends on option).
-_gnuastro_autocomplete_asttable_option_value(){
+_gnuastro_autocomplete_astarithmetic_option_value(){
 
     # Internal variables.
     local fits_file=""
@@ -66,65 +91,31 @@ _gnuastro_autocomplete_asttable_option_value(){
     # with similar operations, keep the order within the '|'s.
     case "$option_name" in
 
-        # Options that need a column from the main argument.
-        -b|--noblank|-c|--column|--inpolygon|--outpolygon)
-            _gnuastro_autocomplete_given_file_and_hdu table "" --hdu
-            _gnuastro_autocomplete_compreply_table_columns \
-                "$given_file" "$given_hdu" "$current"
-            ;;
-
-        # Options that take the column name as first component of value.
-        -m|--colmetadata|-e|--equal|-n|--notequal)
-
-            # Get the main argument's name (and possible HDU).
-            _gnuastro_autocomplete_given_file_and_hdu table "" --hdu
-            _gnuastro_autocomplete_compreply_table_columns \
-                "$given_file" "$given_hdu" "$current"
-
-            # Since these options take a column name as first value and the
-            # user should continue with other details, we need to disable
-            # the extra space on the command-line after the successful
-            # match.
-            compopt -o nospace
-            ;;
-
-        -C|--catcolumns)
-            _gnuastro_autocomplete_given_file_and_hdu \
-                table --catcolumnfile --catcolumnhdu
-            _gnuastro_autocomplete_compreply_table_columns \
-                "$given_file" "$given_hdu" "$current"
-            ;;
-
-        -h|--hdu)
-            _gnuastro_autocomplete_given_file table ""
-            _gnuastro_autocomplete_compreply_hdus table "$given_file"
+        -h|--hdu|-g|--globalhdu|-w|--wcshdu)
+            _gnuastro_autocomplete_given_file image ""
+            _gnuastro_autocomplete_compreply_hdus image "$given_file"
             ;;
 
-        -L|--catcolumnfile)
-            _gnuastro_autocomplete_compreply_tables "$current"
+        -w|--wcsfile)
+            _gnuastro_autocomplete_compreply_fits_images "$current"
             ;;
 
-        --searchin)
-            _gnuastro_autocomplete_compreply_searchin
+        --interpmetric)
+            for v in radial manhattan; do COMPREPLY+=("$v"); done
             ;;
 
-        -u|--catcolumnhdu)
-            _gnuastro_autocomplete_given_file table --catcolumnfile
-            _gnuastro_autocomplete_compreply_hdus table "$given_file"
+        --tableformat)
+            _gnuastro_autocomplete_compreply_tableformat
             ;;
 
-        -w|--wcsfile)
-            _gnuastro_autocomplete_compreply_fits_images "$current"
+        --wcslinearmatrix)
+            for v in cd pc; do COMPREPLY+=("$v"); done
             ;;
 
-        -W|--wcshdu)
-            _gnuastro_autocomplete_given_file image --wcsfile
-            _gnuastro_autocomplete_compreply_hdus image "$given_file"
+        --numthreads)
+            _gnuastro_autocomplete_compreply_numthreads
             ;;
 
-        --tableformat)
-            _gnuastro_autocomplete_compreply_tableformat
-            ;;
     esac
 }
 
@@ -132,7 +123,7 @@ _gnuastro_autocomplete_asttable_option_value(){
 
 
 
-_gnuastro_autocomplete_asttable(){
+_gnuastro_autocomplete_astarithmetic(){
 
     # The installation directory of Gnuastro. The '@PREFIX@' part will be
     # replaced automatically during 'make install', with the user's given
@@ -175,7 +166,7 @@ _gnuastro_autocomplete_asttable(){
     # If 'option_name_complete==1', then we are busy filling in the option
     # value.
     if [ $option_name_complete = 1 ]; then
-        _gnuastro_autocomplete_asttable_option_value
+        _gnuastro_autocomplete_astarithmetic_option_value
 
     # When 'option_name' is not empty (and not yet complete), we are busy
     # filling in the option name.
@@ -184,7 +175,7 @@ _gnuastro_autocomplete_asttable(){
 
     # In the case of "none-of-the-above", it is an argument.
     else
-        _gnuastro_autocomplete_asttable_arguments
+        _gnuastro_autocomplete_astarithmetic_arguments
     fi
 }
 
@@ -195,4 +186,4 @@ _gnuastro_autocomplete_asttable(){
 # Define the completion specification, or COMPSPEC: -o bashdefault: Use
 # Bash default completions if nothing is found.  -F function: Use this
 # 'function' to generate the given program's completion.
-complete -o bashdefault -F _gnuastro_autocomplete_asttable asttable
+complete -o bashdefault -F _gnuastro_autocomplete_astarithmetic astarithmetic
diff --git a/bin/gnuastro-complete.bash b/bin/completion.bash.in
similarity index 92%
rename from bin/gnuastro-complete.bash
rename to bin/completion.bash.in
index d85a45a..dbe0ea6 100644
--- a/bin/gnuastro-complete.bash
+++ b/bin/completion.bash.in
@@ -1,5 +1,3 @@
-#!/bin/bash
-#
 # Common funcitons of Bash auto-completion in Gnuastro. For more details on
 # completion, see the "autocomplete feature" section under the "Developing"
 # chapter of Gnuastro's manual and the comments below.
@@ -17,14 +15,25 @@
 # Bash auto-completion should be 'local' (to that particular function and
 # the functions it calls).
 #
-# To debug/test this script, you can take these steps:
-#    1) Append the program's '-complete.bash' file into this one.
-#    2) Set 'gnuastro_prefix' variable within '_gnuastro_autocomplete_*'
-#       function of the program. This is the location that Gnuastro is
-#       installed in your OS (usually '/usr/local/bin').
-#    3) Activate it by executing this command in the terminal you are
-#       testing:
-#          source gnuastro-complete.bash
+# To debug/test this script, you can take these steps after building
+# Gnuastro in the program's 'bin/progname/astprogname-complete.bash'
+# file. Building Gnuastro is necessary because one of the files
+#
+#    1. Uncomment the two 'source' lines in the program's completion
+#       script.
+#    2. Correct the un-commented locations. Note that the second is an
+#       automatically built file (it is not under version control or in the
+#       source directory). So in case you have defined a separate build
+#       directory, give that directory. If you are building within your
+#       source (which is generally a bad idea!), it will be the same
+#       directory.
+#    3. Give a value to the 'gnuastro_prefix' variable within
+#       '_gnuastro_autocomplete_astprogname'. This is the location that
+#       Gnuastro is installed in your OS (usually '/usr/local/bin').
+#    4. Activate the program's script with this command in the terminal you
+#       are testing: 'source bin/progname/astprogname-complete.bash' (here
+#       assuming you are in the top Gnuastro source directory, you can run
+#       it from anywhere, just correct the locatation).
 #
 # Original author:
 #     Pedram Ashofteh Ardakani <pedramardakani@pm.me>
@@ -315,8 +324,8 @@ _gnuastro_autocomplete_read_option_value(){
 # opened). Note that FITS files have many possible extensions (see the
 # 'gal_fits_name_is_fits' function in 'lib/fits.c').
 _gnuastro_autocomplete_is_fits(){
-    if "$gnuastro_prefix"/astfits "$1" -h0 &> /dev/null; then return 0;
-    else                                                      return 1;
+    if "$gnuastro_prefix"/astfits "$1" &> /dev/null; then return 0;
+    else                                                  return 1;
     fi
 }
 
@@ -586,6 +595,17 @@ _gnuastro_autocomplete_compreply_tableformat(){
 
 
 
+# Add completion replies for the values to '--numthreads'.
+_gnuastro_autocomplete_compreply_numthreads(){
+    if nproc &> /dev/null; then
+        for v in $(seq $(nproc)); do COMPREPLY+=("$v"); done
+    fi
+}
+
+
+
+
+
 # Add matching options to the completion replies.
 _gnuastro_autocomplete_compreply_options_all(){
 
@@ -600,7 +620,7 @@ _gnuastro_autocomplete_compreply_options_all(){
 
     # Limit the options to those that start with the already given portion.
     if [ x$1 = x ]; then
-        options_match=$options_all
+        options_match="$options_all"
     else
         # We aren't using 'grep' because it can confuse the '--XXX' with
         # its own options on some systems (and placing a '--' before the
@@ -653,7 +673,9 @@ _gnuastro_autocomplete_compreply_fits_images(){
     # Parse the list of files and add it when it is a directory or it can
     # be read as a table.
     for f in ${files[*]} ; do
-        if [ -d "$f" ]; then COMPREPLY+=("${f#$1}/");
+        if [ -d "$f" ]; then
+            COMPREPLY+=("$f/")
+            compopt -o nospace
         elif _gnuastro_autocomplete_fits_has_image "$f"; then
             _gnuastro_autocomplete_compreply_file "$1" "$f"
         fi
@@ -693,7 +715,9 @@ _gnuastro_autocomplete_compreply_tables(){
     # Parse the list of files and add it when it is a directory or it can
     # be read as a table.
     for f in ${files[*]} ; do
-        if [ -d "$f" ]; then COMPREPLY+=("${f#$1}/");
+        if [ -d "$f" ]; then
+            COMPREPLY+=("$f/")
+            compopt -o nospace
         elif _gnuastro_autocomplete_is_table "$f"; then
             _gnuastro_autocomplete_compreply_file "$1" "$f"
         fi
diff --git a/bin/table/Makefile.am b/bin/table/Makefile.am
index 9f382ae..e46e9e3 100644
--- a/bin/table/Makefile.am
+++ b/bin/table/Makefile.am
@@ -36,7 +36,8 @@ asttable_LDADD = $(top_builddir)/bootstrapped/lib/libgnu.la \
 
 asttable_SOURCES = main.c ui.c arithmetic.c table.c
 
-EXTRA_DIST = main.h authors-cite.h args.h ui.h arithmetic.h table.h
+EXTRA_DIST = main.h authors-cite.h args.h ui.h arithmetic.h table.h \
+             asttable-complete.bash
 
 
 
diff --git a/bin/table/asttable-complete.bash b/bin/table/asttable-complete.bash
index b9e38a4..941402a 100644
--- a/bin/table/asttable-complete.bash
+++ b/bin/table/asttable-complete.bash
@@ -1,5 +1,5 @@
 # Bash autocompletion to Gnuastro's Table program. See the comments above
-# 'bin/gnuastro-complete.bash' for more.
+# 'bin/completion.bash.in' for more.
 #
 # Original author:
 #     Pedram Ashofteh Ardakani <pedramardakani@pm.me>
@@ -26,10 +26,9 @@
 
 # For debugging
 #
-# For debugging uncomment this line to load the generic Gnuastro
-# auto-completion functions, and correct the location (use an absolute
-# location).
-#source /PATH/TO/gnuastro-complete.bash
+# See the description in 'bin/completion.bash.in'.
+#source /PATH/TO/GNUASTRO/SRC/bin/completion.bash.in
+#source /PATH/TO/GNUASTRO/BUILD/bin/completion.bash-arith.tmp
 
 
 
diff --git a/doc/gnuastro.texi b/doc/gnuastro.texi
index 2612472..ae9a37c 100644
--- a/doc/gnuastro.texi
+++ b/doc/gnuastro.texi
@@ -338,6 +338,7 @@ Command-line
 
 * Arguments and options::       Different ways to specify inputs and 
configuration.
 * Common options::              Options that are shared between all programs.
+* Shell TAB completion::        Customized TAB completion in Gnuastro.
 * Standard input::              Using output of another program as input.
 
 Arguments and options
@@ -846,6 +847,7 @@ $ ./configure
 $ make -j8                         # Replace 8 with no. CPU threads.
 $ make check
 $ sudo make install
+$ echo "source /usr/local/share/gnuastro/completion.bash" > ~/.bashrc
 @end example
 
 @noindent
@@ -6835,6 +6837,7 @@ Afterwards, in @ref{Common options}, we'll go into the 
detailed list of all the
 @menu
 * Arguments and options::       Different ways to specify inputs and 
configuration.
 * Common options::              Options that are shared between all programs.
+* Shell TAB completion::        Customized TAB completion in Gnuastro.
 * Standard input::              Using output of another program as input.
 @end menu
 
@@ -7064,7 +7067,7 @@ But if it is in the middle of the command, it will take 
the text of the next opt
 You can assume by default that counting starts from 1, if it starts from 0 for 
a special option, it will be explicitly mentioned.
 @end cartouche
 
-@node Common options, Standard input, Arguments and options, Command-line
+@node Common options, Shell TAB completion, Arguments and options, Command-line
 @subsection Common options
 
 @cindex Options common to all programs
@@ -7477,8 +7480,39 @@ In others, this option will be ignored.
 
 
 
+@node Shell TAB completion, Standard input, Common options, Command-line
+@subsection Shell TAB completion (highly customized)
 
-@node Standard input,  , Common options, Command-line
+@cindex Bash auto-complete
+@cindex Completion in the shell
+@cindex Shell programmable completion
+@cindex Autocomplete (in the shell/Bash)
+Bash provides a built-in feature called @emph{programmable 
completion}@footnote{@url{https://www.gnu.org/software/bash/manual/html_node/Programmable-Completion.html}}
 (also known as TAB completion, bash completion, auto-completion, or word 
completion) to help increase interactive workflow efficiency (minimize the 
number of key-strokes @emph{and} the need to memorize things).
+Completion is activated by pressing @key{[TAB]} while you are typing a command.
+For file arguments this is the default behavior already and you have probably 
used it a lot with any command-line program.
+
+Besides this simple/default mode, Bash also enables a high level of 
customization features for its completion.
+These features have been extensively used in Gnuastro to improve your work 
efficiency.
+For example if you are running @code{asttable} (which only accepts files 
containing a table), and you press @key{[TAB]}, it will only suggest files 
containing such tables.
+As another example, if an option needs image HDUs within a FITS file, pressing 
@key{[TAB]} will suggest them (and not other possibly existing HDUs that 
contain tables, or just metadata).
+
+To activate Bash's TAB completion, you need to put the following line in one 
of your Bash startup files (for example @file{~/.bashrc}).
+For a list of (and discussion on) Bash startup files and installation 
directories see @ref{Installation directory}.
+Of course, if Gnuastro was installed in a custom location, replace the 
`@file{/usr/local}' part of the line below to the value that was given to 
@option{--prefix} during Gnuastro's configuration@footnote{In case you don't 
know the installation directory of Gnuastro on your system, you can find out 
with this command: @code{which astfits | sed -e"s|/bin/astfits||"}}.
+
+@example
+# Enable Gnuastro's TAB completion
+source /usr/local/share/gnuastro/completion.bash
+@end example
+
+After adding the line above in a Bash startup file, TAB completion will always 
be activated in any new terminal.
+To see if it has been activated, try it out with @command{asttable [TAB][TAB]} 
and @command{astarithmetic [TAB][TAB]} in a directory that contains tables and 
images.
+It will work with any Gnuastro program's arguments and long option names.
+Therefore as a side-effect your commands will be far more human-readable with 
the same number of key strokes of a short option name (if one exists).
+
+
+
+@node Standard input,  , Shell TAB completion, Command-line
 @subsection Standard input
 
 @cindex Standard input
@@ -30437,7 +30471,7 @@ This value must be directly returned by @code{main}, so 
it has to be an @code{in
 This header file keeps the global variable for the program authors and its 
BibTeX record for citation.
 They are used in the outputs of the common options @option{--version} and 
@option{--cite}, see @ref{Operating mode options}.
 
-@item completion.bash
+@item progname-complete.bash
 @cindex GNU Bash
 @cindex Bash auto-complete
 @cindex Completion in the shell
@@ -30789,9 +30823,8 @@ were produced by other tests.
 @cindex Completion in the shell
 @cindex Shell programmable completion
 @cindex Autocomplete (in the shell/Bash)
-Gnuastro uses Bash's @i{Programmable 
completion}@footnote{@url{https://www.gnu.org/software/bash/manual/html_node/Programmable-Completion.html}}
 to decrease the necessary keystrokes by users, and help them spend less time 
on figuring out the option names and values.
-Bash's programmable completion, also known as bash completion, 
auto-completion, or word completion, is a GNU Bash built-in feature that helps 
increase workflow efficiency.
-You can activate word completion by pressing the @key{[TAB]} key while typing 
a command.
+Gnuastro provides Programmable completion facilities in Bash.
+This greatly helps users reach their desired result with minimal keystrokes, 
and helps them spend less time on figuring out the option names and values 
their acceptable values.
 Gnuastro's completion script not only completes the half-written commands, but 
also prints suggestions based on previous arguments.
 
 Imagine a scenario where we need to download three columns containing the 
right ascension, declination, and parallax from the GAIA EDR3 dataset.