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
- Wiki "Textile" @ http://en.wikipedia.org/wiki/Textile_%28markup_language%29.
- "Mylyn WikiText User Guide" @ Eclipse's "Help".