diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/ikiwiki-transition.mdwn | 29 | ||||
| -rw-r--r-- | doc/ikiwiki.mdwn | 4 | ||||
| -rw-r--r-- | doc/ikiwiki/blog.mdwn | 14 | ||||
| -rw-r--r-- | doc/ikiwiki/formatting.mdwn | 22 | ||||
| -rw-r--r-- | doc/ikiwiki/openid.mdwn | 8 | ||||
| -rw-r--r-- | doc/ikiwiki/preprocessordirective.mdwn | 26 | ||||
| -rw-r--r-- | doc/ikiwiki/wikilink.mdwn | 14 | ||||
| -rw-r--r-- | doc/roadmap.mdwn | 9 | ||||
| -rw-r--r-- | doc/shortcuts.mdwn | 94 | ||||
| -rw-r--r-- | doc/templates.mdwn | 12 | ||||
| -rw-r--r-- | doc/todo/New_preprocessor_directive_syntax.mdwn | 2 |
11 files changed, 144 insertions, 90 deletions
diff --git a/doc/ikiwiki-transition.mdwn b/doc/ikiwiki-transition.mdwn new file mode 100644 index 000000000..118050a6c --- /dev/null +++ b/doc/ikiwiki-transition.mdwn @@ -0,0 +1,29 @@ +# NAME + +ikiwiki-transition - transition ikiwiki pages to new syntaxes + +# SYNOPSIS + +ikiwiki-transition prefix_directives page.mdwn... + +# DESCRIPTION + +`ikiwiki-transition` aids in converting ikiwiki pages when +there's a major change in ikiwiki syntax. + +Currently only one such transition is handled, the `prefix_directives` mode +converts an ikiwiki page from the old preprocessor directive syntax, +requiring a space, to the new syntax, prefixed by '!'. + +Preprocessor directives which already use the new syntax will remain +unchanged. + +Note that if the page contains wiki links with spaces, which some +older versions of ikiwiki accepted, the prefix_directives transition will +treat these as preprocessor directives and convert them. + +# AUTHOR + +Josh Triplett <josh@freedesktop.org> + +Warning: this page is automatically made into ikiwiki-transition's man page, edit with care diff --git a/doc/ikiwiki.mdwn b/doc/ikiwiki.mdwn index c3773ed3a..9f8693ec4 100644 --- a/doc/ikiwiki.mdwn +++ b/doc/ikiwiki.mdwn @@ -1,6 +1,6 @@ This wiki is powered by [ikiwiki](http://ikiwiki.info/). -[[if test="enabled(version)" - then="(Currently running version [[version ]].)" +[[!if test="enabled(version)" + then="(Currently running version [[!version ]].)" ]] Some documentation on using ikiwiki: diff --git a/doc/ikiwiki/blog.mdwn b/doc/ikiwiki/blog.mdwn index 80a3d20b3..1a816dceb 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 diff --git a/doc/roadmap.mdwn b/doc/roadmap.mdwn index e869c6b15..af46e162b 100644 --- a/doc/roadmap.mdwn +++ b/doc/roadmap.mdwn @@ -37,6 +37,15 @@ backwards compatability. ---- +# 3.0 + +Still in the early planning stages, version 3.0 will be an opportunity to +make significant transitions. + +* Default to using prefix_directives. + +---- + # future goals * Improved [[todo/html]] stylesheets and templates. diff --git a/doc/shortcuts.mdwn b/doc/shortcuts.mdwn index 62e06614b..e4e740897 100644 --- a/doc/shortcuts.mdwn +++ b/doc/shortcuts.mdwn @@ -1,58 +1,58 @@ -[[if test="enabled(shortcut)" +[[!if test="enabled(shortcut)" then="This wiki has shortcuts **enabled**." else="This wiki has shortcuts **disabled**."]] Some examples of using shortcuts include: - \[[google foo]] - \[[wikipedia War_of_1812]] - \[[debbug 12345]] + \[[!google foo]] + \[[!wikipedia War_of_1812]] + \[[!debbug 12345]] This page controls what shortcut links the wiki supports. -* [[shortcut name=google url="http://www.google.com/search?q=%s"]] -* [[shortcut name=archive url="http://web.archive.org/*/%S"]] -* [[shortcut name=gmap url="http://maps.google.com/maps?q=%s"]] -* [[shortcut name=gmsg url="http://groups.google.com/groups?selm=%s"]] -* [[shortcut name=wikipedia url="http://en.wikipedia.org/wiki/%s"]] -* [[shortcut name=wikitravel url="http://wikitravel.org/en/%s"]] -* [[shortcut name=debbug url="http://bugs.debian.org/%s" desc="bug #%s"]] -* [[shortcut name=deblist url="http://lists.debian.org/debian-%s" desc="debian-%s@lists.debian.org"]] -* [[shortcut name=debpkg url="http://packages.debian.org/%s"]] -* [[shortcut name=debpts url="http://packages.qa.debian.org/%s"]] -* [[shortcut name=debmsg url="http://lists.debian.org/msgid-search/%s"]] -* [[shortcut name=debrt url="https://rt.debian.org/Ticket/Display.html?id=%s"]] -* [[shortcut name=debss url="http://snapshot.debian.net/package/%s"]] - * Usage: `\[[debss package]]`, `\[[debss package#version]]`, or `\[[debss package/version]]`. See http://snapshot.debian.net for details. -* [[shortcut name=fdobug url="https://bugs.freedesktop.org/show_bug.cgi?id=%s" desc="freedesktop.org bug #%s"]] -* [[shortcut name=fdolist url="http://lists.freedesktop.org/mailman/listinfo/%s" desc="%s@lists.freedesktop.org"]] -* [[shortcut name=gnomebug url="http://bugzilla.gnome.org/show_bug.cgi?id=%s" desc="GNOME bug #%s"]] -* [[shortcut name=linuxbug url="http://bugzilla.kernel.org/show_bug.cgi?id=%s" desc="Linux bug #%s"]] -* [[shortcut name=mozbug url="https://bugzilla.mozilla.org/show_bug.cgi?id=%s" desc="Mozilla bug #%s"]] -* [[shortcut name=gnulist url="http://lists.gnu.org/mailman/listinfo/%s" desc="%s@gnu.org"]] -* [[shortcut name=marcmsg url="http://marc.info/?i=%s"]] -* [[shortcut name=marclist url="http://marc.info/?l=%s"]] -* [[shortcut name=gmane url="http://dir.gmane.org/gmane.%s" desc="gmane.%s"]] -* [[shortcut name=gmanemsg url="http://mid.gmane.org/%s"]] -* [[shortcut name=cpan url="http://search.cpan.org/search?mode=dist&query=%s"]] -* [[shortcut name=ctan url="http://tug.ctan.org/cgi-bin/ctanPackageInformation.py?id=%s"]] -* [[shortcut name=hoogle url="http://haskell.org/hoogle/?q=%s"]] -* [[shortcut name=iki url="http://ikiwiki.info/%S/"]] -* [[shortcut name=ljuser url="http://%s.livejournal.com/"]] -* [[shortcut name=rfc url="http://www.ietf.org/rfc/rfc%s.txt" desc="RFC %s"]] -* [[shortcut name=c2 url="http://c2.com/cgi/wiki?%s"]] -* [[shortcut name=meatballwiki url="http://www.usemod.com/cgi-bin/mb.pl?%s"]] -* [[shortcut name=emacswiki url="http://www.emacswiki.org/cgi-bin/wiki/%s"]] -* [[shortcut name=haskellwiki url="http://haskell.org/haskellwiki/%s"]] -* [[shortcut name=dict url="http://www.dict.org/bin/Dict?Form=Dict1&Strategy=*&Database=*&Query=%s"]] -* [[shortcut name=imdb url="http://imdb.com/find?q=%s"]] -* [[shortcut name=gpg url="http://pgpkeys.mit.edu:11371/pks/lookup?op=vindex&exact=on&search=0x%s"]] -* [[shortcut name=perldoc url="http://perldoc.perl.org/search.html?q=%s"]] -* [[shortcut name=whois url="http://reports.internic.net/cgi/whois?whois_nic=%s&type=domain"]] -* [[shortcut name=cve url="http://cve.mitre.org/cgi-bin/cvename.cgi?name=%s"]] -* [[shortcut name=cia url="http://cia.vc/stats/project/%s"]] -* [[shortcut name=ciauser url="http://cia.vc/stats/user/%s"]] -* [[shortcut name=flickr url="http://www.flickr.com/photos/%s"]] +* [[!shortcut name=google url="http://www.google.com/search?q=%s"]] +* [[!shortcut name=archive url="http://web.archive.org/*/%S"]] +* [[!shortcut name=gmap url="http://maps.google.com/maps?q=%s"]] +* [[!shortcut name=gmsg url="http://groups.google.com/groups?selm=%s"]] +* [[!shortcut name=wikipedia url="http://en.wikipedia.org/wiki/%s"]] +* [[!shortcut name=wikitravel url="http://wikitravel.org/en/%s"]] +* [[!shortcut name=debbug url="http://bugs.debian.org/%s" desc="bug #%s"]] +* [[!shortcut name=deblist url="http://lists.debian.org/debian-%s" desc="debian-%s@lists.debian.org"]] +* [[!shortcut name=debpkg url="http://packages.debian.org/%s"]] +* [[!shortcut name=debpts url="http://packages.qa.debian.org/%s"]] +* [[!shortcut name=debmsg url="http://lists.debian.org/msgid-search/%s"]] +* [[!shortcut name=debrt url="https://rt.debian.org/Ticket/Display.html?id=%s"]] +* [[!shortcut name=debss url="http://snapshot.debian.net/package/%s"]] + * Usage: `\[[!debss package]]`, `\[[!debss package#version]]`, or `\[[!debss package/version]]`. See http://snapshot.debian.net for details. +* [[!shortcut name=fdobug url="https://bugs.freedesktop.org/show_bug.cgi?id=%s" desc="freedesktop.org bug #%s"]] +* [[!shortcut name=fdolist url="http://lists.freedesktop.org/mailman/listinfo/%s" desc="%s@lists.freedesktop.org"]] +* [[!shortcut name=gnomebug url="http://bugzilla.gnome.org/show_bug.cgi?id=%s" desc="GNOME bug #%s"]] +* [[!shortcut name=linuxbug url="http://bugzilla.kernel.org/show_bug.cgi?id=%s" desc="Linux bug #%s"]] +* [[!shortcut name=mozbug url="https://bugzilla.mozilla.org/show_bug.cgi?id=%s" desc="Mozilla bug #%s"]] +* [[!shortcut name=gnulist url="http://lists.gnu.org/mailman/listinfo/%s" desc="%s@gnu.org"]] +* [[!shortcut name=marcmsg url="http://marc.info/?i=%s"]] +* [[!shortcut name=marclist url="http://marc.info/?l=%s"]] +* [[!shortcut name=gmane url="http://dir.gmane.org/gmane.%s" desc="gmane.%s"]] +* [[!shortcut name=gmanemsg url="http://mid.gmane.org/%s"]] +* [[!shortcut name=cpan url="http://search.cpan.org/search?mode=dist&query=%s"]] +* [[!shortcut name=ctan url="http://tug.ctan.org/cgi-bin/ctanPackageInformation.py?id=%s"]] +* [[!shortcut name=hoogle url="http://haskell.org/hoogle/?q=%s"]] +* [[!shortcut name=iki url="http://ikiwiki.info/%S/"]] +* [[!shortcut name=ljuser url="http://%s.livejournal.com/"]] +* [[!shortcut name=rfc url="http://www.ietf.org/rfc/rfc%s.txt" desc="RFC %s"]] +* [[!shortcut name=c2 url="http://c2.com/cgi/wiki?%s"]] +* [[!shortcut name=meatballwiki url="http://www.usemod.com/cgi-bin/mb.pl?%s"]] +* [[!shortcut name=emacswiki url="http://www.emacswiki.org/cgi-bin/wiki/%s"]] +* [[!shortcut name=haskellwiki url="http://haskell.org/haskellwiki/%s"]] +* [[!shortcut name=dict url="http://www.dict.org/bin/Dict?Form=Dict1&Strategy=*&Database=*&Query=%s"]] +* [[!shortcut name=imdb url="http://imdb.com/find?q=%s"]] +* [[!shortcut name=gpg url="http://pgpkeys.mit.edu:11371/pks/lookup?op=vindex&exact=on&search=0x%s"]] +* [[!shortcut name=perldoc url="http://perldoc.perl.org/search.html?q=%s"]] +* [[!shortcut name=whois url="http://reports.internic.net/cgi/whois?whois_nic=%s&type=domain"]] +* [[!shortcut name=cve url="http://cve.mitre.org/cgi-bin/cvename.cgi?name=%s"]] +* [[!shortcut name=cia url="http://cia.vc/stats/project/%s"]] +* [[!shortcut name=ciauser url="http://cia.vc/stats/user/%s"]] +* [[!shortcut name=flickr url="http://www.flickr.com/photos/%s"]] To add a new shortcut, use the `shortcut` [[ikiwiki/PreprocessorDirective]]. In the url, "%s" is replaced with the diff --git a/doc/templates.mdwn b/doc/templates.mdwn index 9ed9b838d..24da881c7 100644 --- a/doc/templates.mdwn +++ b/doc/templates.mdwn @@ -1,4 +1,4 @@ -[[if test="enabled(template)" +[[!if test="enabled(template)" then="This wiki has templates **enabled**." else="This wiki has templates **disabled**." ]] @@ -6,14 +6,14 @@ else="This wiki has templates **disabled**." Templates are files that can be filled out and inserted into pages in the wiki. -[[if test="enabled(template) and enabled(inline)" then=""" +[[!if test="enabled(template) and enabled(inline)" then=""" ## Available templates These templates are available for inclusion onto other pages in this wiki: -[[inline pages="templates/* and !*/discussion" feeds=no archive=yes +[[!inline pages="templates/* and !*/discussion" feeds=no archive=yes sort=title template=titlepage]] """]] @@ -21,7 +21,7 @@ sort=title template=titlepage]] Using a template works like this: - \[[template id=note text="""Here is the text to insert into my note."""]] + \[[!template id=note text="""Here is the text to insert into my note."""]] This fills out the [[note]] template, filling in the `text` field with the specified value, and inserts the result into the page. @@ -31,7 +31,7 @@ page outside the template. Triple-quoting the value even allows quotes to be included in it. Combined with multi-line quoted values, this allows for large chunks of marked up text to be embedded into a template: - \[[template id=foo name="Sally" color="green" age=8 notes=""" + \[[!template id=foo name="Sally" color="green" age=8 notes=""" * \[[Charley]]'s sister. * "I want to be an astronaut when I grow up." * Really 8 and a half. @@ -43,7 +43,7 @@ To create a template, simply add a template directive to a page, and page will provide a link that can be used to create the template. The template is a regular wiki page, located in the `templates/` directory. -The template uses the syntax used by the [[cpan HTML::Template]] perl +The template uses the syntax used by the [[!cpan HTML::Template]] perl module, which allows for some fairly complex things to be done. Consult its documentation for the full syntax, but all you really need to know are a few things: diff --git a/doc/todo/New_preprocessor_directive_syntax.mdwn b/doc/todo/New_preprocessor_directive_syntax.mdwn index 0302c4e38..b37985994 100644 --- a/doc/todo/New_preprocessor_directive_syntax.mdwn +++ b/doc/todo/New_preprocessor_directive_syntax.mdwn @@ -17,3 +17,5 @@ Making this transition would fix two major warts: with no arguments, such as `\[[toc ]]` --[[JoshTriplett]] + +[[done]] in version 2.21, using the '!'-prefixed syntax. --[[JoshTriplett]]
\ No newline at end of file |