Change README to use AsciiDoc

README.asciidoc

@@ -0,0 +1,369 @@
+Neko: The Clojure/Android Toolkit
+=================================
+Daniel Solano_Gómez
+
+Neko is a toolkit designed to make Android development using Clojure easier and
+more fun.  It accomplishes this by making adding Clojure support to your
+Android project easy and providing functional wrappers and alternatives to
+Android’s Java API.
+
+Features
+--------
+
+WARNING: Note that the libraries are under heavy development.  APIs are subject
+to change.  In particular, `neko.threading` will be changed.
+
+The toolkit comes as two components:
+
+. Simplified build support for Clojure using Android’s Ant-based build system,
+  and
+
+. The following Clojure libraries:
+
+  * `neko.compilation` helps set up dynamic compilation.
+
+  * `neko.context` helps retrieve resources from the application’s context.
+
+  * `neko.listeners` contains namespaces that take the tedium to adding
+    callback code to various widgets.
+
+  * `neko.log` interns functions that make logging from your code clean and
+    simple.
+
+  * `neko.threading` will contain utilities to manage asynchronous tasks and
+    working with UI threads.
+
+
+=== Requirements ===
+
+Using Neko requires the following:
+
+Clojure::
+  Other versions have not been tested.  If you would like to use dynamic
+  compilation or support API level 7 (2.1/Eclair), you will need to use the
+  Clojure from branch `android-1.2.x` available from
+  https://github.com/sattvik/clojure/tree/android-1.2.x[this repository on
+  GitHub].
+
+
+Android SDK Tools::
+  Neko has been developed with the latest revision of the Android SDK tools,
+  and is compatible with r14 and up of the Android SDK.
+
+WARNING: Revision 14 of the Android SDK introduced some major changes in the
+Ant build system.  Neko has been updated to use the new build system.  You will
+probably need to change your project if you have been using an older version of
+Neko/SDK.  For more detailed information, check the
+http://tools.android.com/recent/buildchangesinrevision14[Android Tools Project
+Site].
+
+
+Android Platform SDK 7 (2.1/Eclair) or newer::
+  In order to maintain backwards-compatibility, Neko does not support any APIs
+  for newer versions of the platform.
+
+
+Use
+---
+
+The following instructions should help you to add Clojure support to your
+project’s build and allow you to use the libraries within your application.
+
+=== Build support ===
+
+To use Neko’s build support for Clojure, you will need to make two
+modifications to your project’s `build.xml` file.
+
+. You must add a line to similar to the following *before the line with
+  `<import file="${sdk.dir}/tools/ant/build.xml" />`*.
++
+----
+<import file="/path/to/neko/build-support/clojure.xml"/>
+----
++
+The important thing is that the value of the `file` attribute should resolve
+to the `clojure.xml` in the `build-support` directory of this
+repository.  It may be either a relative or absolute path.
+
+. You must find the line that reads `<!-- version-tag: 1 -->` and change the
+  `1` to `custom`.  If you do not do this, Android may overwrite your changes.
+
+For most projects, that is all you have to do.  So long as your Clojure source
+files are in `src/clojure` and you have placed a Clojure JAR file in
+`libs`, Ant will now automatically find and compile all of your Clojure code.
+
+
+==== Reflection warnings ====
+
+To enable reflection warnings during compilation, simply set the
+`clojure.warn.reflection` property to `true`.
+
+
+==== `clojure.properties` ====
+
+You can place a `clojure.properties` file in the same directory as the
+`clojure.xml` file.  This file will be sourced and used in any project in which
+you have enabled Clojure support.
+
+==== Test and library projects ====
+
+If your project is a test or library project, you should not place a copy of
+the Clojure library in the `libs` directory.  If you do this, when building an
+application that uses your library or when building your test project, the `dx`
+tool will fail due to multiple inclusions of the same Clojure classes.
+
+In these circumstances, you should either set a `clojure.jar` property in your
+project’s `build.properties` file or in the `clojure.properties` file as
+described in the previous section.
+
+Also, if you are developing an Android library project, you should add the
+following line to your `build.properties` file:
+
+----
+source.dir=src/java
+----
+
+This will ensure that your Clojure sources are not inadvertently included in
+any applications that use your library.
+
+=== Libraries ===
+
+Neko is packaged as an Android library project.  This makes it easy to add the
+libraries to your application if you are using Android’s build system.
+Essentially, all you have to do is add a line to your project’s
+`build.properties` similar to the following:
+
+----
+android.library.reference.1=/path/to/neko
+----
+
+Where the path is either absolute or relative and resolves to the base
+directory for Neko.  To learn more about Android library projects, you can read
+the SDK documentation for referencing a library project in
+http://developer.android.com/guide/developing/projects/projects-eclipse.html#ReferencingLibraryProject[Eclipse]
+or
+http://developer.android.com/guide/developing/projects/projects-cmdline.html#ReferencingLibraryProject[from
+the command line].
+
+
+
+Legal information
+-----------------
+
+Copyright © 2011 Sattvik Software & Technology Resources, Ltd. Co. +
+All rights reserved.
+
+=== Eclipse Public License - v 1.0 ===
+
+THE ACCOMPANYING PROGRAM IS PROVIDED UNDER THE TERMS OF THIS ECLIPSE PUBLIC
+LICENSE (“AGREEMENT”). ANY USE, REPRODUCTION OR DISTRIBUTION OF THE
+PROGRAM CONSTITUTES RECIPIENT’S ACCEPTANCE OF THIS AGREEMENT.
+
+==== 1. DEFINITIONS ====
+
+“Contribution” means:
+
+a. in the case of the initial Contributor, the initial code and documentation
+   distributed under this Agreement, and
+
+b. in the case of each subsequent Contributor:
+
+   i)  changes to the Program, and
+
+   ii) additions to the Program;
++
+where such changes and/or additions to the Program originate from and are
+distributed by that particular Contributor. A Contribution ‘originates’ from a
+Contributor if it was added to the Program by such Contributor itself or anyone
+acting on such Contributor’s behalf.  Contributions do not include additions to
+the Program which: (i) are separate modules of software distributed in
+conjunction with the Program under their own license agreement, and (ii) are
+not derivative works of the Program.
+
+“Contributor” means any person or entity that distributes the Program.
+
+“Licensed Patents” mean patent claims licensable by a Contributor which are
+necessarily infringed by the use or sale of its Contribution alone or when
+combined with the Program.
+
+“Program” means the Contributions distributed in accordance with this
+Agreement.
+
+“Recipient” means anyone who receives the Program under this Agreement,
+including all Contributors.
+
+==== 2. GRANT OF RIGHTS ====
+
+a. Subject to the terms of this Agreement, each Contributor hereby grants
+   Recipient a non-exclusive, worldwide, royalty-free copyright license to
+   reproduce, prepare derivative works of, publicly display, publicly perform,
+   distribute and sublicense the Contribution of such Contributor, if any, and
+   such derivative works, in source code and object code form.p>
+
+b. Subject to the terms of this Agreement, each Contributor hereby grants
+   Recipient a non-exclusive, worldwide, royalty-free patent license under
+   Licensed Patents to make, use, sell, offer to sell, import and otherwise
+   transfer the Contribution of such Contributor, if any, in source code and
+   object code form. This patent license shall apply to the combination of the
+   Contribution and the Program if, at the time the Contribution is added by
+   the Contributor, such addition of the Contribution causes such combination
+   to be covered by the Licensed Patents. The patent license shall not apply to
+   any other combinations which include the Contribution. No hardware per se is
+   licensed hereunder.
+
+c. Recipient understands that although each Contributor grants the licenses to
+   its Contributions set forth herein, no assurances are provided by any
+   Contributor that the Program does not infringe the patent or other
+   intellectual property rights of any other entity. Each Contributor disclaims
+   any liability to Recipient for claims brought by any other entity based on
+   infringement of intellectual property rights or otherwise. As a condition to
+   exercising the rights and licenses granted hereunder, each Recipient hereby
+   assumes sole responsibility to secure any other intellectual property rights
+   needed, if any. For example, if a third party patent license is required to
+   allow Recipient to distribute the Program, it is Recipient’s responsibility
+   to acquire that license before distributing the Program.
+
+d. Each Contributor represents that to its knowledge it has sufficient
+   copyright rights in its Contribution, if any, to grant the copyright license
+   set forth in this Agreement.
+
+==== 3. REQUIREMENTS ====
+
+A Contributor may choose to distribute the Program in object code form under
+its own license agreement, provided that:
+
+a. it complies with the terms and conditions of this Agreement; and
+
+b. its license agreement:
+
+   i) effectively disclaims on behalf of all Contributors all warranties and
+   conditions, express and implied, including warranties or conditions of title
+   and non-infringement, and implied warranties or conditions of
+   merchantability and fitness for a particular purpose;
+
+   ii) effectively excludes on behalf of all Contributors all liability for
+   damages, including direct, indirect, special, incidental and consequential
+   damages, such as lost profits;
+
+   iii) states that any provisions which differ from this Agreement are offered
+   by that Contributor alone and not by any other party; and
+
+   iv) states that source code for the Program is available from such
+   Contributor, and informs licensees how to obtain it in a reasonable manner
+   on or through a medium customarily used for software exchange.
+
+When the Program is made available in source code form:
+
+a. it must be made available under this Agreement; and
+
+b. a copy of this Agreement must be included with each copy of the Program.
+
+Contributors may not remove or alter any copyright notices contained within the
+Program.
+
+Each Contributor must identify itself as the originator of its Contribution, if
+any, in a manner that reasonably allows subsequent Recipients to identify the
+originator of the Contribution.
+
+==== 4. COMMERCIAL DISTRIBUTION ====
+
+Commercial distributors of software may accept certain responsibilities with
+respect to end users, business partners and the like. While this license is
+intended to facilitate the commercial use of the Program, the Contributor who
+includes the Program in a commercial product offering should do so in a manner
+which does not create potential liability for other Contributors. Therefore, if
+a Contributor includes the Program in a commercial product offering, such
+Contributor (“Commercial Contributor”) hereby agrees to defend and indemnify
+every other Contributor (“Indemnified Contributor”) against any losses, damages
+and costs (collectively “Losses”) arising from claims, lawsuits and other legal
+actions brought by a third party against the Indemnified Contributor to the
+extent caused by the acts or omissions of such Commercial Contributor in
+connection with its distribution of the Program in a commercial product
+offering. The obligations in this section do not apply to any claims or Losses
+relating to any actual or alleged intellectual property infringement. In order
+to qualify, an Indemnified Contributor must: a) promptly notify the Commercial
+Contributor in writing of such claim, and b) allow the Commercial Contributor
+to control, and cooperate with the Commercial Contributor in, the defense and
+any related settlement negotiations. The Indemnified Contributor may
+participate in any such claim at its own expense.
+
+For example, a Contributor might include the Program in a commercial product
+offering, Product X. That Contributor is then a Commercial Contributor. If that
+Commercial Contributor then makes performance claims, or offers warranties
+related to Product X, those performance claims and warranties are such
+Commercial Contributor’s responsibility alone. Under this section, the
+Commercial Contributor would have to defend claims against the other
+Contributors related to those performance claims and warranties, and if a court
+requires any other Contributor to pay any damages as a result, the Commercial
+Contributor must pay those damages.
+
+==== 5. NO WARRANTY ====
+
+EXCEPT AS EXPRESSLY SET FORTH IN THIS AGREEMENT, THE PROGRAM IS PROVIDED ON AN
+“AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, EITHER EXPRESS OR
+IMPLIED INCLUDING, WITHOUT LIMITATION, ANY WARRANTIES OR CONDITIONS OF TITLE,
+NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Each
+Recipient is solely responsible for determining the appropriateness of using
+and distributing the Program and assumes all risks associated with its exercise
+of rights under this Agreement , including but not limited to the risks and
+costs of program errors, compliance with applicable laws, damage to or loss of
+data, programs or equipment, and unavailability or interruption of operations.
+
+==== 6. DISCLAIMER OF LIABILITY ====
+
+EXCEPT AS EXPRESSLY SET FORTH IN THIS AGREEMENT, NEITHER RECIPIENT NOR ANY
+CONTRIBUTORS SHALL HAVE ANY LIABILITY FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING WITHOUT LIMITATION LOST
+PROFITS), HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
+STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY
+WAY OUT OF THE USE OR DISTRIBUTION OF THE PROGRAM OR THE EXERCISE OF ANY RIGHTS
+GRANTED HEREUNDER, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
+
+==== 7. GENERAL ====
+
+If any provision of this Agreement is invalid or unenforceable under applicable
+law, it shall not affect the validity or enforceability of the remainder of the
+terms of this Agreement, and without further action by the parties hereto, such
+provision shall be reformed to the minimum extent necessary to make such
+provision valid and enforceable.
+
+If Recipient institutes patent litigation against any entity (including a
+cross-claim or counterclaim in a lawsuit) alleging that the Program itself
+(excluding combinations of the Program with other software or hardware)
+infringes such Recipient’s patent(s), then such Recipient’s rights granted
+under Section 2(b) shall terminate as of the date such litigation is filed.
+
+All Recipient’s rights under this Agreement shall terminate if it fails to
+comply with any of the material terms or conditions of this Agreement and does
+not cure such failure in a reasonable period of time after becoming aware of
+such noncompliance. If all Recipient’s rights under this Agreement terminate,
+Recipient agrees to cease use and distribution of the Program as soon as
+reasonably practicable. However, Recipient’s obligations under this Agreement
+and any licenses granted by Recipient relating to the Program shall continue
+and survive.
+
+Everyone is permitted to copy and distribute copies of this Agreement, but in
+order to avoid inconsistency the Agreement is copyrighted and may only be
+modified in the following manner. The Agreement Steward reserves the right to
+publish new versions (including revisions) of this Agreement from time to time.
+No one other than the Agreement Steward has the right to modify this Agreement.
+The Eclipse Foundation is the initial Agreement Steward. The Eclipse Foundation
+may assign the responsibility to serve as the Agreement Steward to a suitable
+separate entity. Each new version of the Agreement will be given a
+distinguishing version number. The Program (including Contributions) may always
+be distributed subject to the version of the Agreement under which it was
+received. In addition, after a new version of the Agreement is published,
+Contributor may elect to distribute the Program (including its Contributions)
+under the new version. Except as expressly stated in Sections 2(a) and 2(b)
+above, Recipient receives no rights or licenses to the intellectual property of
+any Contributor under this Agreement, whether expressly, by implication,
+estoppel or otherwise. All rights in the Program not expressly granted under
+this Agreement are reserved.
+
+This Agreement is governed by the laws of the State of New York and the
+intellectual property laws of the United States of America. No party to this
+Agreement will bring a legal action under this Agreement more than one year
+after the cause of action arose. Each party waives its rights to a jury trial
+in any resulting litigation.
+
+// vim:set spell ft=asciidoc: