Revision [5472]

This is an old revision of WikkaDevelopment made by NilsLindenberg on 2005-02-02 11:00:57.


Wikka Development

Last edited by NilsLindenberg:
copied ideas to SuggestionBox
Wed, 02 Feb 2005 11:00 UTC [diff]


Things in the next release

I'm planning on putting out a small bugfix release within the next few days. If you have something that you would like to see in this release, make a note here and I'll take a look at it. -- JsnX, 26 Nov 2004

Things to be fixed before releasing wikka-
Here's some sparse thoughts from a first test of the beta version:

I saw it in the SandBox and it messed up things royally there... disabled it, and added notes about my findings.
I agree with Dartar, I'd like to see WikkaReleaseNotes included as a default page; if one doesn't look at it, fine, but at least it's there if you do need to consult what was changed (and why) and it's much more readable than what {{wikkachanges}} produces. I'd vote for just removing the {{wikkachanges}} action and simply including a WikkaReleaseNotes page. --JavaWoman

Have both of you thought how this would be implemented?? It's easy to include a default page on install. However, what are we going to do on upgrade? Are we going to overwrite the page? (Yes, of course! And that's what you'd do with a text file as well - what's the difference?) What if the site has changed the page? (Include a note on the page that it is a system page that will be overwritten on upgrade; if possible protect the page from editing by anyone but admin on install.) I think it would be annoying for the upgrade script to overwrite an existing page. (But you would be overwriting the text file - what's the difference? A page is just a more readable version. And we wouldn;'t need to keep the same information synchronbized in two places - always a bad idea.) Hence the solution that I have proposed. In addition, how long is it going to be before someone says, "Hey, why don't we include a text file that lists the changes". (Maybe very long - it hasn't happened, has it? See how it goes.) Once again, we take care of this by including the text file and then showing it in the wiki. Sites are not going to update the Wikka release notes--it's static data. Why have it as a wiki page? (For readability, and it fits in simply with the system. Yes, sites are not going to update the release notes - in whatever form. And if they do want to update them, they could do that with the text file just as easily.)
My 2 cents. On the one hand, I agree with JW as far as readability is concerned: it is much better to have a formatted version, with headers etc., possibly with links, than a plain-text version (the first thing I thought when I saw the SandBox page full of raw text was : "gosh, the formatters are broken!"). This said, there is a question that none of you has mentioned so far. How are we going to deal with internal links that are present in the current WikkaReleaseNotes page? Either we distribute a version of WikkaReleaseNotes with no internal links and no camelcase words left or we have to think of a solution to avoid generating a ton of missing pages. IMO, one interesting solution (which might require some futher development, though) is to use a IncludeRemote FetchRemote strategy to retrieve fresh and uptodate documentation on the new release from the main server (JsnX, have you tried to install the plugin locally?). This has the advantage of avoiding writing a hardcoded page in the user's database and - as Jason was suggesting - let the user free to decide where to add the release notes (it is just a matter of adding somewhere {{fetchremote page="WikkaReleaseNotes")). On the other hand, I was wondering: is there really a problem with overwriting an existing page? Provided the installer says explicitly it is going to overwrite one page, this page will be nothing more than a version of the page (that's the power of wikis!): if a note is added like "updated by the Wikka installer", the user will always be able to retrieve previous versions of the same page if needed. So I don't really think that overwriting is a problem. -- DarTar

Sorry to keep hammering on this, BUT :), let's see how your logic holds up:
Is there really a problem with overwriting an existing HomePage? Provided the installer says it is going to overwrite the HomePage, the new HomePage will be nothing more than a version of the page. The site admin will always be able to retrieve the previous version of the HomePage if needed. So I don't really think that overwriting the HomePage is a problem.
Sounds absurd, doesn't it?
Um, yes. What goes for the HomePage goes for the WikkaReleaseNotes: "overwriting" simply means creating a new version in the database. So I don't really think that's a problem. ;-) --JW

