Updated documentation and Makefiles

Author: matejak

.gitignore

@@ -4,3 +4,5 @@
 
 tests/regressiontests/test-standalone.sh
 tests/regressiontests/test.sh
+
+doc/_build

ChangeLog

@@ -6,3 +6,4 @@ New features:
 * Support for positional args with default values.
 * "Intelligent" shell auto-quoting of macro arguments.
 * Improvement of standalone parsing code mode.
+

doc/Makefile.pieces

@@ -2,13 +2,14 @@ DOCDIR ?= .
 RESOURCES ?= ../resources
 
 MINIMAL = $(RESOURCES)/examples/minimal.sh
+STATICDIR = _static
 
 NUL =
 
 PIECES = \
-	minimal-output-help.txt \
-	minimal-output-foobar.txt \
-	minimal-output-noverbose.txt \
+	$(STATICDIR)/minimal-output-help.txt \
+	$(STATICDIR)/minimal-output-foobar.txt \
+	$(STATICDIR)/minimal-output-noverbose.txt \
 	$(NUL)
 
 pieces: $(PIECES)
@@ -21,15 +22,15 @@ define CMD_OUT
 	$< $(FLAGS) | sed -e 's/^/    /' >> $@
 endef
 
-minimal-output-help.txt: $(MINIMAL)
+$(STATICDIR)/minimal-output-help.txt: $(MINIMAL)
 	$(eval FLAGS := -h)
 	$(CMD_OUT)
 
-minimal-output-foobar.txt: $(MINIMAL)
+$(STATICDIR)/minimal-output-foobar.txt: $(MINIMAL)
 	$(eval FLAGS := foo -o bar --verbose)
 	$(CMD_OUT)
 
-minimal-output-noverbose.txt: $(MINIMAL)
+$(STATICDIR)/minimal-output-noverbose.txt: $(MINIMAL)
 	$(eval FLAGS := foo -o bar)
 	$(CMD_OUT)
 

doc/_static/minimal-output-foobar.txt

@@ -0,0 +1,6 @@
+::
+
+    ../resources/examples/minimal.sh foo -o bar --verbose
+
+    Positional arg value: foo
+    Optional arg --option value: bar

doc/_static/minimal-output-help.txt

@@ -0,0 +1,11 @@
+::
+
+    ../resources/examples/minimal.sh -h
+
+    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
+    	-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
+    	-h,--help: Prints help

doc/_static/minimal-output-noverbose.txt

@@ -0,0 +1,5 @@
+::
+
+    ../resources/examples/minimal.sh foo -o bar
+
+    Not telling anything, verbose mode is off

doc/example.rst

@@ -18,15 +18,15 @@ Here, we can notice multiple notable things:
 
 So let's try the script in action! Let's see what happens when we pass the -h option:
 
-.. include:: minimal-output-help.txt
+.. include:: _static/minimal-output-help.txt
 
 OK, so it seems that passing it one (mandatory) positional arg will do the trick:
 
-.. include:: minimal-output-noverbose.txt
+.. include:: _static/minimal-output-noverbose.txt
 
 Oops, we have forgot to turn verbose output on! Let's fix that...
 
-.. include:: minimal-output-foobar.txt
+.. include:: _static/minimal-output-foobar.txt
 
 Closer look
 -----------

doc/index.rst

@@ -1,6 +1,19 @@
 Argbash documentation
 =====================
 
+Argbash
+-------
+
+``Argbash`` (`<https://github.com/matejak/argbash>`_) is a ``Bash`` code generator that can assist you in writing scripts that accept arguments.
+You declare arguments that your script should use in few lines and then, you run ``Argbash`` on those declarations to get a parsing code that can be used on all platforms that have ``Bash`` (Linux, OSX, MS Windows, ...).
+``Argbash`` is free software, you are free to use it, share it, modify it and share the modifications with the world, since it is published under the 3-clause BSD linense.
+
+:Authors:
+  - `Matěj Týč <https://github.com/matejak>`_
+
+:Copyright:
+  - 2014-2015, Matěj Týč
+
 Quickstart
 ----------
 
@@ -16,27 +29,55 @@ You need:
 * ``bash>=3.0``
 * ``autoconf>=2.64`` (Argbash makes use of the ``autom4te`` utility)
 
-
 Writing a template
 ++++++++++++++++++
 
 Let's stick with a testing script that accepts some arguments and then it just prints them out.
 So, let's say that we would like a script that produces the following help message:
 
+.. literalinclude:: _static/minimal-output-help.txt
+   :start-after: minimal.sh
+
+Then, it means that we need following arguments
 
-Then, it means that we need 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``.)
+* Four optional arguments:
 
-*
+  * ``--option`` that accepts one value,
+  * ``--verbose`` that doesn't accept any value --- it either is or isn't specified,
+  * ``--version`` that also doesn't accept any value and the program is supposed just to print its version and quit afterwards, and finally
+  * ``--help`` that prints a help message and also quits.
 
 Therefore, we write this to the template:
 
+.. literalinclude:: ../resources/examples/minimal.m4
+   :language: bash
+   :end-before: needed because of Argbash
+
 The body of the script is trivial, but note that it is enclosed in square brackets.
 They are "hidden" in comments, but still, they have to be there.
 
