Create template help Pango markdown programmatically (partial).

Do that the first time the text is shown, rather than at startup.

rtdata/languages/default

@@ -2106,7 +2106,17 @@ QUEUE_DESTPREVIEW_TOOLTIP;Destination path for the first selected image appears
 QUEUE_FORMAT_TITLE;File Format
 QUEUE_LOCATION_FOLDER;Save to folder
 QUEUE_LOCATION_TEMPLATE;Use template
-QUEUE_LOCATION_TEMPLATE_TOOLTIP;Specify the output location based on the source photo's location, rank, trash status or position in the queue.\n\n<b>%dN</b>, <b>%d-N</b>, <b>%pN</b>, <b>%p-N</b>, <b>%PN</b> and <b>%P-N</b> (N = 1..9) will be replaced by elements of the image file's directory path (not including the file name):\n<b>%dN</b> = Nth directory from the end of the path\n<b>%d-N</b> = Nth directory from the start of the path\n<b>%pN</b>  = all directories up to the Nth from the end of the path\n<b>%p-N</b> = the first N directories in the path\n<b>%PN</b>  = the last N directories in the path\n<b>%P-N</b> = all directories from the Nth to the end of the path\n<b>%f</b> = base filename (no extension)\nFor Windows paths, <b>%d-1</b> is the drive letter and colon, and <b>%d-2</b> is the base directory on that drive.\n\nUsing the following pathname as an example:\n<b>/home/tom/photos/2010-10-31/photo1.raw</b>\nthe meaning of the formatting strings follows:\n<b>%d4</b> = <b>%d-1</b> = <i>home</i>\n<b>%d3</b> = <b>%d-2</b> = <i>tom</i>\n<b>%d2</b> = <b>%d-3</b> = <i>photos</i>\n<b>%d1</b> = <b>%d-4</b> = <i>2010-10-31</i>\n<b>%p1</b> = <b>%p-4</b> = <i>/home/tom/photos/2010-10-31/</i>\n<b>%p2</b> = <b>%p-3</b> = <i>/home/tom/photos/</i>\n<b>%p3</b> = <b>%p-2</b> = <i>/home/tom/</i>\n<b>%p4</b> = <b>%p-1</b> = <i>/home/</i>\n<b>%P1</b> = <b>%P-4</b> = <i>2010-10-31/</i>\n<b>%P2</b> = <b>%P-3</b> = <i>photos/2010-10-31/</i>\n<b>%P3</b> = <b>%P-2</b> = <i>tom/photos/2010-10-31/</i>\n<b>%P4</b> = <b>%P-1</b> = <i>/home/tom/photos/2010-10-31/</i>\n<b>%f</b> = <i>photo1</i>\n\n<b>%r</b> will be replaced by the photo's rank. If the photo is unranked, '<i>0</i>' is used. If the photo is in the trash, '<i>x</i>' is used.\n\n<b>%s1</b>, ..., <b>%s9</b> will be replaced by the photo's initial position in the queue at the time the queue is started. The number specifies the padding, e.g. <b>%s3</b> results in '<i>001</i>'.\n\nIf you want to save the output image alongside the source image, write:\n<b>%p1/%f</b>\n\nIf you want to save the output image in a folder named '<i>converted</i>' located in the source photo's folder, write:\n<b>%p1/converted/%f</b>\n\nIf you want to save the output image in\n'<i>/home/tom/photos/converted/2010-10-31</i>', write:\n<b>%p-3/converted/%P-4/%f</b>
+REMOVE_ME_OLD___QUEUE_LOCATION_TEMPLATE_TOOLTIP;Specify the output location based on the source photo's location, rank, trash status or position in the queue.\n\n<b>%dN</b>, <b>%d-N</b>, <b>%pN</b>, <b>%p-N</b>, <b>%PN</b> and <b>%P-N</b> (N = 1..9) will be replaced by elements of the image file's directory path (not including the file name):\n<b>%dN</b> = Nth directory from the end of the path\n<b>%d-N</b> = Nth directory from the start of the path\n<b>%pN</b>  = all directories up to the Nth from the end of the path\n<b>%p-N</b> = the first N directories in the path\n<b>%PN</b>  = the last N directories in the path\n<b>%P-N</b> = all directories from the Nth to the end of the path\n<b>%f</b> = base filename (no extension)\nFor Windows paths, <b>%d-1</b> is the drive letter and colon, and <b>%d-2</b> is the base directory on that drive.\n\nUsing the following pathname as an example:\n<b>/home/tom/photos/2010-10-31/photo1.raw</b>\nthe meaning of the formatting strings follows:\n<b>%d4</b> = <b>%d-1</b> = <i>home</i>\n<b>%d3</b> = <b>%d-2</b> = <i>tom</i>\n<b>%d2</b> = <b>%d-3</b> = <i>photos</i>\n<b>%d1</b> = <b>%d-4</b> = <i>2010-10-31</i>\n<b>%p1</b> = <b>%p-4</b> = <i>/home/tom/photos/2010-10-31/</i>\n<b>%p2</b> = <b>%p-3</b> = <i>/home/tom/photos/</i>\n<b>%p3</b> = <b>%p-2</b> = <i>/home/tom/</i>\n<b>%p4</b> = <b>%p-1</b> = <i>/home/</i>\n<b>%P1</b> = <b>%P-4</b> = <i>2010-10-31/</i>\n<b>%P2</b> = <b>%P-3</b> = <i>photos/2010-10-31/</i>\n<b>%P3</b> = <b>%P-2</b> = <i>tom/photos/2010-10-31/</i>\n<b>%P4</b> = <b>%P-1</b> = <i>/home/tom/photos/2010-10-31/</i>\n<b>%f</b> = <i>photo1</i>\n\n<b>%r</b> will be replaced by the photo's rank. If the photo is unranked, '<i>0</i>' is used. If the photo is in the trash, '<i>x</i>' is used.\n\n<b>%s1</b>, ..., <b>%s9</b> will be replaced by the photo's initial position in the queue at the time the queue is started. The number specifies the padding, e.g. <b>%s3</b> results in '<i>001</i>'.\n\nIf you want to save the output image alongside the source image, write:\n<b>%p1/%f</b>\n\nIf you want to save the output image in a folder named '<i>converted</i>' located in the source photo's folder, write:\n<b>%p1/converted/%f</b>\n\nIf you want to save the output image in\n'<i>/home/tom/photos/converted/2010-10-31</i>', write:\n<b>%p-3/converted/%P-4/%f</b>
+QUEUE_LOCATION_TEMPLATE_TOOLTIP;Specify the output location based on characteristics such as the source photo's location, rank, trash status or position in the queue.\n\nThe output template field value can include specifiers beginning with <b>%</b>, which are replaced by those characteristics in the actual destination path.\n\nPress the <b>?</b> button for full instructions.
+QUEUE_LOCATION_TEMPLATE_HELP_TITLE;Creating an output template
+QUEUE_LOCATION_TEMPLATE_HELP_INTRO;The output template field allows you to to dynamically customize the destination folder and filename. When you include certain specifiers, which begin with <b>%</b>, they are replaced by the program when each file is being saved.\n\nThe sections below describe each type of specifier.
+QUEUE_LOCATION_TEMPLATE_HELP_PATHS_TITLE;Directories and partial paths
+QUEUE_LOCATION_TEMPLATE_HELP_PATHS_INTRO;The <b>%dN</b>, <b>%d-N</b>, <b>%pN</b>, <b>%p-N</b>, <b>%PN</b> and <b>%P-N</b> (N = 1..9) specifiers will be replaced by elements of the image file's directory path.\nThe format specifiers operate as follows:\n  <b>%dN</b> = Nth directory from the end of the path\n  <b>%d-N</b> = Nth directory from the start of the path\n  <b>%pN</b>  = all directories up to the Nth from the end of the path\n  <b>%p-N</b> = the first N directories in the path\n  <b>%PN</b>  = the last N directories in the path\n  <b>%P-N</b> = all directories from the Nth to the end of the path\n  <b>%f</b> = base filename (no extension)\nFor Windows paths, <b>%d-1</b> is the drive letter and colon, and <b>%d-2</b> is the base directory on that drive.
+QUEUE_LOCATION_TEMPLATE_HELP_PATHS_BODY_1;Using this pathname as an example:
+QUEUE_LOCATION_TEMPLATE_HELP_PATHS_EXAMPLE_LINUX;/home/tom/photos/2010-10-31/photo1.raw
+QUEUE_LOCATION_TEMPLATE_HELP_PATHS_EXAMPLE_WINDOWS;C:\users\tom\photos\2010-10-31\photo1.raw
+QUEUE_LOCATION_TEMPLATE_HELP_PATHS_BODY_2;The meanings of the formatting strings are:
+
 QUEUE_LOCATION_TITLE;Output Location
 QUEUE_STARTSTOP_TOOLTIP;Start or stop processing the images in the queue.\n\nShortcut: <b>Ctrl</b>+<b>s</b>
 SAMPLEFORMAT_0;Unknown data format

