Merge remote-tracking branch 'remotes/smcv/ready/openid'

[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 bd47e96e594a754221b66067fc711bf844566b85..05b6d6fbd03d72f181c6733ab1fa6bf15f27a433 100644 (file)
--- a/doc/tips/upgrade_to_3.0.mdwn
+++ b/doc/tips/upgrade_to_3.0.mdwn
@@ -1,32 +1,30 @@
-Version 3.0 of ikiwiki makes some significant configuration changes, which
+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 +37,15 @@ 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:
-
-       find wikidir/ -type f -name '*.mdwn' -print0 | xargs -0 ikiwiki-transition prefix_directives
+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`

 
 

-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.
+(And then commit the changes it makes to pages in your srcdir.)

 
 ## GlobLists
 
 In 3.0, the old "GlobList" syntax for [[PageSpecs|ikiwiki/PageSpec]] is no
 
 ## 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
+longer supported. A GlobList contains multiple terms, but does not separate

 them with "and" or "or":
 
        sandbox !*/Discussion
 them with "and" or "or":
 
        sandbox !*/Discussion


@@ -64,12 +57,13 @@ appropriate between terms:
 
 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
 
 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.
+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:


@@ -87,3 +81,15 @@ Otherwise, follow this procedure to upgrade a wiki using the aggregate plugin:
    files in the srcdir. The command to run is
    `ikiwiki-transition aggregateinternal your.setup`,
 3. Refresh the wiki. (`ikiwiki -setup your.setup -refresh`)
    files in the srcdir. The command to run is
    `ikiwiki-transition aggregateinternal your.setup`,
 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.