Audit backtick usage in command help output

The Problem with Backticks

Original Issue: Missing backticks in milestone edit and delete command documentation (e.g., OWNER/REPO and GROUP/NAMESPACE/REPO placeholders).

Root Cause Discovered: The CLI documentation is auto-generated from Go source files using the pflag library, which interprets backticks in a specific way that creates complications:

1. Flag Type Display: When backticks are used in flag descriptions (e.g., `OWNER/REPO`), pflag removes the placeholder from the flag type display and shows "string" instead
2. Documentation Inconsistency: This creates a disconnect where users see "OWNER/REPO" in the description text but lose it from the flag type indicator
3. Markdown Rendering: The backticks are intended for inline code formatting in markdown docs, but they conflict with how pflag processes flag descriptions

Current State in Codebase/Docs

Inconsistent Usage: The codebase currently has mixed usage of backticks across different commands, with no consistent pattern for placeholder formatting.

Auto-Generation Constraint: Documentation files in docs/source/ are generated via make gen-docs from Go source files, so manual edits to markdown files don't persist.

Example from MR: The -R, --repo flag description shows this issue:

• With backticks: Flag type shows as "string" (loses placeholder context)
• Without backticks: Flag type shows as "OWNER/REPO" (provides helpful context)

Potential Solutions to Explore

1. Angle Bracket Convention (Implemented in !2583 (closed))

• Use <OWNER/REPO> and <GROUP/NAMESPACE/REPO> instead of backticks
• Follows GitLab documentation style guide for placeholder text
• Avoids pflag parsing issues
• Maintains clear placeholder formatting in both CLI and docs

2. Pre-processing in Docs Generation

• Modify the make gen-docs command to transform backticks appropriately for markdown output
• Would allow backticks in Go source while generating proper markdown
• Requires investigation into the docs generation tooling

3. Custom pflag Handling

• Investigate if pflag behavior can be customized or if there's a way to escape backticks
• May require upstream changes to pflag library
• Could be complex and not maintainable

4. Comprehensive Audit

• Audit all usage of backticks across the entire codebase
• Establish consistent guidelines for placeholder formatting
• Document the chosen approach for future contributors

Recommendation

The MR was closed with the decision to repurpose this issue for a broader examination of backticks usage. The angle bracket approach (<placeholder>) appears to be the most pragmatic solution that:

• Aligns with GitLab's documentation standards
• Avoids technical complications with pflag
• Provides clear, consistent placeholder formatting
• Works well in both CLI help output and generated documentation

However, this requires a comprehensive audit and consistent application across the entire codebase rather than piecemeal fixes.