(e)Wiki – A model based Wiki framework

1. What’s Wiki with a (e)?

(e)Wiki is a Wiki markup generation framework based on Mylyn WikiText and EMF. The framework allows to read and write different Wiki markup formats – this time, the model driven way. If you have an existing model based tool chain, the framework could easily fit in there to generate some quick documentation, without worrying about markups. You could reuse all the WikiText markup parsers and document builders, combined with the power of EMF features like EMF persistence, EMF notification etc.

The framework was developed as part of a customer project to generate Wiki documentation out of EMF based domain models. The framework is currently not open sourced and made available to public. Talks are on with the customer on this however.

The article gives an overview about the framework and its features. The intention of the article is also to demonstrate the extensibility of two powerful Eclipse frameworks - Mylyn WikiText and EMF.

2. Architecture

(e)Wiki is an addon to Mylyn WikiText. WikiText is a framework which supports parsing/editing Wiki markup formats like MediaWiki, Textile, Confluence, TracWiki and TWiki and writing them as HTML, Eclipse Help, DocBook, DITA and XSL-FO. WikiText however doesn’t have an internal data model for documents (like DOM for XML). (e)Wiki adds this missing layer to the WikiText framework. Instead of using a POJO data model, (e)Wiki uses a powerful EMF based metamodel. Using (e)Wiki you could read all the above markup formats and generate a (e)WikiModel based on EMF. The model could then be written out using any of the WikiText document builders.

3. (e)WikiModel

(e)WikiModel is an EMF based Wiki metamodel. It is a generic metamodel for any Wiki Language.

(Only partial model is shown above)

(e)WikiModel is not aimed to be used as a DSL for your domain. It is intended to capture the documentation aspects of your domain model. To better describe semantic information use a DSL of your own using a framework like Xtext.

4. Features

(e)Wiki currently delivers the following:

• A metamodel for Wiki called (e)WikiModel
• (e)WikiEditor to view/edit (e)Wiki files
• Previewing of rendered (e)Wiki content
• UI extensions to convert existing markups to (e)WikiModel
• Generating Textile and Redmine markup (together with HTML and Docbook as already supported by WikiText)
• Feature to split generated Textile and Redmine markup files into subpages
• Add Table of Contents to generated output

5. Working with (e)Wiki

5.1. Creating a (e)WikiModel

A (e)Wiki instance could be created either from Eclipse UI or programatically.

5.1.1. Creating from UI

Create a markup file within the eclipse workspace.

Right click the markup file and invoke eWiki -> Generate eWiki.

An (e)Wiki file is created in the same folder as selected file with extension .ewiki.

5.1.2. Creating with code

WikiText is based on “Builder” design pattern. (e)Wiki uses the same pattern and adds a new DocmentBuilder, the EWikiDocumentBuilder. The snippet below shows how to convert existing markup (Textile in this case) to (e)Wiki.

final String markup = "h1. Quisque"

final ResourceSet resourceSet = new ResourceSetImpl();
final Resource eWikiResource = resourceSet.createResource (URI.createFileURI("..."));

MarkupParser parser = new MarkupParser();
parser.setMarkupLanguage(new TextileLanguage());
EWikiDocumentBuilder eWikiDocumentBuilder = new EWikiDocumentBuilder(eWikiResource);
parser.setBuilder(eWikiDocumentBuilder);
parser.parse(markup);

eWikiResource.save(Collections.EMPTY_MAP);

The snippet below shows how to create a (e)WikiModel using model APIs. If you have worked with EMF generated model API code, this is no different, except that (e)Wiki adds additional convenient factory methods.

final ResourceSet resourceSet = new ResourceSetImpl();
final Resource eWikiResource = resourceSet.createResource (URI.createFileURI("..."));
Document document = EwikiFactory.eINSTANCE.createDocument();
document.setTitle("Lorem ipsum");

EwikiFactory.eINSTANCE.createHeading(document, 1, "Quisque");

Paragraph paragraph = EwikiFactory.eINSTANCE.createParagraph();
document.getSegments().add(paragraph);
EwikiFactory.eINSTANCE.createText(paragraph, "Lorem ipsum dolor sit amet, consectetur adipiscing elit.");

BullettedList bullettedList = EwikiFactory.eINSTANCE.createBullettedList();
document.getSegments().add(bullettedList);
EwikiFactory.eINSTANCE.createListItem(bullettedList,"Mauris");
EwikiFactory.eINSTANCE.createListItem(bullettedList,"Etiam");

eWikiResource.getContents().add(document);
eWikiResource.save(Collections.EMPTY_MAP);

5.2. (e)WikiEditor

The (e)WikiEditor provides a tree based editor and a preview tab.

5.2.1. Tree editor tab

The tree editor provides a tree view of the (e)Wiki file. Although the editor could be used to change the file, it is rare that rich text would be edited in this way.

5.2.2. Preview tab

The preview tab provides a preview of the (e)Wiki file as rendered by your default browser.

5.3. Generating output

The (e)Wiki file could be converted to HTML, Docbook, Textile and Redmine markup formats.

5.3.1. Generating output from UI

Right clicking the (e)Wiki file brings up the context menu for conversions.

5.3.2. Generating output from Code

You could use any of the existing DocumentBuilders in WikiText to generate output from a (e)WikiModel. The snippet below shows how to convert an (e)Wiki instance to HTML programatically using the WikiText HTMLDocumentBuilder.

final IFile eWikiFile = ...;
ResourceSet resourceSet = new ResourceSetImpl();
final Resource wikiResource = resourceSet.getResource(URI.createFileURI(eWikiFile.getRawLocation().toOSString()), true);
StringWriter writer = new StringWriter();

EWikiParser parser = new EWikiParser();
parser.setMarkupLanguage(new EWikiLanguage());
parser.setBuilder(new HTMLDocumentBuilder(writer));
parser.parse(wikiResource);

final String htmlContent = writer.toString();