Document CONNECT use-case with parse_authority about url

[alandefreitas]

We already have an example like that in https://develop.url.cpp.al/url/parsing/authority.html#url.parsing.authority.authority_view

[vinniefalco]

Nice! Since this is the use-case that 99% of people will need, I think we should reflect that in the section heading so they can find it in the table of contents.

[alandefreitas]

We did have something like that, where authority_view had its own section. I merged the sections in some previous PR to make the TOC look a little better:

(the overview could still improve though)

Maybe we have a different idea for that, but isolating authority view in the TOC looked quite ugly:

This previous layout also made the relationship between authority and authority_view more complex to explain, less natural to the reader, and I'm not sure it's so helpful, since authority is already visible and it's the natural place to look for that kind of use case. But I don't know, maybe there's a better way I haven't considered yet.

[vinniefalco]

isolating authority view in the TOC looked quite ugly:

Yes that image of the ToC looks bad. It repeats the word Authority. How about the heading "HTTP CONNECT" since that's usually what it is used with?

[alandefreitas]

To be honest, the repeated word is something we can improve but not something I mind that much because this is likely to happen in this kind of document anyway.

What I don't like is

• visually the snaggle-tooth as an exception for something that is really just a use case among many, and
• how it conceptually affects the section hierarchy, because "authority view" is not even the last subsection of this section and this becomes a mess: the "Authority" section would include text that should come before and after the "Authority view"

But we can do anything. Just say the word.

[vinniefalco]

"Documentation can always be improved."

Get the information into the docs, and we can worry how to make it pretty later.

[alandefreitas]

Get the information into the docs, and we can worry how to make it pretty later.

The information is in the docs already. We are just discussing the presentation now.

"Documentation can always be improved."

At this point, we're not discussing an improvement. I think we're discussing whether this would make it worse.

[vinniefalco]

What I mean is we can live with it the way it is now...and worry about making it better later.

[alandefreitas]

I support that :)