SLAC PEP-II
BABAR
SLAC<->RAL
Babar logo
Workbook HEPIC Databases PDG HEP preprints
Organization Detector Computing Physics Documentation
Personnel Glossary Sitemap Search Hypernews
Unwrap page!
Wkbk. Search
Wkbk. Sitemap
Introduction
Non SLAC
HOWTO's
Introduction
Logging In
QuickTour
Detector
Info Resources
Software Infrastructure
CM2 Introduction
Unix
OO
SRT
Objectivity
Event Store
Framework
Beta
Modifying Code
Writing and Editing
Compiling
Debugging
Analysis
Framework II
Analysis
Find Data
Batch Processing
PAW
PAW II
ROOT I
ROOT II
ROOT III
Advanced Infrastructure
New Releases
Workdir
Main Packages
Event Displays
Gen/Sim/Reco
Contributing Software
SRT and CVS
Coding
Advanced Topics
Make CM2 Ntuples
New Packages
New Packages 2
Persistent Classes
Java
Site Installation
Check this page for HTML 4.01 Transitional compliance with the
W3C Validator
(More checks...)

WorkBook Maintenance - a Guide for WorkBook Editors

Introduction

This page is intended to provide guidance to BaBar members who will be making major changes to the BaBar WorkBook. This is usually the domain of the workbook editor, but occasionally includes other users.

workbook.html and workbook_sitemap.html

To navigate around the BaBar Offline Workbook, there is a title page and a sitemap which contain contain links to the major headers in each workbook chapter.

It is the task of the workbook editor or other user making significant changes to the workbook to ensure that both the main workbook page, workbook.html, and the workbook sitemap, workbook_sitemap.html contain accurate links to each of the major headers in each workbook chapter. While this can be a chore, it maintains a professional feel the workbook, is minimal effort if regularly maintained, and provides a useful service for the users of the workbook.

The sitemap contains only brief summaries of the section headings in the workbook chapters in order to maximise the amount of information in in the tight sitemap space.

Wrapping and the Workbook Header

As well as the main and sitemap pages, the workbook sidebar must be kept up to date. This is a facility provided by the BaBar web, and the Babar webmaster, Ray Cowan, should be consulted in the event of problems or questions.

The sidebar and header are maintained in the directory:
$BFROOT/www/.wit_root/Headers/www/Workbook/

The relevant file is header.inc. Warning: editing this file affects the entire workbook.

From time to time the BaBar webmaster "wraps" the entire BaBar web, including the workbook. The effect of this is put a copy of the header.inc file from the location above into $BFROOT/www/doc/workbook and each of its subdirectories, overwriting all incidences of header.inc in those directories, and then apply a script which places text from that header.inc file into the relevant places of each html file.

Edits to the header.inc file should be entirely restricted to changing the contents and order of entries in the sidebar to match that used in the workbook main page and in the sitemap. Before any changes are made to the header.inc file a backup must be made to ensure errors can be undone immediately.

no wrap

This facility should be used very sparingly as most web pages should be wrapped to maintain the overall "feel" of the BaBar web. However, as in the case of the workbook sitemap it is appropriate to prevent the occasional page from wrapping. To do this, one should add the line:
<!-- :WIT:NoWrap: -->
At the very top of the file.

Tools

There are some tools for webwrapping stored in the directory $BFROOT/www/doc/workbook/wraptools. These are
unwrapone          workbookorigcleanforced  workbooktildecleanforced
workbookorigclean  workbooktildeclean       wrapone
The workbookclean scripts are for removing emacs backups, either with the user being prompted at each file, or by forcing deletion of the tilde files (be very careful when using these files).

It is easier to edit BaBar web pages without all the html code associated with the header and sidebars in the way. The extra information can be stripped away by calling the unwrapone script with the filename. When the editing is finished, the web page should be rewrapped with wrapone, and the page should be checked to ensure that it has rewrapped.

Basic Hygiene

Validation

The BaBar sidebar contains, at the bottom, a link to an html validator. This should be used to ensure that the page contains valid html code so that the page will have a consistent look on most web browsers, and also so that when the workbook is rewrapped the procedure is successful.

There is also a command-line validator which is used by the web-wrapping script before it changes a web page. This validator is called testhtml. It can be used simply by changing into the directory and running

testhtml mywebpage.html
This process must run without any errors (warnings are ok, but should be dealt with for tidiness) before that page will wrap. Particular care should be taken to the output from a workbook wrapping command as any pages failing the testhtml script will not be freshly wrapped.

Page meta information

Two pieces of information should be included in every BaBar workbook web page. First, the top line of the file should contain the html version information
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
A character set should also be declared within the head tags of the web page, generally placed directly above the "<title>"..."</title>" information. The code to be placed here is
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
Both lines of information help the html validators to know what to expect in the web page.

Colours

Since many people have some degree of colour-blindness or other visual limitations, care should be taken to avoid using coloured text which might be difficult to read. Reds and greeens are particularly to be avoided whereever convenient.

Basic colours should also be used to ensure that the look and feel on different browsers remains the same, as many colours do render differently on different browsers.

Symbols and quots

Often when quoting output from BaBar commands and snippets of code, one obtains output such as
<BtaCandidate>
This output needs to be modified to have all "less-than" signs replaced with "&lt;" and the greater-than signs similarly replaced. Otherwise validators will complain as the terms in brackets look like html commands. Similarly, instead of using quotes around terms, it is best to use &quot;.

Using relative links

Because the workbook is designed to be mirrored at RAL, links starting with the "/BFROOT/.. " should be used for pages within the BaBar web. Within the workbook, relative links such as "../quicktour/quicktour.html" to get to the quicktour from another workbook chapter should be used.

The Workbook Search Engine

The Workbook Search Engine works pretty effectively, and is a useful tool for the workbook editor as well as for users.

Back to Workbook Front Page

Author: Jenny Williams

Last modification: 22 June 2005
Last significant update: 22 June 2005 (page created)