docs(ref): Specify frontmatter #1974
Conversation
| @@ -8,6 +8,7 @@ | |||
| - [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
| @@ -8,6 +8,7 @@ | |||
| - [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
| 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.
| FRONTMATTER? | ||
| InnerAttribute* | ||
| Item* |
There was a problem hiding this comment.
Despite shebang's not having being here, I assumed I should put FRONTMATTER here
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
| @@ -4,6 +4,7 @@ r[crate] | |||
| 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
Tracking issue: rust-lang/rust#136889