Wiki Help

Wiki Help describes basic tasks that you can accomplish in the wiki, such as creating and editing articles, basic editing tasks, subscribing to feeds, and providing feedback on the wiki. It also includes reference information on how to use the supported wiki markup for formatting.

Browser support notes
Microsoft Windows users using Microsoft Internet Explorer, it is recommended that you use Internet Explorer 7 when interacting with the wiki.
Apple Safari is not supported.

Contributing to the wiki

To add, edit, or comment on an article, you must have a developerWorks Lotus user name and password.
If you have a developerWorks Lotus user name and password, click Log in in the Contribute section on the left side of the wiki.
If you do not have a developerWorks Lotus user name and password, click Wiki user name registration in the Contribute section on the left side of the wiki.

Creating your own articles

1. Click Add an article on the top, left side of the wiki.
2. Type the article title in the Subject field.

• The subject of your article will become the URL for the article
• Changing the article's subject will not change the URL once it is created and saved.
• The first paragraph in your article should be a brief description of the article. This paragraph displays in many of the views and helps the reader determine if the article is relevant to their search without having to open the article.
• The subject of your article can contain any combination of alphanumeric and non-alphanumeric characters, however, if you need to link to an article whose title contains non-alphanumeric characters, only the following characters are supported for linking:
• colon :
• dot .
• comma ,
• apostrophe '
• quotations "

3. Select a category and tags to make your article easier to find. Select all that apply.


IMPORTANT:   Wiki articles use a style sheet for a consistent look and feel, therefore font changes such as size, color, or font face will be overwritten by the style sheet. If you would like to format text to use a different color, font face, or font size, then use HTML. You can type HTML directly into the Rich Text Editor and the wiki parser will recognize it and render it appropriately when you have saved the article.

Best practice:
Create an initial draft of your wiki article and save it, then go back into the article and edit it to add your content and format it. This will ensure that your article is saved to the database, and that all wiki functionality is available.

Recommendations

• Include a brief bio about yourself at the end of the article.
• Include a link to your own blog or Web site as well.

Using HTML markup in articles

You can use HTML directly in the rich text editor to format your article if desired.


Support for the following HTML markup is available:
Use of these elements is supported in wiki articles.

Paragraphs: <p>
Headings: <h1>, <h2>, <h3>
Lists:
<ul><li></li></ul>
<ol><li></li></ol>

Limited support for the following HTML markup is available:
Use of these elements is supported for simple content but are not be supported for complex formatting and layout.

Example of a simple table using HTML Markup:

<table class="lotusTable lotusInfoTable"><tr><th><h2> Table heading </h2></th></tr><tr><td> row 1 row2 row3 </td></tr></table> Renders as follows:

Section II - Introduction to XPages
Link to subtopic Link to subtopic Link to subtopic

No support, use at your own risk:
Use of these elements may effect the overall appearance of the wiki.
<div>
<span>

Editing articles

To edit an article, click Edit at the bottom of the article. You can use a combination of wiki markup, HTML, and the tools available from the rich text editor to add or modify the content in an article. A wiki markup reference guide is available at the bottom of the article when you are in edit mode.

Commenting on articles

To comment on an article, scroll to the bottom of the article, expand the Comments section,  and click Add a comment.

Creating subheadings in a wiki article

You can use wiki markup mixed in with your rich text to get subheadings in your posts, like this:

Wiki markup code for headings:
==My heading 2==
===My heading 3===
====My heading 4====

Headings rendered on the Web:

IMPORTANT: Do not use any kind of formatting on wiki markup. If you do, the markup will not work.
     
Tips:

• Start with heading 2. Your article will automatically use heading 1 as the article title.
• You cannot use any non-alpha-numeric characters in your heading text when using wiki markup to create the headings.

Creating a TOC

When you use wiki markup to designate text as a heading, a table of contents is automatically created at the beginning of the article.

IMPORTANT:

• Do not include any none alpha-numeric characters in the heading text. This can cause the heading markup to be ignored.
• Do not apply any kind of font formatting to the heading text. This will cause the markup to be ignored.

Creating complicated lists

To create create a complicated list (nested bullets, numbers, etc.) you can use the bulleted list and numbered list buttons in the editor's toolbar. 

Adding code examples to an article

You can add an incomplete code example within the context of an article, for the purpose of showing an example. To add a code example, use wiki markup:
{code:} <your code example here> {code}

You can use optional flags to control the appearance of the code example:

{code: |an|width|height} <your code example here>{code}

Optional flags "a" and/or "n" add alternate line shading and numbering respectively.
Height and width values can be used to create a scrolling area for long sections of code examples. For example {code: a|200|400}<your code sample here> {code}
Below is an example of a long code sample that uses the a and n optional flags, and height and width values of 200 and 400 respectively.



