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

doc/editing.rst

@@ -192,12 +192,13 @@ plants that are created.
 Pictures
 """"""""""""
 
-Just as almost all objects in the Ghini database can have *Notes*
-associated to them, Plants can have *Pictures*: next to the tab for Notes,
-the Plants editor contains an extra tab called "Pictures". You can associate
-as many pictures as you might need to a plant.
+Just as almost all objects in the Ghini database can have *Notes* associated
+to them, Plants and Species can also have *Pictures*: next to the tab for
+Notes, the Plant and the Species editors contain an extra tab called
+"Pictures". You can associate as many pictures as you might need to a plant
+and to a species object.
 
-When you associate a picture to a plant, the file is copied in the
+When you associate a picture to an object, the file is copied in the
 *pictures* folder, and a miniature (500x500) is generated and copied in the
 `thumbnails` folder inside of the pictures folder.
 
@@ -211,10 +212,27 @@ specified the details of your database connection. Again, you should make
 sure that the pictures root folder is shared with your file sharing service
 of choice.
 
-When a Plant in the current selection is highlighted, its pictures are
-displayed in the pictures pane, the pane left of the information pane. When
-an accession in the selection is highlighted, any picture associated to the
-plants in the highlighted accession are displayed in the pictures pane.
+When a Plant or a Species in the current selection is highlighted, its
+pictures are displayed in the pictures pane, the pane left of the
+information pane. When an Accession in the selection is highlighted, any
+picture associated to the plants in the highlighted accession are displayed
+in the pictures pane.
+
+In Ghini-1.0, pictures are special notes, with category "<picture>", and
+text the path to the file, relative to the pictures root folder.  In the
+Notes tab, Picture notes will show as normal notes, and you can edit them
+without limitations.
+
+A Plant is a physical object, so you associate to it pictures taken of that
+individual plant, taken at any relevant development stage of the plant,
+possibly helping its identification.
+
+Species are abstract objects, so you would associate to it pictures showing
+the characteristic elements of the species, so it makes sense to associate a
+flora illustration to it. You can also do that by reference: go to the Notes
+tab, add a note and specify as category "<picture>", then in the text field
+you type the URL for the illustration of your choice.
+
 
 Locations
 ---------

doc/imex.rst

@@ -62,14 +62,81 @@ This feature is still under development.
 
 .. image:: images/screenshots/export-to-json.png
 
-when you activate this export tool, you are given the choice to specify what
-to export. You can use the current selection to limit the span of the
-export, or you can start at the complete content of a domain, to be chosen
-among Species, Accession, Plant.  
-
-Exporting *Species* will only export the complete taxonomic information in
-your database. *Accession* will export all your accessions plus all the
-taxonomic information it refers to: unreferred to taxa will not be
-exported. *Plant* will export all living plants (some accession might not be
-included), all referred to locations and taxa.
+when you activate this export tool, you are given the choice to
+specify what to export. You can use the current selection to
+limit the span of the export, or you can start at the complete
+content of a domain, to be chosen among Species, Accession,
+Plant.
+
+Exporting *Species* will only export the complete taxonomic
+information in your database. *Accession* will export all your
+accessions plus all the taxonomic information it refers to:
+unreferred to taxa will not be exported. *Plant* will export all
+living plants (some accession might not be included), all
+referred to locations and taxa.
+
+Importing from a Generic Database
+----------------------------------
+
+This functionality is the object of `issue #127
+<https://github.com/Ghini/ghini.desktop/issues/127>`_, for which
+we have no generic solution yet.
+
+If you're interested in importing data from some flat file
+(e.g.: Excel spreadsheet) or from any database, contact the
+developers.
+
+Importing a Pictures Collection
+----------------------------------
+
+We can consider a collection of plant pictures as a particular
+form of botanical database, in which each picture is clearly
+associated with one specific plant.
+
+Even without using a photo collection software, you can
+associate pictures to accessions by following one and the same
+clear rule when naming picture files.
+
+For example, ``2018.0020.1 (4) Epidendrum.jpg`` would be the
+name of the fourth picture for plant number 1 within accession
+2018.0020, identified to rank genus as an Epidendrum.
+
+The :menuselection:`Tools-->Import-->Pictures` functionality
+here described is meant for importing an ordered collection of
+plant pictures either to initialize a ghini database, or for
+periodically adding to it.
+
+Use :menuselection:`Tools-->Import-->Pictures` to activate this
+import tool.  Import goes in several steps: parameter
+definition; data revision and confirmation; the import step
+proper; finally review the import log.  At the first two steps
+you can confirm the data and go to the next step by clicking on
+the ``next`` button, or you can go back to the previous step by
+clicking on the ``prev`` button.  Once the import is done and
+you're reviewing the log, you can only either confirm —or abort—
+the whole transaction
+
+In the "parameter definition" pane you: select the directory
+from which you intend to import pictures; indicate whether to
+import pictures recursively; select or create a location which
+will be used as default location for new plants; inform the tool
+about the rule you've been following when naming picture files.
+
+.. image:: images/screenshots/import-picture-define.png
+
+In the "data revision" pane you are shown a table with as many
+rows as the pictures you are importing.  Each row holds as much
+information as the tool managed to extract from the picture
+name.  You can review the information, correct or confirm, and
+indicate whether or not the row should be imported.
+
+.. image:: images/screenshots/import-picture-review.png
+
+In the final "commit or rollback" pane you read the logs relative
+to your data import, and decide whether to keep them (commit
+them to the database), or undo them (rollback the transaction).
+
+When the Picture Collection importer creates or updates objects,
+it also sets a Note that you can use for selecting the objects
+involved in the import, and for reviewing if needed.