[NEW] Extended Help for Commands.

[stockholmux]

The problem/use-case that the feature addresses

In valkey-cli, the help command will give you bare-bones information about a command, but it doesn't always give you enough information to know how to use it. Right now, this means that users typically have a CLI running next to a browser window. This may not be practical in some environments (i.e. air gapped situations) nor ergonomic.

Description of the feature

I would like a valkey-cli feature that optionally reads in the full reference information about a command. Here is what I have in mind:

• A users sets :extended-help-path /some/full/path/ in .valkeyclirc
• When a user asks for help on a command it reads in and renders the markdown (to text) for the command in addition to the standard help text. The cli uses the command name to match with a markdown file name using the same scheme asvalkey-doc (e.g. help set -> reads in /some/full/path/set.md). For most users, this would be the valkey-doc (or some artifact of valkey-doc), but it would allow flexibility to support additional user-defined commands for covering modules.

For example:

127.0.0.1:6379> help set

  SET key value [NX|XX] [GET] [EX seconds|PX milliseconds|EXAT unix-time-seconds|PXAT unix-time-milliseconds|KEEPTTL]
  summary: Sets the string value of a key, ignoring its type. The key is created if it doesn't exist.
  since: 1.0.0
  group: string
  complexity: O(1)

  Set key to hold the string value. If key already holds a value, it is overwritten, regardless of its type. Any previous time to live associated with the key is discarded on successful SET operation.

  Options

  The SET command supports a set of options that modify its behavior:

    EX seconds – Set the specified expire time, in seconds (a positive integer).
    PX milliseconds – Set the specified expire time, in milliseconds (a positive integer).
    EXAT timestamp-seconds – Set the specified Unix time at which the key will expire, in seconds (a positive integer).
    PXAT timestamp-milliseconds – Set the specified Unix time at which the key will expire, in milliseconds (a positive integer).
    NX – Only set the key if it does not already exist.
    XX – Only set the key if it already exists.
    KEEPTTL – Retain the time to live associated with the key.
    !GET – Return the old string stored at key, or nil if key did not exist. An error is returned and SET aborted if the value stored at key is not a string.

 Note: Since the SET command options can replace SETNX, SETEX, PSETEX, GETSET, it is possible that in future versions of Valkey 
...

127.0.0.1:6379> 

Note: if a user doesn't set anything in .valkeyclirc, this help isn't enabled and the help command works as it does today.

Alternatives you've considered

Externalized man pages for the command reference or users continuing to use web pages. This doesn't block either, but this feature would be substantially more convenient as it's right in the CLI.

Additional information

I'm not sure if there is a good C library for rendering markdown to the terminal. I could also see a situation where the help files are pre-rendered down to text by some other method (like an action in valkey-doc) to make this a simple operation for the CLI.

[madolson]

Externalized man pages for the command reference or users continuing to use web pages. This doesn't block either, but this feature would be substantially more convenient as it's right in the CLI.

We have man pages now, do we still want to do this?