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.

Keyword markup

This proposal try to:

• Be clear, don't use funny characters if there is a readable way
• Be consistent as possible, so user learn only few things
• Use current syntax or syntax we use in other parts of the system

• Be like WikiPedia markup if it make sense

• Be like html - well known, simple, easy to merge in stuff like class:value in a natural way

The basic idea is [[]] make link, {{}} include extensions. Everything but links is implemented with extensions and can be replaced with farm or wiki plugins.

• Technical note: http, page, image and like will be plugins. To have external links that use "rel=nofollow", simply install a 4 line nofollow http plugin, that extend the builtin http handler by sending the attribute to the formatter. To have fancy include with 17 arguments, install a custom page plugin.

This proposal try to use key:value pairs when possible. We already use this for ACL:

#acl user:read,write All:

and search:

[[FullSearch(linkto:PageName title:Help)]]

And we many want to use this for meta data:

Author: Name
Status: Draft
...

Links

Rules:

• Anything inside [[]] is a link

• Link will never include (unlike current markup)

• title:, image: keywords used just like in our search for special cases.

• No keyword in the first item means page: - [[PageName]] == [[page:PageName]]. Because the most important markup in a wiki is a page link.

• http://, ftp:// are (funny) keywords too

• Support old link types with no change, until at least until next major release

Backward compatibility:

Additions:

Problems:

• Can't have page named "Page Name title:Something"

  • Unless we allow: [[page:"Page Name" title:Title]]

Include

Rules:

• Anything inside {{}} will include the content in the page

• The content can be some extenstion (called now macro/parser)
• Include of pages and attachments is done with extenstions

• Will not support old call syntax because links took the [[]]`

• page:, image:, media: are plugins

• The first item is the plugin, the next are the arguments

  • This is little wired, but thats how http://domain title:text works in the links, if you see http: as a plugin.

• Order of arguments does not matter

Parsers extenstions:

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

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

New SectionParser:
{{section:cssclass format:rst
RST markup here...
}}

or:
{{section class:cssclass format:rst
RST markup here...
}}
?

{{figure
some markup
 <!> we must have nesting if we want to include here!
}}

Backward compatibility:

   1 I'm a file.

Maybe we should use the same words: inline, attachment and drawing instead of page and image?

Discussion

IMHO key:value pairs should only be used when nessesary. One advantage of a wiki markup language is that the user has to type less when he uses it instead of html. With a wiki markup similar to html you loose that advantage.

I like
{{Image(sunrise.jpg,right,nofloat,thumb,"A sunrise")}}
more than
{{Image:sunrise.jpg alignment:right float:nofloat size:thumb caption:"a sunrise"}}.
I also think that a syntax without key:value pairs is easier to learn for a new user.

WikkaWiki uses a syntax similar to html ({{image class="center" alt="DVD logo" title="An Image Link" url="images/dvdvideo.gif" link="RecentChanges"}}) and one of the reasons I chose MoinMoin was because I liked the MoinMoin markup more than the WikkaWiki markup.

Because of these reasons, I prefer the proposed PositionalMarkup to the proposed KeywordMarkup.

• Try to explain a new user how to call this:

  {{Image(sunrise.jpg, right, nofloat, thumb, "A sunrise")}} The order of the arguments is important? How do you leave the default value? How do you find the function signature? You must add keywords for this type of call.

  • The order of the arguments is not improtent. {{Image(sunrise.jpg, nofloat, thumb, "A sunrise", right )}} also works.

    As a consequence the plugin is easy to use, even for new users. A new user would probably use not all optional arguments, she would probably use {{Image(sunrise.jpg)}} or {{Image(sunrise.jpg, "A sunrise" )}}.

    The syntax {{Image:sunrise.jpg alignment:right float:nofloat size:thumb caption:"a sunrise"}} is IMHO harder to learn, because a user has to know the keys and the values which are allowed for each key. The argument "right" to send an image over to the right is easy to remember. If a user also needs to remember the keyword "alignment", it gets harder.

    In KeywordMarkup there is also no clear distinction between the name of the macro and the arguments of the macro, which might be confusing for some users.

I don't think it will work - arguments without any specific order that are magically bound to the correct variable?

• For the Image macro and similar macros it works, because the arguments are or contain keywords. Have a look at http://www.druidwiki.org/HelpOnThumbnail and http://en.wikipedia.org/wiki/Wikipedia:Picture_tutorial.

What if I have some arbitary strings like:

• {{section, cssclass, cssid, title}}
  {{Action, edit, Edit, BacktoPage}}
  {{Include, from here, up to there}}

Either order matter, or you need keys. keys are easier to read.

• Agreed, in these cases you have to use keyword arguments or positional arguments.