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.