Ways to improve the command-line interface

[ColeFrench]

We interact with Tectonic via its command-line interface, or CLI. Its help messages concisely describe how to use Tectonic to build documents, etc. I think some minor yet effective improvements can be made to the help messages in order to improve the user experience.

For reference, here is the current V2 help message (tectonic -X --help):

tectonic -X <version>
Process (La)TeX documents

USAGE:
    tectonic -X [OPTIONS] <SUBCOMMAND>

FLAGS:
    -h, --help       Prints help information
    -V, --version    Prints version information

OPTIONS:
    -c, --chatter <level>    How much chatter to print when running [default: default]  [possible values: default,
                             minimal]
        --color <when>       Control colorization of output [default: auto]  [possible values: always, auto, never]

SUBCOMMANDS:
    build      Build a document
    bundle     Commands relating to this document’s TeX file bundle
    compile    Run a standalone (La)TeX compilation
    dump       Run a partial compilation and output an intermediate file
    help       Prints this message or the help of the given subcommand(s)
    init       Initializes a new document in the current directory
    new        Create a new document project
    show       Display various useful pieces of information
    watch      Watch input files and execute commands on change

Suggestions

Combine flags and options

If you look at the above help output, or any help output from Tectonic, you will see one section for "flags" and one for "options". I propose merging these two into just "options". There is a comprehensive discussion of this in the clap repository (see below for introduction to clap), and I agree with the main argument that separating flags from options complicates things unnecessarily;

1. users probably don't care about the distinction, and
2. it can be confusing—I like the word "muddling" in the linked discussion—to have two different words to say "a change to Tectonic's execution".

Sorting

Right now, "flags" in the help message are sorted alphabetically by their long name (i.e., --help, not -h). I think most of us approve of this, because it facilitates finding a specific option and makes the help message look nice. (Although, justifiable alternatives include sorting by commonly used options or options with similar functionality.)

However, "options" currently sort by the name of their parameter (e.g., <level> in --chatter <level> ). This deviates from the sorting of flags and has no correlation with the name of the option. I suggest we sort "options" the same way as "flags", especially if the two are merged.

Color help messages if possible

Who doesn't love colors? AFAIK, clap does this by default.

Migrate to clap

Tectonic's internals currently use the structopt library to display and implement the CLI, but this library is old. As of February 2022, structopt is in maintenance mode; there will be no new features added to it (and none have been added since the announcement last year). We like new features, because they may make development simpler.

Additionally, one of the dependencies of structopt is not even being maintained anymore: ansi_term. This gives warnings such as in #1034 and is very bad, because there will be no security or bug fixes.

On the other hand, clap is popular and actively developed. As of v3, it does everything structopt does at least as well. The latest major version is v4, which was released September 2022 and has a new release as recent as yesterday.

clap offers instructions for migrating from structopt to v3 and from v3 to v4 that only require a little development effort.

[ColeFrench]

Hi @pkgw, do you have any thoughts on this before I begin working on a PR?

[pkgw]

Sorry for taking so long to follow up on this! And thank you for your PR on this topic.

I definitely agree that it would be good to port to clap V4. I don't love all of its choices, especially the specific thing that you mention where it distinguishes between "options" and "arguments", so I am happy to learn that this can be changed! But overall there is no good reason not to adopt the ecosystem-standard crate here, and to keep up with the latest version(s).

I'm a bit of a fuddy-duddy when it comes to colorized output since I worry about old systems and weird environments, or things like the classical Windows terminal which doesn't support ANSI colorization (hence the termcolor crate). By the same token I've never loved CLIs that use emojis for half their output. But, it's the year 2023 and I've never heard about any real-life issues caused by any of this stuff, so it is problem time for me to embrace change. Colorization in particular can really be helpful.

[ColeFrench]

Thanks for your insight! I'm glad our preferences align—so that I know I'm making sane points, and also so that I can just go ahead and implement everything in this post. To confirm, you do not want to distinguish between "flags" and "options", right?

I understand your concern about antiquated systems. Though I didn't pick up TeX until ~5 years ago, I know it's very old and predates Unicode, and I wouldn't be surprised to learn it predates ANSI codes!

Indeed, the purpose of my PR is to add a bunch of stdout checks to ensure Tectonic's usage messages are being displayed consistently. Some might say I'm overengineering the tests or that I'm introducing needless complexity, but I see it like this: They're just tests, so they can always be changed/removed and don't get in the way of maintenance/development, and they run very quickly.

I should be requesting a review on the PR soon, so you should have the chance to make your own judgement (whenever you have the chance!). The diff is intimidating, because I had to move existing tests around, but I'll try and find some way to make it more digestible.

[Neved4]

classical Windows terminal which doesn't support ANSI colorization

@pkgw Just an idea: when the terminal doesn't support ANSI colors couldn't we simply turn tem off?
Or get some code upstream that disables the colors when detecting legacy terms.

[ratmice]

But overall there is no good reason not to adopt the ecosystem-standard crate here, and to keep up with the latest version(s).

I think clap's latest releases have a fairly aggressive MSRV, in that clap 4.4.0 bumped MSRV to 1.70 less than 2 months after the release of 1.70. So that is something to be aware of. I think it'd be good to perhaps consider a semi-recent clap with lower MSRV instead of the latest.

I'm a bit of a fuddy-duddy when it comes to colorized output since I worry about old systems and weird environments, or things like the classical Windows terminal which doesn't support ANSI colorization (hence the termcolor crate).

It does look like clap depends upon the termcolor crate, and that crate does support setting the NO_COLOR env-var.
So that is at least something, Looks like it can also be set programmatically to ColorChoice::Never.

[ColeFrench]

Oh, that's a good point! For future reference, I just ran cargo-msrv on master on my machine (x86_64-unknown-linux-gnu), and it reported an MSRV of 1.66.1.

[pkgw]

I also noticed the aggressive-seeming MSRV bump in clap. Tectonic has never historically specified an MSRV, or a policy relating thereto, but that's a good point to keep in mind.

[goyalyashpal]

Combine flags and options

i will be against that.

• flags are used standalone, options are used with the subcommands.
• so, there is tectonic -X -c minimal build i.e. options used with subcommands
• but there is no tectonic -V build i.e. flags are not used with subcommand.