reorg and expand docs of some variables

1 files changed, 55 insertions, 44 deletions

diff --git a/doc/plugins/write.mdwn b/doc/plugins/write.mdwn
index fbaabb6a0..712dda8bf 100644
--- a/doc/plugins/write.mdwn
+++ b/doc/plugins/write.mdwn
@@ -31,7 +31,7 @@ they're the same as far as how they hook into ikiwiki. This document will
 explain how to write both sorts of plugins, albeit with an emphasis on perl
 plugins.
 
-## Considerations
+## Remember: Ikiwiki is a compiler
 
 One thing to keep in mind when writing a plugin is that ikiwiki is a wiki
 *compiler*. So plugins influence pages when they are built, not when they
@@ -40,7 +40,23 @@ example, will insert the build time. Also, as a compiler, ikiwiki avoids
 rebuilding pages unless they have changed, so a plugin that prints some
 random or changing thing on a page will generate a static page that won't
 change until ikiwiki rebuilds the page for some other reason, like the page
-being edited.
+being edited. The [[tutorial]] has some other examples of ways that ikiwiki
+being a compiler may trip up the unwary.
+
+## Plugin interface
+
+To import the ikiwiki plugin interface:
+
+	use IkiWiki '3.00';
+
+This will import several variables and functions into your plugin's
+namespace. These variables and functions are the ones most plugins need,
+and a special effort will be made to avoid changing them in incompatible
+ways, and to document any changes that have to be made in the future.
+
+Note that IkiWiki also provides other variables and functions that are not
+exported by default. No guarantee is made about these in the future, so if
+it's not exported, the wise choice is to not use it.
 
 ## Registering plugins
 
@@ -508,28 +524,17 @@ describes the plugin as a whole. For example:
 This hook is used to inject C code (which it returns) into the `main`
 function of the ikiwiki wrapper when it is being generated.
 
-## Plugin interface
-
-To import the ikiwiki plugin interface:
+### Exported variables
 
-	use IkiWiki '3.00';
+Several variables are exported to your plugin when you `use IkiWiki;`
 
-This will import several variables and functions into your plugin's
-namespace. These variables and functions are the ones most plugins need,
-and a special effort will be made to avoid changing them in incompatible
-ways, and to document any changes that have to be made in the future.
-
-Note that IkiWiki also provides other variables and functions that are not
-exported by default. No guarantee is made about these in the future, so if
-it's not exported, the wise choice is to not use it.
-
-### %config
+#### %config
 
 A plugin can access the wiki's configuration via the `%config`
 hash. The best way to understand the contents of the hash is to look at
 your ikiwiki setup file, which sets the hash content to configure the wiki.
 
-### %pagestate
+#### %pagestate
 
 The `%pagestate` hash can be used by plugins to save state that they will need
 next time ikiwiki is run. The hash holds per-page state, so to set a value,
@@ -547,7 +552,7 @@ When pages are deleted, ikiwiki automatically deletes their pagestate too.
 Note that page state does not persist across wiki rebuilds, only across
 wiki updates.
 
-### %wikistate
+#### %wikistate
 
 The `%wikistate` hash can be used by a plugin to store persistant state
 that is not bound to any one page. To set a value, use
@@ -556,19 +561,25 @@ serialize, `$key` is any string you like, and `$id` must be the same as the
 "id" parameter passed to `hook()` when registering the plugin, so that the
 state can be dropped if the plugin is no longer used.
 
-### Other variables
+#### %links
+
+The `%links` hash can be used to look up the names of each page that
+a page links to. The name of the page is the key; the value is an array
+reference. Do not modify this hash directly; call `add_link()`.
+
+#### %destsources
 
-If your plugin needs to access data about other pages in the wiki. It can
-use the following hashes, using a page name as the key:
+The `%destsources` hash records the name of the source file used to
+create each destination file. The key is the output filename (ie,
+"foo/index.html"), and the value is the source filename that it was built
+from (eg, "foo.mdwn"). Note that a single source file may create multiple
+destination files. Do not modify this hash directly; call `will_render()`.
 
-* `%links` lists the names of each page that a page links to, in an array
-  reference.
-* `%destsources` contains the name of the source file used to create each
-  destination file.
-* `%pagesources` contains the name of the source file for each page.
+#### %pagesources
 
-Also, the `%IkiWiki::version` variable contains the version number for the
-ikiwiki program.
+The `%pagesources` has can be used to look up the source filename
+of a page. So the key is the page name, and the value is the source
+filename. Do not modify this hash.
 
 ### Library functions
 
@@ -614,22 +625,6 @@ page created from it. (Ie, it appends ".html".)
 Use this when constructing the filename of a html file. Use `urlto` when
 generating a link to a page.
 
-### `deptype(@)`
-
-Use this function to generate ikiwiki's internal representation of a
-dependency type from one or more of these keywords:
-
-* `content` is the default. Any change to the content
-  of a page triggers the dependency.
-* `presence` is only triggered by a change to the presence
-  of a page.
-* `links` is only triggered by a change to the links of a page.
-  This includes when a link is added, removed, or changes what
-  it points to due to other changes. It does not include the
-  addition or removal of a duplicate link.
-
-If multiple types are specified, they are combined.
-
 #### `pagespec_match_list($$;@)`
 
 Passed a page name, and [[ikiwiki/PageSpec]], returns a list of pages
@@ -683,6 +678,22 @@ The most often used is "location", which specifies the location the
 PageSpec should match against. If not passed, relative PageSpecs will match
 relative to the top of the wiki.
 
+#### `deptype(@)`
+
+Use this function to generate ikiwiki's internal representation of a
+dependency type from one or more of these keywords:
+
+* `content` is the default. Any change to the content
+  of a page triggers the dependency.
+* `presence` is only triggered by a change to the presence
+  of a page.
+* `links` is only triggered by a change to the links of a page.
+  This includes when a link is added, removed, or changes what
+  it points to due to other changes. It does not include the
+  addition or removal of a duplicate link.
+
+If multiple types are specified, they are combined.
+
 #### `bestlink($$)`
 
 Given a page and the text of a link on the page, determine which