Updated docs/features/help.md

tleonhardt · tleonhardt · commit ef30d8dc0277 · 2025-09-13T18:50:18.000-04:00
diff --git a/docs/features/help.md b/docs/features/help.md
@@ -12,8 +12,8 @@ command. The `help` command by itself displays a list of the commands available:
 ```text
 (Cmd) help
 
-Documented commands (use 'help -v' for verbose/'help <topic>' for details):
-===========================================================================
+Documented Commands
+───────────────────
 alias  help     ipy    py    run_pyscript  set    shortcuts
 edit   history  macro  quit  run_script    shell
 ```
@@ -24,9 +24,9 @@ The `help` command can also be used to provide detailed help for a specific comm
 (Cmd) help quit
 Usage: quit [-h]
 
-Exit this application
+Exit this application.
 
-optional arguments:
+Optional Arguments:
   -h, --help  show this help message and exit
 ```
 
@@ -37,8 +37,9 @@ help for a command is the docstring for the `do_*` method defining the command -
 **foo**, that command is implemented by defining the `do_foo` method and the docstring for that
 method is the help.
 
-For commands which use one of the `argparse` decorators to parse arguments, help is provided by
-`argparse`. See [Help Messages](./argument_processing.md#help-messages) for more information.
+For commands which use the [@with_argparser][cmd2.with_argparser] decorator to parse arguments, help
+is provided by `argparse`. See [Help Messages](./argument_processing.md#help-messages) for more
+information.
 
 Occasionally there might be an unusual circumstance where providing static help text isn't good
 enough and you want to provide dynamic information in the help text for a command. To meet this
@@ -51,42 +52,41 @@ not use an `argparse` decorator because we didn't want different output for `hel
 
 By default, the `help` command displays:
 
-    Documented commands (use 'help -v' for verbose/'help <topic>' for details):
-    ===========================================================================
+    Documented Commands
+    ───────────────────
     alias  help     ipy    py    run_pyscript  set    shortcuts
     edit   history  macro  quit  run_script    shell
 
 If you have a large number of commands, you can optionally group your commands into categories.
-Here's the output from the example `help_categories.py`:
-
-    Documented commands (use 'help -v' for verbose/'help <topic>' for details):
+Here's the output from the example
+[help_categories.py](https://github.com/python-cmd2/cmd2/blob/main/examples/help_categories.py):
 
     Application Management
-    ======================
+    ──────────────────────
     deploy  findleakers  redeploy  sessions  stop
     expire  list         restart   start     undeploy
 
     Command Management
-    ==================
+    ──────────────────
     disable_commands  enable_commands
 
     Connecting
-    ==========
+    ──────────
     connect  which
 
     Server Information
-    ==================
+    ──────────────────
     resources  serverinfo  sslconnectorciphers  status  thread_dump  vminfo
 
     Other
-    =====
-    alias   edit  history  py    run_pyscript  set    shortcuts
-    config  help  macro    quit  run_script    shell  version
+    ─────
+    alias   edit  history  quit          run_script  shell      version
+    config  help  macro    run_pyscript  set         shortcuts
 
-There are 2 methods of specifying command categories, using the `@with_category` decorator or with
-the `categorize()` function. Once a single command category is detected, the help output switches to
-a categorized mode of display. All commands without an explicit category defined default to the
-category `Other`.
+There are 2 methods of specifying command categories, using the [@with_category][cmd2.with_category]
+decorator or with the [categorize()][cmd2.categorize] function. Once a single command category is
+detected, the help output switches to a categorized mode of display. All commands without an
+explicit category defined default to the category `Other`.
 
 Using the `@with_category` decorator:
 
@@ -134,58 +134,70 @@ categorize((do_undeploy,
 The `help` command also has a verbose option (`help -v` or `help --verbose`) that combines the help
 categories with per-command help messages:
 
-    Documented commands (use 'help -v' for verbose/'help <topic>' for details):
-
     Application Management
-    ======================================================================================================
-    deploy                Deploy command.
-    expire                Expire command.
-    findleakers           Find Leakers command.
-    list                  List command.
-    redeploy              Redeploy command.
-    restart               Restart command.
-    sessions              Sessions command.
-    start                 Start command.
-    stop                  Stop command.
-    undeploy              Undeploy command.
+    ─────────────────────────────────────
+    Name          Description
+    ─────────────────────────────────────
+    deploy        Deploy command.
+    expire        Expire command.
+    findleakers   Find Leakers command.
+    list          List command.
+    redeploy      Redeploy command.
+    restart       Restart command.
+    sessions      Sessions command.
+    start         Start command.
+    stop          Stop command.
+    undeploy      Undeploy command.
+
 
     Command Management
-    ======================================================================================================
-    disable_commands      Disable the Application Management commands.
-    enable_commands       Enable the Application Management commands.
+    ─────────────────────────────────────────────────────────────────
+    Name               Description
+    ─────────────────────────────────────────────────────────────────
+    disable_commands   Disable the Application Management commands.
+    enable_commands    Enable the Application Management commands.
+
 
     Connecting
-    ======================================================================================================
-    connect               Connect command.
-    which                 Which command.
+    ────────────────────────────
+    Name      Description
+    ────────────────────────────
+    connect   Connect command.
+    which     Which command.
+
 
     Server Information
-    ======================================================================================================
+    ─────────────────────────────────────────────────────────────────────────────────────────────────
+    Name                  Description
+    ─────────────────────────────────────────────────────────────────────────────────────────────────
     resources             Resources command.
     serverinfo            Server Info command.
     sslconnectorciphers   SSL Connector Ciphers command is an example of a command that contains
-                          multiple lines of help information for the user. Each line of help in a
-                          contiguous set of lines will be printed and aligned in the verbose output
-                          provided with 'help --verbose'.
+                        multiple lines of help information for the user. Each line of help in a
+                        contiguous set of lines will be printed and aligned in the verbose output
+                        provided with 'help --verbose'.
     status                Status command.
     thread_dump           Thread Dump command.
     vminfo                VM Info command.
 
+
     Other
-    ======================================================================================================
-    alias                 Manage aliases.
-    config                Config command.
-    edit                  Run a text editor and optionally open a file with it.
-    help                  List available commands or provide detailed help for a specific command.
-    history               View, run, edit, save, or clear previously entered commands.
-    macro                 Manage macros.
-    quit                  Exit this application.
-    run_pyscript          Run Python script within this application's environment.
-    run_script            Run text script.
-    set                   Set a settable parameter or show current settings of parameters.
-    shell                 Execute a command as if at the OS prompt.
-    shortcuts             List available shortcuts.
-    version               Version command.
+    ─────────────────────────────────────────────────────────────────────────────────────────
+    Name           Description
+    ─────────────────────────────────────────────────────────────────────────────────────────
+    alias          Manage aliases.
+    config         Config command.
+    edit           Run a text editor and optionally open a file with it.
+    help           List available commands or provide detailed help for a specific command.
+    history        View, run, edit, save, or clear previously entered commands.
+    macro          Manage macros.
+    quit           Exit this application.
+    run_pyscript   Run Python script within this application's environment.
+    run_script     Run text script.
+    set            Set a settable parameter or show current settings of parameters.
+    shell          Execute a command as if at the OS prompt.
+    shortcuts      List available shortcuts.
+    version        Version command.
 
 When called with the `-v` flag for verbose help, the one-line description for each command is
 provided by the first line of the docstring for that command's associated `do_*` method.
