1 files changed, 122 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..f07e579
--- /dev/null
+++ b/README.md
@@ -0,0 +1,122 @@
+lawnmower
+=========
+
+A simple way to manage the gopher lawn or any other collection of 
+links organised in categories and sub-categories.
+
+SYNOPSYS
+========
+
+  cat file1 file2 ... | ./lawnmower
+
+where `file1`, `file2` ... are files containing the description of 
+categories and links. The command will generate a directory structure
+that mimics the hierarchical organisation of categories, and will 
+generate an index.gph file for each category. 
+
+Customisation
+=============
+
+The rendering can be customised by tinkering with the functions in 
+`render.awk`. The only ones that are called from outside `render.awk`
+are (in this order):
+
+  - render_init(): 
+    can be used for any specific initialisation 
+  
+  - render_categories(category, cnum, link, lnum): 
+    creates the directory structure and puts titles and list of 
+    sub-categories in each index.gph file.
+
+  - render_post_categories(category, cnum):
+    can be used to add anything to the index.gph files before the 
+    list of links is appended.
+
+  - render_links(category, cnum, link, lnum):
+    add each link to the list of links of all the categories it 
+    belongs to.
+
+  - render_finalise(category, cnum, link, lnum):
+    anything that needs to be rendered after the list of links. 
+    Currently used to add a back-link to the main page. 
+
+Link and Category description
+=============================
+
+Each link is a RFC822 stanza like:
+
+Type: link
+Selector:
+Host:
+Port:
+LinkName:
+Description:
+Category:
+Keywords:
+
+The meaning of most fields should be obvious. LinkName: is the displayed 
+name of the selector. Description: is a description line that 
+accompanies the selector. It can possibly span more than one line.
+Category: is a comma-separated list of catagory Names to which the link
+belongs. Keywords: is a comma-separated list of keywords, which could be 
+used to enhance search. Please see an example below:
+
+
+   Type: link
+   Selector: /
+   Host: kalos.mine.nu
+   Port: 70
+   LinkName: KatolaZ's gopherhole 
+   Description: KatolaZ's home page, where he shows software and other 
+     stuff.
+   Category: homepage
+   Keywords: homepage, katolaz, software
+
+Each category is a RFC822 stanza like:
+
+Type: category
+Name: 
+Selector:
+Host:
+Port:
+LinkName:
+Title:
+Description:
+Parent:
+Keywords:
+
+The meaning of the fields should be obvious. Title: is the title to be
+shown in the front page of the category. Name: is the (unique) name of 
+the category. Parent: is a comma-separated list of categories to which
+this category belongs. Examples below:
+
+
+   Type: category
+   Name: homepage
+   Selector: /lawn/homepages/index.gph
+   Host: host
+   Port: port
+   LinkName: homepages
+   Title: ____________H_O_M_E_P_A_G_E_S____________
+   Description: Homepages of some gophers. 
+     Feel free to suggest yours by calling 1-2345-678-901 
+     Mon-Fri 9:00-17:00
+   Parent: root
+   Keywords: homepages, gopherholes, personal
+   
+   
+   Type: category
+   Name: bitreich-members
+   Selector: /lawn/homepages/bitreich/index.gph
+   Host: host
+   Port: port
+   LinkName: Bitreich members
+   Title: _______B_I_T_R_E_I_C_H___M_E_M_B_E_R_S_______
+   Description: gopherholes of Bitreich members
+   Parent: homepage
+   Kewords: homepages, bitreich, members
+   
+There is no special category, meaning that the top-most category is 
+treated as any other category, and its page has exactly the same 
+structure as any other category. This can be customised through the 
+rendering functions above.