From: Colin Clark Date: Tue, 14 Jun 2022 15:23:20 +0000 (+0100) Subject: Update metadata handling documentation X-Git-Tag: gtk2final~9 X-Git-Url: http://geeqie.org/cgi-bin/gitweb.cgi?p=geeqie.git;a=commitdiff_plain;h=b20ddc014f3452526389bc04d4d350ad9b8faaa6 Update metadata handling documentation --- diff --git a/doc/diagrams.c b/doc/diagrams.c index fb1ad37a..2e5bf8a3 100644 --- a/doc/diagrams.c +++ b/doc/diagrams.c @@ -27,6 +27,136 @@ * The .c file extension is so that Doxygen will process it. */ +/** + * @page diagrams Diagrams + * @section metadata_write Metadata write sequence + * + * @startuml + * + * group metadata write sequence + * start + * + * : write to file/sidecar = FALSE; + * if (//Preferences / Metadata//\n **Step 1:**\n Save in image file or sidecar file) then (yes) + * if (extension in //File Filters / File Types / Writable// list) then (yes) + * if (image file writable) then (yes) + * : write to file/sidecar = TRUE; + * : metadata_file = ; + * else (no) + * : log warning; + * endif + * else (no) + * if (extension in //File Filters / File Types / Sidecar Is Allowed// list) then (yes) + * if (sidecar file or folder writable) then (yes) + * : write to file/sidecar = TRUE; + * : metadata_file = ; + * else (no) + * : log warning; + * endif + * else (no) + * endif + * endif + * else (no) + * endif + * + * if (write to file/sidecar) then (yes) + * else (no) + * group If a metadata file already exists, use it + * start + * group Look in user defined option + * if (//Preferences / Metadata//\n **Step 2:**\n Save in sub-folder local to image folder) then (yes) + * : metadata_file = \n/.metadata/.gq.xmp; + * else (no) + * if (XDG_DATA_HOME defined) then (yes) + * : metadata_file = \nXDG_DATA_HOME/geeqie/metadata//.gq.xmp; + * else (no) + * : metadata_file = \nHOME/.local/share/geeqie/metadata//.gq.xmp; + * endif + * endif + * end group + * + * if (metadata_file exists) then (yes) + * else (no) + * group Ignore user defined option and try alternate + * if (//Preferences / Metadata//\n **Step 2:**\n Save in sub-folder local to image) then (no) + * : metadata_file = \n /.metadata/.gq.xmp; + * else (yes) + * if (XDG_DATA_HOME defined) then (yes) + * : metadata_file = \n XDG_DATA_HOME/geeqie/metadata//.gq.xmp; + * else (no) + * : metadata_file = \n HOME/.local/share/geeqie/metadata//.gq.xmp; + * endif + * endif + * end group + * endif + * + * if (metadata_file exists) then (yes) + * else (no) + * group Try GQview legacy format + * if (//Preferences / Metadata//\n **Step 2:**\n Save in sub-folder local to image folder) then (yes) + * : metadata_file = \n/.metadata/.meta; + * else (no) + * if (XDG_DATA_HOME defined) then (yes) + * : metadata_file = \nXDG_DATA_HOME/geeqie/metadata//.meta; + * else (no) + * : metadata_file = \nHOME/.local/share/geeqie/metadata//.meta; + * endif + * endif + * end group + * + * if (metadata_file exists) then (yes) + * else (no) + * group Ignore user defined option and try alternate + * if (//Preferences / Metadata//\n **Step 2:**\n Save in sub-folder local to image) then (no) + * : metadata_file = \n /.metadata/.meta; + * else (yes) + * if (XDG_DATA_HOME defined) then (yes) + * : metadata_file = \n XDG_DATA_HOME/geeqie/metadata//.meta; + * else (no) + * : metadata_file = \n HOME/.local/share/geeqie/metadata//.meta; + * endif + * endif + * end group + * endif + * endif + * end group + * + * if (metadata_file exists) then (yes) + * else (no) + * group If no metadata file exists, use user defined option + * if (//Preferences / Metadata//\n **Step 2:**\n Save in sub-folder local to image folder) then (yes) + * : metadata_file = \n/.metadata/.gq.xmp; + * else (no) + * if (XDG_DATA_HOME defined) then (yes) + * : metadata_file = \nXDG_DATA_HOME/geeqie/metadata//.gq.xmp; + * else (no) + * : metadata_file = \nHOME/.local/share/geeqie/metadata//.gq.xmp; + * endif + * endif + * end group + * endif + * + * if (metadata_file writable) then (yes) + * else (no) + * if (XDG_DATA_HOME defined) then (yes) + * : metadata_file = \nXDG_DATA_HOME/geeqie/metadata//.gq.xmp; + * else (no) + * : metadata_file = \nHOME/.local/share/geeqie/metadata//.gq.xmp; + * endif + * : Recursively create metadata_file_path\n if necessary; + * endif + * endif + * : Write metadata; + * + * end group + * @enduml + */ + /** + * @file + * @ref metadata_write "Metadata write sequence" + */ + + /** * @page diagrams Diagrams * @section options_overview Options Overview diff --git a/doc/docbook/GuideOptionsFiltering.xml b/doc/docbook/GuideOptionsFiltering.xml index 7c2fcc95..5cfead35 100644 --- a/doc/docbook/GuideOptionsFiltering.xml +++ b/doc/docbook/GuideOptionsFiltering.xml @@ -1,7 +1,7 @@
- Files Options - This section describes the options presented under the Files Tab of the preferences dialogue. + File Filters Options + This section describes the options presented under the File Filters Tab of the preferences dialogue.
Filters diff --git a/doc/docbook/GuideOptionsMetadata.xml b/doc/docbook/GuideOptionsMetadata.xml index 7229317c..5cf6f779 100644 --- a/doc/docbook/GuideOptionsMetadata.xml +++ b/doc/docbook/GuideOptionsMetadata.xml @@ -2,12 +2,6 @@
Metadata This section describes the options for metadata writing. - - - The settings in the - Files tab of Preferences - influence whether an attempt is made to write metadata to the file itself, to a sidecar file or to a local folder. - Refer also to @@ -16,13 +10,19 @@
Metadata writing process - When writing metadata, Geeqie will follow three steps. This process will stop when the first successful write occurs. + When writing metadata, Geeqie will follow these steps. This process will stop when the first successful write occurs. A flowchart showing the sequence is + here + . - Save metadata in image files, resp. sidecar files, according to the XMP standard + Save metadata in image files or sidecar files, according to the XMP standard If checked, Geeqie will attempt to write metadata to the file itself, or to an associated XMP sidecar file + + The destination is dependent on the settings in the "Writable" and "Sidecar Is Allowed" columns of the + File Filters tab + . @@ -45,7 +45,7 @@ When writing to local metadata folders, the directory structure duplicates that of the location of the source files.
- Step 1: Write to image files + Step 1 Options: If Step 1 above was successful, the following options take effect: @@ -54,6 +54,10 @@ If checked, Geeqie will write IPTC tags as defined in + + The conversion from XMP tag to IPTC tag is performed by exiv2. A list of the XMP-IPTC conversions is at the end of + this table + . @@ -74,13 +78,13 @@ Create sidecar files named image.ext.xmp (as opposed to image.xmp) - If checked, new sidecar files will use image.ext.xmp naming scheme + If checked, new sidecar files will use image.ext.xmp naming scheme. This scheme is used by Darktable.
- Steps 2 and 3: Write to Geeqie private files + Steps 2 and 3 Option: If Step 2 or 3 above was successful, the following option takes effect: @@ -97,12 +101,37 @@ - Write the same description tags (keywords, comment, title) to all grouped sidecars + Write the same description tags to all grouped sidecars If checked the same descriptive tags are written to all files in a group. File grouping is as defined in the - Files tab + File Filters tab of main Preferences. Technical tags (exif) are handled separately for each file. + The tags written are: + + "Xmp.dc.title" + "Xmp.photoshop.Urgency" + "Xmp.photoshop.Category", + "Xmp.photoshop.SupplementalCategory", + "Xmp.dc.subject", + "Xmp.iptc.Location", + "Xmp.photoshop.Instruction", + "Xmp.photoshop.DateCreated", + "Xmp.dc.creator", + "Xmp.photoshop.AuthorsPosition", + "Xmp.photoshop.City", + "Xmp.photoshop.State", + "Xmp.iptc.CountryCode", + "Xmp.photoshop.Country", + "Xmp.photoshop.TransmissionReference", + "Xmp.photoshop.Headline", + "Xmp.photoshop.Credit", + "Xmp.photoshop.Source", + "Xmp.dc.rights", + "Xmp.dc.description", + "Xmp.photoshop.CaptionWriter", + + @@ -205,4 +234,11 @@
+
+ Metadata Write Sequence Flowchart + + + + +
diff --git a/doc/icons/metadata-flowchart.png b/doc/icons/metadata-flowchart.png new file mode 100644 index 00000000..18d95638 Binary files /dev/null and b/doc/icons/metadata-flowchart.png differ diff --git a/src/metadata.c b/src/metadata.c index a4c7d024..5738c98f 100644 --- a/src/metadata.c +++ b/src/metadata.c @@ -42,7 +42,11 @@ typedef enum { MK_COMMENT } MetadataKey; -static const gchar *group_keys[] = { /* tags that will be written to all files in a group, options->metadata.sync_grouped_files */ +/* If contents change, keep GuideOptionsMetadata.xml up to date */ +/** + * @brief Tags that will be written to all files in a group - selected by: options->metadata.sync_grouped_files, Preferences/Metadata/Write The Same Description Tags To All Grouped Sidecars + */ +static const gchar *group_keys[] = { "Xmp.dc.title", "Xmp.photoshop.Urgency", "Xmp.photoshop.Category", diff --git a/src/preferences.c b/src/preferences.c index 97a6c39b..641962b6 100644 --- a/src/preferences.c +++ b/src/preferences.c @@ -2741,7 +2741,7 @@ static void config_tab_files(GtkWidget *notebook) GtkTreeSelection *selection; GtkTreeViewColumn *column; - vbox = scrolled_notebook_page(notebook, _("Files")); + vbox = scrolled_notebook_page(notebook, _("File Filters")); group = pref_box_new(vbox, FALSE, GTK_ORIENTATION_VERTICAL, PREF_PAD_GAP); @@ -2913,34 +2913,50 @@ static void config_tab_metadata(GtkWidget *notebook) GtkWidget *group; GtkWidget *ct_button; GtkWidget *label; - gchar *text; + GtkWidget *tmp_widget; + char *markup; + GtkWidget *text_label; vbox = scrolled_notebook_page(notebook, _("Metadata")); - group = pref_group_new(vbox, FALSE, _("Metadata writing process"), GTK_ORIENTATION_VERTICAL); + group = pref_group_new(vbox, FALSE, _("Metadata writing sequence"), GTK_ORIENTATION_VERTICAL); #ifndef HAVE_EXIV2 label = pref_label_new(group, _("Warning: Geeqie is built without Exiv2. Some options are disabled.")); #endif - label = pref_label_new(group, _("Metadata are written in the following order. The process ends after first success.")); + label = pref_label_new(group, _("When writing metadata, Geeqie will follow these steps, if selected. This process will stop when the first successful write occurs.")); #if GTK_CHECK_VERSION(3,16,0) gtk_label_set_xalign(GTK_LABEL(label), 0.0); gtk_label_set_yalign(GTK_LABEL(label), 0.5); #else gtk_misc_set_alignment(GTK_MISC(label), 0.0, 0.5); #endif + gtk_widget_set_tooltip_text(label, _("A flowchart of the sequence is shown in the Help file")); + + ct_button = pref_checkbox_new_int(group, "", options->metadata.save_in_image_file, &c_options->metadata.save_in_image_file); + text_label = gtk_bin_get_child(GTK_BIN(ct_button)); + markup = g_markup_printf_escaped ("%s%s", _("Step 1"), _(") Save metadata in either the image file or the sidecar file, according to the XMP standard")); + gtk_label_set_markup (GTK_LABEL(text_label), markup); + g_free(markup); + markup = g_markup_printf_escaped ("%s%s%s%s%s", _("The destination is dependent on the settings in the "), _("Writable"), _(" and "), _("Sidecar Is Allowed"), _(" columns of the File Filters tab)")); + gtk_widget_set_tooltip_markup(ct_button, markup); + g_free(markup); - ct_button = pref_checkbox_new_int(group, _("1) Save metadata in image files, or sidecar files, according to the XMP standard"), - options->metadata.save_in_image_file, &c_options->metadata.save_in_image_file); #ifndef HAVE_EXIV2 gtk_widget_set_sensitive(ct_button, FALSE); #endif - pref_checkbox_new_int(group, _("2) Save metadata in '.metadata' folder, local to image folder (non-standard)"), - options->metadata.enable_metadata_dirs, &c_options->metadata.enable_metadata_dirs); + tmp_widget = pref_checkbox_new_int(group, "", options->metadata.enable_metadata_dirs, &c_options->metadata.enable_metadata_dirs); + text_label = gtk_bin_get_child(GTK_BIN(tmp_widget)); + markup = g_markup_printf_escaped ("%s%s%s%s", _("Step 2"), _(") Save metadata in the folder "),".metadata,", _(" local to the image folder (non-standard)")); + gtk_label_set_markup (GTK_LABEL(text_label), markup); + g_free(markup); + + label = pref_label_new(group, ""); + markup = g_markup_printf_escaped ("%s%s%s%s", _("Step 3"), _(") Save metadata in Geeqie private directory "), get_metadata_cache_dir(), "/"); + gtk_label_set_markup (GTK_LABEL(label), markup); + g_free(markup); - text = g_strdup_printf(_("3) Save metadata in Geeqie private directory '%s'"), get_metadata_cache_dir()); - label = pref_label_new(group, text); #if GTK_CHECK_VERSION(3,16,0) gtk_label_set_xalign(GTK_LABEL(label), 0.0); gtk_label_set_yalign(GTK_LABEL(label), 0.5); @@ -2948,9 +2964,9 @@ static void config_tab_metadata(GtkWidget *notebook) gtk_misc_set_alignment(GTK_MISC(label), 0.0, 0.5); #endif gtk_misc_set_padding(GTK_MISC(label), 22, 0); - g_free(text); + pref_spacer(group, PREF_PAD_GROUP); - group = pref_group_new(vbox, FALSE, _("Step 1: Write to image files"), GTK_ORIENTATION_VERTICAL); + group = pref_group_new(vbox, FALSE, _("Step 1 Options:"), GTK_ORIENTATION_VERTICAL); #ifndef HAVE_EXIV2 gtk_widget_set_sensitive(group, FALSE); #endif @@ -2958,69 +2974,76 @@ static void config_tab_metadata(GtkWidget *notebook) hbox = pref_box_new(group, FALSE, GTK_ORIENTATION_VERTICAL, PREF_PAD_SPACE); pref_checkbox_link_sensitivity(ct_button, hbox); - pref_checkbox_new_int(hbox, _("Store metadata also in legacy IPTC tags (converted according to IPTC4XMP standard)"), - options->metadata.save_legacy_IPTC, &c_options->metadata.save_legacy_IPTC); + tmp_widget= pref_checkbox_new_int(hbox, _("Store metadata also in IPTC tags (converted according to the IPTC4XMP standard)"), options->metadata.save_legacy_IPTC, &c_options->metadata.save_legacy_IPTC); + gtk_widget_set_tooltip_text(tmp_widget, _("A simplified conversion list is in the Help file")); - pref_checkbox_new_int(hbox, _("Warn if the image files are unwritable"), - options->metadata.warn_on_write_problems, &c_options->metadata.warn_on_write_problems); + pref_checkbox_new_int(hbox, _("Warn if the image or sidecar file is not writable"), options->metadata.warn_on_write_problems, &c_options->metadata.warn_on_write_problems); - pref_checkbox_new_int(hbox, _("Ask before writing to image files"), - options->metadata.confirm_write, &c_options->metadata.confirm_write); + pref_checkbox_new_int(hbox, _("Ask before writing to image files"), options->metadata.confirm_write, &c_options->metadata.confirm_write); - pref_checkbox_new_int(hbox, _("Create sidecar files named image.ext.xmp (as opposed to image.xmp)"), - options->metadata.sidecar_extended_name, &c_options->metadata.sidecar_extended_name); + tmp_widget= pref_checkbox_new_int(hbox, "", options->metadata.sidecar_extended_name, &c_options->metadata.sidecar_extended_name); + gtk_widget_set_tooltip_text(tmp_widget, _("This file naming convention is used by Darktable")); + text_label = gtk_bin_get_child(GTK_BIN(tmp_widget)); + markup = g_markup_printf_escaped ("%s%s%s%s%s", _("Create sidecar files named "), "image.ext.xmp", _(" (as opposed to the normal "), "image.xmp", ")"); + gtk_label_set_markup (GTK_LABEL(text_label), markup); + g_free(markup); - group = pref_group_new(vbox, FALSE, _("Step 2 and 3: write to Geeqie private files"), GTK_ORIENTATION_VERTICAL); + pref_spacer(group, PREF_PAD_GROUP); + + group = pref_group_new(vbox, FALSE, _("Steps 2 and 3 Option:"), GTK_ORIENTATION_VERTICAL); #ifndef HAVE_EXIV2 gtk_widget_set_sensitive(group, FALSE); #endif - pref_checkbox_new_int(group, _("Use GQview legacy metadata format (supports only keywords and comments) instead of XMP"), - options->metadata.save_legacy_format, &c_options->metadata.save_legacy_format); + pref_checkbox_new_int(group, _("Use GQview legacy metadata format instead of XMP (supports only Keywords and Comments)"), options->metadata.save_legacy_format, &c_options->metadata.save_legacy_format); + pref_spacer(group, PREF_PAD_GROUP); group = pref_group_new(vbox, FALSE, _("Miscellaneous"), GTK_ORIENTATION_VERTICAL); - pref_checkbox_new_int(group, _("Write the same description tags (keywords, comment, etc.) to all grouped sidecars"), - options->metadata.sync_grouped_files, &c_options->metadata.sync_grouped_files); + tmp_widget = pref_checkbox_new_int(group, _("Write the same description tags to all grouped sidecars"), options->metadata.sync_grouped_files, &c_options->metadata.sync_grouped_files); + gtk_widget_set_tooltip_text(tmp_widget, _("See the Help file for a list of the tags used")); + + tmp_widget = pref_checkbox_new_int(group, _("Permit Keywords to be case-sensitive"), options->metadata.keywords_case_sensitive, &c_options->metadata.keywords_case_sensitive); + gtk_widget_set_tooltip_text(tmp_widget, _("When selected, \"Place\" and \"place\" are two different keywords")); - pref_checkbox_new_int(group, _("Allow keywords to differ only in case"), - options->metadata.keywords_case_sensitive, &c_options->metadata.keywords_case_sensitive); + ct_button = pref_checkbox_new_int(group, _("Write altered image orientation to the metadata"), options->metadata.write_orientation, &c_options->metadata.write_orientation); + gtk_widget_set_tooltip_text(ct_button, _("If checked, the results of orientation commands (Rotate, Mirror and Flip) issued on an image will be written to metadata\nNote: If this option is not checked, the results of orientation commands will be lost when Geeqie closes")); - ct_button = pref_checkbox_new_int(group, _("Write altered image orientation to the metadata"), - options->metadata.write_orientation, &c_options->metadata.write_orientation); #ifndef HAVE_EXIV2 gtk_widget_set_sensitive(ct_button, FALSE); #endif + pref_spacer(group, PREF_PAD_GROUP); + group = pref_group_new(vbox, FALSE, _("Auto-save options"), GTK_ORIENTATION_VERTICAL); - ct_button = pref_checkbox_new_int(group, _("Write metadata after timeout"), - options->metadata.confirm_after_timeout, &c_options->metadata.confirm_after_timeout); + ct_button = pref_checkbox_new_int(group, _("Write metadata after timeout"), options->metadata.confirm_after_timeout, &c_options->metadata.confirm_after_timeout); hbox = pref_box_new(group, FALSE, GTK_ORIENTATION_HORIZONTAL, PREF_PAD_SPACE); pref_checkbox_link_sensitivity(ct_button, hbox); - pref_spin_new_int(hbox, _("Timeout (seconds):"), NULL, 0, 900, 1, - options->metadata.confirm_timeout, &c_options->metadata.confirm_timeout); + pref_spin_new_int(hbox, _("Timeout (seconds):"), NULL, 0, 900, 1, options->metadata.confirm_timeout, &c_options->metadata.confirm_timeout); + + pref_checkbox_new_int(group, _("Write metadata on image change"), options->metadata.confirm_on_image_change, &c_options->metadata.confirm_on_image_change); - pref_checkbox_new_int(group, _("Write metadata on image change"), - options->metadata.confirm_on_image_change, &c_options->metadata.confirm_on_image_change); + pref_checkbox_new_int(group, _("Write metadata on directory change"), options->metadata.confirm_on_dir_change, &c_options->metadata.confirm_on_dir_change); - pref_checkbox_new_int(group, _("Write metadata on directory change"), - options->metadata.confirm_on_dir_change, &c_options->metadata.confirm_on_dir_change); + pref_spacer(group, PREF_PAD_GROUP); #ifdef HAVE_SPELL #if GTK_CHECK_VERSION(3,20,0) group = pref_group_new(vbox, FALSE, _("Spelling checks"), GTK_ORIENTATION_VERTICAL); - ct_button = pref_checkbox_new_int(group, _("Check spelling -Requires restart"), options->metadata.check_spelling, &c_options->metadata.check_spelling); + ct_button = pref_checkbox_new_int(group, _("Check spelling - Requires restart"), options->metadata.check_spelling, &c_options->metadata.check_spelling); + gtk_widget_set_tooltip_text(ct_button, _("Spelling checks are performed on info sidebar panes Comment, Headline and Title")); #endif #endif + pref_spacer(group, PREF_PAD_GROUP); + group = pref_group_new(vbox, FALSE, _("Pre-load metadata"), GTK_ORIENTATION_VERTICAL); - ct_button = pref_checkbox_new_int(group, _("Read metadata in background"), - options->read_metadata_in_idle, &c_options->read_metadata_in_idle); + ct_button = pref_checkbox_new_int(group, _("Read metadata in background"), options->read_metadata_in_idle, &c_options->read_metadata_in_idle); gtk_widget_set_tooltip_text(ct_button,"On folder change, read DateTimeOriginal, DateTimeDigitized and Star Rating in the idle loop.\nIf this is not selected, initial loading of the folder will be faster but sorting on these items will be slower"); }