Skip to content

curl: add table format for help opt#20895

Open
jhauga wants to merge 6 commits into
curl:masterfrom
jhauga:help-table
Open

curl: add table format for help opt#20895
jhauga wants to merge 6 commits into
curl:masterfrom
jhauga:help-table

Conversation

@jhauga
Copy link
Copy Markdown
Contributor

@jhauga jhauga commented Mar 11, 2026

Summary

This PR adds an argument to -h, --help that will use the help categories as qualifiers to table format the output.
Similar to PR 18151, but the formatted output is more of a table with bottom borders.

Since documentation seems to be a constant consideration for improvement, this PR addresses:

See curl 2025 survey[1]

Determining Format

Several articles on UX/UI conclude that using some separator for tables results in improved readability for data.
Although focused on browser tables, the same should apply as the task (reading data) is the same.

Articles Supporting Distinguishing Table Rows

Articles Supporting Minimal Borders

Output using PR

Below is what running curl --help table would output:

Usage: curl [options...] <url>

 -d, --data <data>              HTTP POST data
 --------------------------------------------------------------------------
 -f, --fail                     Fail fast with no output on HTTP errors
 --------------------------------------------------------------------------
 -I, --head                     Show document info only
 --------------------------------------------------------------------------
 -H, --header <header/@file>    Pass custom header(s) to server
 --------------------------------------------------------------------------
 -h, --help <subject>           Get help for commands
 --------------------------------------------------------------------------
 -o, --output <file>            Write to file instead of stdout
 --------------------------------------------------------------------------
 -O, --remote-name              Write output to file named as remote file
 --------------------------------------------------------------------------
 -i, --show-headers             Show response headers in output
 --------------------------------------------------------------------------
 -s, --silent                   Silent mode
 --------------------------------------------------------------------------
 -T, --upload-file <file>       Transfer local FILE to destination
 --------------------------------------------------------------------------
 -u, --user <user:password>     Server user and password
 --------------------------------------------------------------------------
 -A, --user-agent <name>        Send User-Agent <name> to server
 --------------------------------------------------------------------------
 -v, --verbose                  Make the operation more talkative
 --------------------------------------------------------------------------
 -V, --version                  Show version number and quit

@testclutch
Copy link
Copy Markdown

testclutch commented Mar 11, 2026

Analysis of PR #20895 at a4990aa5:

Test 1501 failed, which has NOT been flaky recently, so there could be a real issue in this PR. Note that this test has failed in 12 different CI jobs (the link just goes to one of them). Note that this CI job has had a number of other flaky tests recently (3, to be exact) so it may be that this failure is rather a systemic issue with this job and not with this specific PR.

Generated by Testclutch

@dfandrich
Copy link
Copy Markdown
Contributor

dfandrich commented Mar 11, 2026 via email

@jhauga
Copy link
Copy Markdown
Contributor Author

jhauga commented Mar 12, 2026 •
edited
Loading

Adding table row separators with a one-pixel line on screen is one thing, but I'm not sure halving the amount of information displayed in a console is a win. I can't think of another console program that adds a line of dashes between rows of text. Who do you expect the audience of this feature to be?

Really anyone. I found some studies and articles regarding styling tables for the browser. Like most niche research studies, researchgate.net used college students. I didn't find much on command-line doc research, but if reading is reading, then the same concept should apply. I don't know how helpful this would be for screen readers, but testing it myself; I found that row association mismatching was not an issue.

Articles Supporting Distinguishing Table Rows

Articles Supporting Minimal Borders

Edit

Fixed link in researchgate.net. The study mainly focused on shading rows vs columns, but the base of the main study was grounded on using a grid or having borders for the table.

@bagder
Copy link
Copy Markdown
Member

bagder commented Apr 30, 2026

I don't feel that anyone has particularly asked for this layout option, nor do I feel that it adds much in terms of usability. I would like to see more people voicing their support for this before considering a merge.

@bagder bagder added the needs-votes Pull-request in need of thumbs-ups to make progress label Apr 30, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

cmdline tool needs-votes Pull-request in need of thumbs-ups to make progress tests

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

4 participants

@jhauga @testclutch @dfandrich @bagder