Some Eclipse Foundation services are deprecated, or will be soon. Please ensure you've read this important communication.
View | Details | Raw Unified | Return to bug 244215
Collapse All | Expand All

(-)help/Mylyn WikiText User Guide.textile (-275 / +1 lines)
Lines 1-275 Link Here
1
h1. Overview
1
h1. Overview

This guide provides basic instructions on the use of WikiText.  
WikiText provides extensions to the Mylyn task editor supporting "lightweight markup languages":http://www.wikipedia.com/Lightweight_Markup such as Textile and MediaWiki.  WikiText also provides a wiki text editor for Eclipse and Ant tasks for converting lightweight markup to HTML and other formats.

h2. Table of Contents

{toc}

h1. Getting Started

The WikiText plug-in provides a lightweight markup editor for Eclipse.  The editor is registered against all files with the following file extensions: @*.textile@, @*.tracwiki@, @*.mediawiki@, @*.confluence@

It's also possible to register the editor with other file extensions by setting the Eclipse preferences under *General->Other->File Associations*.

h2. Creating A New File

Using the new file wizard, choose *New->File*, or *New->Other...->General->File*.  In the
filename field, enter the name of the file with a @.textile@ or other registered extension.  

When the new file is created it should open in the WikiText editor.  Start typing!!

h2. WikiText Editor Overview

The WikiText editor provides a source view, preview and outline.

!images/editor-overview.png!

The editor has tabs on the bottom that facilitate switching to and from 'Source' and 'Preview'.

!images/editor-tabs.png!

h3. Markup Source Tab

'Source' is the default editor pane.  This is the area for editing markup such as Textile.   The source pane provides syntax highlighting that should make it easier to see what the markup means.

Standard text editor actions are available here, such as copy/paste and find/replace.  Explore the context menu and 'Edit' menu to see what actions are available.

h3. Preview Tab

The editor preview provides a preview of the wiki markup as it is rendered by your default browser after converting the markup to HTML.  Though the 'Source' syntax highlighting is pretty good, the preview provides a more accurate view of the rendered result.

h3. Outline

The editor outline provides a structured view of the markup source.  Headings in the markup are used to provide a 'Table of Contents'.  

!images/editor-outline.png!

Clicking on an item in the outline will show the corresponding header in the source, and navigating in the source will cause the most relevant item in the outline to be selected.

Note that clicking on an item in the outline has no effect if the editor preview is showing.

h2. Switching Markup Languages

The WikiText editor supports multiple markup languages.  The editor makes a best-guess at the markup language from the file extension.  To switch markup languages in the editor invoke the context menu *Markup Languages* and select the language:

!images/editor-switch-language.png!

The editor will remember your selection the next time the same file is opened.

h2. Accessing the Markup Cheat-Sheet

The editor provides a markup 'cheat-sheet'.  The cheat-sheet is a quick-reference for markup syntax.  To access the cheat-sheet press *F1* in the source view of the editor.

Note that the content of the cheat-sheet will vary according to the markup language being displayed. 

!images/editor-cheat-sheet.png!

h1. Task Editor Integration

WikiText extends Mylyn to provide a markup-aware task editor.  With WikiText installed, Mylyn can render wiki markup as intended, provide markup-specific syntax highlighting, content-assist, validation, and a cheat-sheet for wiki markup syntax.

_TODO: complete this section_

h1. Markup Conversion

Lightweight markup is designed to be readily converted to HTML.  WikiText provides a means to convert markup to:

* HTML
* "DocBook":http://www.docbook.org
* Eclipse help format (HTML and @toc.xml@)

h2. Conversion In Eclipse

These conversions can be made by right-clicking any @.textile@, @.mediawiki@, or @.tracwiki@ resource in the Eclipse UI: 

!images/resource-conversion-menu.png!

Performing a conversion from the UI will cause corresponding files (@*.xml@, @*.html@, @*-toc.xml@) to be created in the same folder as the selected file(s).

More control over the conversion process can be achieved by using Ant build scripts (described below).

h2. Conversion using Ant build scripts

