X-Git-Url: http://git.vanrenterghem.biz/git.ikiwiki.info.git/blobdiff_plain/ba480baa9ec9e2d5d04c6eb06fd3ab4dafd60794..12c5786df4e74c143f24398b8d0028000b61daba:/doc/plugins/write/external.mdwn

diff --git a/doc/plugins/write/external.mdwn b/doc/plugins/write/external.mdwn
index 2ee841e61..cbcd9bf19 100644
--- a/doc/plugins/write/external.mdwn
+++ b/doc/plugins/write/external.mdwn
@@ -1,8 +1,10 @@
 External plugins are standalone, executable programs, that can be written
 in any language. When ikiwiki starts up, it runs the program, and
-communicates with it using XML RPC. If you want to [[write]] an external
+communicates with it using [XML RPC][xmlrpc]. If you want to [[write]] an external
 plugin, read on..
 
+[xmlrpc]: http://www.xmlrpc.com/
+
 ikiwiki contains one sample external plugin, named `externaldemo`. This is
 written in perl, but is intended to be an example of how to write an
 external plugin in your favorite programming language. Wow us at how much
@@ -11,7 +13,7 @@ easier you can do the same thing in your favorite language. ;-)
 There's now a second external plugin, the [[rst]] plugin, written in
 python. It uses a `proxy.py`, a helper library for ikiwiki python plugins.
 
-[[toc ]]
+[[!toc ]]
 
 ## How external plugins use XML RPC
 
@@ -53,8 +55,8 @@ it, external plugins can use the `getstate` and `setstate` RPCs. To access
 stored state, call `getstate("page", "id", "key")`, and to store state,
 call `setstate("page", "id", "key", "value")`.
 
-To access ikiwiki's ARGV, call `getargv()`. To change its ARGV, call
-`setargv(value)`.
+To access ikiwiki's ARGV array, call `getargv()`. To change its ARGV, call
+`setargv(array)`.
 
 ## Notes on function parameters
 
@@ -79,6 +81,19 @@ Other languages might not find it so easy. If not, it might be a good idea
 to convert these named parameters into something more natural for the
 language as part of their XML RPC interface.
 
+## undef
+
+XML RPC has a limitation that it does not have a way to pass
+undef/NULL/None. There is an extension to the protocol that supports this,
+but it is not yet available in the [[!cpan XML::RPC]] library used by
+ikiwiki.
+
+Until the extension is available, ikiwiki allows undef to be communicated
+over XML RPC by passing a sentinal value, a hash with a single key "null"
+with a value of an empty string. External plugins that need to communicate
+null values to or from ikiwiki will have to translate between undef and
+the sentinal.
+
 ## Function injection
 
 Some parts of ikiwiki are extensible by adding functions. For example, the