'''Creating easier to use unified wiki markup for release 2.0''' <> = Problems with current markup = refactor, collect more links to related bugs, feature requests and user observations. This part should be short and clear: what are the REAL problem that we need to solve? There are also comments or complaints about Moin's WikiMarkup. These can be defined into some categories: * features which do exist, but in their current markup cause confusion * finnish abbreviations use colon * include versus link versus an inclusion which also offers a link * exactly how should we invoke Parser, Processor or Macro anyway? which one's which? should a user have to care? Markup should be selected because we have decided it is reasonable, by our own reasons, not just because someone else thought so. In short if we cannot express the reasoning here I would not see the point of making a change. There is another page, MarkupProposals, which is heavily edited (hooray for the wiki way) but suffers the problem of trying to be all three of those, with a bit of online help page thrown in. It also starts off abrasively, with professorial diagrams and a decidedly non-neutral point of view. There are also people reporting feeling lost in the wealth of our HelpContents pages. So, it's clear the refactoring under and over the hood as it were, need to happen at the same time. We need to unify the markup... so the new, unified markup becomes part of the design too. = Related work = There are currently efforts to unify a number of things: * UnifyPagesAndAttachments - unifying their storage mechanism and simplifying their use * UnifyParsersAndMacros - simplifying extensions using unified markup and code Parsers, Processors and Macros are called sometimes PPM, or simply Extensions. See also: [[FeatureRequests/PPMCalledFromPragma]]. = Goals for new markup = replace most of the text with common goals from the proposal page. It must be short and clear: without clear goals we can't evaluate any proposal. Unifying the markup needs the following traits: * It needs to make sense. Not the "I think everyone in the world can possibly guess this" kind of sense, that may not be possible. But at least we should decide what our reasons are, and that some things that are very similar from the user's point of view, should also be using similar markup. * Coders should discuss here how a particular markup redesign will affect the underlying code-design. I'd like this page to describe '''specific''' suggested markup, in a style rather similar to that found in the various HelpOnEditing pages, with discussion following, in the style of the discussion about any possible new MoinDev/MoinMoinLogo. Initial examples are from the IRC log that spurred me to write this up, more is up to you. == How to tell if it makes sense? == When we've decided for ourselves why it does make sense, people can read these defining thoughts at the top of the related HelpContents page and not feel nearly so lost as they do today. How can we tell if it can make sense so easily? Try to describe it in plain language to people whose idea of "computer savvy" is that they can find their web browser icon without being told what Earth look like. For a good test I recommend trying to say your description out loud, and suppose your audience is such an ordinary person. In this regard all wiki are imperfect. It was also well noted on the IRC channel that redefining the markup can actually effect how the code under the hood looks - in order to handle it. Also, if it can't be coded,efficiently, it's possible that describing it won't be so effective either. == Link vs. Include == We were talking about merging the SectionParser, and it wandered in the direction of what code makes sense or not. Yes, this is very long. I have ellided intervening threads about different topics and people popping in and out with the assorted hello and bye noises. [[attachment:moin_markup_ideas_irc_29apr05.txt]] Hmm. This means we have three things to consider: * plain links * inclusions purely for display * inclusions which ''also'' display a link * What is this? This list is confused. Link take input and produce a link, include include another content which can be anything. The topic turned (twisted? :-? ) a few other directions, then back again. Eventually I dug out a browser and started this page. Hope it helps :D Conclusions I think I saw: * leaning toward links, inclusions, macros (or PPM or whatever they are called this week) each getting a different paired symbol. * a preference for a paired symbol, the same symbol being easier to type twice even if it is shifted, than two different characters, even if a little more readable. * combining along the lines of code behavior where possible. * typing less characters for support rather than more, so, maybe three characters instead of two, to replace long words like attachment: and not favoring wikipedia-style Image: for instance. = Markup Specification = <> = Markup proposals = <> <> = Discussion = * Links contain two types of information: the address (URL or WikiName) and how it should be displayed (text or image). The two are sometimes separated by a space and at other times separated by a vertical bar in the suggested markup. The markup would be simplified if I could always separate the two by a vertical bar. . I changed it. * Better yet, if I could always separate the two by a comma, the link syntax would be similar to the macro syntax. A link would appear to be a special case macro. ---- I prefer the usage of {{{["Moin Moin Etymology"]}}} displaying as [[Moin Moin Etymology]], {{{["Moin Moin Etymology" Etymology]}}} displaying as [[Moin Moin Etymology|Etymology]], and urls being the way they are now. This is how we have implemented it at [[http://daviswiki.org|DavisWiki.org]]. The only possible confusion is that sometimes people put quotes around external links, such as {{{["http://daviswiki.org" page]}}}, which would be solved (apparently) in this proposed markup, but there's no reason the same couldn't be done with our quoted markup -- just automatically route {{{"http://*"}}} to be external. We have chosen to notify the user when they make this mistake, which teaches them how to make internal links. Maybe I'll change this. I do like the idea of unified {{{[[Image]]}}} macro that can toggle thumb/no thumb. Right now we have our {{{[[Thumbnail]]}}} macro in addition to the {{{attachment:}}} syntax, which is ugly, but we will unify soon. I would also propose that if you want to simplify markup you turn off WikiNames by default. Giving the user two radically different linking mechanisms is very counterintuitive. Also, I noticed that in the above examples commas were used within the macros. As was noted, this is inconsistant -- but does it matter? I think if you are going to use "|" as the delimator of links that it ought to delimate everything, just as wikipedia does it. I like the use of {{{"}}} quotes because they are used in natural english to {{{quote}}} things, and commas are used to seperate ideas, not {{{|}}} bars. --PhilipNeustrom . I agree both on WikiNames and delimiter. We should have one default way to do things, not 2. -- NirSoffer <> == Refactoring proposals == The goals stated in both proposal are duplicated, we should factor them out to the main page, leaving only the specific goals of each proposal. It will be interesting to try a version which is even more like WikiPedia, not because its better, but because its poplar, and the best interface is the familiar interface. Here is a [[http://en.wikipedia.org/wiki/Wikipedia:How_to_edit_a_page#Sections.2C_paragraphs.2C_lists.2C_and_lines|MediaWiki syntax reference]]. A html like (WikaWiki) syntax also can be nice and very easy to learn. And there are more proposals on the wiki, maybe its good to collect them and compare here. == Python like calls == Since some users prefer positional arguments, and some keywords, and calls with one or two arguments seems bloated with keywords, and calls with more arguments are impossible without keywords, we need both :) Maybe use the python tokenizer that Oliver wrote, so both `[["Page Name", image="moinmoin.png"]]` and `[["Page Name", "moinmoin.png"]]` will work. This will create a more complex system, but can satisfy all users. The problems with Python like calls is its too complex. In Python you have both strings and bound names. In a wiki page, everything is a string, so we don't need any quoting: 1. . {{{ {{plugin arg1, kw=value}} }}} 1. . {{{ call = "plugin" argskw = ["arg1", "kw=value"] }}} 1. . {{{ args" = ["value",] kargs = {"kw": "value"} }}}