"Ant":http://www.apache.org build scripts may also be used to drive a markup conversion.  The following is an example of how to drive conversion from Textile markup to Eclipse help format (to HTML and toc.xml):

bc.. 
	<path id="wikitext.classpath">
		<fileset dir="${eclipse.home}/plugins">
			<include name="org.eclipse.mylyn.wikitext.*core.jar"/>
		</fileset>
	</path>

	<taskdef classpathref="wikitext.classpath" resource="org/eclipse/mylyn/wikitext/core/util/anttask/tasks.properties" />
	
	<target name="generate-help" depends="init" description="Generate Eclipse help from textile source">
		<wikitext-to-eclipse-help markupLanguage="Textile" 
			multipleOutputFiles="true"
			navigationImages="true">
			<fileset dir="${basedir}">
    				<include name="help/*.textile"/>
			</fileset>
			<stylesheet url="styles/help.css"/>
			<stylesheet url="styles/main.css"/>
		</wikitext-to-eclipse-help>
	</target>

p. Similar Ant scripts can be used to convert to HTML:

bc. 	
	<target name="generate-html" depends="init" description="Generate HTML from textile source">
		<wikitext-to-html markupLanguage="Textile">
			<fileset dir="${basedir}">
    				<include name="help/*.textile"/>
			</fileset>
			<stylesheet url="styles/main.css"/>
		</wikitext-to-html>
	</target>

Conversion using Ant is used by the WikiText project to create help content.  We find that writing help content in Textile markup is much easier than writing DocBook or HTML.

The @<stylesheet>@ entries in the above examples are optional; these cause an HTML link to one or more stylesheets to be added to the head of the generated HTML document.

h3. DocBook

You can use WikiText first to convert your Textile markup to "DocBook":http://www.docbook.org then use the "DocBook XSL stylesheets":http://docbook.sourceforge.net/ to convert the DocBook to Eclpse help content, HTML, pdf or other formats.  For more information on using the DocBook XSL stylesheets please refer to the "DocBook XSL project":http://docbook.sourceforge.net/

h1. Textile Syntax

The WikiText editor supports most standard Textile markup.  In addition some markup extensions are supported.  See the markup 'cheat-sheet' for details (press *F1* in the editor).

h2. Textile Syntax Tips

h3. Whitespace

Textile markup is sensitive to whitespace.  For example, a line that starts with '@{color:blue;}h1.@' is only a heading if the '@{color:blue;}h1.@' is immediately followed by a space character.  This can bite you if you're not careful!  

A less obvious example of the same problem is with '@{color:blue;}bc.@'  Usually content in a 'block code' section is on the line following the '@{color:blue;}bc.@'  If the '@{color:blue;}bc.@' is not immediately followed by a space character _before the end of the line_, then the area is simply considered a normal paragraph.

h3. HTML Literals

Textile markup can handle literal HTML.  For example, the following is valid Textile:

bc. 
some <b>bold text</b> here

Care must be taken with literal HTML: the start tag must be completed on one line, and the end tag must be completed on one line.  The following is an example of embedded HTML that won't work with Textile:

bc. 
here is <a
href="#">a bad example</a>

The above example can be fixed by moving the @href@ up on to the same line as the @<a@ portion:

bc. 
here is <a href="#">a working example</a>

h3. Images and DocBook

When handling images in a conversion of Textile markup to DocBook markup, there are several choices for the resulting DocBook markup.  By default images are converted as follows:

bc. 
!images/foo.png!

results in:

bc. 
<mediaobject><imageobject><imagedata fileref=\"images/foo.png\"/></imageobject></mediaobject>

@<mediaobject/>@ is useful for some cases, however there are times when @<inlinemediaobject/>@ should be used instead.  To achieve this result, add the @inline@ class to your image as follows:

bc. 
!(inline)images/foo.png!

The conversion will then result in the following:

bc. 
<inlinemediaobject><imageobject><imagedata fileref=\"images/foo.png\"/></imageobject></inlinemediaobject> 

h2. Examples

This document was written in Textile markup.  The original source code for this document "is available here":http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.mylyn/sandbox/org.eclipse.mylyn.wikitext.ui/help/Mylyn%20WikiText%20User%20Guide.textile?root=Tools_Project&view=markup

