docs(ref): Specify frontmatter #1974
Conversation
| - [Input format](input-format.md) | ||
| - [Keywords](keywords.md) | ||
| - [Identifiers](identifiers.md) | ||
| - [Frontmatter](frontmatter.md) |
There was a problem hiding this comment.
Not stable yet: rust-lang/rust#136889
| - [Input format](input-format.md) | ||
| - [Keywords](keywords.md) | ||
| - [Identifiers](identifiers.md) | ||
| - [Frontmatter](frontmatter.md) |
There was a problem hiding this comment.
I put this under "Lexical structure" because this shebang is there
src/crates-and-source-files.md
Outdated
| FRONTMATTER? | ||
| InnerAttribute* | ||
| Item* |
There was a problem hiding this comment.
I used comments as my guide which were mostly SCREAMING_CASE. Unsure when things should be SCREAMING_CASE vs UpperCamelCase.
src/crates-and-source-files.md
Outdated
| FRONTMATTER? | ||
| InnerAttribute* | ||
| Item* |
There was a problem hiding this comment.
Despite shebang's not having being here, I assumed I should put FRONTMATTER here
There was a problem hiding this comment.
The reason shebang isn't there is that shebangs are ignored at the start of any file, not just in the file which defines a crate.
If that's true for frontmatter too, input-format.md might be a better place to say how frontmatter.md fits in.
There was a problem hiding this comment.
This is a bit confusing.
input-format.md is specifically under the section for lexical analysis.
crates-and-source-files.md includes what looks like its the AST but its specifically scoped to the crate root. r[crate-items] talks generally about any rust source file.
So, like shebang, I'll leave this out but this feels like something that could be cleaned up.
src/frontmatter.md
Outdated
| r[frontmatter.body] | ||
| The body of the frontmatter may contain any content except for a line starting with as many or more dashes (`-`) than in the fences. |
There was a problem hiding this comment.
This follows the RFC rather than rustc's current implementation, see rust-lang/rust#141367
| # Crates and source files | ||
|
|
||
| r[crate.syntax] | ||
| ```grammar,items |
There was a problem hiding this comment.
Aside: it took me a while before I found the appropriate documentation for this.
I quickly went to CONTRIBUTING.md but skipped over the link to the authoring page because it was at the end of the intro. I skimmed the sections until I found "Adding Documentation" which seemed to describe my situation but I found no link.
Eventually I found authoring.md and thankfully I read thoroughly enough to notice the "Grammar" section at the bottom. At that point, I was mostly able to interpret the results to figure out what I needed (e.g. the limitations of ~, what to search for to understand how to do footnotes).
As noted at https://github.com/rust-lang/reference/pull/1974/files#r2292171963, it doesn't really give a style guidance on casing.
src/frontmatter.md
Outdated
| FRONTMATTER -> | ||
| FRONTMATTER_FENCE INFOSTRING? LF | ||
| (FRONTMATTER_LINE LF )* | ||
| FRONTMATTER_FENCE[^matched-fence] LF | ||
| FRONTMATTER_FENCE -> `---` `-`* | ||
| INFOSTRING -> XID_Start ( XID_Continue | `.` )* | ||
| FRONTMATTER_LINE -> (~INVALID_FRONTMATTER_LINE_START (~INVALID_FRONTMATTER_LINE_CONTINUE)*)? | ||
| INVALID_FRONTMATTER_LINE_START -> (FRONTMATTER_FENCE[^escaped-fence] | LF) | ||
| INVALID_FRONTMATTER_LINE_CONTINUE -> LF |
There was a problem hiding this comment.
Was unsure whether to create a new rule for non-newline whitespace and specify that in every location or not.
ehuss
added
the
S-waiting-on-stabilization
epage
force-pushed
the
frontmatter
branch
2 times, most recently
from
161b0fa to
61afc85
Compare
src/frontmatter.md
Outdated
| FRONTMATTER -> | ||
| FRONTMATTER_FENCE INFOSTRING? LF | ||
| (FRONTMATTER_LINE LF )* | ||
| FRONTMATTER_FENCE[^matched-fence] LF | ||
| FRONTMATTER_FENCE -> `---` `-`* | ||
| INFOSTRING -> (XID_Start | `_`) ( XID_Continue | `-` | `.` )* | ||
| FRONTMATTER_LINE -> (~INVALID_FRONTMATTER_LINE_START (~INVALID_FRONTMATTER_LINE_CONTINUE)*)? | ||
| INVALID_FRONTMATTER_LINE_START -> (FRONTMATTER_FENCE[^escaped-fence] | LF) | ||
| INVALID_FRONTMATTER_LINE_CONTINUE -> LF |
There was a problem hiding this comment.
Thinking more on this, I feel like I should be explicit where frontmatter whitespace is allowed.
I assume I should then pull out a whitespace grammar rule to build on that.
src/frontmatter.md
Outdated
| FRONTMATTER -> | ||
| FRONTMATTER_FENCE INFOSTRING? LF | ||
| (FRONTMATTER_LINE LF )* | ||
| FRONTMATTER_FENCE[^matched-fence] LF | ||
| FRONTMATTER_FENCE -> `---` `-`* | ||
| INFOSTRING -> (XID_Start | `_`) ( XID_Continue | `-` | `.` )* | ||
| FRONTMATTER_LINE -> (~INVALID_FRONTMATTER_LINE_START (~INVALID_FRONTMATTER_LINE_CONTINUE)*)? | ||
| INVALID_FRONTMATTER_LINE_START -> (FRONTMATTER_FENCE[^escaped-fence] | LF) | ||
| INVALID_FRONTMATTER_LINE_CONTINUE -> LF |
There was a problem hiding this comment.
Something that i don't make explicit is CR. In most places that can be chalked up to whitespace except for INVALID_FRONTMATTER_LINE_START and INVALID_FRONTMATTER_LINE_CONTINUE.
I created productions for `END_OF_LINE`, `IGNORABLE_CODE_POINT`, and `HORIZONTAL_WHITESPACE` as that is how the unicode standard is written and in preparation for rust-lang#1974 which will make use of `HORIZONTAL_WHITESPACE`
I created productions for `END_OF_LINE`, `IGNORABLE_CODE_POINT`, and `HORIZONTAL_WHITESPACE` as that is how the unicode standard is written and in preparation for rust-lang#1974 which will make use of `HORIZONTAL_WHITESPACE`
This does not create any new productions, instead preferring comments. rust-lang#1974 will involve pulling out the horizontal whitespace into a separate production. Comment wording (and casing) is modeled off of https://www.unicode.org/reports/tr31/#R3a. I left off a "unicode" prefix for ASCII items as they are likely common enough in that context that specifying them as "unicode" could cause more confusion.
This does not create any new productions, instead preferring comments. rust-lang#1974 will involve pulling out the horizontal whitespace into a separate production. Comment wording (and casing) is modeled off of https://www.unicode.org/reports/tr31/#R3a. I left off a "unicode" prefix for ASCII items as they are likely common enough in that context that specifying them as "unicode" could cause more confusion.
traviscross
added
the
S-waiting-on-review
This reverts commit 60eb145. This re-formats our Whitespace to be centered on Unicode's defintion. This makes it easy to compare with the standard and helps with Frontmatter. Unlike regular Rust, Frontmatter cares about the type of Whitespace. Even if we want to duplicate the definition, having them formatted similarly makes them easy to compare.
I'm splitting out `HORIZONTAL_WHITESPACE` to make it easier to connect the concept in frontmatter with `WHITESPACE`. In doing this, I found it awkward to only pull out part when the comments are there. I either needed a redundant comment to start a section, re-arrange out of order from Unicode, or split out all classes. I did the latter.
Tracking issue: rust-lang/rust#136889