WorkBook Maintenance - a Guide for WorkBook Editors
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:
The relevant file is
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.
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.
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.
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
testhtml. It can be used simply by changing into
the directory and running
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.
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
This output needs to be modified to have all "less-than" signs
replaced with "<" 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 ".
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.
Last modification: 22 June 2005
Last significant update: 22 June 2005 (page created)