Improve and reorganize the README

2012-09-10 14:44:06 +02:00 · 2012-09-10 14:44:06 +02:00 · 9bb2bef50d
parent 32b4729305
commit 9bb2bef50d
1 changed files with 68 additions and 72 deletions
--- a/README.md
+++ b/README.md
@ -1,4 +1,4 @@
-# Our goal is to make collaborative editing the standard on the web
+# Making collaborative editing the standard on the web

 # About
 Etherpad lite is a really-real time collaborative editor spawned from the Hell fire of Etherpad. 
@ -7,24 +7,7 @@ is based on node.js ergo is much lighter and more stable than the original Ether
 is that this will encourage more users to use and install a realtime collaborative editor. A smaller, manageable and well 
 documented codebase makes it easier for developers to improve the code and contribute towards the project.

-Etherpad Lite is optimized to be easy embeddable. It provides a [HTTP API](https://github.com/Pita/etherpad-lite/wiki/HTTP-API) 
-that allows your web application to manage pads, users and groups. 
-There are several clients in for this API:
-
-* [PHP](https://github.com/TomNomNom/etherpad-lite-client), thx to [TomNomNom](https://github.com/TomNomNom)
-* [.Net](https://github.com/ja-jo/EtherpadLiteDotNet), thx to [ja-jo](https://github.com/ja-jo)
-* [Node.js](https://github.com/tomassedovic/etherpad-lite-client-js), thx to [tomassedovic](https://github.com/tomassedovic)
-* [Ruby](https://github.com/jhollinger/ruby-etherpad-lite), thx to [jhollinger](https://github.com/jhollinger)
-* [Python](https://github.com/devjones/PyEtherpadLite), thx to [devjones](https://github.com/devjones)
-
-There is also a [jQuery plugin](https://github.com/johnyma22/etherpad-lite-jquery-plugin) that helps you to embed Pads into your website
-
-**Online demo**<br>
-Visit <http://beta.etherpad.org> to test it live
-
-Here is the **[FAQ](https://github.com/Pita/etherpad-lite/wiki/FAQ)**
-
-# Etherpad vs Etherpad Lite
+**Etherpad vs Etherpad lite**
 <table>
  <tr>
    <td>&nbsp;</td><td><b>Etherpad</b></td><td><b>Etherpad Lite</b></td>
@ -43,78 +26,91 @@ Here is the **[FAQ](https://github.com/Pita/etherpad-lite/wiki/FAQ)**
  </tr>
 </table> 

+
+Etherpad Lite is designed to be easily embeddable and provides a [HTTP API](https://github.com/Pita/etherpad-lite/wiki/HTTP-API) 
+that allows your web application to manage pads, users and groups. It is recommended to use the client implementations available for this API, listed on [this wiki page](https://github.com/Pita/etherpad-lite/wiki/HTTP-API-client-libraries).
+There is also a [jQuery plugin](https://github.com/johnyma22/etherpad-lite-jquery-plugin) that helps you to embed Pads into your website
+
+**Visit [beta.etherpad.org](http://beta.etherpad.org) to test it live**
+
+Also, check out the **[FAQ](https://github.com/Pita/etherpad-lite/wiki/FAQ)**, really!
+
 # Installation

 ## Windows

-1. Download <http://etherpad.org/etherpad-lite-win.zip>
-2. Extract the file
-3. Open the extracted folder and double click `start.bat`
-4. Open your web browser and browse to <http://localhost:9001>. You like it? Look at the 'Next Steps' section below
+### Prebuilt windows package
+This package works out of the box on any windows machine, but it's not very useful for developing purposes...
+
+1. Download the windows package <https://github.com/Pita/etherpad-lite/downloads>
+2. Extract the folder
+
+Now, run `start.bat` and open <http://localhost:9001> in your browser. You like it? [Next steps](#next-steps).
+
+### Fancy install
+You'll need [node.js](http://nodejs.org) and (optionally, though recommended) git.
+
+1. Grab the source, either
+  - download <https://github.com/Pita/etherpad-lite/zipball/master>
+  - or `git clone https://github.com/Pita/etherpad-lite.git` (for this you need git, obviously)
+2. start `bin\installOnWindows.bat`
+
+Now, run `start.bat` and open <http://localhost:9001> in your browser.
+
+Update to the latest version with `git pull origin`, then run `bin\installOnWindows.bat`, again.
+
+[Next steps](#next-steps).

 ## Linux
+You'll need gzip, git, curl, libssl develop libraries, python and gcc.  
+*For Debian/Ubuntu*: `apt-get install gzip git-core curl python libssl-dev pkg-config build-essential`  
+*For Fedora/CentOS*: `yum install gzip git-core curl python openssl-devel && yum groupinstall "Development Tools"`

-**As root:**
-
-<ol>
-  <li>Install the dependencies. We need gzip, git, curl, libssl develop libraries, python and gcc. <br><i>For Debian/Ubuntu</i> <code>apt-get install gzip git-core curl python libssl-dev pkg-config build-essential</code><br>
-  <i>For Fedora/CentOS</i> <code>yum install gzip git-core curl python openssl-devel && yum groupinstall "Development Tools"</code>
-  </li><br>
-  <li>Install node.js 
-    <ol type="a">
-      <li>Download the latest <b>0.6.x</b> node.js release from <a href="http://nodejs.org/#download">http://nodejs.org/#download</a></li>
-      <li>Extract it with <code>tar xf node-v0.6*</code></li>
-      <li>Move into the node folder <code>cd node-v0.6*</code> and build node with <code>./configure && make && make install</code></li>
-    </ol>
-  </li>
-</ol>
+Additionally, you'll need [node.js](http://nodejs.org).

 **As any user (we recommend creating a separate user called etherpad-lite):**

-<ol start="3">
-  <li>Move to a folder where you want to install Etherpad Lite. Clone the git repository <code>git clone 'git://github.com/Pita/etherpad-lite.git'</code><br></li>
-  <li>Change into the directory containing the Etherpad Lite source code clone with <code>cd etherpad-lite</code><br></li>
-  <li>Start it with <code>bin/run.sh</code><br>&nbsp;</li>
-  <li>Open your web browser and visit <a href="http://localhost:9001">http://localhost:9001</a>. You like it? Look at the 'Next Steps' section below</li>
-</ol>
+1. Move to a folder where you want to install Etherpad Lite. Clone the git repository `git clone git://github.com/Pita/etherpad-lite.git`
+2. Change into the new directory containing the cloned source code `cd etherpad-lite`

-## Next Steps
-You can modify the settings in the file `settings.json`
+Now, run `bin\run.sh` and open <http://127.0.0.1:9001> in your browser. 

-If you have multiple settings files, you may pass one to `bin/run.sh` using the `-s|--settings` option. This allows you to run multiple Etherpad Lite instances from the same installation.
+Update to the latest version with `git pull origin`. The next start with bin/run.sh will update the dependencies.

-You should use a dedicated database such as "mysql" if you are planning on using etherpad-lite in a production environment, the "dirty" database driver is only for testing and/or development purposes.
+You like it? [Next steps](#next-steps).

-You can update to the latest version with `git pull origin`. The next start with bin/run.sh will update the dependencies
+# Next Steps

-Look at this wiki pages: 
+## Tweak the settings
+You can modify the settings in `settings.json`. (If you need to handle multiple settings files, you can pass the path to a settings file to `bin/run.sh` using the `-s|--settings` option. This allows you to run multiple Etherpad Lite instances from the same installation.)

-* [How to deploy Etherpad Lite as a service](https://github.com/Pita/etherpad-lite/wiki/How-to-deploy-Etherpad-Lite-as-a-service)
-* [How to put Etherpad Lite behind a reverse Proxy](https://github.com/Pita/etherpad-lite/wiki/How-to-put-Etherpad-Lite-behind-a-reverse-Proxy)
-* [How to customize your Etherpad Lite installation](https://github.com/Pita/etherpad-lite/wiki/How-to-customize-your-Etherpad-Lite-installation)
-* [How to use Etherpad-Lite with jQuery](https://github.com/Pita/etherpad-lite/wiki/How-to-use-Etherpad-Lite-with-jQuery)
-* [How to use Etherpad Lite with MySQL](https://github.com/Pita/etherpad-lite/wiki/How-to-use-Etherpad-Lite-with-MySQL)
-* [Sites that run Etherpad Lite](https://github.com/Pita/etherpad-lite/wiki/Sites-that-run-Etherpad-Lite)
-* [How to migrate the database from Etherpad to Etherpad Lite](https://github.com/Pita/etherpad-lite/wiki/How-to-migrate-the-database-from-Etherpad-to-Etherpad-Lite)
+You should use a dedicated database such as "mysql", if you are planning on using etherpad-lite in a production environment, since the "dirtyDB" database driver is only for testing and/or development purposes.

-You can find more information in the [wiki](https://github.com/Pita/etherpad-lite/wiki). Feel free to improve these wiki pages
+## Helpful resources
+The [wiki](https://github.com/Pita/etherpad-lite/wiki) is your one-stop resource for Tutorials and How-to's, really check it out! Also, feel free to improve these wiki pages.

-# Develop
-If you're new to git and github, start by watching [this video](http://youtu.be/67-Q26YH97E) then read this [git guide](http://learn.github.com/p/intro.html).
+Documentation can be found in `docs/`.

-If you're new to node.js, start with this video <http://youtu.be/jo_B4LTHi3I>.
+# Development

-You can debug with `bin/debugRun.sh`
+## Things you should know
+Read this [git guide](http://learn.github.com/p/intro.html) and watch this [video on getting started with Etherpad Lite Development](http://youtu.be/67-Q26YH97E).

-If you want to find out how Etherpads Easysync works (the library that makes it really realtime), start with this [PDF](https://github.com/Pita/etherpad-lite/raw/master/doc/easysync/easysync-full-description.pdf) (complex, but worth reading).
+If you're new to node.js, start with Ryan Dahl's [Introduction to Node.js](http://youtu.be/jo_B4LTHi3I).

-You know all this and just want to know how you can help? Look at the [TODO list](https://github.com/Pita/etherpad-lite/wiki/TODO).
-You can join the [mailinglist](http://groups.google.com/group/etherpad-lite-dev) or go to the freenode irc channel [#etherpad-lite-dev](http://webchat.freenode.net?channels=#etherpad-lite-dev)
+You can debug Etherpad lite using `bin/debugRun.sh`.

-You also help the project, if you only host a Etherpad Lite instance and share your experience with us.
+If you want to find out how Etherpad's `Easysync` works (the library that makes it really realtime), start with this [PDF](https://github.com/Pita/etherpad-lite/raw/master/doc/easysync/easysync-full-description.pdf) (complex, but worth reading).

-Please consider using [jshint](http://www.jshint.com/about/) if you plan to
-contribute to Etherpad Lite.
+## Getting started
+You know all this and just want to know how you can help?
+
+Look at the [TODO list](https://github.com/Pita/etherpad-lite/wiki/TODO) and our [Issue tracker](https://github.com/Pita/etherpad-lite/issues). (Please consider using [jshint](http://www.jshint.com/about/), if you plan to contribute code.)
+
+Also, and most importantly, read our [**Developer Guidelines**](https://github.com/Pita/etherpad-lite/wiki/Developer-Guidelines), really!
+
+# Get in touch
+Join the [mailinglist](http://groups.google.com/group/etherpad-lite-dev) and make some noise on our freenode irc channel [#etherpad-lite-dev](http://webchat.freenode.net?channels=#etherpad-lite-dev)!

 # Modules created for this project

@ -122,9 +118,9 @@ contribute to Etherpad Lite.
 * [channels](https://github.com/Pita/channels) "Event channels in node.js" - ensures that ueberDB operations are atomic and in series for each key
 * [async-stacktrace](https://github.com/Pita/async-stacktrace) "Improves node.js stacktraces and makes it easier to handle errors"

-# Donations
-* [Etherpad Foundation Flattr] (http://flattr.com/thing/71378/Etherpad-Foundation)
-* [Paypal] (http://etherpad.org) <-- Click the donate button
+# Donate!
+* [Flattr] (http://flattr.com/thing/71378/Etherpad-Foundation)
+* Paypal - Press the donate button on [etherpad.org](http://etherpad.org)

 # License
 [Apache License v2](http://www.apache.org/licenses/LICENSE-2.0.html)