Expanded info on getting and building argbash.

doc/_static/index_script-create.txt

@@ -1,2 +1,2 @@
-./bin/argbash-init --pos positional-arg --opt option --opt-bool print - | ./bin/argbash -o script.sh -
+bin/argbash-init --pos positional-arg --opt option --opt-bool print - | ../bin/argbash -o script.sh -
 

doc/_static/wrapper-output-action.txt

@@ -5,16 +5,17 @@ Contents of '../src' matching '*.m4':
 	argbash-init.m4: 4 kiB
 	argbash-lib.m4: 0 kiB
 	argbash.m4: 7 kiB
-	argument_value_types.m4: 3 kiB
+	argument_value_types.m4: 4 kiB
+	constants.m4: 0 kiB
 	default_settings.m4: 0 kiB
 	env_vars.m4: 1 kiB
-	function_generators.m4: 2 kiB
+	function_generators.m4: 5 kiB
 	list.m4: 5 kiB
 	output.m4: 0 kiB
 	output-standalone.m4: 0 kiB
 	progs.m4: 2 kiB
-	stuff.m4: 50 kiB
-	utilities.m4: 3 kiB
+	stuff.m4: 54 kiB
+	utilities.m4: 5 kiB
 	value_validators.m4: 5 kiB
 Contents of '../resources/examples' matching '*.m4':
 	minimal.m4: 0 kiB

doc/index.rst

@@ -22,7 +22,7 @@ A basic template generator ``argbash-init`` is part of the package, and you can
 :Authors:
   `Matěj Týč <https://github.com/matejak>`_
 :Copyright:
-  2014--2016, Matěj Týč
+  2014--2017, Matěj Týč
 :Website:
   https://argbash.io
 
@@ -52,6 +52,14 @@ Eventually, you may want to add/remove/rename arguments your script accepts.
 In that case, you just need to edit the script --- you don't need to repeate the two steps listed above!
 Why? It is so because the script retains the template section, so if you need to make adjustments to the template, you just edit the template section of the script and run ``argbash`` on top of the script to get it updated.
 
+How to use ``Argbash``?
+You can either
+
+* :ref:`download and install it <user_install>` locally,
+* use the `online generator <https://argbash.io/generate>`_, or
+* use the `Docker container <https://hub.docker.com/r/matejak/argbash/>`_.
+
+
 .. _quickstart_init:
 
 Generating a template

doc/install.rst

@@ -1,14 +1,22 @@
 Installation
 ============
 
-Installation is simple, but as it is described in the :ref:`quickstart`, you don't need it to use ``Argbash``.
+
+.. _user_install:
+
+User installation
+-----------------
+
+If you want to use Argbash locally, you have to download the software package and run the installation script.
+
+1. Go to the `release section of the GitHub project <https://github.com/matejak/argbash/releases>`_, choose the version to download, and download the source code package.
+
+#. Unpack the contents of the archive.
+   You can use the ``bin/argbash`` script without any installation (as it is described in the :ref:`quickstart`), but you can proceed to the installation in order to be able to use ``argbash`` system-wide.
 
 #. Go to the ``resources`` folder.
    There is a ``Makefile``.
 
-#. Run some checks: ``make check``.
-   You should get no errors.
-
 #. According to whether you have your ``$HOME/.local/bin`` folder in the ``PATH``:
 
    * If so, run ``make install PREFIX=$HOME/.local``,
@@ -22,6 +30,10 @@ Installation is simple, but as it is described in the :ref:`quickstart`, you don
 
      This way of installation won't install the ``argbash-xtoy`` :ref:`migration scripts <argbash_components>`.
 
+#. Optional: Run some checks by executing: ``make check`` (still in the ``resources`` folder).
+   You should get a message ``All is OK`` at the bottom.
+
+
 ``Argbash`` has this audience:
 
 * Users --- people that use scripts that make use of ``Argbash``.
@@ -33,6 +45,25 @@ Installation is simple, but as it is described in the :ref:`quickstart`, you don
 * ``grep``, ``sed``, ``coreutils`` --- The ``argbash`` script uses ``grep``, ``sed``, ``cat``, and ``test``. If you have ``autoconf``, you probably have those already.
 * ``GNU Make >= 4.0`` --- the project uses Makefiles to perform a wide variety of tasks, although it is more of interest to Tinkerers.
 
+
+Building Argbash
+----------------
+
+If you identify yourself as a tinkerer (i.e. you want to play with internals of ``Argbash``), you may use a different set of steps:
+
+#. Clone the Git repository: ``git clone https://github.com/matejak/argbash.git``
+
+#. Go to the ``resources`` directory consider running a develop install there, e.g. ``make develop PREFIX=$HOME/.local``,
+
+   This type of installation ensures that whenever you make a change to the ``bin/argbash`` script in the repository, the ``argbash`` command always calls that ``bin/argbash`` script.
+
+#. After you make modifications the source files (``.m4`` files in the ``src`` directory), you regenerate ``bin/argbash`` by running ``make ../bin/argbash`` in the ``resources`` directory.
+
+   If you let a bug through that prevents the ``argbash`` script to regenerate itself, run ``make bootstrap`` to regenerate it in a more robust way.
+
+#. Remember to run ``make check`` in the ``resources`` directory often to catch bugs as soon as possible.
+
+
 .. _argbash_components:
 
 Argbash components
@@ -53,11 +84,13 @@ The ``Argbash`` package consists of these scripts:
 * ``argbash-init`` is a quickstart script --- it enables you to create a basic :ref:`template <templates>` for your script.
   Then, you just have to make some slight modifications, :ref:`feed it to argbash <invocation>` and you are done.
 
+
 The main Makefile
 -----------------
 
 The ``Makefile`` in the ``resources`` folder can do many things:
 
+
 .. _install:
 
 Installation
@@ -69,6 +102,7 @@ Installation
   This is inspired by Python's ``python setup.py develop`` pattern.
 * ``make uninstall [PREFIX=foo]`` inverse of the above.
 
+
 Running argbash
 +++++++++++++++
 
@@ -78,6 +112,7 @@ Running argbash
 * ``make foo/bar.sh`` generates a script provided that there is a ``foo/bar.m4`` file.
 * ``make foo/bar2.sh`` generates a script provided that there is a ``foo/bar.sh`` file.
 
+
 Releasing
 +++++++++