Section Headers vs Comments

[kotfu]

I've begun work on a TextMate bundle for Bunch files, the grammer is coming along, but not quite finished. First of all, I'll offer Brett kudos on the excellent Bunch documentation. Writing a grammer from documentation is a really quick way to learn how good the documentation is, and in this case it's outstanding. While working on the grammer I discovered the following, which is really a plea for advice.

Section header documentation says it can start with a # and "whitespace is allowed after the first character". Maybe that could be interpreted to mean whitespace is allowed after the first character inside the brackets, however, the >-=# [Section] #=-< shows whitespace before the opening bracket.

Comments documentation says a line comment can start with # and must be followed by one or more spaces. If not at the beginning of a line, it must also be preceded by a space.

Experimentation shows that a line containing # [My Section] gets parsed as a section header. So does ###[My Section].

The request for advice: is it a feature or a bug that # [My Section] gets parsed as a section header? Or to ask it another way, should # [My Section] be parsed as a comment and #[My Section be parsed as a section header? If
feature, how would you suggest I distinguish that from a comment in the regular expressions of the grammer I'm writing? Look for open and closed brackets in the "comment" and if found, style it as a section header?

Piling on, if you can give a bit of guidance, I'll happily submit a PR for this documentation about snippet fragments.

The question: is it called a fragment, a partial snippet, or a section? All three are used. I lean towards calling them fragments. That would make the nouns:

• Snippet: a file not ending in .bunch that can be included in a Bunch file
• Fragment: a section of a snippet or a bunch file introduced by a Fragment Header and terminated by the end of the file or another Fragment Header
• Fragment Header: A line like ---[My Fragment]--- in a Bunch file or a Snippet
• Fragment Name: the string inbetween the brackets in a Fragment Header

Brett, what nouns would you prefer for these things?

[ttscoff]

I've begun work on a TextMate bundle for Bunch files,

That's awesome!

The request for advice: is it a feature or a bug that # [My Section] gets parsed as a section header? Or to ask it another way, should # [My Section] be parsed as a comment and #[My Section be parsed as a section header? If
feature, how would you suggest I distinguish that from a comment in the regular expressions of the grammer I'm writing? Look for open and closed brackets in the "comment" and if found, style it as a section header?

When a snippet is loaded without a fragment ID, the headers are treated as comments (i.e. ignored), so I guess it's kind of a feature. In the Sublime Text syntax definition I use this regex for the fragment header:

^((?:-{2,}|[=>#])[\-=># ]*)(\[)([^\]]+)(\])(.*$)

(Starts with --, =, >, or #, followed by any combination of those characters plus space, containing a pair of square brackets with at least one character between them.)

The comment regex:

(?: |^)(#+|/{2,})([^\[].*?)$

(Requires that the marker, either # or //, come at the very beginning of a line or following a space, and does not contain a square bracket as the first non-marker, non-space character. Looking at that now I realize it would catch # [id] as a comment, but I have the fragment regex at a higher priority, so that gets caught first. Might fix that in mine.

For scoping I would recommend treating the fragment headers like comments, but highlighting the square brackets. I'm using the following scopes for the captures in the first regex:

1. comment.line.snippet.divider.bunch
2. punctuation.definition.snippet.fragment.bunch
3. keyword.fragment.id.bunch
4. punctuation.definition.snippet.fragment.bunch
5. comment.line.snippet.divider.bunch

Piling on, if you can give a bit of guidance, I'll happily submit a PR for this documentation about snippet fragments.

The question: is it called a fragment, a partial snippet, or a section? All three are used. I lean towards calling them fragments. That would make the nouns:

* Snippet: a file not ending in `.bunch` that can be included in a Bunch file

* Fragment: a section of a snippet or a bunch file introduced by a Fragment Header and terminated by the end of the file or another Fragment Header

* Fragment Header: A line like `---[My Fragment]---` in a Bunch file or a Snippet

* Fragment Name: the string inbetween the brackets in a Fragment Header

Brett, what nouns would you prefer for these things?

Great question, and one that should definitely be clarified. Let's go with your suggestion and consistently use "Fragment". The only thing to add would be the '<Snippet#fragment' part of a snippet line. I tend to use "Fragment ID" when I'm talking about the #fragment in a snippet line (which comes from web URL lingo). But "Name" seems more understandable if we're going to use the same label for both the <snippet line and the fragment header. Open to thoughts on that. Also totally open to a PR on the docs if you're up for it, on both the Snippets page and the Terminology page.

Thanks!

[kotfu]

Happy to submit a PR for the docs. I've got a couple other minor changes I'll submit other PRs for too.