Create a man page

[casey]

The readme can be converted to a man page:

http://asciidoctor.org/docs/user-manual/#man-pages

Would be nice to get command examples directly from clap. Also remember to include the grammar.

[casey]

Working on this, but it's ballooned into a huge and messy diff that refactors command line option handling and command launching.

I need to:

• rebase onto current master
• change name of the new Config struct to Options
• factor write tests for new arg parser
• factor in environment
• actually write the feature I set out to write

[Th3Whit3Wolf]

Would there be in any interest in using clap to generate the man page? This is from the Rust CLI WG.

[casey]

I'd definitely like to use clap to generate the command-line option section of the man page!

[Th3Whit3Wolf]

Since generating a man page with clap relies on using a non-master git version I have experimented with other avenues.

man

I played with man but the way they display options seemed not quite ideal (In retrospect I could probably have made it work with a custom section).

Enter roff-rs

I saw man's only dependency was roff-rs so I checked it out. It's a little more verbose but can pretty easily make whatever you want.

I have so far basically converted the just --help output into a man page that com

JUST(1)                                      General Commands Manual                                     JUST(1)

NAME
       just - Just a command runner

SYNOPSIS
       just [FLAGS] [OPTIONS] [--] [ARGUMENTS]...

DESCRIPTION
       just is a simple, fast and user-friendly alternative to make(1)

FLAGS
       --dry-run
              Print what just would do without doing it

       --dump Print entire justfile

       -e, --editor
              Open justfile with $EDITOR

       --evaluate
              Print evaluated variables

       --highlight
              Highlight echoed recipe lines in bold

       -l, --list
              List available recipes and their arguments

       -q, --quiet
              Suppress all output

       --summary
              List names of available recipes

       -v, --verbose
              Use verbose output

       -h, --help
              Print help information

       -V, --version
              Use version information

OPTIONS
       --color COLOR
              Print colorful output [default: auto] [possible values: auto, always, never]

       -f, --justfile JUSTFILE
              Use JUSTFILE as justfile

       --set VARIABLE VALUE
              Set VARIABLE to VALUE

       --shell SHELL
              Invoke SHELL to run recipes [default: sh]

       -s, --show RECIPE
              Show information about RECIPE

       -d, --working-directory WORKING-DIRECTORY
              Use WORKING-DIRECTORY as working directory. --justfile must also be set

                                                                                                         JUST(1)

Thoughts

Would you be interested in this kind of implementation?
If so what else would you like to have in it?
It should be noted that as of this moment the man page is created on run not build, so it would need to be ran from a seperate binary on install.

[casey]

For the command line options, I'd like to use clap, just because otherwise it'll be easy for the man page and the actual command line parser to get out of date. I think man page generation will land in Clap 3.0, which will probably take a while though, so I'm planning on just generating the non-command-line-option part of the man page now, using asciidoctor to convert the readme, since asciidoctor already has a man page backend.

[bb010g]

My last encounter with this sort of thing ended up in mdoc-to-md, which converts mandoc-package real manual pages (because all the converters I looked at had weird quirks) to Markdown. This allows you to just cat the manual page to a README header and keep things in sync. (It needs updating to a newer mandoc version, but is still operable & consistent thanks to the pinned Nix stuff in there in the meantime.)

[casey]

@bb010g That looks promising. Thank you very much for the tip!

[tgross35]

An update from the future, https://crates.io/crates/clap_mangen is a pretty sane choice nowadays. Probably a reasonable thing to add after #1924 finishes up.

[casey]

@tgross35 Nice! I just merged #2041, which generates the man page with clap_mangen (we were using help2man before).

It would still be nice to get the readme in there, but I think converting the markdown to sensible roff will require some work.

[tgross35]

mandown can do markdown->roff which IIRC works reasonable but it isn't very flexible. Maybe something through roff could be used to glue the mandown output to that of clap_mangen?