no time to do maser for now, but some pointers and thanks

[git.ikiwiki.info.git] / doc / tips / upgrade_to_3.0.mdwn

diff --git a/doc/tips/upgrade_to_3.0.mdwn b/doc/tips/upgrade_to_3.0.mdwn
index 6c74d4fc9a76189fdee716095c46e91c67124b64..8ec2389353f9d57b66b1d6018db17ab509f63beb 100644 (file)
--- a/doc/tips/upgrade_to_3.0.mdwn
+++ b/doc/tips/upgrade_to_3.0.mdwn
@@ -1,32 +1,32 @@
-Version 3.0 of ikiwiki makes some significant configuration changes, which
+[[!meta date="2008-12-23 16:20:37 -0500"]]
+
+Version 3.0 of ikiwiki makes some significant changes, which

 you will need to deal with when upgrading from ikiwiki 2.x.
 
 [[!toc ]]
 
 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
 ## 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.
+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`
 
   
 You can convert old setup files into the new format by running
 `ikiwiki-transition setupformat your.setup`
 

+## 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, and will no longer appear on the admin preferences page once
+your wiki is upgraded to 3.0.
+
+You can move these preferences into the setup file by running
+`ikiwiki-transition moveprefs your.setup; ikiwiki --setup your.setup --refresh --wrappers`
+
+(Make sure you have converted the setup file to the new format first.)
+

 ## prefix directives
 
 In 3.0, the syntax ikiwiki uses for [[directives|ikiwiki/directive]] has
 ## prefix directives
 
 In 3.0, the syntax ikiwiki uses for [[directives|ikiwiki/directive]] has


@@ -39,20 +39,33 @@ following to your setup file:
        
        prefix_directives => 0,
 
        
        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:
+To convert to the new syntax, make sure that your setup file does *not*
+contain the above, then run `ikiwiki-transition prefix_directives your.setup`
+
+(And then commit the changes it makes to pages in your srcdir.)

 
 

-       find wikidir/ -type f -name '*.mdwn' -print0 | xargs -0 ikiwiki-transition prefix_directives
+## GlobLists

 
 

-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.
+In 3.0, the old "GlobList" syntax for [[PageSpecs|ikiwiki/PageSpec]] is no
+longer supported. A GlobList contains multiple terms, 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
 
 ## aggregateinternal
 
 If your wiki uses the [[aggregate|plugins/aggregate]] plugin, it will start

-to aggregate feeds to special "internal" pages. 
+to aggregate feeds to special "internal" pages.

 
 If you don't want this change, you can add the following to your setup
 file:
 
 If you don't want this change, you can add the following to your setup
 file:


@@ -69,4 +82,16 @@ Otherwise, follow this procedure to upgrade a wiki using the aggregate plugin:
 2. Use [[ikiwiki-transition]] to rename all existing aggregated `.html`
    files in the srcdir. The command to run is
    `ikiwiki-transition aggregateinternal your.setup`,
 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`)
+3. Refresh the wiki. (`ikiwiki --setup your.setup --refresh`)
+
+## embed / googlecalendar
+
+The googlecalendar plugin has been deprecated for a long time, and is
+removed in 3.0.
+
+The embed plugin is also now deprecated, though not yet removed.
+
+If you use either plugin to embed content from google, youtube, etc,
+into your wiki, you should instead configure the [[plugins/htmlscrubber]]
+to skip sanitising some pages, via the `htmlscrubber_skip` setting.
+See [[embedding_content]] for examples.