0.4 Workbook Guide for Contributors

Complete:
Detailed Review status

Goals of this page:

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

Contents

How to use the WorkBook Adding new material to the CMS Workbook Save Frequently and other warnings Conventions Template Left Side Navigation Bar Headings Links Link to anchor in same twiki page Link to separate WorkBook twiki page Link to anchor in separate WorkBook twiki page Link to CMS twiki page that's not in the WorkBook Link to general URL (external to CMS twiki) Link to class documentation in the CMSSW Reference Manual

Highlighting code Indexing Tables Equations Long lines (in "pre" and "verbatim" tags) Figures General Guidelines Issues with importing PPT graphics Including text that resides on other pages Variables Environment setup Printed document Acknowledgements Review Status

How to use the WorkBook

The basic philosphy the CMS Offline WorkBook is described in the purpose statement on the main WorkBook page, while WorkBookUsage explains how the user can get the most benefit from the Workbook. Contributors to the Workbook project should be familiar with these aims.

Adding new material to the CMS WorkBook

The first stop for contributing material to the CMS WorkBook is the CMS Workbook Documentation hypernews forum. The email gateway for this forum is: hn-cms-workbook@cernNOSPAMPLEASE.ch. You are encouraged to email the forum with questions, comments, complaints, contributions, corrections, etc. (Alternatively you are welcome to contact the principal workbook editors, presently Kati Lassila-Perini, with your feedback and suggestions.)

In addition to being a discussion area, the WorkBook hypernews forum provides a public staging area for new workbook documentation proposed by CMS users. Suggestions for new workbook documentation - on all aspects of CMS operations - should be posted to this hypernews forum. Please do not add new content directly to the Workbook without prior agreement from an editor.

Save Frequently and other warnings

As you compose pages, SAVE OFTEN! (Hit "Checkpoint" to save without leaving the editor.) Be forewarned that you can lose your work in the twiki if you're not careful. Here are a few guidelines:

• DO NOT write a lot without saving.
• DO NOT hit whatever it is on IE that opens the annoying IE search sidebar.
• DO NOT try to Undo.

Conventions

The CMS WorkBook pages are stored as TWiki topics. Following conventions adopted by the ATLAS WorkBook project, the following simple rules should be adhered to when producing WorkBook pages. Note that Twiki variables, some of which are introduced here, begin and end with a percent sign (%).

Workbook topic names (i.e., page labels used as links to the topics)

Topic names must be of the form WorkBookSomeTopicName i.e., WorkBook followed by a descriptive name.

Workbook Topic Template

Use the provided WorkBook page template to make it easy to follow the rules!

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, shows all white; 5=complete, shows all green).

Review Status

At the bottom, review status info should be inserted each time there is a significant change or a review has been done. The last time the topic was reviewed should be indicated using the formatting %REVIEW% Main.WhoEver - xx month year. Using this format enables the WorkBookSummary to keep track of changes and reviewers.

Responsible person

The person responsible for the topic should be indicated by %RESPONSIBLE% Main.WhoEver.

Editing language

Wherever possible, please use TWiki editing rather than raw HTML.

Template

When you start a new page, use the WorkBookPageTemplate. It includes:

• the completeness bar
• Goals heading
• Sample Table of Contents (TOC), must be manually input in order to produce proper PDF
• Sample headings with anchors (anchors allow inclusion in TOC)
• Information Sources heading
• An include statement for CMSSW environment setup (useful for tutorial pages)
• Review Status table

Further features may occasionally be added to the template and propagated through existing workbook pages.

#CMS.LeftBar

Left Side Navigation Bar

To include a left side navigation bar in a new page, first make the page and save it.

1. On your new WorkBook page click on "Create a CMS.LeftBar" (on left-hand side where bar would go).
2. An editing window appears; it gives you the choice of making your own specialized left bar, or choosing the default.
3. If the default is SWGuidePageLeftBar, replace it by WorkBookLeftBar and click "save".
4. Go back to your new page (click back a couple of times) and refresh.
5. You should now see the standard (default) left sidebar.

