# HG changeset patch
# User Paul Boddie <paul@boddie.org.uk>
# Date 1373986640 -7200
# Node ID dfa50d4aba08ff94c88dc17059de55caf6dab602
# Parent  895da88b64038d46f3af65316dab5c88d6296944
Added some documentation for the software.

diff -r 895da88b6403 -r dfa50d4aba08 README.txt
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/README.txt	Tue Jul 16 16:57:20 2013 +0200
@@ -0,0 +1,132 @@
+Introduction
+------------
+
+The MoinForms extension for MoinMoin provides a way of defining Web forms in
+wiki pages that support elementary and extensible validation, replicated form
+sections, and a framework for handling submitted forms. Each form is defined
+using conventional wiki syntax together with macros that produce HTML form
+elements and is encapsulated using the MoinMoin parsed region syntax. Thus,
+each form appears as an integrated part of the page in which it is defined.
+
+To handle submitted forms, MoinForms employs handler actions that support
+basic manipulation and validation actions, along with the storage of submitted
+form data, and such actions can be extended to perform enhanced validation and
+other submission-related actions.
+
+Installation
+------------
+
+To install MoinForms, consider using the moinsetup tool. See the "Recommended
+Software" section below for more information.
+
+With moinsetup and a suitable configuration file, the installation is done as
+follows with $MFDIR referring to the MoinForms distribution directory
+containing this README.txt file:
+
+  python moinsetup.py -f moinsetup.cfg -m install_extension_package $MFDIR
+  python moinsetup.py -f moinsetup.cfg -m install_actions $MFDIR/actions
+  python moinsetup.py -f moinsetup.cfg -m install_macros $MFDIR/macros
+  python moinsetup.py -f moinsetup.cfg -m install_parsers $MFDIR/parsers
+
+The first command above uses the setup.py script provided as follows:
+
+  python setup.py install --prefix=path-to-moin-prefix
+
+The second, third and fourth commands install the actions, macros and parsers
+respectively.
+
+Additional Installation Tasks
+-----------------------------
+
+See the "Dependencies" section below for details of the software featured in
+this section.
+
+MoinForms depends on MoinSupport having been installed. This is because a lot
+of useful functionality common to a number of MoinMoin extensions now resides
+in the MoinSupport distribution.
+
+The following command can be run with $MSDIR referring to the MoinSupport
+distribution directory:
+
+  python moinsetup.py -f moinsetup.cfg -m install_extension_package $MSDIR
+
+Useful Pages
+------------
+
+The pages directory contains a selection of useful pages using a syntax
+appropriate for use with MoinMoin 1.6 or later. These pages can be created
+through the wiki and their contents copied in from each of the files. An
+easier installation method is to issue the following commands:
+
+  python moinsetup.py -f moinsetup.cfg -m make_page_package $MFDIR/pages pages.zip
+  python moinsetup.py -f moinsetup.cfg -m install_page_package pages.zip
+
+You may need to switch user in order to have sufficient privileges to copy the
+page package into the wiki. For example:
+
+  sudo -u www-data python moinsetup.py -f moinsetup.cfg -m install_page_package pages.zip
+
+Using MoinForms
+---------------
+
+The HelpOnMoinForms page provided in the pages directory provides working
+examples of the macros used to produce HTML form elements and the regions that
+encapsulate such elements to make functioning HTML forms. Adding a form to a
+page is as simple as the following example taken from the HelpOnMoinForms
+page:
+
+{{{#!form fragment=exampleform finishing=finish
+
+|| '''Name'''    || <<FormField(name,ExampleFormDict)>>    ||
+|| '''Address''' || <<FormField(address,ExampleFormDict)>> ||
+|| '''Country''' || <<FormField(country,ExampleFormDict)>> ||
+||               || <<FormField(finish,ExampleFormDict,label=Finish)>> ||
+
+}}}
+
+The ExampleFormDict page referenced in the above example is also provided in
+the pages directory and is used to provide details for the named fields in the
+form. There is also an ExampleFormCountryDict page which provides a choice of
+countries for the country field; this is referenced by the ExampleFormDict
+page.
+
+In short, a form references various definitions which in turn can be built
+upon other definitions, and thus a kind of common vocabulary for form fields
+can be constructed.
+
+Recommended Software
+--------------------
+
+See the "Dependencies" section below for essential software.
+
+The moinsetup tool is recommended for installation since it aims to support
+all versions of MoinMoin that are supported for use with this software.
+
+See the following page for information on moinsetup:
+
+http://moinmo.in/ScriptMarket/moinsetup
+
+Contact, Copyright and Licence Information
+------------------------------------------
+
+See the following Web page for more information about this work:
+
+http://moinmo.in/ParserMarket/MoinForms
+
+The author can be contacted at the following e-mail address:
+
+paul@boddie.org.uk
+
+Copyright and licence information can be found in the docs directory - see
+docs/COPYING.txt and docs/LICENCE.txt for more information.
+
+Dependencies
+------------
+
+MoinForms has the following basic dependencies:
+
+Packages                    Release Information
+--------                    -------------------
+
+MoinSupport                 Tested with 0.4
+                            Source: http://hgweb.boddie.org.uk/MoinSupport