diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/ikiwiki/directive.mdwn | 16 | ||||
| -rw-r--r-- | doc/ikiwiki/pagespec.mdwn | 19 | ||||
| -rw-r--r-- | doc/plugins/aggregate.mdwn | 36 | ||||
| -rw-r--r-- | doc/plugins/contrib.mdwn | 2 | ||||
| -rw-r--r-- | doc/plugins/write.mdwn | 4 | ||||
| -rw-r--r-- | doc/plugins/write/tutorial.mdwn | 2 | ||||
| -rw-r--r-- | doc/roadmap.mdwn | 48 | ||||
| -rw-r--r-- | doc/tips/upgrade_to_3.0.mdwn | 90 | ||||
| -rw-r--r-- | doc/todo/firm_up_plugin_interface.mdwn | 2 |
9 files changed, 140 insertions, 79 deletions
diff --git a/doc/ikiwiki/directive.mdwn b/doc/ikiwiki/directive.mdwn index c4342dee8..fb88aa72d 100644 --- a/doc/ikiwiki/directive.mdwn +++ b/doc/ikiwiki/directive.mdwn @@ -28,15 +28,13 @@ of text with triple-quotes: 3. "baz" """]] -ikiwiki also has an older syntax for directives, which requires a -space in directives to distinguish them from [[wikilinks|ikiwiki/wikilink]]. -This syntax has several disadvantages: it requires a space after directives -with no parameters (such as `\[[pagecount ]]`), and it prohibits spaces in -[[wikilinks|ikiwiki/wikilink]]. ikiwiki now provides the `!`-prefixed syntax -shown above as the preferred alternative. However, ikiwiki still supports -wikis using the older syntax, if the `prefix_directives` option is not enabled. -For backward compatibility with existing wikis, this option currently -defaults to off, so ikiwiki supports the old syntax. +ikiwiki also has an older syntax for directives, which requires a space in +directives to distinguish them from [[wikilinks|ikiwiki/wikilink]]. This +syntax has several disadvantages: it requires a space after directives with +no parameters (such as `\[[pagecount ]]`), and it prohibits spaces in +[[wikilinks|ikiwiki/wikilink]]. ikiwiki now provides the `!`-prefixed +syntax shown above as default. However, ikiwiki still supports wikis using +the older syntax, if the `prefix_directives` option is disabled. [[!if test="enabled(listdirectives)" then=""" Here is a list of currently available directives in this wiki: diff --git a/doc/ikiwiki/pagespec.mdwn b/doc/ikiwiki/pagespec.mdwn index d4dd265cc..86abe5745 100644 --- a/doc/ikiwiki/pagespec.mdwn +++ b/doc/ikiwiki/pagespec.mdwn @@ -72,22 +72,3 @@ filenames of the pages in the wiki, so a pagespec "foo" used on page "a/b" will not match a page named "a/foo" or "a/b/foo". To match relative to the directory of the page containing the pagespec, you can use "./". For example, "./foo" on page "a/b" matches page "a/foo". - -## Old syntax - -The old PageSpec syntax was called a "GlobList", and worked differently in -two ways: - -1. "and" and "or" were not used; any page matching any item from the list - matched. -2. If an item was prefixed with "`!`", then no page matching that item - matched, even if it matched an earlier list item. - -For example, here is the old way to match all pages except for the SandBox -and Discussion pages: - - * !SandBox !*/Discussion - -Using this old syntax is still supported. However, the old syntax is -deprecated and will be removed at some point, and using the new syntax is -recommended. 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/plugins/contrib.mdwn b/doc/plugins/contrib.mdwn index 7a28edaba..e22b13f71 100644 --- a/doc/plugins/contrib.mdwn +++ b/doc/plugins/contrib.mdwn @@ -2,6 +2,6 @@ Contributed [[plugins]]: (See [[install]] for installation help.) -[[!inline pages="plugins/contrib/* !*/Discussion" +[[!inline pages="plugins/contrib/* and !*/Discussion" feedpages="created_after(plugins/contrib/navbar)" archive="yes" rootpage="plugins/contrib" postformtext="Add a new plugin named:" show=0]] diff --git a/doc/plugins/write.mdwn b/doc/plugins/write.mdwn index b6fa96f91..cb7571289 100644 --- a/doc/plugins/write.mdwn +++ b/doc/plugins/write.mdwn @@ -19,7 +19,7 @@ that can be fleshed out to make a useful plugin. `IkiWiki::Plugin::pagecount` is another simple example. All perl plugins should `use IkiWiki` to import the ikiwiki plugin interface. It's a good idea to include the version number of the plugin interface that your plugin -expects: `use IkiWiki 2.00`. +expects: `use IkiWiki 3.00`. An external plugin is an executable program. It can be written in any language. Its interface to ikiwiki is via XML RPC, which it reads from @@ -431,7 +431,7 @@ describes the plugin as a whole. For example: To import the ikiwiki plugin interface: - use IkiWiki '2.00'; + use IkiWiki '3.00'; This will import several variables and functions into your plugin's namespace. These variables and functions are the ones most plugins need, diff --git a/doc/plugins/write/tutorial.mdwn b/doc/plugins/write/tutorial.mdwn index e1b34b800..5345f71f2 100644 --- a/doc/plugins/write/tutorial.mdwn +++ b/doc/plugins/write/tutorial.mdwn @@ -27,7 +27,7 @@ important one is the IkiWiki module. use warnings; use strict; - use IkiWiki 2.00; + use IkiWiki 3.00; Ok, boilerplate is out of the way. Now to add the one function that ikiwiki expects to find in any module: `import`. The import function is called when diff --git a/doc/roadmap.mdwn b/doc/roadmap.mdwn index 9ed5742eb..c6061156b 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,28 +29,43 @@ 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. - -* Default to using `prefix_directives`. -* Default to using `aggregateinternal`. -* Remove deprecated prefs form settings for `allowed_attachments` and - `locked_pages`. -* Finalise a new version of the plugin API, exporting additional commonly - used functions from IkiWiki.pm. See [[todo/firm_up_plugin_interface]] - -It will include a vast number of new features, bugfixes, and other -improvements, far too many to list here. +Version 3.0 is an opportunity to make significant transitions. +Read [[tips/upgrade_to_3.0]] for the steps you will need to +follow when upgrading your wiki to this version. + +The highlights of the changes in version 3.0 include: + +* Blog-style [[plugins/comments]] as an alternative to Discussion pages. +* Support for uploading [[attachments|plugins/attachment]]. +* Can [[plugins/rename]] and [[plugins/remove]] pages and files via the web. +* [[Web_based_setup|plugins/websetup]]. +* Many new plugins including [[plugins/htmlbalance]], [[plugins/format]], + [[plugins/progress]], [[plugins/color]], [[plugins/autoindex]], + [[plugins/cutpaste]], [[plugins/hnb]], [[plugins/creole]], [[plugins/txt]], + [[plugins/amazon_s3]], [[plugins/pinger]], [[plugins/pingee]], + [[plugins/edittemplate]] +* Support for additional revision control systems: [[rcs/bzr]], + [[rcs/monotone]] +* Support for [[tips/trusted_git_push]]. +* The RecentChanges page is compiled statically, not generated the the CGI. +* A new version (3.00) of the plugin API, exporting additional + commonly used functions from IkiWiki.pm. + See [[todo/firm_up_plugin_interface]] +* Far too many bug fixes, features, and enhancements 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..cf33f4d1c --- /dev/null +++ b/doc/tips/upgrade_to_3.0.mdwn @@ -0,0 +1,90 @@ +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. + +## GlobLists + +In 3.0, the old "GlobList" syntax for [[PageSpecs|ikiwiki/PageSpec]] is no +longer supported. A GlobList contains multiple term, but does not separate +them with "and" or "or": + + sandbox !*/Discussion + +To convert this to a modern PageSpec, simply add "and" or "or" as +appropriate between terms: + + sandbox and !*/Discussion + +GlobLists have been deprecated for more than two years. If your wiki dates +to the ikiwiki 1.0 era, you should check it for any that might have lurked +unnoticed in it since back then. Ikiwiki version 2.72 will print warnings +about any GlobLists it sees. + +## 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`) diff --git a/doc/todo/firm_up_plugin_interface.mdwn b/doc/todo/firm_up_plugin_interface.mdwn index c2e190884..c7553f7dd 100644 --- a/doc/todo/firm_up_plugin_interface.mdwn +++ b/doc/todo/firm_up_plugin_interface.mdwn @@ -92,3 +92,5 @@ Probably needs to evolve more and be more widely used before being exported. * %IkiWiki::pagecase (aggregate) * %IkiWiki::backlinks (pagestats) + +[[done]] (until 4.0).. |