Adding upstream version 1:2.11.upstream/1%2.11

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

8 files changed, 344 insertions, 0 deletions

diff --git a/doc/Makefile.am b/doc/Makefile.am
new file mode 100644
index 0000000..6930b9c
--- /dev/null
+++ b/doc/Makefile.am
@@ -0,0 +1,8 @@
+EXTRA_DIST = \
+	bash_completion.txt \
+	bashrc \
+	inputrc \
+	main.txt \
+	makeHtml.sh \
+	styleguide.txt \
+	testing.txt
diff --git a/doc/bash_completion.txt b/doc/bash_completion.txt
new file mode 100644
index 0000000..e67f98b
--- /dev/null
+++ b/doc/bash_completion.txt
@@ -0,0 +1,66 @@
+Bash completion
+===============
+
+Configuration files
+-------------------
+
+*$BASH_COMPLETION_USER_FILE*::
+    Sourced late by bash_completion, pretty much after everything else.
+    Use this file for example to load additional completions, and to remove
+    and override ones installed by bash_completion. Defaults to
+    `~/.bash_completion` if unset or null.
+
+*$XDG_CONFIG_HOME/bash_completion*::
+    Sourced by the bash_completion.sh profile.d script.  This file is
+    suitable for definitions of all `COMP_*` environment variables
+    below.  If `$XDG_CONFIG_HOME` is unset or null, `~/.config` is
+    used instead of it.
+
+Environment variables
+---------------------
+
+*BASH_COMPLETION_COMPAT_DIR*::
+    Directory for pre-dynamic loading era (pre-2.0) backwards compatibility
+    completion files that are loaded eagerly from `bash_completion` when it is
+    loaded. If unset or null, the default compatibility directory to use is
+    `/etc/bash_completion.d`.
+
+*COMP_CONFIGURE_HINTS*::
+    If set and not null, `configure` completion will return the entire option
+    string (e.g.  `--this-option=DESCRIPTION`) so one can see what kind of data
+    is required and then simply delete the descriptive text and add one's own
+    data.  If unset or null (default), `configure` completion will strip
+    everything after the '=' when returning completions.
+
+*COMP_CVS_REMOTE*::
+    If set and not null, `cvs commit` completion will try to complete on
+    remotely checked-out files.  This requires passwordless access to the
+    remote repository.  Default is unset.
+
+*COMP_FILEDIR_FALLBACK*::
+    If set and not null, completions that look for filenames based on their
+    "extensions" will fall back to suggesting all files if there are none
+    matching the sought ones.
+
+*COMP_IWLIST_SCAN*::
+    If set and not null, `iwconfig` completion will try to complete on
+    available wireless networks identifiers.  Default is unset.
+
+*COMP_KNOWN_HOSTS_WITH_HOSTFILE*::
+    If set and not null (default), known hosts completion will complement
+    hostnames from ssh's known_hosts files with hostnames taken from the file
+    specified by the HOSTFILE shell variable (compgen -A hostname). If null,
+    known hosts completion will omit hostnames from HOSTFILE.  Omitting
+    hostnames from HOSTFILE is useful if HOSTFILE contains many entries for
+    local web development or ad-blocking.
+
+*COMP_KNOWN_HOSTS_WITH_AVAHI*::
+    If set and not null, known hosts completion will try to use `avahi-browse`
+    for additional completions.  This may be a slow operation in some setups.
+    Default is unset.
+
+*COMP_TAR_INTERNAL_PATHS*::
+    If set and not null *before* sourcing bash_completion, `tar` completion
+    will do correct path completion for tar file contents.  If unset or null,
+    `tar' completion will do correct completion for paths to tar files.  See
+    also README.
diff --git a/doc/bashrc b/doc/bashrc
new file mode 120000
index 0000000..e22ec0e
--- /dev/null
+++ b/doc/bashrc
@@ -0,0 +1 @@
+../test/config/bashrc
\ No newline at end of file
diff --git a/doc/inputrc b/doc/inputrc
new file mode 120000
index 0000000..b6f22e6
--- /dev/null
+++ b/doc/inputrc
@@ -0,0 +1 @@
+../test/config/inputrc
\ No newline at end of file
diff --git a/doc/main.txt b/doc/main.txt
new file mode 100644
index 0000000..d8a3076
--- /dev/null
+++ b/doc/main.txt
@@ -0,0 +1,18 @@
+Bash-completion
+===============
+Freddy Vulto (FVu)
+v1.0, Mar 2009
+
+Preface
+=======
+Bash completion extends bashs standard completion behavior to achieve
+complex command lines with just a few keystrokes.  This project was
+conceived to produce programmable completion routines for the most
+common Linux/UNIX commands, reducing the amount of typing sysadmins
+and programmers need to do on a daily basis.
+
+// include::intro.txt[]
+include::bash_completion.txt[]
+
+include::styleguide.txt[]
+include::testing.txt[]
diff --git a/doc/makeHtml.sh b/doc/makeHtml.sh
new file mode 100755
index 0000000..79780eb
--- /dev/null
+++ b/doc/makeHtml.sh
@@ -0,0 +1,4 @@
+#!/bin/bash -eu
+
+[ -d html~ ] || mkdir html~
+a2x -D html~ -d book -f xhtml --asciidoc-opts="--unsafe" main.txt
diff --git a/doc/styleguide.txt b/doc/styleguide.txt
new file mode 100644
index 0000000..2251e77
--- /dev/null
+++ b/doc/styleguide.txt
@@ -0,0 +1,134 @@
+Coding Style Guide
+==================
+
+Introduction
+------------
+This document attempts to explain the basic styles and patterns that
+are used in the bash completion.  New code should try to conform to
+these standards so that it is as easy to maintain as existing code.
+Of course every rule has an exception, but it's important to know
+the rules nonetheless!
+
+This is particularly directed at people new to the bash completion
+codebase, who are in the process of getting their code reviewed.
+Before getting a review, please read over this document and make
+sure your code conforms to the recommendations here.
+
+Indentation
+-----------
+Indent step should be 4 spaces, no tabs.
+
+Globbing in case labels
+-----------------------
+
+Avoid "fancy" globbing in case labels, just use traditional style when
+possible.  For example, do "--foo|--bar)" instead of "--@(foo|bar))".
+Rationale: the former is easier to read, often easier to grep, and
+doesn't confuse editors as bad as the latter, and is concise enough.
+
+[[ ]] vs [ ]
+----------------
+
+Always use [[ ]] instead of [ ].  Rationale: the former is less error
+prone, more featureful, and slightly faster.
+
+Line wrapping
+-------------
+
+Try to wrap lines at 79 characters. Never go past this limit, unless
+you absolutely need to (example: a long sed regular expression, or the
+like). This also holds true for the documentation and the testsuite.
+Other files, like ChangeLog, or COPYING, are exempt from this rule.
+
+$(...) vs \`...`
+----------------
+
+When you need to do some code substitution in your completion script,
+you *MUST* use the $(...) construct, rather than the \`...`. The former
+is preferable because anyone, with any keyboard layout, is able to
+type it. Backticks aren't always available, without doing strange
+key combinations.
+
+-o filenames
+------------
+
+As a rule of thumb, do not use "complete -o filenames". Doing it makes
+it take effect for all completions from the affected function, which
+may break things if some completions from the function must not be
+escaped as filenames. Instead, use "compopt -o filenames" to turn on
+"-o filenames" behavior dynamically when returning completions that
+need that kind of processing (e.g. file and command names). The
+_filedir and _filedir_xspec helpers do this automatically whenever
+they return some completions.
+
+[[ ${COMPREPLY-} == *= ]] && compopt -o nospace
+------------------------------------------------
+
+The above is functionally a shorthand for:
+----
+if [[ ${#COMPREPLY[@]} -eq 1 && ${COMPREPLY[0]} == *= ]]; then
+    compopt -o nospace
+fi
+----
+It is used to ensure that long options' name won't get a space
+appended after the equal sign.  Calling compopt -o nospace makes sense
+in case completion actually occurs: when only one completion is
+available in COMPREPLY.
+
+$split && return
+----------------
+
+Should be used in completions using the -s flag of _init_completion,
+or other similar cases where _split_longopt has been invoked, after
+$prev has been managed but before $cur is considered.  If $cur of the
+form --foo=bar was split into $prev=--foo and $cur=bar and the $prev
+block did not process the option argument completion, it makes sense
+to return immediately after the $prev block because --foo obviously
+takes an argument and the remainder of the completion function is
+unlikely to provide meaningful results for the required argument.
+Think of this as a catch-all for unknown options requiring an
+argument.
+
+Note that even when using this, options that are known to require an
+argument but for which we don't have argument completion should be
+explicitly handled (non-completed) in the $prev handling block because
+--foo=bar options can often be written without the equals sign, and in
+that case the long option splitting does not occur.
+
+Use arithmetic evaluation
+-------------------------
+
+When dealing with numeric data, take advantage of arithmetic evaluation.
+In essence, use (( ... )) whenever it can replace [[ ... ]] because the
+syntax is more readable; no need for $-prefixes, numeric comparison etc
+operators are more familiar and easier on the eye.
+
+Array subscript access
+----------------------
+
+Array subscripts are arithmetic expressions, take advantage of that.
+E.g. write ${foo[bar]}, not ${foo[$bar]}, and similarly ${foo[bar+1]}
+vs ${foo[((bar+1))]} or ${foo[$((bar+1))]}, ${foo[--i]} vs ${foo[((--i))]}.
+
+Loop variable names
+-------------------
+
+Use i, j, k for loop-local indices; n and m for lengths; some other descriptive
+name typically based on array name but in singular when looping over actual
+values. If an index or value is to be accessed later on instead of being just
+locally for looping, use a more descriptive and specific name for it.
+
+/////////////////////////////////////////
+case/esac vs if
+---------------
+
+quoting
+-------
+
+awk vs cut for simple cases
+---------------------------
+
+variable and function naming
+----------------------------
+
+/////////////////////////////////////////
diff --git a/doc/testing.txt b/doc/testing.txt
new file mode 100644
index 0000000..3ec7c97
--- /dev/null
+++ b/doc/testing.txt
@@ -0,0 +1,112 @@
+Automated testing
+=================
+
+Introduction
+------------
+The bash-completion package contains an automated test suite.  Running the
+tests should help verifying that bash-completion works as expected.  The tests
+are also very helpful in uncovering software regressions at an early stage.
+
+The test suite is written in Python, using https://pytest.org/[pytest]
+and https://pexpect.readthedocs.io/[pexpect].
+
+
+Coding Style Guide
+------------------
+
+For the Python part, all of it is formatted using
+https://github.com/ambv/black[Black], and we also run
+https://flake8.pycqa.org/[Flake8] on it.
+
+
+Installing dependencies
+-----------------------
+
+Installing dependencies should be easy using your local package manager or
+`pip`. Python 3.4 or newer is required, and the rest of the Python package
+dependencies are specified in the `test/requirements.txt` file. If using `pip`,
+this file can be fed directly to it, e.g. like:
+------------------------------------
+pip install -r test/requirements.txt
+------------------------------------
+
+
+Debian/Ubuntu
+~~~~~~~~~~~~~
+
+On Debian/Ubuntu you can use `apt-get`:
+-------------
+sudo apt-get install python3-pytest python3-pexpect
+-------------
+This should also install the necessary dependencies. Only Debian testing
+(buster) and Ubuntu 18.10 (cosmic) and later have an appropriate version
+of pytest in the repositories.
+
+Fedora/RHEL/CentOS
+~~~~~~~~~~~~~~~~~~
+
+On Fedora and RHEL/CentOS (with EPEL) you can try `yum` or `dnf`:
+-------------
+sudo yum install python3-pytest python3-pexpect
+-------------
+This should also install the necessary dependencies. At time of writing, only
+Fedora 29 comes with recent enough pytest.
+
+
+
+Structure
+---------
+
+Tests are in the `t/` subdirectory, with `t/test_\*.py` being completion
+tests, and `t/unit/test_unit_\*.py` unit tests.
+
+
+Running the tests
+-----------------
+
+Tests are run by calling `pytest` on the desired test directories or
+individual files, for example in the project root directory:
+-----------------------
+pytest test/t
+-----------------------
+
+See `test/docker/docker-script.sh` for how and what we run and test in CI.
+
+
+Specifying bash binary
+~~~~~~~~~~~~~~~~~~~~~~
+
+The test suite standard uses `bash` as found in PATH. Export the
+`bashcomp_bash` environment variable with a path to another bash executable if
+you want to test against something else.
+
+
+Maintenance
+-----------
+
+
+Adding a completion test
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can run `cd test && ./generate cmd` to add a test for the `cmd`
+command. Additional arguments will be passed to the first generated test case.
+This will add the `test/t/test_cmd.py` file with a very basic test, and add it
+to `test/t/Makefile.am`. Add additional tests to the generated file.
+
+Rationale
+---------
+
+
+Naming conventions
+~~~~~~~~~~~~~~~~~~
+
+Test suite or testsuite
+^^^^^^^^^^^^^^^^^^^^^^^
+The primary Wikipedia page is called
+https://en.wikipedia.org/wiki/Test_suite[test suite] and not testsuite, so
+that's what this document sticks to.
+
+script/generate
+^^^^^^^^^^^^^^^
+The name and location of this code generation script come from Ruby on Rails'
+https://en.wikibooks.org/wiki/Ruby_on_Rails/Tools/Generators[script/generate].