Markout

Markout Usage

Getting started

First of all, Markout requires Java 1.5 or greater. Let's just get that fact out of the way. Now, then...

At its simplest, you can just instantiate the MarkoutProcessor, tell it to provide basic free link support, and then run some text through the process() method, like so:

import net.exegetic.markout.*;
import net.exegetic.markout.patterns.*;

...

MarkoutProcessor mp = new MarkoutProcessor();
mp.addPattern(new DocPattern());
String html = mp.process("I _love_ [[monkeys]].");

That simple.

Setting resource patterns

Of course, that leaves something to be desired. First of all, it's going to handle all of your free links very literally. For example, this:

I _love_ [[monkeys]].

Would be turned into this:

I <em>love</em> <a href="monkeys">monkeys</a>.

Which is fine, as far as that goes, but maybe that's not the actual location of the document. No problem, just define a pattern for the url like so:

mp.addPattern(new DocPattern("/docs/[[RESOURCE_NAME]].html"));

And the result will read like this:

I <em>love</em> <a href="/docs/monkeys.html">monkeys</a>.

In addition to parsing simple document free links, markout will also parse other kinds of free links, such as categories or images, if you give it patterns for them. (If you give it a pattern object but do not define an actual value for the pattern, it will default to whatever has been defined for the pattern, which is usually the same as document free links.)

So at this point, we've got something like this:

import net.exegetic.markout.*;
import net.exegetic.markout.patterns.*;

...

MarkoutProcessor mp = new MarkoutProcessor();
mp.addPattern(new DocPattern("/docs/[[RESOURCE_NAME]].html"));
mp.addPattern(new CategoryPattern("/tag/[[RESOURCE_NAME]]/"));
mp.addPattern(new ImagePattern("/images/[[RESOURCE_NAME]]"));
String html = mp.process("I _love_ [[monkeys]].");

Bells and whistles

Okay, this is great, but maybe you want to wrap that output in something to insert it as a node into an XML document or whatever. You've got three things you can wrap your content in: a simple XHTML 1.0 Transitional document, a parent element, or a CDATA block. You can wrap the output in any or all of them, and they will be nested in that order. These methods are wrapInDocument(boolean), wrapInParentElement(name of element), and wrapInCDATA(boolean). If you set wrapInDocument(true) and want to specify a title, pass it as the second argument to the processWithTitle() method. Assuming we want all of these for some unholy reason, our code will look like this:

import net.exegetic.markout.*;
import net.exegetic.markout.patterns.*;

...

MarkoutProcessor mp = new MarkoutProcessor();
mp.addPattern(new DocPattern("/docs/[[RESOURCE_NAME]].html"));
mp.addPattern(new CategoryPattern("/tag/[[RESOURCE_NAME]]/"));
mp.addPattern(new ImagePattern("/images/[[RESOURCE_NAME]]"));
mp.wrapInDocument(true);
mp.wrapInParentElement("markdizzle");
mp.wrapInCDATA(true);
String html = mp.processWithTitle("I _love_ [[monkeys]].", "TITLE!");

And our output will look something like this:

<!DOCTYPE html 
    PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
    <head>
        <title>TITLE!</title>
    </head>
    <body>
        <markdizzle>
            <![CDATA[I <em>love</em> <a href="/docs/monkeys.html">monkeys</a>.]]>
        </markdizzle>
    </body>
</html>

Please note that you are still responsible for providing XML declarations, CSS styling, etc. These methods are provided to give you just enough gravy to grease your wheels.

Hooray for the properties file

Let's be honest: that has the potential to be a bit, shall we say, nightmarish. Fortunately, you can just feed it a properties file and be done with it:

import net.exegetic.markout.*;

...

MarkoutProcessor mp = new MarkoutProcessor();
mp.loadProperties("markout_properties.xml")
String html = mp.process("I _love_ [[monkeys]].");

We could document that here, but this file has gone on long enough, and a sample file is included anyway.

Converting Markout to Markdown

One of the keen things about Markdown is that it looks good enough (more or less) to pass as plaintext. Free links, on the other hand, not so much. Maybe you want to email a wiki page to people in plaintext, and you want the urls to resolve to something that's actually useful. Maybe you want to move your data to Markdown for use by some other third-party tool. No sweat. Everything is the same, just call the preprocess() method instead of process(). Naturally, the wrapInCDATA(), wrapInParentElement(), and wrapInDocument() methods don't have any effect.

MarkdownJ for the lazy

Markout is built on the MarkdownJ processor, and for that reason we can give you a little extra oomph, just for kicks. The wrapInCDATA(), wrapInDocument(), and wrapInParentElement() methods are available for processing normal Markdown text (ie, no free links and whatnot) -- just instantiate MarkdownProcessor instead of MarkoutProcessor, like so:

import net.exegetic.markout.*;

...

MarkdownProcessor mp = new MarkdownProcessor();
mp.wrapInCDATA(true);
mp.wrapInParentElement("markdizzle");
mp.wrapInDocument(true);
String html = mp.processWithTitle("I _love_ monkeys.", "TITLE!");

Or using a properties file:

import net.exegetic.markout.*;

...

MarkdownProcessor mp = new MarkdownProcessor();
mp.loadProperties("markout_properties.xml")
String html = mp.processWithTitle("I _love_ monkeys.", "TITLE!");

From the command line

Lastly, you can run the MarkoutProcessor from the command line. Just make sure that the markout and markdownj jars are on your classpath, and do the following:

java net.exegetic.markout.MarkoutProcessor < infile > outfile

To have it read a properties file, just give the filename with the --propfile= flag:

java net.exegetic.markout.MarkoutProcessor --propfile=markout_properties.xml < infile > outfile

The same works for the MarkdownProcessor:

java net.exegetic.markout.MarkdownProcessor < infile > outfile
java net.exegetic.markout.MarkdownProcessor --propfile=markout_properties.xml < infile > outfile

... aaaaand, that should be it. Don't forget that there are javadocs, if you need them. Have a party, kids!