MoinMoin: PositionalMarkup

Easy markup

PositionalMarkup is not a good name for the proposal, because it was never intended to allow only positional arguments in extensions.

• But Easy Markup is also a bad name, you can call any proposal "Easy".
  • If you can think of a good name, just change it.

Goals

• Easy to learn
  • only a few simple familiar concepts
  • as consistent as possible
• Easy to use
• Easy to type
  • compact syntax (less then html)
• Easy to read
  • clean syntax
  • uses symbols in a familiar way
  • no unnecessary redundancy

• Small MoinMoin-Core, use of plugins where it makes sense

• Similar to MediaWiki when possible, as some new MoinMoin users already know MediaWiki

  • The other stated goals are more important than similarity to MediaWiki

Links

Rules:

• Anything inside [[]] is a link

• A Link will never include (unlike current markup)
• The second optional argument can be used as the caption for the link.
• The second optional argument can also be an image (attachment or page, ends with .gif, .png or .jpg). This image will then be turned into a link.
• The arguments are separeted by a commma.

• Parser should discard spaces after the comma; Both [[Page Name, Title]] and [[Page Name,Title]] should both be displayed as Title

Extensions (macros, parsers)

Rules:

• Anything inside {{ }} is an extension ( / plugin / PPM )

• Extensions support positional arguments, keyword arguments and keywords as arguments.
• Arguments are in parentheses
• The arguments are separeted by a commma

• Parser should discard spaces after the comma. Both {{Image(sunset.jpg, left)}} and {{Image(sunset.jpg,left)}} should get the same result.

description:
markup example

linebreak macro:
{{BR}}

WordCount macro:
{{ WordCount(FrontPage, 1000) }}

indent table parser:
{{IndentTable
1                               
 2                       
  3                               
   4
}}

Python code:
{{python
import sys, os
print 'hello!'
}}

SectionParser, uses keyword arguments:
{{section(class=cssclass, format=rst)
RST markup here...
}}

Image macro, uses keywords as arguments, for example the keyword "right" means to add an image on the right side of the page:
{{ Image(sunset.jpg, thumb, right) }}
{{ Image(sunset.jpg, left) }}
{{ Image(sunset.jpg, left, thumb) }}

Empty extension default to plain plugin:
{{
plain text as is
}}

Inclusion

A stated goal is to reduce the number of concepts for the user and the moin developer. IMHO the moin core should be as small as possible. As a consequence, inclusion should be implemented as macros.

If images are pages or sub pages, then we don't need Image, only Include:

• - include the page content

• - include an image saved as "Some Image"

But then size and alignment don't not make sense for Include.

Alternative Extension Syntax

Use a colon instead of brackets to separate the macro name from the macro arguments.

{{ Image: sunset.jpg, right }}
{{ Image: sunset.jpg }}

{{ section: class=cssclass, format=rst
RST markup here...
}}

{{BR}}

{{IndentTable
1                               
 2                       
  3                               
   4
}}

Backward compability

• a conversion script is needed, which converts the old markup into the new markup
• as positional arguments, keyword arguments and keywords as arguments are supported for PPMs, it is possible to convert the old syntax for parsers and macros to the new syntax for PPMs
• tbc

Discussion

This proposal is more complex than KeywordMarkup, as you have both positional markup and keywords, its more like a programing language. For example, the function calling convetion: name(value, value), compared with simpler html: <tag key="value" key="value">. This also add the complexity of dealing with keyword and positional arguments in same call, just like in Python. For example, is this call correct? name(key=value, value)?

This will be harder to use for the new user, easier for a programmer. -- NirSoffer 2005-07-11 07:30:30

• Yes, the proposal is more complex than KeywordMarkup, because it offers someone who creates a macro more choice. If we take away that choice, we loose backward compability with the current MoinMoin markup. Keyword arguments make sense if you have a macro with many arguments and you can't use "keywords as arguments". When you have to use keyword arguments where they are not nesessary (for example with macros with only one or two arguments), this constraint adds unnesessary complexibility from the perspective of the user of your extension. New users normally don't use macros or parsers with 5, 10 or 15 arguments. To offer them a simple syntax for the extensions they normally use by allowing positional arguments and keywords as arguments, makes it IMHO easier for them.