Use backticks instead

Author: savannahostrowski

Doc/library/argparse.rst

@@ -645,24 +645,24 @@ are set.
 
 .. versionadded:: 3.14
 
-To highlight command examples in your description or epilog text, you can use
-``[cmd]...[/cmd]`` markup::
+To highlight inline code in your description or epilog text, you can use
+backticks::
 
    >>> parser = argparse.ArgumentParser(
    ...     formatter_class=argparse.RawDescriptionHelpFormatter,
    ...     epilog='''Examples:
-   ...   [cmd]python -m myapp --verbose[/cmd]
-   ...   [cmd]python -m myapp --config settings.json[/cmd]
+   ...   `python -m myapp --verbose`
+   ...   `python -m myapp --config settings.json`
    ... ''')
 
-When colors are enabled, the text inside ``[cmd]...[/cmd]`` tags will be
-displayed in a distinct color to help examples stand out. When colors are
-disabled, no transformation is applied and the tags remain as-is.
+When colors are enabled, the text inside backticks will be displayed in a
+distinct color to help examples stand out. When colors are disabled, backticks
+are preserved as-is, which is readable in plain text.
 
 .. note::
 
-   The ``[cmd]`` markup only applies to description and epilog text. It does
-   not apply to individual argument ``help`` strings.
+   Backtick markup only applies to description and epilog text. It does not
+   apply to individual argument ``help`` strings.
 
 .. versionadded:: 3.15
 

Doc/whatsnew/3.15.rst

@@ -423,8 +423,8 @@ argparse
   default to ``True``. This enables suggestions for mistyped arguments by default.
   (Contributed by Jakob Schluse in :gh:`140450`.)
 
-* Added ``[cmd]...[/cmd]`` markup support in description and epilog text to
-  highlight command examples when color output is enabled.
+* Added backtick markup support in description and epilog text to highlight
+  inline code when color output is enabled.
   (Contributed by Savannah Ostrowski in :gh:`142390`.)
 
 calendar

Lib/argparse.py

@@ -525,18 +525,17 @@ def _apply_text_markup(self, text):
         """Apply color markup to text.
 
         Supported markup:
-          [cmd]...[/cmd] - command/shell example (single color)
+          `...` - inline code (rendered with prog_extra color)
 
-        When colors are disabled, no transformation is applied.
+        When colors are disabled, backticks are preserved as-is.
         """
         t = self._theme
         if not t.reset:
             return text
         text = _re.sub(
-            r'\[cmd\](.*?)\[/cmd\]',
+            r'`([^`]+)`',
             rf'{t.prog_extra}\1{t.reset}',
             text,
-            flags=_re.DOTALL
         )
         return text
 

Lib/test/test_argparse.py

@@ -7560,11 +7560,11 @@ def test_error_and_warning_not_colorized_when_disabled(self):
         self.assertNotIn('\x1b[', warn)
         self.assertIn('warning:', warn)
 
-    def test_cmd_markup_in_epilog(self):
+    def test_backtick_markup_in_epilog(self):
         parser = argparse.ArgumentParser(
             prog='PROG',
             color=True,
-            epilog='Example: [cmd]python -m myapp --verbose[/cmd]',
+            epilog='Example: `python -m myapp --verbose`',
         )
 
         prog_extra = self.theme.prog_extra
@@ -7573,14 +7573,13 @@ def test_cmd_markup_in_epilog(self):
         help_text = parser.format_help()
         self.assertIn(f'Example: {prog_extra}python -m myapp --verbose{reset}',
                       help_text)
-        self.assertNotIn('[cmd]', help_text)
-        self.assertNotIn('[/cmd]', help_text)
+        self.assertNotIn('`', help_text)
 
-    def test_cmd_markup_in_description(self):
+    def test_backtick_markup_in_description(self):
         parser = argparse.ArgumentParser(
             prog='PROG',
             color=True,
-            description='Run [cmd]python -m myapp[/cmd] to start.',
+            description='Run `python -m myapp` to start.',
         )
 
         prog_extra = self.theme.prog_extra
@@ -7590,26 +7589,11 @@ def test_cmd_markup_in_description(self):
         self.assertIn(f'Run {prog_extra}python -m myapp{reset} to start.',
                       help_text)
 
