Improved docs

Author: matejak

ChangeLog

@@ -1,4 +1,4 @@
-1.1.0a (2015-09-01)
+1.1.0 (2015-09-06)
 ------------------
 
 New features:

README.md

@@ -36,7 +36,7 @@ Following arguments are supported:
 
 The utility has been inspired by Python's `argparse` and the `shflags` project.
 
-**Read [the docs](doc/index.rst) for more info**
+**[Read the docs](http://argbash.readthedocs.org/en/latest/) for more info**
 
 ## Requirements
 

bin/argbash.sh

@@ -1,6 +1,6 @@
 #!/bin/bash
 
-VERSION=1.1.0a
+VERSION=1.1.0
 # DEFINE_SCRIPT_DIR()
 # ARG_POSITIONAL_SINGLE([input],[The input template file])
 # ARG_OPTIONAL_SINGLE([output],[o],[Name of the output file (pass '-' for stdout)],[-])
@@ -10,7 +10,7 @@ VERSION=1.1.0a
 
 # ARGBASH_GO()
 # needed because of Argbash --> m4_ignore([
-### START OF CODE GENERATED BY ARGBASH v1.1.0a one line above ###
+### START OF CODE GENERATED BY ARGBASH v1.1.0 one line above ###
 # THE DEFAULTS INITIALIZATION --- POSITIONALS
 # THE DEFAULTS INITIALIZATION --- OPTIONALS
 _ARG_OUTPUT="-"

doc/_static/minimal-output-help.txt

@@ -4,7 +4,7 @@
 
     This is a minimal demo of Argbash potential
     Usage: ../resources/examples/minimal.sh <positional-arg> [--option <arg>] [--(no-)verbose] [--version] [--help]
-    	<positional-arg>: Positional arg
+    	<positional-arg>: Positional arg description
     	-o,--option: A option with short and long flags and default (default: 'b')
     	--verbose,--no-verbose: A boolean option with long flag (and implicit default: off) (default: 'off')
     	-v,--version: Prints version

doc/example.rst

@@ -1,3 +1,5 @@
+.. _sec_example:
+
 Minimal example
 ===============
 
@@ -14,7 +16,7 @@ Here, we can notice multiple notable things:
 #. Definitions of arguments are placed before the script body.
    From Bash point of view, they are commented out, so the "template" can be a syntactically valid script.
 
-#. ...
+#. You access the values of argument ``foo-bar`` as ``$_ARG_FOO_BAR`` etc. (this is covered more in-depth in :ref:`parsing_results`).
 
 So let's try the script in action! Let's see what happens when we pass the -h option:
 

doc/guide.rst

@@ -1,5 +1,7 @@
-Declaring arguments
-===================
+Template writing guide
+======================
+
+This section tells you how to write templates, the next one is about ``argbash.sh`` invocation.
 
 Definitions
 -----------
@@ -184,6 +186,8 @@ The macro doesn't take any parameters.
   
    ARGBASH_GO
 
+.. _parsing_results:
+
 Using parsing results
 +++++++++++++++++++++
 
@@ -198,3 +202,4 @@ The argument name is transliterated like this:
 #. Boolean arguments have values either ``on`` or ``off``.
 
    If (a boolean argument) ``--verbose`` is passed, value of ``_ARG_VERBOSE`` is set to ``on``.
+

doc/index.rst

@@ -38,7 +38,7 @@ So, let's say that we would like a script that produces the following help messa
 .. literalinclude:: _static/minimal-output-help.txt
    :start-after: minimal.sh
 
-Then, it means that we need following arguments
+Then, it means that we need following arguments:
 
 * One mandatory positional argument.
   (In other words, an argument that must be passed and that is not preceeded by options such as ``--foo``, ``-f``.)
@@ -55,7 +55,7 @@ Therefore, we write this to the template:
    :language: bash
    :end-before: needed because of Argbash
 
-The body of the script is trivial, but note that it is enclosed in square brackets.
+The body of the script (that follows the template) is trivial, but note that it is enclosed in a pair of square brackets.
 They are "hidden" in comments, but still, they have to be there.
 
 .. literalinclude:: ../resources/examples/minimal.m4
@@ -78,6 +78,11 @@ Now we launch it and the output is good!
    Positional arg value: posi-tional
    Optional arg --option value: opt-ional
 
+.. note::
+
+   If something still isn't totally clear, take look at the :ref:`sec_example` section.
+
+.. _limitations:
 
 Limitations
 +++++++++++

doc/install.rst

@@ -36,6 +36,8 @@ The main Makefile
 
 The ``Makefile`` in the ``resources`` folder can do many things:
 
+.. _install:
+
 Installation
 ++++++++++++
 

doc/usage.rst

@@ -1,67 +1,93 @@
-Usage
-=====
+Argbash invocation
+==================
 
-Layout
-------
+So, you have a template and now it is time to (re)generate a shell script from it!
 
-Separate file for parsing
-+++++++++++++++++++++++++
+File layout
+-----------
+
+You have three options here, they are sorted by the estimated preference: 
+
+#. One file with both parsing code and script body.
+
+   This is a both simple and functional approach.
+
+#. Two files --- one for the parsing code and one for the script body, both taken care of by ``Argbash``.
 
-This is really easy.
-Just place the directives in the file behind comments and then run the ``argbash.sh`` with the ``--standalone`` argument.
+   This is more suitable for people that prefer to keep things tidy, you can have the parsing code separate and included in the script at run-time.
+   However, ``Argbash`` can assist you with that.
+
+#. Same as the above, just without ``Argbash`` assistance.
+
+   You want to take this path if your script has a non-matching square brackets problem (see :ref:`limitations`).
+   This is very unlikely.
+
+.. note::
+
+   We assume that you have installed (see :ref:`install`) the ``argbash.sh``, so it is available as a command ``argbash``.
+   If it is not the case, you just have to substitute ``argbash`` by direct invocation of ``bin/argbash.sh``.
 
 Parsing code and script body together
 +++++++++++++++++++++++++++++++++++++
 
-This requires some trivial adjustments to your script.
+Assuming that you have created a template file ``my-template.m4``, you simply run ``argbash`` over the script [*]_:
 
-#. Add Argbash definitions to the script so they come before the script body.
-   Let's say that the file is called ``my-template.m4`` (the extension [*]_ is not important in itself). 
-   
-   .. note::
+::
+    
+   argbash my-template.m4 -o my-script.sh
 
-      This one is just a recommendation, but don't do othewise if you don't have deep understanding of what's going on.
+If you want to regenerate a new version of ``my-script.sh`` after you have modified its template section, you can run
 
-   Definitions are described in the Argbash API section, include them in a form as shell comments like this:
+::
+    
+   argbash my-script.sh -o my-script.sh
 
-   ::
+as the script can deal with input and output being the same file.
 
-      # ARG_POSITIONAL_SINGLE([filename])
-      # ARG_OPTIONAL_SINGLE([unit], u, [What unit we accept (b for bytes, k for kilobytes, M for megabytes)], b)
-      # ARG_VERSION([echo $0 v0.1])
-      # ARG_OPTIONAL_BOOLEAN(verbose)
-      # ARG_HELP
-      # ARGBASH_GO
+.. [*] ``m4`` is the extension used for the ``M4`` language, but we use the ``m4sugar`` extension built on top of it).
 
