Added help sections for %r and %s tags, and for common examples

rtdata/languages/default

@@ -2106,7 +2106,6 @@ 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
-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.
@@ -2118,7 +2117,12 @@ QUEUE_LOCATION_TEMPLATE_HELP_PATHS_EXAMPLE_LINUX;/home/tom/photos/2010-10-31/pho
 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_TEMPLATE_HELP_RESULT_MISMATCH;ERROR: 2nd result is different:
-
+QUEUE_LOCATION_TEMPLATE_HELP_RANK_TITLE;Rank
+QUEUE_LOCATION_TEMPLATE_HELP_RANK_BODY;<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.
+QUEUE_LOCATION_TEMPLATE_HELP_SEQUENCE_TITLE;Position/sequence in queue
+QUEUE_LOCATION_TEMPLATE_HELP_SEQUENCE_BODY;<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>'.
+QUEUE_LOCATION_TEMPLATE_HELP_EXAMPLES_TITLE;Common examples
+QUEUE_LOCATION_TEMPLATE_HELP_EXAMPLES_BODY;If 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_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

@@ -356,15 +356,16 @@ void BatchQueuePanel::templateHelpButtonToggled()
 void BatchQueuePanel::populateTemplateHelpBuffer(Glib::RefPtr<Gtk::TextBuffer> buffer)
 {
     auto pos = buffer->begin();
-    auto insertHeading1 = [&pos, buffer](const Glib::ustring& text) {
+    auto insertTopicHeading = [&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"));
+    auto insertTopicBody = [&pos, buffer](const Glib::ustring& text) {
+        pos = buffer->insert_markup(pos, Glib::ustring::format("\n", text, "\n"));
+    };
+    auto mainTitle = M("QUEUE_LOCATION_TEMPLATE_HELP_TITLE");
+    pos = buffer->insert_markup(pos, Glib::ustring::format("<big><b>", mainTitle, "</b></big>\n"));
     pos = buffer->insert_markup(pos, M("QUEUE_LOCATION_TEMPLATE_HELP_INTRO"));
-    insertHeading2(M("QUEUE_LOCATION_TEMPLATE_HELP_PATHS_TITLE"));
+    insertTopicHeading(M("QUEUE_LOCATION_TEMPLATE_HELP_PATHS_TITLE"));
     pos = buffer->insert_markup(pos, M("QUEUE_LOCATION_TEMPLATE_HELP_PATHS_INTRO"));
     pos = buffer->insert(pos, "\n");
 #ifdef _WIN32
@@ -409,8 +410,6 @@ void BatchQueuePanel::populateTemplateHelpBuffer(Glib::RefPtr<Gtk::TextBuffer> b
         buildpos = buildBuffer->insert(buildpos, startMonospace);
         for (int n=0; n<pathElementCount; n++)
         {
-            // Example output, for a 4-element path:
-            //   <b>%d4</b> = <b>%d-1</b> = <i>home</i>
             auto path1 = Glib::ustring::format("%",letter,offset1+n*mult1);
             auto path2 = Glib::ustring::format("%",letter,offset2+n*mult2);
             options.savePathTemplate = path1;
@@ -420,6 +419,8 @@ void BatchQueuePanel::populateTemplateHelpBuffer(Glib::RefPtr<Gtk::TextBuffer> b
             buildpos = buildBuffer->insert (buildpos, Glib::ustring::format("\n   <b>", path1, "</b> = <b>", path2, "</b> = <i>", result1, "</i>"));
             if (result1 != result2)
             {
+                // If this error appears, it indicates a coding error in either BatchQueue::calcAutoFileNameBase
+                // or BatchQueuePanel::populateTemplateHelpBuffer.
                 buildpos = buildBuffer->insert(buildpos, Glib::ustring::format(" ", M("QUEUE_LOCATION_TEMPLATE_HELP_RESULT_MISMATCH"), " ", result2));
             }
         }
@@ -434,11 +435,16 @@ void BatchQueuePanel::populateTemplateHelpBuffer(Glib::RefPtr<Gtk::TextBuffer> b
     //   <b>%P1</b> = <b>%P-4</b> = <i>2010-10-31/</i>
     insertPathExamples('P', 1, 1, -pathElementCount, 1);
 
+    insertTopicHeading(M("QUEUE_LOCATION_TEMPLATE_HELP_RANK_TITLE"));
+    pos = buffer->insert_markup(pos, M("QUEUE_LOCATION_TEMPLATE_HELP_RANK_BODY"));
+
+    insertTopicHeading(M("QUEUE_LOCATION_TEMPLATE_HELP_SEQUENCE_TITLE"));
+    pos = buffer->insert_markup(pos, M("QUEUE_LOCATION_TEMPLATE_HELP_SEQUENCE_BODY"));
+
+    insertTopicHeading(M("QUEUE_LOCATION_TEMPLATE_HELP_EXAMPLES_TITLE"));
+    pos = buffer->insert_markup(pos, M("QUEUE_LOCATION_TEMPLATE_HELP_EXAMPLES_BODY"));
     /* FIXME: Still to do here:
-        Insert sections for the remaining specifiers:
+        Insert section for time/date specifiers
-            %r = rank
-            %s# = queue position, with padding
-        Insert an examples section
     */
    options = savedOptions;
 }