MoinMoin: KeywordMarkup

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.