Converted READMEs to markdown

2 files changed, 174 insertions, 141 deletions

diff --git a/README-german.md b/README-german.md
index ffecc5a..297d195 100755
--- a/README-german.md
+++ b/README-german.md
@@ -1,85 +1,91 @@
-htmlSQL - Version 0.5 - README

----------------------------------------------------------------------

-AUTHOR: Jonas John (http://www.jonasjohn.de/)

-

-BESCHREIBUNG:

----------------------------------------------------------------------

-htmlSQL ist eine experimentelle PHP Klasse mit der man auf HTML

-Elemente über eine SQL ähnliche Syntax zugreifen kann. Das

-bedeutet das man nicht mehr über komplizierte Funktionen

-bestimmte Tags extrahieren muss, sondern einfach eine Query

-wie diese ausführt:

-

-SELECT href,title   FROM  a   WHERE $class == "liste"

-       ^ HTML Attrib.     ^         ^ Abfrage (kann auch leer sein)

-         die zurück-      ^

-         gegeben          ^ HTML Tags die durchsucht werden sollen 

-         werden sollen      "*" ist hier möglich = alle Tags

-                              

-Diese Abfrage gibt einen Array aller Links mit dem Attribut class="liste"

-zurück.

-

-Alle HTTP Verbindungen in htmlSQL benützen die wunderbare Snoopy Klasse

-(Package Version 1.2.3 - URL: http://snoopy.sourceforge.net/). 

-Allerdings wird Snoopy nicht für "file" oder "string" Queries benötigt.

-Alle Snoopy betreffenden Dokumente (z.B: Copyright-Infos, Readme, usw.)

-befinden sich im "snoopy_data/" Unterordner.

-

-

-INSTALLATION / ANWENDUNG:

----------------------------------------------------------------------

-Um htmlSQL in eigenen Projekten zu benützen ist es nur notwendig die

-zwei Dateien "snoopy.class.php" und die "htmlsql.class.php" zu laden

-(mit include oder z.B. require). Danach kann htmlSQL, wie in den 

-Beispielen (siehe examples/-Ordner), angesprochen werden. Dies sollte

-nicht allzu schwer sein :-)

-

-

-HINTERGRUND / GESCHICHTE:

----------------------------------------------------------------------

-Ich hatte die Idee zu dieser Klasse als ich Daten von einer Web-Seite

-extrahiert habe und dabei merkte das sich die Funktionen und Quelltexte

-oftmals wiederholen. Da kam mir die Idee das ganze zu vereinfachen und

-eine universelle Klasse dafür zu entwickeln. 

-

-

-WARNUNG:

----------------------------------------------------------------------

-Für die Abfragen wird die eval()-Funktion benützt. Deshalb sollten alle

-vom Besucher abhängige Daten wie z.b. IDs geprüft oder ggf. gefiltert 

-werden da es ansonsten möglich wäre schadhaften PHP Quelltext auszuführen.

-Vertraue niemals Benutzereingaben!

-

-

-TODO:

----------------------------------------------------------------------

-- den internen HTML Parser verbessern

-- ein eigenes Query system entwickeln und nicht

-  das PHP eigene nutzen ( Die eval()-Lösung gefällt mir nicht wirklich)

-- Mehr Fehlerprüfungen

-- LIMIT Funktion einbauen

-

-

-ANWENDUNGSGEBIETE VON HTMLSQL:

----------------------------------------------------------------------

-- Daten von anderen Web-Seiten auslesen

-- HTML basierte Datenbanken?

-- XML Daten auslesen

-

-

-LIZENZ:

----------------------------------------------------------------------

-htmlSQL benützt eine modifizierte BSD Lizenz, welche ziemlich offen ist.

-Der Lizenztext befindet sich in der "htmlsql.class.php". 

-Kurz zusammengefasst besagt er folgendes: 

-

-- Die htmlSQL Klasse kann frei in kommerziellen und nicht-kommerziellen 

-  Projekten benützt werden

-- Die Klasse darf mit oder ohne Änderungen frei weitergegeben werden

-- Der Copyright-Hinweis darf nicht entfernt werden

-- Der Autor übernimmt keine Haftung für eventuelle Schäden

-- Der Name des Autors oder anderen beteiligten Autoren darf nur mit

-  schriftlicher Genehmigung benützt werden um für Produkte, welche 

-  htmlSQL benützen, zu werben

-

-

+htmlSQL - Version 0.5
+=====================
+
+htmlSQL ist eine experimentelle PHP Klasse mit der man auf HTML
+Elemente über eine SQL ähnliche Syntax zugreifen kann. Das
+bedeutet das man nicht mehr über komplizierte Funktionen
+bestimmte Tags extrahieren muss, sondern einfach eine Query
+wie diese ausführt:
+
+    SELECT href,title   FROM  a   WHERE $class == "liste"
+           ^ HTML Attrib.     ^         ^ Abfrage (kann auch leer sein)
+             die zurück-      ^
+             gegeben          ^ HTML Tags die durchsucht werden sollen
+             werden sollen      "*" ist hier möglich = alle Tags
+
+Diese Abfrage gibt einen Array aller Links mit dem Attribut class="liste"
+zurück.
+
+Alle HTTP Verbindungen in htmlSQL benützen die wunderbare Snoopy Klasse
+(Package Version 1.2.3 - URL: http://sourceforge.net/projects/snoopy/).
+Allerdings wird Snoopy nicht für "file" oder "string" Queries benötigt.
+Alle Snoopy betreffenden Dokumente (z.B: Copyright-Infos, Readme, usw.)
+befinden sich im "snoopy_data/" Unterordner.
+
+
+Installation / Anwendung
+------------------------
+
+Um htmlSQL in eigenen Projekten zu benützen ist es nur notwendig die
+zwei Dateien "snoopy.class.php" und die "htmlsql.class.php" zu laden
+(mit include oder z.B. require). Danach kann htmlSQL, wie in den
+Beispielen (siehe examples/-Ordner), angesprochen werden. Dies sollte
+nicht allzu schwer sein :-)
+
+
+Hintergrund / Geschichte
+------------------------
+
+Ich hatte die Idee zu dieser Klasse als ich Daten von einer Web-Seite
+extrahiert habe und dabei merkte das sich die Funktionen und Quelltexte
+oftmals wiederholen. Da kam mir die Idee das ganze zu vereinfachen und
+eine universelle Klasse dafür zu entwickeln.
+
+
+Warnung
+-------
+
+Für die Abfragen wird die eval()-Funktion benützt. Deshalb sollten alle
+vom Besucher abhängige Daten wie z.b. IDs geprüft oder ggf. gefiltert
+werden da es ansonsten möglich wäre schadhaften PHP Quelltext auszuführen.
+Vertraue niemals Benutzereingaben!
+
+
+Todo
+----
+
+- Den internen HTML Parser verbessern
+- Ein eigenes Query system entwickeln und nicht
+  das PHP eigene nutzen ( Die eval()-Lösung gefällt mir nicht wirklich)
+- Mehr Fehlerprüfungen
+- LIMIT Funktion einbauen
+
+
+Anwendungsgebiete von htmlSQL
+-----------------------------
+
+- Daten von anderen Web-Seiten auslesen
+- HTML basierte Datenbanken?
+- XML Daten auslesen
+
+
+Author
+------
+
+- [Jonas John](http://www.jonasjohn.de/)
+
+
+Lizenz
+------
+
+htmlSQL benützt eine modifizierte BSD Lizenz, welche ziemlich offen ist.
+Der Lizenztext befindet sich in der "htmlsql.class.php".
+Kurz zusammengefasst besagt er folgendes:
+
+- Die htmlSQL Klasse kann frei in kommerziellen und nicht-kommerziellen Projekten benützt werden
+- Die Klasse darf mit oder ohne Änderungen frei weitergegeben werden
+- Der Copyright-Hinweis darf nicht entfernt werden
+- Der Autor übernimmt keine Haftung für eventuelle Schäden
+- Der Name des Autors oder anderen beteiligten Autoren darf nur mit
+  schriftlicher Genehmigung benützt werden um für Produkte, welche
+  htmlSQL benützen, zu werben
diff --git a/README.md b/README.md
index 742a254..1b471bb 100755
--- a/README.md
+++ b/README.md
@@ -1,67 +1,94 @@
-htmlSQL - Version 0.5 - README

----------------------------------------------------------------------

-AUTHOR: Jonas John (http://www.jonasjohn.de/)

-

-

-DESCRIPTION:

----------------------------------------------------------------------

+htmlSQL - Version 0.5

+=====================
+
 htmlSQL is a experimental PHP class which allows you to access HTML

 values by an SQL like syntax. This means that you don't have to write

-complex functions (regular expressions) to extract specific values.

-The htmlSQL queries look like this:

-

-SELECT href,title FROM a WHERE $class == "list"

-       ^ Attributes    ^       ^ search query (can be empty)

-         to return     ^ 

-                       ^ HTML tag to search in 

-                         "*" is possible = all tags

-                               

-This query returns an array with all links that contain

-the attribute class="list".

-

-All web transfers in htmlSQL are using the awesome Snoopy class 

-(package version 1.2.3 - URL: http://snoopy.sourceforge.net/)

-But for file or string queries Snoopy is not required. You find all

-Snoopy related documents (copyright, readme, etc) in the snoopy_data/ 

-folder.

-

-

-HOW TO USE:

----------------------------------------------------------------------

-Just include the "snoopy.class.php" and the "htmlsql.class.php" files 

-into your PHP scripts and look at the examples (examples/) to get an

-idea of how to use the htmlSQL class. It should be very simple :-)

-

-

-BACKGROUND / IDEA:

----------------------------------------------------------------------

+complex functions or regular expressions to extract specific values.
+

+**htmlSQL queries look like this:**

+

+    SELECT href,title FROM a WHERE $class == "list"

+           ^ Attributes    ^       ^ search query (can be empty)

+             to return     ^

+                           ^ HTML tag to search in

+                             "*" is possible = all tags

+

+This query should return an array with all links that contain the attribute `class="list"`.

+

+
+The project has been abandoned
+------------------------------
+
+htmlSQL was a experiment I made in 2006. I'm **not** supporting or extending the library anymore, this repository is only for historical purposes.
+But feel free to fork, modify and study the source code. If you need a reliable library for data scraping I recommend using **other modules** (see below).
+
+
+Related projects:
+
+* PHP: [SimpleXML](http://www.php.net/dom), [DOM](http://www.php.net/dom)
+* Perl: [pQuery](http://search.cpan.org/~ingy/pQuery-0.07/lib/pQuery.pm)
+* Python: [Scrapy](http://scrapy.org/)
+* JavaScript: [node.js](http://blog.nodejitsu.com/jsdom-jquery-in-5-lines-on-nodejs)
+
+
+Related Hacker News threads:
+
+* [PHP class to query the web by an SQL like language](http://news.ycombinator.com/item?id=2097008)
+* [Ask YC: What do you scrape? How do you scrape?](http://news.ycombinator.com/item?id=159025)
+

+
+Requirements
+------------
+
+- Any flavor of PHP4+ should do
+- [Snoopy PHP class - Version 1.2.3](http://sourceforge.net/projects/snoopy/) (optional - required for web transfers)
+  You find all Snoopy related documents (copyright, readme, etc) in the snoopy_data/ subdirectory.

+
+

+Usage

+-----
+

+Just include the "snoopy.class.php" and the "htmlsql.class.php" files

+into your PHP scripts and look at the examples to get an idea of how 
+to use the htmlSQL class. It should be very simple :-)

+

+

+Background / idea

+-----------------
+

 I had this idea while extracting some data from a website. As I realized

-that the algorithms and functions to extract links and other tags are 

+that the algorithms and functions to extract links and other tags are

 often the same - I had the idea to combine all functions to an universal

-usable class. While drinking a coffee and thinking on that problem, I 

-thought it would be cool to access HTML elements by using SQL. So I 

-started creating this class... 

+usable class. While drinking a coffee and thinking on that problem, I

+thought it would be cool to access HTML elements by using SQL. So I

+started creating this class...

+

 

+Warning

+-------
 

-WARNING:

----------------------------------------------------------------------

-The eval() function is used for the WHERE statement. Make sure that all 

-user data is checked and filtered against malicious PHP code. 

-Never trust user input! 

+The `eval()` function is used for the WHERE statement. Make sure that all

+user data is checked and filtered against malicious PHP code.

+Never trust any user input!

 

 

-TODO:

----------------------------------------------------------------------

-- enhance the HTML parser

-- test htmlSQL with invalid and bad HTML files

-- replace the ugly eval() method for the WHERE statement

-  with an own method

-- more error checks

-- include the LIMIT function/method like in SQL

+Todo

+----
 

+* Enhance the HTML parser

+* Test htmlSQL with invalid and bad HTML files

+* Replace the ugly `eval()` method for the WHERE statement with an own method

+* More error checks

+* Include the LIMIT function/method like in SQL

 

-LICENSE:

----------------------------------------------------------------------

-htmlSQL uses a modified BSD license, you find the full license text 

-in the "htmlsql.class.php". 

+
+Author
+------
 

+* [Jonas John](http://www.jonasjohn.de/)
+
+
+License
+-------
+
+htmlSQL uses a modified BSD license, you find the full license text in the "htmlsql.class.php".