-    def test_cmd_markup_multiline(self):
+    def test_backtick_markup_multiple(self):
         parser = argparse.ArgumentParser(
             prog='PROG',
             color=True,
-            formatter_class=argparse.RawDescriptionHelpFormatter,
-            epilog='Example:\n[cmd]python -m myapp \\\n  --verbose[/cmd]',
-        )
-
-        prog_extra = self.theme.prog_extra
-        reset = self.theme.reset
-
-        help_text = parser.format_help()
-        self.assertIn(f'{prog_extra}python -m myapp \\\n  --verbose{reset}',
-                      help_text)
-
-    def test_cmd_markup_multiple_tags(self):
-        parser = argparse.ArgumentParser(
-            prog='PROG',
-            color=True,
-            epilog='Try [cmd]app run[/cmd] or [cmd]app test[/cmd].',
+            epilog='Try `app run` or `app test`.',
         )
 
         prog_extra = self.theme.prog_extra
@@ -7619,46 +7603,23 @@ def test_cmd_markup_multiple_tags(self):
         self.assertIn(f'{prog_extra}app run{reset}', help_text)
         self.assertIn(f'{prog_extra}app test{reset}', help_text)
 
-    def test_cmd_markup_not_applied_when_color_disabled(self):
-        # When color is disabled, markup is not transformed (tags remain as-is)
+    def test_backtick_markup_not_applied_when_color_disabled(self):
+        # When color is disabled, backticks are preserved as-is
         parser = argparse.ArgumentParser(
             prog='PROG',
             color=False,
-            epilog='Example: [cmd]python -m myapp[/cmd]',
+            epilog='Example: `python -m myapp`',
         )
 
         help_text = parser.format_help()
-        self.assertIn('[cmd]python -m myapp[/cmd]', help_text)
+        self.assertIn('`python -m myapp`', help_text)
         self.assertNotIn('\x1b[', help_text)
 
-    def test_cmd_markup_unclosed_tag_unchanged(self):
-        parser = argparse.ArgumentParser(
-            prog='PROG',
-            color=True,
-            epilog='Example: [cmd]python -m myapp without closing tag',
-        )
-
-        help_text = parser.format_help()
-        self.assertIn('[cmd]', help_text)
-
-    def test_cmd_markup_empty_tag(self):
-        parser = argparse.ArgumentParser(
-            prog='PROG',
-            color=True,
-            epilog='Before [cmd][/cmd] after',
-        )
-
-        prog_extra = self.theme.prog_extra
-        reset = self.theme.reset
-
-        help_text = parser.format_help()
-        self.assertIn(f'Before {prog_extra}{reset} after', help_text)
-
-    def test_cmd_markup_with_format_string(self):
+    def test_backtick_markup_with_format_string(self):
         parser = argparse.ArgumentParser(
             prog='myapp',
             color=True,
-            epilog='Run [cmd]%(prog)s --help[/cmd] for more info.',
+            epilog='Run `%(prog)s --help` for more info.',
         )
 
         prog_extra = self.theme.prog_extra
@@ -7667,26 +7628,12 @@ def test_cmd_markup_with_format_string(self):
         help_text = parser.format_help()
         self.assertIn(f'{prog_extra}myapp --help{reset}', help_text)
 
-    def test_cmd_markup_case_sensitive(self):
-        parser = argparse.ArgumentParser(
-            prog='PROG',
-            color=True,
-            epilog='[CMD]uppercase[/CMD] vs [cmd]lowercase[/cmd]',
-        )
-
-        prog_extra = self.theme.prog_extra
-        reset = self.theme.reset
-
-        help_text = parser.format_help()
-        self.assertIn('[CMD]uppercase[/CMD]', help_text)
-        self.assertIn(f'{prog_extra}lowercase{reset}', help_text)
-
-    def test_cmd_markup_in_subparser(self):
+    def test_backtick_markup_in_subparser(self):
         parser = argparse.ArgumentParser(prog='PROG', color=True)
         subparsers = parser.add_subparsers()
         sub = subparsers.add_parser(
             'sub',
-            description='Run [cmd]PROG sub --foo[/cmd] to start.',
+            description='Run `PROG sub --foo` to start.',
         )
 
         prog_extra = self.theme.prog_extra
@@ -7695,11 +7642,11 @@ def test_cmd_markup_in_subparser(self):
         help_text = sub.format_help()
         self.assertIn(f'{prog_extra}PROG sub --foo{reset}', help_text)
 
-    def test_cmd_markup_special_regex_chars(self):
+    def test_backtick_markup_special_regex_chars(self):
         parser = argparse.ArgumentParser(
             prog='PROG',
             color=True,
-            epilog='[cmd]grep "foo.*bar" | sort[/cmd]',
+            epilog='`grep "foo.*bar" | sort`',
         )
 
         prog_extra = self.theme.prog_extra