-#. Add this comment before the script body (it is a commented opening square bracket, the note is optional):
+Separate file for parsing with assistance
++++++++++++++++++++++++++++++++++++++++++
 
-   ::
+You have two files, let's say it is a ``my-parsing.m4`` and ``my-script.sh``.
+The ``my-parsing.m4`` file contains just the template section of ``my-script.sh``.
+Then, you add a very small template code to ``my-script.sh`` at the beginning:
 
-      # [ note: <--- this has to be here because of Argbash
+.. code-block:: bash
 
-   and another one (closing square bracket):
+    # DEFINE_SCRIPT_DIR
+    # INCLUDE_PARSING_CODE([my-parsing.sh])
+    # ARGBASH_GO
+    
+    # [ <-- needed because of Argbash
+    
+    # HERE GOES THE SCRIPT BODY
+    
+    # ] <-- needed because of Argbash
 
-   ::
+i.e. you add thos three lines with definitions and you enclose the script in square brackets.
 
-      # ] note: <--- this has to be here because of Argbash
+Finally, you just make sure that ``my-script.sh`` and ``my-parsing.m4`` are next to each other and run
 
-#. Run the ``argbash.sh`` over the script:
+::
 
-   ::
-    
-      bin/argbash.sh my-template.m4 -o my-script.sh
+   argbash my-script.sh -o my-script.sh
 
-Then, if you do some script development and you decide to add an option or remove one:
+which finds ``my-parsing.m4`` (it would find ``my-parsing.sh`` too) and generates new ``my-parsing.sh`` and ``my-script.sh`` that you can use right away.
 
-4. Forget about the template, edit the script --- declarations are preserved in there.
-   Obtain the updated version by re-running ``argbash.sh`` over ``my-script.sh``:
+Separate file for parsing
++++++++++++++++++++++++++
 
-   ::
-    
-      bin/argbash.sh my-script.sh -o my-script-new.sh
+If you want/have to take care of including the parsing code yourself, just make sure you do it in the script:
 
-   If you compare the two, you should find out that it works quite well and that the ``my-script-new.sh`` does what it is supposed to do and that it is by no means cluttered.
+.. code-block:: bash
 
-.. [*] ``m4`` is the extension used for the ``M4`` language, but we use the ``m4sugar`` extension built on top of it).
+    source $(dirname $0)/my-parsing.sh
+    
+    # HERE GOES THE SCRIPT BODY
+
+Then, you just generate ``my-parsing.sh`` using ``--standalone`` option:
 
+::
 
+   argbash my-parsing.m4 -o my-parsing.sh

resources/Makefile

@@ -12,6 +12,7 @@ ROOT = /
 
 GENPARSE = ../bin/argbash.sh
 EXAMPLES = \
+	examples/minimal.sh \
 	examples/simple.sh \
 	examples/simple-standalone.sh \
 	$(NUL)
@@ -84,7 +85,7 @@ version:
 	touch $(M4_SRC)
 
 release: version $(GENPARSE) examples check
-	sed -i "1s/([-0-9]+)/($$(date -I))/ $(CHANGELOG)
+	sed -i "1s/([-0-9]+)/($$(date -I))/" $(CHANGELOG)
 
 tag:
 	git tag $(shell cat ../src/version) -s -m 'Version release' master

resources/examples/minimal.m4

@@ -1,6 +1,6 @@
 #!/bin/bash
 
-# ARG_POSITIONAL_SINGLE([positional-arg])
+# ARG_POSITIONAL_SINGLE([positional-arg], [Positional arg description])
 # ARG_OPTIONAL_SINGLE([option], o, [A option with short and long flags and default], b)
 # ARG_OPTIONAL_BOOLEAN([verbose], , [A boolean option with long flag (and implicit default: off)], )
 # ARG_VERSION([echo $0 v0.1])

resources/examples/minimal.sh

@@ -1,25 +1,26 @@
 #!/bin/bash
 
-# ARG_POSITIONAL_SINGLE([positional-arg])
+# ARG_POSITIONAL_SINGLE([positional-arg],[Positional arg description])
 # ARG_OPTIONAL_SINGLE([option],[o],[A option with short and long flags and default],[b])
 # ARG_OPTIONAL_BOOLEAN([verbose],[],[A boolean option with long flag (and implicit default: off)],[])
 # ARG_VERSION([echo $0 v0.1])
 # ARG_HELP([This is a minimal demo of Argbash potential])
 # ARGBASH_GO()
 # needed because of Argbash --> m4_ignore([
