TABLE OF CONTENTS (HIDE)

How to Write Wiki Text

Introduction

Wiki text is best suit writing documentation during software development, because:

  • It has only a few markups (compared with hundreds of markups in HTML), for marking up heading, paragraph, list, link, table and image. During software development, you really have no time (and no energy) to write a proper HTML documentation. On the other hand, writing plain text with text editor is not really readable. Wiki text strikes a balance between HTML and plain text.
  • [TODO] more.

There are many markup format for wiki text. I shall describe the "textile" format, which is supported by Eclipse.

Eclipse Mylyn WikiText (for Textile Markup)

Installation

Eclipse comes with Mylyn WikiText for creating wiki pages. Read "Mylyn WikiText User Guide" @ eclipse "Help" ⇒ "Help Contents".

On my Ubuntu 13.04, the preview pane is missing. I could fix it by installing "libwebkitgtk-1.0-0". However, that causes Eclipse to crash frequently. I have yet to fix this problem.

Setting up Wiki Locally in Eclipse with Remote Repo

Step 1: In the remote repo, enable "wiki" for your project.

Step 2: Create a local folder for the wiki documentation (says "olas-doc").

Step 3: Clone the Wiki GIT from remote Repo into "olas-doc".

$ cd /path/to/olas-doc
$ git clone https://xxxx@xxxx.org/xxxx/olas.git/wiki

Step 4: In Eclipse, create a project (File ⇒ New ⇒ Project... ⇒ General ⇒ Project) called "olas-doc" at the "olas-doc" folder. All the existing files will be pulled into the project.

Step 5: Create new wiki pages (File ⇒ New ⇒ File ⇒ "test.textile").

Step 6 Commit.

$ cd /path/to/olas-doc
$ git status
$ git add *.textile
$ git commit -m "First commit"

Step 7: Push to remote Repo.

// The remote name "origin" created after clone.
$ git push -u origin master

Step 8: View your new pages at the remote repo.

Step 9: Rename "Home.md" to "Home.textile" (if textile markup is to be used for the Home page), and tailor the page.

Example

[TODO]

Commonly-used Markup Tags for Textile markup

In Eclipse, push F1 to get the WikiText cheat-sheet.

_emphasis_  emphasis 
__italic__  italic   
*strong*    strong   
**bold**    bold  
@code@      code  
hn.         Heading  
p.          Paragraph (optional)    
pre.        Pre-formatted  
bc.         pre code
# ## ###    Numeric list   
* ** ***    Bullet list  
"title":http://www.example.com             Link
!images/logo.png!                          Image
!images/logo.png!:http://www.example.com   Image Link
|_. a|_. table|_. header|                  Table
|a|table|row|
|a|table|row|

REFERENCES & RESOURCES

  1. Wiki "Textile" @ http://en.wikipedia.org/wiki/Textile_%28markup_language%29.
  2. "Mylyn WikiText User Guide" @ Eclipse's "Help".