Using JCreole

You can try out JCreole without downloading it, at http://admc.com/jcreole.

Downloads

Distributables at http://pub.admc.com/jcreole/ . Get the file (of desired type) with the greatest version, unless you have some special compatibility or change control need. If we switch to a new download repository, we will redirect you from there.

Generating HTML from the Command-Line

The easiest way to use JCreole is to get a binary distribution (a file of the format jcreole-*.zip), extract it, and execute the jcreole-*.jar file therein from your command line. It will tell you that it wants you give it a parameter telling where the input file of Creole Wikitext is. By default it will display the generated HTML (which you can redirect to a file since it is written to standard output). The syntax message also shows you can directly tell the program to write an HTML file. The most basic usage is like

    java path/to/jcreole-*.jar path/to/your/file.creole

on UNIX, or

    java path\to\jcreole-*.jar path/to/your/file.creole

on Windows.

If you want to generate just the HTML corresponding to the input Creole, without wrapping HTML to make it a complete HTML page, then add a "-" switch before the file name like

    java path/to/jcreole-*.jar - path/to/your/file.creole

on UNIX, or

    java path\to\jcreole-*.jar - path/to/your/file.creole

on Windows.

When invoked with a java... -jar command as shown above, variable references like ${this} in your Creole text will expand the corresponding Java system property values. Be aware that web or other applications using JCreole may expand any values that they want to, or none. If your .creole files will be expanded to HTML elsewhere in addition to your -jar commands, you need to be aware of the portability issue. If no System property 'this' exists, then the reference ${this} in your .creole will remain exactly like that in your HTML output. To change that unset-reference behavior, prefix the variable name with - (like "${-this}") to remove the unset-reference; and prefix the name with ! (like "${!this}") to cause the translation to abort if the reference is unset.

To integrate with your own product, see the JavaDocs which are distributed with both the source and binary distributions (or at http://admc.com/jcreole/javadoc/index.html ). If you don't plan on extending the language itself, then stick with the binary distribution and work from the API spec, except to definitely look at the source code for method com.admc.jcreole.JCreole.main(). It's likely that you can copy and adjust working code from JCreole.main() to do exactly what you want to do. Even if you need to use CreoleScanner and CreoleParser instances directly, you can learn what you need to do by studying JCreole.main() and working down. You can view the source code online or download the source distribution.

Obviously, if you want to change JCreole itself, for example to add new plugin features, you will need to work with source code. Your choice whether to pull from the source code repository or extract from a JCreole source distribution. The Ant file has lots of targets that should be very useful for integrators. As every Ant user should know, run ant -p from the main directory to list concise descriptions of the available targets.

License

JCreole is copyrighted with an Apache 2.0 license by Axis Data Management Corp. See the LICENSE.txt file in the doc directory of all distributions.

Serving Creole Documents

It's extremely easy to set up your own Creole Document Server, if you have a JEE application server running that you can deploy a webapp to.

To present .creole documents from a web server, deploy either the docServer or springDocServer war file and throw your .creole documents under the WEB-INF/creole subdirectory with the exploded contents, using subdirectories however you wish to. Depending on how you deploy, you will usually want to rename the war file without the version since the webapp context root will normally default to the war file name base (e.g. you probably want name "docServer" from "docServer.war", not "docServer-1.2.3" from "docServer-1.2.3.war". "docServer-*.war" uses traditional a traditional JEE servlet; "springDocServer-*.war" uses a Spring alternative. For springDocServer, you can wire in any other bean properties using Spring methods, perhaps using the "applicationContext.xml" file.

Both alternatives work the same way and have the same features. You can put non-creole content directly in the main directory (using subdirectories as desired) and you can directly reference these resources from your .creole files, as if /x/y.jpg were in directory /WEB-INF/creole/x/ alongside /WEB-INF/creole/x/t.creole. You can obviously enhance either web app however you want to, or you could integrate its functionality into another web app to give Creole functionality.

Developers

For low-level work, e.g. low-level integration into another application (new or existing), to use the API or to use parts as a third party libary, to branch this project or customize it, you can either pull or branch the code from Github, or get and extract the source zip file. Either way, to get started, once you have the code, just run "gradlew" from the base directory.

Documentation

There are text documentation files in the doc subdirectory.

There is also a HTML reference guide for Creole authors, provided in a standalone version and an Internet version. The 100% standalone format is jcreole-ref-s.html the binary zip distribution; the fancier Internet format is jcreole-ref-i.html the binary zip distribution. (The Internet version has references to highly-available Internet resources such as JQuery-UI and google-code-prettify. jcreole-ref-i.html is independent in that it can be distributed alone, but it does require an Internet connection at 'read-time' to satisfy the references just described. jcreole-re-s.html is completely independent.) But the source Creole is also provided as jcreole-ref.creole in the jcreole-*.jar file and in the resources source code directory. Integrators can use jcreole-ref.creole to serve the author guide framed and styled like your other application content. You can obviously edit jcreole-ref.creole. The Ant target standaloneRef will build tmp/jcreole-ref-s.html from the .creole file; and target internetRef will build tmp/jcreole-i.html from the same .creole file.

The web site http://admc.com/jcreole has interactive JCreole demonstrations and comprehensive Creole tutorials.