Display recipe aliases inline with the recipe doc

[marcaddeo]

This updates the --list subcommand to display aliases inline with the recipe doc.

Before:

Available recipes:
    choose               # Open an interactive chooser of available commands
    c                    # alias for `choose`

After:

Available recipes:
    choose               # Open an interactive chooser of available commands [aliases: c]

[casey]

I personally think this is an improvement, but I'd like to get some feedback on it first.

Paging some regulars:

@laniakea64 @neunenak @runeimp

What do you think?

[laniakea64]

I agree that displaying aliases inline would be nicer, and I like the [aliases: alias1, alias2] notation. But placing this in the recipe documentation is confusing. Maybe it would be better placed with the recipe name/signature, perhaps in a distinctive color?

[marcaddeo]

I agree that displaying aliases inline would be nicer, and I like the [aliases: alias1, alias2] notation. But placing this in the recipe documentation is confusing. Maybe it would be better placed with the recipe name/signature, perhaps in a distinctive color?

I think that may make it look somewhat odd to have aliases next to the recipe signature. Putting the aliases there would mean increasing the width of the recipe signature, causing all recipe docs to have to have a lot of padding between them. I think that suggested notation works best for flags/short flags. Whereas there's no limitation on how short or long, or how many, your aliases are.

The way I see it is, an alias is not pertinent information to be prominently displayed in the listing. The list is still useful, even if you have to search slightly for your commands alias.

But maybe my thinking is wrong here :)

I had originally colored the [alias: alias1, alias2] portion of the recipe doc in the annotation color (purple) so it stood out a bit. I wasn't sure if that was a desirable trait, however, and changed it back to the default. Maybe changing the color to purple here, or a different color, would be a good middle ground so that they're more noticeable?

[casey]

I think changing the color would be nice, so that it doesn't look like it's part of the doc.

[laniakea64]

Think semantically: Invocation info is on the left, and description of what the recipe does is on the right. Mixing this information together makes it less human-parseable.

As a compromise to avoid the formatting issue, the aliases could be on the left side of the documentation comment and colorized:

Available recipes:
    choose               # [aliases: c] Open an interactive chooser of available commands

[casey]

Available recipes:
    choose               # [aliases: c] Open an interactive chooser of available commands

I think the downside is that it pushes the doc to the right, and the doc is probably more interesting to the user than the list of aliases.

[runeimp]

I love the concept of inlining aliases. I may have suggested it at one point but don't remember. In any case there is on glaring problem (that I hate) which is that a recipe could have infinite aliases. The current method is the only way that handles the situation consistently. But if we know (do we know?) that if a recipe has an alias at all that say a single alias is used 97% of the time and two aliases 2% of the time and three or more aliases only 1% of the time then I believe there is wiggle room to inline by default.

We could also do the inlining by default and have a set inline-flags=false available for those few that like to have 3 or more aliases all the time.

[marcaddeo]

I think changing the color would be nice, so that it doesn't look like it's part of the doc.

Are there any opinions on what color it should be, or a scheme the project is adhering to?

I love the concept of inlining aliases. I may have suggested it at one point but don't remember. In any case there is on glaring problem (that I hate) which is that a recipe could have infinite aliases. The current method is the only way that handles the situation consistently. But if we know (do we know?) that if a recipe has an alias at all that say a single alias is used 97% of the time and two aliases 2% of the time and three or more aliases only 1% of the time then I believe there is wiggle room to inline by default.

Is this something really to be concerned with, though? You also can have as long as a recipe doc as you want, spanning multiple lines. Wouldn't it be up to the end user to decide how many aliases is too many, like it's their decision on how long the recipe doc is?

We could also do the inlining by default and have a set inline-flags=false available for those few that like to have 3 or more aliases all the time.

So with set inline-flags=false, the aliases would revert to the original behavior of being displayed on their own lines? Would this be better suited as a --no-inline-aliases flag on the --list subcommand, if we go that direction?

[neunenak]

