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. Jam Tangan Murah timbangan Penumbuh Rambut Bisnis Modal Kecil

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.

I would put all arguments on the table. One man's unreasonable may be another's crowing jewel.
-- mateus

Consensus

Syntaxes that require one line, such as
```
=toc
```
are not a good idea because sooner or later we'll need a plugin invoked in enclosing formatting for which line breaks may be significant (e.g. a plugin in a table, or, if we were to use Textile, this very list would break)
Symmetric separators are preferred over the same separator: {{plugin}} over %plugin%. TWiki suffers from this problem (see #Nestability).

Goals

Overall goals:

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 here)
any technology will be abused beyond recognition
keep cruft to a minimum. 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 a piece of code like one above, it would be desirable to highlight a word, say $percntSEARCH. This is currently not possible with MojoMojo.

Target audience

newb
semi-technical. 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.

It's probably worth giving weights to the target audiences to further differentiate them. For example, one weighting is to say the four groups above have equal weight and thus receive a 0.25 weighting when considering the design choices. Or perhaps we really feel semi-technical people are going to be our most common user, and give them a 50% weighting.
-- mateus

Proposals

XML

Example:

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>

Short form: attributes don't need a value

To Get	Write
Test::Harness	<cpan Test::Harness>

Anything longer than <cpan Test::Harness>, such as <cpan module="Test::Harness">, becomes just too close to the <a href="... form to be meaningful lightweight markup.

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

Votes

+1 dandv
+1 lestrrat? just cause. but it seems way too verbose, if you can help it

Mediawiki's plugin syntax

Looks like {{fact|date=March 2009}}, or multi-line:

{{Infobox mineral
| name        = Ruby 
| category    = <span class="newWikiWord"><a title="Not found. Click to create this page." href="/development/discussion/mojomojo_plugin_syntax/Mineral.edit">Mineral?</a></span> variety
| image       = Ruby cristal.jpg
}}

Cons

for a list of cons to MediaWiki's table syntax, see http://en.wikipedia.org/wiki/Help:Table#Comparison_of_table_syntax.
how does this syntax nest?

Pros

If someone is familiar with just one piece of wiki software these days, it's probably MediaWiki. - hobbs
- agree, but I'd say not with the plugin syntax. I've been editing for 3 years and didn't know about multi-line plugin body -- dandv

supports attributes and body:

{{pod|options="hyperlinkg_modules"|
=pod
POD text here
...
}}

Votes

+1 lestrrat? reason: I don't even know this format, but if it's supported in another well known Wiki, it's easier to gain converters.

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

attributes and body
nestable
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.
inspired from the somewhat popular Wikipedia syntax

Debatable

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

{{code syntax="Perl"}}
    if ($foo) {{
        ...this is a valid Perl nested block
    }}
{{code}}

harder to implement than the equivalent XML syntax

Cons

why not just use XML?

Votes

{{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

Difficult to identify what a generic {{end}} closes. 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:

Explicit ending tags	"end" as an ending tag
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}}

**Explicit ending tags**

"end" as an ending tag

    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}}

Votes

-1 dandv (see the Cons above)
-1 jnapiorkowski: My experience with 'end' style syntaxes is that my designers all start doing stuff like [% end %]

Template-Toolkit

Users of TT may find the following syntax familiar:

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

Pros

attributes, body
nestable

Cons

same ending tag for all plugins (discussed at #{{plugin attribute1="value1", ...}} body {{end}}
less popular than the equivalent Mediawiki syntax
on English keyboards, [% and %] are harder to type than {{ and }}.
The only harder part might is the %. } is a reach for me. However, I'm not a fan of typing TT tags. They are cumbersome for my typing skills. I also don't want to have to use caps, I'm lazy. I know it can be configured, but I want the default. Call me an xhtml bitch if you like: lower case all tags and attribute keys. On the other hand, attribute values don't have to be quoted but must be clearly demarcated. -- mateus

Crackpipe Syntax?

Multiple independent actions with multiple argument potential for each action:
```
{{ action1 arg1=value1 arg2=value2 | action2 arg3=arg3 }} 
```

Mutiple linear action chain

