docs: convert to markdown, remove some no longer relevant sections

.gitignore

@@ -17,7 +17,5 @@ pytestdebug.log
 /config.status
 /configure
 /configure.lineno
-/doc/*.xml
-/doc/html*
 /install-sh
 /missing

.pre-commit-config.yaml

@@ -116,23 +116,6 @@ repos:
           - scan
         exclude: ^CHANGELOG\.md$
 
-  - repo: local
-    hooks:
-      - id: asciidoctor
-        name: asciidoctor
-        language: docker_image
-        entry: asciidoctor/docker-asciidoctor:1.15 asciidoctor
-        args:
-          - --out-file
-          - /dev/null
-          - --failure-level
-          - WARN
-          - --doctype
-          - book
-          - doc/main.txt
-        pass_filenames: false
-        files: ^doc/.*\.txt$
-
   - repo: https://github.com/pre-commit/pre-commit-hooks
     rev: v4.0.1
     hooks:

doc/Makefile.am

@@ -1,6 +1,4 @@
 EXTRA_DIST = \
-	bash_completion.txt \
-	main.txt \
-	makeHtml.sh \
-	styleguide.txt \
-	testing.txt
+	configuration.md \
+	styleguide.md \
+	testing.md

doc/configuration.md

@@ -0,0 +1,75 @@
+# 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*` shell variables below.
+If `$XDG_CONFIG_HOME` is unset or null,`~/.config` is
+used instead of it.
+
+## Shell 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_ the `tar` completion, it will do
+correct path completion for tar file _contents_. If unset or null,
+_paths to_ tar files will be correctly completed. Unfortunately we do not
+have a way to make both Just Work properly at the moment. We consider it
+more important to have proper completion of paths to tar files than it is
+to have completion for their contents, so the default is unset.

doc/styleguide.txt → doc/styleguide.md

@@ -1,9 +1,9 @@
-= Coding Style Guide
+# Coding style guide
 
-== Introduction
+## 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
+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!
@@ -13,103 +13,107 @@ 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
+## Indentation
 
 Indent step should be 4 spaces, no tabs.
 
-== Globbing in case labels
+## 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))".
+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 [ ]
+## `[[ ]]` vs `[ ]`
 
-Always use [[ ]] instead of [ ].  Rationale: the former is less error
+Always use `[[ ]]` instead of `[ ]`. Rationale: the former is less error
 prone, more featureful, and slightly faster.
 
-== Line wrapping
+## 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 \`...`
+## `$( )` vs backticks
 
 When you need to do some code substitution in your completion script,
-you *MUST* use the $(...) construct, rather than the \`...`. The former
+you _MUST_ use the `$(...)` construct, rather than backticks. 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
+## `-o filenames`
 
-As a rule of thumb, do not use "complete -o filenames". Doing it makes
+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
+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
+`_filedir` and `_filedir_xspec` helpers do this automatically whenever
 they return some completions.
 
-== `[[ ${COMPREPLY-} == *= ]] && compopt -o nospace`
+## `[[ ${COMPREPLY-} == *= ]] && compopt -o nospace`
 
 The above is functionally a shorthand for:
 
-    if [[ ${#COMPREPLY[@]} -eq 1 && ${COMPREPLY[0]} == *= ]]; then
-        compopt -o nospace
-    fi
+```bash
+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
+appended after the equal sign. Calling `compopt -o nospace` makes sense
 in case completion actually occurs: when only one completion is
-available in COMPREPLY.
+available in `COMPREPLY`.
 
-== `$split && return`
+## `$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
+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
+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
+## 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
+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 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))]}.
+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
+## 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.
+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.
 
-== Function names
+## Function names
 
-Use the _comp_ prefix for all function names, and _comp_cmd_ for functions
+Use the `_comp_` prefix for all function names, and `_comp_cmd_` for functions
 defined in per command completion files and not anywhere else. Prefixing with
 an underscore helps keep the functions out of the way for most command name
 completions (except obviously ones starting with an underscore or ones that have
@@ -120,14 +124,6 @@ It is known that a lot of functions in the tree do not follow this practice.
 This is due to backwards compatibility reasons, but all functions introduced
 after version 2.11 should follow this name prefix rule.
 
-/////////////////////////////////////////
+## Variable naming
 
-== case/esac vs if
-
-== quoting
-
-== awk vs cut for simple cases
-
-== variable naming
-
-/////////////////////////////////////////
+To be written.