Command options (in help message) #4554

UncleSnail · 2024-10-08T17:43:08Z

Description

Show command options in the help message dialogue as specified in this comment and the associated PR discussion.

Handles truncating based on the full length of the line, not just the length of the options, and shows the full options on hover.

Always indicates the presence of options even on lines with very long descriptions.

Correctly handles flags (without showing them as flag=true)

Handles commands with multiple options.

This PR also switches the new hardReload for the old reload hard to avoid repeated code/functionality.

Implementation

There could be cleaner implementations, so let me know if you have a better idea, but I believe I have found a good method that requires minimal changes and fits very well into the existing mechanism. I will describe the implementation and logic more in comments on the code.

I have formatted all new code (see #4553 for the other changes from deno fmt) and all tests pass.

This truncation method is that requested by philc.

UncleSnail

I worked through a few different methods for implementing this, and have tried to explain why I believe this is the best given the existing code. If you have any more questions about why I chose this implementation, please ask!

UncleSnail · 2024-10-08T17:45:58Z

background_scripts/commands.js

@@ -64,8 +64,8 @@ const Commands = {

    for (const line of configLines) {
      const tokens = line.split(/\s+/);
-      const command = tokens[0].toLowerCase();
-      switch (command) {
+      const action = tokens[0].toLowerCase();


This change is for understandability. Before there were two variables named command within this block:

This "command" meaning map, unmap, etc.

The "command" on line 71 which is the actual command to be run, like "newTab" or "setZoom".
This caused understanding errors for me, so to avoid this for others in the future, I renamed the map vs unmap to the more fitting name action. Please suggest your name preference if different.

UncleSnail · 2024-10-08T17:52:15Z

background_scripts/commands.js

+      }
+      (commandToKey[registryEntry.command][optionString] != null
+        ? commandToKey[registryEntry.command][optionString]
+        : (commandToKey[registryEntry.command][optionString] = [])).push(key);


This section changes the commandToKey from a 1 level dictionary like:

{ "setZoom": ["z1", "z2"],// old design }

to a 2 level dictionary mapping from command to options set, like:

{ "setZoom: {// new design "1.1": ["z1"], "1.2": ["z2"], } }

Commands with no options will have the empty string options set, like:

{ "zoomIn: { "": ["zi"],//No options } }

This allows us to split key mappings to their respective command/options combo, while still allowing us to directly check if we have any mappings to a command with commandToKey[command] as we did before.

UncleSnail · 2024-10-08T17:57:34Z

background_scripts/commands.js

+            advanced: this.advancedCommands.includes(command),
+            options: options,
+          });
+        }


Since we now have a 2-level dictionary, we now have a nested loop to loop through both commands and each variation of the command with different options. This also allows us to remove the keys check for null because we provide a default empty array in the loop.

So, for each command we either get each option set and add a line for each, or if there are no mappings to the key we use { "": [] } which is like saying that the empty (default) options set (no options) has no key mappings. This all works correctly with the other code, including with the options "show available commands".

Note that now we are also passing the options with the command entry.

UncleSnail · 2024-10-08T17:58:23Z

background_scripts/commands.js

@@ -409,7 +416,7 @@ const defaultKeyMappings = {
  "d": "scrollPageDown",
  "u": "scrollPageUp",
  "r": "reload",
-  "R": "hardReload",
+  "R": "reload hard",


We also change the hardReload to reload hard and remove its associated code to avoid DRY violations and keep the code standard/maintainable.

UncleSnail · 2024-10-08T17:59:28Z

background_scripts/commands.js

-  zoomIn: ["Increase zoom", { background: true }],
-  zoomOut: ["Decrease zoom", { background: true }],
+  setZoom: ["Set zoom", { background: true }],
+  zoomIn: ["Zoom in", { background: true }],


Change the command descriptions for zoom in/out to make them match the command name and provide better intuition for the default mappings "zi" and "zo" since that name/description is where the mappings come from.

UncleSnail · 2024-10-08T18:09:01Z

pages/help_dialog.js

@@ -124,7 +124,17 @@ const HelpDialog = {
            });
          }

-          $$(descriptionElement, ".vimiumHelpDescription").textContent = command.description;
+          const MAX_LENGTH = 50;
+          const desiredOptionsLength = Math.max(0, MAX_LENGTH - command.description.length - 3);


Find the length that the options list should be to make the full description the right length. Don't ever let it be less than 0, and leave room for the ellipsis "...".

Since this might not be clear, I will explain why I implement it this correct way. It bothers me how many people implement this wrong. Leaving room means that we fit as long lines as we can. For example, if we want a line fewer than 10 characters, not leaving room (not having the - 3) would mean we need to truncate anything over 7 characters so that the ... does not make the line too long. So we end up with:

"truncated!" -> "truncat..."

There is no reason to do this since the word could have fit on the line (word is 10 chars and we are fine with 10 chars). The other common wrong implementation is to truncate anything >= 10 and add the "..." giving:

"truncated!" -> "truncated!..."

This gives us a line that is longer than 10 chars!

The correct implementation (like this where we leave space) means only lines that need to be truncated are, and we never make a line too long:

"truncated!" -> "truncated!" (10 chars)
"even longer" -> "even lo..." (10 chars)

I hope this explains what the -3 is for. I thought about adding a quick comment in the code there since it might not be clear, and I will do so if you like.

UncleSnail · 2024-10-08T18:10:03Z

pages/help_dialog.js

+          const desiredOptionsLength = Math.max(0, MAX_LENGTH - command.description.length - 3);
+          const optionsTruncated = command.options.substring(0, desiredOptionsLength);
+          let ellipis = "";
+          if ((command.description.length + command.options.length) > MAX_LENGTH) {


If we needed to truncate, add a set of ellipsis and set the title to the full options list so that we can see it on hover.

UncleSnail · 2024-10-08T18:12:06Z

pages/help_dialog.js

+          }
+          const optionsString = command.options ? ` (${optionsTruncated}${ellipis})` : "";
+          const fullDescription = `${command.description}${optionsString}`;
+          $$(descriptionElement, ".vimiumHelpDescription").textContent = fullDescription;


Note that this implementation works exactly as you described in your comment on #4518 where the options list is truncated, but not the ending ")" or the command description itself.

I tried the other methods of truncation, and I like this one the most. I agree with your design, it works very well.

UncleSnail · 2024-10-09T19:27:28Z

One more improvement that I think I should look into is ensuring the lines for the same command with different options inside of the help menu are reasonably ordered. Right now they aren't entirely. It's probably rare that it would be relevant, but for my setZoom commands that I use it is noticeable.

I could sort alphanumerically, but I think it makes the most sense to sort by the order the user has defined the commands in their mappings config. I plan to look into this, but I need to see if that is even feasible and it could be saved for a future PR.

UncleSnail · 2024-10-09T19:48:45Z

I also just pushed a commit to allow for a command + options set to be considered advanced. This way the reload hard command can be considered advanced and be hidden by default.

If you do not like this feature, I can easily remove this commit. It seems like hard reloading should be an advanced command, so I wanted to let us mark it as such, but it does add some complexity and the potential for the advanced command list to explode with advanced option choices.

Another implementation is to consider any command with options to be advanced, but then user mappings of simple commands (like new tab) with options are considered advanced and can't be seen in help without showing advanced options. I can imagine many users want to see their custom mappings without having "see advanced" checked, so I went with the implementation above. But, all options commands being advanced is a simpler solution to the problem with less scope-creep and still lets reload hard be advanced.

UncleSnail · 2024-10-09T19:53:23Z

background_scripts/commands.js

+            description: this.availableCommands[command].description,
+            keys: keys,
+            advanced: this.advancedCommands.includes(command) ||
+              this.advancedCommands.includes(`${command} ${options}`),


This is the line for allowing command + options sets to be considered advanced (like reload hard). We just also check if the advancedCommands list includes the command + options set.

UncleSnail · 2024-10-09T19:55:04Z

background_scripts/commands.js

@@ -386,11 +395,11 @@ const Commands = {
    "enterVisualLineMode",
    "toggleViewSource",
    "passNextKey",
-    "hardReload",


Previously (last PR), hardReload was considered an advanced command, but reload is not (so we add reload hard as an advanced command and add support for this).

UncleSnail · 2024-10-09T19:58:21Z

background_scripts/commands.js

-        ? commandToKey[registryEntry.command]
-        : (commandToKey[registryEntry.command] = [])).push(key);
+      const optionString = registryEntry.optionList?.length > 0
+        ? registryEntry.optionList?.join(" ")


Joining the option list here is the simplest way to turn the options back into a string. It does mean that differently written commands with the same options will be marked different. IE: command opt=example opt2=example2 is not equal to command opt2=example2 opt=example even though they are the same. I can do a mapping from the options object which would fix this problem if you would like, but it seemed like code bloat.

UncleSnail added 4 commits October 8, 2024 03:30

Change zoom command description to match mapping intuition.

4b3bdd5

Initial implementation of command options help messages.

51e8753

Remove hardReload command and replace it with reload hard

034630e

Change truncating logic to full description length and fmt.

0f93cb5

This truncation method is that requested by philc.

UncleSnail commented Oct 8, 2024

View reviewed changes

UncleSnail mentioned this pull request Oct 8, 2024

Fix DRY and Styling Issues (hardReload) #4518

Closed

Allow commands with options to be advanced (for hard reload).

63f266d

Fix advanced check styling.

6fdbdd1

UncleSnail commented Oct 9, 2024

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Command options (in help message) #4554

Command options (in help message) #4554

UncleSnail commented Oct 8, 2024

UncleSnail left a comment

UncleSnail Oct 8, 2024 •

edited

Loading

UncleSnail Oct 8, 2024 •

edited

Loading

UncleSnail Oct 8, 2024

UncleSnail Oct 8, 2024

UncleSnail Oct 8, 2024

UncleSnail Oct 8, 2024

UncleSnail Oct 8, 2024

UncleSnail Oct 8, 2024

UncleSnail commented Oct 9, 2024

UncleSnail commented Oct 9, 2024

UncleSnail Oct 9, 2024

UncleSnail Oct 9, 2024 •

edited

Loading

UncleSnail Oct 9, 2024

Command options (in help message) #4554

Are you sure you want to change the base?

Command options (in help message) #4554

Conversation

UncleSnail commented Oct 8, 2024

Description

Implementation

UncleSnail left a comment

Choose a reason for hiding this comment

UncleSnail Oct 8, 2024 • edited Loading

Choose a reason for hiding this comment

UncleSnail Oct 8, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

UncleSnail commented Oct 9, 2024

UncleSnail commented Oct 9, 2024

Choose a reason for hiding this comment

UncleSnail Oct 9, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

UncleSnail Oct 8, 2024 •

edited

Loading

UncleSnail Oct 8, 2024 •

edited

Loading

UncleSnail Oct 9, 2024 •

edited

Loading