Members of the BaBar Collaboration who are considering writing new tutorials are encouraged to join in this Workbook project rather than go it alone. When you integrate your tutorial into the Workbook, you get to just teach the material for which you are the expert. All of the background material is taught by others.

Contributions to the Workbook are very welcome. But because we have very limited resources for technical editing, we must ask that you observe the following guidelines.

What the Workbook Is and Isn't

Before you write anything, please be sure you understand the intended scope of the Workbook. Start by rereading the introductory sections:

Keep the User Moving Along

Understand that the workbook is meant to quickly introduce users to BaBar tools. It should contain brief explanations and be full of simple examples, but it should not be a detailed help manual. Rather, it should present a link to the detailed help manual (or any other background reading) and should then move on quickly to the next topic.

Keep the Examples as Simple and Uncluttered as possible

Each section of the Workbook can take as already known anything that is discussed in earlier sections (even if that previous section is currently just an outline). The idea is to keep the user moving along. They have many other tools to learn.

Show the Expected Output

For each command you have the user enter, show them the expected output (as is done in the Workbook section Quick Tour). This is the only way the user will be able to tell the difference between unimportant warning messages and real problems. This is especially useful for software that gives lots of confusing warning messages that the user is supposed to ignore (currently the case for most BaBar offline software). Screen shots may also be useful (GIF images please).

We would eventually like to have a output automatically pasted back into the Workbook after nightly tests (but this has yet to be done).

Contributors should provide examples that work, but should not be surprised if the editors then change the examples. Examples will gradually be rewritten to have them build on one another.

Use Simple Language

Keep in mind that many readers are not native english speakers.
Avoid the use of puns or of elaborate jokes. While these may amuse the native english speaker, they cause other readers to waste time consulting their dictionaries when they would rather be learning BaBar concepts.

Use of Existing Outlines

Try to follow the existing outline as closely as is reasonable. A significant amount of thought has already been given to the order of introduction of concepts and commands. But do go ahead and add more concepts and commands. And do trust your own judgment if you believe the existing order is not best.

Each Workbook section contains a list of related documents. In a completed Workbook section, this list should contain the resources that treat the topic in greater depth. In a section of the Workbook that is only an outline, this list of related documents is also meant to be used as source material for the writer. Feel free to take material from these sources as you flesh out the Workbook section. Some of these references will no longer be necessary once the actual Workbook section is complete.

SLAC Versus Other Sites

Because SLAC is the only site that guarantees computing resources to every BaBar collaborator, the Workbook must give instructions that work at SLAC. But it is also important for the Workbook to include appropriate hints for users at other sites. Users at other sites are therefore encouraged to send in contributions about how to run at their sites.

If a particular site provides many detailed instructions, a graphic will be established to serve as a standard flag for that site's instructions.

For example, where the Workbook discusses the BaBar Release Structure in the section SRT: the Software Release Tools, the section ends with the flags:

RAL Special for RAL: Releases

LBL Special for LBL: Releases

HTML Conventions

Initially, the Workbook is being developed in simple HTML. Contributors may submit their work in either HTML or plain text. We ask that contributors keep their formatting simple so that we can maintain a uniform style to the document.

