diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/bugs.mdwn | 7 | ||||
| -rw-r--r-- | doc/features.mdwn | 7 | ||||
| -rw-r--r-- | doc/ikiwiki.setup | 2 | ||||
| -rw-r--r-- | doc/plugins.mdwn | 27 | ||||
| -rw-r--r-- | doc/plugins/brokelinks.mdwn | 11 | ||||
| -rw-r--r-- | doc/plugins/inline.mdwn | 4 | ||||
| -rw-r--r-- | doc/plugins/pagecount.mdwn | 11 | ||||
| -rw-r--r-- | doc/plugins/write.mdwn | 74 | ||||
| -rw-r--r-- | doc/post-commit.mdwn | 2 | ||||
| -rw-r--r-- | doc/security.mdwn | 2 | ||||
| -rw-r--r-- | doc/todo.mdwn | 6 | ||||
| -rw-r--r-- | doc/todo/lists.mdwn | 5 | ||||
| -rw-r--r-- | doc/todo/plugin.mdwn | 19 | ||||
| -rw-r--r-- | doc/usage.mdwn | 28 |
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 |