uutils / uutils/coreutils

Manpages' synopses are confusing

Open
#14,086 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Rust
Stars
24.1k
Forks
2k
Avg merge
1d 5h
Merged PRs (30d)
365

Description

Hello,
First and foremost thank you for your work.

Using Ubuntu latest LTS and uutils 0.10.0, the Synopsis section of the manpages have been altered in a fashion where it is impossible to understand the basic way to invoke a command with resorting to tldr examples.
For example, seq shows the following:

$ man seq
SYNOPSIS
       seq [-s|--separator] [-t|--terminator] [-w|--equal-width] [-f|--format] [-h|--help] [-V|--version] [numbers]

and nowhere is it described what [numbers] consist of. There's no way to know how to properly invoke the command.

The old version used to show the different way of invoking:

SYNOPSIS
       seq [OPTION]... LAST
       seq [OPTION]... FIRST LAST
       seq [OPTION]... FIRST INCREMENT LAST

Same thing for install and many other commands which have various ways of being invoked.
If I may remark: most commands have several lines of options when listed inline, and listing them in the synopsis seem particularly suboptimal when it deters basic understanding of the command.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by locating how the Rust project generates the manpage synopsis for commands such as seq and install. Compare the current synopsis with the older multi-form examples, then identify how similar commands represent multiple invocation forms. Done means the manpages explain each supported invocation clearly, including what seq’s numeric arguments mean.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
cli, documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
65/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.