To insert code samples inline with text use the "no wiki" markup option. Surround the text you do not want parsed with three curly braces "{" as shown in the example below:


Doing so will allow characters that are normally interpreted by browsers to pass through as text. For example:
In the following example, the <note> is an object that contains the elements <to>, <from>, <heading>, and <body>.


Note: Working code samples and executables should not be attached to wiki articles. If you have a piece of code that can be executed, please post it in Lotus Greenhouse and link to it from your wiki article. Go to the Lotus Greenhouse website for more information: https://greenhouse.lotus.com/plugins/plugincatalog.nsf/home.xsp

Adding images and attachments to articles

Use the Attachments section at the bottom of the page to attach the graphics, then reference the graphic using wiki markup:

• Expand the Attachments section and select Attach File.
• Browse to the file on your local system and select open.
• Insert a reference to the image in the body of your article using the following syntax:
  {{image.file | alt text}}

IMPORTANT: The alt text attribute is required.

Including multimedia in an article

You can embed flash objects in a wiki article using the following HTML code in the article:

To embed a .swf file, use this code:


where "URL" is the URL to the .swf file hosted on a publicly available Web server.


To embed an HTML file that references a .swf, .wmv, or other media file, use this code:

<iframe src="URL" width="1000" height="650"></iframe>

where "URL" is the URL to the .html file hosted on a publicly available Web server.

In addition, to embedded the multimedia in the article, also include a link to open the object full screen in a new window. Use the following code to create this link:
<a href="URL" target="_blank">Watch the demonstration full screen in a new window</a>

where "URL" is the URL to the .html, .swf, .wmv, or other file


Categorize the wiki article in the Media Gallery category in the wiki, and include the appropriate tag; for example, demo, tutorial, video, podcast, seminar, and so on.

Creating tables

Use wiki markup to create a table using the following syntax:

|= for headings; | for cells:

For example

|=|=column 1|= column 2|=Column 3
|=Row 1|cell 1|cell 2|cell 3
|=Row 2|cell 1|cell 2|cell 3

which renders as follows:

	column 1	column 2	Column 3
Row 1	cell 1	cell 2	cell 3
Row 2	cell 1	cell 2	cell 3

Linking

Use wiki markup to add links to wiki articles or external links:
To link to a wiki article within the wiki use [[wiki page name]]. Simply use the title of the wiki article to which you want to link.

