Mirrors/clap
2
0
Fork 0
mirror of https://github.com/clap-rs/clap synced 2024-11-10 06:44:16 +00:00
Code Issues Projects Releases Packages Wiki Activity
clap/examples/escaped-positional-derive.md

61 lines
1.3 KiB
Markdown
Raw Permalink Normal View History

docs: Move everything to docs.rs A couple of things happened when preparing to release 3.0 - We needed derive documentation - I had liked how serde handled theres - I had bad experiences finding things in structopt's documentation - The examples were broken and we needed tests - The examples seemed to follow a pattern of having tutorial content and cookbook content - We had been getting bug reports from people looking at master and thinking they were looking at what is currently released - We had gotten feedback to keep down the number of places that documentation was located From this, we went with a mix of docs.rs and github - We kept the number of content locations at 2 rather than 3 by not having an external site like serde - We rewrote the examples into explicit tutorials and cookbooks to align with the 4 styles of documentation - We could test our examples by running `console` code blocks with trycmd - Documentation was versioned and the README pointed to the last release This had downsides - The tutorials didn't have the code inlined - Users still had a hard time finding and navigating between the different forms of documentation - In practice, we were less likely to cross-link between the different types of documentation Moving to docs.rs would offer a lot of benefits, even if it is only designed for Rust-reference documentation and isn't good for Rust derive reference documentation, tutorials, cookbooks, etc. The big problem was keeping the examples tested to keep maintenance costs down. Maybe its just me but its easy to overlook - You can pull documentation from a file using `#[doc = "path"]` - Repeated doc attributes get concatenated rather than first or last writer winning Remember these when specifically thinking about Rust documentation made me realize that we could get everything into docs.rs. When doing this - Tutorial code got brought in as was one of the aims - We needed to split the lib documentation and the README to have all of the linking work. This allowed us to specialize them according to their rule (user vs contributor) - We needed to avoid users getting caught up in making a decision between Derive and Builder APIs so we put the focus on the derive API with links to the FAQ to help users decide when to use one or the other. - Improved cross-referencing between different parts of the documentation - Limited inline comments were added to example code - Introductory example code intentionally does not have teaching comments in it as its meant to give a flavor or sense of things and not meant to teach on its own. This is a first attempt. There will be a lot of room for further improvement. Current know downsides: - Content source is more split up for the tutorials This hopefully addresses #3189
2022-07-19 18:29:31 +00:00
**This requires enabling the [`derive` feature flag][crate::_features].**
docs: Call out features used in root examples mitsuhiko immediately jumped into the examples and got tripped up by the lack of documentation on feature flags needed. I limited this to just the root ones because the rest are in a more proper tutorial that steps through it all.
2021-12-08 22:46:49 +00:00
docs: Re-work examples This creates distinct tutorial examples from complex feature examples (more how-tos). Both sets are getting builder / derive versions (at least the critical ones).
2021-11-30 18:30:19 +00:00
You can use `--` to escape further arguments.
Let's see what this looks like in the help:
docs: Fix messed up highlighting This just affects how it's rendered; rather than attempting to highlight these blocks as a shell script, they'll get highlighted as console output. See the rendered versions for a better comparison.
2022-01-05 16:54:33 +00:00
```console
refactor(examples): Change naming style This is to make room for a reasonable looking cargo plugin example. I got lazy and didn't update the tutorials.
2021-12-15 17:12:16 +00:00
$ escaped-positional-derive --help
docs: Re-work examples This creates distinct tutorial examples from complex feature examples (more how-tos). Both sets are getting builder / derive versions (at least the critical ones).
2021-11-30 18:30:19 +00:00
A simple to use, efficient, and full-featured Command Line Argument Parser
fix(help): Collapse usage to one line After looking at more examples, I've become more attached to this briefer format. Part of #4132
2022-09-07 16:03:55 +00:00
Usage: escaped-positional-derive[EXE] [OPTIONS] [-- <SLOP>...]
docs: Re-work examples This creates distinct tutorial examples from complex feature examples (more how-tos). Both sets are getting builder / derive versions (at least the critical ones).
2021-11-30 18:30:19 +00:00
fix(help): Don't rely on ALL CAPS for headers I see them fulfilling two roles - A form of bolding - As a callback to their placeholder in usage However, it is a bit of an unpolished look and no other CLI seems to do it. This looks a bit more proefessional. We have colored help for formatting and I think the sections relation to usage will be clear enough.
2022-08-26 14:40:23 +00:00
Arguments:
fix(help): Make output more dense In looking at other help output, I noticed that they use two spaces, in place of clap's 4, and it doesn't suffer from legibility. If it doesn't make the output worse, let's go ahead and make it as dense so we fit more content on the screen. This is a part of #4132
2022-09-07 20:29:15 +00:00
[SLOP]...
docs: Re-work examples This creates distinct tutorial examples from complex feature examples (more how-tos). Both sets are getting builder / derive versions (at least the critical ones).
2021-11-30 18:30:19 +00:00
fix(help): Don't rely on ALL CAPS for headers I see them fulfilling two roles - A form of bolding - As a callback to their placeholder in usage However, it is a bit of an unpolished look and no other CLI seems to do it. This looks a bit more proefessional. We have colored help for formatting and I think the sections relation to usage will be clear enough.
2022-08-26 14:40:23 +00:00
Options:
fix(help): Make output more dense In looking at other help output, I noticed that they use two spaces, in place of clap's 4, and it doesn't suffer from legibility. If it doesn't make the output worse, let's go ahead and make it as dense so we fit more content on the screen. This is a part of #4132
2022-09-07 20:29:15 +00:00
-f
-p <PEAR>
fix(help): Remove extraneous text from built-ins This is an intermediate solution for #4408. As there were no agreeed upon goals, I went with what I felt read well and that I saw commonly used on non-clap commands. - "information" isn't really a necessary word. - I originally favored `Print this help` but realied that doesn't read correctly in completions. - Besides being shorter, the reason for the flipped short/long hint is it gives people the context they need for scanning, emphasizing "summary" and "more". Fixes #4409
2023-01-03 16:49:43 +00:00
-h, --help Print help
-V, --version Print version
docs: Fix messed up highlighting This just affects how it's rendered; rather than attempting to highlight these blocks as a shell script, they'll get highlighted as console output. See the rendered versions for a better comparison.
2022-01-05 16:54:33 +00:00
docs: Re-work examples This creates distinct tutorial examples from complex feature examples (more how-tos). Both sets are getting builder / derive versions (at least the critical ones).
2021-11-30 18:30:19 +00:00
```
Here is a baseline without any arguments:
docs: Fix messed up highlighting This just affects how it's rendered; rather than attempting to highlight these blocks as a shell script, they'll get highlighted as console output. See the rendered versions for a better comparison.
2022-01-05 16:54:33 +00:00
```console
refactor(examples): Change naming style This is to make room for a reasonable looking cargo plugin example. I got lazy and didn't update the tutorials.
2021-12-15 17:12:16 +00:00
$ escaped-positional-derive
docs: Re-work examples This creates distinct tutorial examples from complex feature examples (more how-tos). Both sets are getting builder / derive versions (at least the critical ones).
2021-11-30 18:30:19 +00:00
-f used: false
-p's value: None
'slops' values: []
docs: Fix messed up highlighting This just affects how it's rendered; rather than attempting to highlight these blocks as a shell script, they'll get highlighted as console output. See the rendered versions for a better comparison.
2022-01-05 16:54:33 +00:00
docs: Re-work examples This creates distinct tutorial examples from complex feature examples (more how-tos). Both sets are getting builder / derive versions (at least the critical ones).
2021-11-30 18:30:19 +00:00
```
Notice that we can't pass positional arguments before `--`:
docs: Fix messed up highlighting This just affects how it's rendered; rather than attempting to highlight these blocks as a shell script, they'll get highlighted as console output. See the rendered versions for a better comparison.
2022-01-05 16:54:33 +00:00
```console
refactor(examples): Change naming style This is to make room for a reasonable looking cargo plugin example. I got lazy and didn't update the tutorials.
2021-12-15 17:12:16 +00:00
$ escaped-positional-derive foo bar
docs: Re-work examples This creates distinct tutorial examples from complex feature examples (more how-tos). Both sets are getting builder / derive versions (at least the critical ones).
2021-11-30 18:30:19 +00:00
? failed
fix(error): Try to soften unexpected argument/value errors Adding "found" might seem minor but I feel it has a slight softening on the message. It also maintains scanability as it is at the end and short. As this is a one-off message change and not a styling issue to be consistent with, I think this is safe to put in a patch release.
2023-01-14 03:29:49 +00:00
error: unexpected argument 'foo' found
docs: Re-work examples This creates distinct tutorial examples from complex feature examples (more how-tos). Both sets are getting builder / derive versions (at least the critical ones).
2021-11-30 18:30:19 +00:00
fix(help): Collapse usage to one line After looking at more examples, I've become more attached to this briefer format. Part of #4132
2022-09-07 16:03:55 +00:00
Usage: escaped-positional-derive[EXE] [OPTIONS] [-- <SLOP>...]
docs: Re-work examples This creates distinct tutorial examples from complex feature examples (more how-tos). Both sets are getting builder / derive versions (at least the critical ones).
2021-11-30 18:30:19 +00:00
fix(error): Match rustc for giving more information
2023-01-03 19:22:35 +00:00
For more information, try '--help'.
docs: Fix messed up highlighting This just affects how it's rendered; rather than attempting to highlight these blocks as a shell script, they'll get highlighted as console output. See the rendered versions for a better comparison.
2022-01-05 16:54:33 +00:00
docs: Re-work examples This creates distinct tutorial examples from complex feature examples (more how-tos). Both sets are getting builder / derive versions (at least the critical ones).
2021-11-30 18:30:19 +00:00
```
But you can after:
docs: Fix messed up highlighting This just affects how it's rendered; rather than attempting to highlight these blocks as a shell script, they'll get highlighted as console output. See the rendered versions for a better comparison.
2022-01-05 16:54:33 +00:00
```console
refactor(examples): Change naming style This is to make room for a reasonable looking cargo plugin example. I got lazy and didn't update the tutorials.
2021-12-15 17:12:16 +00:00
$ escaped-positional-derive -f -p=bob -- sloppy slop slop
docs: Re-work examples This creates distinct tutorial examples from complex feature examples (more how-tos). Both sets are getting builder / derive versions (at least the critical ones).
2021-11-30 18:30:19 +00:00
-f used: true
-p's value: Some("bob")
'slops' values: ["sloppy", "slop", "slop"]
docs: Fix messed up highlighting This just affects how it's rendered; rather than attempting to highlight these blocks as a shell script, they'll get highlighted as console output. See the rendered versions for a better comparison.
2022-01-05 16:54:33 +00:00
docs: Re-work examples This creates distinct tutorial examples from complex feature examples (more how-tos). Both sets are getting builder / derive versions (at least the critical ones).
2021-11-30 18:30:19 +00:00
```
As mentioned, the parser will directly pass everything through:
docs: Fix messed up highlighting This just affects how it's rendered; rather than attempting to highlight these blocks as a shell script, they'll get highlighted as console output. See the rendered versions for a better comparison.
2022-01-05 16:54:33 +00:00
```console
refactor(examples): Change naming style This is to make room for a reasonable looking cargo plugin example. I got lazy and didn't update the tutorials.
2021-12-15 17:12:16 +00:00
$ escaped-positional-derive -- -f -p=bob sloppy slop slop
docs: Re-work examples This creates distinct tutorial examples from complex feature examples (more how-tos). Both sets are getting builder / derive versions (at least the critical ones).
2021-11-30 18:30:19 +00:00
-f used: false
-p's value: None
'slops' values: ["-f", "-p=bob", "sloppy", "slop", "slop"]
docs: Fix messed up highlighting This just affects how it's rendered; rather than attempting to highlight these blocks as a shell script, they'll get highlighted as console output. See the rendered versions for a better comparison.
2022-01-05 16:54:33 +00:00
docs: Re-work examples This creates distinct tutorial examples from complex feature examples (more how-tos). Both sets are getting builder / derive versions (at least the critical ones).
2021-11-30 18:30:19 +00:00
```
Reference in a new issue Copy permalink