note about sort and dependency types

There's a gotcha where pagespec_match_list is used with a dependency type
that is not a full content dependency, and so ikiwiki does not know that
a content change to a page that sorted too low to match needs to trigger
a rebuild, since its sort order may have changed.

Inline is mostly ok re this, as it does use content dependencies. Except
for in the case of raw mode. But then, page metadata is documented to not
be loaded, so it doesn't make sense to use sortspecs that depend on
metadata. I hope. :)

diff --git a/doc/plugins/write.mdwn b/doc/plugins/write.mdwn
index 05ddf2215de9872bbc891d5d288b5a16df55ae6c..707622956988b4f1b93fff55ec6d82b903a2972c 100644 (file)
--- a/doc/plugins/write.mdwn
+++ b/doc/plugins/write.mdwn
@@ -734,7 +734,10 @@ Additional named parameters can be specified:
 * `filter` is a reference to a function, that is called and passed a page,
   and returns true if the page should be filtered out of the list.
 * `sort` specifies a sort order for the list. See
-  [[ikiwiki/PageSpec/sorting]] for the avilable sort methods.
+  [[ikiwiki/PageSpec/sorting]] for the avilable sort methods. Note that
+  if a sort method is specified that depends on the
+  page content (such as 'meta(foo)'), the deptype needs to be set to
+  a content dependency.
 * `reverse` if true, sorts in reverse.
 * `num` if nonzero, specifies the maximum number of matching pages that
   will be returned.