Keeping the formatting simple also makes it possible for us to later convert the Workbook project to latex, the format recommended by the BaBar Documentation, Communication and Information Task Force (that conversion has been delayed while we work around latex2html's ugly url structure).

Some html writing tools such as MicroSoft Word and NetScape Composer create very messy HTML code. This code tends to contain amounts of unnecessary formatting information (fonts, colors, etc.). Please do not submit contributions that contain this kind of unnecessary formatting.

Please use the following conventions:

Use EM for first introduction of new terms
Use CODE for commands and file names that are imbedded in the main text
Use quotation marks for system responses that are imbedded in the main text
Use PRE and then indent three spaces for commands, file names, and system responses that are to be set off from the main text (the tag CODE is then not needed)
Use Angle brackets, <>, around variables (these are formed in HTML by < and >) - this is to avoid problems with html tags which are identified with angled brackets.
Use Square brackets, [], around optional arguments
Use a vertical bar, |, to separate options

The last three points above match the form used by Unix man pages.

In preformatted blocks of text that the user should type in, show the Unix prompt as

If it is important that the user remember which directory they should be in when they enter a particular command, show the relevant part of the directory structure in the prompt, as in:

   ana26/workdir>

Here is an example showing all of the above rules:

Issue the following two commands to create a new release directory for your work. This directory will be called ana26. Your will build the rest of your job in this release directory. This directory will in turn contain links to the scratch area that you created in Logging In:
```
   > setenv MYWORK /nfs/farm/babar/work/${USER}
   > newrel -s $MYWORK -t analysis-26 ana26
```
The system should respond:
```
   /nfs/farm/babar/work/<CR> is on NFS disk, leave tmp in test release
   next, add pkg, checkout or ln -s to your packages, then gmake installdirs
```
If you instead get an error message that includes "not a block device, directory or mounted resource" then go back to Logging In and create the scratch space as recommended there.
The more general form of the newrel command is:
```
   > newrel [-t|-p|-a|-f|-F|-v|-l|-m|-s dir] <base release> [<new release>]
```

Only the following other tags should be used:

HTML, HEAD, TITLE, BODY
H1, H2, H3
UL, OL, LI
P, BR, HR
STRONG to make something stand out boldly (don't use this too often)
EM to emphasise text
PRE to display preformatted text
CODE to display code in true-type font
TABLE, BORDER, TR, TH, TD, ALIGN, SUMMARY
A, HREF, NAME
IMG, SRC (use ALT in images for when the browser can't display the image)
ADDRESS to indicate author of the page

You are welcome to divide your work into multiple pages, but please store them in a flat file structure (that is, no subdirectories).

Screen shots or other image files are also welcome.

BaBar has a number of images, such as pictures of the infamous elephant and other useful icons in the /BFROOT/www/Images/ directory.

Use relative URLs

Relative URLs are used within the Workbook, rather than absolute pathnames, to allow copies of the Workbook to be easily taken elsewhere.

URLs should be relative when moving around the Workbook space. For example, to go from ...workbook/editing/editing.html to workbook/clr/clr.html, use ../clr/clr.html.

URLs for moving outside the workbook should be absolute, although to work within the BaBar webspace, links should start with /BFROOT, to enable users based at RAL to access the RAL mirror pages of the SLAC site.

Editing html files with Microsoft products

The BaBar workbook files, like most BaBar web pages, contain a header and sidebar with useful links. However, many Microsoft product, such as Microsoft Frontpage tend to corrupt the code in the BaBar headers.

If you use a Microsoft product to edit BaBar html pages, you can avoid this problem by unwrapping the page (which removes the banner and sidebar), then editing with the Microsoft product, then rewrapping the page to restore the banner and sidebar.

The correct sequence is:

WEBwrap -rh somefile.html
Copy the file to windows; edit there; copy it back to unix
WEBwrap -ah somefile.html

where the options -rh and -ah mean "remove" and "add" header respectively.

You will need to enter "Yes" to WEBwrap's confirmation prompt. The WEBwrap script is in $BFROOT/bin; it should be in the PATH for all BaBar unix accounts.

If you edit directly on unix, using emacs or some other editor, it is not necessary to unwrap and re-wrap, although it will work ok if you do, and it removes distracting html code while you're editing the file.

How to Submit Contributions

Contributions following the above guidelines should be sent to Jenny Williams. If the file has been placed into a publicly available web space, you can also just send the location of the file.

Back to Workbook Front Page

Author:
Joseph Perl
Last edited by:
Jenny Williams

Last modification: 13 June 2005
Last significant update: 6 October 1999