Markdown and POD Syntax Highlighting Modes for jEdit

Posted on April 21, 2009
Filed under 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.

Update (April 23, 09): Updated the Markdown mode with slightly better handling of code blocks and list item paragraphs as well as some comments about problems therein (see below in the post for more info on this).

The Markdown jEdit mode

Markdown jEdit mode screenshot

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):


<MODE   NAME="markdown"
        FILE="markdown.xml"
        FILE_NAME_GLOB="*.markdown"
/>

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:


<!-- PROBLEM: code blocks
     
     Both code blocks and list paragraphs are specified by indenting
     (4+ spaces or 1+ tab) - how to differentiate between them? We
     don't want markdown syntax coloring to apply within code blocks
     but we _do_ want it to apply within list paragraphs. As it stands,
     we can't have both (or at least I don't know how to do that with
     jEdit's current mode syntax implementation.)
     
     The next line applies one syntax color type for all lines that
     begin with at least 4 spaces or 1 tab, which means that all such
     lines are treated as code blocks (this disables markdown syntax
     coloring for indented list paragraphs). Comment or uncomment it
     according to your preferences.
-->
<EOL_SPAN_REGEXP TYPE="LITERAL2" AT_LINE_START="TRUE" HASH_CHARS=" &#09;">(\s{4,}|\t+)</EOL_SPAN_REGEXP>
<!-- The next line applies one syntax color type for all lines that
     are indented "twice" (i.e. begin with at least 8 spaces or 2 tabs).
     This should safely match only code blocks (no list paragraphs can
     be indented twice like this, if I understand the spec correctly.)
-->
<EOL_SPAN_REGEXP TYPE="LITERAL2" AT_LINE_START="TRUE" HASH_CHARS=" &#09;">(\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

POD jEdit mode screenshot

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).

Comments

One Response to “Markdown and POD Syntax Highlighting Modes for jEdit”

Show/hide comments & reply form: