New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Manpage never mentions you can specify flags before each URL #2515

Closed
salty-horse opened this Issue Apr 21, 2018 · 6 comments

Comments

Projects
None yet
2 participants
@salty-horse
Contributor

salty-horse commented Apr 21, 2018

The SYNOPSIS section in the manpage says:

curl [options] [URL...]

This is incorrect, as more options can be specified before each URL, and each set of options only applies to the URL after it (if I understand correctly. It's unclear).
You can also specify flags after the URL, as mentioned in the MANUAL section referenced below, which is odd and I don't think it's documented.

I'm not sure how to improve it without making it over-complicated. Maybe [[options] [URL ...]] ....
(man(7) uses a similar [[section] page[.section] ...] ...)

The manpage does say "curl will attempt to re-use connections for multiple file transfers", but doesn't explain how to go about it (e.g. with flags before each URL).

The file MANUAL contains the section "MULTIPLE TRANSFERS WITH A SINGLE COMMAND LINE". It's informative and should be copied to the manpage, after the section about re-using connections.

curl/libcurl version

7.55.1

@bagder

This comment has been minimized.

Member

bagder commented Apr 22, 2018

Maybe [options / URLs] ?

The manpage does say "curl will attempt to re-use connections for multiple file transfers", but doesn't explain how to go about it (e.g. with flags before each URL).

curl's ability to re-use connections is totally unrelated to how you put the arguments on the command line... It will always attempt to re-use connections no matter that.

@salty-horse

This comment has been minimized.

Contributor

salty-horse commented Apr 22, 2018

curl's ability to re-use connections is totally unrelated to how you put the arguments on the command line... It will always attempt to re-use connections no matter that.

The quoted paragraph clued me to the fact that I can probably use curl to download several files in sequence from the same server. My next question was how to specify a new filename for each URL, and I had to search the web for an example, as the manpage wasn't helpful.

@bagder

This comment has been minimized.

Member

bagder commented Apr 22, 2018

It is clearly spelled out in the -o, --output section though. If you have a suggetion on how to improve this, please offer your take!

@salty-horse

This comment has been minimized.

Contributor

salty-horse commented Apr 22, 2018

Hm, I missed that. That answers many of my questions. I still think it's not the right place to discover the "download multiple files at once" feature.

My suggestion is to copy the "Multiple transfers" section from the manual to the manpage.

I'm fine with [options / URLs]. Note that it's a style that's not mention in man man and I don't think I've ever encountered it before.

bagder added a commit that referenced this issue Apr 23, 2018

@bagder

This comment has been minimized.

Member

bagder commented Apr 23, 2018

I don't want the man page to turn into the tutorial though, the size of the man page is already daunting. I'm proposing #2517 as a minimal change to state that options and URLs can be mixed on the command line.

@salty-horse

This comment has been minimized.

Contributor

salty-horse commented Apr 23, 2018

👍

@bagder bagder closed this in a39593d Apr 23, 2018

@lock lock bot locked as resolved and limited conversation to collaborators Jul 22, 2018

Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.