diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/plugins/aggregate.mdwn | 36 | ||||
| -rw-r--r-- | doc/roadmap.mdwn | 23 | ||||
| -rw-r--r-- | doc/tips/upgrade_to_3.0.mdwn | 72 |
3 files changed, 90 insertions, 41 deletions
diff --git a/doc/plugins/aggregate.mdwn b/doc/plugins/aggregate.mdwn index 6fc87853b..e2efcd83f 100644 --- a/doc/plugins/aggregate.mdwn +++ b/doc/plugins/aggregate.mdwn @@ -5,10 +5,6 @@ This plugin allows content from other feeds to be aggregated into the wiki. To specify feeds to aggregate, use the [[ikiwiki/directive/aggregate]] [[ikiwiki/directive]]. -New users of aggregate should enable the `aggregateinternal => 1` option in the -.setup file. If you don't do so, you will need to enable the [[html]] plugin -as well as aggregate itself, since feed entries will be stored as HTML. - The [[meta]] and [[tag]] plugins are also recommended. Either the [[htmltidy]] or [[htmlbalance]] plugin is suggested, since feeds can easily contain html problems, some of which these plugins can fix. @@ -27,37 +23,19 @@ visit is `http://whatever/ikiwiki.cgi?do=aggregate_webtrigger`. Anyone can visit the url to trigger an aggregation run, but it will only check each feed if its `updateinterval` has passed. -## internal pages and `aggregateinternal` +## aggregated pages This plugin creates a page for each aggregated item. If the `aggregateinternal` option is enabled in the setup file (which is -recommended), aggregated pages are stored in the source directory with a +the default), aggregated pages are stored in the source directory with a "._aggregated" extension. These pages cannot be edited by web users, and do not generate first-class wiki pages. They can still be inlined into a blog, but you have to use `internal` in [[PageSpecs|IkiWiki/PageSpec]], like `internal(blog/*)`. -For backward compatibility, the default is that these pages have the -".html" extension, and are first-class wiki pages -- each one generates -a separate HTML page in the output, and they can even be edited. - -That turns out to not be ideal for aggregated content, because publishing -files for each of those pages is a waste of disk space and CPU, and you -probably don't want to allow them to be edited. So, there is an alternative -method that can be used (and is recommended), turned on by the -`aggregateinternal` option in the setup file. - -If you are already using aggregate and want to enable `aggregateinternal`, -you should follow this process: - -1. Update all [[PageSpecs|ikiwiki/PageSpec]] that refer to the aggregated - pages -- such as those in inlines. Put "internal()" around globs - in those PageSpecs. For example, if the PageSpec was `foo/*`, it should - be changed to `internal(foo/*)`. This has to be done because internal - pages are not matched by regular globs. -2. Turn on `aggregateinternal` in the setup file. -3. Use [[ikiwiki-transition]] to rename all existing aggregated `.html` - files in the srcdir. The command to run is - `ikiwiki-transition aggregateinternal $setupfile`, -4. Refresh the wiki. (`ikiwiki -setup your.setup -refresh`) +If `aggregateinternal` is disabled, you will need to enable the [[html]] +plugin as well as aggregate itself, since feed entries will be stored as +HTML, and as first-class wiki pages -- each one generates +a separate HTML page in the output, and they can even be edited. This +option is provided only for backwards compatability. diff --git a/doc/roadmap.mdwn b/doc/roadmap.mdwn index 9ed5742eb..c85c6de5b 100644 --- a/doc/roadmap.mdwn +++ b/doc/roadmap.mdwn @@ -7,10 +7,7 @@ This is the roadmap for ikiwiki development. Released 29 April 2006. -The 1.x series changed a great deal over the more than 50 releases in its -lifetime. It is now in maintenance mode, only security issues or really bad -bugs will be fixed in 1.x going forward. 1.x will stop being supported with -the release of 3.0. +The 1.x series is no longer supported. ---- @@ -32,20 +29,18 @@ the release of 3.0. Released 30 April 2007. -The 2.x series is expected to undergo continuing development for some time, -adding improvements and new features, but avoiding changes that break -backwards compatability. +The 2.x series is now in maintenance mode. Only security fixes and fixes for +really bad bugs will be applied going forward. ---- # 3.0 -Version 3.0 will be an opportunity to make significant transitions. +Version 3.0 is an opportunity to make significant transitions, and also adds +many new features. -* Default to using `prefix_directives`. -* Default to using `aggregateinternal`. -* Remove deprecated prefs form settings for `allowed_attachments` and - `locked_pages`. +* See [[tips/upgrade_to_3.0]] for the steps you will need to follow + when upgrading to this version. * Finalise a new version of the plugin API, exporting additional commonly used functions from IkiWiki.pm. See [[todo/firm_up_plugin_interface]] @@ -54,6 +49,10 @@ improvements, far too many to list here. Release is planned for fall^Wlate, 2008. +The 3.x series is expected to undergo continuing development for some time, +adding improvements and new features, but avoiding changes that break +backwards compatability. + ---- # future goals diff --git a/doc/tips/upgrade_to_3.0.mdwn b/doc/tips/upgrade_to_3.0.mdwn new file mode 100644 index 000000000..6c74d4fc9 --- /dev/null +++ b/doc/tips/upgrade_to_3.0.mdwn @@ -0,0 +1,72 @@ +Version 3.0 of ikiwiki makes some significant configuration changes, which +you will need to deal with when upgrading from ikiwiki 2.x. + +[[!toc ]] + +# moving settings from Preferences page + +The admin preferences page used to have settings for allowed attachments, +locked pages, and banned users. These three settings have moved to the +setup file: + + allowed_attachments => "", + locked_pages => "", + banned_users => "", + +If you have not yet upgraded to ikiwiki 3.0, you can look at the admin +preferences page to see if any of these values is shown there, and copy +them into the setup file. + +## setup file format change + +The layout of the setup file changed in a significant way in version 2.60 +of ikiwiki. If you have not changed yours to the new format, now would be a +good time to do so. Some new features, like the [[plugins/websetup]] interface, +need the new format setup file. + +You can convert old setup files into the new format by running +`ikiwiki-transition setupformat your.setup` + +## prefix directives + +In 3.0, the syntax ikiwiki uses for [[directives|ikiwiki/directive]] has +changed, requiring that the directive start with a bang: + + \[[!directive ...]] + +If you would like to keep the old syntax, it is still supported, add the +following to your setup file: + + prefix_directives => 0, + +But it's not hard to convert your wiki to the new syntax. You can use +[[ikiwiki-transition]]. It will convert preprocessor directives in all +files given on the command line. To convert an entire wiki: + + find wikidir/ -type f -name '*.mdwn' -print0 | xargs -0 ikiwiki-transition prefix_directives + +Be sure to modify the find to list all pages in the wiki if you're using +other markup than markdown. You will probably want to commit the changes +when you're done too. + +## aggregateinternal + +If your wiki uses the [[aggregate|plugins/aggregate]] plugin, it will start +to aggregate feeds to special "internal" pages. + +If you don't want this change, you can add the following to your setup +file: + + aggregateinternal => 0, + +Otherwise, follow this procedure to upgrade a wiki using the aggregate plugin: + +1. Update all [[PageSpecs|ikiwiki/PageSpec]] that refer to the aggregated + pages -- such as those in inlines. Put "internal()" around globs + in those PageSpecs. For example, if the PageSpec was `foo/*`, it should + be changed to `internal(foo/*)`. This has to be done because internal + pages are not matched by regular globs. +2. Use [[ikiwiki-transition]] to rename all existing aggregated `.html` + files in the srcdir. The command to run is + `ikiwiki-transition aggregateinternal your.setup`, +3. Refresh the wiki. (`ikiwiki -setup your.setup -refresh`) |