Skip to content

docs(man): preserve markdown list/code block structure in DESCRIPTION#13391

Open
Cris682 wants to merge 1 commit into
cli:trunkfrom
Cris682:fix-13343-manpage-formatting
Open

docs(man): preserve markdown list/code block structure in DESCRIPTION#13391
Cris682 wants to merge 1 commit into
cli:trunkfrom
Cris682:fix-13343-manpage-formatting

Conversation

@Cris682
Copy link
Copy Markdown

@Cris682 Cris682 commented May 10, 2026

Commit Title

docs(man): preserve markdown block formatting in DESCRIPTION sections

Commit Message

The manpage generator now normalizes command Long descriptions before passing them to md2man.

This fixes formatting issues where markdown blocks in DESCRIPTION were flattened into hard-to-read paragraphs, especially:

  • unordered/ordered lists
  • fenced code blocks
  • indented code blocks

What changed

  • Added normalizeMarkdownForMan() in internal/docs/man.go
  • Inserted normalization in man preamble rendering:
    • normalizeMarkdownForMan(cmd.Long) instead of raw cmd.Long
  • Added helper logic to detect markdown block starts and insert missing block separators safely, including fenced-code awareness

Tests

  • Added TestNormalizeMarkdownForManAddsMissingBlockSeparators
  • Added TestRenderManFormatsDescriptionLists
  • Verified with:
    • go test ./internal/docs/...
    • go test ./cmd/gen-docs/...

Scope

  • Minimal, targeted change
  • Files touched:
    • internal/docs/man.go
    • internal/docs/man_test.go

Issue

Fixes #13343

@Cris682 Cris682 requested a review from a team as a code owner May 10, 2026 08:34
@Cris682 Cris682 requested review from babakks and Copilot May 10, 2026 08:34
@github-actions github-actions Bot added external pull request originating outside of the CLI core team needs-triage needs to be reviewed unmet-requirements and removed needs-triage needs to be reviewed labels May 10, 2026
@github-actions
Copy link
Copy Markdown

github-actions Bot commented May 10, 2026

Thanks for your pull request! Unfortunately, it doesn't meet the requirements for review:

  • None of the referenced issues have the help wanted label

Please update your PR to address the above. This PR will be automatically closed in 4 days if these requirements are not met.

Full contribution requirements
  1. Include a detailed description of what this PR does
  2. Link to an issue with the help wanted label (use Fixes #123 or Closes #123)

Copilot AI reviewed May 10, 2026
View reviewed changes
Copy link
Copy Markdown
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This pull request updates the manpage generator to preserve Markdown block structure in DESCRIPTION sections by normalizing cmd.Long before converting it with md2man, preventing lists and code blocks from being flattened into paragraphs.

Changes:

  • Added normalizeMarkdownForMan() and supporting helpers to insert missing blank lines before Markdown block starts (lists, fenced code blocks, indented code blocks), while avoiding changes inside fenced code blocks.
  • Applied this normalization when writing the # DESCRIPTION content in internal/docs/man.go.
  • Added unit tests covering normalization behavior and an integration-style assertion that rendered man output contains bullet list formatting.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.

File Description
internal/docs/man.go Normalizes cmd.Long Markdown to preserve block formatting in manpage DESCRIPTION rendering.
internal/docs/man_test.go Adds tests for Markdown normalization and verifies bullet lists render as list items in man output.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

@Cris682
Copy link
Copy Markdown
Author

Cris682 commented May 10, 2026

Thanks for the automated checks and review.

This PR fixes #13343 (manpage DESCRIPTION formatting for markdown lists/code blocks) with a minimal, targeted change in:

  • internal/docs/man.go
  • internal/docs/man_test.go

I understand the external contribution policy requires linking an issue with the help wanted label.
Since #13343 currently does not have that label, could a maintainer please advise whether:

  1. this PR can be reviewed as an exception, or
  2. Manpage generation doesn't format lists, code samples #13343 can be marked help wanted if external contribution is welcome.

Happy to adjust/close/reopen based on maintainer guidance. Thanks!

Nevo24 pushed a commit to Nevo24/leap that referenced this pull request May 10, 2026
fix(monitor): GitHub PR-tracking parity with GitLab
d548830 
Audit-driven fixes to the GitHub provider. GitLab path is byte-identical
— pinned by 5 regression-guard tests covering anchor format, leap-message
notation, env-var placeholder, and abstract-method signatures.

Read-path fixes:
- Anchor format: deep-links use #discussion_r<id> for review comments and
  #issuecomment-<id> for conversation comments (was unconditionally
  #note_<id>, the GitLab format, so on GitHub the page loaded but never
  scrolled to the comment).
- Fork PR tracking: PR-pinned rows store pr_iid; providers fetch by IID
  to bypass the head filter (which excludes fork PRs by design on
  GitHub). Auto-tracked rows still use the head filter — no perf
  regression for branches without a PR.
- branch_deleted check queries pr.head.repo (the fork) instead of the
  base repo, so fork PRs aren't falsely flagged as deleted.
- PR conversation tab: pr.get_issue_comments() now feeds unresponded
  count, /leap detection, and "Send comments to session". A
  discriminated discussion_id ('r:<id>' / 'i:<id>') routes acks to the
  right API endpoint.
- Resolved review threads filtered via GraphQL (REST v3 doesn't expose
  isResolved). Paginates up to 300 threads.
- Emoji reactions on the last other-party comment count as ack — parity
  with GitLab's award_emoji semantics.
- Notification URL handles /commits/ → /commit/, falls back to repo URL
  for unknown subject types (releases, workflow runs, …).
- format_leap_message uses '#N' for GitHub PRs, keeps '!N' for GitLab.

UX/setup-dialog fixes:
- Per-provider env-var placeholder (was hardcoded GITLAB_TOKEN; GitHub
  dialog now correctly says GITHUB_TOKEN).
- Explicit api.github.com / github.com URLs no longer auto-check
  "Self-hosted" on next dialog open.
- /meta server check accepts 401/403 as proof-of-GitHub so bad-token
  errors aren't masked as "not GitHub".
- Token scope check accepts public_repo as valid alongside repo.
- UserNotification.author='' explicitly (was None — GitHub
  notifications API doesn't expose actor without an extra fetch we
  don't pay for).

Tests: 41 new unit tests (36 GitHub-focused + 5 GitLab regression
guards) covering pure-logic surface end-to-end. Live read-only sanity
run against cli/cli/pull/13391 (a fork PR with an unresponded
issue-tab comment) exercised every read path on real data.
@samo-agent samo-agent mentioned this pull request May 11, 2026
Open
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

Copilot code review Copilot Copilot left review comments

@babakks babakks Awaiting requested review from babakks babakks is a code owner automatically assigned from cli/code-reviewers

At least 1 approving review is required to merge this pull request.

Assignees

No one assigned

Labels

external pull request originating outside of the CLI core team unmet-requirements

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Manpage generation doesn't format lists, code samples

2 participants

@Cris682