Name

Table of contents

Name
Purpose
Process
Directories and Files
Warning
Files
Cascading Style Sheets
Logos
Heading Pix
generate-background.pl
generate-page-headings.pl
web-site.pl and SAX2HTML.pm
Acronyms
Colors
References
Author
Licence

Name

Web Site Elements - A description of the programs and files making up this web site.

Purpose

This document describes the elements which combine to automate the construction of a web site.

Process

Put simply, these steps are undertaken:

A web site is designed
Images are created, eg for logos and page backgrounds
A file, web-site.xml, is created which contains the design and content of the site
A program, web-site.pl, is run which converts web-site.xml into a set of web pages

Directories and Files

We assume the web site is stored in some sub-directory of a hard disk.

All directory and file references are with respect to that sub-directory, and that sub-directory is called 'the current directory', and is written as './'.

Hence a file within the current directory is written as './index.html'.

Sub-directories within the current directory are written as './css/' and './Pages/'.

Hence a file within a sub-directory is written as './Pages/web-site.xml'.

A set of files is referred to by '*'.

Hence all HTML files in the current directory './' are referred to by './*.html'.

Warning

Unix and Microsoft Windows Operating Systems have differing conventions about what is and what is not a valid file name.

This matters because you most likely develop your web site under Windows, and then upload it to your web host, which is most likely to be running a version of Unix.

You are strongly advised to observe these recommendations:

Do not use spaces in file names
Be absolutely consistent about upper and lower case letters in file names

Files

The web site consists of:

A set of Perl programs
./Pages/generate-backgound.pl
./Pages/generate-page-headings.pl
./Pages/web-site.pl and SAX2HTML.pm
A set of data files
./Pages/web-site.xml

This is the core file. It contains almost all the text of the web site, the definitions of the pages, and the names and locations of the images.

This file is read by the Perl program ./Pages/web-site.pl.

./Pages/privacy.pod

This contains the text of ./privacy.html. A program converts this file into ./privacy.html.

A set of font files
./Pages/hum531k.ttf and hum777b.ttf

These font files are from the Humanist family. There are hundreds of megabytes of font files available.

The b suffix indicate a Bold font.

The ttf extension indicates a True Type Font file.

These fonts, or others, can be used in the generation of the Heading Pix.

These files are read by the Perl program ./Pages/generate-page-headings.pl.

A set of images
./assets/images/background-*.gif

These are created by the Perl program ./Pages/generate-background.pl.

Background images do not have to be *.gif files.

./assets/images/i-love-png.png, smile.gif

These are demo Logos.

./assets/images/Home.png and Services.png

These are created by the program ./Pages/generate-page-headings.pl.

A Cascading Style Sheet
./css/default.css
A set of web pages
./index.html and Services.html

These are created by the Perl program ./Pages/web-site.pl.

./Pages/color.html

This is a color reference chart.

./privacy.html

This is created by a program, from ./Pages/privacy.pod.

By convention, the home page of a web site is almost invariably in the file ./index.html, not ./Home.html, but is called 'The home page'.

Hence the home page, in the <page> element in web-site.xml, has the name attribute set to 'index', which means ./Pages/web-site.pl outputs a file called ./index.html, but it also has the toc attribute set to 'Home', so that the global Table of Contents refers to this page as 'Home'.

See line 44 in ./Pages/web-site.xml.

Cascading Style Sheets

