feat: Add man page for prqlc

[vanillajonathan]

Man pages for Unix-like systems such as Linux, BSD and macOS.

$ man prqlc

You can live preview this on https://roperzh.github.io/grapse/

Here is the documentation for groff which explains the syntax https://manpages.debian.org/testing/groff/groff_mdoc.7.en.html

I haven't written any manual pages before so I don't know if this is semantically idiomatic but it is a start.

[max-sixty]

Thanks @vanillajonathan !

My main concern here is with maintaining it — how do we know whether it's current?

I'd favor merging this if there were a test to confirm it's mostly correct; that way we can at least know we're not shipping something incorrect.

Is that possible?

---

Looking for something that would be easier to maintain / auto-generated:

• This looks very promising: https://github.com/clap-rs/clap/tree/master/clap_mangen
  • I had also found https://github.com/rust-cli/man, but doesn't look maintained
• And a broader discussion of how to bundle man pages (but focuses more on the bundling): Support installing manpages (and potentially other files) rust-lang/cargo#2729

[vanillajonathan]

We wouldn't know if its current unless we actively maintain it and update it when prqlc is changed. It probably shouldn't change too much though.

This clap_magnen thing sounds pretty cool, I wasn't aware of it. Keep in mind though that manual pages may be comphrensive and contain a lot of more information than would be available to clap. See groff_mdoc or man bash for example, it is comprehensive!
Or for a smaller example ping or ifconfig.

There is also Pandoc which can be used to convert documentation in one format from another, it may be more developer-friendly than groff syntax.

[max-sixty]

OK. I'm very open to those.

I would gate merging this on some way of ensuring these don't fall out of date — it's worse to have out-of-date docs than no docs, I do think that prqlc will change, and it's important that we keep the maintenance burden of the repo low, so contributing can be a joyful experience.

That could be a test, or a way of auto-generating it, or open to other ideas...

[vanillajonathan]

I cannot imagine any way of adding tests, but auto-generating it could definitely be an alternative solution, however I believe it is a more limiting alternative as clap likely won't know too much about things other than what is strictly needed the command-line parsing.

A dedicated manual page may include things such as return status codes, examples, in-depth explanations, etc.

[max-sixty]

Here's the man page from the playground — it does look good!

---

@vanillajonathan WDYT about attempting this with the clap plugin?

I agree it's difficult to test — if there were examples here, then maybe we could test those. I definitely expect there will be changes, and I don't have a good visualization of how we'd maintain this.

Would we not merge any changes to prqlc until the man page was updated? That would mean folks had to learn groff to make a contribution, which doesn't seem great — and nor does an incorrect man page.

Does this make sense? I'm trying to balance the benefits of this against the long-term maintenance costs.

An alternative is to merge this and then just remove it when it gets out of date. But I'd be concerned about the expectations that sets around removing folks' hard work at the first sign of staleness, and that it crowds out potentially better solutions, like the clap_mangen approach.

[vanillajonathan]

I looked at the clap plugin and it sounds good, but I wasn't able to get it working. The prqlc uses a different way to setup clap, it seems the plugin expects clap to be configured using Command::new but prqlc appears to do it with structs instead. Maybe you would have better luck.

Dust uses this clap plugin but also does it together with the clap_complete plugin to generate shell completions scripts.
https://github.com/bootandy/dust/blob/master/build.rs

So that prql com + Tab expands to prql compile.

[max-sixty]

Dust uses this clap plugin but also does it together with the clap_complete plugin to generate shell completions scripts. https://github.com/bootandy/dust/blob/master/build.rs

So that prql com + Tab expands to prql compile.

This is great! Does this work or does it also require the builder plugin? I guess a separate issue from the man page but would be cool to have this too.

[max-sixty]

Great, I asked re derive vs builder over at clap-rs/clap#4749

[vanillajonathan]

Dust uses this clap plugin but also does it together with the clap_complete plugin to generate shell completions scripts. https://github.com/bootandy/dust/blob/master/build.rs
So that prql com + Tab expands to prql compile.

