Using SimpleWiki

[Christian V. Sciberras]

I'll be using SimpleWiki in an upcoming PHP framework (especially the
wiki system for the said framework), called K2F.
I've got SimpleWiki running nicely. I've got the following couple of
queries:

- Development seems to have halted on 2009(?) Might just be the dates
I looked at.
- How secure is it? Can people inject arbitrary HTML in final document
(I saw variable SimpleWiki->$_allow_html defaulted to true).
- How exactly do I extend it? In all honesty, I couldn't understand
SimpleWiki.org's text regarding extending, plus the module page seems
to be empty.
- I'd like to add ###...### rule to SimpleWiki, as per Creole
reccomendation for code blocks (the alternative write now is
{{{...}}}, for preformatted text).
- This is more of a feature request, but most methods lack PhpDoc
documentation, so I don't understand what's going on.
- How easy is it to modify the engine to support a different wiki
markup? Most markups I've seen look quite bad (and unfriendly).
However, I got to like simplistic ones like those used in Google Code
wiki and Stackoverflow (eg: *bold* in place of **bold**). I've
searched a bit for code support in SimpleWiki and seems %c php%{{{ /
*php code*/ }}} is the best it can offer (the Creole spec suggested to
use ### /*php code*/ ### instead). Stackoverflow and Google code use
the backtick operator; `/*php code*/`, way easier on the eye.

[Henrik Bechmann]

Hi Christian,

I have a very long term commitment to Simplewiki, as it is part of my database application framework strategy (see musterdb.org). The wheels grind very slowly, it's a long term project. It's all starting to show life. (The other major piece is dlml.org with dlml.org/gargoyle starting to show a bit of life).

Simplewiki has been stable for me, but I know it needs some work. Re extensions, I've done some work to split out the classes into separate files so that the classes can be loaded with an autoloader (I use Kohana for the base application framework for musterdb, and they use a search approach I like that I believe they mention was established by the Zend framework). This will allow arbitrary class extensions when it is relased, which is I presume the preferred way to extend the product. I'll publish that in probably March or April or so.

Currently the best guide to the code is the annotation and the code itself. In general SimpleWiki acts as a facade. The best thing is to invoke one instance, and then re-use it as needed with

$html = $wiki->prepare($text)->get_html();

so, like

$wiki = new SimpleWiki();

$wiki->allow_html(false);

etc...

To see how the parser/compiler is extended, best to study the Simplwiki class implementation for now. Simplewiki itself could certainly be extended now (mywiki extends SimpleWiki) to add your own flavours.

Note that the parser ($wiki->parser()) has an argchars() method for setting allowable value characters for properties and attributes.

Adding a separate markup for code blocks is certainly an option. Could you tell me where "###" is recommended? I haven't seen it. In the meantime as you say %c html%{{{ provides a door to literal inline code (could be php), or |:pre html:|{{{... for whole blocks.

I use the backtick operator for line extensions and comments (and the "```##" combination for metadata, very interesting possibilities there!).

Hope this helps a bit, and thanks for your interest.

- Henrik

--
You received this message because you are subscribed to the Google Groups "simplewiki" group.
To post to this group, send email to simpl...@googlegroups.com.
To unsubscribe from this group, send email to simplewiki+...@googlegroups.com.
For more options, visit this group at http://groups.google.com/group/simplewiki?hl=en.

--
bechmann.ca

[Christian Sciberras]

Hello Henrik,

Good to know about your commitment. So far I've found it quite stable, but you never know what could go wrong, and having someone actually care about it is a huge plus in adoption.

I did assume (or guess actually) that extending it would be through sub-classing, but I wasn't really sure since (afaik) it wasn't mentioned on the website.
I'm already relieved to know this is possible, also extended code in the past with this method, so the idea isn't exactly new to me.

One issue I had was that even if the code is quite clear, there's no way I would understand what is going on because: (1) lack of documentation (in code) and (2) no mention on the structure, ie, what your engine passes through etc.
However, I will eventually overcome this after some serious use of the code. Well, eventually :)

With regards to the recommendation of "###" for code, please find it here. Note that this doesn't seem to be a standard, just a suggestion. Also as I read the page again, it said "##" should be for inline code fragments, I'd have assumed "###" would be for block code (since triple characters seem to be used for blocks).

With regards to metadata (and syntax), I don't really understand what it is? And how is it beneficial?

Best regards,
Christian Sciberras.

[Henrik Bechmann]

Thanks Christian,

I've added Raph Levian's suggested markups to http://simplewiki.org/future for consideration during the next round. Looks like there's a laundry list of available markup basically, with an attempt to assign functionality.

There's a philosophical question here: so far I've more or less limited the shortcuts to basic markup, and left the rest a bit wordy, treating markup extensions as specialized, more explicit, less frequent, and a performance drain. A little less richness for some syntactic limits (but with very broad scope - esp. decorators). So I think it would be worth considering how much commitment is required for shortcuts. I'm not against it, just want to be careful, and I always prefer some kind of coherence. (years in the trenches<grin>).

Very sorry about the lack of documentation. I'm also committed to that, long term. One of the benefits of dlml (for which I'll make an easy add-on available to simplewiki) I hope will be more accessible documentation tools. But I think the place to start would be phpdoc, as you suggested. I'll definitely incorporate that into my next round of general php work (starting in a few weeks) and as I gain experience with it I'll see about applying it to Simplewiki sooner rather than later. 

For an idea about metadata, see the wiki source for any of the pages on simplewiki.org (link at top right of pages), like http://simplewiki.org/display/article/future. Note for example how the first line of metadata specifies membership of a tab (in this case causes the "Future" tab to light up when the "future" page is shown). IOW the metadata allows for specification of (arbitrary) system data, and allows the system to say to the markup "tell me about yourself so that I know what to do with you". Flexible and open ended. Warning: I'm all about metadata!<grin>.

The metadata section starts with ```## and accepts any class (string), property (":" separated) or attribute ("=" separated). Then your application can query it with $wiki->get_metadata(). This returns an object with "classes", "attributes", and "properties" properties. Unfortunately I haven't enabled line extension for the metadata line, but I intend to do that.

I'll let you know when I plan to have another round at this code, and we can share possibilities. In the meantime, I'm always interested in feedback.

- Henrik

[Henrik Bechmann]

Christian (et al),

I've released beta 3 of simplewiki. The main change is that I broke the classes into separate files, and organized a calling chain for subclasses to allow for easy extension of the classes.

The module organization is documented here: http://simplewiki.org/module (including procedure for extending classes)

The new download can be obtained here: http://simplewiki.org/download

Hope this helps,

Best,

- HEnrik

On Wed, Jan 5, 2011 at 4:32 PM, Christian Sciberras <uuf...@gmail.com> wrote:

--
bechmann.ca

[Christian Sciberras]

Wow, now that was some fast updating :)

Thanks Henrik!