{{ action1 : arg1=value1 arg2=value2 -> action2 : arg3=arg3 }}

Equivalency

If I understand correctly, that is, action2 takes the output of action1, then this is equivalent to the IMO cleaner:

{{action2 arg3="arg3"}}
    {{action1 arg1="value1" arg2="value2 /}}
{{/action2}}

If this looks backwards, imagine a real scenario. IMO, the crackpipe syntax will look really nasty. I tried a go at it and kinda stumbled; feel free to continue. -- dandv

Nested plugin invocation	Crackpipe syntax - unwieldy
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. {{search body="foo AND bar" limit="5" \| literal = "Pages that mention foo and bar:" _ [...TBD... literal="Title: " _ title _ snippet _ literal = "Summary: " _ summary \| more] \| more }}

*Nested plugin invocation*

Crackpipe syntax - unwieldy

    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.
    {{search body="foo AND bar" limit="5" 
      | literal = "Pages that mention foo and bar:" 
      _ [...TBD... literal="Title: " _ title _ snippet
      _ literal = "Summary: " _ summary | more] | more 
     }}

Notes

This is more geared towards transclusion syntax which has "singular" tag nature to it. I mention this because this discussion also touches upon a syntax change that is primarily concerned with formatting some content between here and there which, imo, is more suited to a dual tag nature like <tag> </tag>.
- Agree that the syntax targets "blocks" more. For transclusion, XML already provides <img src="object">, which in effect is a transclusion. -- dandv
In theory the values could be anything, even another action with its own of arguments. Then we could bring a server down to its knees with while(while(while(1))) ;-}

Votes

-1 dandv The XML format is way clearer IMO.

Comments

Please leave your signed comments inline. -- dandv Jasa SEO Jasa SEO Murah Jasa SEO Murah Jasa SEO Jasa Adwords Jasa Google Adwords Google Adwords Sepatu Online Toko Sepatu Online Sepatu Sepatu Murah Sepatu Safety Sepatu Futsal Cheapes Hostgator Coupon Link Booking Televisori offerte Notebook Offerte Berita Terkini Internet Marketer Muda Internet Marketer Indonesia Portatile Apple RDAnet Lorks Karikatur Bisnis Modal Kecil Bisnis UKM Berita Terbaru Iklan Baris Jasa SEO Jasa SEO Murah SEO Indonesia Konsultan SEO SEO Belajar SEO Kursus SEO Kursus SEO Murah Jam Tangan Casio Jam Tangan Casio Jam Tangan Murah Jam Tangan Grosir Baju Terbaru Grosir Baju Baju Terbaru Grosir Baju Murah Bisnis Online Belajar SEO Kerupuk Kerupuk kulit Social Bookmark Dofollow Social Bookmark Kumpulan Puisi Kirim Puisi Penumbuh Rambut Penumbuh Rambut timbangan WBC Wonogiri Jasa SEO Murah Jasa SEO Jam Tangan Murah Jam Tangan Murah Kata Gaul

Cupu Berita Terbaru Android Store Upinson Berita Terkini Edo Ziedo Aplikasi Symbian Sepatu Safety Upin Upin Tablet Android Sepatu Murah Upinson Blogger Radio Streaming SEO Star Upinson Cinta EDU Jasa SEO Sepatu Murah Sepatu Murah Sepatu Murah Penumbuh Rambut Penumbuh Rambut Penumbuh Rambut Penumbuh Rambut Penumbuh Rambut Penumbuh Rambut Penumbuh Rambut

Showing changes from previous revision. ~~Removed~~ | Added

Revision by onnycorp, 2012-08-22

MojoMojo Plugin Syntax

MojoMojo plugin syntax discussion

Framing the discussion

Consensus

Goals

Attributes and body

Nestability

A particular problem with nestability

Target audience

Proposals

XML

Short form: attributes don't need a value

Pros

Cons

Votes

Mediawiki's plugin syntax

Cons

Pros

Votes

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

Pros

Debatable

Cons

Votes

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

Cons

Votes

Template-Toolkit

Pros

Cons

Crackpipe Syntax?

Equivalency

Notes

Votes

Comments