[gthumb] documented the importer

[Michael J. Chudobiak <mjc src gnome org>]

commit 94b7b3d412a54caabc08e70caf555e89b2f5b07c
Author: Michael J. Chudobiak <mjc avtechpulse com>
Date:   Fri Aug 13 12:28:11 2010 -0400

    documented the importer

 .../photo_importer/data/ui/photo-importer.ui       |    4 +-
 extensions/photo_importer/dlg-photo-importer.c     |   12 +++
 help/C/figures/import-pref-auto-folder.png         |  Bin 0 -> 21590 bytes
 help/C/figures/import-pref-custom-format.png       |  Bin 0 -> 30046 bytes
 help/C/figures/import.png                          |  Bin 0 -> 130886 bytes
 help/C/import.page                                 |   78 ++++++++++++++++++++
 help/C/rename-series.page                          |    2 +-
 help/Makefile.am                                   |    8 ++-
 8 files changed, 99 insertions(+), 5 deletions(-)
---
diff --git a/extensions/photo_importer/data/ui/photo-importer.ui b/extensions/photo_importer/data/ui/photo-importer.ui
index acfc783..1e110c3 100644
--- a/extensions/photo_importer/data/ui/photo-importer.ui
+++ b/extensions/photo_importer/data/ui/photo-importer.ui
@@ -280,7 +280,7 @@
               </packing>
             </child>
             <child>
-              <object class="GtkButton" id="button2">
+              <object class="GtkButton" id="help_button">
                 <property name="label">gtk-help</property>
                 <property name="visible">True</property>
                 <property name="can_focus">True</property>
@@ -306,7 +306,7 @@
     <action-widgets>
       <action-widget response="0">cancel_button</action-widget>
       <action-widget response="0">ok_button</action-widget>
-      <action-widget response="0">button2</action-widget>
+      <action-widget response="0">help_button</action-widget>
     </action-widgets>
   </object>
   <object class="GtkImage" id="image1">
