More ergonomic doc generation - macro-based approach

[eugenesvk]

Currently generating docs involves too much syntax noise, which rivals the content itself and makes it hard to read

doc.empasis("Usage:");
doc.literal("my_program");
doc.text("some long description ");
doc.invalid("not X");
doc.text(" but ");
doc.emphasis("Y");
doc.text(" but ");

I've added some shorter aliases, which helps, but still less than ideal

doc.em("Usage:");
doc.lit("my_program");
doc.text("some long description ");
doc.x("not X");
doc.text(" but ");
doc.em("Y");
doc.text(" but ");

I think a much better way would be to have something similar to a format! macro, but where you could inline all the styles, for example, this is a nice clean readable text:

doc!("*‹Usage:› `‹my_program› some long description !‹not X›  but  *‹Y› but ")
doc!("b‹Usage:› l‹my_program› some long description x‹not X›  but  b‹Y› but ")

where each style requires only 3 symbols: style name X and very light brackets ‹› (to not add any more noise than needed)

• *‹› or b‹› empasis (or em‹›)
• `‹› or l‹› literal
• !‹› or x‹› invalid
• nothing for text

and could easily be extended should you need more styles:

• _‹underline›
• -‹strikethrough›
• ...

And literal *‹ could be as simple as duplicating the bracket *‹‹ (similarly, ›› inside an opened ‹ could bit a literal ›)

Downgrading to ascii could also be an alternative crate feature in case you don't mind having more potential conflics since these have common use

doc!("*<Usage:> `<my_program> some long description !<not X>  but  *<Y> but ")
doc!("*[Usage:] `[my_program] some long description ![not X]  but  *[Y] but ")

[pacak]

It's probably going to be markdown or ANSI codes directly that you can create in any way you want. So *literal*, _emphasis_ or something like that with escape if you want use specific chars: \_not_literal\_. Using macro doesn't bring much benefits - we are allocating anyway, might as well use a regular function - easier to test, easier to implement.

So something like that I guess

doc("*Usage*: _my_program_ some long description **not X**  but  **Y** but ")

Still, need some time to get there.

[eugenesvk]

Macro would allow common variable syntax?

let my_program = env!("CARGO_BIN_NAME");
doc!("*‹Usage:› `‹{my_program}›`)
doc!("*‹Usage:› `‹{}›`",env!("CARGO_BIN_NAME"))

[pacak]

So will the format!. doc(format!( ... )), but there's a chance it will be just format!("*Usage: {my_program}").