Web Author Guide

This is a quick guide to help local web authors write and maintain web pages that share the look and feel of the main top-level ("department-style") web pages - like this one.

    Overview
    The Basic Page
    Generating It
    Navigation
        The buttons File
        Adding and Removing Pages
    Links
    Special Tags and Features
        Some Very Useful WML Features
            #include's
            <protect>
            Automatic <img> Sizing
        Local System-Only Features
            Maintain
            Color Definitions
            Columns
            Indent
            Automatic Page Owner Link & Mtime

Overview

The department web pages are generated from source files written in Website Meta Language. These files are easily recognized by their .wml suffix. Website Meta Language is an HTML preprocessor which supports a wide array of programming language features designed to simplify web site design and management.

Html files can coexist with WML files, however HTML files will not be able to take advantage of the look & feel of these pages (at least, not easily). It is easy to author web pages in WML, the learning curve is very gradual - you can learn about and use its features as you need them.

A description of WML is beyond the scope of this page. The reader is referred to the WML web site (see especially the DOC section there) or the local man pages (start with wml(1)). It may also help to look at the .wml files scattered throughout the web heirarchy.

The Basic Page

Each department-style web page in the department web has a similar look. Each has a top and left border with text, graphics and navigation, and an author name at the bottom. This look is defined in the department web page template,

	/pro/web/web/include/csdept.wml

Each web page in the hierarchy includes this template with a line at the top like this:

	#include <csdept.wml>

All WML or HTML markup that appears after this line appears in the "main window" portion of the page. Note that there is no need for <html>, <head> or <body> tags, as the template takes care of these. All you need to worry about is the content of your page. That content need not make use of any WML constructs, in fact most pages will consist of straight HTML following the #include line.

Generating It

There is a Makefile in each directory of department-style web pages. Running make in any directory should process all the .wml files in that and all subdirectories, recursively. The Makefile simply runs the command wml(1) on each .wml file, to produce the corresponding .html file.

	% make
	wml -oai.html ai.wml
	wml -ographics.html graphics.wml
	wml -otheory.html theory.wml
	wml -osystems.html systems.wml
	wml -olabs.html labs.wml
	wml -ohome.html home.wml

Most files and directories in the main web heirarchy are owned and writable by group web. This is essential for all members of the staff to cooperatively work on the web. Staff members are encouraged to make sure that all files and directories remain group writable (and, of course, world readable). Other web authors should pay similar attention to file permissions.

Navigation

The department web pages are organized into a multi-level hierarchy. The topmost sections are listed on the navigation bar on the department home page.

The hierarchical structure of the web is generated from the directory structure of the underlying files. As each page is made, WML climbs the directory tree to the root of the web looking for files named "buttons". The contents of these files are interpreted and assembled into the navigation bar.

The `buttons` File

The buttons file is a simple text file containing comments and one entry per button. Here is a sample buttons file:

	# href          button text
	# ---------     -----------
	ai.html         "AI"
	graphics.html   "Graphics"
	labs.html       "Labs"
	projects/       "Projects"
	systems.html    "Systems"
	theory.html     "Theory"

The first item is the reference (href) to which the button will link. This can be a file or a directory. The navigation bar should only include links to on-site, department-style pages, so the href should never be a full url.

The second field is the actual text of the button. Fields can be double-quoted if they are empty or contain whitespace. A line with only empty values acts like a blank line.

Buttons appear in the order in which they are listed in this file. By convention, buttons are usually listed alphabetically (except for the dept home page).

Adding and Removing Pages

To add a new page:

Cd to the parent directory where your page will go
Create a new .wml file or directory (or copy an existing one)
- If you create a new directory, copy the files
  .wmlrc buttons Makefile
  from an existing web directory into your new one.
Edit the file "buttons" in the parent directory and add a row for the new topic

buttons files should have an entry for every page except home.html.

Edit the Makefile and add the new filename to PAGES (or the new directory name to SUBDIRS)
Run make

Remove a page by undoing these steps. Don't forget to run make.

Links

When creating links within .wml pages, you can link both relatively and absolutely as you would in a normal .html file. But there is an additional option which you should use in place of all absolute links outside your local web tree. Instead of this:

	<a href="/research/ai/learning.html">

you can instead use this:

	<a href="<get-var ROOT>/research/ai/learning.html">

These are exactly the same. The advantage of the latter notation is that it is self-adjusting. If the logical root of the web were to change, all such links would automatically adjust when the pages are re-made.

This feature can be used in web sub-hierarchies, too. For instance, all links within the technical staff's system web tree use the variable SYSTEM, as in:

	<a href="<get-var SYSTEM>/hardware/printers.html">

The SYSTEM variable is defined in the .wmlrc file located at the root of the system web. These variables can be defined at any point in the web, to make that sub-tree movable.

Images stored in the root-level images directory should also be referenced this way.

Special Tags and Features

There are a number of HTML-like tags and other features provided by WML and (locally) by csdept.wml that authors, who might not otherwise want to learn anything more about WML, may nonetheless want to take advantage of.

Some Very Useful WML Features

#include's

You may, at any point in your .wml file, insert a line like

	#include "myfile"

and the file myfile, in the current directory, will be inserted at that place, and its contents processed by WML.

<protect>

The <protect> tag (<protect>...</protect>) keeps WML from processing anything within it. Use this if something you type results in something you didn't expect, and you suspect that it is a WML command or construct. In the most extreme case, you can simply wrap your entire page in this, but I don't advise it.

Automatic <img> Sizing

WML automatically determines the size of every image it encounters and inserts the appropriate width, height and alt parameters. But it won't do this if you supply them yourself. You may want to provide an alt if you have something to say (the default is the empty string), but leave the image sizing to WML.

Local System-Only Features

The csdept.wml file provides a number of definitions and some tags that you may find useful.

Maintain

The meta-maintain feature of the web lets you embed markers in your web pages that cause email messages to be sent to you at predetermined times and circumstances, to remind you to update those pages. See the meta-maintain web page for a complete description of the syntax.

The <maintain> tag is just a shortcut for putting meta-maintain tags in your files. It works with the department template to ensure that the tags end up in the <head> portion of the final page.

	<maintain trigger="file+15" mail=billg>

The mail parameter is optional. The default is to send mail to the owner of the .wml file.

Color Definitions

WML files that include csdept.wml can and should refer to the following colors symbolically.

	page_bg		Page Background
	mast_bg		Masthead Background
	main_bg		Main Page Background
	left_bg		Left Navbar Background
	leftdrop_bg	Left Navbar Trim (Drop Shadow)
	trim_bg		Main Page Trim Color
	title_fg	Title Text Foreground
	text_fg		Text
	hitext_fg	Highlighted Text
	link_fg		Link
	vlink_fg	Visited Link
	alink_fg	Active Link
	hitexttrim_fg	Text on Top of Trim

[Don't use these yet - they need better names. - jsb]
To use a predefined color, use the meta-html construct

	<get-var page_bg>

Because this is evaluated as a preprocessing step, you can use it almost anywhere within your .wml files. It is most often used as the value of an attribute, like this

	<table bgcolor=<get-var mast_bg>>

Columns

In many places, it looks nicer to organize text in columns, particularly when providing the viewer with a number of brief textual selections. The <columns> tag makes this easy. Here is the syntax

	<columns number=3 [gap=3]>...<nextcol>...<nextcol>...</columns>

This creates three columns of text extending the full height of the area in which it appears. There is a 3% gap between each column. There must be exactly (number - 1) <nextcol> tags within the tag, or the results are undefined. Any WML or HTML markup may appear within this tag, including nested columns.

Indent

A page like this one scans more easily if sections are set off by indentation. The <indent> tag makes this easy. Here is the syntax

	<indent [level=2]>...</indent>

Indent simply moves everything within it over to the right by level increments. The default is 1. Indent tags may be nested.

Automatic Page Owner Link & Mtime

The page owner link at the bottom of the page is generated automatically based on the unix ownership of the .wml source file. The "Last Modified" time is the last modified time of the source file.

You may also force the page owner to be something else by setting the "author" parameter when including the department template.

	#include <csdept.wml> author="billg"

If the author name is a valid department logname, the full name from the password file is used as the text of the link.

Page Owner: John Bazik

Last Modified: Fri Feb 3 15:14:59 2006

Inside Search: