FR: Compile the docs into the jj binary

[ilyagr]

I think it would be nice for jj to be self-documenting. A relatively simple approach would be to create a jj doc command so that jj doc tutorial prints docs/tutorial.md via a pager, using the include_str! macro. jj doc or jj doc list would list the available topics. I'm hoping that clap will provide tab completion (though this is optional, especially for the first version).

For example, I expect jj doc revsets to be useful.

Alternatively, this could be part of the jj help command, but I couldn't figure out an easy way to do that with clap. Also, the output of jj help is already quite long.

This will also match the version of the documentation people see with the version of jj they use.

[dbarnett]

I'd definitely start with making jj help more useful and self-contained. At least reference relevant docs from help.

Maybe could have some kind of jj help --topic FOO command (along the lines of hg's hg help FOO vs hg help --command FOO)?

[martinvonz]

I'd definitely start with making jj help more useful and self-contained. At least reference relevant docs from help.

Patches for that would be appreciated. I don't notice it much myself.

Maybe could have some kind of jj help --topic FOO command (along the lines of hg's hg help FOO vs hg help --command FOO)?

There actually used to be a command for that. I decided that it was less maintenance work to keep it in separate markdown files. There's probably a way of generating something that's readable in terminal from the markdown files. I think I looked into that a little bit a year or so.

[ilyagr]

Maybe could have some kind of jj help --topic FOO command

I am a little apprehensive about touching jj help since it's auto-generated by clap and I don't want to replace it entirely. If I can, I'd add a paragraph advertising the new jj doc command to jj help -- I think clap supports that much customization.

There's probably a way of generating something that's readable in terminal from the markdown files

At least at first, I was thinking of just sending them to the pager. There are also plenty of tools that try to render markdown more nicely in the terminal, we could later try finding a library that can be used from rust.

Some notes on that:

• Here is the first one Google returns, termimad.
• bat is simpler, and I think the syntax highlighting portion of it might be useable as a library. Or, we can recommend it as a pager for jj doc, or try to use it if it's installed.
• https://docs.rs/mdcat/latest/mdcat/ seems promising. It just converts markdown to ANSI terminal escaped text. OTOH, it doesn't support tables or rewrapping text and uses terminal links (which not all terminals support).
• There is always pandoc, but it would require a build step since it's in Haskell. There's a rust library to call it, we could use it if the user has pandoc installed. (Actually, it doesn't seem to support terminal escapes as the output format :( . There's abandoned https://github.com/Orange-OpenSource/pandoc-terminal-writer. On Unix, it can pipe to man).