Changes to the left sidebar (e.g., to accommodate new workbook pages) are made by editing "WorkBookLeftBar" (Please send a request for such to the workbook HN forum and let one of the editors evaluate your request and make the change).

Headings

The Workbook uses standard TWiki headings. To disable linking on a WikiWord in a heading, precede it with <nop> instead of !; the latter does not work properly in the table of contents.

Links

In general, it's best to do

[[http://this/is/a/url][description of url]]

Remember to close all the brackets!

Specifics follow.

Link to anchor in same twiki page

Put a link of the form #LinkName just ahead of the source, and add

[[#LinkName][link name]]

at the target location.

Note that anchor link names must be WikiWords - that is, they must start with a capital and have a mixture of capitals and small letters in the word, e.g. AnchorPage, not Anchorpage.

Link to separate WorkBook twiki page

Put the name of the page as the link, e.g., WorkBookPageName, or

[[WorkBookPageName][Title of Workbook page]]

Link to anchor in separate WorkBook twiki page

Put the name of the page plus the anchor preceded by # as the link, e.g., WorkBookPageName#LinkName, or

[[WorkBookPageName#LinkName][Title of section on Workbook page]]

Note that the anchor must be a wikiword - namely a collection of letters having at least two capitals with them separated by at least one lower-case character.

Link to CMS twiki page that's not in the WorkBook

The Workbook pages are simply a part of the main CMS twiki, differentiated by having all page names called WorkBookXYX to enable some special workbook features to pick out only workbook pages. As such, linking to an anchor in any CMS twiki page uses the same syntax, e.g.

Name of CMS twiki page

[[WebHome][Name of CMS twiki page]] 

It follows that linking to an anchor in a CMS twiki page is the same as the case of linking to an anchor in a separate workbook page.

Link to general URL (external to CMS twiki)

Use the full URL, e.g.,

[[http://this/is/a/url][description of url]]

Link to the CMSSW Reference Manual class documentation

To link the Doxygen CMSSW Reference Manual Documentation from Twiki, you can use the twiki variable %DOXY%. For a short guide on its usage see here

Highlighting code

In tutorial pages, the readability can be improved by highlighting the command line instructions and code with a different background, see an example in WorkBookPATTupleCreationExercise. To do this, attach the following style sheet (name it "tutorial.css") to the page

PRE { background-color:beige;
      border-color:maroon; border-style:solid; border-width:thin;
      padding:5px; }
TABLE PRE  { background-color:paleturquoise;
         border-color:blue; border-style:solid; border-width:thin;
         padding:5px; }

define it in the page settings (follow More topic actions -> Edit page settings)

   * Set USERSTYLEURL = %ATTACHURL%/tutorial.css

These settings will define your "verbatim" and "PRE" environments which you can use for command line instructions.

To highlight the code use the "SYNTAX" environment as described in SyntaxHighlightingPlugin instructions. You can dump the list of supported syntax names with

enscript --help-pretty-print | grep Name

Indexing

To add terms to the index, first add an anchor at the place where the term appears in the text, then in the Glossary/Index page, add a link to that source page and anchor, as described in Link to anchor in separate WorkBook twiki page.

Tables

Tables are described in the standard TWiki documentation. To use angle brackets inside a table, e.g., to say

<hi> 

within a table cell, the only way that works for both web and PDF is

<hi> 

E.g.,

greeting
<hi> ("hi" written as recommended) works
("hi" with plain angle brackets) doesn't work (look at raw text and see that it's in the table, but isn't printing)

In the initial line of a table, make the text bold by using asterisks, e.g., Column Heading, and leave a space between the asterisks and the vertical lines.

| *Column Heading* |

If you write a table using the html <td> etc tags, the table will appear normally, but will not have the more attractive colouring and display of the twiki tables made with vertical lines to separate table cells.

Equations

You should use standard html markup to include equations or mathematical symbols in workbook pages. (A previous feature of the workbook involving LaTex rendering is now deprecated as it is not compatible with the current twiki version.)

Html symbol codes can be found in the following links:

• HTML Codes - Characters and Symbols
• Entities for Symbols and Greek Letters

Long lines (in "pre" and "verbatim" tags)

Normal text is wrapped to fit the page width of your browser window and display nicely. However, text included in <pre> and <verbatim> tags retains its formatting. The new twiki version introduces individual scroll bars for each line of overlong text, so that lines of text that are too long to display in the browser window can be studied. However when the pdf version is made, the text is simply truncated - and therefore not all information from overlong lines is printed.

As such, you should be very careful about using the verbatim tags to ensure that overlong lines are not leading to important information being omitted. Long lines generally result from instructions listing long pathnames for files or code packages, or from quoting expected output from issuing a certain command. In the latter case, the truncation in the printed version is rarely a problem, but in the former case, the page author should make sure to add line breaks (and possibly a note to the user that they need to issue all the commands in a single line but that they are shown in the document as 2 or more lines simply for formatting reasons).

In general, don't make lines longer than 90 characters. In general, if you're wondering if your text will fit - save the text - hit the standard TWiki "PDF" button, and see if it fits.

Attaching Files

When you wish the reader to be able to see a file, e.g., a configuration file, as he or she goes through your page, you have some choices as to how to make it available.

• If the file exists in CVSweb, we recommend that you link to the file in that location.
• If the file doesn't exist in CVSweb, it's best to attach the file directly to the page. Using the "Attach" button is described in the standard "More Formatting Help" link at the bottom of each edit page. It's best to give the file an extension that is recognizable to the system, usually txt is best. E.g., for an ASCII configuration file that ends in .cfg, .cff, or other extension, make a copy that ends in .txt, and attach the copy. It will save your reader several clicks and some frustration.

Figures

General Guidelines

Instructions for entering figures for display in your twiki page are at the standard "More Formatting Help" link at the bottom of each edit page. You need to "attach" your images before including them in your pages - please do not simply source the images from a different URL, as these pages can change, and the links therefore get broken.

The standard image insertion command used in the current (Nov '06) version of the workbook is (make sure there are NO LINEBREAKS in the img src command; wrapping over lines is ok though. Line break shown here to avoid cutoff in PDF printing):

<img src="%ATTACHURLPATH%/MyFigure.jpg" 
alt="text to appear if image fails" height="XXX" width="YYY" />

You can include higher resolution figures in the PDF version by including a pdfsrc on the img tag, e.g. (line broken before "pdfsrc" such that entire line prints in PDF; note there is a space preceding "pdfsrc"):

<img src="%ATTACHURLPATH%/NormalFigure.jpg" 
pdfsrc="%ATTACHURLPATH%/HighResFigure.eps" /> 

Note: remember to put ATTACHURLPATH, rather than just ATTACHURL, which does not work as well in img src commands, and breaks the PDF maker.

Issues with importing PPT graphics

• If you're including a bunch of ppt stuff grouped together and then saved as a picture, you have to put a background box on the image, or else it doesn't work in the PDF.
• If you save a textbox from ppt as an image to put into the twiki, you have to format that box and give it some background fill (generally white), else you get an equally frustrating and hard-to-find crash.

Including Text that resides on other pages

You can include pieces of other CMS WorkBook TWiki pages without copying them in (and having redundant information to maintain). To do so, you put (invisible) start-stop markers around the desired chunk of content in the file with text to be included, i.e., the source file. You may enclose multiple chunks this way, serially, in the same page:

<!--STARTWORKBOOK-->
Text to be included 
...
<!--STOPWORKBOOK-->

The first occurrence of a pair of these markers around a text chunk is counted as number 0 (zero) within the source page, and identified by this number in the target page. So you'll need to count forwards, starting at 0, to the desired occurrence, and use its place in the order to identify it. E.g., the 6th actual occurrence of these markers would be identified as "5".

In the page in which the text is to be included, i.e., the target page, use the following syntax. Here we show the source page as as SomeTWikiTopic. Notice that the occurrence number is put inside the curly brackets, and shown here for occurrences 0 and 1 (lines broken here after the {n} in order that entire lines print in PDF):

%INCLUDE{"SomeTWikiTopic" pattern="(?:.*?<!--STOPWORKBOOK-->){0}
.*?<!--STARTWORKBOOK-->(.*?)<!--STOPWORKBOOK-->.*"}%

%INCLUDE{"SomeTWikiTopic" pattern="(?:.*?<!--STOPWORKBOOK-->){1}
.*?<!--STARTWORKBOOK-->(.*?)<!--STOPWORKBOOK-->.*"}%
...

Note that this is looking for the pattern . If you have an INCLUDE statement already in your source page (i.e., your source page is also a target page for some other information) ahead of the desired instance of START/STOP that you want, this search will find the two matched patterns in the INCLUDE statement first. Therefore, ...

For every INCLUDE statement in the source page preceding the desired instance of STARTWORKBOOK/STOPWORKBOOK, add 2 to the number used in the INCLUDE statement on the target page to specify the instance.

This last bit, below, can be used to pick up the signatures from the end of the source page (assuming they were entered properly in the format Main.Twiki.Name):

%INCLUDE{"SomeTWikiTopic" pattern=".*?(\-\- Main\..*)"}%

This practice saves repeating already existing text, and more importantly helps ensure that a given topic is described (and updated as needed) in only one place. It also automatically imports changes when they are made to the source TWiki topic.

Variables

To avoid extensive editing when things like release numbers change, the following variables are defined in the WebPreferences twiki document:

• %WBRELEASE% - The latest production release - currently set to 7_4_15

Please use them in your content, as appropriate. If any of these varible values need updating, please notify the WorkBook editors. Other variables will be added as needed.

Since TWiki variables are not expanded inside <verbatim>...</verbatim>, use <pre>...</pre> instead when a variable is included in the content.

Environment setup

In the WorkBookPageTemplate, we suggest that you add the following to any workbook page that is a tutorial.

#SetUpEnv
---++ Set up your Environment  

%INCLUDE{"WorkBookEnvIncludeNew" pattern="(?:.*?<!--STOPWORKBOOK-->){0}.*?
  <!--STARTWORKBOOK-->(.*?)<!--STOPWORKBOOK-->.*"}%
#edit the above two lines to be a single line!

This will produce the following:

Set up your Environment

Set your runtime environment (shown for release %WBRELEASENEW%):
cd CMSSW_%WBRELEASENEW%/src
cmsenv

• Full instructions
• Summary for every login session
• Access modules from the CVS repository.

The text to be included is provided for the moment for releases %WBRELEASENEW% as shown above.

If you are using another releases, you should type this yourself.

Printed document

The WorkBook will be printed in regular intervals. To add different text in the printed version and the online version you can use conditional statement %IF{"defined PRINT" then="text for print" else="text for online"}% such as

 
To set up a !CMS.HyperNews membership, start %IF{"defined PRINT" 
then="in http://hypernews.cern.ch/" else="[[http://hypernews.cern.ch/][here]]"}%.

which results to "To set up a CMS.HyperNews membership, start here" for the online pages and to "To set up a CMS.HyperNews membership, start in http://hypernews.cern.ch/" for the printed pages if printed from the pages linked under WorkBookPrintable for which the PRINT variable is defined.

Review status

Reviewer/Editor and Date (copy from screen)	Comments
JennyWilliams - 02 Jul 2007	Changed equation markup recommendation to html from LateX (latex use in the workbook is now discouraged)
CMSUserSupport - 01 Dec 2006	added PRINT variable
AnneHeavey - 14 Nov 2006	review prior to mass printing end of 2006

Responsible: KatiLassilaPerini
Last reviewed by: KatiLassilaPerini - 25 Jan 2008