mention prefix_directives

[git.ikiwiki.info.git] / doc / ikiwiki / preprocessordirective.mdwn

diff --git a/doc/ikiwiki/preprocessordirective.mdwn b/doc/ikiwiki/preprocessordirective.mdwn
index 1e2332c091b48386c2f164b2de2c2bfc5f5106cc..e8bf783a9cba1e179fd922e80eb0d85b064cdb69 100644 (file)
--- 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
 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.
 
 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:
 
 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:
        
 
 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:
 
        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"
        """]]
        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.