added README.md and removed debugging messages

3 files changed, 128 insertions, 22 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.
diff --git a/parse.awk b/parse.awk
index e725532..db83b49 100644
--- a/parse.awk
+++ b/parse.awk
@@ -10,11 +10,10 @@ BEGIN{
 	delete link;
 
 	### configurable variables
-	BASEDIR="./";
-	ROOTFILE="./lawn/index.gph";
-	ROOTSEL="/lawn/index.gph";
-	HOST="localhost";
-	PORT="1500";
+	BASEDIR="./"; # the folder where the hierarchy will be created 
+	ROOTSEL="/lawn/index.gph"; # the selector of the root page (back)
+	HOST="localhost"; # the default host
+	PORT="1500"; # and the default port
 }
 
 function is_empty(a){
@@ -39,7 +38,6 @@ function add_category(c){
 
 
 function get_cur(cur){
-	#print "cur[Type]:", cur["Type"];	
 	switch (cur["Type"]) {
 		case "": {
 			print "empty type -- skipping record";
@@ -63,7 +61,6 @@ function get_cur(cur){
 
 /^[A-Z][-a-zA-Z]+:/{## New field
 	
-	#print "Field:",$1,"-","Value:",$2
 	gsub(/^ +/,"",$2);
 	gsub(/ *$/,"",$2);
 	cur[$1]=$2;
@@ -86,18 +83,10 @@ function get_cur(cur){
 }
 
 END{
-##	for (i=1;i<=cnum;i++){
-##		printf("[1%s|%s|%s|%s]\r\n", category[i,"LinkName"], category[i,"Selector"], \
-##			category[i,"Host"], category[i,"Port"]);
-##	}
-
 	render_init();
 	render_categories(category, cnum);
 	render_post_categories(category, cnum);
 	render_links(category, cnum, link, lnum);
 	render_finalise(category, cnum, link, lnum);
-	##render_links(link, lnum, cfiles);
-	#for (k in cnames)
-	#	print k, cnames[k];
-	
+	dump_links(category, cnum, link, lnum);
 }
diff --git a/render.awk b/render.awk
index c528188..148a43e 100644
--- a/render.awk
+++ b/render.awk
@@ -30,7 +30,6 @@ function get_parents(a){
 	split(a, pars, /[:blank:]*,[:blank:]*/);
 	for (k in pars){
 		gsub(/ +/, "", pars[k]);
-		#printf("%d: %s\n", k, pars[k]);
 	}
 
 }
@@ -39,15 +38,13 @@ function category_in_parents(category, i){
 
 	get_parents(category[i,"Parent"]);
 	for (p in pars){
-		#printf("pars[%d]: %s\n", p,  pars[p]);
-		if (pars[p]!="none"){### this is the root page
+		if (pars[p]!="none"){### the root page does not have parents...
 			dst=cfiles[pars[p]];
 			if (has_categories[pars[p]] == ""){
 				info_line("", "Err", HOST, PORT, dst);
 				info_line("Sub-categories:", "Err", HOST, PORT, dst) ;
 			}
 			has_categories[pars[p]]=1;
-			##print "cfiles[pars[p]]:", cfiles[f];
 			show_category_link(category, i, dst);
 		}
 	}
@@ -81,13 +78,11 @@ function render_init(){
 function render_categories(category, cnum, link, lnum){
 	for (i=1; i<=cnum; i++){
 		cname=category[i,"Name"];
-		#print "'" cname "'";
 		cfiles[cname]=BASEDIR category[i,"Selector"];
 		"dirname " cfiles[cname] | getline bdir;
 		if (system("ls -d " bdir " >/dev/null") >0){
 			system("mkdir " bdir);
 		}
-		#print cname ":" cfiles[cname];
 		cmd=sprintf("rm -f %s", cfiles[cname]);
 		system(cmd);
 		category_header(category, i, cfiles[cname]);