Markup Conversion | ||
---|---|---|
![]() | ![]() | |
Task Editor Integration | Textile Syntax |
Lightweight markup is designed to be readily converted to HTML. WikiText provides a means to convert markup to:
toc.xml
)These conversions can be made by right-clicking any *.textile
, *.tracwiki
, *.mediawiki
, *.twiki
, or *.confluence
resource in the Eclipse UI:
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).
Ant 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):
<property name="wikitext.standalone" value=""/><!-- path to wikitext standalone package -->
<path id="wikitext.classpath">
<fileset dir="${wikitext.standalone}">
<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"
helpPrefix="help">
<fileset dir="${basedir}">
<include name="help/*.textile"/>
</fileset>
<stylesheet url="styles/help.css"/>
<stylesheet url="styles/main.css"/>
</wikitext-to-eclipse-help>
</target>
Similar Ant scripts can be used to convert to HTML:
<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.
The markupLanguage
attribute accepts any of the following values (depending on your classpath):
Textile
MediaWiki
TracWiki
TWiki
Confluence
org.eclipse.mylyn.wikitext.core.parser.markup.MarkupLanguage
common task options
Option | Usage |
---|---|
markupLanguage | The markup language to use, for example ‘Textile’, ‘Confluence’, ‘MediaWiki’, ‘TracWiki’, ‘TWiki’. |
validate | Indicate if the input file should be validated. Default is true . |
failOnValidationError | Indicate if validation errors should cause a build failure. true or false , default is true. |
failOnValidationWarning | Indicate if validation warnings should cause a build failure. true or false , default is false. |
overwrite | Indicate if target files should be overwritten even if the target document is newer than the source document. true or false , default is false. |
sourceEncoding | Indicate source file encoding. Example: UTF-8 . Defaults to the platform default encoding as defined by java.nio.charset.Charset.defaultCharset() . See the IANA Charset Registry for valid charset names. |
wikitext-to-html and wikitext-to-eclipse-help task options
Option | Usage |
---|---|
title | Specify the title of the output document. If unspecified, the title is the filename (without extension). |
file | The source file. Not required if a fileset is specified. |
linkRel | The ‘rel’ value for HTML links. If specified the value is applied to all generated links. The default value is null. |
multipleOutputFiles | Indicate if output should be generated to multiple output files (true/false). Default is false. |
formatOutput | Indicate if the output should be formatted (true/false). Default is false. |
navigationImages | Indicate if navigation links should be images (true/false). Only applicable for multi-file output. Default is false. |
prependImagePrefix | If specified, the prefix is prepended to relative image urls. |
overwrite | Indicate if output files should be overwritten. The default is false. When false output files are only overwritten if the output file timestamp is older than the markup source file. |
helpPrefix | The prefix to URLs in the toc.xml, typically the relative path from the plugin to the help files (wikitext-to-eclipse-help only). For example, if the help file is in ‘help/index.html’ then the help prefix would be ‘help’ |
defaultAbsoluteLinkTarget | Specify that hyperlinks to external resources (<a href ) should use a target attribute to cause them to be opened in a seperate window or tab. The value specified becomes the value of the target attribute on anchors where the href is an absolute URL. |
stylesheet
Nested <stylesheet>
elements cause HTML to contain links to CSS stylesheets or CSS stylesheet content. When used with the url
attribute the stylesheet element is linked. When used with the file
attribute the stylesheet content is copied into the HTML document.
Stylesheets may have nested <attribute>
elements with name
and value
. These attributes are copied verbatim to the HTML <link>
element. Attributes named type
, rel
and href
are ignored.
WikiText can convert wiki markup to XSL-FO. PDF is readily obtained from XSL-FO by using an FO processor such as the excellent Apache FOP project.
<wikitext-to-xslfo markupLanguage="Textile">
<fileset dir="help" includes="**/*.textile"/>
</wikitext-to-xslfo>
WikiText conversion to XSL-FO is performed using the wikitext-to-xslfo
task. In addition to common options listed above, the following options are available:
wikitext-to-xslfo task options
Option | Usage |
---|---|
targetdir | Specify a folder in which output files should be created. |
title | Specify a specific book title. If unspecified, the book title is the filename of the source file (without extension). |
subTitle | Specify a sub-title to appear under the book title. |
fontSize | Specify the default font size. The default is 10.0 |
showExternalLinks | Indicate if external link URLs should be emitted in the text. The default is true. |
underlineLinks | Indicate if links should be underlined. The default is false. |
pageBreakOnHeading1 | Indicate if h1 headings should start a new page. The default is true. |
panelText | Indicate if the text ‘Note: ’, ‘Tip: ’, and ‘Warning: ’ should be added to blocks of type note, tip and warning respectively. |
version | A document version to emit on the title page, for example: ‘Version 1.0.23’ |
date | A date to emit on the title page. |
author | An author to emit on the title page. |
copyright | A copyright to emit in the document page footer. |
pageNumbering | Indicate if pages should be numbered. The default is true. |
pageMargin | The page margin in cm. Defaults to 1.5. |
pageHeight | The page height in cm. Defaults to A4 sizing (29.7) |
pageWidth | The page width in cm. Defaults to A4 sizing (21.0) |
To convert the XSL-FO output files to PDF using the Apache FOP project, add the following to your Ant script:
<property name="fop.home" value="/full/system/path/to/fop-0.95"/>
<exec command="${fop.home}/fop">
<arg value="${basedir}/help/MyFile.fo"/>
<arg value="${basedir}/help/MyFile.pdf"/>
</exec>
Refer to the Apache FOP documentation for more details.
WikiText can convert markup to DocBook
<wikitext-to-docbook markupLanguage="Textile">
<fileset dir="${textile.root.dir}">
<include name="**/*.textile"/>
</fileset>
</wikitext-to-docbook>
You can use WikiText first to convert your Textile markup to DocBook then use the DocBook XSL stylesheets 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
wikitext-to-docbook task options
Option | Usage |
---|---|
bookTitle | Specify a specific book title. If unspecified, the book title is the filename of the source file (without extension). |
overwrite | true or false , default is true. Indicate if existing target files should be overwritten even if they are newer than the source file. |
file | The source file. Not required if a fileset is specified. |
doctype | Overrides the DTD doctype to use in the output file. Optional. |
WikiText can convert markup to OASIS DITA. The conversion can either be used to convert a single input file to a bookmap and multiple topics, or to a single topic.
WikiText conversion to DITA is performed using the wikitext-to-dita
task. In addition to common options listed above, the following options are available:
wikitext-to-dita task options
Option | Usage |
---|---|
bookTitle | Specify a specific book title. If unspecified, the book title is the filename of the source file (without extension). |
overwrite | true or false , default is true. Indicate if existing target files should be overwritten even if they are newer than the source file. |
file | the source file. Optional, not required if a fileset is specified. |
doctype | Overrides the DTD doctype to use in the target bookmap. Optional. |
topicDoctype | Overrides the DTD doctype to use in the target topic files. Optional. |
topicFolder | The relative folder name to use for topic files when producing multiple output files. Optional, defaults to ‘topics’. |
topicStrategy | Specify how multiple output files are generated. Optional, defaults to ‘FIRST’. Must be one of ‘FIRST’, ‘LEVEL1’ or ‘NONE’. ‘FIRST’ indicates that multiple topic files are to be created, split at the level of the first heading encountered in the file. ‘LEVEL1’ indicates that multiple topic files are to be created, split one file for each level-1 heading encountered. ‘NONE’ indicates that multiple topic files are not to be created. Only a single topic file is created, with no bookmap. |
To convert an input file to a bookmap and multiple topics, use the following:
<wikitext-to-dita markupLanguage="Textile">
<fileset dir="help" includes="**/*.textile"/>
</wikitext-to-dita>
The output is created as multiple files: a bookmap and multiple topics, one topic for every level-1 heading.
To convert an input file to a single output file, use the following:
<wikitext-to-dita markupLanguage="Textile"
topicStrategy="NONE">
<fileset dir="help" includes="**/*.textile"/>
</wikitext-to-dita>
See the examples for example Ant build scripts.
Mylyn WikiText provides a means of customizing wiki markup languages for use with Ant tasks. This is useful for altering the markup language to include specialized markup rules specific to your needs.
To customize a markup language you may either extend a markup language using subclassing, or you may provide a MarkupLanguageConfiguration
. The best option will vary depending on your needs. MarkupLanguageConfiguration
provides a means of altering a markup language without subclassing the language itself, which makes it reusable with different markup languages.
Following is an example of providing a MarkupLanguageConfiguration
configuration:
<taskdef resource="org/eclipse/mylyn/wikitext/core/util/anttask/tasks.properties" classpathref="wikitext.ant.classpath"/> <typedef name="languageConfiguration" classname="org.eclipse.mylyn.wikitext.core.parser.markup.MarkupLanguageConfiguration" classpathref="wikitext.ant.classpath"/> <wikitext-to-eclipse-help markupLanguage="org.eclipse.mylyn.wikitext.textile.core.TextileLanguage" ...> <languageConfiguration escapingHtmlAndXml="true"/> </wikitext-to-eclipse-help>
See the Mylyn WikiText Developer Guide for details on extending a markup language via subclassing.
![]() | ![]() | ![]() |
Task Editor Integration | Textile Syntax |