[dokuwiki] Re: Is there any 'recommended' formatting/layout/syntax for plugins?
- From: Chris Green <cl@xxxxxxxx>
- To: dokuwiki@xxxxxxxxxxxxx
- Date: Mon, 6 Feb 2012 16:27:29 +0000
On Mon, Feb 06, 2012 at 03:20:18PM +0000, Christopher Smith wrote:
>
> On 6 Feb 2012, at 14:48, Chris Green wrote:
>
> > I seem to remember asking something like this a long time ago but I
> > don't think I got a very conclusive answer then and a lot of things have
> > changed since (Dokuwiki has developed and so has my knowledge, a bit).
> >
> > So are there any good reasons for using particular Dokuwiki syntax for
> > calling plugins? I have two basic questions I think:-
> >
> > 1. Is there any particular reason to prefer, say "<pluginName......>"
> > over "~~pluginName......~~" or any other character or characters? If
> > not then should we not recommend one particular format just for the sake
> > of consistency (unless there are *very* specific reasons for using
> > something different)?
>
> Consistency.
>
> ~~token~~ is typically used to change some setting, e.g. ~~NOTOC~~
>
Yes, true, but there are other characters used in plugins such as {{ and
[[. What I'm suggesting/asking is that these conventions used for
consistency as you say should be stated somewhere in the documentation.
> >
> >
> > 2. Are there any reasons for putting parameters/text in one place rather
> > than another?
> >
> > E.g. is there any major difference between:-
> >
> > <pluginName:A load of text of some sort>
> >
>
> <token:string> effectively precludes the use of wiki syntax in string. Using
> only ">" as an exit token lacks sufficient uniqueness.
>
>
> > ... and:-
> >
> > <pluginName>A load of text of some sort</pluginName>
>
> <token>string</token> allows the use of wiki syntax (if properly implemented
> in your plugin).
>
Again this should be made clear, it's probably possible to work it out
from the description of modes and such in the development documentation
but it's not easy. I think some general guidelines (in the comments of
the sample plugin there maybe) woud be very useful.
>
> >
> >
> > I know that the plugin code will get called with DOKU_LEXER_ENTER,
> > DOKU_LEXER_UNMATCHED, DOKU_LEXER_EXIT with the text from the various
> > places. What I'm asking is whether there is any good reason for putting
> > things in particular places.
>
>
>
> If "string" is actual wiki content. For me its sensible to bracket it in
> ENTER and EXIT tokens, it makes the document more intuitively understandable.
> Someone can read the raw wiki text skipping tokens. In pretty much the same
> way, the plugin can set up default processing for unknown render formats,
> e.g. PDF or ODT, by removing the tokens and sending string through to the
> default "cdata" render() method, which fits with (what I think is) a common
> understanding of how tokens and text works, at least for anyone who has any
> familiarity with html or xml.
>
It's possibly more understandable for someone familiar with HTML etc.
but it's not so for others.
The reason I've brought this up now is that I'm trying to write a plugin
for extracting certain parts of a wiki document and writing them to a
database. I want the extracted text to be as much part of the wiki
document as possible, and to require as little effort as possible to
enter. It's wholly for my own use so some ambiguity/non-uniqueness is
OK so my idea is to have something like:-
/b 12345 This is some sort of description/
With a string match like '^/b[^/]*/'. Something like:-
<bl>12345 This is some sort of description</bl>
Is much less readable *and* much harder work to type (lots of shifted
keys etc.)
--
Chris Green
--
DokuWiki mailing list - more info at
http://www.dokuwiki.org/mailinglist
Other related posts:
