Skip to content

Commit ec9a2c9

Browse files
committed
docs(rfc): Expand more on frontmatter choices
1 parent ed04aa8 commit ec9a2c9

File tree

1 file changed

+11
-2
lines changed

1 file changed

+11
-2
lines changed

0000-cargo-script.md

+11-2
Original file line numberDiff line numberDiff line change
@@ -622,10 +622,10 @@ foo = "1.2.3"
622622

623623
fn main() {}
624624
````
625-
- The first line post-shebang-stripping is 3+ backticks, then capture all content until a matching pair of backticks on a dedicated line. This would be captured into a `#![frontmatter(info = "cargo", content = "..."]`. `frontmatter` attribute is reserved for crate roots. The 3+ with matching pair is a "just in case" a TOML multi-line string has that syntax in it)
625+
- The first line post-shebang-stripping is 3+ backticks with a `cargo` infostring, then capture all content until a matching pair of backticks on a dedicated line. This would be captured into a `#![frontmatter(info = "cargo", content = "..."]`. `frontmatter` attribute is reserved for crate roots. The 3+ with matching pair is a "just in case" a TOML multi-line string has that syntax in it)
626626
- Future evolution: Allow `cargo` being the default `info` string
627627
- Future evolution: Allow any `info` string with cargo checking for `content.starts_with(["cargo", "cargo,"])`
628-
- Future evolution: Allow `frontmatter` attribute on any module
628+
- Future evolution: Allow this `frontmatter` attribute on any module
629629

630630
Benefits
631631
- Visually/syntactically lightweight
@@ -636,6 +636,15 @@ Benefits
636636
Downsides
637637
- People are likely to make mistakes in wrapping these in code fences when posting issues to github (this post originally had the code fence wrong)
638638

639+
The `cargo` infostring was chosen because
640+
- An alternative is `Cargo.toml` but infostring language fields are generally an identifier rather than a file name
641+
- An alternative is to specify the cargo payload as an attribute, like `cargo,file=Cargo.toml` but the language should generally convey the format/schema rather than an attribute
642+
- This also adds a lot of verbosity to teach, write, and get wrong
643+
- If we add additional frontmatter blocks in the future (like for lockfiles),
644+
the manifest block will be needed at minimum and other blocks will likely
645+
only be used in 1% of cases the manifest block is present, so we shouldn't
646+
hurt the simple, common case for the more advanced, long tail cases.
647+
639648
See also [t-lang zulup thread](https://rust-lang.zulipchat.com/#narrow/stream/213817-t-lang/topic/Embedding.20cargo.20manifests.20in.20rust.20source)
640649

641650
**Alternative 1: Doc-comment**

0 commit comments

Comments
 (0)