X-Git-Url: http://git.vanrenterghem.biz/git.ikiwiki.info.git/blobdiff_plain/eede986a5964152bfbd1459e87b9f2e9f7fa9c96..3575f939d8c836ac7d2b28f334bab6747cec5ec4:/doc/ikiwiki/directive/comment.mdwn

diff --git a/doc/ikiwiki/directive/comment.mdwn b/doc/ikiwiki/directive/comment.mdwn
index f5c373890..590ad5c6b 100644
--- a/doc/ikiwiki/directive/comment.mdwn
+++ b/doc/ikiwiki/directive/comment.mdwn
@@ -1,11 +1,19 @@
 The `comment` directive is supplied by the
-[[!iki plugins/comments desc=comments]] plugin, and is used to add a comment
-to a page. Typically, the directive is the only thing on a comment page,
-and is filled out by the comment plugin when a user posts a comment.
+[[!iki plugins/comments desc=comments]] plugin. There should
+be one comment directive in each source file with extension
+`._comment` or `._comment_pending`, and the directive should not
+appear anywhere else. Comments are normally created via the web,
+in which case ikiwiki automatically creates a suitable
+`._comment` file.
+
+Wiki administrators can also commit comment files to the version
+control system directly: they should be named starting with
+the *comments\_pagename* config option (usually `comment_`)
+and ending with `._comment`, for instance `comment_42._comment`.
 
 Example:
 
-	[[!comment format=mdwn
+	\[[!comment format=mdwn
 	username="foo"
 	subject="Bar"
 	date="2009-06-02T19:05:01Z"
@@ -17,7 +25,8 @@ Example:
 ## usage
 
 The only required parameter is `content`, the others just add or override
-metadata of the comment.
+metadata for the comment. Many parameters are shortcuts for [[meta]]
+directives.
 
 * `content` - Text to display for the comment.
   Note that [[directives|ikiwiki/directive]]