Web Tools README File

$Id: README,v 1.7 2014/06/04 08:55:38 mark Exp $

INTRODUCTION

    Web tools is a set of tools to aid the publishing of simple web
    sites.  It consists of a set of GNU (gmake) make files, and a number
    of python scripts.  

    The tools are intended to be driven by a master GNU makefile,
    which sets key macros and includes make/main.mk.

    The make files assume there are three stages of web site
    production; a source tree, a staging (object) tree and a published
    tree.  The master makefile lives in the source tree.  The source
    tree also contains a directory with .html files and/or other
    supporting files (such as images), and a cgi-bin directory.  The
    location of these directories and files are specified by make
    variables.

    As source files are processed, they are inserted into a site page
    template, and copied into the staging tree.  This allows the files
    to be checked visually before the final publishing step.  The
    processing of source files also includes a check for valid HTML,
    performed by the chk_xml.py or chk_xhtml.py tool. CGI-BIN files
    are not copied to the staging area, but are copied, if necessary,
    direct to the publishing directory.

    File suffixes on HTML files are used to indicate the kind of XML
    syntax checking to be performed.  Those ending in .html are
    checked for well-formedness and conformance to the DTD.  Those
    ending in .htmx are only checked for well-formedness.

    The make process supports the ability to create a set of
    linked pages, using pagelink.py.

VALIDATION TOOLS    

    The python scripts in this release offer a dead link checker
    (dlc.py), a XML validator, based on libxml2 (chk_xml.py), and a
    simple XHTML validator (chk_xhtml.py).

    chk_xml.py will check an XML document for well-formedness and
    conformance to a DTD (if one is given).  chk_xhtml.py, based on
    the standard python xml.sax libraray, will only check for
    well-formedness.

    chk_xhtml.py relies on a catalog.py, which reads the local PUBLIC
    XML entity mappings to files.

    Instructions on running the python scripts can be found in the
    source.

MAKEFILE SUPPORT

    The following demonstrates an example of a master makefile:

        SYSTEM=${shell uname -s}
        SITE-ROOT=${PWD}
        WEB-TOOLS=${HOME}/web
        CHKXML-ARGS="-f ${HOME}/dtd/CATALOG"
        SRC := ${SITE-ROOT}/data
        OBJ := ${HOME}/public_html/hydrus
        CGI-BIN-DIR := ${SITE-ROOT}/cgi-bin
        LINK-DIRS := journal articles
        HTTPD-ROOT := /home/www/hydrus
        PUB-DIR := ${HTTPD-ROOT}/data
        # Master page template which is modified for OS by CONFIG-${SYSTEM} macros
        MASTER-TEMPLATE := master.template
        SYSTEM-TEMPLATE := system.template
        CONFIG-Linux="s/%IMAGE%/debian.jpg/;s/%ALT%/Debian Logo/;s/%URL%/http:\/\/www.debian.org/"
        CONFIG-FreeBSD="s/%IMAGE%/freebsd.jpg/;s/%ALT%/FreeBSD Logo/;s/%URL%/http:\/\/www.freebsd.org/"
        CREATE-ARGS="-t www.hydrus.org.uk"
        LINK-ARGS=-r
        include ${WEB-TOOLS}/make/main.mk

    The mandatory make variables are as follows:

    SITE-ROOT             Root directory of source tree
    SRC                   Location of html files and other material
    OBJ                   Location of staging area
    CGI-BIN-DIR           Location of any cgi-bin programs
    HTTPD-ROOT            Root directory of published tree
    PUB-DIR               Location of published html files

    The optional make variables are:

    MASTER-TEMPLATE       Name of master template, configured by 
                          CONFIG-${SYSTEM} macros (see example above)
    LINK-DIRS             List of directories (under SRC) which
                          contain html files for linking
    SYSTEM                Identifies target server (usually by OS)
    SYSTEM-TEMPLATE       Pathname of standard site template.
    WEB-TOOLS             Location of this set of web tools
    CHKXML-ARGS           Arguments to chk_xml.py/chk_xhtml.py
    CREATE-ARGS           Arguments passed to create-html.py tool
    LINK-ARGS             Arguments passed to pagelink.py tool

    If MASTER-TEMPLATE is set, then the SYSTEM-TEMPLATE is created by
    running sed with the commands defined in CONFIG-${SYSTEM}.  If
    MASTER-TEMPLATE is not set, then SYSTEM-TEMPLATE is expected to
    exist.  The SYSTEM-TEMPLATE is copied to PUB-DIR and may be used
    by cgi-bin programs when building html content.

ERRORS

    Should you encounter errors during use of these scripts, please
    email mark@hydrus.org.uk with relevant details.

LICENCE

    Copyright (C) 2014  Mark Willson

    These programs are free software; you can redistribute them and/or
    modify them under the terms of the GNU General Public License
    as published by the Free Software Foundation; either version 2
    of the License, or (at your option) any later version.

    These programs are distributed in the hope that they 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 this program; if not, write to the Free Software
    Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.

RELEASE HISTORY
    19th April, 2014            1.0     First public release
     9th May,   2014            1.1     Use pattern rules for templating and 
                                        XML checking
     4th June,  2014            1.2     Fix broken OBJ rule in compile.mk

