Right now, long comments can be boxed or open, i.e.:
***************************
* This is boxed. *
***************************
or
Each comment is a contiguous block in the generated sources. Because comments are associated with file offsets, you can't have two in a row.
What I'd like to do is fake it by having some way to specify that a line should be left totally blank. For example:
; This is comment #1.
; This is also comment #1, but it looks like comment #2.
This gives the same aesthetic benefits as having multiple comments, or allowing the user to insert blank lines, without actually changing the way things are put together.
The question is how to specify it. Once you start down this road, a bunch of other possibilities spring to mind. For example, we could define a set of embedded codes that would do things like:
- Indicate that a line should be completely blank.
- Start or stop "boxed" mode.
- Specify that a line of asterisks should be printed (currently, in box mode, you just put a '*' on a line by itself).
- Change the width (affects boxing and line-wrap).
- Specify that text is a URL, for the benefit of the HTML exporter.
- Change text or background color, for the HTML exporter. (I feel like this could go badly for the world.)
- Note that a word is a symbol, so that the refactoring rename updates it automatically when you rename the symbol.
This feels a lot like BBCode, which I'm not overly fond of, but is relatively simple to handle.
Additional ruminations...
Steam game guides use a similar system, with [bracketed]stuff[/bracketed] for formatting. So it's certainly a proven approach.
For backward compatibility and simplicity we'd probably want to have an "enable fancy formatting" checkbox. If not checked, you get the old format style.
The refactoring-rename symbol reference is probably the most practically useful thing in the list, since it allows you to discuss symbols without worrying about them getting renamed, but it's also the hardest thing to get right. The other items are either purely string formatting items, or things that only the HTML converter cares about.
So the BBCode / Steam approach would be:
- Plain text is just flowed normally.
- [width=40] sets the line-wrap width to 40.
- [box] starts a box that maxes out the current line width; [/box] ends it.
- [boxchar='#'] sets the box character to '#' (default '*').
- [blank] on a line by itself adds a blank line.
- [url=example.com]website link[/url], which formats with the URL showing in text output mode, but forms a proper link in HTML output mode.
If we want to get fancy:
- [symbol]MySym[/symbol] would get updated during a rename.
We currently allow a little flex in assembly source generation, because some assemblers may want to format things a little differently. For example, some assemblers allow '*' box comments to be on a line by themselves, while others require them to start with a ';', which effectively reduces the line width by one character. We don't guarantee WYSIWYG. We may want to force consistency by formatting with the expectation that a leading ';' is required, which would convert an 80-column box to be 79 everywhere.
Right now, long comments can be boxed or open, i.e.:
or
Each comment is a contiguous block in the generated sources. Because comments are associated with file offsets, you can't have two in a row.
What I'd like to do is fake it by having some way to specify that a line should be left totally blank. For example:
This gives the same aesthetic benefits as having multiple comments, or allowing the user to insert blank lines, without actually changing the way things are put together.
The question is how to specify it. Once you start down this road, a bunch of other possibilities spring to mind. For example, we could define a set of embedded codes that would do things like:
This feels a lot like BBCode, which I'm not overly fond of, but is relatively simple to handle.
Additional ruminations...
Steam game guides use a similar system, with [bracketed]stuff[/bracketed] for formatting. So it's certainly a proven approach.
For backward compatibility and simplicity we'd probably want to have an "enable fancy formatting" checkbox. If not checked, you get the old format style.
The refactoring-rename symbol reference is probably the most practically useful thing in the list, since it allows you to discuss symbols without worrying about them getting renamed, but it's also the hardest thing to get right. The other items are either purely string formatting items, or things that only the HTML converter cares about.
So the BBCode / Steam approach would be:
If we want to get fancy:
We currently allow a little flex in assembly source generation, because some assemblers may want to format things a little differently. For example, some assemblers allow '*' box comments to be on a line by themselves, while others require them to start with a ';', which effectively reduces the line width by one character. We don't guarantee WYSIWYG. We may want to force consistency by formatting with the expectation that a leading ';' is required, which would convert an 80-column box to be 79 everywhere.