On Sat, 12 Nov 2016, Ray Satiro via curl-users wrote:

> Could you keep an html manpage around as a generated single-flow page for
> the web as well, even if you are adding a default web manpage with links
> based on the abbreviated --help? I prefer the big html page for the curl
> tool, I just / and what I'm looking for. Also I've given out a bunch of help
> links like manpage.html#--option when people ask about things, so if the
> default manpage.html will be one with links to individual options can you
> please add <a name="--option".

Yeah, we have a lot of links spread out over the world in use already that go
to the achors the existing html man page has, and one huge web page also makes
it easier to search within to some extent so yes I do see the value on this
version.

> I wonder how much more documentation each of those options needs though? I
> think the important part is what they do and that is already documented. Too
> much documentation not necessarily a good thing if it makes the usage harder
> to understand or learn.

Agreed. And it will of course vary. I think this overhaul will provide a lot
of other useful outcomes. Just adding more words is not a goal in itself. We
will for example get the right sort order easier (whichever order we actually
think is right). We will get the output more unified. We can generate lists
with "options for a specific" protocol. Getting all command line options with
meta-data in a way with more formal descriptions I think will bring even more
good stuff as we proceed.

For longer explanations and more tutorial-like descriptions, we should rather
defer to sections in the "Everything curl" book instead which is really the
long form documentation.

(The --next description at
https://ec.haxx.se/cmdline-urls.html#separate-options-per-url should probably
be expanded.)

> The global/local name I wonder if to start calling options local or global
> will be confusing to the user. My opinion is we could just document in
> --next what --next does not reset. "--next does not reset the following
> options: --verbose, --fail-early, etc ". If it were continued to --verbose
> to say "--verbose is not reset by --next" or is global isn't that confusing
> for anyone who's never used --next and requires more learning.

Agreed!

-- 
  / daniel.haxx.se
-------------------------------------------------------------------
List admin: https://cool.haxx.se/list/listinfo/curl-users
FAQ:        https://curl.haxx.se/docs/faq.html
Etiquette:  https://curl.haxx.se/mail/etiquette.html