Fix manpage command synopsis by jhrcek · Pull Request #2113 · htop-dev/htop

jhrcek · 2026-09-19T12:25:05Z

Fix for #2112 + all the other issues found in manpage command synopsis.

The synopsis listed a lowercase '-v' option that has never existed; version info is printed by '-V'. It also omitted '-n', '-U' and '-M', which are all accepted and already documented further down in the page. The option letters now match the getopt string in CommandLine.c.

For pcp-htop, '--host' is a long-only option (its val is PLATFORM_LONGOPT_HOST, not a character), so the advertised '-h host' short form does not work -- '-h' prints the help screen. Its argument is a HOSTSPEC, as the --help output states.

coderabbitai · 2026-09-19T12:26:20Z

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

@coderabbitai resume to resume automatic reviews.
@coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

▶️ Resume reviews
🔍 Trigger review

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: ASSERTIVE

Plan: Advanced

Run ID: e8abf3f9-9676-4708-9d63-9a9888518c66

📥 Commits

Reviewing files that changed from the base of the PR and between 6d73136 and 92ae42a.

📒 Files selected for processing (1)

htop.1.in

Included review availability: Your plan provides up to 8 included reviews per hour; 6 remain after this review.

📝 Walkthrough

Walkthrough

The SYNOPSIS section now lists the updated option sets for htop and pcp-htop. The pcp-htop host argument is shown as HOSTSPEC.

Suggested reviewers: fasterit

Priority: ⬇️ Low

Change: Other

Merge Risk: ⚪ Minimal · up to 92ae4

This documentation-only update clarifies htop and pcp-htop command-line forms and aligns HOSTSPEC and timezone options with supported behavior; no merge-blocking risk remains.

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Synopsis lines align
Options march in order
HOSTSPEC takes its place
Manuals speak clearly
A small patch, complete}

_{Comment @coderabbitai help to get the list of available commands.}

coderabbitai

Actionable comments posted: 1

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: ASSERTIVE

Plan: Advanced

Run ID: ac0d8c47-0314-47b0-a467-876881f42939

📥 Commits

Reviewing files that changed from the base of the PR and between 23f8ad0 and a0fdc7b.

📒 Files selected for processing (1)

htop.1.in

Included review availability: Your plan provides up to 8 included reviews per hour; 7 remain after this review.

jhrcek · 2026-09-20T06:58:36Z

Optimistically pushing more ambitious update of the manpage, but feel free to be more specific about which of these changes you like and I can reduce the scope of changes.

For ease of review I'm adding a diff of the rendered manpage between what would be rendered from master vs from this PR:

