Last update:
Sun Dec 30 11:39:41 CET 2001

This directory contains a simple and lightweight database system
for LinuxFocus. 

Gerneral 
========
The principe is that all files can be compiled from
a single XML file (xmldb_en.xml). This master database
file is maintained and checked manually. Normally this means
just that you copy new entries from resdb_newarticles.xml
to xmldb_en.xml and then execute xmlupdateall_sh
to compile all files.

To maintain the database you need:
- perl
- nsgmls (http://www.jclark.com/sp/nsgmls.htm) for xml validation
- Sablotron (http://www.gingerall.com/) as a XSLT processor

You can query this database system via
http://cgi.linuxfocus.org/cgi-bin/qdb

New article numbers can be allocated via
http://cgi.linuxfocus.org/getticket
getticket will write to resdb_newarticles.xml

The architecture
================
The master files for this database system are xml files.
However xml is only good to transform xml into another document
without changing much the structure. It becomes very slow and
inefficent if you need to do more complex changes.

The system consists therefore of structured text files that
can be read very efficently with perl.
It's a 2 layer system. XML as a master file for easy maintenance
and perl parsible text files which are really used
by the various programs such as (lfthemes, lftaklback, getticket, qdb...)

The files in are:

downloaddb -- a script to download the latest db files from
              linuxfocus.org to the current directory
xmldb_en.xml -- the master DB file. 
resdb_newarticles.xml -- new articles allocated via
               getticket are written into this file. You need
               to check the entries and copy them over to xmldb_en.xml
resdb.txt -- all articles allocated via getticket are as well listed here
             Do not manually change this file it is updated by 
             getticket.

The generated files are:
textdb.txt -- all articles with title, abstract etc....
textdb_person.txt -- all authors
issuedb.txt -- issue numbers
talkback.txt -- used by lftalkback

Scripts and other files:
maindb.txt -- the old DB system file (before XML was introduced), no longer
              used.
linkus.txt -- Hist here the current article numbers. This will then
              periodically be used to automatically update 
              http://linuxfocus.org/common/linkus/
renumber.txt -- end of 2000 the old articles where renumbered to
              get new numbers which are unique. This file explains
              what was done.
              
olddb2xml -- script, transforms the old maindb.txt file into xmldb_en.xml
qdb_sh -- shell script to query the linuxfocus db (you need to be
          online to use this).
querydb_pl -- a perl script to query the linuxfocus db

The scripts to update the low level text files, the
stylesheets and xml helper files are:
textdb2issue_pl
textdb_person.txt
textdb_person.xslt
talkback.xslt
textdb.txt
textdb.xslt
validate_sh
xhtml-lat1.ent
xml2talkback_sh
xml2textdb_person_sh
xml2textdb_sh
xmldb.dtd
xml.dcl
xmlupdateall_sh

Regular maintenance
===================
Every second month (when a new issue comes out). The main editor
has to move the entries from resdb_newarticles.xml to xmldb_en.xml and
check them. Change the <issueref href="none"/> to the directory name of the
new issue and add a new issue entry under <issues>.
Next run the program xmlupdateall_sh and upload the files:
common/db/issuedb.txt
common/db/resdb_newarticles.xml
common/db/talkback.txt
common/db/textdb.txt
common/db/textdb_person.txt
common/db/xmldb_en.xml

The file linkus.txt (which is as such not related to the DB system but
used for the http://linuxfocus.org/common/linkus/ pages) needs to be
updated with the new articles of the current issue.

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