Merge pull request scop#676 from scop/docs/asciidoc

asciidoc test and fixes

Author: scop

.pre-commit-config.yaml

@@ -116,6 +116,23 @@ 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/bash_completion.txt

@@ -1,8 +1,6 @@
-Bash completion
-===============
+= Bash completion
 
-Configuration files
--------------------
+== Configuration files
 
 *$BASH_COMPLETION_USER_FILE*::
     Sourced late by bash_completion, pretty much after everything else.
@@ -16,8 +14,7 @@ Configuration files
     below.  If `$XDG_CONFIG_HOME` is unset or null, `~/.config` is
     used instead of it.
 
-Environment variables
----------------------
+== Environment variables
 
 *BASH_COMPLETION_COMPAT_DIR*::
     Directory for pre-dynamic loading era (pre-2.0) backwards compatibility

doc/main.txt

@@ -1,10 +1,11 @@
-Bash-completion
-===============
+= Bash-completion
+
 Freddy Vulto (FVu)
 v1.0, Mar 2009
 
-Preface
-=======
+[preface]
+= 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

doc/styleguide.txt

@@ -1,8 +1,7 @@
-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
 these standards so that it is as easy to maintain as existing code.
@@ -14,43 +13,38 @@ 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))".
 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
 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 \`...`
 
 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
-------------
+== -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
@@ -61,8 +55,7 @@ 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`
--------------------------------------------------
+== `[[ ${COMPREPLY-} == *= ]] && compopt -o nospace`
 
 The above is functionally a shorthand for:
 
@@ -75,8 +68,7 @@ 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`
-------------------
+== `$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
@@ -95,31 +87,27 @@ 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
 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))]}.
 
-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.
 
-Function names
---------------
+== Function names
 
 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
@@ -133,16 +121,13 @@ This is due to backwards compatibility reasons, but all functions introduced
 after version 2.11 should follow this name prefix rule.
 
 /////////////////////////////////////////
-case/esac vs if
----------------
 
-quoting
--------
+== case/esac vs if
+
+== quoting
 
-awk vs cut for simple cases
----------------------------
+== awk vs cut for simple cases
 
-variable naming
----------------
+== variable naming
 
 /////////////////////////////////////////

doc/testing.txt

@@ -1,26 +1,21 @@
-Automated testing
-=================
+= Automated testing
+
+== Introduction
 
-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
-------------------
+== 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
 
 Installing dependencies should be easy using your local package manager or
 `pip`. Python 3.6 or newer is required, and the rest of the Python package
@@ -30,9 +25,7 @@ this file can be fed directly to it, e.g. like:
 pip install -r test/requirements.txt
 ------------------------------------
 
-
-Debian/Ubuntu
-~~~~~~~~~~~~~
+=== Debian/Ubuntu
 
 On Debian/Ubuntu you can use `apt-get`:
 -------------
@@ -42,8 +35,7 @@ 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
-~~~~~~~~~~~~~~~~~~
+=== Fedora/RHEL/CentOS
 
 On Fedora and RHEL/CentOS (with EPEL) you can try `yum` or `dnf`:
 -------------
@@ -52,17 +44,12 @@ 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
----------
+== 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
------------------
+== Running the tests
 
 Tests are run by calling `pytest` on the desired test directories or
 individual files, for example in the project root directory:
@@ -72,41 +59,32 @@ pytest test/t
 
 See `test/docker/entrypoint.sh` for how and what we run and test in CI.
 
-
-Specifying bash binary
-~~~~~~~~~~~~~~~~~~~~~~
+=== 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
 
-Maintenance
------------
-
-
-Adding a completion test
-~~~~~~~~~~~~~~~~~~~~~~~~
+=== 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
----------
+== Rationale
 
+=== Naming conventions
 
-Naming conventions
-~~~~~~~~~~~~~~~~~~
+==== Test suite or testsuite
 
-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
-^^^^^^^^^^^^^^^
+==== 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].