[gimp] devel-docs: update documentation of performance-log parameters

[Ell <ell src gnome org>]

commit d72e6b3aedf32975d929920da7a5d704d71fa7f7
Author: Ell <ell_se yahoo com>
Date:   Thu Jul 30 18:14:23 2020 +0300

    devel-docs: update documentation of performance-log parameters

 devel-docs/performance-logs/Makefile.am            |   1 +
 .../performance-log-parameters.png                 | Bin 0 -> 7000 bytes
 devel-docs/performance-logs/performance-logs.md    |  45 +++++++++++++++++++--
 3 files changed, 43 insertions(+), 3 deletions(-)
---
diff --git a/devel-docs/performance-logs/Makefile.am b/devel-docs/performance-logs/Makefile.am
index 4f400b25d8..9f97b4bb49 100644
--- a/devel-docs/performance-logs/Makefile.am
+++ b/devel-docs/performance-logs/Makefile.am
@@ -4,6 +4,7 @@ EXTRA_DIST = \
        dashboard-add-marker.png        \
        dashboard-start-recording.png   \
        dashboard-stop-recording.png    \
+       performance-log-parameters.png  \
        new-performance-issue.png       \
        performance-log-viewer.png      \
        performance-logs.md
diff --git a/devel-docs/performance-logs/performance-log-parameters.png 
b/devel-docs/performance-logs/performance-log-parameters.png
new file mode 100644
index 0000000000..4ec2c8bb32
Binary files /dev/null and b/devel-docs/performance-logs/performance-log-parameters.png differ
diff --git a/devel-docs/performance-logs/performance-logs.md b/devel-docs/performance-logs/performance-logs.md
index 97f1108086..8e951a4422 100644
--- a/devel-docs/performance-logs/performance-logs.md
+++ b/devel-docs/performance-logs/performance-logs.md
@@ -11,6 +11,7 @@ report performance-related issues.
 
   - [1. Recording Performance Logs](#1-recording-performance-logs)
     - [1.1. Event Markers](#11-event-markers)
+    - [1.2. Log Parameters](#12-log-parameters)
   - [2. Reporting Performance-Related Issues](#2-reporting-performance-related-issues)
   - [3. What Information is Contained in the Log?](#3-what-information-is-contained-in-the-log)
   - [4. Viewing Performance Logs](#4-viewing-performance-logs)
@@ -33,7 +34,6 @@ report performance-related issues.
       - [4.3.1. Searching Samples](#431-searching-samples)
     - [4.4. History Navigation](#44-history-navigation)
     - [4.5. Environment Variables](#45-environment-variables)
-  - [5. Performance-Log Parameters](#5-performance-log-parameters)
 
 ## 1. Recording Performance Logs
 
@@ -69,6 +69,11 @@ At this point, GIMP will perform any necessary final steps, which may take a
 while (usually, no more than a few seconds).
 At the end of this process, the log is ready.
 
+*Note:*
+In situations where you can't cleanly stop recording the log, such as
+when GIMP crashes or freezes in the middle of the process, make sure to record
+a *progressive* log, as described in [section *1.2*](#12-log-parameters).
+
 ### 1.1. Event Markers
 
 When the recorded task is made up of multiple steps, it is useful to have an
@@ -95,6 +100,39 @@ number (this is especially useful for empty event markers.)
 The number of the next event marker (the one that will be added when the button
 is clicked) is displayed on the *Add Marker* button.
 
+### 1.2. Log Parameters
+
+When creating a performance log, several parameters can be set at the bottom of
+the file-selection dialog.
+There should normally be no reason to change the parameters, unless noted
+otherwise.
+
+![Performance-log parameters](log-parameters.png)
+
+  - *Sample Frequency:*
+    The number of program-state samples per second.
+    Higher values improve the resolution of the log, while making the recording
+    itself more expensive.
+
+  - *Backtrace:*
+    Whether or not to include backtraces in the log.
+    Backtraces capture the code-paths taken while recording the log, and should
+    normally be included.
+
+  - *Progressive:*
+    Whether or not to record a progressive log.
+
+    GIMP normally defers certain information to the end of the log, in order to
+    minimize the cost of recording.
+    If the log can't be cleanly finished -- for example, if GIMP crashes or
+    freezes while recording the log -- this information will be missing,
+    rendering the log of limited use.
+    In situations like these, a progressive log should be recorded; progressive
+    logs include all relevant information at each sample, allowing them to be
+    terminated at any time.
+
+    Progressive logs may incur a higher overhead while recording.
+
 ## 2. Reporting Performance-Related Issues
 
 ![Reporting a performance-related issue](new-performance-issue.png)
@@ -119,7 +157,7 @@ also be very helpful.
 
 The log consists mainly of a series of periodic *samples* of the program state.
 (The default sampling rate is 10 samples per second; see
-[section *5*](#5-performance-log-parameters) for a way to modify this value.)
+[section *1.2*](#12-log-parameters) for a way to modify this value.)
 Each sample contains the values of all the *instrumentation variables*
 displayed in the Dashboard.
 Additionally, on supported platforms, each sample contains a full *program
@@ -234,7 +272,7 @@ associated with any sample, including:
 
   - *Log Parameters*:
     Various parameters relating to the performance log itself.
-    See [section *5*](#5-performance-log-parameters) for more information.
+    See [section *1.2*](#12-log-parameters) for more information.
 
   - *GIMP Version*:
     Verbose GIMP version information, as reported by `gimp -v`.
@@ -607,6 +645,7 @@ The following environment variables are used by the viewer:
 
 ## 5. Performance-Log Parameters
 
+
 A number of parameters affect performance-log generation.
 They may be currently specified as environment variables for GIMP: