docs(ref): Specify frontmatter

[epage]

Tracking issue: rust-lang/rust#136889

[epage]

Not stable yet: rust-lang/rust#136889

[epage]

I put this under "Lexical structure" because this shebang is there

[epage]

I used comments as my guide which were mostly SCREAMING_CASE. Unsure when things should be SCREAMING_CASE vs UpperCamelCase.

[epage]

Despite shebang's not having being here, I assumed I should put FRONTMATTER here

[mattheww]

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.

[epage]

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.

[epage]

This follows the RFC rather than rustc's current implementation, see rust-lang/rust#141367

[epage]

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.

[epage]

Was unsure whether to create a new rule for non-newline whitespace and specify that in every location or not.

[epage]

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.

[epage]

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.