Merge branch 'master' of ssh://git.ikiwiki.info

[git.ikiwiki.info.git] / doc / plugins / write / tutorial.mdwn

diff --git a/doc/plugins/write/tutorial.mdwn b/doc/plugins/write/tutorial.mdwn
index 977849cf2f0573560ca8adf0b5aaa54075b29a0c..1912c8a2f37041ee54d4187957d7a664c6909573 100644 (file)
--- a/doc/plugins/write/tutorial.mdwn
+++ b/doc/plugins/write/tutorial.mdwn
@@ -27,7 +27,7 @@ important one is the IkiWiki module.
 
        use warnings;
        use strict;
 
        use warnings;
        use strict;

-       use IkiWiki 2.00;
+       use IkiWiki 3.00;

 
 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
 
 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


@@ -81,8 +81,8 @@ textbook.
 
        sub fib {
                my $num=shift;
 
        sub fib {
                my $num=shift;

-               return 0 if $num == 1;
-               return 1 if $num == 2;
+               return 0 if $num == 0;
+               return 1 if $num == 1;

                return fib($num - 1) + fib($num - 2);
        }
 
                return fib($num - 1) + fib($num - 2);
        }
 


@@ -92,7 +92,7 @@ And let's change the `preprocess` sub to use it:
 
        sub preprocess {
                my %params=@_;
 
        sub preprocess {
                my %params=@_;

-               my $num=$last++;
+               my $num=++$last;

                return fib($num);
        }
 
                return fib($num);
        }
 


@@ -102,7 +102,7 @@ Feel free to try it out with a simple page like this:
 
 Looks like it works ok, doesn't it? That creates a page that lists:
 
 
 Looks like it works ok, doesn't it? That creates a page that lists:
 

-       1, 1, 3, 5, 8
+       1, 1, 2, 3, 5

 
 But what happens if there are two pages that both use fib? Try it out.
 If ikiwiki builds both pages in one pass, the sequence will continue
 
 But what happens if there are two pages that both use fib? Try it out.
 If ikiwiki builds both pages in one pass, the sequence will continue


@@ -116,7 +116,7 @@ a page that uses fib. Now the inlined page will have one set of numbers,
 and the standalone page another. The numbers might even skip over part of
 the sequence in some cases.
 
 and the standalone page another. The numbers might even skip over part of
 the sequence in some cases.
 

-Obviously, using a global `$last` veriable was a bad idea. It would
+Obviously, using a global `$last` variable 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's not very hard to fix, though, if we do want the sequence
 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's not very hard to fix, though, if we do want the sequence


@@ -127,7 +127,7 @@ to start from 1 in every page that uses it.
        sub preprocess {
                my %params=@_;
                my $page=$params{destpage};
        sub preprocess {
                my %params=@_;
                my $page=$params{destpage};

-               my $num=$last{$page}++;
+               my $num=++$last{$page};

                return fib($num);
        }
 
                return fib($num);
        }
 


@@ -145,7 +145,7 @@ Just insert these lines of code inside `preprocess`, in the appropriate
 spot:
 
                if (exists $params{seed}) {
 spot:
 
                if (exists $params{seed}) {

-                       $last{$page}=$params{seed}-1;
+                       $last{$page}=$params{seed};

                }
 
 But this highlights another issue with the plugin. The `fib()` function is
                }
 
 But this highlights another issue with the plugin. The `fib()` function is


@@ -158,7 +158,7 @@ Now, we could try to fix `fib()` to run in constant time for any number,
 but that's not the focus of this tutorial. Instead, let's concentrate on
 making the plugin use the existing function safely. A good first step would
 be a guard on how high it will go.
 but that's not the focus of this tutorial. Instead, let's concentrate on
 making the plugin use the existing function safely. A good first step would
 be a guard on how high it will go.

-       
+

        my %last;
 
        sub preprocess {
        my %last;
 
        sub preprocess {


@@ -167,7 +167,7 @@ be a guard on how high it will go.
                if (exists $params{seed}) {
                        $last{$page}=$params{seed}-1;
                }
                if (exists $params{seed}) {
                        $last{$page}=$params{seed}-1;
                }

-               my $num=$last{$page}++;
+               my $num=++$last{$page};

                if ($num > 25) {
                        error "can only calculate the first 25 numbers in the sequence";
                }
                if ($num > 25) {
                        error "can only calculate the first 25 numbers in the sequence";
                }


@@ -178,10 +178,10 @@ Returning an error message like this is standard for preprocessor plugins,
 so that the user can look at the built page and see what went wrong.
 
 Are we done? Nope, there's still a security hole. Consider what `fib()`
 so that the user can look at the built page and see what went wrong.
 
 Are we done? Nope, there's still a security hole. Consider what `fib()`

-does for numbers less than 1. Or for any number that's not an integer. In
+does for numbers less than 0. Or for any number that's not an integer. In

 either case, it will run forever. Here's one way to fix that:
 
 either case, it will run forever. Here's one way to fix that:
 

-               if (int($num) != $num || $num < 1) {
+               if (int($num) != $num || $num < 0) {

                        error "positive integers only, please";
                }
 
                        error "positive integers only, please";
                }