Web page content is formatted by associating specific content with specific formatting instructions. The web page content is in ./*.html, of course. The formatting instructions are in ./css/default.css.

See line 6 of ./index.html.

What's good about CSS is that you can edit ./css/defaults.css and just hit the 'Refresh' button on your browser, to get your new CSS definitions to be used.

Some samples of these associations follow:

Global Table of Contents

This is the box down the left hand side of every page, labelled Pages.

See line 80 of ./Pages/web-site.pl.

This text is formatted by the .global_toc_heading property in the CSS file ./css/default.css.

See lines 9 to 15 of ./css/default.css.

The border on the box is created by the $border option of sub make_global_toc in ./Pages/web-site.pl.

See lines 74, 83 and 250 of ./Pages/web-site.pl.

Each entry can be clicked to take you to another page.

The entries are specified by the 'toc' attribute of a <page> element in ./Pages/web-site.xml.

See lines 44 and 76 of ./Pages/web-site.xml.

The order of these, down the page, is specified by the 'order' attribute of a <page> element in web-site.xml.

See lines 44 and 76 of ./Pages/web-site.xml.

Entries are formatted by the .global_toc_text property in the CSS file ./css/default.css.

See lines 17 to 23 of ./css/default.css.

Page Heading Text

This is text which appears are the top of each page, just under the Heading Pix (if present).

The Page Heading Text is specified by the <heading> element in ./Pages/web-site.xml.

See lines 48 and 80 of ./Pages/web-site.xml.

The Page Heading Text is formatted by the .page_heading property in ./css/default.css.

See lines 77 to 85 of ./css/default.css.

Visual breaks

These horizontal bars which appear at the end of each section in ./index.html, etc, are formatted with the h5 property in ./css/default.css.

./Pages/web-site.pl outputs a single '*' for each visual break, and the CSS does the rest.

Visual breaks are formatted by the h5 property in ./css/default.css.

See lines 25 to 33 in ./css/default.css.

Headings for Local Table of Contents

These are the lines saying 'Table of Contents' at the top of those pages which have their own table of contents.

They are formatted with the .local_toc_heading property in ./css/default.css.

See lines 53 to 59 in ./css/default.css.

Line items for Local Table of Contents

These are the entries in the Table of Contents' at the top of those pages which have their own table of contents.

The entries are specified by the 'toc_id' attribute of a <publication> element in ./Pages/web-site.xml.

See lines 88, 94, 100 and 106 of ./Pages/web-site.xml.

They are formatted with the .local_toc_text property in ./css/default.css.

See lines 69 to 75 in ./css/default.css.

Headlines

These are the maroon lines such as 'News flash: 4-Dec-2001' on ./index.html.

They are formatted with the .headline property in ./css/default.css.

See line 58 in ./web-site.xml and lines 35 to 42 in ./css/default.css.

Common-or-garden text

Such text is formatted with the .local_text property in ./css/default.css.

See line 60 in web-site.xml and lines 44 to 51 in ./css/default.css.

Also, such text is formatted with the .content property in ./css/defaults.css.

See lines 4 to 7 of ./css/default.css.

Logos

This is the small image at the top left of each page.

The Logo is optional
The Logo can be the same or different on every page
The Logo is any image you find or create
The Logo is specified by the 'logo' attribute of a <page> element in ./Pages/web-site.xml

See lines 44 and 76 of ./Pages/web-site.xml.

Heading Pix

This is the large image at the top center of each page.

The Heading Pix is optional
The Heading Pix can be the same or different on every page

However, it makes sense for them to be all different.

The Heading Pix is any image you find or create

The Heading Pix supplied are created by the program ./Pages/generate-page-headings.pl.

The Heading Pix is specified by the <heading_pix> element in ./Pages/web-site.xml

See lines 50 and 82 of ./Pages/web-site.xml.

generate-background.pl

This program is used to create sample page background images.

It is in the ./Pages directory.

generate-page-headings.pl

This program is used to create sample Heading Pix.

It is in the ./Pages directory.

The names of the page headings are specified by the 'name' attribute of a <page> element in ./Pages/web-site.xml.

See lines 44 and 76 of ./Pages/web-site.xml.

The names are extracted when ./Pages/web-site.pl is run, and are written to the file ./Pages/page-names.txt. It is this latter file which is read by ./Pages/generate-page-headings.pl and used to create ./assets/images/Home.png etc.

Note: The page name 'index' is converted to 'Home' by the program ./Pages/generate-page-headings.pl.

web-site.pl and SAX2HTML.pm

These are in the ./Pages directory.

These are used to convert ./Pages/web-site.xml into ./*.html.

The pages generated are each specified by a <page> element in ./Pages/web-site.xml.

The name of the file output is specified by the 'name' attribute of the <page> element.

See lines 44 and 76 of ./Pages/web-site.xml.

Acronyms

These acronyms are often used as file name extensions.

CSS - Cascading Style Sheet
DAT - Data
GIF - Graphics Interchange Format
HTML - Hyper Text Markup Language
PL - A Perl program
PM - A Perl module
PNG - Portable Network Graphics
POD - Plain Old Documentation
TTF - True Type Font
TXT - Text
URI - Uniform Resource Indicator
URL - Uniform Resource Locator
XHTML - An XML version of HTML
XML - Extensible Markup Language

Colors

Colors can be specified by name or by a '#' followed by 6 hexadecimal digits.

The 6 hex digits are 2 for Red, 2 for Green and 2 for Blue, in that order.

Hex digits are 0 .. 9 as for decimal, plus a (hex) = 10 (decimal), b = 11, c = 12, d = 13, e = 14 and f = 15.

Upper or lower case for a .. f are both ok.

Thus Red values run from 00 .. ff, with the same range for Green and Blue.

00 means no color and ff means full color. So 80 is half way along the scale.

#000000 is Black
#6495ed is CornFlowerBlue
#abcdef means Red is ab, Green is cd and Blue is ef
#ffffff is White

See color.html for more details (this page is documentation from the package ImageMagick).

References

CSS

http://www.projectcool.com/developer/reference/css_style.html

http://www.builder.com/Authoring/CSS/table.html

HTML

http://www.htmlhelp.org/reference/wilbur/

http://werbach.com/barebones/

XML

http://www.ucc.ie/xml/

http://www.w3schools.com/xml/

Author

Ron Savage .

Home page: http://savage.net.au/index.html

Version: 1.01 01-Jun-2006

This version disguises my email address.

Version: 1.00 18-Feb-2002

Original version.

Licence

Australian Copyright © 2002 Ron Savage. All rights reserved.

        All Programs of mine are 'OSI Certified Open Source Software';
        you can redistribute them and/or modify them under the terms of
        The Artistic License, a copy of which is available at:
        http://www.opensource.org/licenses/index.html