summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/bugs.mdwn7
-rw-r--r--doc/features.mdwn7
-rw-r--r--doc/ikiwiki.setup2
-rw-r--r--doc/plugins.mdwn27
-rw-r--r--doc/plugins/brokelinks.mdwn11
-rw-r--r--doc/plugins/inline.mdwn4
-rw-r--r--doc/plugins/pagecount.mdwn11
-rw-r--r--doc/plugins/write.mdwn74
-rw-r--r--doc/post-commit.mdwn2
-rw-r--r--doc/security.mdwn2
-rw-r--r--doc/todo.mdwn6
-rw-r--r--doc/todo/lists.mdwn5
-rw-r--r--doc/todo/plugin.mdwn19
-rw-r--r--doc/usage.mdwn28
14 files changed, 166 insertions, 39 deletions
diff --git a/doc/bugs.mdwn b/doc/bugs.mdwn
index 47799676a..c646242aa 100644
--- a/doc/bugs.mdwn
+++ b/doc/bugs.mdwn
@@ -2,10 +2,11 @@
adding/removing a page. For example, if Foo/Bar links to "Baz", which is
Foo/Baz, and Foo/Bar/Baz gets added, it will update the links in Foo/Bar
to point to it, but will forget to update the linkbacks in Foo/Baz.
- And if Foo/Bar/Baz is then removed, it forgets to update Foo/Bar to link
+
+* And if Foo/Bar/Baz is then removed, it forgets to update Foo/Bar to link
back to Foo/Baz.
- -- is this still true?
+ -- is this still true? (Yes (as of 1.0))
* If I try to do a web commit, to a svn+ssh repo, it fails with
"Host key verification failed."
@@ -31,4 +32,4 @@
line if --cgi is set, even if it's not yet running as a cgi
* if a page containing an rss feed happens to show up in an rss feed,
the preprocessor directives won't be expanded (good) but are left in
- raw rather than removed (bad)
+ raw rather than removed (bad).
diff --git a/doc/features.mdwn b/doc/features.mdwn
index a8b33a75f..f63122edf 100644
--- a/doc/features.mdwn
+++ b/doc/features.mdwn
@@ -61,7 +61,8 @@ Some of ikiwiki's features:
* [[BackLinks]]
- Automatically included on pages. Rather faster than eg [[MoinMoin]] and always there to help with navigation.
+ Automatically included on pages. Rather faster than eg MoinMoin and
+ always there to help with navigation.
* [[PageHistory]]
@@ -115,6 +116,10 @@ Some of ikiwiki's features:
ikiwiki can be configured to send you commit mails with diffs of changes
to selected pages.
+* [[Plugins]]
+
+ A plugin system allows extending ikiwiki in arbitrary ways.
+
----
It also has some [[TODO]] items and [[Bugs]].
diff --git a/doc/ikiwiki.setup b/doc/ikiwiki.setup
index 9775b3194..4a08e1919 100644
--- a/doc/ikiwiki.setup
+++ b/doc/ikiwiki.setup
@@ -52,4 +52,6 @@ use IkiWiki::Setup::Standard {
#hyperestraier => 1,
# Sanitize html?
sanitize => 1,
+ # To change the enabled plugins, edit this list
+ #plugins => [qw{pagecount inline brokenlinks}],
}
diff --git a/doc/plugins.mdwn b/doc/plugins.mdwn
new file mode 100644
index 000000000..e83250f02
--- /dev/null
+++ b/doc/plugins.mdwn
@@ -0,0 +1,27 @@
+Plugins can be used to add additional features to ikiwiki. It's possible to
+[[write]] your own plugins, or you can install and use plugins contributed by
+others.
+
+The ikiiki package includes some standard plugins that are installed and
+by default. These include [[inline]], [[pagecount]], and [[brokenlinks]].
+Of these, [[inline]] is enabled by default.
+
+## Third party plugins
+
+Plugins are perl modules and should be installed somewhere in the perl
+module search path. See the @INC list at the end of the output of `perl -V`
+for a list of the directories in that path. All plugins are in the
+IkiWiki::Plugin namespace, so they go in a IkiWiki/Plugin subdirectory
+inside the perl search path. For example, if your perl looks in
+`/usr/local/lib/site_perl` for modules, you can locally install ikiwiki
+plugins to `/usr/local/lib/site_perl/IkiWiki/Plugin`
+
+Once a plugin is installed, you need to configure ikiwiki to load it using
+the `--plugin` switch described in [[usage]], or the equivilant line in
+[[ikiwiki.setup]].
+
+## Plugin directory
+
+Add your contributed plugins using this form:
+
+[[inline pages="plugins/* !plugins/write !*/Discussion" archive="yes" rootpage="plugins/contrib" show="30"]]
diff --git a/doc/plugins/brokelinks.mdwn b/doc/plugins/brokelinks.mdwn
new file mode 100644
index 000000000..05efe2806
--- /dev/null
+++ b/doc/plugins/brokelinks.mdwn
@@ -0,0 +1,11 @@
+This plugin generates a list of broken links on pages in the wiki. This is
+a useful way to find pages that still need to be written, or links that
+are written wrong.
+
+The optional parameter "pages" can be a [[GlobList]] specifying the pages
+to search for broken links, default is search them all.
+
+This plugin is included in ikiwiki, but is not enabled by default.
+If it is turned on, here's a list of broken links on this wiki:
+
+[[brokenlinks ]]
diff --git a/doc/plugins/inline.mdwn b/doc/plugins/inline.mdwn
new file mode 100644
index 000000000..68f381790
--- /dev/null
+++ b/doc/plugins/inline.mdwn
@@ -0,0 +1,4 @@
+Allows including one wiki page inside another, generating blogs and RSS
+feeds. See [[blog]] for details.
+
+This plugin is enabled by default.
diff --git a/doc/plugins/pagecount.mdwn b/doc/plugins/pagecount.mdwn
new file mode 100644
index 000000000..678ac823c
--- /dev/null
+++ b/doc/plugins/pagecount.mdwn
@@ -0,0 +1,11 @@
+Provides a \\[[pagecount ]] [[PreProcessorDirective]] that is replaced with
+the total number of pages currently in the wiki.
+
+The optional parameter "pages" can be a [[GlobList]] specifying the pages
+to count, default is to count them all.
+
+This plugin is included in ikiwiki, but is not enabled by default.
+
+If it is turned on it can tell us that this wiki includes
+[[pagecount ]] pages, of which [[pagecount pages="*/Discussion"]] are
+discussion pages.
diff --git a/doc/plugins/write.mdwn b/doc/plugins/write.mdwn
new file mode 100644
index 000000000..e09ca3510
--- /dev/null
+++ b/doc/plugins/write.mdwn
@@ -0,0 +1,74 @@
+ikiwiki [[plugins]] are written in perl. Each plugin is a perl module, in
+the `IkiWiki::Plugin` namespace. The name of the plugin is typically in
+lowercase, such as `IkiWiki::Plugin::inline`. Ikiwiki includes a
+`IkiWiki::Plugin::skeleton` that can be fleshed out to make a useful
+plugin. `IkiWiki::Plugin::pagecount` is another simple example.
+
+## Note
+
+One thing to keep in mind when writing a plugin is that ikiwiki is a wiki
+*compiler*. So plugins influence pages when they are built, not when they
+are loaded. A plugin that inserts the current time into a page, for
+example, will insert the build time. Also, as a compiler, ikiwiki avoids
+rebuilding pages unless they have changed, so a plugin that prints some
+random or changing thing on a page will generate a static page that won't
+change until ikiwiki rebuilds the page for some other reason, like the page
+being edited.
+
+## Registering plugins
+
+Plugins should, when imported, call IkiWiki::register_plugin to hook into
+ikiwiki. The function takes four parameters:
+
+1. A method type. Use "preprocess" to register a [[PreProcessorDirective]]
+2. A command name. This is the bit that will appear inside brackets in a
+ page.
+3. A reference to a subroutine that is run when the plugin is used.
+
+## Writing a [[PreProcessorDirective]]
+
+For preprocessor commands, the subroutine is passed named parameters. A
+"page" parameter gives the name of the page that embedded the preprocessor
+command. All parameters included in the preprocessor command are included
+as named parameters as well. Whatever the subroutine returns goes onto the
+page in place of the command.
+
+## Error handing in plugins
+
+While a plugin can call ikiwiki's error routine for a fatal error, for
+errors that aren't intended to halt the entire wiki build, including bad
+parameters passed to a [[PreProcessorDirective]], etc, it's better to just
+return the error message as the output of the plugin.
+
+## Html issues
+
+Note that if [[HTMLSanitization]] is enabled, html in
+[[PreProcessorDirective]] output is sanitised, which may limit what your
+plugin can do. Also, the rest of the page content is not in html format at
+preprocessor time.
+
+## Wiki configuration
+
+A plugin can access the wiki's configuration via the `%IkiWiki::config` hash.
+The best way to understand the contents of the hash is to look at
+[[ikiwiki.setup]], which sets the hash content to configure the wiki.
+
+## Wiki data
+
+If your plugin needs to access data about other pages in the wiki. It can
+use the following hashes, using a page name as the key:
+
+* `%IkiWiki::links` lists the names of each page
+ that is linked to from that page in an array reference.
+* `%IkiWiki::pagemtime` contains the last modification time of each page
+* `%IkiWiki::pagectime` contains the creation time of each page`
+* `%IkiWiki::renderedfiles` contains the name of the file rendered by a
+ page
+* `%IkiWiki::pagesources` contains the name of the source file for a page.
+* `%IkiWiki::depends` contains a [[GlobList]] that is used to specify other
+ pages that a page depends on. If one of its dependencies is updated, the
+ page will also get rebuilt.
+
+ Many plugins will need to add dependencies to this hash; the best way to do
+ it is by using the IkiWiki::add_depends function, which takes as its
+ parameters the page name and a [[GlobList]] of dependencies to add.
diff --git a/doc/post-commit.mdwn b/doc/post-commit.mdwn
index 780687563..76c8dfeac 100644
--- a/doc/post-commit.mdwn
+++ b/doc/post-commit.mdwn
@@ -1,7 +1,7 @@
A post-commit hook is run every time you commit a change to your subversion repository. To make the wiki be updated each time a commit is made, it can be run from (or as) a post-commit hook.
The best way to run ikiwiki in a [[Subversion]] post-commit hook is using
-a [[wrapper]], which can be generated using `ikiwiki --wrapper`.
+a wrapper, which can be generated using `ikiwiki --wrapper`.
First, set up the subversion checkout that ikiwiki will update and compile
into your wiki at each subversion commit. Run ikiwiki a few times by hand
diff --git a/doc/security.mdwn b/doc/security.mdwn
index 766b8bee4..77552b1b2 100644
--- a/doc/security.mdwn
+++ b/doc/security.mdwn
@@ -62,7 +62,7 @@ this wiki, BTW.
## page locking can be bypassed via direct svn commits
-A [[lock]]ed page can only be edited on the web by an admin, but
+A locked page can only be edited on the web by an admin, but
anyone who is allowed to commit direct to svn can bypass this. This is by
design, although a subversion pre-commit hook could be used to prevent
editing of locked pages when using subversion, if you really need to.
diff --git a/doc/todo.mdwn b/doc/todo.mdwn
index 764872eea..4bf9eb4c0 100644
--- a/doc/todo.mdwn
+++ b/doc/todo.mdwn
@@ -7,9 +7,3 @@ Welcome to ikiwiki's todo list. Items are moved to [[todo/done]] when done.
# Full list of open items:
[[inline pages="todo/* !todo/done* !*/Discussion" archive="yes"]]
-
-----
-
-Test:
-
-[[inline pages="news/* !*/Discussion" rootpage="news" show="30"]]
diff --git a/doc/todo/lists.mdwn b/doc/todo/lists.mdwn
index 841e3a463..933012493 100644
--- a/doc/todo/lists.mdwn
+++ b/doc/todo/lists.mdwn
@@ -1,7 +1,8 @@
* list of all missing pages
- Could be a [[plugin]].
+ done
* list of registered users, with the names being links to any userpages.
- Could be implemented with a [[preprocessordirective]], which suggests that there needs to be some sort of plugin interface for new preprocessordirectives. Although, how to let the wiki know that the page needs an update whever a new user is added? \ No newline at end of file
+ Might be a plugin, but how to let the wiki know that the page
+ needs an update whever a new user is added?
diff --git a/doc/todo/plugin.mdwn b/doc/todo/plugin.mdwn
index 0a8a0942e..255f0ccf6 100644
--- a/doc/todo/plugin.mdwn
+++ b/doc/todo/plugin.mdwn
@@ -1,5 +1,3 @@
-For one type of plugin, see [[todo/PluggableRenderers]].
-
A plugin system should ideally support things like:
* [[todo/lists]] of pages, of mising pages / broken links, of registered users, etc
@@ -11,22 +9,15 @@ A plugin system should ideally support things like:
* would it be useful to reimplement the hyperestradier search integration as a plugin?
* Support [[RecentChanges]] as a regular page containing a plugin that updates each time there is a change, and statically builds the recent changes list. (Would this be too expensive/inflexible? There might be other ways to do it as a plugin, like making all links to RecentChanges link to the cgi and have the cgi render it on demand.)
* etc
+* For another type of plugin, see [[todo/PluggableRenderers]].
-Another, separate plugin system that already (mostly) exists in ikiwiki is the RCS backend, which allows writing modules to drive other RCS systems than subversion.
+Another, separate plugin system that already (mostly) exists in ikiwiki is
+the RCS backend, which allows writing modules to drive other RCS systems
+than subversion.
## preprocessor plugins
-Considering ikiwiki plugins, one idea I have is to make the [[PreProcessorDirective]]s be a plugin. A setting in the config file would enable various plusins, which are perl modules, that each provide one or more preprocessor directives.
-
-Since preprocessing happens before htmlization but after a page is loaded and linkified, it should be possible to use it to create something like a link map or lists, or a page index. Page inlining and rss generation is already done via preprocessor directives and seems a natureal as a plugin too.
-
-Note that things like a link map or a broken link list page would need to
-be updated whenever a set (or all) pages change; the %depends hash
-already allows for pages to register this, although there could be some
-strange behavior if mixing multiple directives some of which exclude pages
-that others might want to include.
-
-I need to look at the full range of things that other wikis use their plugin systems for, but preprocessor directives as plugins certianly seems useful, even if it's not a complete solution.
+done
## case study: Moin Moin plugins
diff --git a/doc/usage.mdwn b/doc/usage.mdwn
index 4936039b6..c4d1f5818 100644
--- a/doc/usage.mdwn
+++ b/doc/usage.mdwn
@@ -41,7 +41,7 @@ These options control the mode that ikiwiki is operating in.
* --wrapper [file]
- Generate a [[wrapper]] binary that is hardcoded to do action specified by
+ Generate a wrapper binary that is hardcoded to do action specified by
the other options, using the specified input files and `destination`
directory. The filename to use for the wrapper is optional.
@@ -70,13 +70,6 @@ These options configure the wiki.
The name of the wiki, default is "wiki".
-* --fixctime
-
- Pull last changed time for all pages out of the revision control system.
- This rarely used option provides a way to get the real creation times of
- items in weblogs, for example when building a wiki from a new subversion
- checkout. It is unoptimised and quite slow.
-
* --templatedir
Specify the directory that the page [[templates]] are stored in.
@@ -129,7 +122,7 @@ These options configure the wiki.
* --rss, --norss
If rss is set, ikiwiki will generate rss feeds for pages that inline
- a blog.
+ a [[blog]].
* --url http://url/
@@ -137,7 +130,8 @@ These options configure the wiki.
* --cgiurl http://url/ikiwiki.cgi
- Specifies the url to the ikiwiki [[CGI]] script [[wrapper]]. Required when building the wiki for links to the cgi script to be generated.
+ Specifies the url to the ikiwiki [[CGI]] script wrapper. Required when
+ building the wiki for links to the cgi script to be generated.
* --historyurl http://url/trunk/\[[file]]?root=wiki
@@ -172,6 +166,11 @@ These options configure the wiki.
Enable [[HtmlSanitization]] of wiki content. On by default, disable with
--no-sanitize.
+* --plugin name
+
+ Enables the use of the specified plugin in the wiki. See [[plugins]] for
+ details. Note that plugin names are case sensative.
+
* --hyperestraier
Enables use of the [[HyperEstraier]] search engine for full test page
@@ -179,7 +178,14 @@ These options configure the wiki.
* --verbose
- Be vebose about what it's doing.
+ Be vebose about what is being done.
+
+* --fixctime
+
+ Pull last changed time for all pages out of the revision control system.
+ This rarely used option provides a way to get the real creation times of
+ items in weblogs, for example when building a wiki from a new subversion
+ checkout. It is unoptimised and quite slow.
# AUTHOR