Update help text and documentation for history -t argument

Clarified that this actually re-runs the select commands since the expected output from the commands isn't saved in the history along with the commands themselves.

Author: tleonhardt

CHANGELOG.md

@@ -3,8 +3,9 @@
 - Breaking Change
     - `cmd2` 2.6 supports Python 3.9+ (removed support for Python 3.8)
 - Enhancements
-    - Add support for Python 3.14
+    - Added support for Python 3.14
     - Added new `Cmd.ppretty()` method for pretty printing arbitrary Python data structures
+    - Clarified help text for `-t`/`--transcript` argument to the `history` command
 
 ## 2.5.11 (January 25, 2025)
 

cmd2/cmd2.py

@@ -4632,7 +4632,7 @@ def do_ipy(self, _: argparse.Namespace) -> Optional[bool]:  # pragma: no cover
         '-t',
         '--transcript',
         metavar='TRANSCRIPT_FILE',
-        help='output commands and results to a transcript file,\nimplies -s',
+        help='create a transcript file by re-running the commands,\nimplies both -r and -s',
         completer=path_complete,
     )
     history_action_group.add_argument('-c', '--clear', action='store_true', help='clear all history')
@@ -4750,7 +4750,7 @@ def do_history(self, args: argparse.Namespace) -> Optional[bool]:
                 self.pfeedback(f"{len(history)} command{plural} saved to {full_path}")
                 self.last_result = True
         elif args.transcript:
-            # self.last_resort will be set by _generate_transcript()
+            # self.last_result will be set by _generate_transcript()
             self._generate_transcript(list(history.values()), args.transcript)
         else:
             # Display the history items retrieved

docs/features/history.md

@@ -127,6 +127,10 @@ The `history` command can also save both the commands and their output to a text
 
 The `--transcript` option implies `--run`: the commands must be re-run in order to capture their output to the transcript file.
 
+!!! warning
+
+    Unlike the `-o`/`--output-file` option, the `-t`/`--transcript` option will actually run the selected history commands again. This is necessary for creating a transcript file since the history saves the commands themselves but does not save their output. Please note that a side-effect of this is that the commands will appear again at the end of the history.
+
 The last action the history command can perform is to clear the command history using `-c` or `--clear`:
 
     (Cmd) history -c