diff --git a/extensions/photo_importer/dlg-photo-importer.c b/extensions/photo_importer/dlg-photo-importer.c
index 4b9fcc6..8704f55 100644
--- a/extensions/photo_importer/dlg-photo-importer.c
+++ b/extensions/photo_importer/dlg-photo-importer.c
@@ -197,6 +197,14 @@ ok_clicked_cb (GtkWidget  *widget,
 
 
 static void
+help_clicked_cb (GtkWidget  *widget,
+                 DialogData *data)
+{
+        show_help_dialog (GTK_WINDOW (data->dialog), "gthumb-importing");
+}
+
+
+static void
 update_sensitivity (DialogData *data)
 {
 	gboolean can_import;
@@ -600,6 +608,10 @@ dlg_photo_importer (GthBrowser *browser,
 			  "clicked",
 			  G_CALLBACK (close_dialog),
 			  data);
+        g_signal_connect (GET_WIDGET ("help_button"),
+                          "clicked",
+                          G_CALLBACK (help_clicked_cb),
+                          data);
 	g_signal_connect (data->source_list,
 			  "changed",
 			  G_CALLBACK (source_list_changed_cb),
diff --git a/help/C/figures/import-pref-auto-folder.png b/help/C/figures/import-pref-auto-folder.png
new file mode 100644
index 0000000..c054446
Binary files /dev/null and b/help/C/figures/import-pref-auto-folder.png differ
diff --git a/help/C/figures/import-pref-custom-format.png b/help/C/figures/import-pref-custom-format.png
new file mode 100644
index 0000000..cca7981
Binary files /dev/null and b/help/C/figures/import-pref-custom-format.png differ
diff --git a/help/C/figures/import.png b/help/C/figures/import.png
new file mode 100644
index 0000000..a2d927a
Binary files /dev/null and b/help/C/figures/import.png differ
diff --git a/help/C/import.page b/help/C/import.page
new file mode 100644
index 0000000..35ba821
--- /dev/null
+++ b/help/C/import.page
@@ -0,0 +1,78 @@
+<page xmlns="http://projectmallard.org/1.0/"; type="topic"
+id="gthumb-importing">
+  <info>
+    <link type="guide" xref="index#importing" />
+    <link type="topic" xref="gthumb-date-formats" />
+  </info>
+
+  <title>Importing From a Camera</title>
+
+  <p>On most systems, <app>gThumb</app> will automatically launch the 
+  import dialog when a digital camera is connected to the computer, 
+  or a memory card with photos is plugged into a card reader.
+  (It does this because it is registered as the default handler for
+  x-content/image-dcf and x-content/image-picturecd mime types.)</p>
+
+  <p>To manually launch the import dialog, use 
+  <guiseq><gui>File</gui><gui>Import From</gui><gui>Removable Device</gui></guiseq>.</p>
+
+  <figure>
+    <title>The Import Dialog</title>
+    <media type="image" mime="image/png" src="figures/import.png" />
+  </figure>
+  
+  <p>The import dialog shows thumbnails of the photos available on the
+  selected device. The user can select one of more photos using
+  normal keyboard or mouse techniques (for example, Ctrl+click to
+  add a photo to the selection, or click and drag the mouse over the
+  desired photos.) If no photos are explicitly selected, all will be imported.</p>
+
+  <p>Tags may optionally be associated with the imported photos, using the
+  <gui>Tags</gui> control below the thumbnail window. Click the 
+  drop-down control to see the predefined tags.</p>
+
+  <p>An event name may also be optionally associated with the photos.
+  This event name can be used to generate an automatic subfolder name
+  (possibly incorporating a date) as described below. For example, 
+  if the base destinator folder is "/photos", and you enter
+  "Wedding-Jennifer" in the <gui>Event</gui> field, you can configure 
+  generation of automatic subfolders like "/photos/2010-07-31, Wedding-Jennifer".</p>
+
+  <figure>
+    <title>Standard Date-Based Subfolders</title>
+    <media type="image" mime="image/png" src="figures/import-pref-auto-folder.png" />
+  </figure>
+
+  <p>As mentioned above, subfolders for imported photos can be automatically generated
+  based on event names and dates. This is enabled or disabled by clicking on the
+  destination foldername in the import dialog. This opens a second dialog, where
+  the base folder for imports may be selected (the <gui>Destination</gui> folder).
+  To generate automatic subfolders, select <gui>Automatic subfolder</gui>.</p>
+
+  <p>You can select either the <gui>File Date</gui> or the <gui>Current Date</gui> to
+  use as the basis for subfolder naming. (The <gui>File Date</gui> examines the dates
+  embedded in the file metadata to determine when the photo was taken.) A variety of
+  standard date formats are available (<gui>year-month</gui> for example). The
+  <gui>as single subfolder</gui> checkbox controls whether a "deep" or "shallow"
+  hierarchy of files is made (for example, with <gui>year-month</gui>, you can have
+  year subfolders with month subfolders under them, or all subfolders can be at the
+  same level in the filesystem, with the year and name both the folder name.</p>
+
+  <p>It is not necessary to use the predefined date formats. If you select
+  <gui>custom format</gui>, standard date codes can be used. Click on the 
+  help icon to the right of the custom format field for a list of format codes.
+  "%E" is a special code that will embed the <gui>Event</gui> name defined in the
+  main import dialog.</p>
+
+  <p>See <link xref="gthumb-date-formats"/> for more date format codes.</p>
+
+  <p>If you use automatic subfolder naming, the <gui>Destination</gui> field in the main
+  import dialog will show the automatic portion of the folder in red. (For date-based
+  formats, dummy data may be shown in the red portion.)</p>
+
+  <figure>
+    <title>Using Custom Formats</title>
+    <media type="image" mime="image/png" src="figures/import-pref-custom-format.png" />
+  </figure>
+
+</page>
diff --git a/help/C/rename-series.page b/help/C/rename-series.page
index 309bffa..3cdfe2c 100644
--- a/help/C/rename-series.page
+++ b/help/C/rename-series.page
@@ -105,7 +105,7 @@ id="gthumb-rename-series">
         datestamps embedded inside the photo). The formatting of
         this date (and optionally time) can be specified by adding
         a standard formatting code in curly braces. For example,
-        "%M{%Y-%m-%d, %T}" would be replaced with a date and time
+        "%D{%Y-%m-%d, %T}" would be replaced with a date and time
         like "2010-04-01, 15:02:01".</p>
       </td>
     </tr>
diff --git a/help/Makefile.am b/help/Makefile.am
index 7996db6..52b85ce 100644
--- a/help/Makefile.am
+++ b/help/Makefile.am
@@ -12,7 +12,10 @@ DOC_FIGURES = \
 	figures/palette.png \
 	figures/thumbnail-pane.png \
 	figures/general-filter.png \
-	figures/specific-filter.png
+	figures/specific-filter.png \
+	figures/import.png \
+	figures/import-pref-auto-folder.png \
+        figures/import-pref-custom-format.png
 
 DOC_PAGES = \
 	index.page \
@@ -43,7 +46,8 @@ DOC_PAGES = \
 	shortcuts.page \
 	sharing-disc.page \
 	wallpaper.page \
-	bookmarks.page
+	bookmarks.page \
+	import.page
 	
 DOC_LINGUAS = de el es fr oc sl sv zh_CN