```diff
--- main
+++ PR
@@ -4,8 +4,8 @@
        htop, pcp-htop - interactive process viewer
 
 SYNOPSIS
-       htop [-dCFhpustvH]
-       pcp-htop [-dCFhpustvH] [--host/-h host]
+       htop [-CdFHhMnpstUuV]
+       pcp-htop [-CdFHhMnpstUuV] [--host=HOSTSPEC] [--hostzone|--timezone=TZ]
 
 DESCRIPTION
        htop is a cross-platform ncurses-based process viewer.
@@ -50,11 +50,11 @@
        -h --help
               Display a help message and exit
 
-       -p --pid=PID,PID...
+       -p --pid=PID[,PID...]
               Show only the given PIDs
 
-       -s --sort-key COLUMN
-              Sort by this column (use --sort-key  help  for  a  column  list).
+       -s --sort-key=COLUMN
+              Sort by this column (use  --sort-key=help  for  a  column  list).
               This  will  force  a  list view unless you specify -t at the same
               time.  Sorting in tree mode applies to  the  direct  children  of
               each process.
@@ -71,7 +71,7 @@
        --no-meters
               Hide graph meters
 
-        --keep-visible[=N]
+       --keep-visible[=N]
               Keep  the  first N columns visible when scrolling sideways in the
               process list.  The argument is optional; if omitted, N  is  taken
               to be 1, and 0 disables the feature (the default). If N is larger
@@ -94,8 +94,10 @@
               to move the whole tree down, creating empty space above the  root
               when necessary.
 
-       -H --highlight-changes=DELAY
-              Highlight new and old processes
+       -H --highlight-changes[=DELAY]
+              Highlight  new and old processes.  If DELAY is omitted, the high‐
+              light time configured in the setup screen is used (5  seconds  by
+              default).
 
        --drop-capabilities[=off|basic|strict]
               Linux  only;  this  option needs to have been enabled at compile-
@@ -105,6 +107,22 @@
               accounting information will not work due  to  fewer  capabilities
               being held.
 
+       --host=HOSTSPEC
+              pcp-htop only.
+              Read  metrics  from  the PMCD daemon on HOSTSPEC rather than from
+              the local host; see PCPIntro(1) for the HOSTSPEC syntax.
+
+       --hostzone
+              pcp-htop only.
+              Set the reporting timezone to the local timezone of the host sup‐
+              plying the metrics, rather than that of the local host.  Mutually
+              exclusive with --timezone.
+
+       --timezone=TZ
+              pcp-htop only.
+              Set the reporting timezone to TZ, using the syntax of the TZ  en‐
+              vironment variable.  Mutually exclusive with --hostzone.
+
 INTERACTIVE COMMANDS
        The following commands are supported while in htop:

BenBE · 2026-09-20T08:32:31Z

I think except for the first hunk in your diff above, the changes are mostly for consistency or completeness. Hunk 1 is still discussed in the team, but there's a slight tendency against it (not final yet though). Updating the set of short options in the usage section is agreed upon though; mostly a matter of whether to use the long version though or not.

fasterit · 2026-09-21T12:21:17Z

I think the short options synopsis is better. Less noise to scroll by.

fasterit · 2026-09-21T12:27:35Z

Would also be nice to remove AI overshoots like "The value must be attached with an equals sign."
You also don't state how to press = on all local keyboard variants.

jhrcek · 2026-09-22T05:48:32Z

Ok, removed the AI overshoots and made the synopsis only list the short options only (except for the 3 extra options of pcp-htop, for which @BenBE asked to be included in the synopsis and which don't have short variants). Also updated the manpage diff above to reflect the changes.

BenBE

LGTM. Please fixup the commits into one (or at most two) commits; grouped by the kind of changes (synopsis update/content vs. style/consistency). Everything in one commit is fine too.

Add COMMAND-LINE OPTIONS entries for --host, --hostzone and --timezone, which pcp-htop accepts but the page never documented; they appeared only in --help output. Correct notation against the parser: -H takes an optional argument, --pid repeats are optional, --sort-key uses '='. Terminate four unterminated \fB escapes, drop a stray leading space before --keep-visible, and remove a no-op .br before a .SH. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

The synopsis listed a lowercase '-v' option that has never existed; version info is printed by '-V'. It also omitted '-n', '-U' and '-M', which are all accepted and already documented further down in the page. The option letters now match the getopt string in CommandLine.c. For pcp-htop, '--host' is a long-only option (its val is PLATFORM_LONGOPT_HOST, not a character), so the advertised '-h host' short form does not work; '-h' prints the help screen. Its argument is a HOSTSPEC, as the --help output states. Also list the other two PCP-only options, --hostzone and --timezone, which are mutually exclusive. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

jhrcek · 2026-09-22T07:22:58Z

Sure, I split it into 2 commits.

fasterit · 2026-09-22T08:08:42Z

Thank you!

BenBE added this to the 3.6.0 milestone Sep 19, 2026

BenBE added the documentation 📖 Improvements or additions to documentation label Sep 19, 2026

BenBE linked an issue Sep 19, 2026 that may be closed by this pull request

man page: htop synopsis mentions -v option that doesn't exist #2112

Closed

BenBE reviewed Sep 19, 2026

View reviewed changes

Comment thread htop.1.in Outdated

coderabbitai Bot reviewed Sep 20, 2026

View reviewed changes

Comment thread htop.1.in Outdated

jhrcek requested a review from BenBE September 20, 2026 07:08

BenBE approved these changes Sep 22, 2026

View reviewed changes

jhrcek and others added 2 commits September 22, 2026 08:12

jhrcek force-pushed the jhrcek/manpage branch from 92ae42a to 2bc145d Compare September 22, 2026 06:13

fasterit merged commit 1daf6d9 into htop-dev:main Sep 22, 2026
1 check passed

Navigation Menu

Repository navigation

Fix manpage command synopsis - #2113

Fix manpage command synopsis#2113
fasterit merged 2 commits into
htop-dev:mainfrom
jhrcek:jhrcek/manpage

jhrcek commented Sep 19, 2026 •

edited

Loading

Uh oh!

coderabbitai Bot commented Sep 19, 2026 •

edited

Loading

Reviews paused

Walkthrough

Uh oh!

Uh oh!

coderabbitai Bot left a comment

Uh oh!

Uh oh!

jhrcek commented Sep 20, 2026 •

edited

Loading

Uh oh!

BenBE commented Sep 20, 2026

Uh oh!

fasterit commented Sep 21, 2026

Uh oh!

fasterit commented Sep 21, 2026

Uh oh!

jhrcek commented Sep 22, 2026

Uh oh!

BenBE left a comment •

edited

Loading

Uh oh!

jhrcek commented Sep 22, 2026

Uh oh!

Uh oh!

fasterit commented Sep 22, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

jhrcek commented Sep 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

coderabbitai Bot commented Sep 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Reviews paused

Walkthrough

Uh oh!

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

jhrcek commented Sep 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

BenBE commented Sep 20, 2026

Uh oh!

fasterit commented Sep 21, 2026

Uh oh!

fasterit commented Sep 21, 2026

Uh oh!

jhrcek commented Sep 22, 2026

Uh oh!

BenBE left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jhrcek commented Sep 22, 2026

Uh oh!

Uh oh!

fasterit commented Sep 22, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

jhrcek commented Sep 19, 2026 •

edited

Loading

coderabbitai Bot commented Sep 19, 2026 •

edited

Loading

jhrcek commented Sep 20, 2026 •

edited

Loading

BenBE left a comment •

edited

Loading