docs(style): Specify the frontmatter style

[epage]

Taken from a style team discussion.

Assumptions on my part:

• I specify that frontmatter fences should not have trailing whitespace
• We aren't specifying when to include the infostring (one idea being if there is no shebang)
• Keep it simple and have a single example instead of showing allowed several variations

Tracking issue: #136889

Closes rust-lang/style-team#212

[rustbot]

r? @calebcartwright

rustbot has assigned @calebcartwright.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

[rustbot]

Some changes occurred in src/doc/style-guide

cc @rust-lang/style

[epage]

CC @calebcartwright

From rust-lang/style-team#212 (comment)

Before anything else, let's confirm if @calebcartwright is in agreement with the above.

[joshtriplett]

I don't need to specify the lack of trailing spaces after the code fence / infostring

We don't actually have a general specification of that anywhere (just one specific to doc comments), so it may be worth specifying, until we add a more general prohibition.

We aren't specifying when to include the infostring (one idea being if there is no shebang)

I don't think we should specify whether to include or exclude the infostring; that's outside the scope of formatting (at least, until a hypothetical future in which we know how to format certain types of infostrings).

Keep it simple and have a single example instead of showing allowed several variations

Seems fine.

[traviscross]

We don't actually have a general specification of that anywhere (just one specific to doc comments), so it may be worth specifying, until we add a more general prohibition.

Agreed. I'd want rustfmt to normalize out trailing spaces.

[joshtriplett]

#145735

[rustbot]

This PR was rebased onto a different master commit. Here's a range-diff highlighting what actually changed.

Rebasing is a normal part of keeping PRs up to date, so no action is needed—this note is just to help reviewers.

[traviscross]

Let's do it. In particular, we're deciding to accept the following set of decisions, from rust-lang/style-team#212 (comment):

1. The Style Guide should require zero blank lines before frontmatter. (That's true whether there's a shebang or not.)

2. The Style Guide should require normalizing blank lines after frontmatter to reduce more-than-one blank line down to one blank line, but should allow either zero or one blank lines after frontmatter, without prescribing whether it should be zero or one. (For precedent here, we're using the current handling of blank lines around inner/outer doc comments.)

3. The Style Guide should require exactly one space between the opening dashes and the infostring. Looking at many examples, this felt substantially different from markdown's triple-backquotes, which didn't feel "attached" to the infostring. Dashes feel more "attached" to the infostring, perhaps because of mental lexing of command-line options. This also seemed better for infostrings that look like filenames (e.g. starting with a / or .). We initially were inclined to allow zero-or-one, or even normalize to zero, but then we looked at actual code in context in a code editor rather than on github or markdown, and rapidly changed our minds because zero spaces felt wrong.

4. The Style Guide should require normalizing the number of matching dashes before and after the frontmatter to the minimum number needed to unambiguously delimit the frontmatter. (For instance, use 4 dashes if the frontmatter contains 3 dashes.)

@rfcbot fcp merge

[rust-rfcbot]

Team member @traviscross has proposed to merge this. The next step is review by the rest of the tagged team members:

• @calebcartwright
• @joshtriplett
• @traviscross

No concerns currently listed.

Once a majority of reviewers approve (and at most 2 approvals are outstanding), this will enter its final comment period. If you spot a major issue that hasn't been raised at any point in this process, please speak up!

See this document for info about what commands tagged team members can give me.

[rust-rfcbot]

🔔 This is now entering its final comment period, as per the review above. 🔔

[rust-rfcbot]

The final comment period, with a disposition to merge, as per the review above, is now complete.

As the automated representative of the governance process, I would like to thank the author for their work and everyone else who contributed.

This will be merged soon.

[traviscross]

Most of the style guide is consistently wrapped at 80 columns. The remainder of this chapter, though, is not hard wrapped at all. It seems we should do one of the two.

@joshtriplett, do you have thoughts about the style guide for the style guide?

[calebcartwright]

I don't think it's ever anything that's been enforced (once upon a time before the style guide was in this repo I'd merge text and modify it after versus asking the author).

If we are going to try to maintain consistency then maybe it could be incorporated into the tidy checks someday?

For now my .02 would be to proceed and circle back to it if/when we make that decision

[traviscross]

(once upon a time before the style guide was in this repo I'd merge text and modify it after versus asking the author).

Similarly to that, we could push a commit ourselves to this branch doing it, then merge it.

[traviscross]

I don't think it's ever anything that's been enforced...

I had looked through all the chapters before asking. They're mostly wrapped at 80, with a handful of sections wrapped closer to 90 or 95, and then there's the types chapter where two sections are unwrapped and the nightly chapter that is unwrapped.