+.. literalinclude:: ../resources/examples/minimal.m4
+   :language: bash
+   :start-after: ARGBASH_GO
 
 We generate the script from the template:
 
-The output is good!
+::
+
+   bin/argbash.sh script.m4 -o script.sh 
+
+
+Now we launch it and the output is good!
+
+::
+
+   ./script.sh posi-tional -o opt-ional --verbose
+
+   Positional arg value: posi-tional
+   Optional arg --option value: opt-ional
+
 
 Limitations
 +++++++++++
@@ -48,9 +89,9 @@ Limitations
 #. The delimiter between optional argument name and value is whitespace, ``=`` is not supported.
    Create an issue if this disturbs you, it should be quite easy to implement.
 #. Clustering of short arguments (e.g. using ``-xzf`` instead of ``-x -z -f``) is not supported.
-#. The square brackets in your script have to match (i.e. every opening square bracket ``[`` should be followed at some point by a closing square bracket ``]``)
-   This limitation does not apply if you have the argument parsing code in a separate file.
-
+#. The square brackets in your script should match (i.e. every opening square bracket ``[`` should be followed at some point by a closing square bracket ``]``).
+   More precisely, the number of closing square brackets ``]`` must not exceed the number of opening ``[``.
+   This limitation does apply to files that are processed by ``argbash.sh`` --- you are fine if you have the argument parsing code in a separate file and you don't use the ``INCLUDE_PARSING_CODE``.
 
 Index
 -----

resources/Makefile

@@ -49,6 +49,7 @@ bootstrap:
 examples: $(EXAMPLES)
 
 check: unittests regressiontests
+	$(MAKE) tests-clean
 
 unittests:
 	autom4te -l m4sugar -I ../src/ ../tests/unittests/list.m4

resources/packages/Makefile

@@ -1,19 +1,19 @@
 VERSION = $(shell cat ../../src/version)
 
-SOURCE = argbash-$(VERSION).tar.gz
+SOURCE = build/argbash-$(VERSION).tar.gz
 
-LICENSE: ../../LICENSE
+build/LICENSE: ../../LICENSE | build
 	cp $< $@
 
-md5-LICENSE: LICENSE
+build/md5-LICENSE: build/LICENSE | build
 	md5sum $< | cut -f 1 -d ' ' > $@
 
 source: $(SOURCE)
 
-$(SOURCE):
+$(SOURCE): | build
 	wget -O $@ https://github.com/matejak/argbash/archive/$(VERSION).tar.gz
 
-md5-$(VERSION): $(SOURCE)
+build/md5-$(VERSION): $(SOURCE)
 	md5sum $< | cut -f 1 -d ' ' > $@
 
 define substitute =
@@ -23,16 +23,22 @@ cat $< \
 	| sed -e 's/@PKGREL@/$(PKGREL)/' \
 	| sed -e 's/@DESC@/Bash argument parsing code generator/' \
 	| sed -e 's|@URL@|https://github.com/matejak/argbash|' \
-	| sed -e 's/@MD5SUM@/$(shell cat md5-$(VERSION))/' \
-	| sed -e 's/@LIC_MD5UM@/$(shell cat md5-LICENSE)/' \
+	| sed -e 's/@MD5SUM@/$(shell cat $(word 3,$+))/' \
+	| sed -e 's/@LIC_MD5UM@/$(shell cat $(word 4,$+))/' \
 	> $@
 endef
 
-PKGBUILD: arch/PKGBUILD $(SOURCE) md5-$(VERSION) md5-LICENSE
+build:
+	mkdir $@
+
+build/PKGBUILD: arch/PKGBUILD $(SOURCE) build/md5-$(VERSION) build/md5-LICENSE
 	$(substitute)
 
-archlinux: PKGBUILD
-	makepkg -f
+archlinux: build/PKGBUILD
+	cd build && makepkg -f
 
-SPEC: rpm/SPEC $(SOURCE)
+build/SPEC: rpm/SPEC $(SOURCE)
 	$(substitute)
+
+clean:
+	$(RM) build/*

tests/regressiontests/Makefile

@@ -9,6 +9,16 @@ TESTS = \
 	args-salone \
 	$(NUL)
 
+# test-salone is side-effect of call-salone
+SCRIPTS = \
+	$(TESTDIR)/test.sh \
+	$(TESTDIR)/test2.sh \
+	$(TESTDIR)/test-standalone.sh \
+	$(TESTDIR)/test-standalone2.sh \
+	$(TESTDIR)/call-salone.sh \
+	$(TESTDIR)/test-salone.sh \
+	$(NUL)
+
 regressiontests: $(TESTS)
 
 stability: $(TESTDIR)/test.sh $(TESTDIR)/test2.sh
@@ -39,3 +49,6 @@ args-salone: $(TESTDIR)/call-salone.sh
 
 stability-salone: $(TESTDIR)/test-standalone.sh $(TESTDIR)/test-standalone2.sh
 	diff -q $< $(word 2,$^)
+
+tests-clean:
+	$(RM) $(SCRIPTS)