[Bash-completion-commits] [SCM] bash-completion branch, master, updated. b33a1c7526696585e43f4f6d23b1d0d88d176b99

Wed Apr 15 20:39:21 UTC 2009

The following commit has been merged in the master branch:
commit b33a1c7526696585e43f4f6d23b1d0d88d176b99
Author: Freddy Vulto <fvulto at gmail.com>
Date:   Wed Apr 15 22:19:26 2009 +0200

    Added asciidoc files.

diff --git a/doc/main.txt b/doc/main.txt
new file mode 100644
index 0000000..d9acde5
--- /dev/null
+++ b/doc/main.txt
@@ -0,0 +1,10 @@
+Bash-completion
+===============
+Freddy Vulto (FVu)
+v1.0, Mar 2009
+
+// include::intro.txt[]
+// include::bash_completion.txt[]
+
+include::styleguide.txt[]
+include::testing.txt[]
diff --git a/doc/main.xml b/doc/main.xml
new file mode 100644
index 0000000..ddf324a
--- /dev/null
+++ b/doc/main.xml
@@ -0,0 +1,151 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<book lang="en">
+<bookinfo>
+    <title>Bash-completion</title>
+    <date>Mar 2009</date>
+    <author>
+        <firstname>Freddy</firstname>
+        <othername>Vulto</othername>
+        <surname>(FVu)</surname>
+    </author>
+    <authorinitials>FV(</authorinitials>
+
+<revhistory><revision><revnumber>1.0</revnumber><date>Mar 2009</date><authorinitials>FV(</authorinitials></revision></revhistory>
+
+</bookinfo>
+<preface>
+<title>Preface</title>
+</preface>
+<part id="_coding_style_guide">
+<title>Coding Style Guide</title>
+<simpara>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!</simpara>
+
+<simpara>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.</simpara>
+
+</part>
+<part id="_automated_testing">
+<title>Automated testing</title>
+<chapter id="_introduction">
+<title>Introduction</title>
+<simpara>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.</simpara>
+
+<simpara>The bash-completion test suite is written on top of the <ulink url="http://www.gnu.org/software/dejagnu/">DejaGnu</ulink> testing framework.  DejaGnu is written in <ulink url="http://expect.nist.gov">Expect</ulink>, which in turn uses <ulink url="http://tcl.sourceforge.net">Tcl</ulink> &#8212; Tool command language.</simpara>
+
+</chapter>
+<chapter id="_installing_dejagnu">
+<title>Installing DejaGnu</title>
+<simpara>Installing DejaGnu should be easy using your local package manager.</simpara>
+
+<section id="_debian_ubuntu">
+<title>Debian/Ubuntu</title>
+<simpara>On Debian/Ubuntu you can use <literal>apt-get</literal>:</simpara>
+
+<screen>sudo apt-get install dejagnu</screen>
+<simpara>This should also install the necessary <literal>expect</literal> and <literal>tcl</literal> packages.</simpara>
+
+</section>
+</chapter>
+<chapter id="_structure">
+<title>Structure</title>
+<section id="_main_areas_dejagnu_tools">
+<title>Main areas (DejaGnu tools)</title>
+<simpara>The tests are grouped into different areas, called <emphasis>tool</emphasis> in DejaGnu:</simpara>
+
+<variablelist>
+<varlistentry>
+<term>
+<emphasis role="strong">install</emphasis>
+</term>
+<listitem>
+<simpara>
+  Functional tests for installation and caching of the main bash-completion package.
+</simpara>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>
+<emphasis role="strong">completion</emphasis>
+</term>
+<listitem>
+<simpara>
+  Functional tests per completion.
+</simpara>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>
+<emphasis role="strong">unit</emphasis>
+</term>
+<listitem>
+<simpara>
+  Unit tests for bash-completion helper functions.
+</simpara>
+</listitem>
+</varlistentry>
+</variablelist>
+</section>
+<section id="_running_the_tests">
+<title>Running the tests</title>
+<simpara>The tests are run by calling <literal>runtest</literal> in the test directory:</simpara>
+
+<screen>runtest --outdir=log --tool completion
+runtest --outdir=log --tool install
+runtest --outdir=log --tool unit</screen>
+<simpara>The commands above are already wrapped up in shell scripts within the <literal>test</literal> directory:</simpara>
+
+<screen>./runCompletion
+./runInstall
+./runUnit</screen>
+</section>
+</chapter>
+<chapter id="_maintenance">
+<title>Maintenance</title>
+<section id="_adding_a_completion_test">
+<title>Adding a completion test</title>
+<simpara>You can add script/generate to add a test.</simpara>
+
+</section>
+</chapter>
+<chapter id="_rationale">
+<title>Rationale</title>
+<section id="_naming_conventions">
+<title>Naming conventions</title>
+<section id="_test_suite_or_testsuite">
+<title>Test suite or testsuite</title>
+<simpara>The primary Wikipedia page is called
+<ulink url="http://en.wikipedia.org/wiki/Test_suite">test suite</ulink> and not testsuite, so that's what this
+document sticks to.</simpara>
+
+</section>
+<section id="_script_generate">
+<title>script/generate</title>
+<simpara>The name and location of this code generation script come from Ruby on Rails' <ulink url="http://en.wikibooks.org/wiki/Ruby_on_Rails/Tools/Generators">script/generate</ulink>.</simpara>
+
+</section>
+</section>
+</chapter>
+<chapter id="_reference">
+<title>Reference</title>
+<simpara>Within test scripts the following library functions can be used:</simpara>
+
+</chapter>
+<chapter id="_the_test_environment">
+<title>The test environment</title>
+<simpara>The tests run in a specially prepared bash environment.  The following files are used:
+<emphasis role="strong"> bashrch
+</emphasis> inputrc
+* fixtures</simpara>
+
+<section id="_bashrc">
+<title>bashrc</title>
+<simpara>Contents of bashrc:</simpara>
+
+</section>
+</chapter>
+</part>
+<index id="_index">
+<title>Index</title>
+</index>
+</book>
diff --git a/doc/makeHtml.sh b/doc/makeHtml.sh
new file mode 100755
index 0000000..8e52eff
--- /dev/null
+++ b/doc/makeHtml.sh
@@ -0,0 +1,4 @@
+#!/bin/bash -eu
+
+[ -d html~ ] || mkdir html~
+a2x -D html~ -d book -f xhtml main.txt
diff --git a/doc/styleguide.txt b/doc/styleguide.txt
new file mode 100644
index 0000000..7dd7c20
--- /dev/null
+++ b/doc/styleguide.txt
@@ -0,0 +1,36 @@
+Coding Style Guide
+==================
+
+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.
+
+/////////////////////////////////////////
+case/esac vs if
+---------------
+
+simple matching vs extended globbing
+------------------------------------
+in case statements: -@(a|b)) vs -a|-b)
+
+[[ ]] vs [ ]
+------------
+
+indentation
+-----------
+
+line wrapping
+-------------
+
+quoting
+-------
+
+awk vs cut for simple cases
+---------------------------
+
+$(...) vs `...`
+---------------
+
+variable and function naming
+----------------------------
+/////////////////////////////////////////
diff --git a/doc/testing.txt b/doc/testing.txt
new file mode 100644
index 0000000..65579fd
--- /dev/null
+++ b/doc/testing.txt
@@ -0,0 +1,115 @@
+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 bash-completion test suite is written on top of the http://www.gnu.org/software/dejagnu/[DejaGnu] testing framework.  DejaGnu is written in http://expect.nist.gov[Expect], which in turn uses http://tcl.sourceforge.net[Tcl] -- Tool command language.
+
+
+
+
+Installing DejaGnu
+------------------
+
+Installing DejaGnu should be easy using your local package manager.
+
+
+Debian/Ubuntu
+~~~~~~~~~~~~~
+
+On Debian/Ubuntu you can use `apt-get`:
+-------------
+sudo apt-get install dejagnu
+-------------
+This should also install the necessary `expect` and `tcl` packages.
+
+
+
+
+Structure
+---------
+
+
+Main areas (DejaGnu tools)
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The tests are grouped into different areas, called _tool_ in DejaGnu:
+
+*install*:: 
+  Functional tests for installation and caching of the main bash-completion package.
+*completion*::
+  Functional tests per completion.
+*unit*:: 
+  Unit tests for bash-completion helper functions.
+
+
+Running the tests
+~~~~~~~~~~~~~~~~~
+
+The tests are run by calling `runtest` in the test directory:
+-----------------------
+runtest --outdir=log --tool completion
+runtest --outdir=log --tool install
+runtest --outdir=log --tool unit
+-----------------------
+The commands above are already wrapped up in shell scripts within the `test` directory:
+-----------------------
+./runCompletion
+./runInstall
+./runUnit
+-----------------------
+
+
+
+
+Maintenance
+-----------
+
+
+Adding a completion test
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can add script/generate to add a test.
+
+
+
+
+Rationale
+---------
+
+
+Naming conventions
+~~~~~~~~~~~~~~~~~~
+
+Test suite or testsuite
+^^^^^^^^^^^^^^^^^^^^^^^
+The primary Wikipedia page is called
+http://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' http://en.wikibooks.org/wiki/Ruby_on_Rails/Tools/Generators[script/generate].
+
+
+
+
+== Reference
+
+Within test scripts the following library functions can be used:
+
+== The test environment
+
+The tests run in a specially prepared bash environment.  The following files are used:
+* bashrch
+* inputrc
+* fixtures
+
+=== bashrc
+
+Contents of bashrc:
+
+Index
+=====

-- 
bash-completion