-### START OF CODE GENERATED BY ARGBASH v1.0.0 one line above ###
-# THE DEFAULTS INITIALIZATION
-_ARG_OPTION=b
+### START OF CODE GENERATED BY ARGBASH v1.1.0 one line above ###
+# THE DEFAULTS INITIALIZATION --- POSITIONALS
+# THE DEFAULTS INITIALIZATION --- OPTIONALS
+_ARG_OPTION="b"
 _ARG_VERBOSE=off
 
 # THE PRINT HELP FUNCION
 function print_help
 {
 	echo "This is a minimal demo of Argbash potential"
 	echo "Usage: $0 <positional-arg> [--option <arg>] [--(no-)verbose] [--version] [--help]"
-	echo -e "\t<positional-arg>: Positional arg"
-	echo -e "\t-o,--option: A option with short and long flags and default (default: 'b')"
-	echo -e "\t--verbose,--no-verbose: A boolean option with long flag (and implicit default: off) (default: 'off')"
+	echo -e "\t<positional-arg>: Positional arg description"
+	echo -e "\t-o,--option: A option with short and long flags and default (default: '""b""')"
+	echo -e "\t--verbose,--no-verbose: A boolean option with long flag (and implicit default: off) (default: '"off"')"
 	echo -e "\t-v,--version: Prints version"
 	echo -e "\t-h,--help: Prints help"
 }
@@ -47,15 +48,14 @@ do
 			;;
 		*)
 		    	POSITIONALS+=("$1")
-		    	# unknown option
 			;;
 	esac
 	shift
 done
 
 POSITIONAL_NAMES=('_ARG_POSITIONAL_ARG' )
 test ${#POSITIONALS[@]} -lt 1 && { ( echo "FATAL ERROR: Not enough positional arguments."; print_help ) >&2; exit 1; }
-test ${#POSITIONALS[@]} -gt 1 && { ( echo "FATAL ERROR: There were spurious positional arguments."; print_help ) >&2; exit 1; }
+test ${#POSITIONALS[@]} -gt 1 && { ( echo "FATAL ERROR: There were spurious positional arguments --- we expect at most 1."; print_help ) >&2; exit 1; }
 for (( ii = 0; ii <  ${#POSITIONALS[@]}; ii++))
 do
 	eval "${POSITIONAL_NAMES[$ii]}=\"${POSITIONALS[$ii]}\""

resources/examples/simple-standalone.sh

@@ -7,19 +7,20 @@
 # ARG_HELP()
 # ARGBASH_GO()
 # needed because of Argbash --> m4_ignore([
-### START OF CODE GENERATED BY ARGBASH v1.0.0 one line above ###
-# THE DEFAULTS INITIALIZATION
-_ARG_UNIT=b
+### START OF CODE GENERATED BY ARGBASH v1.1.0 one line above ###
+# THE DEFAULTS INITIALIZATION --- POSITIONALS
+# THE DEFAULTS INITIALIZATION --- OPTIONALS
+_ARG_UNIT="b"
 _ARG_VERBOSE=off
 
 # THE PRINT HELP FUNCION
 function print_help
 {
 	echo "Usage: $0 <filename> [--unit <arg>] [--version] [--(no-)verbose] [--help]"
-	echo -e "\t<filename>: Positional arg"
-	echo -e "\t-u,--unit: What unit we accept (b for bytes, k for kilobytes, M for megabytes) (default: 'b')"
+	echo -e "\t<filename>: "
+	echo -e "\t-u,--unit: What unit we accept (b for bytes, k for kilobytes, M for megabytes) (default: '""b""')"
 	echo -e "\t-v,--version: Prints version"
-	echo -e "\t--verbose,--no-verbose:  (default: 'off')"
+	echo -e "\t--verbose,--no-verbose:  (default: '"off"')"
 	echo -e "\t-h,--help: Prints help"
 }
 # THE PARSING ITSELF
@@ -46,15 +47,14 @@ do
 			;;
 		*)
 		    	POSITIONALS+=("$1")
-		    	# unknown option
 			;;
 	esac
 	shift
 done
 
 POSITIONAL_NAMES=('_ARG_FILENAME' )
 test ${#POSITIONALS[@]} -lt 1 && { ( echo "FATAL ERROR: Not enough positional arguments."; print_help ) >&2; exit 1; }
-test ${#POSITIONALS[@]} -gt 1 && { ( echo "FATAL ERROR: There were spurious positional arguments."; print_help ) >&2; exit 1; }
+test ${#POSITIONALS[@]} -gt 1 && { ( echo "FATAL ERROR: There were spurious positional arguments --- we expect at most 1."; print_help ) >&2; exit 1; }
 for (( ii = 0; ii <  ${#POSITIONALS[@]}; ii++))
 do
 	eval "${POSITIONAL_NAMES[$ii]}=\"${POSITIONALS[$ii]}\""