Instructions for Contributors to the LCG Application Area Workbook

Introduction

The source of the workbook is kept in the form of html files in the CVS repositories of the different LCG Application Area projects in modules called workbook. The project-independent parts of the workbook are kept in the SPI CVS repository. Workbook sections on for example POOL are kept in the POOL CVS repository, and similarly for all other LCG Application Area projects.

Each workbook page includes a common header and footer via server-side includes. When you start a new page, please start from the template page provided in the directory shared/template.html of the workbook and do not modify anything above or below the comment lines indicating the end of the header and start of the footer, respectively.

Since different releases of LCG Application Area software will likely require different versions of the workbook, the structure of the workbook is designed to allow several versions to be simultaneously available. The complete workbook consists of one or more versions of the workbook for each project, arranged in the following structure on the web server:

index.html
  |
  |-- shared                                  // Shared files: header, footer, images, ...
  |
  |-- general/current --> general-x-y-z       // link to the current version of general workbook material
  |           general-x-y-z                   // version x-y-z of general workbook material
  |
  |-- pool/current --> pool-x-y-z             // link to the current version of pool workbook
  |        pool-x-y-z                         // version x-y-z of pool workbook
  |        pool-a-b-c                         // version a-b-c of pool workbook
  ...

Thus the most current version of a particular project's workbook is found in project/current, while a particular version can be accessed through project/version.

In order to contribute to the workbook, you need to check out the workbook source files from the respective CVS repository, make, commit and tag your changes, and finally let the workbook webmaster know that an update of the workbook is available and should be published on the LCGAPP web server. These steps are described in detail below, assuming that you will be working on a Linux system.

Note that in order to keep the documentation up-to-date, a new release of a project should always be accompanied by a new version of the corresponding workbook sections.

How to Check Out the Source of the Workbook

In order to modify the workbook, you first need to check out the current version of the workbook into a temporary working area. Utility scripts are available to set up the overall structure of the workbook and to check out the source files of the project-specific workbooks from the different CVS repositories involved.

It is best to check out the workbook into a temporary directory in your web area, since then you will be able to immediately see the effect of your changes with your web browser, but any directory will do for modifying and committing back your changes.

For example, if your web area is in ~/www, proceed as follows:

Download and save the 3 scripts workbook-create, workbook-update, and workbook-update-all in a directory that is in your PATH (all 3 scripts are needed).
Check out the source files of the workbook project you are interested in, or of the complete LCG Application Area workbook.
For example to check out the POOL workbook for modification into your personal web area (~/www/workbook), do:
```
workbook-update-all ~/www/workbook HEAD main
workbook-update-all -w ~/www/workbook HEAD pool
```
The first command sets up the overall structure of the workbook, and the second checks out the source of the POOL workbook.
Or, to check out the complete workbook, do:
```
workbook-update-all -w ~/www/workbook HEAD all
```
In each case the option -w indicates that you may want to modify the files that are checked out and therefore need to log into the CVS repository with write access. Omit the -w option if you don't want to modify any of the files checked out or don't have write access to the corresponding CVS repository.
You will be asked for the CVS password for each CVS repository that contains a part of the workbook that you are checking out. In each case, enter your own CVS password (if you used '-w' to get write access), or "cvs" to access a CVS repository anonymously (if you omitted the -w option).
If you execute workbook-update-all without any arguments, it will display a brief usage information (this is true for all the workbook utility scripts). workbook-update-all simply calls workbook-create and workbook-update with the correct options. If you look at the workbook-update-all script, it will be obvious which arguments to use with workbook-update in case you ever wanted to use it directly.
If you checked out the workbook into an area in your web space, you will have created a fully functional private version of the workbook. If you are working at CERN, point your browser to http://cern.ch/yourname/workbook to check that this is indeed the case. If you don't see the header or footer on the workbook pages, your web server does not have server-side includes enabled for this area. Add the following lines
```
Options +Includes
XBitHack on
```
to a .htaccess file in your workbook top level directory or ask your system manager to add this to his httpd.conf file. Also note that with these settings all html files using server-side includes must have their execute bit set.

How to Modify an Existing Page or Write a New Page for the Workbook

Because you will need write access to commit back your changes to the corresponding CVS repository, make sure you use the -w option with the workbook utility scripts when checking out the part of the workbook you want to modify (see above). If you don't have write access, please follow these instructions to obtain it.