To link to an external page use [[URL|Linkname]], for example [[http://www.ibm.com|IBM]] looks like this: IBM

Revisions

Reading previous versions of an article

To read previous versions of an article, scroll to the bottom of the page. In the Article Information section, click any of the previous article links under the Revision section. Note that the current version of the article is the only version that can be edited.

Rolling back to a previous version of an article

The wiki administrators have the ability to rollback articles to previous versions. If you would like an article rolled back to a previous version, click Wiki feedback in the Help section for the footer. In the form include the following information:

• Name of wiki
• Name of the article you want to roll back
• Specific version (date and time) you want to roll back to
• Reason you need to roll back the article

The wiki administrators will review the request and determine if an article roll back is needed.

Deleting an article

If you would like an article deleted from the wiki, click Wiki feedback in the Help section of the footer. In the form include the following information:

• Name of wiki
• Name of the article you want to delete
• Specific version (date and time) you want to delete
• Reason you need to delete the article

Providing feedback on the wiki

We want your feedback! To provide feedback on using the wiki, click Wiki feedback in the Help section of the footer.

Using feeds and notifications

To receive notification of the latest updates on the wiki, subscribe to an RSS feed by clicking the orange RSS icon in the Subscribe to RSS section on the wiki footer i to subscribe to a RSS feed.
Note: If your browser does not have RSS reading capability built in, or if you do not have an installed feed reader,  you will see the raw XML feed when clicking the RSS icon. You must have a feed reader to use the RSS feature of the wiki.

More about wiki markup

This wiki supports a subset of wiki creole markup. Refer to the following quick reference information:

Links

To link to another wiki page: Link to [[wiki page]], for example: Internal wiki page (Creates the page if it does not exist)

To link to an external URL: [[URL|Linkname]], for example: http://www.ibm.com

Headings and TOC

To create headings (and an automatic TOC), use the following:

==Large Heading==
===Medium Heading===
====Small Heading====

Which render like this in the live wiki:

IMPORTANT:

• You cannot use any non-alpha-numeric characters such as : or ' in the headings, otherwise the markup does not work.
• Do not use any kind of font formatting around your heading text. This will cause the headings to break.

Horizontal rule

To create a horizontal line, use ----

---

Images

To insert an image that has been attached to the page, use the following markup:

{{Image.jpg|title}}
{{Image.jpg|title|align="right"}}

Tables

To create a simple table, use Table: | is for a cell |= is for a cell heading for example:
|=|=Table|=Heading
|a| Table | Row
|b| Table | Row

which renders as follows:

	column 1	column 2	Column 3
Row 1	cell 1	cell 2	cell 3
Row 2	cell 1	cell 2	cell 3

Code examples

Text enclosed in three curly braces "{" and "}" will be ignored by the parser and will display as text. For example:
Sentence containing something with HTML characters - <this is a piece of code enclosed in the no wiki brackets>

Surrounding code with {code:} {code} will retain the format and include a source code box.

Optional flags "a" and/or "n" add alternate line shading and line numbering.

Height and width values can also be added, for example {code: |a|100|200}<code sample here>
some code
:some more code
//some more code {code}

would render as:

Troubleshooting wiki markup

The following are common issues that might arise while using wiki markup:
Link to a wiki article does not work:

• This can happen if the wiki article's title contains a none alpha-numeric character. When creating a wiki article, you should ensure that the subject only contains alpha-numeric characters.

The link to a wiki article I created is showing as a new page:

• This can happen if you typed the wiki article's name incorrectly in the wiki markup for the link, or if the wiki article contains a none alpha-numeric character in the title.

Wiki markup is showing up in the short description of my wiki article from the views in the home page:

• The view doesn't parse the wiki markup and displays it as text. Ensure that the first paragraph in your article does not include wiki markup. It's a good idea to add a short description of the article because this information is displayed in any views from the home page. The description enables readers to assess whether or not the article is what they are looking for without actually opening the article.

Tips for porting an MS Word doc to the wiki

TIP: Always author in the wiki so you don't have to port a Word document. But if you need to port a Word document to a wiki article, the information below can help make this transition smoother.

Save the Word document as HTML

Before you can port the document, save it as HTML. HTML files created by Microsoft Word carry a lot of extra information to make it possible to re-import the file into Word and save is as a .doc without losing certain features. The standard Save As dialog in Word is not primarily designed to create documents to upload to a Web server for anyone to browse.

1. If using MS Office 2000, click File > Export As > Compact HTML. Office 2003 or later, Save as HTML.
2. Download and run MS Office HTML Filter 2.0 This step gives you clean HTML.

Cleanup

Delete top Javascript and style sections at the top of the file, and then remove the following tags:


<div>
<span>
<ins cite>
<p>&nbsp;</p>
&nbsp;

Table of Contents

The MS Word table of contents works because the HTML contains anchor links. However, you must replace the <p> tags with list tags if you want to show a hierarchical table of contents.

HTML with <p> tags in the table of contents:




HTML with <p> tags replaced with list tags.

Lists

Word uses <p> tags and &nbsp; (non-breaking space) markup for ordered and unordered lists. The result is a sloppy list. Lists should be fixed up with list tags. For example:

Before:


After:

Links

Saving a Word document as HTML creates links with anchor tags:

<a href = “URL....”>URL</a>

Problem: This format shows up as two links on the wiki, and long URLS cause other text to be "carried" with it, thus creating non-breaking lines.

Solution: remove the <a href = “URL...”></a> and just show the URL.

Before:


After:


Or if the URL is very long, create a text link with the URL embedded:

[URL|Linkname]
Example: [[http://www.ibm.com|IBM]]
Displays as: IBM

Code samples

Use the code sample markup for all code samples. A width value no greater than 600 pixels is recommended because of non-breaking line issues.
Puts a scrollable box around the code sample. See code examples for details.

Images

When porting a Word document to HTML for the wiki, Word creates a subdirectory containing all your images as JPG and GIF files. You need to attach these images to the top of your wiki article. Click "Show attachments", then click the upload button to attach your images.

Note: keep the width of images under 600 pixels, otherwise you may have non-breaking lines

Use Wiki Creole markup

{{Image.jpg|alt text}}
{{Image.jpg|alt text|align="right"}}

Example:

{{directory.jpg|Person entry in LDAP directory}}

Known issues

This section contains a list of the known issues and common mistakes, and tips for working around them.

Word wrap issues

Large images (wider than say 600-800 pixels) and long non-breaking strings such as long URL links will "carry" other text along with it and cut off text on the right. In general an image should be no wider than 600 pixels.

If you run into this problem, decrease the width of images below 600 pixels and put long URLs into clickable text.

Use the code sample markup for all code samples. A width value no greater than 600 pixels is recommended because of non-breaking line issues.
Puts a scrollable box around the code sample. See code examples for details.