Markdown and POD Syntax Highlighting Modes for jEdit

In The Pragmatic Programmer¹, the authors Andrew Hunt and David Thomas empasize the power of plain text, as well as "generators" that take the canonical form of some document and generate different representations of it. This is very much in line with the way I like to work with a lot of documents, which is why I've been using the Markdown and POD (Plain Old Documentation) syntaxes for a couple of things. As jEdit is the editor I prefer to use for working with most plain-text formats, I wrote highlighting modes for it for these two syntaxes.

The Markdown jEdit mode

Markdown is my favourite markup language. Its primary design principle, that the markup written in it should be as readable as possible even by itself, is something my plain text -loving mind can easily agree with. If I'm writing a document that needs to be represented as HTML later on, Markdown is my first choice (too bad it doesn't work very well with Wordpress).

Here's my jEdit mode file for Markdown: markdown.xml.

To install this mode, add the following to the modes/catalog file in your jEdit user settings directory (select Utilities → Settings Directory in jEdit to find this):

Then copy the markdown.xml file into the same directory with this file. See the Installing Modes section of the jEdit users' guide for more information.

This mode is not perfect; I could not figure out how to properly differentiate between code blocks and list item paragraphs (both are indented by 4+ spaces or 1+ tabs). Here's what I wrote into the mode file related to these:

<EOL_SPAN_REGEXP TYPE=“LITERAL2” AT_LINE_START=“TRUE” HASH_CHARS=" 	">(\s{4,}|\t+){2,}</EOL_SPAN_REGEXP>

Here’s how you’d generate a HTML file from a Markdown file:

perl Markdown.pl myDocument.markdown > myDocument.html

The POD jEdit mode

When writing documentation for icalBuddy, I had to enter the wonderful world of creating man pages for the first time. The raw syntax for writing these things is, to say the least, awful. Just awful. Unfortunately I can't use Markdown for writing them, but a pretty nice alternative I found was POD (or "Plain Old Documentation"), which is mainly used to document Perl code. Now, the important thing to note about this mode is that I don't know any Perl, I don't code in Perl and I have no idea how POD is used with Perl, so this mode is not suitable for simultaneous use of Perl and POD — I just wrote it for syntax highlighting in the pure POD documents I use to write man pages. Adjusting it to work for the purposes of documenting Perl code might just be trivial for someone who does know Perl and how POD is used with it, but I can't do it.

Here's my jEdit mode file for POD: pod.xml. Refer to the installation instructions for the Markdown mode above to see how this should be taken into use — the process is similar.

Here’s how you’d generate a man page from a POD file:

pod2man --section=1 --release=1.0 --center="manpage_title" --date="2009-04-21" myManPage.pod > myManPage.1

Footnotes

1. The Pragmatic Programmer (ISBN 0-201-61622-X): Chapter 3 ("The Basic Tools"), Sections "The Power of Plain Text" (pages 73-77) and "Code Generators" (pages 102-106).

1 Comments