Read Me

Copyright 2002, 2003 Andrew Willard
Copyright 2002-2012 Barbara E. Irwin (beirwin@shaw.ca)

This file is part of the Loads of Linux Links (LoLL) package.

    LoLL is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License version 2 
    as published by the Free Software Foundation.
        
    LoLL is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with loll; if not, write to the Free Software
    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

1. Introduction

The Loads of Linux Links project was started several years ago as a service
for the Victoria Linux Users' Group (VLUG, http://vlug.org).  The purpose of
the LoLL project, which is licensed under the GPL, is to collect, organise and
maintain selected URLs about Linux and the Open Source movement.  The
current contributors to the project are Andrew Willard
(willychilly@users.sourceforge.net), past president of VLUG with extensive
experience with Linux hardware and software, Barbara E. Irwin
(beirwin@users.sourceforge.net), current publicity coordinator of VLUG with 30
years experience as a professional librarian, and, most importantly, users
of LoLL who use the provided forms to submit Linux-related URL's for
inclusion in the project.

The project has now grown to 4000+ classified links and is hosted
by SourceForge with the generated website
(http://loll.sourceforge.net/linux/links, the place to do your Linux
searching!); home page (http://loll.sourceforge.net/); and project page
(http://sourceforge.net/projects/loll).

If you are only interested in the 4000+ classified Linux links that are
generated by the LoLL software, stop reading here, and instead go to the
created website (http://loll.sourceforge.net/linux/links).  If you want to
give occasional help to the project by submitting URL's or changing existing
URL's, please use the forms provided at
http://loll.sourceforge.net/linux/links/submit.html or
http://loll.sourceforge.net/linux/links/change.html.

If you are keen to generate your own Linux Links page (under the
GPL license, of course, since LoLL is GPLed) or give larger scale help to
the LoLL project, read on.

2. Overview of how the results site is generated

The key source file for LoLL is bookmarks.html, which is a netscape-style
bookmarks file maintained with mozilla (version 1.0.0 as of this writing).
The programme bk2site (http://bk2site.sourceforge.net) is used to convert
this bookmarks source file into the generated web site,
http://loll.sourceforge.net/linux/links.  Note that bookmark file comments;
5 configuration files; and 4 perl scripts are used for informing bk2site
about how the resulting website should be organized.  (We also maintain a
separate set of bk2site configuration files which allows us to generate a
special form of the website for VLUG use which is available at
http://vlug.org/linux/links.) 

Note the LoLL developers typically make changes to bookmarks.html that are
cvs committed every day so if you obtained that file from a tarball file
release it is almost certainly quite out of date already.  Therefore, we
strongly suggest that you periodically use cvs update (see
http://sourceforge.net/cvs/?group_id=42381 or
http://sourceforge.net/projects/loll --> CVS Repository for instructions on
obtaining anonymous CVS access to our project) to keep the bookmarks.html
file up to date.

3. Why not use an XBEL-compatible browser to maintain a LoLL bookmarks file in
XBEL format?

In the future we plan to use the much more readable and easy-to-parse XBEL
(XML Bookmark Exchange Language, http://pyxml.sourceforge.net/topics/xbel/)
format for the bookmarks file. This could then be maintained by non-mozilla
browsers such as konqueror or grail which use the XBEL format for their
browsers.  The results could be converted to the required (by bk2site)
netscape-style bookmarks using the xbel2html conversion tool.  However,
although the XBEL format supports comments which are an essential part of
configuration used by bk2site to generate the results site, comments are
currently ignored by konqueror so this idea will have to wait until
konqueror supports bookmark comments.

4. Annotated list of files/directories in the LoLL package

bk2site_config_sf/* -- bk2site configuration files for generating sf_results

bk2site_config_vlug/* -- bk2site configuration files for generating
vlug_results

bk2site_prepare.sed -- sed script for filtering mozilla-style bookmarks file
to netscape-4.7 form which bk2site can understand.

bk2site_scripts_sf/* -- bk2site and FormMail perl scripts (with some 
configurable data) for generating sf_results.

bk2site_scripts_vlug/* -- bk2site and FormMail perl scripts (with some 
configurable data) for generating vlug_results.

bookmarks.html -- mozilla (1.0.0) style bookmarks file.

COPYING -- text of GPL version 2, the license for LoLL.

generate_sf_loll.sh -- script for generating the sf_results directory tree.

generate_vlug_loll.sh -- script for generating the vlug_results directory
tree.

Makefile -- used to organize generation of sf_results and vlug_results.

README -- this file.

CHANGES -- Overview of the changes made for each release.

ChangeLog -- More detailed list of changes but not as extensive as changes
documented in commits and accessible using the "cvs log" command.

www/index.html -- home page for the loll software package.

www/CHANGES.html -- htmlized version of CHANGES.

www/announcement-1.1.0.html - announcement of the 1.1.0 release.

classification_hierarchy -- the software in this directory is used to obtain
a nicely formatted output of the hierarchy of almost 200 categories used in
the LoLL project.  This output is useful for helping to make decisions about
changes to the names or organization of the categories.  This software in
this directory also allows the user to obtain a listing of all LoLL URL
titles and annotations which can be spell checked.

5. Generation of the sf_results and vlug_results directory trees.

The above files in the LoLL package are used to create local directory trees
(sf_results and vlug_results) which in turn can be uploaded to either the
SourceForge results site (http://loll.sourceforge.net/linux/links) or the
VLUG results site (http://vlug.org/linux/links).  Thus, the generation of
sf_results and vlug_results is mostly for our own internal LoLL use in
creating our results sites, but this generation process (for either results
site) is also a good working example which can be modified for your own
needs.

N.B. If you distribute a site using original or modified forms of our
software or data, you should be aware that they are protected by the GPL.
That means you must give a link to the source of your website
(bookmarks.html and the bk2site scripts you are using to generate your
website from these data).

If you care to generate sf_results and vlug_results as a test simply execute

make

in the directory containing this README.  The whole process should only take
a few seconds on a modern PC.  You will need to supply (or fake with the
"touch" command) your own icons in both sf_loll_icons and vlug_loll_icons.
These icons are used to distinguish the list of the various Linux news
sources and the host organization on the results home page.  In addition to
these icons, the generation process also uses the standard bk2site icons
which are automatically copied from the local bk2site installation.

Barbara E. Irwin (beirwin@users.sourceforge.net)