start working on guide-level docs

derive/src/lib.rs

@@ -19,6 +19,21 @@ use proc_macro::TokenStream;
 use quote::quote;
 use syn::{parse_macro_input, Data::Enum, DeriveInput};
 
+/// Derive `Arguments`
+///
+/// ## Argument specifications
+///
+/// | specification  | kind       | value    |
+/// | -------------- | ---------- | -------- |
+/// | `VAL`          | positional | n.a.     |
+/// | `-s`           | short      | none     |
+/// | `-s VAL`       | short      | required |
+/// | `-s[VAL]`      | short      | optional |
+/// | `--long`       | long       | none     |
+/// | `--long=VAL`   | long       | required |
+/// | `--long[=VAL]` | long       | optional |
+/// | `long=VAL`     | dd         | required |
+/// 
 #[proc_macro_derive(Arguments, attributes(arg, arguments))]
 pub fn arguments(input: TokenStream) -> TokenStream {
     let input = parse_macro_input!(input as DeriveInput);

design/arguments_in_coreutils.md → docs/design/arguments_in_coreutils.md

@@ -109,12 +109,25 @@ Some utils take positional arguments, which might be required.
 
 ### Deprecated syntax `+N` and `-N`
 
-Some utils (e.g. `head`, `tail`, `kill`, `fold` and `uniq`) support an old deprecated syntax where numbers can be directly passed as arguments as a shorthand. For example, `uniq +5` is a shorthand for `uniq -s 5` and `uniq -5` is short for `uniq -f 5`.
+Some utils (e.g. `head`, `tail`, `kill`, `fold` and `uniq`) support an old
+deprecated syntax where numbers can be directly passed as arguments as a
+shorthand. For example, `uniq +5` is a shorthand for `uniq -s 5` and `uniq -5`
+is short for `uniq -f 5`.
 
 These all behave slightly differently.
-1. `head` and `tail` only accept this if it is the first argument and either 1 or 2 arguments are given.
-2. In `fold` the `-N` must be standalone (e.g. `-10b` is rejected), but can appear at any position.
-3. In `kill`, the same rules as `fold` apply, but it can also be a name instead of a number.
-4. In `uniq`, the syntax does not need to stand alone and is additive in a weird way, because they hack `-22` as `-2 -2` so each flag `-1...-9` multiplies the previous by 10 and adds itself. I'm not sure that we need to support this. Doing something like what `fold` and `kill` do is probably fine. Also note that to make it extra confusing, the `+` variant works like `fold`.
+
+1. `head` and `tail` only accept this if it is the first argument and either 1
+   or 2 arguments are given.
+2. In `fold` the `-N` must be standalone (e.g. `-10b` is rejected), but can
+   appear at any position.
+3. In `kill`, the same rules as `fold` apply, but it can also be a name instead
+   of a number.
+4. In `uniq`, the syntax does not need to stand alone and is additive in a weird
+   way, because they hack `-22` as `-2 -2` so each flag `-1...-9` multiplies the
+   previous by 10 and adds itself. I'm not sure that we need to support this.
+   Doing something like what `fold` and `kill` do is probably fine. Also note
+   that to make it extra confusing, the `+` variant works like `fold`.
 5. `pr` the behaviour is similar to `uniq`.
-6. `split` seems to be somewhere between `uniq` and `fold`. It accepts things like `-x10x` correctly, but it doesn't do the additive thing from `uniq` across multiple occurrences. Basically, it's very clever and cursed.
+6. `split` seems to be somewhere between `uniq` and `fold`. It accepts things
+   like `-x10x` correctly, but it doesn't do the additive thing from `uniq`
+   across multiple occurrences. Basically, it's very clever and cursed.

docs/design/design.md

@@ -0,0 +1 @@
+# Design

design/design.md → docs/design/iterative.md

@@ -64,10 +64,10 @@ struct Settings {
 > is always obvious where an argument is defined.
 
 As part of the `Options` derive, we get a `Settings::parse` method that returns
-a `Settings` from a `OsString` iterator. The implementation of
-this is defined by the `set` and `map` attributes. `map` just says: "if we
-encounter this value in the iterator set this value", using a match-like syntax
-(it expands to a match). And the `#[set(Arg::Name)]` is just short for
+a `Settings` from a `OsString` iterator. The implementation of this is defined
+by the `set` and `map` attributes. `map` just says: "if we encounter this value
+in the iterator set this value", using a match-like syntax (it expands to a
+match). And the `#[set(Arg::Name)]` is just short for
 `#[map(Arg::Name(name) => name)]`, because that is a commonly appearing pattern.
 
 Importantly, arguments can appear in the attributes for multiple fields. We
@@ -147,7 +147,9 @@ enum Arg {
 
 ## Options struct
 
-The options struct has just one fundamental attribute: `map`. It works much like a `match` expression (in fact, that's what it expands to). Furthermore, it's possible to define defaults on fields.
+The options struct has just one fundamental attribute: `map`. It works much like
+a `match` expression (in fact, that's what it expands to). Furthermore, it's
+possible to define defaults on fields.
 
 ```rust
 #[derive(Options, Default)]
@@ -180,7 +182,8 @@ struct Settings {
 }
 ```
 
-As a shorthand, there is also a `set` attribute. These fields behave identically:
+As a shorthand, there is also a `set` attribute. These fields behave
+identically:
 
 ```rust
 #[derive(Options, Default)]
@@ -195,7 +198,8 @@ struct Settings {
 
 ## `FromValue` enums
 
-We often want to map values to some enum, we can define this mapping by deriving `FromValue`:
+We often want to map values to some enum, we can define this mapping by deriving
+`FromValue`:
 
 ```rust
 #[derive(Default, FromValue)]
@@ -210,4 +214,4 @@ enum Color {
     #[value("never", "no", "none")]
     Never,
 }
-```
+```

design/problems_with_clap.md → docs/design/problems_with_clap.md

@@ -111,7 +111,7 @@ uutils diverge.
 
 `clap`'s arguments are identified by strings. This leads to code like this:
 
-```rust
+```rust,ignore
 const OPT_NAME: &'static str = "name";
 
 // -- snip --
@@ -183,9 +183,10 @@ libraries.
   - Does not support a many-to-many relationship.
 - [`bpaf`](https://github.com/pacak/bpaf)
   - Extremely flexible, even supports `dd`-style.
-  - A different configuration between short and long options requires a workaround.
+  - A different configuration between short and long options requires a
+    workaround.
   - A many-to-many relation ship is possible, though not very ergonomic.
-  - For more information, see: https://github.com/uutils/uutils-args/issues/17
+  - For more information, see: <https://github.com/uutils/uutils-args/issues/17>
 - [`gumdrop`](https://github.com/murarth/gumdrop)
   - Does not handle invalid UTF-8.
   - Not configurable enough.

docs/guide/completions.md

@@ -0,0 +1 @@
+# Completions

docs/guide/guide.md

@@ -0,0 +1,12 @@
+# Guide
+
+This module provides guide-level documentation for [`uutils-args`](crate). If
+you're unfamiliar with this library you probably want to start with the first
+chapter below and work your way through.
+
+## Chapters
+
+1. [Quick Start](guide::quick)
+2. [Porting a Parser from `clap`](guide::port)
+3. [The `Value` trait](`guide::value`)
+4. [Generating completions](`guide::completions`)

docs/guide/port.md

@@ -0,0 +1 @@
+# Porting from Clap