Once you have checked out the source of the workbook, you can directly edit the html source files. In principle you may use any html editor you like, as long as the overall format of the file (see above) is preserved (i.e. you must not edit the sections that include header and footer). Do not spend time on fancy formatting of individual pages because the plan is to develop an overall style sheet for the workbook at a later time. Please note that unless you want to refer to a particular version of the workbook, all links to other workbook pages should be made as relative links (i.e. for example <a href="pool.html"> or <a href="../../pool/current/pool.html"> instead of <a href="http://lcgapp.cern.ch/project/workbook/pool/current/pool.html">).

If you want to start a new page, please start with the template file template.html that you will find in shared/template.html when you check out the workbook.

Once you are happy with your changes, commit them back to the respective CVS repository as follows:

cd to the directory containing your changes
Review the changes by doing a
```
cvs diff
```
Make sure that there have been no conflicting changes in the mean time:
```
cvs update -A
```
If there were any conflicts, you will need to resolve them before proceeding to the next step.
Commit your changes and tag them:
```
cvs commit -m "A concise comment describing what you changed"
cvs tag yourtag
```
where yourtag is a CVS tag following the conventions of the respective CVS repository (for example your initials followed by the date you issue the tag).
Finally, notify the workbook webmaster about your changes and tell them the tag you've used, so that the official version of the workbook can be updated.

How to Start a Workbook for a New Project

In order to start a workbook for a new project, you need to create a directory (preferably named workbook) in the CVS repository of the corresponding project. This directory will hold the the source files for that workbook. The directory can be located anywhere in the directory tree of the CVS repository. Examples are:

SPI: SpiInfrastructure/UserDocumentation/workbook
POOL: workbook

Since a given repository may contain more than one workbook, it is desirable to create a subdirectory for each workbook (for example, the SPI repository currently contains a general workbook and a workbook for SPI specific information).

Once the workbook directory is created in the CVS repository, the corresponding workbook can be added to a copy of the LCG Application Area workbook (that has been created using the script workbook-create) by using the script workbook-update. The arguments to workbook-update specify the CVS repository, the name of the project, the path to the workbook within the CVS repository, the directory into which the workbook should be checked out, and the desired tag of the workbook. For example, to check out the HEAD of the SPI workbook into a local copy of the LCG Application Area workbook, the following command can be used:

workbook-update :pserver:anoncvs@lcgapp.cern.ch:/cvs/Infrastructure spi SpiInfrastructure/UserDocumentation/workbook ~/www/workbook HEAD

Whenever you create a new project workbook, you should add the corresponding command to check out your new workbook to the workbook-update-all script, so that everybody will then be able to conveniently build a complete version of the LCG Application Area workbook.

Finally, you should create links to your new workbook in the existing workbook.

If you need help creating a new workbook, please contact the workbook webmaster.

How to Publish the Workbook on the Web Server

The LCG Application Area workbook is available at the URL http://lcgapp.cern.ch/project/workbook/. The corresponding files are located on AFS in the directory

/afs/cern.ch/project/lcg/app/www/workbook

You can use the scripts described above in order to check out the workbook from scratch, update it to the current version, or add different versions of the workbook. For example, to check out the most recent version of the complete workbook from scratch and make this the default version seen by the user you could do the following:

workbook-update-all /afs/cern.ch/project/lcg/app/www/workbook HEAD

The latter command will also update an existing version of the workbook to the most recent version. Of course you can use workbook-update-all to check out particular versions of individual workbooks as well, for example, to check out the POOL workbook for release POOL_0_4_0 do:

workbook-update-all /afs/cern.ch/project/lcg/app/www/workbook POOL_0_4_0 pool

The default links on the main workbook page refer to the "current" version of each project's workbook. This version is found by using a softlink named current that points to one of the checked out versions (see directory structure described above in the introduction). workbook-update-all will create this link if it doesn't exist, but will not change it if it does exist already. After checking out a new version of the workbook, you may therefore want to either change the current link to point to the new version, or add an explicit link to the main workbook page (located in the SPI CVS repository under SpiInfrastructure/UserDocumentation/workbook/index.html).

All changes to the official version of the workbook provided by the LCG Application Area web server should be coordinated with the workbook webmaster.

Author(s): Juerg Beringer