Merge pull request #1647 from dbcli/RW/further-refine-inline-help-descriptions

Further refine inline help descriptions

Author: rolandwalker

changelog.md

@@ -22,6 +22,7 @@ Bug Fixes
 Documentation
 ---------
 * Add `help <keyword>` to TIPS.
+* Refine inline help descriptions.
 
 
 1.57.0 (2026/02/25)

mycli/main.py

@@ -348,7 +348,7 @@ def register_special_commands(self) -> None:
             case_sensitive=True,
         )
         special.register_special_command(
-            self.execute_from_file, "source", "source <filename>", "Execute commands from file.", aliases=["\\."]
+            self.execute_from_file, "source", "source <filename>", "Execute queries from a file.", aliases=["\\."]
         )
         special.register_special_command(
             self.change_prompt_format, "prompt", "prompt <string>", "Change prompt format.", aliases=["\\R"], case_sensitive=True

mycli/packages/special/iocommands.py

@@ -104,13 +104,13 @@ def set_pager(arg: str, **_) -> list[SQLResult]:
     return [SQLResult(status=msg)]
 
 
-@special_command("nopager", "nopager", "Disable pager, print to stdout.", arg_type=ArgType.NO_QUERY, aliases=["\\n"], case_sensitive=True)
+@special_command("nopager", "nopager", "Disable pager; print to stdout.", arg_type=ArgType.NO_QUERY, aliases=["\\n"], case_sensitive=True)
 def disable_pager() -> list[SQLResult]:
     set_pager_enabled(False)
     return [SQLResult(status="Pager disabled.")]
 
 
-@special_command("\\timing", "\\timing", "Toggle timing of commands.", arg_type=ArgType.NO_QUERY, aliases=["\\t"], case_sensitive=True)
+@special_command("\\timing", "\\timing", "Toggle timing of queries.", arg_type=ArgType.NO_QUERY, aliases=["\\t"], case_sensitive=True)
 def toggle_timing() -> list[SQLResult]:
     global TIMING_ENABLED
     TIMING_ENABLED = not TIMING_ENABLED
@@ -555,7 +555,7 @@ def flush_pipe_once_if_written(post_redirect_command: str) -> None:
     PIPE_ONCE['stdout_mode'] = None
 
 
-@special_command("watch", "watch [seconds] [-c] <query>", "Executes the query every [seconds] seconds (by default 5).")
+@special_command("watch", "watch [seconds] [-c] <query>", "Execute query every [seconds] seconds (5 by default).")
 def watch_query(arg: str, **kwargs) -> Generator[SQLResult, None, None]:
     usage = """Syntax: watch [seconds] [-c] query.
     * seconds: The interval at the query will be repeated, in seconds.

mycli/packages/special/main.py

@@ -208,7 +208,7 @@ def quit_(*_args):
 @special_command(
     "\\edit",
     "<query>\\edit | \\edit <filename>",
-    "Edit query with editor (uses $EDITOR).",
+    "Edit query with editor (uses $VISUAL or $EDITOR).",
     arg_type=ArgType.NO_QUERY,
     case_sensitive=True,
     aliases=['\\e'],
@@ -221,6 +221,13 @@ def stub():
 
 if LLM_IMPORTED:
 
-    @special_command("\\llm", "\\llm [arguments]", "Interrogate an LLM.", arg_type=ArgType.RAW_QUERY, case_sensitive=True, aliases=["\\ai"])
+    @special_command(
+        "\\llm",
+        "\\llm [arguments]",
+        "Interrogate an LLM.  See \"\\llm help\".",
+        arg_type=ArgType.RAW_QUERY,
+        case_sensitive=True,
+        aliases=["\\ai"],
+    )
     def llm_stub():
         raise NotImplementedError

test/features/fixture_data/help_commands.txt

@@ -5,33 +5,33 @@
 | \bug           | <nope>   | \bug                            | File a bug on GitHub.                                       |
 | \clip          | <nope>   | <query>\clip                    | Copy query to the system clipboard.                         |
 | \dt            | <nope>   | \dt[+] [table]                  | List or describe tables.                                    |
-| \edit          | \e       | <query>\edit | \edit <filename> | Edit query with editor (uses $EDITOR).                      |
+| \edit          | \e       | <query>\edit | \edit <filename> | Edit query with editor (uses $VISUAL or $EDITOR).           |
 | \f             | <nope>   | \f [name [args..]]              | List or execute favorite queries.                           |
 | \fd            | <nope>   | \fd <name>                      | Delete a favorite query.                                    |
 | \fs            | <nope>   | \fs <name> <query>              | Save a favorite query.                                      |
 | \l             | <nope>   | \l                              | List databases.                                             |
-| \llm           | \ai      | \llm [arguments]                | Interrogate an LLM.                                         |
+| \llm           | \ai      | \llm [arguments]                | Interrogate an LLM.  See "\llm help".                       |
 | \once          | \o       | \once [-o] <filename>           | Append next result to an output file (overwrite using -o).  |
 | \pipe_once     | \|       | \pipe_once <command>            | Send next result to a subprocess.                           |
-| \timing        | \t       | \timing                         | Toggle timing of commands.                                  |
+| \timing        | \t       | \timing                         | Toggle timing of queries.                                   |
 | connect        | \r       | connect [database]              | Reconnect to the server, optionally switching databases.    |
 | delimiter      | <nope>   | delimiter <string>              | Change end-of-statement delimiter.                          |
 | exit           | \q       | exit                            | Exit.                                                       |
 | help           | \?       | help [term]                     | Show this help, or search for a term on the server.         |
-| nopager        | \n       | nopager                         | Disable pager, print to stdout.                             |
+| nopager        | \n       | nopager                         | Disable pager; print to stdout.                             |
 | notee          | <nope>   | notee                           | Stop writing results to an output file.                     |
 | nowarnings     | \w       | nowarnings                      | Disable automatic warnings display.                         |
 | pager          | \P       | pager [command]                 | Set pager to [command]. Print query results via pager.      |
 | prompt         | \R       | prompt <string>                 | Change prompt format.                                       |
 | quit           | \q       | quit                            | Quit.                                                       |
 | redirectformat | \Tr      | redirectformat <format>         | Change the table format used to output redirected results.  |
 | rehash         | \#       | rehash                          | Refresh auto-completions.                                   |
-| source         | \.       | source <filename>               | Execute commands from file.                                 |
+| source         | \.       | source <filename>               | Execute queries from a file.                                |
 | status         | \s       | status                          | Get status information from the server.                     |
 | system         | <nope>   | system <command>                | Execute a system shell commmand.                            |
 | tableformat    | \T       | tableformat <format>            | Change the table format used to output interactive results. |
 | tee            | <nope>   | tee [-o] <filename>             | Append all results to an output file (overwrite using -o).  |
 | use            | \u       | use <database>                  | Change to a new database.                                   |
 | warnings       | \W       | warnings                        | Enable automatic warnings display.                          |
-| watch          | <nope>   | watch [seconds] [-c] <query>    | Executes the query every [seconds] seconds (by default 5).  |
+| watch          | <nope>   | watch [seconds] [-c] <query>    | Execute query every [seconds] seconds (5 by default).       |
 +----------------+----------+---------------------------------+-------------------------------------------------------------+