]> git.vanrenterghem.biz Git - git.ikiwiki.info.git/blobdiff - doc/plugins/write/tutorial.mdwn
Merge branch 'tova' into autoconfig
[git.ikiwiki.info.git] / doc / plugins / write / tutorial.mdwn
index 2fc1c3e3f4c764ffe76ff3fe7b7ffb816c9d2141..5b810a18faea4f6460635fcd7e06f58bce56ac57 100644 (file)
@@ -1,22 +1,22 @@
 This tutorial will walk you through [[writing|write]] your first ikiwiki
 plugin.
 
-What should the plugin do? Let's make it calculate and output the Fibonachi
-sequense. To output the next number in the sequence, all a user has to do
+What should the plugin do? Let's make it calculate and output the Fibonacci
+sequence. To output the next number in the sequence, all a user has to do
 is write this on a wiki page:
 
-       \[[fib ]]
+       [[!fib ]]
 
-When the page is built, that'll be replaced by the next number in the
-sequence.
+When the page is built, the [[ikiwiki/PreProcessorDirective]] will be
+replaced by the next number in the sequence.
 
-Most of ikiwiki's plugins are written in perl, and it's currently easiest
-to write them in perl. So, open your favorite text editor, and start
+Most of ikiwiki's plugins are written in Perl, and it's currently easiest
+to write them in Perl. So, open your favorite text editor and start
 editing a file named "fib.pm".
 
        #!/usr/bin/perl
 
-This isn't really necessary, since fib.pm will be a perl module, but it's
+This isn't really necessary, since fib.pm will be a Perl module, but it's
 nice to have. Since it's a module, the next bit is this. Notice the "fib"
 at the end, matching the "fib" in the filename.
 
@@ -31,7 +31,7 @@ important one is the IkiWiki module.
 
 Ok, boilerplate is out of the way. Now to add the one function that ikiwiki
 expects to find in any module: `import`. The import function is called when
-the module is first loaded, and what modules typically do with it is
+the module is first loaded; what modules typically do with it is
 register hooks that ikiwiki will call later.
 
        sub import {
@@ -39,12 +39,12 @@ register hooks that ikiwiki will call later.
        }
 
 This has hooked our plugin into the preprocess hook, which ikiwiki uses to
-expand [[PreprocessorDirectives|preprocessordirectives]]. Notice that "fib"
-has shown up again. It doesn't actually have to match the module name this
-time, but it generally will. This "fib" is telling ikiwiki what kind of
-PreprocessorDirective to handle, namely one that looks like this:
+expand [[PreprocessorDirectives|ikiwiki/preprocessordirective]]. Notice
+that "fib" has shown up again. It doesn't actually have to match the module
+name this time, but it generally will. This "fib" is telling ikiwiki what
+kind of PreprocessorDirective to handle, namely one that looks like this:
 
-       \[[fib ]]
+       [[!fib ]]
 
 Notice the `\&preprocess`? This is how you pass a reference to a function,
 and the `preprocess` function is the one that ikiwiki will call to expand
@@ -56,19 +56,19 @@ the PreprocessorDirective. So, time to write that function:
        }
 
 Whatever this function returns is what will show up on the wiki page.
-Since this is the Fibonachi sequence, returning 1 will be right for the
+Since this is the Fibonacci sequence, returning 1 will be right for the
 first two calls anways, so our plugin isn't _too_ buggy. ;-) Before we fix
 the bug, let's finish up the plugin.
 
        1
 
-Always put this as the last line in your perl modules. Perl likes it.
+Always put this as the last line in your Perl modules. Perl likes it.
 
 Ok, done! If you save the plugin, you can copy it to a place your ikiwiki
 looks for plugins (`/usr/share/perl5/IkiWiki/Plugins/` is a good bet; see
 [[install]] for the details of how to figure out where to
 install it). Then configure ikiwiki to use the plugin, and you're ready to
-insert at least the first two numbers of the Fibonachi sequence on web
+insert at least the first two numbers of the Fibonacci sequence on web
 pages. Behold, the power of ikiwiki! ...
 
 ----
@@ -76,7 +76,7 @@ pages. Behold, the power of ikiwiki! ...
 You could stop here, if you like, and go write your own plugin that does
 something more useful. Rather than leave you with a broken fib plugin
 though, this tutorial will go ahead and complete it. Let's add a simple
-Fibonachi generating function to the plugin. This is right out of a
+Fibonacci generating function to the plugin. This is right out of a
 textbook.
 
        sub fib {
@@ -98,7 +98,7 @@ And let's change the `preprocess` sub to use it:
 
 Feel free to try it out with a simple page like this:
 
-       \[[fib ]], \[[fib ]], \[[fib ]], \[[fib ]], \[[fib ]]
+       [[!fib ]], [[!fib ]], [[!fib ]], [[!fib ]], [[!fib ]]
 
 Looks like it works ok, doesn't it? That creates a page that lists:
 
@@ -119,7 +119,7 @@ the sequence in some cases.
 Obviously, using a global `$last` veriable was a bad idea. It would
 work ok in a more regular cgi-based wiki, which only outputs one page per
 run. But since ikiwiki is a wiki *compiler*, things are a bit more
-complicated. It't not very hard to fix, though, if we do want the seqense
+complicated. It's not very hard to fix, though, if we do want the sequence
 to start from 1 in every page that uses it.
 
        my %last;
@@ -139,7 +139,7 @@ Ok, one more enhancement. Just incrementing the numbers is pretty boring.
 It would be nice to be able to jump directly to a given point in the
 sequence:
 
-       \[[fib seed=20]], [[fib ]], [[fib ]]
+       \[[!fib seed=20]], [[!fib ]], [[!fib ]]
 
 Just insert these lines of code inside `preprocess`, in the appropriate
 spot:
@@ -169,7 +169,7 @@ be a guard on how high it will go.
                }
                my $num=$last{$page}++;
                if ($num > 25) {
-                       return "[[fib will only calculate the first 25 numbers in the sequence]]";
+                       error "can only calculate the first 25 numbers in the sequence";
                }
                return fib($num);
        }
@@ -182,8 +182,8 @@ does for numbers less than 1. Or for any number that's not an integer. In
 either case, it will run forever. Here's one way to fix that:
 
                if (int($num) != $num || $num < 1) {
-                       return "[[fib positive integers only, please]]";
+                       error "positive integers only, please";
                }
 
 As these security problems have demonstrated, even a simple input from the
-user needs to be checked thuroughly before being used by an ikiwiki plugin.
+user needs to be checked thoroughly before being used by an ikiwiki plugin.