Add new preprocessor directive syntax¸ using a '!' prefix.

Add a prefix_directives option to the setup file to turn this syntax
on; currently defaults to false, for backward compatibility.  Support
optional '!' prefix even with prefix_directives off, and use that in
the underlay to support either setting of prefix_directives.  Add NEWS
entry with migration information.

5 files changed, 49 insertions, 35 deletions

diff --git a/doc/ikiwiki/blog.mdwn b/doc/ikiwiki/blog.mdwn
index 6e5eec4aa..8a9c50d0b 100644
--- a/doc/ikiwiki/blog.mdwn
+++ b/doc/ikiwiki/blog.mdwn
@@ -1,14 +1,14 @@
-[[if test="enabled(inline)"
+[[!if test="enabled(inline)"
      then="This wiki has the inline plugin **enabled**."
      else="This wiki has the inline plugin **disabled**."]]
 
-[[if test="enabled(inline)"
+[[!if test="enabled(inline)"
      then="You can"
      else="If this wiki had the inline plugin enabled, you could"]]
 turn any page on this wiki into a weblog by using the `inline`
 [[PreProcessorDirective]]. For example:
 
-	\[[inline pages="blog/* and !*/Discussion" show="10" rootpage="blog"]]
+	\[[!inline pages="blog/* and !*/Discussion" show="10" rootpage="blog"]]
 
 Any pages that match the specified [[PageSpec]] (in the example, any
 [[SubPage]] of "blog") will be part of the blog, and the newest 10
@@ -23,23 +23,23 @@ top of the blog that can be used to add new items.
 If you want your blog to have an archive page listing every post ever made
 to it, you can accomplish that like this:
 
-	\[[inline pages="blog/* and !*/Discussion" archive="yes"]]
+	\[[!inline pages="blog/* and !*/Discussion" archive="yes"]]
 
 You can even create an automatically generated list of all the pages on the
 wiki, with the most recently added at the top, like this:
 
-	\[[inline pages="* and !*/Discussion" archive="yes"]]
+	\[[!inline pages="* and !*/Discussion" archive="yes"]]
 
 If you want to be able to add pages to a given blog feed by tagging them,
 you can do that too. To tag a page, just make it link to a page or pages 
 that represent its tags. Then use the special `link()` [[PageSpec]] to match
 all pages that have a given tag:
 
-	\[[inline pages="link(life)"]]
+	\[[!inline pages="link(life)"]]
 
 Or include some tags and exclude others:
 
-	\[[inline pages="link(debian) and !link(social)"]]
+	\[[!inline pages="link(debian) and !link(social)"]]
 
 ## usage
 
diff --git a/doc/ikiwiki/formatting.mdwn b/doc/ikiwiki/formatting.mdwn
index 69e28913f..dc1fa77fd 100644
--- a/doc/ikiwiki/formatting.mdwn
+++ b/doc/ikiwiki/formatting.mdwn
@@ -1,4 +1,4 @@
-[[meta title="Formatting wiki pages"]]
+[[!meta title="Formatting wiki pages"]]
 
 Text on this wiki is, by default, written in a form very close to how you
 might write text for an email message. This style of text formatting is
@@ -59,36 +59,36 @@ you use the following additional features:
 * To link to another page on the wiki, place the page's name inside double
   square brackets. So you would use `\[[WikiLink]]` to link to [[WikiLink]].
 
-[[if test="enabled(smiley) and smileys" then="""
+[[!if test="enabled(smiley) and smileys" then="""
 * Insert [[smileys]] and some other useful symbols. :-)
 """]]
 
-[[if test="enabled(shortcut) and shortcuts" then="""
+[[!if test="enabled(shortcut) and shortcuts" then="""
 * Use [[shortcuts]] to link to common resources.
 
-	\[[wikipedia War\_of\_1812]]
+	\[[!wikipedia War\_of\_1812]]
 """]]
 
-[[if test="enabled(toc)" then="""
+[[!if test="enabled(toc)" then="""
 * Add a table of contents to a page:
 
-	\[[toc ]]
+	\[[!toc ]]
 """]]
 
 
-[[if test="enabled(meta)" then="""
+[[!if test="enabled(meta)" then="""
 * Change the title of a page:
 
-	\[[meta title="full page title"]]
+	\[[!meta title="full page title"]]
 """]]
 
-[[if test="enabled(inline) and blog" then="""
+[[!if test="enabled(inline) and blog" then="""
 * Create a [[blog]] by inlining a set of pages:
 
-	\[[inline pages="blog/*"]]
+	\[[!inline pages="blog/*"]]
 """]]
 
-[[if test="enabled(template) and templates" then="""
+[[!if test="enabled(template) and templates" then="""
 * Create and fill out [[templates]] for repeated chunks of
   parameterized wiki text.
 """]]
diff --git a/doc/ikiwiki/openid.mdwn b/doc/ikiwiki/openid.mdwn
index f02a0a62c..d0f93a8a9 100644
--- a/doc/ikiwiki/openid.mdwn
+++ b/doc/ikiwiki/openid.mdwn
@@ -1,6 +1,6 @@
-[[meta title="OpenID"]]
+[[!meta title="OpenID"]]
 
-[[if test="enabled(openid)"
+[[!if test="enabled(openid)"
      then="This wiki has OpenID **enabled**."
      else="This wiki has OpenID **disabled**."]]
 
@@ -17,7 +17,7 @@ To sign up for an OpenID, visit one of the following identity providers:
 * or any of the [many others out there](http://openiddirectory.com/index.php?dir=1)..
 
 Your OpenID is the URL that you are given when you sign up.
-[[if test="enabled(openid)" then="""
+[[!if test="enabled(openid)" then="""
 To sign in to this wiki using OpenID, just enter it in the OpenID field in the
 signin form. You do not need to give this wiki a password or go through any
 registration process when using OpenID.
@@ -28,5 +28,5 @@ registration process when using OpenID.
 It's also possible to make a page in the wiki usable as an OpenID url,
 by delegating it to an openid server. Here's an example of how to do that:
 
-	\[[meta openid="http://yourid.myopenid.com/"
+	\[[!meta openid="http://yourid.myopenid.com/"
 	       server="http://www.myopenid.com/server"]]
diff --git a/doc/ikiwiki/preprocessordirective.mdwn b/doc/ikiwiki/preprocessordirective.mdwn
index 1e2332c09..e8bf783a9 100644
--- a/doc/ikiwiki/preprocessordirective.mdwn
+++ b/doc/ikiwiki/preprocessordirective.mdwn
@@ -1,7 +1,7 @@
 Preprocessor directives are similar to a [[WikiLink]] in form, except they
-contain spaces and parameters. The general form is:
+begin with `!` and may contain parameters. The general form is:
 
-	\[[directive param="value" param="value"]]
+	\[[!directive param="value" param="value"]]
 
 This gets expanded before the rest of the page is processed, and can be used
 to transform the page in various ways.
@@ -9,25 +9,31 @@ to transform the page in various ways.
 The quotes around values can be omitted if the value is a simple word.
 Also, some directives may use parameters without values, for example:
 
-	\[[tag foo]]
-
-Note that if a preprocessor directive has no parameters, a space still must
-be put after its name, to avoid confusion with a [[WikiLink]]. For example:
-
-	\[[pagecount ]]
+	\[[!tag foo]]
 
 A preprocessor directive does not need to all be on one line, it can be
 wrapped to multiple lines if you like:
 	
-	\[[directive foo="baldersnatch"
+	\[[!directive foo="baldersnatch"
 	bar="supercalifragalisticexpealadocious" baz=11]]
 
 Also, multiple lines of *quoted* text can be used for a value.
 To allow quote marks inside the quoted text, delimit the block
 of text with triple-quotes:
 
-	\[[directive text="""
+	\[[!directive text="""
 	1. "foo"
 	2. "bar"
 	3. "baz"
 	"""]]
+
+ikiwiki also has an older syntax for preprocessor directives, which requires a
+space in directives to distinguish them from [[wikilinks|wikilink]].  This
+syntax has several disadvantages: it requires a space after directives with no
+parameters (such as `\[[!pagecount ]]`), and it prohibits spaces in
+[[wikilinks|wikilink]].  ikiwiki now provides the `!`-prefixed syntax shown
+above as the preferred alternative.  However, ikiwiki still supports wikis
+using the older syntax, if their setup files disable the `prefix_directives`
+option.  For backward compatibility with existing wikis, this option currently
+defaults to off, so ikiwiki uses the old directive syntax; however, future
+versions of ikiwiki will turn this on by default.
diff --git a/doc/ikiwiki/wikilink.mdwn b/doc/ikiwiki/wikilink.mdwn
index 38df00f86..debbe7305 100644
--- a/doc/ikiwiki/wikilink.mdwn
+++ b/doc/ikiwiki/wikilink.mdwn
@@ -22,6 +22,14 @@ page, but the link will appear like this: [[foo_bar|SandBox]].
 To link to an anchor inside a page, you can use something like
 `\[[WikiLink#foo]]`
 
-**Note that you cannot use spaces in WikiLinks**. Replace spaces with
-underscores. The presence of spaces is used to distinguish between a
-[[PreprocessorDirective]] and a WikiLink.
+## Preprocessor directives and wikilinks
+
+ikiwiki has two syntaxes for
+[[preprocessor_directives|PreprocessorDirective]].  The older syntax
+used spaces to distinguish between preprocessor directives and
+wikilinks; as a result, with that syntax in use, you cannot use spaces
+in WikiLinks, and must replace spaces with underscores.  The newer
+syntax, enabled with the `prefix_directives` option in an ikiwiki
+setup file, prefixes directives with `!`, and thus does not prevent
+links with spaces.  Future versions of ikiwiki will turn this option
+on by default.
\ No newline at end of file