Merge remote-tracking branch 'origin/ghini-1.0-dev' into ghini-1.0-dev

doc/administration.rst

@@ -2,7 +2,7 @@ Database Administration
 --------------------------
 
 If you are using a real DBMS to hold your botanic data, then you need do
-something about database administration. While database adnimistration is
+something about database administration. While database administration is
 far beyond the scope of this document, we make our users aware of it.
 
 SQLite
@@ -17,7 +17,7 @@ In Windows it is somewhere in your ``AppData`` directory, most likely in
 ``AppData\Roaming\Bauble``. Do keep in mind that Windows does its best to
 hide the ``AppData`` directory structure to normal users. 
 
-The fastest way to open it is with the file explorer: type ``%APPDATA%` and
+The fastest way to open it is with the file explorer: type ``%APPDATA%`` and
 hit enter.
 
 MySQL

doc/building.rst

@@ -96,15 +96,15 @@ project. Within this project we have components, each of which corresponds
 to a branch of a repository on github. Each component accepts translations
 in several languages.
 
-=============== =========================== ==================
-component       repository                  branch
-=============== =========================== ==================
-desktop-1.0     ghini.desktop               ghini-1.0-dev
-desktop-1.1     ghini.desktop               ghini-1.1-dev
-docs-1.0        ghini.desktop-docs.i18n     ghini-1.0-dev
-docs-1.1        ghini.desktop-docs.i18n     ghini-1.1-dev
-web-1.2         ghini.web                   master
-=============== =========================== ==================
+================== =========================== ==================
+component          repository                  branch
+================== =========================== ==================
+Desktop 1.0        ghini.desktop               ghini-1.0-dev
+Desktop 1.1        ghini.desktop               ghini-1.1-dev
+Documentation 1.0  ghini.desktop-docs.i18n     ghini-1.0-dev
+Documentation 1.1  ghini.desktop-docs.i18n     ghini-1.1-dev
+Web 1.2            ghini.web                   master
+================== =========================== ==================
 
 To update the ``po`` files relative to the *software*, you set the working
 directory to the root of your checkout of *ghini.desktop*, and you run the

doc/imex.rst

@@ -3,7 +3,7 @@ Importing and Exporting Data
 
 Although Ghini can be extended through plugins to support alternate
 import and export formats, by default it can only import and export
-comma seperated values files or CSV.
+comma separated values files or CSV.
 
 There is some support for exporting to the Access for Biological
 Collections Data it is limited.
@@ -23,7 +23,7 @@ previously exported from Ghini. It is possible to import any CSV file
 but that is more advanced that this doc will cover.
 
 To import CSV files into Ghini select
-:menuselection:`Tools-->Export-->Comma Seperated Values` from the
+:menuselection:`Tools-->Export-->Comma Separated Values` from the
 menu.
 
 After clicking OK on the dialog that ask if you are sure you know what
@@ -35,7 +35,7 @@ Exporting to CSV
 ----------------
 
 To export the Ghini data to CSV select
-:menuselection:`Tools-->Export-->Comma Seperated Values` from the menu.
+:menuselection:`Tools-->Export-->Comma Separated Values` from the menu.
 
 This tool will ask you to select a directory to export the CSV data.
 All of the tables in Ghini will be exported to files in the format

doc/installing.rst

@@ -4,20 +4,28 @@ Installation
 ghini.desktop is a cross-platform program and it will run on unix machines
 like GNU/Linux and MacOSX, as well as on Windows.
 
-To install Ghini first requires that you install its dependencies that
-cannot be installed automatically.  These include virtualenv, PyGTK
-and pip. Python and GTK+, you probably already have. As long as you have
-these packages installed then Ghini should be able to install the rest of
-its dependencies by itself.
+Ghini is maintained by very few people, who focus on enhancing its
+functional parts, more than on writing fancy installers. Instead of several
+native installers we offer a single cross-platform installation procedure.
+This has a few big advantages which you will learn to appreciate as we go.
 
-.. note:: If you follow these installation steps, you will end with Ghini
-          running within a Python virtual environment, all Python
-          dependencies installed locally, non conflicting with any other
-          Python program you may have on your system.
+The installation is based on running a script.
 
-          if you later choose to remove Ghini, you simply remove the
-          virtual environment, which is a directory, with all of its
-          content.
+* The GNU/Linux script takes care of everything, from dependecies to
+  installation for all users.
+* The Windows script needs you to first install a couple things.
+* On MacOSX we use the same script as on GNU/Linux. Since OSX has no default
+  package manager, we install one and we use it before we start the script.
+
+Following our installation procedure, you will end with Ghini running within
+a Python virtual environment, all Python dependencies installed locally, non
+conflicting with any other Python program you may have on your system.
+
+Dependencies that don't fit in a Python virtual environment are: Python,
+virtualenv, GTK+, and PyGTK. Their installation varies per platform.
+
+If you later choose to remove Ghini, you simply remove the virtual
+environment, which is a directory, with all of its content.
 
 Installing on GNU/Linux
 --------------------------
@@ -51,7 +59,7 @@ Open a shell terminal window, and follow these instructions.
      https://raw.githubusercontent.com/Ghini/ghini.desktop/master/scripts/devinstall.sh
 
    Please note that the script will not help you install any extra database
-   connector. This is not strictly necessary and you can do it at any later step.
+   connector. This is not strictly necessary and you can do it at any later moment.
 
    If the script ends without error, you can now start ghini::
 
@@ -174,7 +182,7 @@ The installation steps on Windows:
 #. download and install ``git`` (comes with a unix-like ``sh`` and includes
    ``vi``) from::
 
-   https://git-scm.com/download/win
+     https://git-scm.com/download/win
    
    `Direct link to download git`_
 
@@ -185,7 +193,7 @@ The installation steps on Windows:
 
 #. download and install Python 2.x (32bit) from::
 
-   http://www.python.org
+     http://www.python.org
 
    `Direct link to download Python`_
 
@@ -200,7 +208,7 @@ The installation steps on Windows:
 #. download ``pygtk`` from the following source. (this requires 32bit
    python). be sure you download the "all in one" version::
 
-   http://ftp.gnome.org/pub/GNOME/binaries/win32/pygtk/
+     http://ftp.gnome.org/pub/GNOME/binaries/win32/pygtk/
 
    `Direct link to download PyGTK`_
 

doc/report.rst

@@ -27,7 +27,7 @@ The template generator will use the same file extension as the
 template which should indicate the type of output the template with
 create.  For example, to generate an HTML page from your template you
 should name the template something like `report.html`.  If the template
-will generate a comma seperated value file you should name the
+will generate a comma separated value file you should name the
 template `report.csv`.
 
 The template will receive a variable called `values` which will

doc/runme.sh

@@ -4,8 +4,8 @@
 LANGUAGES='ar cs da de es fr hi it pl pt_BR ru sv uk zh jp'
 
 # configure locations, don't incude the final slash
-SOURCEDOCDIR=~/Local/github/Ghini/ghini.desktop/doc
-CHECKOUTDIR=~/Local/github/Ghini/ghini.desktop-docs.i18n
+SOURCEDOCDIR=$HOME/Local/github/Ghini/ghini.desktop/doc
+CHECKOUTDIR=$HOME/Local/github/Ghini/ghini.desktop-docs.i18n
 ALLPODIR=$CHECKOUTDIR/po
 
 # "all remaining actions must be run from the doc dir"
@@ -46,7 +46,7 @@ do
     do
         ln -s doc.po $(basename $i .rst).po 2>/dev/null
     done
-    cd $PODIR
+    cd $ALLPODIR
     ln -s ../locale/$l/LC_MESSAGES/doc.po $l.po 2>/dev/null
 done
 

doc/searching.rst

@@ -222,7 +222,32 @@ Select and/or next to the property name to choose how the clauses will be
 combined in the search query.
 
 When you are done building your query click OK to perform the search.
-
+
+At this point the Query Builder writes the query in the search entry, and
+executes it. You may now edit the string as if you had typed it
+yourself. Notice how the left hand side values are interpreted by the query
+builder and enclosed in single quotes if recognized as strings, left alone
+if they look like numbers or the two reserved words ``None`` and
+``Empty``. You may edit the query and insert quotes if you need them, eg if
+you need to literally look for the string ``Empty``.
+
+``None`` is the value of an empty field. It is not the same as the zero
+lenght string ``''`` nor the numeric ``0`` nor the boolean ``False`` nor the
+set ``Empty``, it indicates that the field has no value at all.
+
+``Empty`` is the empty set. Being it a set, it can be matched against sets
+(eg: plants of an accession, or accessions of a species), not against
+elements (eg: quantity of a plant or description of a location). However,
+the Query Builder does not let you choose a left hand side value stopping at
+a set, it expects you to select a field. Choose just any field: at the
+moment of producing the query, when the Query Builder meets a clause with
+right hand side value the literal string ``Empty``, it will drop the field
+name and let you compare the set on the left with ``Empty`` on the right.
+
+We have no literals ``False`` and ``True``. These are typed values, and the
+Query Builder does not know how to produce them. Instead of ``False`` type
+``0``, and instead of ``True`` type ``1``.
+
 
 Query Grammar
 ==================