Fancy comments, part 5 (of 5)

Added a "format help" button to the long comment edit window.  This
brings up a quick summary of the format tags in a modal dialog.

Updated documentation and tutorial.

SourceGen/SGTestData/20090-notes-and-comments.dis65

@@ -167,7 +167,7 @@
 "BackgroundColor":0},
 
 "115":{
-"Text":"[BOX]ALL CAPS [URL=HTTPS://EXAMPLE.COM/]FOR EVERYTHING[/URL][HR][/BOX]\r\n[BR]\r\n[WIDTH=10]SHORT LINES\r\n[BOX CHAR=\u0027X\u0027]BOXED[/BOX]\r\n",
+"Text":"[BOX]ALL CAPS [URL=HTTPS://EXAMPLE.COM/]FOR EVERYTHING[/URL][HR][/BOX]\r\n[BR]\r\n[WIDTH=10]SHORT LINES\r\n[BOX CHAR=\u0027X\u0027]BOXED[HR CHAR=\u0027-\u0027]STUFF[/BOX]\r\n",
 "IsFancy":true,
 "BoxMode":false,
 "MaxWidth":80,

SourceGen/SGTestData/Expected/20090-notes-and-comments_64tass.S

@@ -170,6 +170,8 @@ L1062   bit     plataddr   ;Pull in plataddr to see the comment on the platform
 ;LINES
 ;XXXXXXXXX
 ;X BOXED X
+;X-------X
+;X STUFF X
 ;XXXXXXXXX
         lda     #$17
 ;Test some folding

SourceGen/SGTestData/Expected/20090-notes-and-comments_acme.S

@@ -168,6 +168,8 @@ L1062   bit     plataddr   ;Pull in plataddr to see the comment on the platform
 ;LINES
 ;XXXXXXXXX
 ;X BOXED X
+;X-------X
+;X STUFF X
 ;XXXXXXXXX
         lda     #$17
 ;Test some folding

SourceGen/SGTestData/Expected/20090-notes-and-comments_cc65.S

@@ -170,6 +170,8 @@ L1062:   bit     plataddr   ;Pull in plataddr to see the comment on the platform
 ;LINES
 ;XXXXXXXXX
 ;X BOXED X
+;X-------X
+;X STUFF X
 ;XXXXXXXXX
          lda     #$17
 ;Test some folding

SourceGen/SGTestData/Expected/20090-notes-and-comments_merlin32.S

@@ -165,6 +165,8 @@ L1062    bit   plataddr   ;Pull in plataddr to see the comment on the platform f
 *LINES
 *XXXXXXXXX
 *X BOXED X
+*X-------X
+*X STUFF X
 *XXXXXXXXX
          lda   #$17
 *Test some folding

SourceGen/Tools/WpfGui/ShowText.xaml.cs

@@ -66,6 +66,7 @@ namespace SourceGen.Tools.WpfGui {
         private void Window_KeyEventHandler(object sender, KeyEventArgs e) {
             if (e.Key == Key.Escape) {
                 Close();
+                e.Handled = true;
             }
         }
     }

SourceGen/WpfGui/EditLongComment.xaml

@@ -82,9 +82,10 @@ limitations under the License.
                  FontFamily="{StaticResource GeneralMonoFont}" VerticalScrollBarVisibility="Visible"
                  IsReadOnly="True" Background="#f8f8f8"/>
 
-        <StackPanel Grid.Row="5" Orientation="Horizontal" HorizontalAlignment="Right" Margin="0,8,0,0">
+        <DockPanel Grid.Row="5" LastChildFill="False" Margin="0,8,0,0">
-            <Button Content="OK" IsDefault="True" Width="70" Click="OkButton_Click"/>
+            <Button Content="Format Help" DockPanel.Dock="Left" Width="100" Click="FormatHelp_Click"/>
-            <Button Content="Cancel" IsCancel="True" Width="70" Margin="4,0,0,0"/>
+            <Button Content="Cancel" DockPanel.Dock="Right" IsCancel="True" Width="70" Margin="4,0,0,0"/>
-        </StackPanel>
+            <Button Content="OK" DockPanel.Dock="Right" IsDefault="True" Width="70" Click="OkButton_Click"/>
+        </DockPanel>
     </Grid>
 </Window>

SourceGen/WpfGui/EditLongComment.xaml.cs

@@ -197,5 +197,27 @@ namespace SourceGen.WpfGui {
             return new MultiLineComment(UserInput, IsFancyEnabled, RenderInBox,
                 (int)maxWidthComboBox.SelectedItem);
         }
+
+        private const string HELP_TEXT =
+            "Fancy formatting tags:\r\n" +
+            "  [width=nn] sets the width to the specified value; '*' sets to default (80).\r\n" +
+            "  [br] breaks up the output with a totally blank line.\r\n" +
+            "  [box]...[/box] puts text in a box, using the comment char for the frame.\r\n" +
+            "  [box char='#']...[/box] puts text in a box, using the specified char.\r\n" +
+            "  [hr] outputs a horizontal line of characters, using the comment char.\r\n" +
+            "  [hr char='-'] outputs a horizontal rule, using the specified char.\r\n" +
+            "  [url]https://example.com/[/url] outputs a URL.\r\n" +
+            "  [url=https://example.com/]link text[/url] outputs a URL with separate link text.\r\n" +
+            "\r\n" +
+            "[width=nn] and [br] are not allowed in boxes, but [hr] and [url] are.\r\n" +
+            "\r\n" +
+            "If fancy mode is disabled, the Line Width and Render In Box controls are enabled,\r\n" +
+            "and will be used to format the text.  Formatting tags are ignored.\r\n";
+
+        private void FormatHelp_Click(object sender, RoutedEventArgs e) {
+            Tools.WpfGui.ShowText dialog = new Tools.WpfGui.ShowText(this, HELP_TEXT);
+            dialog.Title = "Format Help";
+            dialog.ShowDialog();
+        }
     }
 }

