[
https://issues.apache.org/jira/browse/HTTPCLIENT-1201?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13287940#comment-13287940
]
Oleg Kalnichevski commented on HTTPCLIENT-1201:
-----------------------------------------------
@Eric
This is a classic case of 'damned if you do, damned if you don't'. In the
HttpClient 3.x days it was fashionable to rubbish it for not being flexible
enough. Now when HttpClient 4.x can do so much more people complain about it
being too complex. Same goes for documentation. HttpClient 3.x did not have a
comprehensive tutorial, just a bunch of short, unrelated documents and was
often criticized for that. People will always find something to bitch about.
Especially if their problems turn out to be of their own making. Thanks for the
words of encouragement, anyway.
@Miles
If you want this whole story to end with some practical outcome, start
producing patches. Otherwise, your big, bold statements are meaningless and
useless.
(1) HttpClient tutorials can be found here
https://svn.apache.org/repos/asf/httpcomponents/httpclient/trunk/src/docbkx/
You can build HTML or PDF documents out of XML sources by running
mvn docbkx:generate-pdf
mvn docbkx:generate-html
(2) HttpClient web site sources can be found here
https://svn.apache.org/repos/asf/httpcomponents/httpclient/trunk/src/site/
You can change site navigation by modifying
https://svn.apache.org/repos/asf/httpcomponents/httpclient/trunk/src/site/site.xml
You can add new pages or modify existing ones by changing these documents
https://svn.apache.org/repos/asf/httpcomponents/httpclient/trunk/src/site/apt/
You can re-generate the site locally and check out how it looks by running
mvn site
(3) HttpClient API closely follows the language of the HTTP specification and
terminology used by the spec. There is no such thing HTTP parameters in the
HTTP spec. There are different types of content entities including content
bodies produced by HTML forms that are frequently interpreted by server side
scripts or APIs (such as Servlet API) as 'parameters'. If you find working with
entities too difficult you are welcome to use the fluent facade API included
with HttpClient 4.2.
http://hc.apache.org/httpcomponents-client-ga/tutorial/html/fluent.html
Alternatively, feel free to contribute a Builder class for common HTTP requests
with a better, more intuitive API. That would in fact be a very welcome
contribution to the project.
And if you are not willing to put your money where your mouth is, better say
nothing at all.
Oleg
> provide basic documentation in an obvious place
> -----------------------------------------------
>
> Key: HTTPCLIENT-1201
> URL: https://issues.apache.org/jira/browse/HTTPCLIENT-1201
> Project: HttpComponents HttpClient
> Issue Type: Improvement
> Components: Documentation
> Affects Versions: 4.2 Final
> Reporter: miles zarathustra
>
> The only documentation obviously linked from the main HttpClient page is the
> "tutorial." This "tutorial" talks about a lot of esoteric arcane junk I
> don't care about, but gives no clue on how to send parameters via a basic
> post. For that, I have to go here:
> http://wiki.apache.org/HttpComponents/QuickStart
> It's very difficult to find, and it's a lot easier to google examples that
> don't work. I wound up trying 4 different purported solutions before I found
> this one that works. If you look around the web you'll notice that people
> generally find the httpclient documentation frustrating. I have colleagues
> who argue that it would be easier to just write the post logic from scratch
> than figure out how the silly apache stuff works, and it's difficult for me
> to contradict them.
> It would be SO easy to improve the situation by making links to already
> available examples of the basic operations in an obvious place.
> The FAQ that explains some things about WHY the posts work in the totally
> non-intuitive way that they do would be nice also.
> Thanks.
--
This message is automatically generated by JIRA.
If you think it was sent incorrectly, please contact your JIRA administrators:
https://issues.apache.org/jira/secure/ContactAdministrators!default.jspa
For more information on JIRA, see: http://www.atlassian.com/software/jira
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
