RFE: Entity-definition and -replacement plugin

jdickey

2009-02-18, 10:19 #1

Member since Feb 2009 · 6 posts · Location: Singapore
Group memberships: Members

Show profile ·

Link to this post

Subject: RFE: Entity-definition and -replacement plugin

The problem:
References to the same concept using nearly-identical text strings, links, etc., can be sprinkled throughout a wiki, in numerous pages and/or namespaces; the likelihood of unintentional variances stymies indexing.

First conceptual solution:
This plugin should support the definition of XML-style entities with as little additional markup overhead as possible. Question: Is it possible to have a plugin action triggered by text in the wiki itself, as opposed to an embedded tag?

Each wiki or namespace may have an entity page, on which the currently-defined entities are listed in two columns: the name of the entity itself, such as homepage, and the expansion of that entity, such as [[http://www.domain.com/jsmith/index.php|John Smith's home page]]. This should be ordered alphabetically within each namespace, so that the entity page for namespace :foo:bar:baz includes an alphabetic list of the entities in namespace :foo, followed by those in :foo:bar, and finally those in :foo:bar:baz. New entities, or redefinitions of existing ones (see below), may only be added to the current namespace.

A child namespace should be able to override entities defined within an ancestor.

Entity definition should support nesting of other entities: for example, the example homepage entity from above might be defined as [[&smithsite;/index.php|John Smith's home page. If the nested entity is not defined, it should be output verbatim, with a FIXME smiley added to the end of the enclosing entity.

Does anybody know of any plugin that is reasonably close to implementing this behavior? Am I proposing anything that would horribly break existing functionality within Dokuwiki?

ach (Moderator) 2009-04-26, 15:10 #2

Member since May 2006 · 544 posts
Group memberships: Global Moderators, Members, Super Mods, Wiki Managers

Show profile ·

Link to this post

Take a look at http://www.dokuwiki.org/entities and http://www.dokuwiki.org/interwiki
With entities you can do something like this:

&homepage; <a href="http://www.domain.com/">homepage</a>

And then each occurrence of &homepage; will get substituted with that link. But you cannot use an entity inside certain other syntax elements like a link ([[&homepage;/foobar.html]]).

And with interwiki links you can do this:

hp http://www.{NAME}.com/homepage
user http://www.domain.com/{NAME}/foo

Then you can use [[hp>johnsmith]], which will create a link going to http://www.johnsmith.com/homepage or [[user>johnsmith]], which will create a link to http://www.domain.com/johnsmith/foo.

You can go still further ...

jdickey

2009-04-26, 17:23 #3

Member since Feb 2009 · 6 posts · Location: Singapore
Group memberships: Members

Show profile ·

Link to this post

Subject: Thanks - using that, and thinking about more

Thanks. Actually, what I was thinking about is what you've noted the current implementation of entities can't do, and testing has confirmed - you can't define an entity like, say, &homepage; which expands to [[http://example.com/|Home Page]]. That capability and the namespace features I described (in particular the notion that entity names and definitions are stored within the wiki content, rather than some inaccessible-to-normal-users configuration file), were the "itches" I was really trying to scratch. (Because entities defined in wiki syntax and content would be renderable anywhere the wiki itself could be rendered, where HTML address tags might not make real sense.

I've just opened a medium-low priority project ticket for myself to investigate how practical/difficult implementing such a beast would really be. I'm still using Trac for issue management and recording; I can think of three or four ways to go about doing quite a lot of that in Dokuwiki using namespaces, tags and templates; what I can't figure out is a way to handle notifications and reminders. Anybody have any better ideas than just listing all tickets in a page with owners and dates?

Again... original question answered for now; anything else is at least a couple months off.

ach (Moderator) 2009-04-28, 01:38 #4

Member since May 2006 · 544 posts
Group memberships: Global Moderators, Members, Super Mods, Wiki Managers

Show profile ·

Link to this post

Quote by jdickey on 2009-04-26, 17:23:
in particular the notion that entity names and definitions are stored within the wiki content, rather than some inaccessible-to-normal-users configuration file

I'd prefer to make the acronyms, entities, interwiki, mime and smileys configuration files configurable inside the admin area (probably open to the manager group as well). It doesn't make sense to me to put them (or something similar) into actual wiki pages.

Quote by jdickey on 2009-04-26, 17:23:
Because entities defined in wiki syntax and content would be renderable anywhere the wiki itself could be rendered, where HTML address tags might not make real sense.

I don't understand why you'd want to render entities into wiki syntax. Could you elaborate on that? What would be the difference to actual HTML? And what would be the benefit?

jdickey

2009-04-28, 11:46 #5

Member since Feb 2009 · 6 posts · Location: Singapore
Group memberships: Members

Show profile ·

Link to this post

The difference to actual HTML would be that, at least internally, a link (for example) wouldn't be rendered using an HTML a tag but would instead be what the Wiki thought of as a link. If the Wiki were rendered to HTML, it would use the tag. If it were rendered to something else, say, PDF or RTF, it might be done differently, based on how the Wiki rendered to that format normally. You'd be maintaining consistency with the other content in the Wiki's content, which might not know how to deal with 'raw' HTML in its presentation.

ach (Moderator) 2009-05-01, 02:26 #6

Member since May 2006 · 544 posts
Group memberships: Global Moderators, Members, Super Mods, Wiki Managers

Show profile ·

Link to this post

Quote by jdickey on 2009-04-28, 11:46:
The difference to actual HTML would be that, at least internally, a link (for example) wouldn't be rendered using an HTML a tag but would instead be what the Wiki thought of as a link. If the Wiki were rendered to HTML, it would use the tag. If it were rendered to something else, say, PDF or RTF, it might be done differently, based on how the Wiki rendered to that format normally.

I'm not sure if this is possible. Did I understand you correctly: You want to insert the wiki text PATTERN1, which shall be converted into PATTERN2, which gets rendered as PATTERN3? At which stage shall this PATTERN2 appear?
We either have wiki text or rendered HTML/PDF/ODT/whatever. There is no interim stage inbetween.

ryan.chappelle 2009-05-20, 22:31 #7

User title: Chilean DW Fan
Member since May 2008 · 97 posts · Location: Temuco, Chile
Group memberships: Members, Newsletter Team

Show profile ·

Link to this post

If I am understanding correctly, what jdicky tries to explain, is that the new entity would not render (X)HTML output, but rather new Wikitext for the Wiki renderer to handle. For example, an entity like &todaysnews would be picked for replacement into its equivalent string, such as [[http://www.newspaper.com/@DATE@|Today's News!]], and then the resulting text would be handed to the Wiki parser to handle. The central management would be like the "entities.local.conf" file, except the right side is Wikitext instead of (X)HTML!

In essence, it feels like modifying the var plugin [1] with absolute precedence so that it can be used inside some specific Wiki constructs and then accessing the available substitutions via a central system (an Admin plugin component) And most likely it would require patching of the parser engine.

[1] http://www.dokuwiki.org/plugin:var

☆ Chilean DW Fan!
→ check my plugins for DokuWiki
→ GULIX -- Araucania LUG
→ Surviving earthquakes since Feb 2010!

jdickey

2009-05-23, 06:39 #8

Member since Feb 2009 · 6 posts · Location: Singapore
Group memberships: Members

Show profile ·

Link to this post

Bingo, we have a winner! Ryan, yes, thank you; you understand exactly what it is I was asking for. Also, thank you for giving such a clear summary of what changes would be needed to the existing software; the absolute precedence was something I have always had implied when I thought of this, but should have made more clear in the original post. I would expect it would take patching of the parser engine to do that. I browsed through the source, and an exploitable seam to add this to the existing workflow without changing the parser just didn't jump out at me. I was hoping to get an opinion from someone more knowledgeable about/experienced with the source. I didn't expect it to be doable with a single, simple plugin - that's why I labeled it as an 'RFE' to begin with.

Now, any ideas on how/whether to proceed?

Jeff

ryan.chappelle 2009-06-03, 23:18 #9

User title: Chilean DW Fan
Member since May 2008 · 97 posts · Location: Temuco, Chile
Group memberships: Members, Newsletter Team

Show profile ·

Link to this post

Thanks, JD.

I see working directly over (under) the DokuWiki parser a very complicated thing to do, and most likely not advisable because of the large amount of user-generated information that may become affected. And even more if we're looking for entity nesting, be it into another entity or into a DW construct such as wikilinks (the only disadvantage of the var plugin so far).

If nesting is to be a key feature, I would first try to adapt the command plugin, or one of its complements, testing it with higher precedence, as the command plugin allows for a more freeform definition of "entities". Otherwise the var plugin should be fine, and probably complementing it with an Action plugin would be needed. Once I reach'd a fashionable level of precedence (or had I determined that no higher precedence is possible), I would try to complement with an Admin plugin component that would store the entities. If things worked up to that point, then I would try to reengineer into a parsing framework that would have to be patched over an existing DokuWiki installation, due to the limitations of the plugin system.

If turning this into a dependable and probably widespread complement is intended, then a testing period using an amount of data and preexisting plugins as large and spread as possible would follow. Key testing cases would include but not limited to: entities unexpandable due to ACL (eg.: an entity that expands into an {{include>...}} construct), entities that depend on out-of-server content generation (eg.: an entity that expands to an online newspapers' current headline), any entity that triggers action of a container syntax mode, and entities that expand to content unavailable in the renderer.

Lots of work, but I don't have a clue of how to make it easier so far, sorry.

☆ Chilean DW Fan!
→ check my plugins for DokuWiki
→ GULIX -- Araucania LUG
→ Surviving earthquakes since Feb 2010!