clarify when to use utlto and when to use htmlpage

[ikiwiki.git] / doc / plugins / write.mdwn

diff --git a/doc/plugins/write.mdwn b/doc/plugins/write.mdwn
index e8ba0a6abe6826924b8e41aee71b3ceea50ae13e..1cdea6a774b87a7eee6ef1aa2e4a619c312cafb9 100644 (file)
--- a/doc/plugins/write.mdwn
+++ b/doc/plugins/write.mdwn
@@ -188,6 +188,10 @@ languages to ikiwiki.
 The function is passed named parameters: "page" and "content" and should
 return the htmlized content.
 
+If `hook` is passed an optional "keepextension" parameter, set to a true
+value, then this extension will not be stripped from the source filename when
+generating the page.
+
 ### pagetemplate
 
        hook(type => "pagetemplate", id => "foo", call => \&pagetemplate);
@@ -518,6 +522,9 @@ parameters are passed to `HTML::Template->new`.
 Passed a page name, returns the base name that will be used for a the html
 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.
+
 #### `add_depends($$)`
 
 Makes the specified page depend on the specified [[ikiwiki/PageSpec]].
@@ -719,8 +726,8 @@ Changes can be staged by calls to `rcs_add, `rcs_remove`, and
 Adds the passed file to the archive. The filename is relative to the root
 of the srcdir.
 
-Note that this should not check the new file in, it should only
-prepare for it to be checked in when rcs_commit (or `rcs_commit_staged`) is
+Note that this should not commit the new file, it should only
+prepare for it to be committed when rcs_commit (or `rcs_commit_staged`) is
 called. Note that the file may be in a new subdir that is not yet in
 to version control; the subdir can be added if so.
 
@@ -728,9 +735,9 @@ to version control; the subdir can be added if so.
 
 Remove a file. The filename is relative to the root of the srcdir.
 
-Note that this should not check the removal in, it should only prepare for it
-to be checked in when `rcs_commit` (or `rcs_commit_staged`) is called. Note
-that the new file may be in a new subdir that is not yet inversion
+Note that this should not commit the removal, it should only prepare for it
+to be committed when `rcs_commit` (or `rcs_commit_staged`) is called. Note
+that the new file may be in a new subdir that is not yet in version
 control; the subdir can be added if so.
 
 #### `rcs_rename($$)`
@@ -805,6 +812,6 @@ when imported, populate `$IkiWiki::Setup::raw_setup` with a reference
 to a hash containing all the config items. They should also implement a
 `gendump` function.
 
-By the way, to parse a ikiwiki setup file, a program just needs to
-do something like:
-`use IkiWiki::Setup; my %setup=IkiWiki::Setup::load($filename)`
+By the way, to parse a ikiwiki setup file and populate `%config`, a
+program just needs to do something like:
+`use IkiWiki::Setup; IkiWiki::Setup::load($filename)`