Maybe a good compromise would be to inline the aliases if the total length of them is short, and otherwise stick with the current behavior of listing them below the recipe they are aliases for? (I actually think it would be a good idea to indent the alias lines below the recipe line, to make it visually clearer that the lines form a conceptual group). I think the most common case is definitely that people have one short alias for a recipe, so optimizing for that case is ok as long as it doesn't completely break things for people with less common use cases. And in that common case having an inline alias makes sense. And having a command line flag to force aliases onto their own line in all cases also makes sense to me.

I agree that having a special color for aliases is a good idea, and I don't feel strongly about whether an inlined alias comes before or after the doc comment.

[casey]

One concern: Are there possibly cases where the alias is actually the descriptive, user-discoverable name, and it would hurt discoverability if it isn't present in the list output on its own line?

[laniakea64]

One concern: Are there possibly cases where the alias is actually the descriptive, user-discoverable name,

#1725

and it would hurt discoverability if it isn't present in the list output on its own line?

Trying this out on that justfile: yes, moving the aliases to the right of the documentation comment hurts discoverability.

If the aliases were inlined to the left of the documentation comment, it would actually improve discoverability compared to having the aliases on their own lines.

[marcaddeo]

I've updated the code so that the [aliases: a, b, c] notation is now colored Purple. I don't have a strong opinion on what the color should be, happy to change to something else.

Here's how it looks in my terminal:

For recipe's that have aliases but do not have a document, should the aliases display as # [aliases: a, b,c ] (as seen in the screenshot) or should the # be omitted?

