Skip to content

Latest commit

 

History

History
147 lines (108 loc) · 4.29 KB

README.creole

File metadata and controls

147 lines (108 loc) · 4.29 KB
Raw

This is a WikiCreole parser in EmacsLisp.

Rationale

We have Emacs Muse and we have OrgMode as wiki/blog makers but neither is close to the Creole syntax which is actually the syntax used on the EmacsWiki.

WikiCreole is closest to the OddMuse syntax used there. It also happens to be my favorite Wiki syntax.

The combination of this and Elnode should make a complete EmacsLisp EmacsWiki a possibility. Also a blog engine and all sorts of other simple content based things.

I even like the idea of using WikiCreole as a kind of base language for every HTML template I write, rather than HTML.

Compliance

This is early stages so it's not fully compliant with WikiCreole yet. Here is the WikiCreole test document and we don't handle some big things and all of what I'd call the exceptions:

  • not ending headings with an appropriate =
  • having whitespace before list items
  • no escapes
  • org-mode tables only

Tests

We do have a somewhat comprehensive ERT suite for the code we do have. The tests are embedded in the code.

Extensions

We support a couple of extra extensions over Creole right now.

Syntax Coloring

We automatically fontify PRE sections with extra markup:

##! emacs-lisp
(defun creole-block-parse (text)
  "Parses TEXT as a creole block.

A creole block is a paragraph or list item that can include
links, italic, bold, line break or inline preformatted markup.

Returns a copy of TEXT with the WikiCreole replaced with
appropriate HTML."
  (replace-regexp-in-string
   "\\*\\*\\(\\(.\\|\n\\)*\\)\\*\\*"
   "<strong>\\1</strong>"
   (replace-regexp-in-string
    "//\\(\\(.\\|\n\\)*\\)//"
    "<em>\\1</em>"
    (replace-regexp-in-string
     "{{{\\(\\(.\\|\n\\)*\\)}}}"
     "<code>\\1</code>"
     (replace-regexp-in-string
      "\\\\"
      "<br/>"
      (creole-link-parse text))))))

Org-Mode tables

Instead of Creole tables, we actually use org-mode tables. Org-mode tables are very similar:

Date Amount Description
------------+--------+---------------------
2011-11-15 100.15 Expensive lunch out
2011-11-18 7.30 Dry cleaning
2011-11-21 22.50 Takeaway curry
------------+--------+---------------------
129.95
  1. +TBLFM: @5$2=vsum(@I..@II)

When a table is exported to HTML it is recalculated, so you can use formulas quite happily. Formula lines are not exported to HTML.

Lisp callouts

You can call to EmacsLisp like this:

<<(
 (mapconcat
   (lambda (s)
     (format "* %s" s))
   '("rationale" "compliance" "tests")
   "\n")
)>>

And this is what that would output:

<<( (mapconcat (lambda (s) (format "* %s" s)) '("rationale" "compliance" "tests") "\n") )>>

It's my intention to build a few Lisp functions specifically for use inside the Lisp extension element. The first of these is:

creole-directory-list directory-name &optional make-links

WikiCreole format a table of files in directory-name.

make-links causes the files to be WikiCreole links.

HTML

You can embed HTML directly into this Creole implementation, using a plugin, like this:

<<html <P>This is HTML which is just embedded <EM>directly</EM> into the output.<BR/> You obviously have to be really <u>careful</u> you don't break the output.</P> html>>

Reuse

The code is designed to be reused in differing circumstances, it is split into:

  • a tokenizer creole-tokenizer which produces a list of tokens representing the input document
    • Inline markup inside a paragraph is NOT converted.
  • a parser creole-structure which takes a tokenizer list and returns a parsed representation
    • note it's only creole lists that need this parsing step
  • an HTML exporter creole-html which outputs HTML from a WikiCreole source buffer
    • it always outputs to the same buffer right now, obviously changes coming here
    • it also has an interactive output option
  • a user tool creole-wiki which can take lots of customization options