Manpages' synopses are confusing
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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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