As an aside, the inspiration for this notation (aliases on the right of the command help text) came from clap (at least for me, can't speak for the other people who requested this) so that's what I was trying to emulate.

This is how clap handles many and long aliases for comparison:

± cargo run --features derive --features cargo --example 03_04_subcommands --
   Compiling clap v4.5.17 (/Users/marc/dev/clap)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.23s
     Running `target/debug/examples/03_04_subcommands`
A simple to use, efficient, and full-featured Command Line Argument Parser

Usage: 03_04_subcommands <COMMAND>

Commands:
  add   Adds files to myapp [aliases: a, b, c, d, e, f, g, h, a-really-long-alias-goes-here-and-stuff, this-is-just-going-to-be-the-longest-alias-you-have-ever-seen-its-really-incredible-you-wont-believe-your-eyes]
  help  Print this message or the help of the given subcommand(s)

Options:
  -h, --help     Print help
  -V, --version  Print version

And with Just using these changes (other recipes removed for brevity):

± cargo run --bin just -- --list
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.05s
     Running `target/debug/just --list`
Available recipes:
    sloc                                          # count non-empty lines of code [aliases: a, a-really-long-alias-goes-here-and-stuff, b, c, d, e, f, g, h, this-is-just-going-to-be-the-longest-alias-you-have-ever-seen-its-really-incredible-you-wont-believe-your-eyes]
    test                                          # [aliases: t]

So this follows the pattern clap is using pretty closely, but obviously Just is not clap so it doesn't necessarily hold much weight on the decisions made here. But I Just wanted to show that this is an established practice in other tools.

One concern: Are there possibly cases where the alias is actually the descriptive, user-discoverable name,

#1725

and it would hurt discoverability if it isn't present in the list output on its own line?

Trying this out on that justfile: yes, moving the aliases to the right of the documentation comment hurts discoverability.

If the aliases were inlined to the left of the documentation comment, it would actually improve discoverability compared to having the aliases on their own lines.

I'm not sure I'm understanding the concern here. I looked through #1725 and the referenced discussion, and it seems like aliases are being used as a workaround to what looks to be a bug in argument expansion when passing to dependencies?

[laniakea64]

I've updated the code so that the [aliases: a, b, c] notation is now colored Purple.

Nice, purple is good choice! 👍 It's distinct from doc comments, distinct from recipe parameters and values, and keeps contrast with the blue doc comment when using a very warm monitor color temperature with Gammastep.

As an aside, the inspiration for this notation (aliases on the right of the command help text) came from clap (at least for me, can't speak for the other people who requested this) so that's what I was trying to emulate.

This is how clap handles many and long aliases for comparison:

± cargo run --features derive --features cargo --example 03_04_subcommands --
   Compiling clap v4.5.17 (/Users/marc/dev/clap)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.23s
     Running `target/debug/examples/03_04_subcommands`
A simple to use, efficient, and full-featured Command Line Argument Parser

Usage: 03_04_subcommands <COMMAND>

Commands:
  add   Adds files to myapp [aliases: a, b, c, d, e, f, g, h, a-really-long-alias-goes-here-and-stuff, this-is-just-going-to-be-the-longest-alias-you-have-ever-seen-its-really-incredible-you-wont-believe-your-eyes]
  help  Print this message or the help of the given subcommand(s)

Options:
  -h, --help     Print help
  -V, --version  Print version

That clap output has different semantics from just --list. It doesn't try to present subcommand invocation info. Its left side is subcommand name/title only, its right side is a brief descriptive summary. Which makes it natural for it to have aliases on the right.

I'm not sure I'm understanding the concern here.

When the main recipe name is uninformative: if the descriptive alias isn't in the invocation info, people can't scan just --list output to easily find what recipe(s) might have that functionality. It takes much more mental processing to sift through all the doc comments.

[runeimp]

@marcaddeo

I love the concept of inlining aliases. I may have suggested it at one point but don't remember. In any case there is on glaring problem (that I hate) which is that a recipe could have infinite aliases. The current method is the only way that handles the situation consistently. But if we know (do we know?) that if a recipe has an alias at all that say a single alias is used 97% of the time and two aliases 2% of the time and three or more aliases only 1% of the time then I believe there is wiggle room to inline by default.

Is this something really to be concerned with, though? You also can have as long as a recipe doc as you want, spanning multiple lines. Wouldn't it be up to the end user to decide how many aliases is too many, like it's their decision on how long the recipe doc is?

Yes, knowing what percentage of the user base this would directly affect lets us know if we can make changes with abandon or how much consideration we should consider for potential disruption, if that information is available. It also can inform the context of reasonable defaults to avoid unnecessary configuration options which potentially adds complexity with no benefit to the end user. I generally prefer control. But I use Mac because I like the defaults of the OS. I could get more control with POSIX systems like GNU/Linux. But I'm not in love with most of the defaults.

We could also do the inlining by default and have a set inline-flags=false available for those few that like to have 3 or more aliases all the time.

So with set inline-flags=false, the aliases would revert to the original behavior of being displayed on their own lines? Would this be better suited as a --no-inline-aliases flag on the --list subcommand, if we go that direction?

Right, inline-flags=false defaults to the current setup. I believe the command line option should exist along with the configuration setting. Cover all the bases. 🙂

[marcaddeo]

Just pushed a commit that adds a --no-inline-aliases command line flag to opt-out of the inline aliases.

I'm not sure if it makes sense for this to be a Justfile setting, however, as the documentation reads:

Settings control interpretation and execution. Each setting may be specified at most once, anywhere in the justfile.

And this setting wouldn't control interpretation or execution, just the display of the --list subcommand.

EDIT: Just wanted to point out this will need some additional tests but I figured I'd hold off until there's some decisions made on how this should progress forward.

[runeimp]

What is the big hangup over having a setting? My default recipe is just --list 99.99% of the time. I use Just specifically to document what command line tools and preferred options I have with any given project.

Also when I do run just --list bare in an existing project I don't want to have to remember the special option that gives me the output I want over 99% of the time in any project. Are settings difficult to create and maintain in Rust?

[marcaddeo]

What is the big hangup over having a setting? My default recipe is just --list 99.99% of the time. I use Just specifically to document what command line tools and preferred options I have with any given project.

Also when I do run just --list bare in an existing project I don't want to have to remember the special option that gives me the output I want over 99% of the time in any project. Are settings difficult to create and maintain in Rust?

I was just going off of what the documentation states, so as not to conflict with the design decisions of Just.

However, Just options can also be set via environment variables. So you could add export JUST_NO_INLINE_ALIASES=true to your .bashrc/etc to opt-out of the new list formatting.

[laniakea64]

What is the big hangup over having a setting?

Because this option doesn't decide how the justfile will behave. It only decides how just presents information.

just --list is not only for justfile authors, it's for anyone who might run the justfile recipes. If there are options in how to present the recipes included in just --list output, it makes most sense to leave it to whoever is going to read the just --list output to decide what's clearer for them.

And the global environment variable suggestion seems much better anyway, as it lets you have your preference on this regardless of whether you authored the justfile.

[runeimp]

I was just going off of what the documentation states, so as not to conflict with the design decisions of Just.

However, Just options can also be set via environment variables. So you could add export JUST_NO_INLINE_ALIASES=true to your .bashrc/etc to opt-out of the new list formatting.

@marcaddeo Sorry, if I was a bit aggressive. It's just been a very rough few months for me and I was feeling a bit attacked with that prior statement. The environment variable is not a 100% solution for me. My problem is easily fixed by simply adding a setting I can set differently in every other project as I need instead of an all or nothing 100% of the time. I can do a hack like adding --no-inline-aliases to the default recipe. But that is just another hack I'd like to avoid. The real solution is simply using a setting.

@casey could you weigh in? I don't want to go against your general plans for Just but this exception seems reasonable to me.

[laniakea64]

@runeimp It feels like there maybe a XY-like problem here: To avoid further misunderstanding of where you're coming from, could you please be more specific what exactly you would like to achieve that you think can only be done by a justfile setting to toggle inlining of aliases?

[runeimp]

What is the big hangup over having a setting?

Because this option doesn't decide how the justfile will behave. It only decides how just presents information.

I disagree. I do consider the display of information a behavior of the tool.

just --list is not only for justfile authors, it's for anyone who might run the justfile recipes. If there are options in how to present the recipes included in just --list output, it makes most sense to leave it to whoever is going to read the just --list output to decide what's clearer for them.

And the global environment variable suggestion seems much better anyway, as it lets you have your preference on this regardless of whether you authored the justfile.

@laniakea64 I appreciate that your considering this is an XY-problem. And this could be, but in the sense that this feature should not have been an option only to begin with. I think that it should have instead been a setting first with the option added in support of the possible transitive nature of the setting in any given situation.

The issue is that I will want it one way for over 90% of my projects. And I will 100% want it the other way for a small percentages of projects. A setting via an environment variable only allows for one way for all local projects. And some special consideration on how to manage that setting in the other projects to overcome the environment variable. The only way to handle that which is consistent with anything is a setting I can manage per project. I can set the environment variable if needed for the majority of projects and then consistently set the local setting in the Justfile for unambiguous handling in the other projects. Or I end up special case handling for every project I realize has to be handled differently because a simple setting is not desired.

[laniakea64]

The issue is that I will want it one way for over 90% of my projects. And I will 100% want it the other way for a small percentages of projects.

Thanks for clarifying. So without a setting, with only a command-line flag + environment variable, the closest would be every project having its own recipe to run just --list with the environment variable explicitly set correctly. Yeah, not a solution.

Would there be a pattern in when you'd want this one way vs the other? Could/should just --list detect such pattern and automatically make the right choice by default?

[runeimp]

I doubt a universal rational for when to and when not to is achievable. More than one alias? That doesn't mean much if all the aliases are one or two letters. Any alias more than 8 characters? Lots of people will think that is too many or not enough of a limit. Only when the terminal has over 80 characters wide? Basically the same problem as max length of a single alias. What font is being used in the terminal? etc.

All of that and more is likely way too fiddly. I suspect the only way to make such a formula work at all would require several more settings. I think the binary true|false is sufficient.

[marcaddeo]

@marcaddeo Yooo, sorry for not looking at this, I've been letting my notifications pile up. Can you fix the merge conflicts and I'll take another look?

😅 happens! PR has been rebased, let me know what you think.

[casey]

This looks good! Did some compulsive tweaking of the code to avoid the need to do the left / right stuff.

What do you think about changing the name of the values to left, right, and separate? I think recipe is a little unclear, and having inline-left but just inline is a little inconsistent.

[marcaddeo]

This looks good! Did some compulsive tweaking of the code to avoid the need to do the left / right stuff.

What do you think about changing the name of the values to left, right, and separate? I think recipe is a little unclear, and having inline-left but just inline is a little inconsistent.

left, right, and separate seems good to me, should be pretty clear what they do

[casey]

LGTM