docs/sgmanual/editors.html

@@ -361,24 +361,18 @@ editor.</p>
 
 
 <h2 id="long-comment">Edit Long Comment</h2>
+
 <p>Long comments can be arbitrarily long and span multiple lines.  They
 will be word-wrapped at a line width of your choosing.  They're always
 drawn with a fixed-width font, so you can create ASCII-art diagrams.
 Comment delimiters are added automatically at the start of each line.</p>
-<p>For a true retro look you can "box" the comment with asterisks.  You
+
-can create a full-width row of asterisks by putting a '*' on a line by
-itself.  (Assembly source generators are allowed to use a character
-other than '*' for the output, e.g. they might use a full set of
-box outline characters, though that's somewhat against the spirit of
-the thing.  Regardless, a solo '*' results in a line.)</p>
 <p>The bottom window will update automatically as you type, showing what
 the output is expected to look like.  The actual assembler source output
 will depend on features of the target assembler, such as comment
 delimiter choices and maximum line length limitations.  For example,
-Merlin allows a leading '*' to indicate a comment, while cc65 does not,
+Merlin allows a leading '*' to indicate a full-line comment, while most
-so cc65 code uses ";*' instead.  Because the length limitation affects
+others use ";'.</p>
-the length of the line, not just the comment text, an asterisk-boxed
-comment will have one fewer character per line in cc65 output.</p>
 
 <p>Clear the text field to delete the comment.</p>
 <p>You can use <kbd class="key">Ctrl+Enter</kbd> as a keyboard shortcut
@@ -388,6 +382,88 @@ for <samp>OK</samp>.</p>
 not associated with a file offset.  If you delete it, you can get it
 back by using <samp>Edit &gt; Edit Header Comment</samp>.</p>
 