h1. Tips and Tricks

h2. Hot-Keys

To get a pop-up showing the list of available hot-keys and commands, press *CTRL+SHIFT+l* (or *COMMAND+SHIFT+l* on a mac)

!images/editor-command-help.png!

h2. Word Completion

Word completion is available from within the Textile editor.  Press *CTRL+.* (that is CTRL + '.', the dot character) repeatedly to see available completions from the current cursor position.

Word completion is based on the "Hippie":http://www.xemacs.org/Documentation/packages/html/edit-utils_23.html algorithm, which finds existing words in the editing context and uses them to create completion proposals.

h2. Spelling

Spell checking is enabled by default in the Textile editor.  Pressing *CTRL+1* on a spelling issue will provide options for dealing with the spelling problem.

!images/editor-spelling.png!

h2. Content Assist

Content assist is available by pressing *CTRL+SPACE*.  Content assist will make suggestions based on the cursor position.  If only one proposal is available at the cursor position, the content will be filled in automatically, otherwise a list of proposals is shown.

Continued typing while the proposals are displayed will narrow the list of available choices.  A selection can be made with the mouse, or by using the up/down arrows and the enter key.

!images/editor-assist-proposals.png!

h3. Template-Based Content Assist

Content assist may also make proposals involving templates with variables.

!images/editor-assist-template-proposal-selection.png!

When such a proposal is selected the variables are displayed with a surrounding box.  Typing replaces the variable content, the *TAB* key advances to the next variable position, and the *ENTER* or *ESC* keys complete the template editing session.  The vertical line displayed at the end of the template shows where the cursor will be located when finished.

!images/editor-assist-template-proposal.png!

Note that while editing a template the standard undo/redo functionality is still available to you.

h3. Selection and Content Assist

Content assist may be invoked with selected text.  To do so, select text using the mouse or keyboard, and then press *CTRL+SPACE*.  Content assist is activated with the current selection.

Selecting a template-based content proposal will cause the selected text to be included in the template.  The following shows a selection and content assist proposals before selecting a proposal:

!images/editor-assist-selection-proposal.png!

The following shows the same text after selecting a proposal:

!images/editor-assist-selection-proposal-completed.png!

The selected text in this case is wrapped in '*' characters for the 'strong' Textile markup.

h1. Preferences

WikiText editor preferences may be configured via the Eclipse preferences dialog.  CSS styles are used to modify the markup syntax highlighting in the editor:

!images/editor-preferences.png!

The following CSS styles are recognized:

| @color@ | named or rgb(r,g,b) |
| @background-color@ | named or rgb(r,g,b) |
| @font-family@ | monospace, courier, courier new |
| @font-style@ | italic, bold, normal |
| @font-weight@ | bold, bolder, normal, lighter |
| @font-size@ | percentage, named size, or absolute size (pt or px) |
| @text-decoration@ | none, line-through, underline |
| @vertical-align@ | super, sub |

h1. More Information

More information about WikiText can be accessed from the "Mylyn WikiText Homepage":http://wiki.eclipse.org/Mylyn/Incubator/WikiText

h2. Feedback

We're interested to hear of any feedback that you might have.  For patches, enhancement requests, bugs: "post an issue":https://bugs.eclipse.org/bugs

