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.
-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.)
+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, -so cc65 code uses ";*' instead. Because the length limitation affects -the length of the line, not just the comment text, an asterisk-boxed -comment will have one fewer character per line in cc65 output.
+Merlin allows a leading '*' to indicate a full-line comment, while most +others use ";'.Clear the text field to delete the comment.
You can use Ctrl+Enter as a keyboard shortcut @@ -388,6 +382,88 @@
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 +Enable Fancy Formatting checkbox.
+ +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 +Render In Box checkbox.
+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.
+Within a box, putting '*' on a line by itself causes a full line of +asterisks to be output.
+ +If fancy formatting is enabled, the width and box controls are disabled +in the dialog. The features are available with embedded formatting +commands.
+The supported tags are:
+[width=nn]: 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.[br]: breaks up the output with a totally blank line.
+ The line won't even have a comment delimiter.[box]...[/box]: formats the text inside the tags in
+ a box. The box frame will be composed of comment delimiters (usually
+ ';' or '*').[box char='#']: alternate form of [box]
+ 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.[hr]: outputs a horizontal line of characters, using
+ the comment char.[hr char='-']: outputs a horizontal line of characters,
+ using the specified char.[url]https://example.com/[/url]: outputs a URL.[url=https://example.com/]link text[/url]: outputs
+ the link text followed by the URL.The width and br tags are not allowed in
+boxes, but the hr and url tags are.
For example, the text:
++[width=20][box] +Hello, world! +[hr char='-'] +The quick brown fox jumps over the lazy dog. +[/box] ++
will be formatted as:
++******************** +* Hello, world! * +*------------------* +* The quick brown * +* fox jumps over * +* the lazy dog. * +******************** ++ +
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. "\[br]" will appear in the output as
+"[br]".
A quick reference for the format tags can be accessed with the +Format Help button.
+ +Sets the Data Bank Register (DBR) value for 65816 code. This is used diff --git a/docs/sgtutorial/images/t1-edit-long-comment.png b/docs/sgtutorial/images/t1-edit-long-comment.png index f4b81e26..36be0d1f 100644 Binary files a/docs/sgtutorial/images/t1-edit-long-comment.png and b/docs/sgtutorial/images/t1-edit-long-comment.png differ diff --git a/docs/sgtutorial/making-edits.html b/docs/sgtutorial/making-edits.html index 2b86eb7f..0dbf8ecd 100644 --- a/docs/sgtutorial/making-edits.html +++ b/docs/sgtutorial/making-edits.html @@ -111,8 +111,7 @@
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" - settings to see what they do. You can hit Enter to create line breaks, + window. You can hit Enter to create line breaks, or let SourceGen wrap lines for you. When you're done, click OK. (Or hit Ctrl+Enter.)
When the dialog closes, you'll see your new comment in place at the