logo标签列表

Rust CLI工具撰写man手册的惯用方式是什么？

rustrust-cargo
16

在类Unix操作系统上，CLI应用程序通常提供man页面供参考。我还没有看到任何关于如何在Rust生态系统中做到这一点的好指南 - 这样做的惯用方法是什么？

我知道Cargo build scripts功能，这是否是通常的方法？如果是，它将如何生成man页面，并如何处理不同操作系统上的man安装？

3
我相信跟随CLI 工作组会很有成效。他们有一个关于命令行应用文档的具体问题，其中包括 man 页面。 - Shepmaster
1
谢谢提供这些链接！阅读文档后，我发现man页面仍然是一个未解决的问题。我看到ripgrep有一种可行的方法，我会研究一下。 - Espen H
5
ripgrep的关键策略是使用一个轻量的抽象层来定义clap，并存储每个clap参数的状态，这可以用于构建man手册中繁琐的部分。如果clap增加了查询其参数的API，则可以避免使用此抽象层。（但这对clap来说是相当大的变化，解决ripgrep的特定情况比完全一般的情况要容易得多。） - BurntSushi5
1个回答
3

我所知道的目前最佳方法是使用man crate。这仍然是一项正在进行的工作，CLI 工作组正在积极致力于增加更好的man页生成支持。

如 README 中所述，man 可以从类似以下语法的内容生成man页：

use man::prelude::*;

fn main() {
    let page = Manual::new("basic")
        .about("A basic example")
        .author(Author::new("Alice Person").email("alice@person.com"))
        .author(Author::new("Bob Human").email("bob@human.com"))
        .flag(
            Flag::new()
                .short("-d")
                .long("--debug")
                .help("Enable debug mode"),
        )
        .flag(
            Flag::new()
                .short("-v")
                .long("--verbose")
                .help("Enable verbose mode"),
        )
        .option(
            Opt::new("output")
                .short("-o")
                .long("--output")
                .help("The file path to write output to"),
        )
        .example(
            Example::new()
                .text("run basic in debug mode")
                .command("basic -d")
                .output("Debug Mode: basic will print errors to the console")
            )
        .custom(
            Section::new("usage note")
                .paragraph("This program will overwrite any file currently stored at the output path")
        )
        .render();

    println!("{}", page);
}
网页内容由stack overflow 提供, 点击上面的
可以查看英文原文，
原文链接