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.
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:
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 poolThe 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 allIn 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.
Options +Includes XBitHack onto 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.
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:
cvs update -AIf there were any conflicts, you will need to resolve them before proceeding to the next step.
cvs commit -m "A concise comment describing what you changed" cvs tag yourtagwhere 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).
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:firstname.lastname@example.org:/cvs/Infrastructure spi SpiInfrastructure/UserDocumentation/workbook ~/www/workbook HEADWhenever 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.
/afs/cern.ch/project/lcg/app/www/workbookYou 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 HEADThe 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