rtgui/batchqueuepanel.cc

@@ -23,6 +23,57 @@
 #include "soundman.h"
 #include "rtimage.h"
 
+namespace // helper functions
+{
+
+    // Populate the buffer of a Gtk::TextView with help text for the location template field
+    void populateTemplateHelpBuffer(Glib::RefPtr<Gtk::TextBuffer> buffer)
+    {
+        auto pos = buffer->begin();
+        auto insertHeading1 = [&pos, buffer](const Glib::ustring& text) {
+            pos = buffer->insert_markup(pos, Glib::ustring::format("<big><b>", text, "</b></big>\n"));
+        };
+        auto insertHeading2 = [&pos, buffer](const Glib::ustring& text) {
+            pos = buffer->insert_markup(pos, Glib::ustring::format("\n\n<u><b>", text, "</b></u>\n"));
+        };
+        insertHeading1(M("QUEUE_LOCATION_TEMPLATE_HELP_TITLE"));
+        pos = buffer->insert_markup(pos, M("QUEUE_LOCATION_TEMPLATE_HELP_INTRO"));
+        insertHeading2(M("QUEUE_LOCATION_TEMPLATE_HELP_PATHS_TITLE"));
+        printf("[[[%s]]]", M("QUEUE_LOCATION_TEMPLATE_HELP_PATHS_INTRO").c_str());
+        pos = buffer->insert_markup(pos, M("QUEUE_LOCATION_TEMPLATE_HELP_PATHS_INTRO"));
+        pos = buffer->insert(pos, "\n");
+        pos = buffer->insert_markup(pos, M("QUEUE_LOCATION_TEMPLATE_HELP_PATHS_BODY_1"));
+#ifdef _WIN32
+        auto exampleString = M("QUEUE_LOCATION_TEMPLATE_HELP_PATHS_EXAMPLE_WINDOWS");
+#else
+        auto exampleString = M("QUEUE_LOCATION_TEMPLATE_HELP_PATHS_EXAMPLE_LINUX");
+#endif
+        pos = buffer->insert_markup(pos, Glib::ustring::format("\n   ", exampleString, "\n"));
+        pos = buffer->insert_markup(pos, M("QUEUE_LOCATION_TEMPLATE_HELP_PATHS_BODY_2"));
+        pos = buffer->insert(pos, "\n");
+        /* FIXME: Still to do here:
+            Generate text like the original below, but use the actual conversion function to create it:
+                <b>%d4</b> = <b>%d-1</b> = <i>home</i>
+                <b>%d3</b> = <b>%d-2</b> = <i>tom</i>
+                <b>%d2</b> = <b>%d-3</b> = <i>photos</i>
+                <b>%d1</b> = <b>%d-4</b> = <i>2010-10-31</i>
+                <b>%p1</b> = <b>%p-4</b> = <i>/home/tom/photos/2010-10-31/</i>
+                <b>%p2</b> = <b>%p-3</b> = <i>/home/tom/photos/</i>
+                <b>%p3</b> = <b>%p-2</b> = <i>/home/tom/</i>
+                <b>%p4</b> = <b>%p-1</b> = <i>/home/</i>
+                <b>%P1</b> = <b>%P-4</b> = <i>2010-10-31/</i>
+                <b>%P2</b> = <b>%P-3</b> = <i>photos/2010-10-31/</i>
+                <b>%P3</b> = <b>%P-2</b> = <i>tom/photos/2010-10-31/</i>
+                <b>%P4</b> = <b>%P-1</b> = <i>/home/tom/photos/2010-10-31/</i>
+                <b>%f</b> = <i>photo1</i>
+            Insert sections for the remaining specifiers:
+                %r = rank
+                %s# = queue position, with padding
+            Insert an examples section
+        */
+    }
+}
+
 static Glib::ustring makeFolderLabel(Glib::ustring path)
 {
     if (!Glib::file_test (path, Glib::FILE_TEST_IS_DIR)) {
@@ -158,13 +209,6 @@ BatchQueuePanel::BatchQueuePanel (FileCatalog* aFileCatalog) : parent(nullptr)
     templateHelpTextView->set_wrap_mode(Gtk::WRAP_WORD);
     scrolledTemplateHelpWindow = Gtk::manage(new Gtk::ScrolledWindow());
     scrolledTemplateHelpWindow->add(*templateHelpTextView);
-    {
-        auto helptext = M("QUEUE_LOCATION_TEMPLATE_TOOLTIP");
-        auto buffer = templateHelpTextView->get_buffer();
-        buffer->create_tag("bold");
-        buffer->create_tag("italic");
-        buffer->insert_markup(buffer->begin(), helptext);
-    }
     middleSplitPane->pack1 (*scrolledTemplateHelpWindow);
     middleSplitPane->pack2 (*batchQueue);
     scrolledTemplateHelpWindow->set_visible(false); // initially hidden, templateHelpButton shows it
@@ -348,7 +392,11 @@ void BatchQueuePanel::setGuiFromBatchState(bool queueRunning, int qsize)
 void BatchQueuePanel::templateHelpButtonToggled()
 {
     bool visible = templateHelpButton->get_active();
-    //scrolledTemplateHelpWindow->set_no_show_all(!visible);
+    auto buffer = templateHelpTextView->get_buffer();
+    if (buffer->get_text().empty()) {
+        // Populate the help text the first time it's shown
+        populateTemplateHelpBuffer(buffer);
+    }
     scrolledTemplateHelpWindow->set_visible(visible);
     templateHelpTextView->set_visible(visible);
 }