The CMS Offline Guide - Guide for Contributors

Complete: 4

Goals of this page:

This page explains the protocol for adding new material to the CMS Offline Guide, and provides guidelines for users to create a standard CMS Offline Guide page. The page also explains how to use some of the extra features, e.g., adding index markers and displaying text that resides on other CMS twiki pages.


Adding new material to the CMS Offline Guide

The group user support contact persons are responsible of the material provided for their areas.


The CMS Offline Guide pages are stored as TWiki topics. The following simple rules should be adhered to when producing CMS Offline Guide pages:

Offline Guide topic names (i.e., page labels used as links to the topics)
Topic names should be of the form SWGuidePageName i.e., each page in the Offline Guide should should have a name starting with SWGuide.

Offline Guide page template
Use the provided templates for documentation.

Completeness Indicator
The variable %COMPLETEn% where n is an integer between 0 and 5 is used to indicate how complete the topic is (0 empty, 5 complete).


For the pages covering reconstructed objects, follow the SWGuidePhysicsObjectTemplate. It includes:
  • sample table of contents (TOC)
  • sample headings
    • Offline Guide
      • Contacts
      • Introduction
      • Tutorials
      • RECO/AOD collection
      • Algorithms and Software Architecture
      • Analysis and Validation
      • Documentation
      • Related Topics * review status table
When you start a new page for an item other than physics object (for example for a subgroup), use the SWGuidePageTemplate. It includes:
  • sample table of contents (TOC)
  • Goal of this page heading
  • Contacts: group home page, mailing lists, hn forum, group convenors
  • sample headings
  • resposible of the page
  • review status table
The descriptions of algorithms should follow the SWGuideAlgorithmTemplate.

If you want to start a new page from a template, create your page (by adding a link to an existing page, and clicking on the small question marks which appears right after the name of your yet non-existing page after saving), open the template page by clicking on Raw View, copy the contents and paste it to your new page.

Predefined variables

Some variables are defined in WebPreferences. In particular, you may want to use the links to the Reference Manual and to the cvs repository.

Reference manual

 [[%DOXY%r=3_4_0&c=AboveSeed][AboveSeed]]  [[%DOXY%r=3_4_0&c=Electron&K={reco}][reco::Electron]]  
which give AboveSeed and reco::Electron. This script finds the correct location independently of the doxygen generated directory structure.

It redirects incoming links from twiki to doxygen pages according to the parameters specified after the twiki variable %DOXY%. There must be at least 2 parameters:

  • the first parameter must be "r" which stands for the CMSSW release (e.g. 2_2_10)
  • the second parameter must be one of the following set
    • "s" (which stands for "struct")
    • "c" (which stands for "class")
    • "n" (which stands for "namespace")
    • "o" (which stands for "source code")
If the script hits many entries matching those parameters, then it returns a default page listing all the retrieved entries to let the user pick the suitable one. To bypass that (or alternatively to refine your query), you can set up:
  • a third parameter to specify a list of keywords (if many, then separated by commas) and select the match whose http-address contains all of them: this parameter must be
    • either "k" (to implement a strict research, namely, the http-address matches the keywords if it contains all and ONLY the listed keywords)
    • or "K" (to implement a wide research, namely, the http-address matches the keywords if it contains AT LEAST all the listed keywords)
  • Note that all the mentioned parameters except "r" (i.e. "c","s","n","o","k" and "K"), accept wildcards "*"
  • Finally note that the string that follows %DOXY% should contain no blanks or spaces

For a better understanding, please compare the following tests yourself:

CVS repository

  • %CVSL%Alignment/TrackerAlignment%CVSR% 
    gives CVS
  • %CVSL%Alignment/TrackerAlignment][Alignment/TrackerAlignment]] 
    gives Alignment/TrackerAlignment

Links to other material

The scope of the Offline Guide is to collect the needed documentation in the structured way to help the collaborators to find the information on each CMSSW package easily. Links to the WorkBook and to the Reference Manual (see above) are encouraged, whereas all the Offline Guide material should reside directly under the Offline Guide, the topic name starting with SWGuide. To avoid duplication, already existing wiki pages will be moved from their current location to the Offline Guide.

Common links on PAG pages

The following part "Guidelines and documentation" should be included to all PAG pages.

CMS guidelines and documentation

General analysis guidelines

CMS physics results

CMSSW documentation

It can be included with this line

%INCLUDE{"SWGuideContributors" pattern="(?:.*?<!--STOPPAGCOMMONS-->){0}.*?<!--STARTPAGCOMMONS-->(.*?)<!--STOPPAGCOMMONS-->.*"}%
It should be followed by a link to the group-specific documentation in the Offline SW Guide.


The Offline Guide is closely connected to the WorkBook and its functionality relies on what already exists for the WorkBook. Please check also WorkBookContributors.

Review Status

Reviewer/Editor and Date (copy from screen) Comments
KatiLassilaPerini - 21 Jan 2009 updates to templates and predefined material
KatiLassilaPerini - 23 Jan 2007 significant content editing
KatiLassilaPerini - 05 Feb 2007 page content last edited
JennyWilliams - 07 Feb 2007 twiki tidying

Responsible: KatiLassilaPerini
Last reviewed by: Reviewer

Edit | Attach | Watch | Print version | History: r27 < r26 < r25 < r24 < r23 | Backlinks | Raw View | WYSIWYG | More topic actions
Topic revision: r27 - 2010-05-07 - AreshVedaee

    • Cern Search Icon Cern Search
    • TWiki Search Icon TWiki Search
    • Google Search Icon Google Search

    CMSPublic All webs login

This site is powered by the TWiki collaboration platform Powered by PerlCopyright & 2008-2018 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback