[Options](https://github.com/epage/cargo-script-mvs/blob/main/0000-cargo-script.md#embedded-manifest-format)

Next steps
- Check with Guillaume about rustdoc rendering of `cargo` fences
- And check if rustdoc *might* be useful to parse or if that'd have way too much overhead?
- Prototype `cargo add` support for doc comments
- Testing a symlink to a `Cargo.toml`
- We should talk about whether to use extensions or content sniffing or a different shebang

Note
- We already support files without a `.rs` extension; cargo and rustc both seem to handle them

Options

- doc comments
- precedent from rust-script
- lib support means we wouldn't want to use doc comments?
- Or have rustdoc ignore it?
- Fold it?
- Parse it and show highlights?
- Abuse?
- But a lot of people have reported seeing the files and feeling they understand it
- doc tests are precedence
- Programmatic editing is more difficult
- Parse with rustdoc?
- Slow?
- Character overhead
- Multi-line is good for copy/paste
- Single-line repetition and IDEs help with overhead
- Difficult to put the comment at the end
- More of an issue for the lockfile
- Resolution time-machine to avoid lockfile?
- Long manifest?
- Is this still the right tool?

/*!```cargo
[dependencies]
clap = "4"

/*!
* ```cargo
* [dependencies]
* clap = "4"
* ```
*/

//! ```cargo
//! [dependencies]
//! clap = "4"
//! ```

- `#![cargo = r#"..."#]`
    - Could drop `r#` if we encourage string literals in TOML
    - Could have a special kind of comment that's shorthand for this, like `///` is shorthand for `#[doc]`.
        - Bigger lift
        - Edition?
        - Minor incompat?
    - `#![cargo(clap = { version = "3" }, anyhow = "1")]`
    - Can you do `#![cargo.dep()]` or `#![cargo::dependencies()]`
    - Or no string
        - Need yet another TOML parser written using `syn` (inside cargo)?
        - Or could we get a string from it
    - Potential novice mistake: thinking the attribute could be manipulated/generated using Rust
        - `cfg`, `cfg_attr`, macro, etc for compile-time (ie we can only work with a literal)
        - `concat!`
        - `include_str!`
    - More ugly / harder to grok for new users to look at, especially on the web
    - Harder for tools to handle when syntax highlighting (they have to special-case it)

- `#![metadata.cargo = "..."]`
    - Who defines what other metadata means?
    - Could have a special kind of comment that's shorthand for this, like `///` is shorthand for `#[doc]`.

- `cargo!(...)`
    - Potential novice mistake: thinking the macro could be manipulated/generated using Rust
    - Compatibility issue: what if they have a macro named cargo
    - This is a new feature (cargo script) interpreting it (still not great)

- non-doc comment
    - Really don't want to make non-doc comments semantically meaningful

- YAML presentation stream?



## Edition

Rough plan
- Perma-warning now
  - cargo fix to address it (not required for first release)
  - Can always require in future on edition boundary
- Maybe edition wrapper later

`cargo +nightly new script.rs` propgate or warn about toolchain difference?
  - Can we detect presence of `+` to warn?
  - We'd need support from rustup for this

Default to an edition (the one introducing cargo script) unless specified
- Effectively always requires the edition once people want a new edition
  - Bloats educational material

~~Insert edition on first run~~

~~Edition flag~~
- `env` issues

edition wrapper (cargo-2018)
- Bloated on windows (esp 40 years from now...)
- `cargo 2018` is weird and requires special parsing to not error out
- `car\t` is annoying for completions
    - Already true for third-party commands. (Possibly already true for first-party commands?)
    - Will it be overhwleming though in 40 years

Require an explicit edition

Perma-warning on missing field.
- This effectively makes an explicit edition mandatory (for anything except toys and bug-reproductions)
- If we have a `cargo new --script`, should it always generate the manifest so we get edition?
    - What to call the flag?
        - `cargo new foo.rs` does it based on extension?
        - Doesn't help when people don't want an extension
    - `chmod +x`
    - `#!` block
    - Insert manifest

Bug reproduction
Throwaway scripts

Long-term scripts
Clean documentation that doesn't produce warnings