From ef131019238fca628ab8b830ec83bfa0f8abfe58 Mon Sep 17 00:00:00 2001
From: Andy McFadden <fadden@fadden.com>
Date: Thu, 1 Aug 2024 15:08:43 -0700
Subject: [PATCH] Clarify some app settings

The pop-up that lets you choose which assembler to set configuration
options for looked like it let you choose an assembler generally.
Changed some wording and visuals for better clarity.
---
 SourceGen/Sandbox/DomainManager.cs    |  8 ++--
 SourceGen/WpfGui/EditAppSettings.xaml | 53 +++++++++++++++------------
 docs/sgmanual/index.html              |  2 +-
 docs/sgmanual/settings.html           | 26 +++++++------
 4 files changed, 49 insertions(+), 40 deletions(-)

diff --git a/SourceGen/Sandbox/DomainManager.cs b/SourceGen/Sandbox/DomainManager.cs
index b458e94e..4d1c1b27 100644
--- a/SourceGen/Sandbox/DomainManager.cs
+++ b/SourceGen/Sandbox/DomainManager.cs
@@ -79,10 +79,10 @@ public DomainManager(bool useKeepAlive) {
                 Debug.WriteLine("Setting keep-alive timer...");
                 mKeepAliveTimer = new Timer(60 * 1000);
                 mKeepAliveTimer.Elapsed += (source, e) => {
-                    // I don't know if there's a shutdown race.  The dispose code stops the timer
-                    // before clearing the other fields, but I don't know if the Stop() code
-                    // waits for the currently-executing timer event to finish.  So wrap
-                    // everything in try/catch.
+                    // The Timer docs say that Elapsed events can occur after Stop(), because
+                    // the signal to raise Elapsed is queued on a thread pool thread.  Instead
+                    // of being careful we just wrap it in try/catch, since nothing bad happens
+                    // if this fails.
                     try {
                         int result = mPluginManager.Instance.Ping(1000);
                         Debug.WriteLine("KeepAlive tid=" +
diff --git a/SourceGen/WpfGui/EditAppSettings.xaml b/SourceGen/WpfGui/EditAppSettings.xaml
index f431982c..acaf8993 100644
--- a/SourceGen/WpfGui/EditAppSettings.xaml
+++ b/SourceGen/WpfGui/EditAppSettings.xaml
@@ -759,7 +759,7 @@ limitations under the License.
 
             <TabItem Name="asmConfigTab" Header="Asm Config">
                 <StackPanel>
-                    <GroupBox Header="Assembler Configuration" Padding="2,4">
+                    <GroupBox Header="Assembler-Specific Configuration" Padding="2,4">
                         <Grid>
                             <Grid.ColumnDefinitions>
                                 <ColumnDefinition Width="Auto"/>
@@ -771,12 +771,14 @@ limitations under the License.
                                 <RowDefinition/>
                             </Grid.RowDefinitions>
 
-                            <TextBlock Grid.Column="0" Grid.Row="0" Text="Assembler:"
-                                       HorizontalAlignment="Right" Margin="0,5,4,0"/>
-                            <ComboBox Name="asmConfigComboBox" Grid.Column="1" Grid.Row="0" IsReadOnly="True"
-                                      Width="150" HorizontalAlignment="Left" Margin="0,4,0,20"
-                                      ItemsSource="{Binding AssemblerList}" DisplayMemberPath="Name"
-                                      SelectionChanged="AsmConfigComboBox_SelectionChanged"/>
+                            <StackPanel Orientation="Horizontal" Grid.Column="0" Grid.Row="0" Grid.ColumnSpan="2">
+                                <TextBlock Text="Select assembler to configure:"
+                                           HorizontalAlignment="Right" Margin="0,7,4,0"/>
+                                <ComboBox Name="asmConfigComboBox" Grid.Column="1" Grid.Row="0" IsReadOnly="True"
+                                          Width="150" HorizontalAlignment="Left" Margin="0,4,0,20"
+                                          ItemsSource="{Binding AssemblerList}" DisplayMemberPath="Name"
+                                          SelectionChanged="AsmConfigComboBox_SelectionChanged"/>
+                            </StackPanel>
 
                             <TextBlock Grid.Column="0" Grid.Row="1" Text="Executable:"
                                        HorizontalAlignment="Right" Margin="0,0,4,0"/>
@@ -831,23 +833,26 @@ limitations under the License.
                         </Grid>
                     </GroupBox>
 
-                    <TextBlock Text="General code generation:" Margin="4,16,0,0"/>
-                    <CheckBox Content="Show cycle counts in comments" Margin="4,8,0,0"
-                              IsChecked="{Binding ShowCycleCountsAsm}"/>
-                    <CheckBox Content="Identify assembler in output" Margin="4,6,0,0"
-                              IsChecked="{Binding AddIdentComment}"/>
-                    <StackPanel Orientation="Vertical" Margin="10,6,0,0">
-                        <TextBlock Text="Put labels on their own line..."/>
-                        <RadioButton GroupName="labelLineGroup" Margin="0,4,0,0"
-                                     Content="Only when required"
-                                     IsChecked="{Binding LabelPlacement_PreferSameLine}"/>
-                        <RadioButton GroupName="labelLineGroup" Margin="0,4,0,0"
-                                     Content="When the label is wider than the field"
-                                     IsChecked="{Binding LabelPlacement_SplitIfTooLong}"/>
-                        <RadioButton GroupName="labelLineGroup" Margin="0,4,0,0"
-                                     Content="Whenever possible"
-                                     IsChecked="{Binding LabelPlacement_PreferSeparateLine}"/>
-                    </StackPanel>
+                    <GroupBox Header="Code Generation Settings" Padding="2,4" Margin="0,8,0,0">
+                        <StackPanel>
+                            <CheckBox Content="Show cycle counts in comments"
+                                      IsChecked="{Binding ShowCycleCountsAsm}"/>
+                            <CheckBox Content="Identify assembler in output" Margin="0,4,0,0"
+                                      IsChecked="{Binding AddIdentComment}"/>
+                            <StackPanel Orientation="Vertical" Margin="0,6,0,0">
+                                <TextBlock Text="Put labels on their own line..."/>
+                                <RadioButton GroupName="labelLineGroup" Margin="4,4,0,0"
+                                             Content="Only when required"
+                                             IsChecked="{Binding LabelPlacement_PreferSameLine}"/>
+                                <RadioButton GroupName="labelLineGroup" Margin="4,4,0,0"
+                                             Content="When the label is wider than the field"
+                                             IsChecked="{Binding LabelPlacement_SplitIfTooLong}"/>
+                                <RadioButton GroupName="labelLineGroup" Margin="4,4,0,0"
+                                             Content="Whenever possible"
+                                             IsChecked="{Binding LabelPlacement_PreferSeparateLine}"/>
+                            </StackPanel>
+                        </StackPanel>
+                    </GroupBox>
                 </StackPanel>
             </TabItem>
 
diff --git a/docs/sgmanual/index.html b/docs/sgmanual/index.html
index 1b241fc3..652e7fb0 100644
--- a/docs/sgmanual/index.html
+++ b/docs/sgmanual/index.html
@@ -149,9 +149,9 @@ <h2>Contents</h2>
     <ul>
       <li><a href="settings.html#appset-codeview">Code View</a></li>
       <li><a href="settings.html#appset-textdelim">Text Delimiters</a></li>
-      <li><a href="settings.html#appset-asmconfig">Asm Config</a></li>
       <li><a href="settings.html#appset-displayformat">Display Format</a></li>
       <li><a href="settings.html#appset-pseudoop">Pseudo-Op</a></li>
+      <li><a href="settings.html#appset-asmconfig">Asm Config</a></li>
     </ul></li>
     <li><a href="settings.html#project-properties">Project Properties</a>
     <ul>
diff --git a/docs/sgmanual/settings.html b/docs/sgmanual/settings.html
index e7d3f2d5..f2e0f737 100644
--- a/docs/sgmanual/settings.html
+++ b/docs/sgmanual/settings.html
@@ -30,7 +30,7 @@ <h2 id="app-settings">Application Settings</h2>
 affect the way the project analyzes code and data, though they may affect
 the way generated assembly sources look.</p>
 
-<p>The settings editor is divided into four tabs.  Changes don't take
+<p>The settings editor is divided into five tabs.  Changes don't take
 effect until you hit <samp>Apply</samp> or <samp>OK</samp>.</p>
 
 
@@ -84,6 +84,10 @@ <h3 id="appset-codeview">Code View</h3>
 
 <h3 id="appset-textdelim">Text Delimiters</h3>
 
+<p>These options change the way the code list looks on screen.  They
+do not affect generated code, which must use the delimiter characters
+specified by the chosen assembler.</p>
+
 <p>Character and string operands are shown surrounded by quotes, e.g.
 <code>LDA #'*'</code> or <code>.STR "Hello, world!"</code>.  It's
 handy to be able to tell at a glance how characters are encoded, so
@@ -92,8 +96,8 @@ <h3 id="appset-textdelim">Text Delimiters</h3>
 <p>String operands may contain a mixture of text and hexadecimal values.
 For example, in ASCII data, the control characters for linefeed and
 carriage return ($0a and $0d) are considered part of the string, but
-don't have a printable symbol.  (Unicode defines some glpyhs, but they
-don't look very good at smaller font sizes.)</p>
+don't have a printable symbol.  (Unicode defines some "control picture"
+glyphs, but they don't look very good at smaller font sizes.)</p>
 <p>If one of the delimiter characters appears in the string itself,
 the character will be output as hex to avoid confusion.  For this
 reason, it's generally wise to use delimiter characters that aren't
@@ -104,9 +108,6 @@ <h3 id="appset-textdelim">Text Delimiters</h3>
 <p>For character operands, the prefix and suffix are added to the start
 and end of the operand.  For string operands, the prefix is added to the
 start of the first line, and suffixes aren't allowed.</p>
-<p>These options change the way the code list looks on screen.  They
-do not affect generated code, which must use the delimiter characters
-specified by the chosen assembler.</p>
 
 <p>The "quick set" pop-up can be used to set the fields for a few
 common configurations.  The default set uses curly quotes with a few
@@ -189,9 +190,9 @@ <h3 id="appset-asmconfig">Asm Config</h3>
 <p>These settings configure cross-assemblers and modify assembly source
 generation in various ways.</p>
 <p>To configure an assembler, select it in the pop-up menu.  The fields
-will initially contain assembler-specific default values.  All of
-the values in the Assembler Configuration box may be configured
-differently for each assembler.</p>
+will initially contain assembler-specific default values.  The values
+in the Assembler-Specific Configuration box may be configured
+independently for each assembler.</p>
 <p>The "executable" box holds the full path to the cross-assembler
 executable.</p>
 <ul>
@@ -208,6 +209,8 @@ <h3 id="appset-asmconfig">Asm Config</h3>
 of the next column will be pushed over.  (The comment field width is
 not currently being used, but may be used to fold lines in the future.)</p>
 
+<p>The Code Generation Settings affect all assemblers.</p>
+
 <p>When <samp>show cycle counts in comments</samp> is checked, cycle
 counts are inserted into end-of-line comments.  This works the same as
 the option in the <samp>Code View</samp> tab, but applies to generated
@@ -328,8 +331,9 @@ <h3 id="projprop-general">General</h3>
 this setting will determine which encoding is preferred in generated
 sources.</p>
 <p>The <samp>min chars for string detection</samp> setting determines how
-many ASCII characters need to appear consecutively for the data analyzer to
-declare it a string.  Shorter values are prone to false-positive
+many printable characters (based on the default text encoding setting)
+need to appear consecutively for the data analyzer to
+decide it's a string.  Shorter values are prone to false-positive
 identifications, longer values miss out on short strings.  You can also
 set it to "none" to disable automatic string identification.</p>
 <p>The <samp>auto-label style</samp> setting determines the format for