+<p>Recent versions of SourceGen support "fancy" formatting tags, which
+are embedded in the comment like BBCode or HTML.  You can choose to
+use "classic" or "fancy" formatting by clicking the
+<samp>Enable Fancy Formatting</samp> checkbox.</p>
+
+<h3>Classic Formatting</h3>
+
+<p>If fancy formatting is disabled, you can set the line width for the
+comment block from the choices in the pop-up menu.  If you want to
+wrap the comment in a box of asterisks, check the
+<samp>Render In Box</samp> checkbox.</p>
+<p>For boxed text, most assemblers don't accept '*' as a full-line comment
+delimiter, so the actual delimiter will be output at the start of each
+line.  This reduces the width of the box by 1 for those assemblers and
+the on-screen display.</p>
+<p>Within a box, putting '*' on a line by itself causes a full line of
+asterisks to be output.</p>
+
+<h3>Fancy Formatting</h3>
+
+<p>If fancy formatting is enabled, the width and box controls are disabled
+in the dialog.  The features are available with embedded formatting
+commands.</p>
+<p>The supported tags are:</p>
+<ul>
+  <li><code>[width=nn]</code>: sets the line width to the specified value.
+    The minimum width is 8, maximum is 128.  The special value '*' sets
+    the width to the default (80).  This is the total width of the output,
+    so the actual text width will be slightly smaller because of comment
+    delimiters and box edges.</li>
+  <li><code>[br]</code>: breaks up the output with a totally blank line.
+    The line won't even have a comment delimiter.</li>
+  <li><code>[box]...[/box]</code>: formats the text inside the tags in
+    a box.  The box frame will be composed of comment delimiters (usually
+    '<code>;</code>' or '<code>*</code>').</li>
+  <li><code>[box char='#']</code>: alternate form of <code>[box]</code>
+    that allows the frame character to be specified.  Because lines will
+    need to be prefixed with a comment delimiter, the box width is
+    reduced by one.  If the specified character happens to match the
+    comment delimiter, the comment delimiter will be omitted, but the
+    width will still be reduced so that the inside of the box is the same
+    width regardless of assembler configuration.</li>
+  <li><code>[hr]</code>: outputs a horizontal line of characters, using
+    the comment char.</li>
+  <li><code>[hr char='-']</code>: outputs a horizontal line of characters,
+    using the specified char.</li>
+  <li><code>[url]https://example.com/[/url]</code>: outputs a URL.</li>
+  <li><code>[url=https://example.com/]link text[/url]</code>: outputs
+    the link text followed by the URL.</li>
+</ul>
+
+<p>The <code>width</code> and <code>br</code> tags are not allowed in
+boxes, but the <code>hr</code> and <code>url</code> tags are.</p>
+
+<p>For example, the text:</p>
+<pre>
+[width=20][box]
+Hello, world!
+[hr char='-']
+The quick brown fox jumps over the lazy dog.
+[/box]
+</pre>
+<p>will be formatted as:</p>
+<pre>
+********************
+* Hello, world!    *
+*------------------*
+* The quick brown  *
+* fox jumps over   *
+* the lazy dog.    *
+********************
+</pre>
+
+<p>Incomplete or malformed format tags will be output as written.  To
+avoid confusing the parser, the left bracket can be escaped with a
+backslash, e.g. "<code>\[br]</code>" will appear in the output as
+"<code>[br]</code>".</p>
+
+<p>A quick reference for the format tags can be accessed with the
+<samp>Format Help</samp> button.</p>
+
+
 <h2 id="data-bank">Edit Data Bank (65816 only)</h2>
 
 <p>Sets the Data Bank Register (DBR) value for 65816 code.  This is used

docs/sgtutorial/making-edits.html

@@ -111,8 +111,7 @@
     <div class="grid-item-text">
         <p>Double-click the comment to open the editor.  Type some words into the
         upper window, and note that a formatted version appears in the bottom
-        window.  Experiment with the maximum line width and "render in box"
+        window.  You can hit Enter to create line breaks,
-        settings to see what they do.  You can hit Enter to create line breaks,
         or let SourceGen wrap lines for you.  When you're done, click <samp>OK</samp>.
         (Or hit <kbd class="key">Ctrl+Enter</kbd>.)</p>
         <p>When the dialog closes, you'll see your new comment in place at the