help: Add a keyword feature

It would be nice to not need to go the documentation website. This aims
to solve that by introducing the concept of keyword to the help
command.

Basically, keywords are things that we want to add help messages to,
but they don't necessarily have an associated subcommand.

For now we only have two keywords:
	- `revsets`: Shows the docs for revsets
	- `tutorial`: Shows the tutorial that is on the documentation

You get the keyword content by tipping `jj help --keyword revsets` or
`jj help -k revsets`.

It would be nice to have all the documentation on the keywords, maybe
a next commit could do it.

CHANGELOG.md

@@ -78,6 +78,10 @@ to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 * Add a new template alias `bultin_log_compact_full_description()`.
 
+* `jj help` now has the flag `--keyword`(shorthand `-k`), which can give help
+  for some keywords(e.g. `jj help -k revsets`). To see a list of the available
+  keywords you can do `jj help`, `jj --help` or `jj help -k`.
+
 ### Fixed bugs
 
 * Error on `trunk()` revset resolution is now handled gracefully.

cli/src/command_error.rs

@@ -207,7 +207,7 @@ pub fn internal_error_with_message(
     CommandError::with_message(CommandErrorKind::Internal, message, source)
 }
 
-fn format_similarity_hint<S: AsRef<str>>(candidates: &[S]) -> Option<String> {
+pub fn format_similarity_hint<S: AsRef<str>>(candidates: &[S]) -> Option<String> {
     match candidates {
         [] => None,
         names => {

cli/src/commands/help.rs

@@ -12,38 +12,158 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+use std::fmt::Write as _;
+use std::io::Write;
+
+use clap::builder::StyledStr;
+use crossterm::style::Stylize;
+use itertools::Itertools;
 use tracing::instrument;
 
 use crate::cli_util::CommandHelper;
-use crate::command_error;
 use crate::command_error::CommandError;
+use crate::command_error::{self};
 use crate::ui::Ui;
 
 /// Print this message or the help of the given subcommand(s)
 #[derive(clap::Args, Clone, Debug)]
 pub(crate) struct HelpArgs {
     /// Print help for the subcommand(s)
     pub(crate) command: Vec<String>,
+    // Show help for keywords instead of commands
+    #[arg(long, short = 'k')]
+    keyword: bool,
 }
 
 #[instrument(skip_all)]
 pub(crate) fn cmd_help(
-    _ui: &mut Ui,
+    ui: &mut Ui,
     command: &CommandHelper,
     args: &HelpArgs,
 ) -> Result<(), CommandError> {
-    let mut args_to_show_help = vec![command.app().get_name()];
-    args_to_show_help.extend(args.command.iter().map(|s| s.as_str()));
-    args_to_show_help.push("--help");
-
-    // TODO: `help log -- -r` will gives an cryptic error, ideally, it should state
-    // that the subcommand `log -r` doesn't exist.
-    let help_err = command
-        .app()
-        .clone()
-        .subcommand_required(true)
-        .try_get_matches_from(args_to_show_help)
-        .expect_err("Clap library should return a DisplayHelp error in this context");
-
-    Err(command_error::cli_error(help_err))
+    if args.keyword {
+        if let [name] = &*args.command {
+            if let Some(keyword) = find_keyword(name) {
+                ui.request_pager();
+                write!(ui.stdout(), "{}", keyword.content)?;
+
+                return Ok(());
+            } else {
+                let error_str = format!("No help found for keyword \"{name}\"");
+                let similar_keywords = &KEYWORDS
+                    .iter()
+                    .map(|keyword| keyword.name)
+                    .filter(|str| strsim::jaro(name, str) > 0.7)
+                    .collect_vec();
+
+                if let Some(similar_keywords) =
+                    command_error::format_similarity_hint(similar_keywords)
+                {
+                    return Err(command_error::user_error_with_hint(
+                        error_str,
+                        similar_keywords,
+                    ));
+                } else {
+                    return Err(command_error::user_error(error_str));
+                }
+            }
+        }
+
+        let keyword_list = if ui.color() {
+            format_keywords().ansi().to_string()
+        } else {
+            format_keywords().to_string()
+        };
+
+        write!(ui.stdout(), "{keyword_list}")?;
+
+        return Ok(());
+    } else {
+        let mut args_to_show_help = vec![command.app().get_name()];
+        args_to_show_help.extend(args.command.iter().map(|s| s.as_str()));
+        args_to_show_help.push("--help");
+
+        // TODO: `help log -- -r` will gives an cryptic error, ideally, it should state
+        // that the subcommand `log -r` doesn't exist.
+        let help_err = command
+            .app()
+            .clone()
+            .subcommand_required(true)
+            .try_get_matches_from(args_to_show_help)
+            .expect_err("Clap library should return a DisplayHelp error in this context");
+
+        Err(command_error::cli_error(help_err))
+    }
+}
+
+#[derive(Clone)]
+struct Keyword {
+    name: &'static str,
+    description: &'static str,
+    content: &'static str,
+}
+
+// TODO: Add all documentation to keywords
+//
+// Maybe adding some code to build.rs to find all the docs files and build the
+// `KEYWORDS` at compile time.
+//
+// It would be cool to follow the docs hierarchy somehow.
+//
+// One of the problems would be `config.md`, as it has the same name as a
+// subcommand.
+//
+// TODO: Find a way to render markdown using ANSI escape codes.
+//
+// Maybe we can steal some ideas from https://github.com/martinvonz/jj/pull/3130
+const KEYWORDS: &[Keyword] = &[
+    Keyword {
+        name: "revsets",
+        description: "A functional language for selecting a set of revision",
+        content: include_str!("../../../docs/revsets.md"),
+    },
+    Keyword {
+        name: "tutorial",
+        description: "Show a tutorial to get started with jj",
+        content: include_str!("../../../docs/tutorial.md"),
+    },
+];
+
+fn find_keyword(name: &str) -> Option<&Keyword> {
+    KEYWORDS.iter().find(|keyword| keyword.name == name)
+}
+
+fn format_keywords() -> StyledStr {
+    let keyword_name_max_len = KEYWORDS
+        .iter()
+        .map(|keyword| keyword.name.len())
+        .max()
+        .unwrap();
+
+    let mut ret = String::new();
+
+    writeln!(ret, "{}", "Help Keywords:".bold().underlined()).unwrap();
+    for keyword in KEYWORDS {
+        write!(
+            ret,
+            "  {}  ",
+            format!("{:<keyword_name_max_len$}", keyword.name).bold()
+        )
+        .unwrap();
+        writeln!(ret, "{}", keyword.description).unwrap();
+    }
+
+    ret.into()
+}
+
+pub fn format_keywords_for_after_help() -> StyledStr {
+    let mut ret = StyledStr::new();
+    writeln!(
+        ret,
+        "Use {} to show help related to these keywords",
+        "'jj help -k'".bold()
+    )
+    .unwrap();
+    write!(ret, "{}", format_keywords()).unwrap();
+    return ret;
 }

cli/src/commands/mod.rs

@@ -73,6 +73,7 @@ use crate::ui::Ui;
 
 #[derive(clap::Parser, Clone, Debug)]
 #[command(disable_help_subcommand = true)]
+#[command(after_long_help = help::format_keywords_for_after_help())]
 enum Command {
     Abandon(abandon::AbandonArgs),
     Backout(backout::BackoutArgs),

cli/tests/cli-reference@.md.snap

@@ -112,6 +112,11 @@ To get started, see the tutorial at https://martinvonz.github.io/jj/latest/tutor
 
 **Usage:** `jj [OPTIONS] [COMMAND]`
 
+Help Categories:
+  revsets   A functional language for selecting a set of revision
+  tutorial  Show a tutorial to get started with jj
+
+
 ###### **Subcommands:**
 
 * `abandon` — Abandon a revision
@@ -1196,12 +1201,16 @@ Set the URL of a Git remote
 
 Print this message or the help of the given subcommand(s)
 
-**Usage:** `jj help [COMMAND]...`
+**Usage:** `jj help [OPTIONS] [COMMAND]...`
 
 ###### **Arguments:**
 
 * `<COMMAND>` — Print help for the subcommand(s)
 
+###### **Options:**
+
+* `-k`, `--keyword`
+
 
 
 ## `jj init`

cli/tests/test_help_command.rs

@@ -84,3 +84,60 @@ fn test_help() {
     For more information, try '--help'.
     "#);
 }
+
+#[test]
+fn test_help_keyword() {
+    let test_env = TestEnvironment::default();
+
+    // Capture 'Help Keywords' part
+    let help_cmd_stdout = test_env.jj_cmd_success(test_env.env_root(), &["help"]);
+    insta::with_settings!({filters => vec![
+        (r"(?s).+\n\n(?<h>.*Help Keywords:.+)", "$h"),
+    ]}, {
+        insta::assert_snapshot!(help_cmd_stdout, @r#"
+        Use 'jj help -k' to show help related to these keywords
+        Help Keywords:
+          revsets   A functional language for selecting a set of revision
+          tutorial  Show a tutorial to get started with jj
+        "#);
+    });
+
+    // It should show help for a certain keyword if the `--keyword` flag is present
+    let help_cmd_stdout =
+        test_env.jj_cmd_success(test_env.env_root(), &["help", "--keyword", "revsets"]);
+    // It should be equal to the docs
+    assert_eq!(help_cmd_stdout, include_str!("../../docs/revsets.md"));
+
+    // It should show help for a certain keyword if the `-k` flag is present
+    let help_cmd_stdout = test_env.jj_cmd_success(test_env.env_root(), &["help", "-k", "revsets"]);
+    // It should be equal to the docs
+    assert_eq!(help_cmd_stdout, include_str!("../../docs/revsets.md"));
+
+    // It should give hints if a similar keyword is present
+    let help_cmd_stderr = test_env.jj_cmd_failure(test_env.env_root(), &["help", "-k", "rev"]);
+    insta::assert_snapshot!(help_cmd_stderr, @r#"
+    Error: No help found for keyword "rev"
+    Hint: Did you mean "revsets"?
+    "#);
+
+    // The keyword flag with no argument should print the keyword list
+    let help_cmd_stdout = test_env.jj_cmd_success(test_env.env_root(), &["help", "-k"]);
+    insta::assert_snapshot!(help_cmd_stdout, @r#"
+    Help Keywords:
+      revsets   A functional language for selecting a set of revision
+      tutorial  Show a tutorial to get started with jj
+    "#);
+
+    // It shouldn't show help for a certain keyword if the `--keyword` is not
+    // present
+    let help_cmd_stderr = test_env.jj_cmd_cli_error(test_env.env_root(), &["help", "revsets"]);
+    insta::assert_snapshot!(help_cmd_stderr, @r#"
+    error: unrecognized subcommand 'revsets'
+
+      tip: some similar subcommands exist: 'resolve', 'prev', 'restore', 'rebase', 'revert'
+
+    Usage: jj [OPTIONS] <COMMAND>
+
+    For more information, try '--help'.
+    "#);
+}