As I said above, I don't consider this a problem. But even if you don't agree with this, consider that no one is proposing here to overwrite a page like HomePage, but a page with a sufficiently clear 'system default' name (like WikkaReleaseNotes) that will hardly be modified by Wikka users (and if it is, again, it's just a version..). -- DarTar

Regarding JavaWoman's comments:
Your first point was that the installer would overwrite the text file, so why not overwrite a page.
That's not correct. The site admin would overwrite the text file, by his choice of uploading the new file to the webserver. It would be his choice to overwrite the file. See the difference?
Most site admins would not "upload the [separate] files" but rather upload the archive to the server, untar it there, and then run the upgrade routine. Just untarring would replace all files. And why would one not replace a release notes (text) file? It contains all previous information, doesn't it?
Your next point was that it's a bad idea to keep the information in two places.
So you are suggesting that we should only make the information available online and after the upgrade has already happened. Wouldn't you want to know what has changed before you upgrade?
It is known before you upgrade because it's right here. --JW
I could go on and on. The bottom line: it's standard for software distributions to include a text file that describes changes. This is where most people will look for the information....and they will want to review the changes before they decide to upgrade--not upgrade and then review what has changed. I'm in favor of using {{fetchremote}} to make the information available online, but also including a text file that can be reviewed offline. Here's an example of how the text file might be useful: Let's say an upgrade breaks an existing site. The admin could view the text file to help narrow his focus for fixing the problem. ... I'm going to throw in one more thing just to preempt it: But couldn't the site admin just view the release notes on WikkaWiki? That's possible, however this site might be down. It could be down from a denial-of-service attack. I could be dead and thus not able to pay the bill. Who knows? By including a text file we won't have to worry about any of this. -- JsnX
Actually, many applications have all their documentation online, except maybe a small readme and a license file. Most people don't download first, then unpack an archive, and then read a changes file to see what's in the latest release: they read the release notes online before even downloading. Sure a site can be down - that can always happen. Many possible causes (and it happens to the best of them). As to you being dead and not being able to pay the bill - that's an entirely different discussion (one we should have, about continuity and how to ensure it, but not here in this context). But the whole idea of including release notes is to provide a reference after download and installation - but that won't normally happen until after one has checked the release notes online to see whether it's worth the download in the first place.
My argument about keeping the information in two different places and two different formats identical still stands, meanwhile - how do you propose to make sure the two versions have identical information at all times? Even if you have a reliable procedure for that (you'll need a script) - it's extra (unneeded) work, as is creating a special action to show the contents of the text file: two files, two programs, all to show the same content? A simple page that (for now) shows just a link or (later) pulls the content directly from the site will be much simpler. -- JavaWoman

Regarding this point, I don't agree with JW's argument. I think a text version with the release notes, accessible to the Wikka administrator before untarring and uploading the package makes perfectly sense (and actually is very common in software distributions). I really don't see the problem with "keeping information in two places": before releasing a new version, the text release notes can be created in 5 seconds just by copying and pasting in a text editor the formatted output of WikkaReleaseNotes. So where's the problem? -- DarTar

In referring to "keeping information in two places" I'm thinking of a build process, assuming (not the case now!) that all the to-be-released files are in a CVS branch, and you just run a script to turn that into a distribution. The files in that branch should -at all times- be up-to-date, which includes any text files to be included. So what happens while you're working on a new release? Something like this - for every change to be made for the next release:
The set of files in the repository should be "complete" at all times to be able to do a build; which (in your proposal) means also repeatedly copying the WikkaReleaseNotes (manually, or via a script) - not just once, but for every change being made. It's an extra step, and doing that step is a manual process (even if you run a script to do the copying, running the script is a manual step). People do forget steps :), so the fewer manual steps there are, the more reliable the build and release process will be.

On the other hand, a static WikkaReleaseNotes page with a link to the online WikkaReleaseNotes would need to be created and committed only once; no redundant and easy-to-forget manual steps needed any more. --JavaWoman

Why don't we focus our energy on making the {{wikkachanges}} action better? JavaWoman, you are detailing problems with my crappy action that I spent ten minutes on to demonstrate the concept. Wouldn't it be possible to tweak the action to output the text to your satisfaction? (What I see is is a far less readable version, and if it's in a text file, then how are you going to keep the two synchronized? We already have WikkaReleaseNotes - if you just include that it's simpler (it's already there), more reliable (nothing to synchronise, the data is in one place, not two), and more readable (no extra action needed either).)

I'm proposing that we name the page WikkaReleaseNotes for a reason. Let's imagine that Linus decides he wants to create a Wikka site name LinuxWiki to document his Linux kernel. If we name a default page as WikkaReleaseNotes, won't this confuse people on the LinuxWiki site when they are looking for the release notes for Linux? What will Linus name the page that describes the release notes for his software? You might say, he could just overwrite the Wikka release notes with whatever he wants. But then what happens when he upgrades to a new Wikka version? Do you see the problem that we are creating? (So rename it WikkaReleaseNotes here and include that page as a system page. I agree that the name is not optimal - but the same is true here already. Note: this rename has been done now --JW)

I don't like the idea of us forcing pages on people. If we make the release notes as an action, people can have the release notes show on any page they want. They could create a page named WikiEngineChanges and place the {{wikkachanges}} action on it, and when they upgrade, the changes will show up on the page that they decided. (So they create a page called WikiEngineChanges and just {{include}} the WikkaReleaseNotes on it.) If we force a page named WikkaReleaseNotes, we are going to create an unnecessary struggle with site owners that might not want to have the Wikka release notes on a page named WikkaReleaseNotes. (It's just another "system" page, like SandBox and FormattingRules. I don't see the problem.) -- JsnX

Comments embedded above to make them more relevant to context -- JavaWoman

I gave above some more reactions about my way of seeing the problem of release notes. I'd like to propose here some steps towards a solution that I hope we might all agree upon.
===== Wikka Release Notes ===== 
This server runs on [[[ Wikka Wiki]] version **{{version}}**.
The new features of the current version are described on the [[ main Wikka server]]

In the future, this action will be replaced by a FetchRemote action.
(BTW it might be interesting to add named anchors in WikkaReleaseNotes to facilitate referring to specific Wikka versions)

Is this an acceptable compromise? ;) -- DarTar

===== Wikka Documentation ===== 
A comprehensive and up-to-date documentation on Wikka Wiki can be found on the 
[[ main Wikka server]]

Agreed. --JavaWoman

For the time being, what about creating a default page called WikkaReleaseNotes containing a static link to the online WikkaReleaseNotes? (see my note above on why creating or overwriting a page during upgrade is not really a problem) -- DarTar

Actually, I'd like to see our current ReleaseNotes page here renamed to WikkaReleaseNotes; pages relating to Wikka itself really should start with 'Wikka': we already have WikkaDevelopment, WikkaBugs, WikkaBugsResolved, etc. (why not WikkaDocumentation?) - WikkaReleaseNotes would neatly fit into that pattern and be clearer than just "ReleaseNotes". Then someone writing about, say, a Calendar can create a page like FancyCalendarWikkaReleaseNotes etc.
I agree with DarTar that a page with a static link to the online release notes here, to be included with the install, would be a good temporary solution; to be replaced later by a mechanism like FetchRemote (once finished - but let's not wait for that!) (Note: edited somewhat for readablity - we now do have WikkaReleaseNotes and WikkaDocumentation as suggested.) --JavaWoman

=====Welcome to your Wikka site! ===== 
Thanks for installing [[Wikka:HomePage WikkaWiki]]! This site is running on version {{version}} (see WikkaReleaseNotes).
Double-click on this page or click on the "edit page" link at the bottom to get started.

Also don't forget to visit the [[Wikka:HomePage WikkaWiki website]]!

Useful pages: FormattingRules, WikkaDocumentation, OrphanedPages, WantedPages, TextSearch.

This should do it:
echo $this->VERSION;
Save as actions/version.php --JavaWoman (who for once doesn't document what she writes. ;o) )

Here it comes: this is Wikka version Unknown action ""version"". I wonder if it wouldn't be better to have such basic system plugins handled by the wikka formatter, instead of using an action. And maybe in the future {{version}} will print a link (fetchable or not) to WikkaReleaseNotes? -- DarTar

I'm in Rom till sunday so don't expect big changes before monday. Nils
Dropped. Geez, in the whole wide world it's only the Americans who spell it without the "u" we keep the U.S. spelling? Ironic.
spelling is ironic - you can always add a colour action yourself containing nothing but an include of actions/color.php, if you must. :) --JavaWoman
Liberia???? Japan I get (beaten in war). OAS I get (sucking up to U.S. ;) ). LIBERIA??? Liberia I don't get. (Simple, look up the history of Liberia; knowing that I could easily guess they'd be using American English(oh ya, I see what you mean. I'd forgotten that bit of history.). And where did you think the name Liberia came from? --JW) BTW, I didn't mean that spelling was ironic, I meant that the decision was, given efforts by various members on this wiki to "internationalize" the wiki. (Or, I could rename the file. Writing an action to include an action is a programmer's solution obviously. LOL ;-} ) -- Mike

must be replaced with the appropriate call to $this->FormOpen():

Things to be fixed before releasing wikka- (JW's take):

After (and in addition to) all the discussion above triggered by DarTar's notes, here are my own observations based on careful code inspection (sometimes better than testing ;-)). See also my thoughts in WikkaGeshiIntegration.
Numbers within brackets refer to (approximate) line numbers.

GeSHi integration
See also WikkaGeshiIntegration.


resolved in version 1.0.4:

(See detailed integration solution in WikkaGeshiIntegration, complete with installer/updater code.)
$geshi =& new GeShi($sourcecode, $language, $this->geshi_path);

to be done:
=> at least ones that are highly likely to be used in our (online) implementation:

Bugs and other issues/problems

looking at the code I'm sure this will not work correctly. It wil "accept" numerical entity references but not named entity references - so those still won't work. (And actually, its operation doesn't have anything to do with Unicode, only with entities - which may encode Unicode characters but entities are not themselves Unicode.)
See my item 'Non-breaking space in forced links' in the SuggestionBox: this is one case that actually shows the function htmlspecialchars_unicode() does not work correctly!
Also, there is no option for the quote_style and charset parameters as in the PHP original, so we lose functionality here, too. It's probably better to have a "wrapper" function around the PHP one, which (after applying the PHP function, passing on the extra parameters) merely reverts all ampersands that are for any entity references (numerical or named); thus the wrapper function should accept all parameters the PHP function does. And since we are supposed to produce XHTML, ENT_QUOTES should probably be the default for quote_style; maybe also UTF-8 should be the default for charset?
Note: the INI code formatter used ENT_QUOTES and this has now disappeared (it was there for a reason!). But an entity used in code should be visible as an entity, not as the character it encodes. Conclusion: a code formatter should use the PHP function htmlspecialchars() so that any entities are "escaped".
Here's the solution: a new function htmlspecialchars_ent() to replace the proposed (beta) htmlspecialchars_unicode():
     * Wrapper around PHP's htmlspecialchars() which preserves (repairs) entity references.
     * The function accepts the same parameters as htmlspecialchars() in PHP and passes them on
     * to that function.
     * One defaults here is different here from that in htmlspecialchars() in PHP:
     * charset is set to UTF-8 so we're ready for UTF-8 support (and as long as we don't support
     * that there should be no difference with Latin-1); on systems where the charset parameter
     * is not available or UTF-8 is not supported this will revert to Latin-1 (ISO-8859-1).
     * The function first applies htmlspecialchars() to the input string and then "unescapes"
     * character entity references and numeric character references (both decimal and hexadecimal).
     * Entities are recognized also if the ending semicolon is omitted at the end or before a
     * newline or tag but for consistency the semicolon is always added in the output where it was
     * omitted.
     * NOTE:
     * Where code should be rendered _as_code_ the original PHP function should be used so that
     * entity references are also rendered as such instead of as their corresponding characters.
     * @access  public
     * @since   wikka
     * @version 1.0
     * @todo    (later) support full range of situations where (in SGML) a terminating ; may legally
     *          be omitted (end, newline and tag are merely the most common ones).
     * @param   string  $text required: text to be converted
     * @param   integer $quote_style optional: quoting style - can be ENT_COMPAT (default, escape
     *          only double quotes), ENT_QUOTES (escape both double and single quotes) or
     *          ENT_NOQUOTES (don't escape any quotes)
     * @param   string  $charset optional: charset to use while converting; default UTF-8
     *          (overriding PHP's default ISO-8859-1)
     * @return  string  converted string with escaped special characted but entity references intact

    function htmlspecialchars_ent($text,$quote_style=ENT_COMPAT,$charset='UTF-8')
        // define patterns
        $alpha  = '[a-z]+';                         # character entity reference
        $numdec = '#[0-9]+';                        # numeric character reference (decimal)
        $numhex = '#x[0-9a-f]+';                    # numeric character reference (hexadecimal)
        $terminator = ';|(?=($|[\n<]|&lt;))';       # semicolon; or end-of-string, newline or tag
        $entitystring = $alpha.'|'.$numdec.'|'.$numhex;
        $escaped_entity = '&amp;('.$entitystring.')('.$terminator.')';

        // execute PHP built-in function, passing on optional parameters
        $output = htmlspecialchars($text,$quote_style,$charset);
        // "repair" escaped entities
        // modifiers: s = across lines, i = case-insensitive
        $output = preg_replace('/'.$escaped_entity.'/si',"&$1;",$output);
        // return output
        return $output;

I created a test harness for it (I tested with htmlspecialchars() in the Link() function in wikka.php replaced by htmlspecialchars_ent():

      1. [[HomePage word & notherword]] (to be escaped)
        => HomePage word & notherword
      1. [[JavaWoman Java&nbsp;Woman]] (alpha: no-breaking space)
        => JavaWoman Java Woman
      1. [[JavaWoman &Auml;hnlich]] (alpha with uppercase)
        => JavaWoman Ähnlich
      1. no terminating ; before tag &quot<span style="color:blue;">blue</span>&quot; (alpha: text, not link)
        => no terminating ; before tag "blue"
      1. [[CategoryDevelopment test no terminating ; before end &quot]] (alpha)
        => CategoryDevelopment test no terminating ; before end "
      1. [[FormattingRules <b>no ; before tag &#039</b>]] (numeric decimal)
        => FormattingRules <b>no ; before tag '</b>
      1. [[SandBox missing ; before &#x3f5
|<- newline]] (numeric hex)
=> <- newline
There are problems (now) with test cases 2, 3, 5, 6 and 7; with my proposed solution all testcases are converted correctly.

Note: The formatter does not recognize forced links with newline in description text (test case 7)! There is nothing wrong with having a newline inside a link description. => This requires small fix in wakka formatter (./formatters/wakka.php), as follows:
        // forced links
        // \S : any character that is not a whitespace character
        // \s : any whitespace character
        else if (preg_match("/^\[\[(\S*)(\s+(.+))?\]\]$/", $thing, $matches))

        // forced links
        // \S : any character that is not a whitespace character
        // \s : any whitespace character
        else if (preg_match("/^\[\[(\S*)(\s+(.+))?\]\]$/s", $thing, $matches))      # s modifier: recognize forced links across lines

Finally: the call in ./formatters/ini.php should be restored to:
$text = htmlspecialchars($text, ENT_QUOTES);

and in ./formatters/code.php we should also use
htmlspecialchars($text, ENT_QUOTES);
(i.e, add the ENT_QUOTES parameter).
All other calls to htmlspecialchars_unicode() (as well as the definition) should be replaced by htmlspecialchars_ent() above.

NOTE: As noted elsewhere: copy code fragments from the source of this page, not the rendering, to preserve layout (tabs)!

The show check is in there to prevent the applet code from displaying when not "viewing" a page. Specifically, there were problems with showing a "page history" before this was added. -- JsnX


=> Note: working with CVS (on SourceForge) - and access to it for developers - could prevent this sort of code mangling.




Well, I think I'd suggest adding it to the 3rd party plugin directory then. Although for you sorts that action doesn't seem necessary, for the community of kids that I work with, it's something that I anticipate will be the main way they make pages at first. By all means improve the action so that it cannot be blank (I raised this initially I think), and that so a regex checks for camelcasing, but I think it should be available somewhere & the 3rd party plugins directory would suit. -- GmBowen
How hard is it for them to learn to use a Wiki in a Wiki-way? There are already two ways to create a page - referring to one and then creating it from the missing link being the best (and easiest) and it will not leave any orphans (which should be discouraged anyway!); this is not that hard (no URLs, no code, just using the Wiki). Surely highschool kids can learn something - don't underestimate them. ;-) --JW
Oh, I don't underestimate them, they can learn the "normal" way of making a page. But the create page action is a good scaffold towards that....and scaffolding is important. Also, I'm working on a separate environment for grade 6/7/8...for those age groups it'll be even more useful. And, in my experience with people playing with this wiki (my undergrads), many people start with making orphaned pages, and then organize them so they're unorphaned and can find them more easily. (HOW do they make orphaned pages then? The newpage action actually encourages making orphaned pages, something that should be avoided. If they're not using a newpage action then obviously they don't need that to create orphans. :)) As for using the normal wiki-way to create pages, I'm a pretty competent computer nerd and I found (and find) the normal way of making wiki pages awkward. If I want to start a new page for some reason, having to open another page to write the name, save it, and then click on the link to go to the new page to edit it is "annoying" in that it takes so much work. (But it's the only way to ensure the page will not be orphaned to begin with. Wikis are about interlinking pages easily, orphans don't have a place in that.) Kids (and other users I would argue) will want to start a new page like they do in a word or two clicks only (and in my environment the URL bar is hidden, so they can't do it that way). (Where "will want" suggests assumption rather than research - if they can learn to use a word processor they certainly can learn to use a Wiki. A Wiki is not a word processor - why should it work the same? It would create an incorrect mental model. Creating links is about the easiest part of using a Wiki - and the most essential!) Wiki-think is that you make structure as you make content (that's essentially what you're describing). But many people don't work (or think) that way....disparate content first, then structure it....I know numerous academics that write that way in fact. (In fact, on this site I make a new page first, get it the way I want, and then go and add links.....I just use the URL bar to do it) The "make new page" action allows wikka to support both sorts of approaches, and that means more appealing to more people. (But Wikka should not encourage creating orphans - which is what the newpage action does - and if you really must Wikka already supports it: you can use the address bar to make a new URL. That's sufficient.) An old DOS program, Tornado notes, worked this way too. You added bunches of content that you could search on, but in use you then added keywords (like we do in wikka with categories) to provide organizational structure in searches. --GmBowen
To present it a different way, My understanding of why the alt tag is needed is because it is picked up by screen readers (literally, readers) to assist visually impaired people with "reading" the page...I suspect that's one of the reasons that it's in the standards in the first place. -- GmBowen


For the next minor release

RR on
			"root_page" => "HomePage",
"base_url" => "http://wokka/",
"rewrite_mode" => "1",

RR off
			"root_page" => "HomePage",
"base_url" => "http://test/wikka-",
"rewrite_mode" => "0",

Hope this helps -- DarTar

DarTar kind of gave you the key....
Forget about the wrong information that your ISP gave you and read ModRewrite. -- JsnX

For the next major release

- See my questions at HandlingWikkaConfig. NilsLindenberg

There are 8 comments on this page. [Show comments]
Valid XHTML :: Valid CSS: :: Powered by WikkaWiki