Updated build instructions; updated web site; added quick start page

git-svn-id: https://svn.apache.org/repos/asf/httpcomponents/httpclient/trunk@792647 13f79535-47bb-0310-9956-ffa450edef68

BUILDING.txt

@@ -25,7 +25,44 @@ mvn package
 
 The resultant packages can be found in the target folders of their respective modules
 
-module-client/target/httpclient-<VERSION>.jar
+httpclient/target/httpclient-<VERSION>.jar
-module-httpmime/target/httpmime-<VERSION>.jar
+httpmime/target/httpmime-<VERSION>.jar
+httpclient-osgi/target/org.apache.httpcomponents.httpclient_<VERSION>.jar
 
 where <VERSION> is the release version
+
+(4) Building documentation 
+
+Execute the following command in order to generate javadoc:
+
+mvn javadoc:javadoc
+
+Execute the following command in order to generate the tutorial in html and pdf formats
+
+mvn docbkx:generate-pdf docbkx:generate-html
+
+(5) Building distribution assemblies 
+
+Execute the following command in order to build the distribution assemblies
+
+mvn package assembly:assembly
+
+(6) Fix EOL in source files
+
+Fix the archive files so the source files have the correct EOL settings:
+
+mvn antrun:run
+
+(7) Building project web site 
+
+Execute the following command in order to generate the project web site:
+
+mvn site -Dclover.license=<path>/clover.license
+
+where <path> is a full path to Clover license file
+
+ASF committers can obtain a copy of Clover license donated to the ASF from the SVN repository
+at the following location:
+
+https://svn.apache.org/repos/private/committers/donated-licenses/clover
+

src/site/apt/index.apt

@@ -49,6 +49,12 @@ HttpClient Overview
     service clients, or systems that leverage or extend the HTTP protocol for distributed 
     communication.
 
+Documentation
+
+    * HttpClient Tutorial ( {{{tutorial/html}HTML}} / {{{tutorial/pdf/httpclient-tutorial.pdf}PDF}} )
+    
+    * Some examples of HttpClient in action can be found {{{examples.html}here}}
+    
 Features
 
     * Standards based, pure Java, implementation of HTTP versions 1.0 and 1.1
@@ -91,25 +97,6 @@ Features
 
     * Source code is freely available under the Apache License.
 
-Modules
-
-    HttpClient currently is a single module that comprises code for 
-    authentication, cookies, connection management, and the client itself.
-    It may be changed to a more modular structure in the future.
-
-* HttpClient module
-
-    The {{{httpclient/index.html}HttpClient}} module is a full-featured, standards compliant HTTP 
-    client built on top of {{{/httpcomponents-core/index.html}HttpCore}}. HttpClient requires 
-    a Java 5.0 compatible runtime.
-
-* HttpMime module
-
-    The {{{httpmime/index.html}HttpMime}} module extends 
-    {{{http://james.apache.org/mime4j/index.html}mime4j}} library with some HTTP specific
-    functionality and integrates it with the HttpComponents framework. HttpMime requires 
-    a Java 5.0 compatible runtime and HttpClient module with its dependencies.
-
 Standards Compliance
 
     HttpClient strives to conform to the following specifications endorsed by the Internet 
@@ -125,8 +112,3 @@ Standards Compliance
     * {{{http://www.ietf.org/rfc/rfc2109.txt}RFC 2109}} HTTP State Management Mechanism (Cookies)
     
     * {{{http://www.ietf.org/rfc/rfc2965.txt}RFC 2965}} HTTP State Management Mechanism (Cookies v2)
-    
-
-Examples
-
-    Some examples of HttpClient components in action can be found {{{examples.html}here}}.

src/site/apt/quickstart.apt

@@ -0,0 +1,61 @@
+~~ ====================================================================
+~~ Licensed to the Apache Software Foundation (ASF) under one
+~~ or more contributor license agreements.  See the NOTICE file
+~~ distributed with this work for additional information
+~~ regarding copyright ownership.  The ASF licenses this file
+~~ to you under the Apache License, Version 2.0 (the
+~~ "License"); you may not use this file except in compliance
+~~ with the License.  You may obtain a copy of the License at
+~~ 
+~~   http://www.apache.org/licenses/LICENSE-2.0
+~~ 
+~~ Unless required by applicable law or agreed to in writing,
+~~ software distributed under the License is distributed on an
+~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+~~ KIND, either express or implied.  See the License for the
+~~ specific language governing permissions and limitations
+~~ under the License.
+~~ ====================================================================
+~~ 
+~~ This software consists of voluntary contributions made by many
+~~ individuals on behalf of the Apache Software Foundation.  For more
+~~ information on the Apache Software Foundation, please see
+~~ <http://www.apache.org/>.
+
+    ----------
+    HttpClient Quick Start
+    ----------
+    ----------
+    ----------
+
+HttpClient Quick Start
+
+    [[1]] Download 'Binary with dependencies' package of the latest official release from 
+    the {{{http://hc.apache.org/downloads.cgi} project download page}}. 
+  
+    There should be 6 jars in total (components marked with (*) are optional if MIME multipart 
+    support is not required)
+  
+    * commons-logging-<x.x.x>.jar
+  
+    * commons-codec-<x.x.x>.jar
+  
+    * httpcore-<x.x.x>.jar
+  
+    * httpclient-<x.x.x>.jar
+  
+    * apache-mime4j-<x.x.x>.jar (*)
+  
+    * httpmime-<x.x.x>.jar (*)
+    
+    []
+    
+    [[2]] Take a look at the HttpClient tutorial shipped with the release package or avaialble
+    {{{tutorial/html/}online}} to learn HttpClient API.
+    
+    [[3]] Another good way of getting started with HttpClient is by seeing it in action. Take 
+    a look at the samples shipped with the release package or available {{{examples.html}online}}.
+    
+    [[4]] Please note that HttpClient is not a browser. Importantly it lacks UI, cache, HTML 
+    renderer and a JavaScript engine. To learn more about the scope of HttpClient please refer to 
+    {{{primer.html}HttpClient Primer}}

src/site/site.xml

@@ -49,9 +49,11 @@
     <menu name="HttpClient Overview">
       <item name="Description" href="index.html"/>
       <item name="Download" href="download.html"/>
-      <item name="Examples" href="examples.html"/>
+      <item name="Quick Start" href="quickstart.html"/>
     </menu>
     <menu name="Documentation">
+      <item name="Tutorial" href="tutorial/html/"/>
+      <item name="Examples" href="examples.html"/>
       <item name="Client HTTP Programming Primer" href="primer.html"/>
       <item name="NTLM support" href="ntlm.html"/>
       <item name="Logging" href="logging.html"/>