Skip to content

Update shebang#2192

Merged
traviscross merged 2 commits intorust-lang:masterfrom
ehuss:shebang
Mar 1, 2026
Merged

Update shebang#2192
traviscross merged 2 commits intorust-lang:masterfrom
ehuss:shebang

Conversation

@ehuss
Copy link
Contributor

@ehuss ehuss commented Feb 25, 2026

This updates the shebang description, primarily to add a grammar for it. It also reworks the rules so the introduction explains what this section is talking about, and placing specific behaviors in individual rules.

@rustbot rustbot added the S-waiting-on-review Status: The marked PR is awaiting review from a maintainer label Feb 25, 2026
This updates the shebang description, primarily to add a grammar for it.
It also reworks the rules so the introduction explains what this section
is talking about, and placing specific behaviors in individual rules.
@rustbot
Copy link
Collaborator

rustbot commented Mar 1, 2026

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.

The shebang section was rewritten to add a grammar and to restructure
the rules.  Let's improve some things editorially.

In this commit, we reorder the syntax explanation so that the
basic description (start and end) comes before the exception (the
`#![` disambiguation).  We replace the awkward "continues to and
including" with "extends through", convert the purpose clause into a
parenthetical, remove a stray blank line between the rule identifier
and the grammar block, and use the existing `[shebang]` link
definition so that the term links to Wikipedia.
@traviscross
Copy link
Contributor

Looks good; thanks.

@traviscross traviscross added this pull request to the merge queue Mar 1, 2026
Merged via the queue into rust-lang:master with commit 1d55d6d Mar 1, 2026
6 checks passed
@rustbot rustbot removed the S-waiting-on-review Status: The marked PR is awaiting review from a maintainer label Mar 1, 2026
traviscross added a commit that referenced this pull request Mar 4, 2026
The `r[frontmatter.document]` rule said "Frontmatter may only be
preceded by a shebang and whitespace", where the "and" could be
misread as requiring both a shebang and whitespace rather than listing
the set of things allowed to precede frontmatter.

Since we merged the shebang prose revision (#2192),
the shebang position rule now reads as a positive statement of where
the shebang may appear.  Let's follow the same pattern here: state
positively where frontmatter may appear rather than leaning on "only"
and a negative constraint.

In this commit, we rewrite the rule as "Frontmatter may appear at
the start of the file or after a shebang, in either case optionally
preceded by whitespace."  This resolves the ambiguity and parallels
the shebang position rule's structure.
traviscross added a commit that referenced this pull request Mar 4, 2026
The `r[frontmatter.document]` rule said "Frontmatter may only be
preceded by a shebang and whitespace", where the "and" could be
misread as requiring both a shebang and whitespace rather than listing
the set of things allowed to precede frontmatter.

Since we merged the shebang prose revision (#2192),
the shebang position rule now reads as a positive statement of where
the shebang may appear.  Let's follow the same pattern here: state
positively where frontmatter may appear rather than leaning on "only"
and a negative constraint.

In this commit, we rewrite the rule as "Frontmatter may appear at
the start of the file or after a shebang, in either case optionally
preceded by whitespace."  This resolves the ambiguity and parallels
the shebang position rule's structure.
traviscross added a commit that referenced this pull request Mar 4, 2026
The `r[frontmatter.document]` rule said "Frontmatter may only be
preceded by a shebang and whitespace", where the "and" could be
misread as requiring both a shebang and whitespace rather than listing
the set of things allowed to precede frontmatter.

Since we merged the shebang prose revision (#2192),
the shebang position rule now reads as a positive statement of where
the shebang may appear.  Let's follow the same pattern here: state
positively where frontmatter may appear rather than leaning on "only"
and a negative constraint.

In this commit, we rewrite the rule as "Frontmatter may appear at
the start of the file or after a shebang, in either case optionally
preceded by whitespace."  This resolves the ambiguity and parallels
the shebang position rule's structure.
traviscross added a commit that referenced this pull request Mar 4, 2026
The `frontmatter.document` rule said "Frontmatter may only be preceded
by a shebang and whitespace", where the "and" could be misread as
requiring both a shebang and whitespace rather than listing the set of
things allowed to precede frontmatter.

Since we merged the shebang prose revision (#2192),
the shebang position rule now reads as a positive statement of where
the shebang may appear.  Let's follow the same pattern here: state
positively where frontmatter may appear rather than leaning on "only"
and a negative constraint.

We'll also rename the rule identifier to `frontmatter.position` in
keeping with our conventions.
traviscross added a commit that referenced this pull request Mar 4, 2026
The `frontmatter.document` rule said "Frontmatter may only be preceded
by a shebang and whitespace", where the "and" could be misread as
requiring both a shebang and whitespace rather than listing the set of
things allowed to precede frontmatter.

Since we merged the shebang prose revision (#2192),
the shebang position rule now reads as a positive statement of where
the shebang may appear.  Let's follow the same pattern here: state
positively where frontmatter may appear rather than leaning on "only"
and a negative constraint.

We'll also rename the rule identifier to `frontmatter.position` in
keeping with our conventions.
traviscross added a commit that referenced this pull request Mar 4, 2026
In #2192, we extended our documentation about
shebangs but kept it in Input Format under a section on shebang
removal.  But really, this section is mostly now about documenting
what a shebang is, for our purposes.

Let's separate this out into a new subchapter.

We'll keep the rule about shebang removal in Input Format; it can link
to Shebang for a description of what a shebang is, its grammar, etc.

This follows the pattern that we'll similarly be using for
frontmatter.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants