Web Authoring 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
buttonsFile 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
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.
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,
Each web page in the hierarchy includes this template with a line at the top like this:
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
<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
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.
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 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).
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
- If you create a new directory, copy the files
- Edit the file "buttons" in the parent directory and add a row for the new topic
buttonsfiles should have an entry for every page except
- 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.
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:
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
.wmlrcfile 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
imagesdirectory should also be referenced this way.
There are a number of HTML-like tags and other features provided by WML and (locally) by
csdept.wmlthat authors, who might not otherwise want to learn anything more about WML, may nonetheless want to take advantage of.
You may, at any point in your .wml file, insert a line like
and the file
myfile, in the current directory, will be inserted at that place, and its contents processed by WML.
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.
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.
csdept.wmlfile provides a number of definitions and some tags that you may find useful.
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.
<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.
WML files that include
csdept.wmlcan 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
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>>
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 (
<nextcol>tags within the tag, or the results are undefined. Any WML or HTML markup may appear within this tag, including nested columns.
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 simply moves everything within it over to the right by
levelincrements. The default is 1. Indent tags may be nested.
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.