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.
Mylyn/WikiText/AsciiDoc
Contents
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
- Go to Help / Install new software...
- 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").
- After a monent check Mylyn WikiText Extras feature and proceed with Next button.
- Agree with licence and so on.
- During installation you will be asked to confirm install unsigned content. Continue with OK button.
- Restart Eclipse IDE
- Create new file with .adoc file extension and you are done.
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":
- Code blocks, see #474084
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.