p{font-style: italic;}. Copyright (c) 2008 David Green and others.
All rights reserved. This program and the accompanying materials are made available under the terms of the Eclipse Public License v1.0 which accompanies this distribution, and is available at "http://www.eclipse.org/legal/epl-v10.html":http://www.eclipse.org/legal/epl-v10.html
2
3
This guide provides basic instructions on the use of WikiText.  
4
WikiText provides extensions to the Mylyn task editor supporting "lightweight markup languages":http://www.wikipedia.com/Lightweight_Markup such as Textile and MediaWiki.  WikiText also provides a wiki text editor for Eclipse and Ant tasks for converting lightweight markup to HTML and other formats.
5
6
h2. Table of Contents
7
8
{toc}
9
10
h1. Getting Started
11
12
The WikiText plug-in provides a lightweight markup editor for Eclipse.  The editor is registered against all files with the following file extensions: @*.textile@, @*.tracwiki@, @*.mediawiki@, @*.confluence@
13
14
It's also possible to register the editor with other file extensions by setting the Eclipse preferences under *General->Other->File Associations*.
15
16
h2. Creating A New File
17
18
Using the new file wizard, choose *New->File*, or *New->Other...->General->File*.  In the
19
filename field, enter the name of the file with a @.textile@ or other registered extension.  
20
21
When the new file is created it should open in the WikiText editor.  Start typing!!
22
23
h2. WikiText Editor Overview
24
25
The WikiText editor provides a source view, preview and outline.
26
27
!images/editor-overview.png!
28
29
The editor has tabs on the bottom that facilitate switching to and from 'Source' and 'Preview'.
30
31
!images/editor-tabs.png!
32
33
h3. Markup Source Tab
34
35
'Source' is the default editor pane.  This is the area for editing markup such as Textile.   The source pane provides syntax highlighting that should make it easier to see what the markup means.
36
37
Standard text editor actions are available here, such as copy/paste and find/replace.  Explore the context menu and 'Edit' menu to see what actions are available.
38
39
h3. Preview Tab
40
41
The editor preview provides a preview of the wiki markup as it is rendered by your default browser after converting the markup to HTML.  Though the 'Source' syntax highlighting is pretty good, the preview provides a more accurate view of the rendered result.
42
43
h3. Outline
44
45
The editor outline provides a structured view of the markup source.  Headings in the markup are used to provide a 'Table of Contents'.  
46
47
!images/editor-outline.png!
48
49
Clicking on an item in the outline will show the corresponding header in the source, and navigating in the source will cause the most relevant item in the outline to be selected.
50
51
Note that clicking on an item in the outline has no effect if the editor preview is showing.
52
53
h2. Switching Markup Languages
54
55
The WikiText editor supports multiple markup languages.  The editor makes a best-guess at the markup language from the file extension.  To switch markup languages in the editor invoke the context menu *Markup Languages* and select the language:
56
57
!images/editor-switch-language.png!
58
59
The editor will remember your selection the next time the same file is opened.
60
61
h2. Accessing the Markup Cheat-Sheet
62
63
The editor provides a markup 'cheat-sheet'.  The cheat-sheet is a quick-reference for markup syntax.  To access the cheat-sheet press *F1* in the source view of the editor.
64
65
Note that the content of the cheat-sheet will vary according to the markup language being displayed. 
66
67
!images/editor-cheat-sheet.png!
68
69
h1. Task Editor Integration
70
71
WikiText extends Mylyn to provide a markup-aware task editor.  With WikiText installed, Mylyn can render wiki markup as intended, provide markup-specific syntax highlighting, content-assist, validation, and a cheat-sheet for wiki markup syntax.
72
73
_TODO: complete this section_
74
75
h1. Markup Conversion
76
77
Lightweight markup is designed to be readily converted to HTML.  WikiText provides a means to convert markup to:
78
79
* HTML
80
* "DocBook":http://www.docbook.org
81
* Eclipse help format (HTML and @toc.xml@)
82
83
h2. Conversion In Eclipse
84
85
These conversions can be made by right-clicking any @.textile@, @.mediawiki@, or @.tracwiki@ resource in the Eclipse UI: 
86
87
!images/resource-conversion-menu.png!
88
89
Performing a conversion from the UI will cause corresponding files (@*.xml@, @*.html@, @*-toc.xml@) to be created in the same folder as the selected file(s).
90
91
More control over the conversion process can be achieved by using Ant build scripts (described below).
92
93
h2. Conversion using Ant build scripts
94
95
"Ant":http://www.apache.org build scripts may also be used to drive a markup conversion.  The following is an example of how to drive conversion from Textile markup to Eclipse help format (to HTML and toc.xml):
96
97
bc.. 
98
	<path id="wikitext.classpath">
99
		<fileset dir="${eclipse.home}/plugins">
100
			<include name="org.eclipse.mylyn.wikitext.*core.jar"/>
101
		</fileset>
102
	</path>
103
104
	<taskdef classpathref="wikitext.classpath" resource="org/eclipse/mylyn/wikitext/core/util/anttask/tasks.properties" />
105
	
106
	<target name="generate-help" depends="init" description="Generate Eclipse help from textile source">
107
		<wikitext-to-eclipse-help markupLanguage="Textile" 
108
			multipleOutputFiles="true"
109
			navigationImages="true">
110
			<fileset dir="${basedir}">
111
    				<include name="help/*.textile"/>
112
			</fileset>
113
			<stylesheet url="styles/help.css"/>
114
			<stylesheet url="styles/main.css"/>
115
		</wikitext-to-eclipse-help>
116
	</target>
117
118
p. Similar Ant scripts can be used to convert to HTML:
119
120
bc. 	
121
	<target name="generate-html" depends="init" description="Generate HTML from textile source">
122
		<wikitext-to-html markupLanguage="Textile">
123
			<fileset dir="${basedir}">
124
    				<include name="help/*.textile"/>
125
			</fileset>
126
			<stylesheet url="styles/main.css"/>
127
		</wikitext-to-html>
128
	</target>
129
130
Conversion using Ant is used by the WikiText project to create help content.  We find that writing help content in Textile markup is much easier than writing DocBook or HTML.
131
132
The @<stylesheet>@ entries in the above examples are optional; these cause an HTML link to one or more stylesheets to be added to the head of the generated HTML document.
133
134
h3. DocBook
135
136
You can use WikiText first to convert your Textile markup to "DocBook":http://www.docbook.org then use the "DocBook XSL stylesheets":http://docbook.sourceforge.net/ to convert the DocBook to Eclpse help content, HTML, pdf or other formats.  For more information on using the DocBook XSL stylesheets please refer to the "DocBook XSL project":http://docbook.sourceforge.net/
137
138
h1. Textile Syntax
139
140
The WikiText editor supports most standard Textile markup.  In addition some markup extensions are supported.  See the markup 'cheat-sheet' for details (press *F1* in the editor).
141
142
h2. Textile Syntax Tips
143
144
h3. Whitespace
145
146
Textile markup is sensitive to whitespace.  For example, a line that starts with '@{color:blue;}h1.@' is only a heading if the '@{color:blue;}h1.@' is immediately followed by a space character.  This can bite you if you're not careful!  
147
148
A less obvious example of the same problem is with '@{color:blue;}bc.@'  Usually content in a 'block code' section is on the line following the '@{color:blue;}bc.@'  If the '@{color:blue;}bc.@' is not immediately followed by a space character _before the end of the line_, then the area is simply considered a normal paragraph.
149
150
h3. HTML Literals
151
152
Textile markup can handle literal HTML.  For example, the following is valid Textile:
153
154
bc. 
155
some <b>bold text</b> here
156
157
Care must be taken with literal HTML: the start tag must be completed on one line, and the end tag must be completed on one line.  The following is an example of embedded HTML that won't work with Textile:
158
159
bc. 
160
here is <a
161
href="#">a bad example</a>
162
163
The above example can be fixed by moving the @href@ up on to the same line as the @<a@ portion:
164
165
bc. 
166
here is <a href="#">a working example</a>
167
168
h3. Images and DocBook
169
170
When handling images in a conversion of Textile markup to DocBook markup, there are several choices for the resulting DocBook markup.  By default images are converted as follows:
171
172
bc. 
173
!images/foo.png!
174
175
results in:
176
177
bc. 
178
<mediaobject><imageobject><imagedata fileref=\"images/foo.png\"/></imageobject></mediaobject>
179
180
@<mediaobject/>@ is useful for some cases, however there are times when @<inlinemediaobject/>@ should be used instead.  To achieve this result, add the @inline@ class to your image as follows:
181
182
bc. 
183
!(inline)images/foo.png!
184
185
The conversion will then result in the following:
186
187
bc. 
188
<inlinemediaobject><imageobject><imagedata fileref=\"images/foo.png\"/></imageobject></inlinemediaobject> 
189
190
h2. Examples
191
192
This document was written in Textile markup.  The original source code for this document "is available here":http://TODO-PROVIDE-URL-TO-DOCUMENT-SOURCE-ONLINE
193
194
h1. Tips and Tricks
195
196
h2. Hot-Keys
197
198
To get a pop-up showing the list of available hot-keys and commands, press *CTRL+SHIFT+l* (or *COMMAND+SHIFT+l* on a mac)
199
200
!images/editor-command-help.png!
201
202
h2. Word Completion
203
204
Word completion is available from within the Textile editor.  Press *CTRL+.* (that is CTRL + '.', the dot character) repeatedly to see available completions from the current cursor position.
205
206
Word completion is based on the "Hippie":http://www.xemacs.org/Documentation/packages/html/edit-utils_23.html algorithm, which finds existing words in the editing context and uses them to create completion proposals.
207
208
h2. Spelling
209
210
Spell checking is enabled by default in the Textile editor.  Pressing *CTRL+1* on a spelling issue will provide options for dealing with the spelling problem.
211
212
!images/editor-spelling.png!
213
214
h2. Content Assist
215
216
Content assist is available by pressing *CTRL+SPACE*.  Content assist will make suggestions based on the cursor position.  If only one proposal is available at the cursor position, the content will be filled in automatically, otherwise a list of proposals is shown.
217
218
Continued typing while the proposals are displayed will narrow the list of available choices.  A selection can be made with the mouse, or by using the up/down arrows and the enter key.
219
220
!images/editor-assist-proposals.png!
221
222
h3. Template-Based Content Assist
223
224
Content assist may also make proposals involving templates with variables.
225
226
!images/editor-assist-template-proposal-selection.png!
227
228
When such a proposal is selected the variables are displayed with a surrounding box.  Typing replaces the variable content, the *TAB* key advances to the next variable position, and the *ENTER* or *ESC* keys complete the template editing session.  The vertical line displayed at the end of the template shows where the cursor will be located when finished.
229
230
!images/editor-assist-template-proposal.png!
231
232
Note that while editing a template the standard undo/redo functionality is still available to you.
233
234
h3. Selection and Content Assist
235
236
Content assist may be invoked with selected text.  To do so, select text using the mouse or keyboard, and then press *CTRL+SPACE*.  Content assist is activated with the current selection.
237
238
Selecting a template-based content proposal will cause the selected text to be included in the template.  The following shows a selection and content assist proposals before selecting a proposal:
239
240
!images/editor-assist-selection-proposal.png!
241
242
The following shows the same text after selecting a proposal:
243
244
!images/editor-assist-selection-proposal-completed.png!
245
246
The selected text in this case is wrapped in '*' characters for the 'strong' Textile markup.
247
248
h1. Preferences
249
250
WikiText editor preferences may be configured via the Eclipse preferences dialog.  CSS styles are used to modify the markup syntax highlighting in the editor:
251
252
!images/editor-preferences.png!
253
254
The following CSS styles are recognized:
255
256
| @color@ | named or rgb(r,g,b) |
257
| @background-color@ | named or rgb(r,g,b) |
258
| @font-family@ | monospace, courier, courier new |
259
| @font-style@ | italic, bold, normal |
260
| @font-weight@ | bold, bolder, normal, lighter |
261
| @font-size@ | percentage, named size, or absolute size (pt or px) |
262
| @text-decoration@ | none, line-through, underline |
263
| @vertical-align@ | super, sub |
264
265
h1. More Information
266
267
More information about WikiText can be accessed from the "Mylyn WikiText Homepage":http://wiki.eclipse.org/Mylyn/Incubator/WikiText
268
269
h2. Feedback
270
271
We're interested to hear of any feedback that you might have.  For patches, enhancement requests, bugs: "post an issue":https://bugs.eclipse.org/bugs
272
273
p{font-style: italic;}. Copyright (c) 2008 David Green and others.
274
All rights reserved. This program and the accompanying materials are made available under the terms of the Eclipse Public License v1.0 which accompanies this distribution, and is available at "http://www.eclipse.org/legal/epl-v10.html":http://www.eclipse.org/legal/epl-v10.html
275

Return to bug 244215