expand documentation

diff --git a/doc/plugins/contrib/transient.mdwn b/doc/plugins/contrib/transient.mdwn
index ff2fab610f1607c3916d69a4f9755c82bc016d80..6003196b0cac6aee99dc2fdef8fb77aedb5f25cb 100644 (file)
--- a/doc/plugins/contrib/transient.mdwn
+++ b/doc/plugins/contrib/transient.mdwn
@@ -1,9 +1,35 @@
+*For discussion and the branch please see [[todo/transient pages]]. If this
+plugin is merged, this page can be renamed to act as its documentation. --[[smcv]]*
+
 [[!template id=plugin name=transient author="[[Simon_McVittie|smcv]]"]]
-[[!template id=gitbranch branch=smcv/ready/transient author="[[Simon_McVittie|smcv]]"]]
 [[!tag type/special-purpose]]
 
-The `transient` plugin is an implementation of [[todo/transient pages]]
-in an underlay. It's mostly useful as something other plugins can depend on;
-[[plugins/contrib/album]] puts photo-album "viewer" pages there,
-and the versions of [[plugins/autoindex]] and [[plugins/tag]] on the
-same branch optionally put their auto-generated pages there.
+The `transient` plugin adds an underlay in `.ikiwiki/transient`, which is
+intended for pages that are automatically created and should not be committed
+to the [[RCS]]. It works in the same way as the [[basewiki]] and the underlays
+set up by the [[plugins/underlay]] plugin, so if a page in the transient
+underlay is edited via the web, the edited version is committed to the RCS
+as usual. Unlike other underlays, if a page in the transient underlay is
+superseded by an edited version in the RCS, the old transient version
+is deleted automatically.
+
+This plugin is mostly useful as something that other plugins can depend on:
+
+* [[plugins/contrib/album]] always writes photo-album "viewer" pages to the
+  transient underlay
+
+Likely future users of this plugin (the appropriate branches need to be
+merged first):
+
+* with a patch (which exists but hasn't yet been tested), [[plugins/aggregate]]
+    always writes aggregated posts into the transient underlay
+* with a patch, [[plugins/autoindex]] can be configured to auto-create missing
+    pages that have a [[ikiwiki/subpage]] or an [[plugins/attachment]], but not
+    commit them, in which case they go in the transient underlay
+* [[plugins/comments]] can be configured to not commit comments: if so, it
+    should probably put them in the transient underlay
+* with a patch, [[plugins/recentchanges]] always writes new changes into the
+    transient underlay
+* with a patch, [[plugins/tag]] can be configured to auto-create missing
+    tag pages but not commit them, in which case they go in the transient
+    underlay