Rust CLI book

[killercup]

Since we are not just creating libraries but also collecting and curating knowledge around writing CLI crates, we need a good place to document this. I propose we create a web site that is hosted as part of this repo.

For this, we added a mdBook to this repository whose rendered version you can find here: https://rust-lang-nursery.github.io/cli-wg/

Content

• A "learn Rust by writing a CLI app" tutorial
  • @killercup has an initial draft ready to go but it'll be a lot of work to really polish this
• Best practices
  • What we learned from Common "footguns" when writing CLI applications #29 and Support development of well-behaved CLI apps #21
• Hidden treasures of the ecosystem (which will then no longer be hidden)
  • cf. Improve ecosystem discoverability #11

Prior art:

• Rust WASM book: https://rustwasm.github.io/book/
• @epage has already created https://github.com/crate-ci a https://crate-ci.github.io which track, develop, and document tooling and best practices around maintaining crates.

Alternatives/additions

• Add content to other resources! Cross-linking should be encouraged.

Content team

Who is responsible for (maintaining) the content?

[killercup]

Let's use this issue to discuss the general idea and propose possible content. I'll open more issues to track actual action items for this.

[epage]

• Are there any best practices related to parsable output (like cargo) that we should document?
• Is https://github.com/rust-lang-nursery/cli-wg/issues/39 going here?
• Do we want to document things related to https://github.com/rust-lang-nursery/cli-wg/issues/27 here?

[deg4uss3r]

I think it would really nice to have a section that focuses on currently working on and currently needs help with. I definitely want to help (even if it is with documentation), but I find it really hard to track things and feel like we are really spread out.

[killercup]

@epage yes, if we go ahead with this I see both #27 and #39 as issues where the result should be "has docs/a section on the website".

@deg4uss3r are you talking about a section on the website that lists things you can help out with -- or "help needed" issues here that are about help we need with content for the website?

[steveklabnik]

In general, any books that the WGs produce, I'd like to put on the bookshelf and distribute with Rust. So if you all want to do one of those, that'd be great...

[deg4uss3r]

@deg4uss3r are you talking about a section on the website that lists things you can help out with -- or "help needed" issues here that are about help we need with content for the website?

Why not both? 😁 However, originally I was talking about a section on the website for things the working group is working on or unassigned/mentored work to do. We could pull these from issues, but having a central place would be great since I feel like the working group work is spread pretty far.

Aww @steveklabnik does that mean we need to come in on Saturday?

[killercup]

FYI I might be inclined to make a mdbook theme for the cli site if we choose to use mdbook. (Best case scenario, other WGs could use it too because it's so awesome, worst case scenario people hate it, average case nobody cares.)

[yoshuawuyts]

I kind of like the idea of starting with an mdbook. Feel it would fit nicely with the other WGs:

• WASM WG Book
• Net WG Book
• Embedded WG Book

[killercup]

@tvannahl in https://github.com/rust-lang-nursery/cli-wg/issues/46#issuecomment-408386068 (pasting here for visibilty):

To be a book that includes best practises and pattern does sound very desirable. For later consultations a good overview about what changed (dropped pattern, etc.) would also be really nice.

Personally I do prefer a book since its easier and faster to comprehend the structure of it and straight forward to use as a lookup source.

Content to cover

To be more precise on the content I would assume on a cli-wg book to have:

• An introduction about the problem (cli) covered by the book.
• Introduction into CLI parsing using clap and reference to 5(?) popular alternatives one could look into.
• Introduction about the Signal handling problem (see Error handling in CLI apps #12, Signal handling #27) and recommendation of a solution.
• Introduction about man page generation
• Introduction into config file management (Config file management #7) and config file parsing.
• Exit codes (sysexits.h, errno(3) from Tracking Issue: Documenting Exit Codes #39) does sound like a good praxis, too.

Referenced content

If such a book is meant to be an introduction about developing a cli application, there are topics I would not cover but only reference. Further read if you will.

As such further read topic I would assume the following topics to fit right into this:

• Packaging and distributing apps #8 (Packaging and distributing apps)
• Testing CLI apps #9 (Testing CLI apps)

Possibly to consider

I don't know much about the cross-platform problem (#10) but since the related thread is rather active I assume it has relevance for cli as well.

[killercup]

We now have a "Command Line Application in Rust" (CLAIR) book! https://rust-lang-nursery.github.io/cli-wg/

Its TOC is currently as follows:

• A command line app in 15 minutes
  • Project setup
  • Parsing command line arguments
  • First implementation of our example tool
  • Nicer error reporting
  • Output for humans and machines
  • Testing
  • Packaging and documentation
• In-depth topics
  • Signal handling
  • Using config files
  • Exit codes
  • Communicating with humans
  • Communicating with machines
  • Rendering documentation for you CLI apps
  • Packaging apps and distributing them for different platforms

This is only meant as an initial draft, and all of the "In-depth topics" chapters are empty.

If you see a chapter you want to work on, comment here, and please submit PRs to fill them with notes, ideas, links, and drafts!

If you feel like we are missing chapters or are unclear what the chapters should be about, comment here, and maybe also submit a PR to add clarifications or content!