Note: I would've written this on mojomojo.org but Textile makes it nigh impossible to nest stuff in lists.

MojoMojo plugin syntax discussion

The purpose of this document is to agree on a plugin markup syntax for MojoMojo that makes easy things easy, hard things possible, is nestable and extensible, and as familiar to users as practical.

Framing the discussion

Reasonable arguments

  • "it allows <desired feature>" - nesting, attributes, embedded newlines
  • "it's popular" - if users are familiar with a syntax, they will have a shorter learning curve and feel "at home", an important factor in user retention

Unreasonable arguments:

  • "it's hard to implement"
  • "will conflict with <implementation detail>"
  • "will break compatibility with the existing installations" - our installed base is manageably small, and a search&replace feature is in the works

Debatable arguments:

  • "it's like <X>" - depends on X. The argument has more weight if X is relatively more popular than an alternative, and if X is a markup language than if X is a programming language. Although with a huge target of MojoMojo being Perl programmers, the latter may seem arguable, Perl programmers are familiar already with XML and lightweight markup languages.

Goals

Overall

  • make hard things possible: we have good lightweight markup syntax (MultiMarkDown). Plugin syntax targets more difficult, composite operations. The starting level for complexity is a single Table of Contents placeholder, but the common level of complexity will be a sortable table of entities such as code snippets (this already poses problems at http://mojomojo.org/documentation/cheatsheet#Cheatsheet)
  • any technology will be abused beyond recognition
  • keep cruft to a minium. This particularly targets escaping (see the discussion on TWiki in #Attributes).

Attributes and body

A plugin must take attributes and a body. Example: an option to the POD plugin to hyperlink calls to Perl functions to their online documentation, and use Modules to their CPAN page. Other plugins may need neither. The syntax must accommodate both cases.

TWiki suffers from the fact that plugins can only take attributes. The example in nestability shows how a secondary search must be passed as a plugin attribute, with heavy escaping.

Nestability

The plugin syntax must allow for nesting other plugins, including the same plugin (table of tables). This must be done without having to escape a potential plugin invocation delimiter. Twiki suffers from this problem:

%SEARCH{ "culture" format="   * $topic is referenced by:$n      * $percntSEARCH{ \"$topic\" format=\"$dollartopic\" nosearch=\"on\" nototal=\"on\" separator=\", \" }$nop%" nosearch="on" nototal="on" }%

A particular problem with nestability

The ideal syntax would allow for the invocation of any plugin from any plugin. For example, in the TWiki search code above, it would be desirable to highlight $percntSEARCH. This is currently not possible with MojoMojo.

Target audience

  • semi-techical. User profile: project manager, marketing coordinator. Not a programmer but has used a CMS like TWiki or Confluence.
  • tech writer. Experienced with CMSes and markup languages.
  • programmers. User profile: can code, and markup languages are easily mastered.

Proposals

XML

This concludes the topic about foo and bar.
For related pages, expand the section below.
<more>
    Pages that mention foo and bar:
    <search body="foo AND bar" limit="5">
        * Title: <title /> - <snippet />
        * Summary:
            <more>
                <summary />
            </more>
    </search>
</more>

Pros:

  • attributes and body
  • nestable
  • popular
  • other markup syntaxes fallback to it (even MojoMojo's)
  • existing XML parsing modules make this easier to implement

Cons:

  • the < delimiter often needs to be escaped

Mediawiki's plugin syntax

Looks like {{fact|date=March 2009}}.

Cons:

Debatable

MediaWiki-like: {{plugin attribute1="value1", ...}} body {{/plugin}}

This is a modified version of MediaWiki's plugin syntax. The syntax proposed is:

{{plugin attribute1="value1", ...}}
    body
{{/plugin}}

Pros:

  1. attributes and body
  2. nestable
  3. looks different from HTML markup, which is consistent with it performing functional operations (e.g. ToC, searches), as opposed to presentational markup. On the other hand, many plugins could do mostly presentation, such as a sortable table plugin (which injects JavaScript code for sorting) or a "more" plugin to collapse/expand a section.
  4. inspired from the somewhat popular Wikipedia syntax

Debatable:

  1. the {{ delimiter rarely needs escaping, albeit legal in C-like code:

    {{code syntax="Perl"}}
        if ($foo) {{
            ...this is a valid Perl nested block
        }}
    {{/code}}
    
  2. harder to implement than the equivalent XML syntax

Cons:

  1. why not just use XML?

{{plugin attribute1="value1", ...}} body {{end}}

The end tag being the same (}) for all control structures of C-like programming languages, makes it hard to track syntax errors when there is an extra or a missing }. An explicitly matching ending tag solves this problem. See below.

Cons:

  1. Clearer nesting than with a generic {{end}}. Imagine a {{search}} plugin that for each search result calls its body to format it, providing it with a few variables such as the title, a short snippet, and a longer summary:
    This concludes the topic about foo and bar.
    For related pages, expand the section below.
    {{more}}
        Pages that mention foo and bar:
        {{search body="foo AND bar" limit="5"}}
            * Title: {{title /}} - {{snippet /}}
            * Summary:
                {{more}}
                    {{summary /}}
                {{/more}}
        {{/search}}
    {{/more}}
    This concludes the topic about foo and bar.
    For related pages, expand the section below.
    {{more}}
        Pages that mention foo and bar:
        {{search body="foo AND bar" limit="5"}}
            * Title: {{title /}} - {{snippet /}}
            * Summary:
                {{more}}
                    {{summary /}}
                {{/end}}
        {{/end}}
    {{/end}}
  

Cons:

Template-Toolkit

Users of TT may find the following syntax familiar:

[% plugin attribute1="value1" %]
    body
[% end %]

Pros:

  • attributes, body
  • nestable

Cons:

Comments

Please leave your signed comments inline. -- dandv

My tags:
 
Popular tags: