Attachment 110017 Details for Bug 244215 – a patch that replaces the hyperlink

Some Eclipse Foundation services are deprecated, or will be soon. Please ensure you've read this important communication.

[patch] a patch that replaces the hyperlink

doc-sample-href.patch (text/plain), 25.27 KB, created by David Green

on 2008-08-14 14:07:55 EDT

(hide)

Description:

Filename:

MIME Type:

Creator: David Green

Created: 2008-08-14 14:07:55 EDT

Size: 25.27 KB

patch

obsolete

>### Eclipse Workspace Patch 1.0
>#P org.eclipse.mylyn.wikitext.ui
>Index: help/Mylyn WikiText User Guide.textile
>===================================================================
>RCS file: /cvsroot/tools/org.eclipse.mylyn/sandbox/org.eclipse.mylyn.wikitext.ui/help/Mylyn WikiText User Guide.textile,v
>retrieving revision 1.2
>diff -u -r1.2 Mylyn WikiText User Guide.textile
>--- help/Mylyn WikiText User Guide.textile	12 Aug 2008 21:05:33 -0000	1.2
>+++ help/Mylyn WikiText User Guide.textile	14 Aug 2008 18:05:59 -0000
>@@ -1,275 +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://TODO-PROVIDE-URL-TO-DOCUMENT-SOURCE-ONLINE
>-
>-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
>-
>+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>

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:

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

>\ No newline at end of file

Actions: View | Diff

Attachments on bug 244215: 110017