Skip to main content

Notice: This Wiki is now read only and edits are no longer possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Mylyn/WikiText/AsciiDoc

AsciiDoc support for Mylyn WikiText

AsciiDoc is "AsciiDoc is a text document format for writing notes, documentation, articles, books, ebooks, slideshows, web pages, man pages and blogs". Recently it has gained popularity as a more flexible and powerful form for markup via the project.

The main bugzilla entry for AsciiDoc support is #418563 which started to merged into WikiText in Eclipse Mars development cycle.

For now Mylyn WikiText will not ship with AsciiDoc syntax support by default. But it is available from "WikiText Extras" feature from the Mylyn nightly snapshots.

Below are the installations steps for this and further down some info about the current state of the feature.

Installation

  1. Go to Help / Install new software...
  2. Click on Add button and fill repository URL into Location field as http://download.eclipse.org/mylyn/snapshots/nightly/docs/ (name it as you want e.g. "Mylyn WikiText nightly").
    Creole wikitext Add Repository.png
  3. After a monent check Mylyn WikiText Extras feature and proceed with Next button.
    Creole wikitext install.png
  4. Agree with licence and so on.
  5. During installation you will be asked to confirm install unsigned content. Continue with OK button.
    Creole wikitext security warn.png
  6. Restart Eclipse IDE
  7. Create new file with .adoc file extension and you are done.


Asciidoc wikitext editor.png

Features

AsciiDoc in Eclipse is done as a language added to Mylyn WikiText. Meaning it out of the box have four main features:

  • Source editor with basic syntax highlighting
  • Preview page showing generated page using the WikiText AsciiDoc parser
  • Outline support in the the Outline view and Cmd+o/Ctrl+o pop up for quick navigation
  • Content assist with templates for commong asciidoc syntax

Furthermore the implementation can be used standalone (wikitext engine is in pure java), but this have not been fully tested yet as for now the major features implemented are just to have a decent editor support. But in theory if someone wanted to the implementation could be used to cover all of AsciiDoc.

Syntax supported

For now the following basic features are covered:

  • Basic formatting (italic, bold, strong, etc.)
  • Heading for different levels
  • Lists, see #481670

Incoming features (https://git.eclipse.org/r/#/q/project:mylyn/org.eclipse.mylyn.docs+status:open):

  • Links with full formatting
  • Comments (simply ignored in output)
  • Attributes (done by a preprocessing that collects :attr: val and replace {attr} with val)
  • Images (both inline and as blocks)

Planned "must haves":

How to contribute

Contributions are done through Eclipse Gerrit, the development/contribution process is documented at https://wiki.eclipse.org/Mylyn/Contributor_Reference

The basic steps for testing it are:

 git clone git://git.eclipse.org/gitroot/mylyn/org.eclipse.mylyn.docs.git
 cd org.eclipse.mylyn.docs
 mvn clean install -DskipTests

Now all of wikitext is built and you should now be able to do the following to run the AsciiDoc tests on their own:

 cd org.eclipse.mylyn.wikitext.asciidoc.tests
 mvn clean verify

Of course the simplest is to load the code into Eclipse and run the tests directly from there.

If you use Eclipse, the simplest way to get all the dependencies is to follow the instructions at https://wiki.eclipse.org/Mylyn/Contributor_Reference#Target_Environment about setting up Target Environment.

If you plan to develop and improve AsciiDoc, you should read the WikiText Develoepr Guide.

Back to the top