Provide manpages

[Xophmeister]

Provide manpages

Resolves #806

Description

Convert the Topiary CLI section in the Topiary Book into manpages, for distribution with Topiary.

Checklist

Checklist before merging, wherever relevant:

• CHANGELOG.md updated
• Documentation (The Topiary Book, README.md, etc.) up-to-date

[Xophmeister]

There are a few rough edges with mdbook-man:

1. It puts everything into section 7 (Miscellaneous). This can be programmatically changed afterwards, though.
2. The original Markdown files for the book contain relative links to other book content; these are copied into the manpages verbatim, which make little sense. These could probably be stripped from the Markdown with some preprocessing.
3. Markdown tables are not supported. I'm not sure what to do about this...
4. Our Markdown files are hard-wrapped, which results in the last word in a line becoming joined to the first word in the next line. Maybe this could be preprocessed out, too.

Here is the non-pre/post-processed output, for reference: topiary.man.gz

[aspiwack]

Honestly, I'm not sure the book is what people want/expect to read in the man pages. Which probably explains (in part) why the tool you're using doesn't really work well with it.

[Xophmeister]

Honestly, I'm not sure the book is what people want/expect to read in the man pages. Which probably explains (in part) why the tool you're using doesn't really work well with it.

I'm not using the whole book; I've taken a subset which just covers the usage and configuration of the Topiary CLI.

[Xophmeister]

Pre- and post-processing code is [finally] complete 🎉 This is what it spits out now: topiary.1.gz

The problem was due to mismatched versions of mdbook-man on GitHub vs. crates.io. The Nix derivation uses the GitHub version, but building manually with crates.io will fail. Until upstream has corrected this problem -- which isn't likely any time soon -- the best I can do is document a working manual install for non-Nix users.

Otherwise, this has been pending for 3 months, so I'm forcing it through!

[mkatychev]

Nit: the indentation feels rather steep, man topiary:

man less:

[mkatychev]

Have you looked into clap_mangen? It may be a better alternative to mdbook-man as it is far more frequently maintained, this is my patch to have a topiary man subcommand using clap_mangen:

diff --git a/topiary-cli/Cargo.toml b/topiary-cli/Cargo.toml
index 4bf6bb6..02ea3d8 100644
--- a/topiary-cli/Cargo.toml
+++ b/topiary-cli/Cargo.toml
@@ -28,6 +28,7 @@ path = "src/main.rs"
 async-scoped = { workspace = true }
 clap = { workspace = true, features = ["derive", "env", "wrap_help"] }
 clap_complete = { workspace = true }
+clap_mangen = "0.2.29"
 env_logger = { workspace = true }
 futures = { workspace = true }
 itertools = { workspace = true }
diff --git a/topiary-cli/src/cli.rs b/topiary-cli/src/cli.rs
index fe87bb2..8dca38a 100644
--- a/topiary-cli/src/cli.rs
+++ b/topiary-cli/src/cli.rs
@@ -176,6 +176,10 @@ pub enum Commands {
         /// Shell (omit to detect from the environment)
         shell: Option<Shell>,
     },
+
+    /// Generate manpages
+    #[command(display_order = 100)]
+    Man,
 }
 
 /// Parse CLI arguments and normalise them for the caller
diff --git a/topiary-cli/src/main.rs b/topiary-cli/src/main.rs
index b360889..5cc00a5 100644
--- a/topiary-cli/src/main.rs
+++ b/topiary-cli/src/main.rs
@@ -15,7 +15,7 @@ use error::Benign;
 use topiary_core::{check_query_coverage, formatter, Operation};
 
 use crate::{
-    cli::Commands,
+    cli::{Cli, Commands},
     error::{CLIError, CLIResult, TopiaryError},
     io::{read_input, Inputs, OutputFile},
     language::LanguageDefinitionCache,
@@ -212,6 +212,9 @@ async fn run() -> CLIResult<()> {
             // The CLI parser fails if no shell is provided/detected, so it's safe to unwrap here
             cli::completion(shell.unwrap());
         }
+
+        Commands::Man => clap_mangen::Man::new(<Cli as clap::CommandFactory>::command())
+            .render(&mut std::io::stdout())?,
     }
 
     Ok(())

You can run cargo run -p topiary-cli -- man > ~/.local/share/man/man1/topiary.1 && man topiary from workspace to see result after patch is applied (assuming no other manpage is installed)

[Xophmeister]

Thanks for taking a look, @mkatychev 🙏

I agree that the spacing is a bit much...I'll have a look at clap_mangen tomorrow to see how it looks. It sounds like a simpler solution, although it would lose the extra detail from the mdBook sources.

[mkatychev]

with the BSD changes, lgtm

[Xophmeister]

Thanks, @mkatychev 🙏 I haven't had the opportunity to look at clap_mangen yet, but I will try to soon and will delay merging until then.