The first order of business is to setup your Ant classpath so you can use the WikiText Ant tasks.

The first order of business is to setup your Ant classpath so you can use the WikiText Ant tasks.

−

You can [http://www.eclipse.org/downloads/download.php?file=/tools/mylyn/update/weekly/mylyn-wikitext-standalone-latest.zip download] the WikiText SDK which contains the jars you'll need. In our case, we only need the org.eclipse.mylyn.wikitext.core_1.3.0.I20100116-0000-e3x.jar and org.eclipse.mylyn.wikitext.mediawiki.core_1.3.0.I20100116-0000-e3x.jar since we are only working with Mediawiki. If we were working with something like confluence, we would have to grab the respective JAR and put it on our classpath.

+

You can [http://www.eclipse.org/downloads/download.php?file=/mylyn/snapshots/nightly/docs/wikitext-standalone-latest.zip download] the WikiText SDK which contains the jars you'll need. In our case, we only need the org.eclipse.mylyn.wikitext.core_1.3.0.I20100116-0000-e3x.jar and org.eclipse.mylyn.wikitext.mediawiki.core_1.3.0.I20100116-0000-e3x.jar since we are only working with Mediawiki. If we were working with something like confluence, we would have to grab the respective JAR and put it on our classpath.

When the Ant task is executed... the wiki content will be transformed into HTML and a respective Eclipse help TOC XML will be generated.

When the Ant task is executed... the wiki content will be transformed into HTML and a respective Eclipse help TOC XML will be generated.

Line 74:

Line 73:

There are two main approaches when it comes to crowdsourcing documentation: '''wiki-based''' and '''file-based'''.

There are two main approaches when it comes to crowdsourcing documentation: '''wiki-based''' and '''file-based'''.

−

In this example, we focus on the wiki-based approach as it's the most collaborative approach. Anyone can contribute to documentation easily and the changes are instantly available online for people to see. The downside to this approach is that contributions are a bit less controlled which could impact quality depending on how a project structures its documentation process and depending on the wiki you choose, version history may be a bit harder to manage. In the file-based approach, the origin of the content is only in the SCM and is transformed during build-time. The plus side to this is it's managed by your existing version control system. The two major downsides are that changes aren't immediately available to your users and that it's much harder to contribute to the documentation since you need to have commit access. There are merits to both approaches and it really depends on your needs. Thankfully, examples for both approaches can be found in the [[#Eclipse.org Reference Projects]] section.

+

In this example, we focus on the wiki-based approach as it's the most collaborative approach. Anyone can contribute to documentation easily and the changes are instantly available online for people to see. The downside to this approach is that contributions are a bit less controlled which could impact quality depending on how a project structures its documentation process and depending on the wiki you choose, version history may be a bit harder to manage.

+

+

In the file-based approach, the origin of the content is only in the SCM and is transformed during build-time. The plus side to this is it's managed by your existing version control system. The two major downsides are that changes aren't immediately available to your users and that it's much harder to contribute to the documentation since you need to have commit access. There are merits to both approaches and it really depends on your needs. Thankfully, examples for both approaches can be found in the [[#Eclipse.org Reference Projects]] section.

=Tips and Tricks=

=Tips and Tricks=

Line 92:

Line 93:

Each of these have their own Help table of contents, which are arranged into a common document via a top-level table of contents with links.

Each of these have their own Help table of contents, which are arranged into a common document via a top-level table of contents with links.

−

You can browse the source code [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.mylyn/org.eclipse.mylyn.help.ui/?root=Tools_Project here]. Pay attention to [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.mylyn/org.eclipse.mylyn.help.ui/build-helper.xml?root=Tools_Project&view=markup build-helper.xml], which drives the generation tasks, and [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.mylyn/org.eclipse.mylyn.help.ui/toc.xml?root=Tools_Project&view=markup toc.xml], which links the generated table of contents into a single document.

+

You can browse the source code [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.mylyn/org.eclipse.mylyn.help.ui/?root=Mylyn_Project here]. Pay attention to [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.mylyn/org.eclipse.mylyn.help.ui/build-helper.xml?root=Mylyn_Project&view=markup build-helper.xml], which drives the generation tasks, and [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.mylyn/org.eclipse.mylyn.help.ui/toc.xml?root=Mylyn_Project&view=markup toc.xml], which links the generated table of contents into a single document.

==EGit==

==EGit==

Line 123:

Line 124:

<stylesheet url="book.css" />

<stylesheet url="book.css" />

<pageAppendum>

<pageAppendum>

−

= Updating This Document =

+

= Updating This Document =

−

This document is maintained in a collaborative wiki. If you wish to

+

This document is maintained in a collaborative wiki. If you wish to

−

update or modify this document please visit {url}

+

update or modify this document please visit {url}

</pageAppendum>

</pageAppendum>

</mediawiki-to-eclipse-help>

</mediawiki-to-eclipse-help>

Line 132:

Line 133:

Classpath/taskdef setup is performed in [https://dev.eclipse.org/svnroot/technology/org.eclipse.osee/trunk/plugins/org.eclipse.osee.framework.help.ui/scripts/help-build-common.xml help-build-common.xml]. Another example of an OSEE help plugin is [https://dev.eclipse.org/svnroot/technology/org.eclipse.osee/trunk/plugins/org.eclipse.osee.ats.help.ui/ org.eclipse.osee.ats.help.ui], which uses the libraries and taskdefs from org.eclipse.osee.framework.help.ui.

Classpath/taskdef setup is performed in [https://dev.eclipse.org/svnroot/technology/org.eclipse.osee/trunk/plugins/org.eclipse.osee.framework.help.ui/scripts/help-build-common.xml help-build-common.xml]. Another example of an OSEE help plugin is [https://dev.eclipse.org/svnroot/technology/org.eclipse.osee/trunk/plugins/org.eclipse.osee.ats.help.ui/ org.eclipse.osee.ats.help.ui], which uses the libraries and taskdefs from org.eclipse.osee.framework.help.ui.

+

+

== PsychoPath XPath 2.0 Processor ==

+

+

The [[PsychoPathXPathProcessor/UserManual | PsychoPath Processor documentation]] is maintained on the eclipse wiki. The documentation is then generated into DocBook format using Mylyn WikiText. The documentation is then cleaned up as some of the conversions do not necessarily fit our specific needs. The Docbook Project's XSL stylesheets are then used to generate the help into a variety of formats including eclipse help.

+

+

* See [[Authoring_Eclipse_Help_Using_DocBook]] for more information on using Docbook to generate the final output produced by WikiText.

+

+

== XSL Tools ==

+

+

Like the Psychopath Processor, the webtools [[XSLT_Project | XSL Tools documentation]] is also available on the wiki and generated back into DocBook format using Mylyn WikiText.

+

+

* See [[Authoring_Eclipse_Help_Using_DocBook]] for more information on using Docbook to generate the final output produced by WikiText.

Introduction

There are many ways to generate help content in Eclipse. One particular method involves generating your help content from the wiki which allows you to crowdsource your documentation. By having your documentation on the wiki, you lower the barrier of entry for people to contribute documentation. The purpose of this wiki entry is to guide you through an example of how you can crowdsource your documentation using Mylyn WikiText.

What is WikiText

Mylyn WikiText provides an extensible framework and tools for parsing, editing and presenting lightweight markup. On top of that, it has a wiki text editor for Eclipse and Ant tasks for converting lightweight markup to HTML and other formats. In this specific example, we will be using WikiText's ability to convert Mediawiki content into Eclipse help content.

A Simple Example

The best way to learn is by doing. As an example, we will take this wiki entry and create some Eclipse help content from it. To accomplish this, we will use Ant so you can easily integrate this into a build if you wish.

Setting up the Classpath

The first order of business is to setup your Ant classpath so you can use the WikiText Ant tasks.

You can download the WikiText SDK which contains the jars you'll need. In our case, we only need the org.eclipse.mylyn.wikitext.core_1.3.0.I20100116-0000-e3x.jar and org.eclipse.mylyn.wikitext.mediawiki.core_1.3.0.I20100116-0000-e3x.jar since we are only working with Mediawiki. If we were working with something like confluence, we would have to grab the respective JAR and put it on our classpath.

Source Code

Other Approaches

There are two main approaches when it comes to crowdsourcing documentation: wiki-based and file-based.

In this example, we focus on the wiki-based approach as it's the most collaborative approach. Anyone can contribute to documentation easily and the changes are instantly available online for people to see. The downside to this approach is that contributions are a bit less controlled which could impact quality depending on how a project structures its documentation process and depending on the wiki you choose, version history may be a bit harder to manage.

In the file-based approach, the origin of the content is only in the SCM and is transformed during build-time. The plus side to this is it's managed by your existing version control system. The two major downsides are that changes aren't immediately available to your users and that it's much harder to contribute to the documentation since you need to have commit access. There are merits to both approaches and it really depends on your needs. Thankfully, examples for both approaches can be found in the #Eclipse.org Reference Projects section.

Tips and Tricks

You can use <pageAppendum> to add some extra information to your documentation.

It's common to add a blurb about how to update the documentation so users can be informed that the documentation they are reading has been generating from the wiki.

Eclipse.org Reference Projects

If you're looking for other examples on how to crowdsource your documentation at Eclipse, the best place is to look and see what other Eclipse.org projects are doing.

Mylyn

Each of these have their own Help table of contents, which are arranged into a common document via a top-level table of contents with links.

You can browse the source code here. Pay attention to build-helper.xml, which drives the generation tasks, and toc.xml, which links the generated table of contents into a single document.

EGit

The EGit project uses a single wiki page on Eclipsepedia for its documentation.

Check out the org.eclipse.egit.doc plug-in.

Xtext

The Xtext project uses a Textile and Wikitext for its documentation. The code is available in the org.eclipse.xtext.doc plug-in. The documentation is sourced from various Textile files stored in source control and then transformed at build-time. This is different from the previous two examples which used the wiki as the source of documentation.

OSEE

For modularity reasons, the OSEE project has multiple help projects which generate Eclipse online help from different parts of the OSEE wiki. The central help plugin is org.eclipse.osee.framework.help.ui, which contains a build-helper.xml file that calls mediawiki-to-eclipse-help and specifies the different help chapters:

<mediawiki-to-eclipse-helpwikiBaseUrl="${osee.help.doc.url.base}"validate="true"failonvalidationerror="true"prependImagePrefix="images"formatoutput="true"defaultAbsoluteLinkTarget="osee_external"dest="${basedir}"navigationimages="true"title="OSEE User's Guide"generateUnifiedToc="true"><pathname="OSEE/Users_Guide/Getting_Started"title="Introduction"/><pathname="OSEE/Users_Guide/Concepts"title="Concepts"/><pathname="OSEE/Users_Guide/Features"title="Features"/><pathname="OSEE/Users_Guide/Tips"title="Tips"/><pathname="OSEE/Users_Guide/New"title="New"/><stylesheeturl="book.css"/><pageAppendum>
= Updating This Document =
This document is maintained in a collaborative wiki. If you wish to
update or modify this document please visit {url}
</pageAppendum></mediawiki-to-eclipse-help>

PsychoPath XPath 2.0 Processor

The PsychoPath Processor documentation is maintained on the eclipse wiki. The documentation is then generated into DocBook format using Mylyn WikiText. The documentation is then cleaned up as some of the conversions do not necessarily fit our specific needs. The Docbook Project's XSL stylesheets are then used to generate the help into a variety of formats including eclipse help.