X-Git-Url: http://git.vanrenterghem.biz/git.ikiwiki.info.git/blobdiff_plain/68aca6516a1c4b78991b5fc002c66efc5f012a0c..7998f73ded64d3101bcd9cdf9a388f23e694653a:/doc/tips/optimising_ikiwiki.mdwn

diff --git a/doc/tips/optimising_ikiwiki.mdwn b/doc/tips/optimising_ikiwiki.mdwn
index fcf3077f8..caed75ba6 100644
--- a/doc/tips/optimising_ikiwiki.mdwn
+++ b/doc/tips/optimising_ikiwiki.mdwn
@@ -1,8 +1,18 @@
-Is ikiwiki taking too long to build your wiki? Read on for some common
-problems that can be avoided to make ikiwiki run quick.
+Ikiwiki is a wiki compiler, which means that, unlike a traditional wiki,
+all the work needed to display your wiki is done up front. Where you can
+see it and get annoyed at it. In some ways, this is better than a wiki
+where a page view means running a program to generate the page on the fly.
+
+But enough excuses. If ikiwiki is taking too long to build your wiki,
+let's fix that. Read on for some common problems that can be avoided to
+make ikiwiki run quick.
 
 [[!toc]]
 
+(And if none of that helps, file a [[bug|bugs]]. One other great thing about
+ikiwiki being a wiki compiler is that it's easy to provide a test case when
+it's slow, and get the problem fixed!)
+
 ## rebuild vs refresh
 
 Are you building your wiki by running a command like this?
@@ -22,13 +32,21 @@ configured the hook in the usual way.) Most people who have run into this
 problem got in the habit of running `ikiwiki -setup my.setup` by hand
 when their wiki was small, and found it got slower as they added pages.
 
-### use the latest version
+## use the latest version
 
-If your version of ikiwiki is not [[!verison]], try upgrading. New
+If your version of ikiwiki is not [[!version]], try upgrading. New
 optimisations are frequently added to ikiwiki, some of them yielding
 *enormous* speed increases.
 
-### expensive inlines
+## run ikiwiki in verbose mode
+
+Try changing a page, and run ikiwiki with `-v` so it will tell you
+everything it does to deal with that changed page. Take note of
+which other pages are rebuilt, and which parts of the build take a long
+time. This can help you zero in on individual pages that contain some of
+the expensive things listed below. 
+
+## expensive inlines
 
 Do you have an archive page for your blog that shows all posts, 
 using an inline that looks like this?
@@ -54,7 +72,7 @@ smaller.
 	
 	\[[!inline pages="blog/* and link(tag)" show=0 archive=yes quick=yes]]
 
-Only downsides: This won't show titles set by the [[!ikiwiki/directive/meta]]
+Only downsides: This won't show titles set by the [[ikiwiki/directive/meta]]
 directive. And there's no RSS feed for users to use -- but if this page
 is only for the archives or tag for your blog, users should be subscribing
 to the blog's main page's RSS feed instead.
@@ -75,7 +93,7 @@ The resulting html file might get big and expensive to generate as you
 keep adding pages.
 
 First, consider removing the "show=title". Then the map will not show page
-titles set by the [[!ikiwiki/directive/meta]] directive -- but will also
+titles set by the [[ikiwiki/directive/meta]] directive -- but will also
 only need to be generated when pages are added or removed, not for every
 page change.
 
@@ -123,13 +141,28 @@ This site's own [[plugins/linkmap]] rarely slows it down, because it
 only shows the [[index]] page, and the small set of pages that link to it.
 That is accomplished as follows:
 
-	\[!linkmap pages="index or (backlink(index)"]]
+	\[[!linkmap pages="index or (backlink(index)"]]
 
 ## overhead of the search plugin
 
 Be aware that the [[plugins/search]] plugin has to update the search index
 whenever any page is changed. This can slow things down somewhat.
 
+## profiling
+
+If you have a repeatable change that ikiwiki takes a long time to build,
+and none of the above help, the next thing to consider is profiling
+ikiwiki. 
+
+The best way to do it is:
+
+* Install [[!cpan Devel::NYTProf]]
+* `PERL5OPT=-d:NYTProf`
+* `export PER5OPT`
+* Now run ikiwiki as usual, and it will generate a `nytprof.out` file.
+* Run `nytprofhtml` to generate html files.
+* Those can be examined to see what parts of ikiwiki are being slow.
+
 ## scaling to large numbers of pages
 
 Finally, let's think about how huge number of pages can affect ikiwiki.
@@ -143,7 +176,7 @@ Finally, let's think about how huge number of pages can affect ikiwiki.
   quickly, but still, lots more pages will make PageSpecs more expensive.
 
 * The backlinks calculation has to consider every link on every page
-  in the wiki. (In practice, most pages only like to at most a few dozen
+  in the wiki. (In practice, most pages only link to at most a few dozen
   other pages, so this is not a `O(N^2)`, but closer to `O(N)`.)
 
 * Ikiwiki also reads and writes an `index` file, which contains information