Schedulist User's Guide

Urpo Lankinen

This describes the basic file formats and the usage of Schedulist in most of the common situations.

Legal notice

This material may be distributed only subject to the terms and conditions set forth in the GNU Free Documentation License, v1.2 or later (the latest version is presently available at http://www.gnu.org/licenses/fdl.html).



Dedication

Dedicated to the fine folks in the University of Oulu Department of Information Processing Science administration, for their "gentle" inspiration to write a schedule program that allows schedules to be actually printed...

Table of Contents
1. Introduction
What is Schedulist?
Why Schedulist? How it came to current form?
2. Setting up
Automated installation
Automated installation with GNU Stow
The simple parser and the Perl modules
Website Meta Language files
Uninstallation
3. Table generation backends
HTMLList
HTMLTable
HTMLTableHoriz
4. Schedulist's file formats
The schedule XML source format
Simple template format
5. Usage of the simple template parser
6. Use of Schedulist with Website Meta Language
What is WML?
A simple example
7. How to get onward

Chapter 1. Introduction

What is Schedulist?

Schedulist is a program that is used to generate schedules in many different formats. It was made with HTML output in mind, but in principle, it is possible to use any kind of output.

Schedulist uses simple-to-understand XML files to describe the actual events in the schedule. The schedule in question needs only the Columns (in most schedules, the columns are named after days), and the Events that are in the Columns - with every event having their start hour and end hour.

Schedulist was written in Perl 5. It uses the Perl's packages as a means to implement an extensible output framework. The standard package includes a simple command-line tool that accepts simple templates and

Schedulist was written by Urpo Lankinen. It is distributed under the Artistic License - in short, you can do almost anything you want with it and you get the source code too (naturally, we are talking of Perl here!), but not anything totally outrageous...

Schedulist development is hosted by SourceForge. The official home page of the project is at http://schedulist.sourceforge.net/.


Why Schedulist? How it came to current form?

In 1999, I started my studies in the Department of Information Processing Science in University of Oulu, Finland.

I have to say that this place is a very nice place to study, but the Department's information spreading is not entirely the best of breed: The schedules they have on the web are made with Netscape Composer (last time I checked), and they don't print properly on portrait A4 - the friday and rest of the things on the edge never fit to the sheet, and I have not yet find a way to print it in landscape format.

Nor did I need: I decided that it would be much better if I had a schedule of my own in the web, and it could also be printed. Naturally, I didn't want to make an one-shot web page, but rather make a program specifically for this task.

Schedulist 1.0 was released in early 2000. It had just a couple of little problems in it: The HTML code was hard-coded to the program, and the code was absolutely hideous.

Schedulist 1.1 was started some time later, but it progressed very slowly - mostly due to the fact that the new structure was not the most easy to understand, and I had originally written the program so badly that I did not understand what I had done! I was too smart at coding but dumb on commenting, the end result was disastrous. Plus, Perl 5's reference handling is not really easy to understand, either - Perl 6 looked very nice in this respect, though. I have learned important lessons with this project.

Schedulist is now being hosted in SourceForge, but so far, there has been little interest in it from other people. I take that as a sign of the quality of the program, or most likely lack of thereof...

Schedulist has been, for me, the nicest example of a geeky solution for a management-created problem. No longer shall the schedules be a problem for me, but it took sweat and tears to get thus far.


Chapter 2. Setting up

Automated installation

In 1.1, Schedulist has an automated installer script. Basically, all you need to do is to run the script install.sh. Uncompress Schedulist distribution file, go to the directory and type sh ./install.sh. Basically, you don't need to give it any differing locations, because it assumes you are installing it to the /usr/local file hierarchy: The executable goes, by default, to /usr/local/bin/schedulist, the Perl libraries to /usr/local/lib/site_perl/, WML files to /usr/local/lib/wml/include/, and the templates to /usr/local/share/schedulist/.


Automated installation with GNU Stow

I recommend automated installation - combined with use of GNU Stow. This is due to the convinience of upgrading and uninstallation.

GNU Stow is a very handy program for installing and uninstalling "local" program packages.

Basically, all you need to do is to start installer as described before, and give /usr/local/stow/schedulist-1.1 (or others, depending on the release number) as the base directory - and install everything under it.

After this, type cd /usr/local/stow; stow schedulist-1.1 to complete the installation. The program should now be properly linked in the /usr/local hierarchy.

[FIXME: Doesn't work as advertised due to site_perl dir... =( ]


Uninstallation

There is no automated uninstallation. You need to remove the binary from the executable directory, the Perl libraries, the templates and the WML includes, if you installed them. All of these are stored in their own directories (except for the executable), which should not contain any other, conflicting binaries.

Stow'd version can be uninstalled easily: cd /usr/local/stow; stow -D schedulist-1.1; rm -rf schedulist-1.1 … that's it!


Chapter 3. Table generation backends

The workhorses of Schedulist are called table generation backends. Even though they are often used to generate tables, they don't necessarily need to. In fact, they don't need to even produce HTML. They can produce any kind of output.

The table generation backends are just pieces of code written in Perl, stored in Schedulist/TableGenerator/*.pm. At the moment, two used and proven table generators come with Schedulist.


HTMLList

HTMLList generates a simple nested HTML list, on first level the column names, on second level the events in columns. It is mostly intended for PDA / textual browser use.


HTMLTable

HTMLTable generates a complicated HTML table intended for graphical displays and possibly printing.

The generated HTML table is entirely defined in CSS classes, which means its outlook can be easily changed and it's more or less legible for browsers without CSS capabilities.

Title row and the hour column has CSS class "green", the cells with event have CSS class "action", and cells with nothing have no CSS class.

"Power use" of the class needs extensive knowledge of CSS language; for a good example of CSS definitions, see the example template!


HTMLTableHoriz

This backend remains extremely experimental - as of writing, it doesn't work. At all. In fact, I didn't even remember it existed; It may not be written at all! I guess I have to keep a better eye on what I write, it may come back haunting me one day...


Chapter 4. Schedulist's file formats


Simple template format

The template format Schedulist uses is just normal HTML. You can insert the page to any kind of HTML file with relatively little pain. An example of templates is provided with the program.

The substitution commands that the simple template parser knows are all closed in brackets, [likeThis]. Sometimes these may use arguments: [command:argument].

The following is a list of the commands currently known:

[form_title]

Add the title specified in the schedule file.

[doclang]

Add the document language specified in the schedule file.

[extrainfo]

Insert the information specified in the schedule file's optional <extrainfo> ... </extrainfo> section.

[release]

Insert the release number of the Schedulist simple template parser program (this rarely corresponds to the actual Schedulist package version).

[table:BackendModule]

Insert the contents of the schedule using the specified table generation backend. For example, [table:HTMLList] produces a list in HTML.

It should be noted that of these, only [table:BackendModule] is used actively in version 1.1. The rest are mostly of historical interest; 1.0 didn't support any templating. and that required that the information that was to be added to the page should have been included to the actual source file. These days, this information can be included to the template itself!


Chapter 5. Usage of the simple template parser

The template parser is designed to be very easy to use.

The program uses a simple template, described in the file format section. The program installs a simple default template to the template directory.

The program searches through some common file locations for this template:

The template parser accepts two options: -t templatename to specify the template location, and -o outputfile to specify the output file (if omitted, the result will be printed to standard output.

A simple usage example follows. This will use the template officialtemplate.html, read the events from 2002-period1.xml, and place output to /tmp/example.html.

$ schedulist -t officialtemplate.html -o /tmp/example.html 2002-period1.xml

Schedulist simple template parser 1.5, (c) 2000-2002 Weyfour WWWWolf

Successfully parsed input file: 2002-period1.xml
Template: officialtemplate.html

 *** Replaced: [table:HTMLTable]
 *** Replaced: [table:HTMLList]
$

     

Chapter 6. Use of Schedulist with Website Meta Language

What is WML?

Website META Language is...


Chapter 7. How to get onward

...