This is great! Does this work or does it also require the builder plugin? I guess a separate issue from the man page but would be cool to have this too.

The clap_complete page at cargo.rs says "Generate shell completion scripts for your clap::Command". So I assume it only works with clap::Command not derive.

[max-sixty]

The clap_complete page at cargo.rs says "Generate shell completion scripts for your clap::Command". So I assume it only works with clap::Command not derive.

We do have one of those though!

prql/prql-compiler/prqlc/src/cli.rs

Line 34 in 246cee9

command: Command,

[vanillajonathan]

The clap_complete page at cargo.rs says "Generate shell completion scripts for your clap::Command". So I assume it only works with clap::Command not derive.

We do have one of those though!

prql/prql-compiler/prqlc/src/cli.rs

Line 34 in 246cee9

command: Command,

Oh, we do!

I haven't been able to get it to work though. You would probably have better luck.

[max-sixty]

OK, I had a go for 10 minutes but couldn't figure this out — we can open an issue and see if someone who knows clap better wants to take a look. Here's where i got up to:

diff --git a/prql-compiler/prqlc/Cargo.toml b/prql-compiler/prqlc/Cargo.toml
index 40b0ced3..ae9cd009 100644
--- a/prql-compiler/prqlc/Cargo.toml
+++ b/prql-compiler/prqlc/Cargo.toml
@@ -28,3 +28,10 @@ walkdir = "^2.3.2"
 
 [target.'cfg(not(target_family="wasm"))'.dev-dependencies]
 insta = {version = "1.28", features = ["colors", "glob", "yaml"]}
+
+[build-dependencies]
+clap = {version = "4.1.1", features = ["derive"]}
+clap_mangen = "0.2.9"
+
+[dependencies]
+clap_complete = "4.1.4"
diff --git a/prql-compiler/prqlc/src/cli.rs b/prql-compiler/prqlc/src/cli.rs
index 41db7dc8..05143ccb 100644
--- a/prql-compiler/prqlc/src/cli.rs
+++ b/prql-compiler/prqlc/src/cli.rs
@@ -1,6 +1,6 @@
 use anyhow::Result;
 use ariadne::Source;
-use clap::{Parser, Subcommand};
+use clap::{CommandFactory, Parser, Subcommand};
 use clio::{Input, Output};
 use itertools::Itertools;
 use std::io::{Read, Write};
@@ -14,12 +14,27 @@
 
 use crate::watch;
 
+use clap::Command as ClapCommand;
+use clap_complete::{generate, Generator, Shell};
+use std::io;
+
 /// Entrypoint called by [crate::main]
 pub fn main() -> color_eyre::eyre::Result<()> {
     env_logger::builder().format_timestamp(None).init();
     color_eyre::install()?;
     let mut cli = Cli::parse();
 
+    let matches = Cli::command().get_matches();
+
+    if let Some(generator) = dbg!(matches).get_one::<Shell>("compile").copied() {
+        dbg!(generator);
+        let mut cmd = Cli::command();
+        eprintln!("Generating completion file for {}...", generator);
+        print_completions(generator, &mut cmd);
+    } else {
+        dbg!("No generator");
+    }
+
     if let Err(error) = cli.command.run() {
         eprintln!("{error}");
         exit(1)
@@ -28,7 +43,12 @@ pub fn main() -> color_eyre::eyre::Result<()> {
     Ok(())
 }
 
+fn print_completions<G: Generator>(gen: G, cmd: &mut ClapCommand) {
+    generate(gen, cmd, cmd.get_name().to_string(), &mut io::stdout());
+}
+
 #[derive(Parser, Debug, Clone)]
+#[command(about = "hello")]
 struct Cli {
     #[command(subcommand)]
     command: Command,
@@ -65,6 +85,7 @@ enum Command {
 
     /// Watch a directory and compile .prql files to .sql files
     Watch(watch::WatchArgs),
+    // Generate,
 }
 
 #[derive(clap::Args, Default, Debug, Clone)]

[vanillajonathan]

Hmm, I wanted to rename this branch but it seems GitHub closed it. 😢️